Skip to content

Latest commit

 

History

History
344 lines (260 loc) · 13.9 KB

README.md

File metadata and controls

344 lines (260 loc) · 13.9 KB
Raw

Rosetta Ethereum

This repository contains a sample implementation of Rosetta API for the Ethereum blockchain.

Build Status

Build once. Integrate your blockchain everywhere.

ROSETTA-ETHEREUM IS CONSIDERED ALPHA SOFTWARE. USE AT YOUR OWN RISK.

This project is available open source under the terms of the [Apache 2.0 License](https://opensource.org/licenses/Apache-2.0).

Overview

The rosetta-ethereum repository provides an implementation sample of the Rosetta API for Ethereum in Golang. We created this repository for developers of Ethereum-like (a.k.a., account-based) blockchains, who may find it easier to fork this implementation sample than write one from scratch.

Rosetta is an open-source specification and set of tools that makes integrating with blockchains simpler, faster, and more reliable. The Rosetta API is specified in the OpenAPI 3.0 format.

You can craft requests and responses with auto-generated code using Swagger Codegen or OpenAPI Generator. These requests and responses must be human-readable (easy to debug and understand), and able to be used in servers and browsers.

Jump to:

How to Use This Repo

  1. Fork the repo.
  2. Start playing with the code.
  3. Deploy a node in Docker to begin testing.

System Requirements

RAM: 16 MB minimum

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

Network Settings

To increase the load rosetta-ethereum can handle, we recommend these actions:

  1. Tune your OS settings to allow for more connections. On a linux-based OS, run the following commands to do so (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 rosetta-ethereum with net.ipv4.tcp_tw_recycle and do not recommend enabling it.

  1. Modify your open file settings to 100000. You can do this on a linux-based OS with the command: ulimit -n 100000.

Memory-Mapped Files

rosetta-ethereum uses memory-mapped files to persist data in the indexer. As a result, you must run rosetta-ethereum on a 64-bit architecture (the virtual address space easily exceeds 100s of GBs).

If you receive a kernel OOM, you may need to increase the allocated size of swap space on your OS. There is a great tutorial for how to do this on Linux 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

Development

Helpful commands for development:

Install dependencies

make deps

Run Tests

make test

Lint the Source Code

make lint

Security Check

make salus

Build a Docker Image from the Local Context

make build-local

Generate a Coverage Report

make coverage-local

Docker Deployment

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.

Image Installation

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

Installing from GitHub

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

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

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

Installing from Source

After cloning this repository, run:

make build-local

Configuring the Environment Variables

Required Arguments

MODE Type: String Options: ONLINE, OFFLINE Default: None

MODE determines if Rosetta can make outbound connections.

NETWORK Type: String Options: MAINNET, ROPSTEN, RINKEBY, GOERLI or TESTNET Default: ROPSTEN, but only for backwards compatibility if you use TESTNET

NETWORK is the Ethereum network to launch or communicate with.

PORT Type: Integer Options: 8080, any compatible port number Default: None

PORT is the port to use for Rosetta.

Optional Arguments

GETH Type: String Options: A node URL Default: None

GETH points to a remote geth node instead of initializing one

SKIP_GETH_ADMIN Type: Boolean Options: TRUE, FALSE Default: FALSE

SKIP_GETH_ADMIN instructs Rosetta to not use the geth admin RPC calls. This is typically disabled by hosted blockchain node services.

Run Docker

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

Example Commands

You can run these commands from the command line. If you cloned the repository, you can use the make commands shown after the examples.

Mainnet:Online

Uncloned repo:

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

Cloned repo:

make run-mainnet-online

Mainnet:Online (Remote)

Uncloned repo:

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 rosetta-ethereum:latest

Cloned repo:

make run-mainnet-remote geth=<NODE URL>

Mainnet:Offline

Uncloned repo:

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

Cloned repo:

make run-mainnet-offline

Testnet:Online

Uncloned repo:

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

Cloned repo:

make run-testnet-online
// to send some funds into your testnet account you can use the following commands
geth attach http://127.0.0.1:8545
> eth.sendTransaction({from: eth.coinbase, to: "0x9C639954BC9956598Df734994378A36f73cfba0C", value: web3.toWei(50, "ether")})

Testnet:Online (Remote)

Uncloned repo:

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 rosetta-ethereum:latest

Cloned repo:

make run-testnet-remote geth=<NODE URL>

Testnet:Offline

Uncloned repo:

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

Cloned repo:

make run-testnet-offline

Test the Implementation with rosetta-cli

To validate rosetta-ethereum, 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.

Read the How to Test your Rosetta Implementation documentation for additional details.

Contributing

You may contribute to the rosetta-ethereum project in various ways:

Read our Contributing documentation for more information.

When you've finished an implementation for a blockchain, share your work in the ecosystem category of the community site. Platforms looking for implementations for certain blockchains will be monitoring this section of the website for high-quality implementations they can use for integration. Make sure that your implementation meets the expectations of any implementation.

You can also find community implementations for a variety of blockchains in the rosetta-ecosystem repository.

Documentation

You can find the Rosetta API documentation at rosetta-api.org.

Check out the Getting Started section to start diving into Rosetta.

Our documentation is divided into the following sections:

Related Projects

  • rosetta-geth-sdk — This SDK helps accelerate Rosetta API implementation on go-ethereum based chains.
  • rosetta-sdk-go — The rosetta-sdk-go SDK provides a collection of packages used for interaction with the Rosetta API specification.
  • rosetta-specifications — Much of the SDKs’ code is generated from this repository.
  • rosetta-cli — Use the rosetta-cli tool to test your Rosetta API implementation. The tool also provides the ability to look up block contents and account balances.

Other Implementation Samples

You can find community implementations for a variety of blockchains in the rosetta-ecosystem repository, and in the ecosystem category of our community site.

License

This project is available open source under the terms of the Apache 2.0 License.

© 2022 Coinbase