polygon-rosetta provides an implementation of the Rosetta API for
Polygon in Golang. If you haven't heard of the Rosetta API, you can find more
information here.
- Comprehensive tracking of all MATIC balance changes
- Stateless, offline, curve-based transaction construction (with address checksum validation)
- Atomic balance lookups using go-ethereum's GraphQL Endpoint
- Idempotent access to all transaction traces and receipts
As specified in the Rosetta API Principles,
all Rosetta implementations must be deployable via Docker and support running via either an
online or offline mode.
YOU MUST INSTALL DOCKER FOR THE FOLLOWING INSTRUCTIONS TO WORK. YOU CAN DOWNLOAD DOCKER HERE.
Running the following commands will create a Docker image called polygon-rosetta:latest.
To download the pre-built Docker image from the latest release, run:
curl -sSfL https://raw.githubusercontent.com/maticnetwork/polygon-rosetta/master/install.sh | sh -s
After cloning this repository, run the following to build the heimdall and bor node:
make build-node-local
run the following to build the rosetta implementation:
make build-rosetta-local
Alternatively, you can build a binary for faster testing cycles:
make build-rosetta-local-bin
Running the following commands will start a Docker container in
detached mode with
a data directory at <working directory>/polygon-data and the Rosetta API accessible
at port 8080.
MODE(required) - Determines if Rosetta can make outbound connections. Options:ONLINEorOFFLINE.NETWORK(required) - Polygon network to launch and/or communicate with. Options:MAINNETorTESTNET.PORT(required) - Which port to use for Rosetta.BOR(optional) - Point to a remotebornode instead of initializing oneSKIP_GETH_ADMIN(optional, default:FALSE) - Instruct Rosetta to not use thegethadminRPC calls. This is typically disabled by hosted blockchain node services.GETH_HEADERS(optional) - Pass a key:value comma-separated list to be passed to thegethclients. e.g.X-Auth-Token:12345-ABCDE,X-Other-Header:SomeOtherValue
NETWORK=MAINNET docker-compose -p polygon -f dockerfiles/docker-compose.yml up bor heimdall
If you cloned the repository, you can run make run-node-mainnet.
NETWORK=TESTNET docker-compose -p polygon -f dockerfiles/docker-compose.yml up bor heimdall
If you cloned the repository, you can run make run-node-testnet.
NETWORK=MAINNET docker-compose -p polygon -f dockerfiles/docker-compose.yml up rosetta
If you cloned the repository, you can run make run-mainnet-online.
NETWORK=MAINNET BOR=<NODE URL> docker-compose -p polygon -f dockerfiles/docker-compose.yml up rosetta
If you cloned the repository, you can run make run-mainnet-remote bor=<NODE_URL>.
NETWORK=MAINNET docker-compose -p polygon -f dockerfiles/docker-compose.yml up rosetta_offline
If you cloned the repository, you can run make run-mainnet-offline.
NETWORK=TESTNET docker-compose -p polygon -f dockerfiles/docker-compose.yml up rosetta
If you cloned the repository, you can run make run-testnet-online.
NETWORK=TESTNET BOR=<NODE URL> docker-compose -p polygon -f dockerfiles/docker-compose.yml up rosetta
If you cloned the repository, you can run make run-testnet-remote bor=<NODE_URL>.
NETWORK=TESTNET docker-compose -p polygon -f dockerfiles/docker-compose.yml up rosetta_offline
If you cloned the repository, you can run make run-testnet-offline.
You can also run the polygon-rosetta integration locally using a binary
make run-bin-testnet-offline
make run-bin-testnet-online bor=<NODE_URL>:8545
polygon-rosetta has been tested on an AWS c5.2xlarge instance.
This instance type has 8 vCPU and 16 GB of RAM. If you use a computer with less than 16 GB of RAM,
it is possible that polygon-rosetta will exit with an OOM error.
To increase the load polygon-rosetta can handle, it is recommended to tune your OS
settings to allow for more connections. On a linux-based OS, you can run the following
commands (source):
sysctl -w net.ipv4.tcp_tw_reuse=1
sysctl -w net.core.rmem_max=16777216
sysctl -w net.core.wmem_max=16777216
sysctl -w net.ipv4.tcp_max_syn_backlog=10000
sysctl -w net.core.somaxconn=10000
sysctl -p (when done)
We have not tested polygon-rosetta with net.ipv4.tcp_tw_recycle and do not recommend
enabling it.
You should also modify your open file settings to 100000. This can be done on a linux-based OS
with the command: ulimit -n 100000.
To validate polygon-rosetta, install rosetta-cli
and run one of the following commands:
rosetta-cli check:data --configuration-file rosetta-cli-conf/testnet/config.jsonrosetta-cli check:construction --configuration-file rosetta-cli-conf/testnet/config.jsonrosetta-cli check:data --configuration-file rosetta-cli-conf/mainnet/config.json
- Add ERC-20 Rosetta Module to enable reading ERC-20 token transfers and transaction construction
- Rosetta API
/mempool/*implementation - Add more methods to the
/callendpoint (currently only supporteth_getTransactionReceipt) - Add CI test using
rosetta-clito run on each PR (likely on a regtest network)
Please reach out on our community if you want to tackle anything on this list!
make depsto install dependenciesmake testto run testsmake lintto lint the source codemake salusto check for security concernsmake build-localto build a Docker image from the local contextmake coverage-localto generate a coverage report
Upon first glance, using a single Dockerfile to start all services required for a particular API (i.e. the node runtime and an indexer DB) may sound antithetical. However, we have found that restricting deployment to a single container makes the orchestration of multiple nodes much easier because of coordinated start/stop and single volume mounting.
Although Rosetta Spec has strongly recommended using a single dockerfile so that the service that manages the nodes can gracefully start and stop them, we have found out that due to the special dual-node setup with Polygon it makes more sense to have separate dockerfiles that bootstrap each services and uses docker-compose to bring up all the dependencies.
This project is available open source under the terms of the Apache 2.0 License.
© 2020 Coinbase