XDC.Network Rosetta API Implementation

Rosetta XDC.Network

ROSETTA XDC.Network IS CONSIDERED ALPHA SOFTWARE. USE AT YOUR OWN RISK! COINBASE ASSUMES NO RESPONSIBILITY OR LIABILITY IF THERE IS A BUG IN THIS IMPLEMENTATION.

Overview

xdc-rosetta provides a reference implementation of the Rosetta API for XDC.Network in Golang. If you haven't heard of the Rosetta API, you can find more information here.

Features

Comprehensive tracking of all ETH 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

System Requirements

xdc-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 xdc-rosetta will exit with an OOM error.

Recommended OS Settings

To increase the load xdc-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 xdc-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.

Usage

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.

Install

Running the following commands will create a Docker image called xdc-rosetta:latest.

From GitHub

To download the pre-built Docker image from the latest release, run:

curl -sSfL https://raw.githubusercontent.com/coinbase/xdc-rosetta/master/install.sh | sh -s

Do not try to install xdc-rosetta using GitHub Packages!

From Source

After cloning this repository, run:

make build-local

Run

Running the following commands will start a Docker container in detached mode with a data directory at <working directory>/XDC-data and the Rosetta API accessible at port 8080.

Configuration Environment Variables

MODE (required) - Determines if Rosetta can make outbound connections. Options: ONLINE or OFFLINE.
NETWORK (required) - XDC network to launch and/or communicate with. Options: MAINNET,TESTNET or DEVNET.
PORT(required) - Which port to use for Rosetta.
GETH (optional) - Point to a remote XDC node instead of initializing one
SKIP_GETH_ADMIN (optional, default: FALSE) - Instruct Rosetta to not use the geth admin RPC calls. This is typically disabled by hosted blockchain node services.

Mainnet:Online

docker run -d --rm --ulimit "nofile=100000:100000" -v "$(pwd)/XDC-data:/data" -e "MODE=ONLINE" -e "NETWORK=MAINNET" -e "PORT=8080" -p 8080:8080 -p 30303:30303 xdc-rosetta:latest

If you cloned the repository, you can run make run-mainnet-online.

Mainnet:Online (Remote)

docker run -d --rm --ulimit "nofile=100000:100000" -e "MODE=ONLINE" -e "NETWORK=MAINNET" -e "PORT=8080" -e "GETH=<NODE URL>" -p 8080:8080 -p 30303:30303 xdc-rosetta:latest

If you cloned the repository, you can run make run-mainnet-remote geth=<NODE URL>.

Mainnet:Offline

docker run -d --rm -e "MODE=OFFLINE" -e "NETWORK=MAINNET" -e "PORT=8081" -p 8081:8081 xdc-rosetta:latest

If you cloned the repository, you can run make run-mainnet-offline.

Testnet:Online

docker run -d --rm --ulimit "nofile=100000:100000" -v "$(pwd)/XDC-data:/data" -e "MODE=ONLINE" -e "NETWORK=TESTNET" -e "PORT=8080" -p 8080:8080 -p 30303:30303 xdc-rosetta:latest

If you cloned the repository, you can run make run-testnet-online.

Testnet:Online (Remote)

docker run -d --rm --ulimit "nofile=100000:100000" -e "MODE=ONLINE" -e "NETWORK=TESTNET" -e "PORT=8080" -e "GETH=<NODE URL>" -p 8080:8080 -p 30303:30303 xdc-rosetta:latest

If you cloned the repository, you can run make run-testnet-remote geth=<NODE URL>.

Testnet:Offline

docker run -d --rm -e "MODE=OFFLINE" -e "NETWORK=TESTNET" -e "PORT=8081" -p 8081:8081 xdc-rosetta:latest

If you cloned the repository, you can run make run-testnet-offline.

Testing with rosetta-cli

To validate xdc-rosetta, install rosetta-cli and run one of the following commands:

rosetta-cli check:data --configuration-file rosetta-cli-conf/testnet/config.json - This command validates that the Data API implementation is correct using the ethereum testnet node. It also ensures that the implementation does not miss any balance-changing operations.
rosetta-cli check:construction --configuration-file rosetta-cli-conf/testnet/config.json - This command validates the Construction API implementation. It also verifies transaction construction, signing, and submissions to the testnet network.
rosetta-cli check:data --configuration-file rosetta-cli-conf/mainnet/config.json - This command validates that the Data API implementation is correct using the ethereum mainnet node. It also ensures that the implementation does not miss any balance-changing operations.

Issues

Interested in helping fix issues in this repository? You can find to-dos in the Issues section. Be sure to reach out on our community before you tackle anything on this list.