GuidesAPI Reference
DocumentationLog In

How to Test your Rosetta Implementation

Overview

You can use the rosetta-cli tool to test your Rosetta API implementation. Once your implementation passes through the check:data and check:construction tests, it's a few steps away from being used in services that use Rosetta API.

Prerequisites

1. Install the rosetta-cli tool in your local directory

Download the binary into a ./bin directory (relative to your current directory) with the following command:

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).

  • Note: Downloading binaries from the GitHub application will cause permission errors on Mac.

To download the binary into a specific directory, run the following command:

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

2. Create your configuration file

Read our How to Write a Configuration File for rosetta-cli Testing documentation to learn how to create a configuration file. You can find example configuration files in the examples/configuration directory. You can also find example configuration files for running tests against a Bitcoin Rosetta implementation (configuration file) and an Ethereum Rosetta implementation (configuration file).

You can also create a default configuration file with the rosetta-cli tool's configuration:create command.

3. Write the check:construction tests in Rosetta DSL.

Read our How to Write a Rosetta DSL File documentation to learn how to create the tests.

4. Disable complex checks (for now)

If you are just getting started with your implementation, you may want to disable balance tracking (did any address balance go below zero?) and reconciliation (does the balance I calculated match the balance returned by the /account/balance endpoint?). Take a look at this simple configuration for an example of how to do this.

If you'd like to add more details, see our How to Disable Complex Checks documentation.

After you're done testing, be sure to enable these complex checks again! Your Rosetta API implementation is complete when these complex checks pass the rosetta-cli tool testing.

Run the Tool

Run the rosetta-cli tool from the command line with this command: rosetta-cli [command]. You must run the tool with a command. Otherwise, the default return is the same as the return for the rosetta-cli help command.

If there are no issues found while running check:data or check:construction, it will exit with a 0 status code. If there are any issues, it will exit with a 1 status code. It can be useful to run this command as an integration test for any changes to your implementation.

Commands

You can use the following commands with the rosetta-cli tool.

CommandDescriptionExample
check:constructionTests a Rosetta Construction API Implementation.rosetta-cli check:construction
check:dataTests a Rosetta Data API Implementation.rosetta-cli check:data
configuration:createCreates a default configuration file at the provided path.rosetta-cli configuration:create
configuration:validateEnsures that the configuration file at the provided path is formatted correctly.rosetta-cli configuration:validate
helpProvides help about any command.rosetta-cli help
utils:asserter-configurationGenerate a static configuration file. Most users will not need to use this command.rosetta-cli utils:asserter-configuration
utils:train-zstdGenerate a zstd dictionary for enhanced compression performance. Most users will not need to use this command.rosetta-cli utils:train-zstd
versionPrints the rosetta-cli tool’s version number.rosetta-cli version
view:balanceViews an account balance.rosetta-cli view:balance
view:blockViews a block.rosetta-cli view:block
view:networksViews all network statuses.rosetta-cli view:networks

Flags

Use the following flags with the commands for the rosetta-cli tool.

FlagDescriptionExample
--block-profile [filename]Saves the pprof block profile in the specified file.rosetta-cli [command] --block-profile pprof.file
--configuration-file [filename]The configuration file that provides connection and test settings.
If you would like to generate a starter configuration file (populated with the defaults), run rosetta-cli configuration:create. Any fields not populated in the configuration file will be populated with default values.
rosetta-cli check:data --configuration-file config.json
--cpu-profile [filename]Save the pprof cpu profile in the specified file.1
-h, --helpShows the help file for the rosetta-cli tool.rosetta-cli --help
--mem-profile [filename]Saves the pprof mem profile in the specified file.rosetta-cli [command] --mem-profile pprof.file
rosetta-cli [command] --helpProvides more information about the specified command.rosetta-cli check:data --help

Example

The following example runs the check:data command with the --configuration-file flag.

rosetta-cli check:data --configuration-file config.json

The command’s output will resemble the following example:

Success: Reconciliation Coverage End Condition [Coverage: 100.000000%]

+--------------------+--------------------------------+--------+
|  CHECK:DATA TESTS  |          DESCRIPTION           | STATUS |
+--------------------+--------------------------------+--------+
| Request/Response   | Rosetta implementation         | PASSED |
|                    | serviced all requests          |        |
+--------------------+--------------------------------+--------+
| Response Assertion | All responses are correctly    | PASSED |
|                    | formatted                      |        |
+--------------------+--------------------------------+--------+
| Block Syncing      | Blocks are connected into a    | PASSED |
|                    | single canonical chain         |        |
+--------------------+--------------------------------+--------+
| Balance Tracking   | Account balances did not go    | PASSED |
|                    | negative                       |        |
+--------------------+--------------------------------+--------+
| Reconciliation     | No balance discrepancies were  | PASSED |
|                    | found between computed and     |        |
|                    | live balances                  |        |
+--------------------+--------------------------------+--------+

+--------------------------+--------------------------------+-------------+
|     CHECK:DATA STATS     |          DESCRIPTION           |    VALUE    |
+--------------------------+--------------------------------+-------------+
| Blocks                   | # of blocks synced             |       92610 |
+--------------------------+--------------------------------+-------------+
| Orphans                  | # of blocks orphaned           |           0 |
+--------------------------+--------------------------------+-------------+
| Transactions             | # of transactions processed    |       93674 |
+--------------------------+--------------------------------+-------------+
| Operations               | # of operations processed      |      374511 |
+--------------------------+--------------------------------+-------------+
| Accounts                 | # of accounts seen             |          97 |
+--------------------------+--------------------------------+-------------+
| Active Reconciliations   | # of reconciliations performed |      138996 |
|                          | after seeing an account in a   |             |
|                          | block                          |             | 
+--------------------------+--------------------------------+-------------+
| Inactive Reconciliations | # of reconciliations performed |      849330 |
|                          | on randomly selected accounts  |             |
+--------------------------+--------------------------------+-------------+
| Exempt Reconciliations   | # of reconciliation failures   |           0 |
|                          | considered exempt              |             |
+--------------------------+--------------------------------+-------------+
| Failed Reconciliations   | # of reconciliation failures   |           0 |
+--------------------------+--------------------------------+-------------+
| Skipped Reconciliations  | # of reconciliation skipped    |           0 |
+--------------------------+--------------------------------+-------------+
| Reconciliation Coverage  | % of accounts that have been   | 100.000000% |
|                          | reconciled                     |             |
+--------------------------+--------------------------------+-------------+

Frequently Asked Questions

Which command should I run first?

This will depend on what goals you're trying to accomplish. We suggest that you run the check:data test first. The reason is that this test may take a long time, depending on your configuration. If the check:data test has to check all of the accounts in older blockchains, that test can take a long time to finish.

(Fortunately, if there are any errors that end the check:data test before it's checked all the information you want it to check, the test will restart at the last block where it left off.)

After the check:data test completes, we suggest that you run the check:construction test.

Can I run the check:data and check:construction commands at the same time?

You must run the check:data and check:construction commands separately. They cannot be run at the same time. The check:data test may take a long time to complete on older blockchains with lots of blocks. (We're talking about weeks, maybe even a month or more!) If you are testing on the mainnet network, be aware that this situation will likely occur for older blockchains.

What does the pprof profile do?

The pprof profile is a Golang tool that helps with performance optimization. You can use this tool to know which resources your system is using before or after you run the rosetta-cli tool for testing your Rosetta API implementations. For more information, visit Google's pprof repository in GitHub.