Skip to content

Latest commit

 

History

History
428 lines (316 loc) · 27.3 KB

README.adoc

File metadata and controls

428 lines (316 loc) · 27.3 KB
Raw
Table of Contents

Papyrus

A Starknet full node

Papyrus logo

Github workflow status #LICENSE PRs welcome codecov

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.

Supported Starknet versions

This Papyrus version supports the following starknet versions:

  • v0.13.0

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. Minimum supported version is 1.76.

  • 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 Sepolia testnet, you need to override the default values by using the file /config/presets/sepolia_testnet.json, as follows:

cargo run --release --package papyrus_node --bin papyrus_node -- --base_layer.node_url <ethereum_node_url> --config-file /config/presets/sepolia_testnet.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 Sepolia testnet, run the following command:

cargo run --release --package papyrus_node --bin papyrus_node -- --base_layer.node_url <ethereum_node_url> \
--chain_id SN_SEPOLIA \
--starknet_url https://alpha-sepolia.starknet.io/ \
--base_layer.starknet_contract_address 0xe2bb56ee936fd6433dc0f6e7e3b8365c906aa057

For more information, see the papyrus-config README.

Running Papyrus with Docker

Prerequisites

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_6

  • v0_7

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>", "params": "<params>"}'

For example, to send a request calling the starknet_getBlockTransactionCount method, on block number 100000, 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_7_0' --header 'Content-Type: application/json'\
 --data '{"jsonrpc":"2.0","id":0,"method":"starknet_getBlockTransactionCount", "params": [{"block_number": 100000}] }'

JSON RPC API endpoints

Endpoint V0.6 V0.7

starknet_addDeclareTransaction

image

image

starknet_addDeployAccountTransaction

image

image

starknet_addInvokeTransaction

image

image

starknet_blockHashAndNumber

image

image

starknet_blockNumber

image

image

starknet_call

image

image

starknet_chainId

image

image

starknet_estimateFee

image

image

starknet_estimateMessageFee

image

image

starknet_getBlockTransactionCount

image

image

starknet_getBlockWithTxHashes

image

image

starknet_getBlockWithTxs

image

image

starknet_getBlockWithReceipts

image

image

starknet_getClass

image

image

starknet_getClassAt

image

image

starknet_getClassHashAt

image

image

starknet_getEvents

image

image

starknet_getNonce

image

image

starknet_getStateUpdate

image

image

starknet_getStorageAt

image

image

starknet_getTransactionByBlockIdAndIndex

image

image

starknet_getTransactionByHash

image

image

starknet_getTransactionReceipt

image

image

starknet_getTransactionStatus

image

image

starknet_simulateTransactions

image

image

starknet_specVersion

image

image

starknet_syncing

image

image

starknet_traceBlockTransactions

image

image

starknet_traceTransaction

image

image

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 http://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.
peer_id

Gets the P2P peer ID of the node (if the network component is inactive returns an empty string).

Collecting metrics

Papyrus can collect the following types of metrics:

  • JSON-RPC metrics

  • synchronization metrics

  • process metrics

  • p2p network 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:

Getting help

Reach out to the maintainer at any of the following:

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.