Rosetta CLI

CLI to validate the correctness of Rosetta API implementations

The rosetta-cli tool is used by developers to test the correctness of their Rosetta API implementations. The CLI also provides the ability to look up block contents and account balances.

Installation

To download a binary for the latest release, run:

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

The binary will be installed inside the ./bin directory (relative to the directory where you ran the installation command).

Downloading binaries from the Github UI will cause permission errors on Mac.

Installing in a Custom Location

To download the binary into a specific directory, run:

curl -sSfL https://raw.githubusercontent.com/coinbase/rosetta-cli/master/scripts/install.sh | sh -s -- -b <relative directory>

Run via Docker

Running the following command will start a Docker container and present CLI for the Rosetta API.

docker run -it [image-name] [command]

Example: To validate that the Data API implementation is correct, running the following command will start a Docker container with a data directory at <working directory>.

docker run -v "$(pwd):/data" -it [image-name] check:data --configuration-file /data/config.json

Key Sign Tool

Rosetta CLI comes with a handy key sign tool for local testing. Please refer to this README on how to use it.

Updates and Releases

We recommend that you continually update your installation to the latest release as soon as possible. The latest release notes are available in our Community board under the Release category.

You can also view releases and change log information in the Releases section of this repository.

Documentation

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

For more information on the rosetta-cli tool, read our The rosetta-cli tool documentation.

For more information on how to test your implementation file with the rosetta-cli tool, read our How to Test Your Rosetta Implementation documentation.

Our documentation is divided into the following sections:

• Product Overview
• Getting Started
• Rosetta API Spec
• Testing
• Best Practices
• Repositories

Contributing

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

• Asking Questions
• Providing Feedback
• Reporting Issues

Read our Contributing documentation for more information.

rosetta-cli Tool Development

While working on improvements to this repository, we recommend that you use these commands to check your code:

• make deps to install dependencies
• make test to run tests
• make lint to lint the source code (included generated code)
• make release to run one last check before opening a PR
• make compile version=RELEASE_TAG to generate binaries

If you are developing on both the rosetta-cli and rosetta-sdk-go repositories, use go.mod replace to reference local changes:

replace "github.com/coinbase/rosetta-sdk-go" v0.6.8 => "<PATH TO LOCAL rosetta-sdk-go>"

Release

• When we release a new rosetta-cli version, please update the version number to follow PR so that rosetta-cli version command can print the correct value.
• Create binaries and upload all the binaries in the new release tag (e.g. https://github.com/coinbase/rosetta-cli/releases/tag/v0.7.7)
  • Ensure $GOPATH/bin is added to $PATH
  • Run make compile version=<New Version>
  • All the binaries will be created in the bin folder and should have extension as tar.gz and new version number

Helper/Handler

Many of the packages use a Helper/Handler interface pattern to acquire required information or to send events to some client implementation. An example of this is in the reconciler package where a Helper is used to get the account balance and the Handler is called to indicate whether the reconciliation of an account was successful.

Repo Structure

cmd
examples // examples of different config files
pkg
  logger // logic to write syncing information to stdout/files
  processor // Helper/Handler implementations for reconciler, storage, and syncer
  tester // test orchestrators

Troubleshooting

While running the check:data or check:construction option, if you get the following error:

dial tcp 127.0.0.1:8080: socket: too many open files: unable to sync to 1902533: unable to sync to 1902533

Please run the ulimit -n 10000 command to increase the max concurrent opened file limit.

Note: MacOS users, if you face ulimit: setrlimit failed: invalid argument error while setting ulimit, please run sudo launchctl limit maxfiles 10000 200000 before setting the ulimit.

Related Projects

• rosetta-sdk-go — The rosetta-sdk-go SDK provides a collection of packages used for interaction with the Rosetta API specification. Much of the SDK code is generated from this, the rosetta-specifications repository.
• rosetta-specifications — The rosetta-specifications repository generates the SDK code in the rosetta-sdk-go repository.

Reference Implementations

To help you with examples, we developed complete Rosetta API reference implementations for Bitcoin and Ethereum. Developers of Bitcoin-like or Ethereum-like blockchains may find it easier to fork these reference implementations than to write an implementation from scratch.

You can also 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