Table of Contents

• Papyrus
  • About
  • Disclaimer
  • Getting started
    • Building and running Papyrus locally
    • Local node configuration
    • Customizing your configuration
      • Configuration files (local node only)
      • Configuration via the command-line (local node and Docker image)
    • Running Papyrus with Docker
      • Upgrading the Docker container
      • Docker container memory usage
  • Sending API requests to the node
  • JSON RPC API endpoints
  • Papyrus monitoring API
    • Papyrus monitoring API endpoints
  • Collecting metrics
  • Viewing metrics
  • Deployment
  • Roadmap
  • Getting help
  • Help make Papyrus better!
  • Contributing
  • Authors and contributors
  • Security
  • License

Papyrus

A Starknet full node

Report a Bug · Request a Feature · Ask a Question

About

Papyrus is a Starknet full node implemented in Rust. Papyrus tracks Starknet’s state as it evolves over time, and enables you to query this state and to execute transactions via Starknet’s JSON-RPC.

Disclaimer

Papyrus is a work in progress.

Use it at your own risk.

Getting started

Building and running Papyrus locally

Prerequisites

• Rust must be installed.

• You must have access to an Ethereum node. For example, you can use a node provider such as Infura.

Procedure

1. Fork and clone the Github repo.

2. Build and run a Papyrus node with the default configuration by running the following commands:

   mkdir data
   cargo run --release --package papyrus_node --bin papyrus_node -- --base_layer.node_url <ethereum_node_url>

   Note	Papyrus uses the data directory for the node’s storage, as follows: ./data/<chain_id> You can configure the directory name using the storage.db_config.path_prefix configuration parameter.

3. See the version of Papyrus by running the following command:

   cargo run --release --package papyrus_node --bin papyrus_node -- --version

Local node configuration

The configuration is stored in one or more configuration files in .json format.

The default Papyrus configuration file, default_config.json, includes descriptions of all available parameters.

Customizing your configuration

You can override the default configuration in the following ways:

• Refer to one or more custom configuration files, using the same format as the default configuration file, default_config.json. For example, see any of the preset configuration files in this repository at /config/presets/. You can use configuration files when running a local node only, not a Docker image.

• Include configuration options in the command line when you run Papyrus.

• Set environment variables in the command line when you run Papyrus.

Configuration files (local node only)

The following rules apply:

• You do not need to specify the default configuration file.

• There is no limit on the number of custom configuration files you use.

• If the same configuration parameter appears in multiple configuration files, the last file in the list determines the value.

You can create separate configuration files to override specific configuration parameters.

To create a custom configuration file, create a .json file using the same format as the default configuration file.

To specify custom configuration files, include the --config_file command-line option when you run the full node locally, as follows:

cargo run --release --package papyrus_node --bin papyrus_node -- --base_layer.node_url <ethereum_node_url> --config-file <path_to_custom_configuration_file_1> <path_to_custom_configuration_file_n>

For example, preset .json files for several Starknet networks are located in this repository at /config/presets. To use Goerli testnet, you need to override the default values by using the file /config/presets/testnet1.json, as follows:

cargo run --release --package papyrus_node --bin papyrus_node -- --base_layer.node_url <ethereum_node_url> --config-file /config/presets/testnet1.json

Configuration via the command-line (local node and Docker image)

You can specify configuration parameters as command-line options. To see all available configuration parameters, enter the following command:

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

For example, to use Goerli testnet, run the following command:

cargo run --release --package papyrus_node --bin papyrus_node -- --base_layer.node_url <ethereum_node_url> \
--central.url https://alpha4.starknet.io/ \
--chain_id SN_GOERLI \
--rpc.starknet_url https://alpha4.starknet.io/ \
--base_layer.starknet_contract_address 0xde29d060D45901Fb19ED6C6e959EB22d8626708e

For more information, see the papyrus-config README.

Running Papyrus with Docker

Prerequisites

• Docker should be installed.

Procedure

1. Make a local directory to use for the container’s data. You only need to complete this step the first time you run Papyrus.

   mkdir <local-host-data-path>

2. Run a Papyrus node with the default configuration. You must explicitly give the container write access to the <local-host-data-path> directory by adding --user "$(id -u):$(id -g)" to the docker run command.

   Enter the following command:

   docker run --rm --name papyrus\
     -p 8080-8081:8080-8081 \
     -v /<local-host-data-path>:/app/data \
     ghcr.io/starkware-libs/papyrus:dev \
     --base_layer.node_url <ethereum_node_url> \
     --user "$(id -u):$(id -g)"

   Note	You must include the dev, tag which tracks the development branch and contains the most up-to-date code. When an official release is available, you can use the latest tag for the latest release.

