Skip to content

Commit

Permalink
update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
Liu Peng committed Sep 29, 2021
1 parent 41ae58a commit a7e10df
Show file tree
Hide file tree
Showing 5 changed files with 34 additions and 56 deletions.
2 changes: 1 addition & 1 deletion .dockerignore
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
ethereum-data
maro-data
cli-data
4 changes: 2 additions & 2 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
rosetta-ethereum
ethereum-data
rosetta-maro
maro-data
cli-data
8 changes: 4 additions & 4 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -49,22 +49,22 @@ update-bootstrap-balances:
# go run main.go utils:generate-bootstrap ethereum/genesis_files/testnet.json rosetta-cli-conf/testnet/bootstrap_balances.json;

run-mainnet-online:
docker run -d --rm --ulimit "nofile=${NOFILE}:${NOFILE}" -v "${PWD}/ethereum-data:/data" -e "MODE=ONLINE" -e "NETWORK=MAINNET" -e "PORT=8080" -p 8080:8080 -p 30303:30303 rosetta-maro:latest
docker run -d --rm --ulimit "nofile=${NOFILE}:${NOFILE}" -v "${PWD}/maro-data:/data" -e "MODE=ONLINE" -e "NETWORK=MAINNET" -e "PORT=8080" -p 8080:8080 -p 30303:30303 rosetta-maro:latest

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

run-testnet-online:
docker run -d --rm --ulimit "nofile=${NOFILE}:${NOFILE}" -v "${PWD}/ethereum-data:/data" -e "MODE=ONLINE" -e "NETWORK=TESTNET" -e "PORT=8080" -p 8080:8080 -p 30303:30303 rosetta-maro:latest
docker run -d --rm --ulimit "nofile=${NOFILE}:${NOFILE}" -v "${PWD}/maro-data:/data" -e "MODE=ONLINE" -e "NETWORK=TESTNET" -e "PORT=8080" -p 8080:8080 -p 30303:30303 rosetta-maro:latest

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

run-mainnet-remote:
docker run -d --rm --ulimit "nofile=${NOFILE}:${NOFILE}" -e "MODE=ONLINE" -e "NETWORK=MAINNET" -e "PORT=8080" -e "GETH=$(gttc)" -e "GRAPHQL=$(graphql)" -p 8080:8080 -p 30303:30303 rosetta-maro:latest
docker run -d --rm --ulimit "nofile=${NOFILE}:${NOFILE}" -e "MODE=ONLINE" -e "NETWORK=MAINNET" -e "PORT=8080" -e "GRPC=$(gttc)" -e "GRAPHQL=$(graphql)" -p 8080:8080 -p 30303:30303 rosetta-maro:latest

run-testnet-remote:
docker run -d --rm --ulimit "nofile=${NOFILE}:${NOFILE}" -e "MODE=ONLINE" -e "NETWORK=TESTNET" -e "PORT=8080" -e "GETH=$(gttc)" -e "GRAPHQL=$(graphql)" -p 8080:8080 -p 30303:30303 rosetta-maro:latest
docker run -d --rm --ulimit "nofile=${NOFILE}:${NOFILE}" -e "MODE=ONLINE" -e "NETWORK=TESTNET" -e "PORT=8080" -e "GRPC=$(gttc)" -e "GRAPHQL=$(graphql)" -p 8080:8080 -p 30303:30303 rosetta-maro:latest

check-comments:
${GOLINT_INSTALL}
Expand Down
74 changes: 26 additions & 48 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,30 +4,23 @@
</a>
</p>
<h3 align="center">
Rosetta Ethereum
Rosetta maro
</h3>
<p align="center">
<a href="https://circleci.com/gh/coinbase/rosetta-ethereum/tree/master"><img src="https://circleci.com/gh/coinbase/rosetta-ethereum/tree/master.svg?style=shield" /></a>
<a href="https://coveralls.io/github/coinbase/rosetta-ethereum"><img src="https://coveralls.io/repos/github/coinbase/rosetta-ethereum/badge.svg" /></a>
<a href="https://goreportcard.com/report/github.com/coinbase/rosetta-ethereum"><img src="https://goreportcard.com/badge/github.com/coinbase/rosetta-ethereum" /></a>
<a href="https://github.com/coinbase/rosetta-ethereum/blob/master/LICENSE.txt"><img src="https://img.shields.io/github/license/coinbase/rosetta-ethereum.svg" /></a>
<a href="https://pkg.go.dev/github.com/coinbase/rosetta-ethereum?tab=overview"><img src="https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white&style=shield" /></a>
</p>

