Table of Contents
Papyrus is still being built therefore breaking changes might happen often so use it at your own risks.:construction: :warning:
Papyrus is a StarkNet full node written in Rust.
Prerequisites
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 -- --base_layer.node_url <ethereum_node_url>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 -- --helpSee here for more information.
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 \
--base_layer.node_url <ethereum_node_url>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 runPapyrus) and add--user "$(id -u):$(id -g)"to the docker run command.- You must include the
devtag which keeps track of our development branch and contains the most up-to-date code. Once we have official releases we will add alatesttag for the latest release.- Currently, there is no automatic upgrade mechanism. Make sure to periodically pull the latest image and re-run the node.
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:devFor more information, see Docker's documentation.
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>andv<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.
| 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 |
|
|
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
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.
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.
Papyrus collects three metrics in the rpc:
rpc_incoming_requestscounterrpc_failed_requestscounterrpc_request_latency_secondshistogram
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.
We provide a helm chart for deploying the node to a kubernetes cluster. It is located under the deployments folder.
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
Reach out to the maintainer at one of the following places:
- GitHub Discussions
- Contact options listed on this GitHub profile
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!
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!
For a full list of all authors and contributors, see the contributors page.
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.
This project is licensed under the Apache 2.0 license.
See LICENSE for more information.