Upgrading the Docker container

Currently, there is no automatic upgrade mechanism. Make sure to periodically pull the latest image and re-run the node.

Docker container memory usage

The Papyrus node uses all available RAM in order to cache the storage.

If no other applications are running on your machine, this is the recommended configuration.

Otherwise, you can limit the node’s memory usage by adding the --memory flag to run the node in a container with limited memory. Be aware that limiting the memory usage might make the node less efficient, as doing so decreases storage caching.

For example, to limit memory usage to 1GB, run the container with the following command:

docker run --rm --name papyrus\
  -p 8080-8081:8080-8081 \
  -v /<local-host-data-path>:/app/data \
  --memory 1g
  ghcr.io/starkware-libs/papyrus:dev \
  --base_layer.node_url <ethereum_node_url> \
  --user "$(id -u):$(id -g)"

For more information, see Limit a container’s access to memory in the Docker documentation.

Sending API requests to the node

When sending API requests, send them to the path /rpc/<starknet-rpc-version-id>.

Where <starknet-rpc-version-id> is one of the following strings:

• v0_3

• v0_4

See the API specification at the Starknet specifications repository on Github. You can send API requests using the following command:

curl --location '<node_path>/rpc/<starknet-rpc-version-id>' --header 'Content-Type: application/json'\
 --data '\{"jsonrpc":"2.0","id":0,"method":"<method>"}'

For example, to send a request calling the starknet_blockHashAndNumber method, using the 0.4.0 version of the API where <node_path> is localhost:8080, use the following command:

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

JSON RPC API 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 are available at the path monitoring.

You can send API requests using the following curl command:

curl -X GET https://<node_monitoring_gateway>/monitoring/<endpoint>

For example, when the node monitoring gateway is exposed at localhost:8081, send a request to view the liveliness endpoint using the following curl command:

curl -X GET https://localhost:8081/monitoring/alive

Papyrus monitoring API endpoints

alive	Liveliness endpoint. Returns status code 200 if the node is alive.
nodeVersion	Gets the node version.
nodeConfig	Gets the current node’s configuration.
dbTablesStats	Gets statistics for each table in the libmdbx database. For more information, see libmdbx::Stat in the libmdbx documentation.
metrics	Gets metrics of the node’s activity. For more information, see Collecting metrics.

Collecting metrics

Papyrus can collect the following types of metrics:

• JSON-RPC metrics

• synchronization metrics

• process metrics

By default, the node does not collect metrics and the metric path returns the following error code:

405 - Method Not Allowed.

To collect metrics, set the configuration value collect_metrics in the default configuration file to true.

Viewing metrics

Papyrus collects the following types of metrics:

• rpc_incoming_requests counter

• rpc_failed_requests counter

• rpc_request_latency_seconds histogram

• process Are these process metrics?

• papyrus Are these sync metrics?

You can see information for each metric by entering the following command:

<metric>\{method="<method_endpoint_suffix>", version="<ver>"}

Where:

<metric>	is the JSON-RPC metric.
<method_endpoint_suffix>	is the name of the JSON RPC API method endpoint, not including starknet_.
<ver>	is the JSON-RPC API version.

For example, to get all the incoming requests to the method starknet_chainId in JSON-RPC version 0.4, use method="chainId" in the following command:

curl -X GET https://localhost:8081/monitoring/metrics/rpc_incoming_requests\{method="chainId", version="V0_4"}

Tip	To get the number of requests with an illegal method name, such as those resulting from a typo, like starknet_chainIddd, use illegal_method for <method_endpoint_suffix>.

Deployment

See a helm chart for deploying the node to a Kubernetes cluster in the deployments folder.

Roadmap

See the open issues for proposed features and known issues:

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

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

• Newest Bugs

Getting help

Reach out to the maintainer at any of the following:

• GitHub Discussions

• Contact options listed on this GitHub profile

Help make Papyrus better!

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

• Add a GitHub Star to the project.

• Tweet about Papyrus.

• Write interesting articles about the project on Dev.to, Medium, or your personal blog.

Contributing

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 benefit everybody else and are greatly appreciated.

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

Authors and 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.

For more information, see LICENSE.