<p align="center"><b>
ROSETTA-ETHEREUM IS CONSIDERED <a href="https://en.wikipedia.org/wiki/Software_release_life_cycle#Alpha">ALPHA SOFTWARE</a>.
USE AT YOUR OWN RISK! COINBASE ASSUMES NO RESPONSIBILITY NOR LIABILITY IF THERE IS A BUG IN THIS IMPLEMENTATION.
ROSETTA-MARO IS CONSIDERED <a href="https://en.wikipedia.org/wiki/Software_release_life_cycle#Alpha">ALPHA SOFTWARE</a>.
USE AT YOUR OWN RISK! MARO ASSUMES NO RESPONSIBILITY NOR LIABILITY IF THERE IS A BUG IN THIS IMPLEMENTATION.
</b></p>

## Overview
`rosetta-ethereum` provides a reference implementation of the Rosetta API for
Ethereum in Golang. If you haven't heard of the Rosetta API, you can find more
`rosetta-maro` provides a reference implementation of the Rosetta API for
maro in Golang. If you haven't heard of the Rosetta API, you can find more
information [here](https://rosetta-api.org).

## Features
* Comprehensive tracking of all ETH balance changes
* Comprehensive tracking of all maro balance changes
* Stateless, offline, curve-based transaction construction (with address checksum validation)
* Atomic balance lookups using go-ethereum's GraphQL Endpoint
* Atomic balance lookups using gttc's GraphQL Endpoint (gttc is maro in golang)
* Idempotent access to all transaction traces and receipts

## Usage
Expand All @@ -39,12 +32,12 @@ all Rosetta implementations must be deployable via Docker and support running vi
DOCKER [HERE](https://www.docker.com/get-started).**

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

#### From GitHub
To download the pre-built Docker image from the latest release, run:
```text
curl -sSfL https://raw.githubusercontent.com/coinbase/rosetta-ethereum/master/install.sh | sh -s
curl -sSfL https://raw.githubusercontent.com/TTCECO/rosetta-maro/master/install.sh | sh -s
```

#### From Source
Expand All @@ -56,60 +49,59 @@ make build-local
### Run
Running the following commands will start a Docker container in
[detached mode](https://docs.docker.com/engine/reference/run/#detached--d) with
a data directory at `<working directory>/ethereum-data` and the Rosetta API accessible
a data directory at `<working directory>/maro-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) - Ethereum network to launch and/or communicate with. Options: `MAINNET`, `ROPSTEN`, `RINKEBY`, `GOERLI` or `TESTNET` (which defaults to `ROPSTEN` for backwards compatibility).
* `NETWORK` (required) - Ethereum network to launch and/or communicate with. Options: `MAINNET` or `TESTNET` (which defaults to `MAINNET` for backwards compatibility).
* `PORT`(required) - Which port to use for Rosetta.
* `GETH` (optional) - Point to a remote `geth` 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.
* `GETH_HEADERS` (optional) - Pass a key:value comma-separated list to be passed to the `geth` clients. e.g. `X-Auth-Token:12345-ABCDE,X-Other-Header:SomeOtherValue`
* `GRPC` (optional) - Point to a remote `gttc` node's RPC address(default port 8545) instead of initializing one
* `GRAPHQL` (optional) - Point to a remote `gttc` node's GraphQL address (default port 8547) instead of initializing one

#### Mainnet:Online
```text
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
docker run -d --rm --ulimit "nofile=100000:100000" -v "$(pwd)/maro-data:/data" -e "MODE=ONLINE" -e "NETWORK=MAINNET" -e "PORT=8080" -p 8080:8080 -p 30303:30303 rosetta-maro:latest
```
_If you cloned the repository, you can run `make run-mainnet-online`._

#### Mainnet:Online (Remote)
```text
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
docker run -d --rm --ulimit "nofile=100000:100000" -e "MODE=ONLINE" -e "NETWORK=MAINNET" -e "PORT=8080" -e "GRPC=<NODE RPC URL>" -e "GRAPHQL=<NODE GRAPHQL URL>" -p 8080:8080 -p 30303:30303 rosetta-maro:latest
```
_If you cloned the repository, you can run `make run-mainnet-remote geth=<NODE URL>`._
_If you cloned the repository, you can run `make run-mainnet-remote grpc=<NODE RPC URL> graphql=<NODE GRAPHQL URL>`._

#### Mainnet:Offline
```text
docker run -d --rm -e "MODE=OFFLINE" -e "NETWORK=MAINNET" -e "PORT=8081" -p 8081:8081 rosetta-ethereum:latest
docker run -d --rm -e "MODE=OFFLINE" -e "NETWORK=MAINNET" -e "PORT=8081" -p 8081:8081 rosetta-maro:latest
```
_If you cloned the repository, you can run `make run-mainnet-offline`._

#### Testnet:Online
```text
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
docker run -d --rm --ulimit "nofile=100000:100000" -v "$(pwd)/maro-data:/data" -e "MODE=ONLINE" -e "NETWORK=TESTNET" -e "PORT=8080" -p 8080:8080 -p 30303:30303 rosetta-maro:latest
```
_If you cloned the repository, you can run `make run-testnet-online`._

#### Testnet:Online (Remote)
```text
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
docker run -d --rm --ulimit "nofile=100000:100000" -e "MODE=ONLINE" -e "NETWORK=TESTNET" -e "PORT=8080" -e "GRPC=<NODE URL>" -e "GRAPHQL=<NODE GRAPHQL URL>" -p 8080:8080 -p 30303:30303 rosetta-maro:latest
```
_If you cloned the repository, you can run `make run-testnet-remote geth=<NODE URL>`._
_If you cloned the repository, you can run `make run-testnet-remote grpc=<NODE RPC URL> graphql=<NODE GRAPHQL URL>`._

#### Testnet:Offline
```text
docker run -d --rm -e "MODE=OFFLINE" -e "NETWORK=TESTNET" -e "PORT=8081" -p 8081:8081 rosetta-ethereum:latest
docker run -d --rm -e "MODE=OFFLINE" -e "NETWORK=TESTNET" -e "PORT=8081" -p 8081:8081 rosetta-maro:latest
```
_If you cloned the repository, you can run `make run-testnet-offline`._

## System Requirements
`rosetta-ethereum` has been tested on an [AWS c5.2xlarge instance](https://aws.amazon.com/ec2/instance-types/c5).
`rosetta-maro` has been tested on an [AWS c5.2xlarge instance](https://aws.amazon.com/ec2/instance-types/c5).
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.
it is possible that `rosetta-maro` will exit with an OOM error.

### Recommended OS Settings
To increase the load `rosetta-ethereum` can handle, it is recommended to tune your OS
To increase the load `rosetta-maro` 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](http://www.tweaked.io/guide/kernel)):
```text
Expand All @@ -120,26 +112,12 @@ 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
_We have not tested `rosetta-maro` 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`.

## Testing with rosetta-cli
To validate `rosetta-ethereum`, [install `rosetta-cli`](https://github.com/coinbase/rosetta-cli#install)
and run one of the following commands:
* `rosetta-cli check:data --configuration-file rosetta-cli-conf/testnet/config.json`
* `rosetta-cli check:construction --configuration-file rosetta-cli-conf/testnet/config.json`
* `rosetta-cli check:data --configuration-file rosetta-cli-conf/mainnet/config.json`

## Future Work
* Add ERC-20 Rosetta Module to enable reading ERC-20 token transfers and transaction construction
* [Rosetta API `/mempool/*`](https://www.rosetta-api.org/docs/MempoolApi.html) implementation
* Add more methods to the `/call` endpoint (currently only support `eth_getTransactionReceipt`)
* Add CI test using `rosetta-cli` to run on each PR (likely on a regtest network)

_Please reach out on our [community](https://community.rosetta-api.org) if you want to tackle anything on this list!_

## Development
* `make deps` to install dependencies
Expand All @@ -152,4 +130,4 @@ _Please reach out on our [community](https://community.rosetta-api.org) if you w
## License
This project is available open source under the terms of the [Apache 2.0 License](https://opensource.org/licenses/Apache-2.0).

© 2021 Coinbase
© 2021 maro
2 changes: 1 addition & 1 deletion configuration/configuration.go
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ const (
// GethEnv is an optional environment variable
// used to connect rosetta-ethereum to an already
// running geth node.
GethEnv = "GETH"
GethEnv = "GRPC"

// DefaultGethURL is the default URL for
// a running geth node. This is used
Expand Down

0 comments on commit a7e10df

Please sign in to comment.