The mesh-cli Tool

The mesh-cli tool uses the Mesh SDK (mesh-sdk-go) to validate the correctness of both Mesh Data API and Construction API implementations.

Correctness Checks

This tool performs a variety of correctness checks using the Mesh Server. A correctness check reviews the information in the blockchain and confirms that it matches the blockchain’s historical and current account balances. If any correctness check fails, the CLI will exit and print out a detailed message explaining the error.

Response Correctness

The validator uses the autogenerated Go Client package to communicate with the Mesh Server and assert that responses adhere to the Mesh interface specification.

Duplicate Hashes

The validator checks that a block hash or transaction hash is never duplicated.

Non-negative Balances

The validator checks that an account balance does not go negative from any operations.

Balance Reconciliation

Active Accounts

The CLI checks that the balance of an account computed by its operations is equal to the balance of the account according to the node. If this balance is not identical, the CLI will exit.

Inactive Accounts

The CLI randomly checks the balances of accounts that aren’t involved in any transactions. The balances of accounts could change on the blockchain node without being included in an operation returned by the Mesh Data API. Recall that all balance-changing operations should be returned by the Mesh Data API.

Configuration File

All mesh-cli parameters are populated from a configuration file (--configuration-file) that you provide at runtime. If you do not provide a configuration file, the tool uses the default configuration, for example, default.json.

To run tests against Bitcoin and Ethereum implementations, see these config samples for mesh-bitcoin and mesh-ethereum.

For more information on how to create a configuration file, read How to Write a Configuration File for mesh-cli testing.

Disable Complex Checks

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 the simple configuration for an example of how to do this. For more details, read our How to Disable Complex Checks documentation.

Using environment variables

It’s possible to set the configuration file path using an environment variable instead of using a CLI flag. See an example below:

ROSETTA_CONFIGURATION_FILE=/path/to/cli/config rosetta <command>

CLI flags take precedence over environment variables.

Writing check:construction Tests

The Construction API testing framework (the check:construction test in mesh-cli) uses a design pattern that allows for complex transaction construction orchestration.

Most engineers write their check:construction tests using the Mesh Constructor DSL. We have examples of DSL files written for UTXO-based chains and account-based chains. For more information, read How to Write a Mesh DLS File.

End Conditions

When running the mesh-cli tool in a continuous integration (CI) job, it is usually desired to exit when certain conditions are met (or before then with an exit code of 1). We provide this functionality through the use of end conditions which you can specify in your configuration file.

check:data

You can find a full list of check:data end conditions in How to Write a Configuration File, and in the Go Configuration website. If any end condition is satisfied, the tool exits and output the results in the results output file, if the results_output_file field’s value is populated.

check:construction

The check:construction end condition is a map of workflow:count that indicates how many of each workflow should be performed before check:construction stops. For example, {"create_account": 5} indicates that 5 create_account workflows should be performed before stopping.

Unlike check:data, all check:construction end conditions must be satisfied before the mesh-cli tool exits.

Status Codes

If there are no issues found while running check:data or check:construction, the tests will exit with a 0 status code. If there are any issues, they 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.

Usage

CLI for the Mesh API

Usage:
  mesh-cli [command]

Available Commands:
  check:construction           Check the correctness of a Mesh Construction API Implementation
  check:data                   Check the correctness of a Mesh Data API Implementation
  configuration:create         Create a default configuration file at the provided path
  configuration:validate       Ensure a configuration file at the provided path is formatted correctly
  help                         Help about any command
  utils:asserter-configuration Generate a static configuration file for the Asserter
  version                      Print mesh-cli version
  view:account                 View an account balance
  view:block                   View a block
  view:networks                View all network statuses

Flags:
      --configuration-file string   Configuration file that provides connection and test settings.
                                    If you would like to generate a starter configuration file (populated
                                    with the defaults), run mesh-cli configuration:create.

                                    Any fields not populated in the configuration file will be populated with
                                    default values.
  -h, --help                        help for mesh-cli

Use "mesh-cli [command] --help" for more information about a command.

Commands

check:construction

The check:construction command automatically tests a
Construction API implementation by creating and broadcasting transactions
on a blockchain. In short, this tool generates new addresses, requests
funds, constructs transactions, signs transactions, broadcasts transactions,
and confirms transactions land on-chain. At each phase, a series of tests
are run to ensure that intermediate representations are correct (i.e., does
an unsigned transaction return a superset of operations provided during
construction?).

Check out the https://github.com/coinbase/mesh-cli/tree/master/examples
directory for examples of how to configure this test for Bitcoin and
Ethereum.

Right now, this tool only supports transfer testing (for both account-based
and UTXO-based blockchains). However, we plan to add support for testing
arbitrary scenarios (i.e., staking, governance).

