rosetta-cli

rosetta-cli utilizes the rosetta-sdk-go to validate the "correctness" of a Rosetta Node API implementation. For a full list of all checks performed to determine correctness, visit this link.

Commands

The rosetta-cli offers a growing collection of tools to debug Rosetta API implementations. If you have any ideas for new commands, please open an issue.

check

Check all server responses are properly constructed, that there are no duplicate blocks and transactions, that blocks can be processed from genesis to the current block (re-orgs handled automatically), and that computed balance changes are equal to balance changes reported by the node.

When re-running this command, it will start where it left off if you specify some --data-dir. Otherwise, it will create a new temporary directory and start again from the genesis block. If you want to discard some number of blocks populate the --start flag with some block index. Starting from a given index can be useful to debug a small range of blocks for issues but it is highly recommended you sync from start to finish to ensure all correctness checks are performed.

By default, account balances are looked up at specific heights (instead of only at the current block). If the node you are working on does not support this functionality set --lookup-balance-by-block to false. This will make reconciliation much less efficient but it will still work.

If check fails due to an INACTIVE reconciliation error (balance changed without any corresponding operation), the cli will automatically try to find the block missing an operation. If --lookup-balance-by-block is not enabled, this automatic debugging tool does not work.

To debug an INACTIVE account reconciliation error without --lookup-balance-by-block, set the --interesting-accounts flag to the absolute path of a JSON file containing accounts that will be actively checked for balance changes at each block. This will return an error at the block where a balance change occurred with no corresponding operations.

If the blockchain you are working on has a genesis allocation of funds and you set --lookup-balance-by-block to false, you must provide an absolute path to a JSON file containing initial balances with the --bootstrap-balances flag. You can look at the examples folder for an example of what one of these files looks like.

create:configuration

In production deployments, it is useful to initialize the response asserter using a static configuration instead of intializing a configuration dynamically from the node. This allows a client to error on new types/statuses that may have been added in an update instead of silently erroring.

To use this command, simply provide an absolute path as the argument for where the configuration file should be saved (in JSON). Populate the optional --server-url flag with the url of the server to generate the configuration from.

view:account

While debugging, it is often useful to inspect the state of an account at a certain block. This command allows you to look up any account by providing a JSON representation of a types.AccountIdentifier (and optionally a height to perform the query).

For example, you could run view:account '{"address":"interesting address"}' 1000 to lookup the balance of an interesting address at block 1000. Allowing the address to specified as JSON allows for querying by SubAccountIdentifier.

view:block

While debugging a Node API implementation, it can be very useful to inspect block contents. This command allows you to fetch any block by index to inspect its contents. It uses the fetcher package to automatically get all transactions in the block and assert the format of the block is correct before printing.

If this command errors, it is likely because the block you are trying to fetch is formatted incorrectly.