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.
| Command | Description | Example |
|---|---|---|
check:construction | Tests a Rosetta Construction API Implementation. | rosetta-cli check:construction |
check:data | Tests a Rosetta Data API Implementation. | rosetta-cli check:data |
configuration:create | Creates a default configuration file at the provided path. | rosetta-cli configuration:create |
configuration:validate | Ensures that the configuration file at the provided path is formatted correctly. | rosetta-cli configuration:validate |
help | Provides help about any command. | rosetta-cli help |
utils:asserter-configuration | Generate a static configuration file. Most users will not need to use this command. | rosetta-cli utils:asserter-configuration |
utils:train-zstd | Generate a zstd dictionary for enhanced compression performance. Most users will not need to use this command. | rosetta-cli utils:train-zstd |
version | Prints the rosetta-cli tool’s version number. | rosetta-cli version |
view:balance | Views an account balance. | rosetta-cli view:balance |
view:block | Views a block. | rosetta-cli view:block |
view:networks | Views all network statuses. | rosetta-cli view:networks |
Flags
Use the following flags with the commands for the rosetta-cli tool.
| Flag | Description | Example |
|---|---|---|
--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, --help | Shows 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] --help | Provides 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 | |
+--------------------------+--------------------------------+-------------+
Testing Destination Tag Blockchains
You can test the Rosetta implementation of a blockchain that uses destination tags with a Workflow that you can add to your Rosetta DSL file.
- Manually generate the recipient account address and the corresponding destination tag from the blockchain wallet or tool you're testing.
- Write your Rosetta DSL file
transferWorkflows to test the destination tag. You can follow the example in the Destination Tag Support section of the How to Write a Rosetta DSL File documentation. - Enter the recipient address and destination tag that you generated in step 1 in these fields in your
transferWorkflow:- The
addressfield inrecipient_account:recipient_account = {"address":"a1d2d3r4e5s6s7"} - The
memofield intransfer.preprocess_metadata:transfer.preprocess_metadata = {"memo":"destination-tag"}
- The
- Run the
check:constructioncommand and check the results. If your results are correct, your output should be similar to the output in the Example section.
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.