Usage:
  mesh-cli check:construction [flags]

Flags:
  -h, --help   help for check:construction

Global Flags:
      --configuration-file string   Configuration file that provides connection and test settings.
                                    If you would like to generate a starter configuration file (populated
                                    with the defaults), run mesh-cli configuration:create.

                                    Any fields not populated in the configuration file will be populated with
                                    default values.

check:data

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 directory. 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 your node does not support this functionality
set historical_balance_disabled to true. 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 historical_balance_disabled is true, this automatic
debugging tool does not work.

To debug an INACTIVE account reconciliation error without historical balance lookup,
set the interesting accounts to the 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 your blockchain has a genesis allocation of funds and you set
historical_balance_disabled to true, you must provide an
absolute path to a JSON file containing initial balances with the
bootstrap balance config. You can look at the examples folder for an example
of what one of these files looks like.

Usage:
  mesh-cli check:data [flags]

Flags:
      --end int     block index to stop syncing (default -1)
  -h, --help        help for check:data
      --start int   block index to start syncing (default -1)

Global Flags:
      --configuration-file string   Configuration file that provides connection and test settings.
                                    If you would like to generate a starter configuration file (populated
                                    with the defaults), run mesh-cli configuration:create.

                                    Any fields not populated in the configuration file will be populated with
                                    default values.

configuration:create

Create a default configuration file at the provided path

Usage:
  mesh-cli configuration:create [flags]

Flags:
  -h, --help   help for configuration:create

Global Flags:
      --configuration-file string   Configuration file that provides connection and test settings.
                                    If you would like to generate a starter configuration file (populated
                                    with the defaults), run mesh-cli configuration:create.

                                    Any fields not populated in the configuration file will be populated with
                                    default values.

configuration:validate

Validate the correctness of a configuration file at the provided path

Usage:
  mesh-cli configuration:validate [flags]

Flags:
  -h, --help   help for configuration:validate

Global Flags:
      --configuration-file string   Configuration file that provides connection and test settings.
                                    If you would like to generate a starter configuration file (populated
                                    with the defaults), run mesh-cli configuration:create.

                                    Any fields not populated in the configuration file will be populated with
                                    default values.

help

Provides help information about any command.

utils:asserter-configuration

In production deployments, it is useful to initialize the response
Asserter (https://github.com/coinbase/mesh-sdk-go/tree/master/asserter) using
a static configuration instead of initializing 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).

Usage:
  mesh-cli utils:asserter-configuration [flags]

Flags:
  -h, --help   help for utils:asserter-configuration

Global Flags:
      --configuration-file string   Configuration file that provides connection and test settings.
                                    If you would like to generate a starter configuration file (populated
                                    with the defaults), run mesh-cli configuration:create.

                                    Any fields not populated in the configuration file will be populated with
                                    default values.

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.

Usage:
  mesh-cli view:account [flags]

Flags:
  -h, --help   help for view:account

Global Flags:
      --configuration-file string   Configuration file that provides connection and test settings.
                                    If you would like to generate a starter configuration file (populated
                                    with the defaults), run mesh-cli configuration:create.

                                    Any fields not populated in the configuration file will be populated with
                                    default values.

view:block

While debugging a Data 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 (https://github.com/coinbase/mesh-sdk-go/tree/master/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.

Usage:
  mesh-cli view:block [flags]

Flags:
  -h, --help   help for view:block

Global Flags:
      --configuration-file string   Configuration file that provides connection and test settings.
                                    If you would like to generate a starter configuration file (populated
                                    with the defaults), run mesh-cli configuration:create.

                                    Any fields not populated in the configuration file will be populated with
                                    default values.

view:networks

While debugging a Data API implementation, it can be very
useful to view network(s) status. This command fetches the network
status from all available networks and prints it to the terminal.

If this command errors, it is likely because the /network/* endpoints are
not formatted correctly.

Usage:
  mesh-cli view:networks [flags]

Flags:
  -h, --help   help for view:networks

Global Flags:
      --configuration-file string   Configuration file that provides connection and test settings.
                                    If you would like to generate a starter configuration file (populated
                                    with the defaults), run mesh-cli configuration:create.

                                    Any fields not populated in the configuration file will be populated with
                                    default values.

version

Print mesh-cli version

Usage:
  mesh-cli version [flags]

Flags:
  -h, --help   help for version

Global Flags:
      --configuration-file string   Configuration file that provides connection and test settings.
                                    If you would like to generate a starter configuration file (populated
                                    with the defaults), run mesh-cli configuration:create.

                                    Any fields not populated in the configuration file will be populated with
                                    default values.