Papyrus

Report a Bug · Request a Feature · Ask a Question

Table of Contents

• ⚠️ Disclaimer
• About
• Getting Started
  • Compiling and running papyrus
  • Configuration
• Running papyrus with Docker
• Endpoints
• Papyrus monitoring API
• Roadmap
• Support
• Project assistance
• Contributing
• Authors & contributors
• Security
• License

---

⚠️ Disclaimer

⚠️ 🚧 Papyrus is still being built therefore breaking changes might happen often so use it at your own risks.:construction: :warning:

About

Papyrus is a StarkNet full node written in Rust.

Getting started

Compiling and running Papyrus

Prerequisites

• Rust

You can build and run a Papyrus node with the default configuration by running:

mkdir data
cargo run --release --package papyrus_node --bin papyrus_node

Configuration

Papyrus default configuration file documents all the available parameters, including pointers to common values and #is_none flags for optional parameters.

You can override the default with configuration json files, by providing paths to the --config_file command-line argument. We provide preset json files for several Starknet networks here. Note that the configuration files can be partial. Alternatively, You can specify environment variables and command-line arguments. See the available command-line arguments by running:

cargo run --release --package papyrus_node --bin papyrus_node -- --help

See here for more information.

Running Papyrus with Docker

Prerequisites

• Docker

Command line

You can run a Papyrus node with the default configuration by running:

docker run --rm --name papyrus\
  -p 8080-8081:8080-8081 \
  -v <local-host-data-path>:/app/data \
  ghcr.io/starkware-libs/papyrus:dev

NOTE

• The container must have write access to <local-host-data-path>. A possible way to assure this is to create the <local-host-data-path> directory (only the first time you run Papyrus) and add --user "$(id -u):$(id -g)" to the docker run command.
• You must include the dev tag which keeps track of our development branch and contains the most up-to-date code. Once we have official releases we will add a latest tag for the latest release.
• Currently, there is no automatic upgrade mechanism. Make sure to periodically pull the latest image and re-run the node.

Memory usage

The Papyrus node will use all the RAM it can in order to cache the storage.

If you're not running any other applications on your machine, this is the recommended behavior.

Otherwise, you can limit the node's memory usage by running it in a container with a limited memory. Note that it might make the node less efficient as it will decrease the caching of the storage.

This can be done by adding the flag --memory 1g (For a 1GB limitation) to the command in the Docker section. The full command should be

docker run --rm --name papyrus\
  -p 8080-8081:8080-8081 \
  -v <local-host-data-path>:/app/data \
  --memory <memory-limit>
  ghcr.io/starkware-libs/papyrus:dev

For more information, see Docker's documentation.

Sending API requests to the node

API requests are sent to the path /rpc/<starknet-rpc-version-id>. Current supported versions are:

• V0_3_0
• V0_4_0

See specification at: starknet-specs repo
Assuming the node is exposed at localhost:8080 one might send requests via curl with:

curl --location 'localhost:8080/rpc/v0_3' --header 'Content-Type: application/json'\  
 --data '{"jsonrpc":"2.0","id":0,"method":"starknet_blockHashAndNumber"}'

NOTE
The default expected version id is in the format: v<Major>_<Minor>.
Also supported: V<Major>_<Minor> and v<Major>_<Minor>_<Patch> (or any combination of the above).
The Node always supports one patched version per minor version (the latest for that minor version).
When specifying a patch the semantic is grater or equal to the specified patch.

Endpoints

Endpoint	V0.3	V0.4
starknet_addDeclareTransaction
starknet_addDeployAccountTransaction
starknet_addInvokeTransaction
starknet_blockHashAndNumber
starknet_blockNumber
starknet_call
starknet_chainId
starknet_estimateFee
starknet_getBlockTransactionCount
starknet_getBlockWithTxHashes
starknet_getBlockWithTxs
starknet_getClass
starknet_getClassAt
starknet_getClassHashAt
starknet_getEvents
starknet_getNonce
starknet_getStateUpdate
starknet_getStorageAt
starknet_getTransactionByBlockIdAndIndex
starknet_getTransactionByHash
starknet_getTransactionReceipt
starknet_pendingTransactions
starknet_syncing

Papyrus monitoring API

Endpoints for retrieving monitoring information for the running node is available at monitoring path.

Assuming the node monitoring gateway is exposed at localhost:8081 one might send requests via curl with:
curl -X GET https://localhost:8081/monitoring/alive

Endpoints

• alive
    liveliness endpoint (Returns status code 200 if the node is alive).
• nodeVersion
    get node version.
• nodeConfig
    get the current node configuration.
• dbTablesStats
    get statistics for each table in the database (libmdbx), for more details see libmdbx::Stat.
• metrics
    get metrics of the node activity. See details below.

Metrics

Papyrus collects three kinds of metrics: rpc metrics, sync metrics, and process metrics. By default, the node will not collect metrics and the metric path will return an error code 405 - Method Not Allowed. To collect metrics, set the configuration value collect_metrics to true.

JSON-RPC metrics

Papyrus collects three metrics in the rpc:

• rpc_incoming_requests counter
• rpc_failed_requests counter
• rpc_request_latency_seconds histogram

Each metric can be filtered by method with the method label and by spec version with the version label. For example, to get all the incoming requests to method starknet_chainId in spec version 0.4, use the metric rpc_incoming_requests{method="chainId", version="V0_4"}.

In addition, the number of requests with illegal method name (for example typo of the user, starknet_chainIddd) can be retrieved using illegal_method value for the method label.

Deployment

We provide a helm chart for deploying the node to a kubernetes cluster. It is located under the deployments folder.

Roadmap

See the open issues for a list of proposed features (and known issues).

• Top Feature Requests (Add your votes using the 👍 reaction)
• Top Bugs (Add your votes using the 👍 reaction)
• Newest Bugs

Support

Reach out to the maintainer at one of the following places:

• GitHub Discussions
• Contact options listed on this GitHub profile

Project assistance

If you want to say thank you or/and support active development of Papyrus:

• Add a GitHub Star to the project.
• Tweet about the Papyrus.
• Write interesting articles about the project on Dev.to, Medium or your personal blog.

Together, we can make Papyrus better!

Contributing

First off, thanks for taking the time to contribute! Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make will benefit everybody else and are greatly appreciated.

Please read our contribution guidelines, and thank you for being involved!

Authors & contributors

For a full list of all authors and contributors, see the contributors page.

Security

Papyrus follows good practices of security, but 100% security cannot be assured. Papyrus is provided "as is" without any warranty. Use at your own risk.

For more information and to report security issues, please refer to our security documentation.

License

This project is licensed under the Apache 2.0 license.

See LICENSE for more information.