Integrating the Rosetta API in Cosmos Blockchains

Developed by Coinbase, the Rosetta API is an open standard designed to simplify blockchain deployment and interaction. The Rosetta API specifications offer a common interface to communicate with blockchains of different types. Because each blockchain has its own mechanism for signing transactions, forming requests, querying balances, and other operations, wallets and exchanges like Coinbase are constantly developing and maintaining the software required for interacting with these technologies.

The Cosmos Rosetta API support was developed so that blockchain builders could adhere to or create a proxy that meets Coinbase’s specifications.

Why Rosetta makes your life easier

Rosetta is the only supported specification for interacting with blockchain applications — and Coinbase is one of the largest cryptocurrency exchanges in the world. Wallet and exchange integration with Coinbase is becoming a standard of blockchain infrastructure. The Cosmos SDK architecture makes Rosetta API integration possible by adding only one line of code.

By integrating the Rosetta API in your Cosmos SDK blockchain application, exchanges are capable of listing your cryptocurrency coin. Integration for wallets and other services that rely on the Rosetta API to interact with a chain also benefit from its integration. If you already use the Rosetta API with any other blockchain, you will find it especially useful and easy to integrate with Cosmos SDK based applications.

How we integrated Rosetta API in Cosmos

Integrating the Rosetta API into the Cosmos SDK presented interesting challenges. Specifically, the Rosetta API specifications expected the implementation to work like a UTXO (unspent transaction output) blockchain. In UTXO-based blockchains, transactions in each block comprise a set of inputs (coins received) and outputs (coins spent). In this case, querying an account in the given height x returns the sum of inputs and outputs of its address that is computed by querying the transaction inputs and outputs of that address from block 0 to block x.

State transitions for blockchains launched with the Cosmos SDK occur at the transaction level and also at begin block and end block stages. Because of this difference, querying transactions and computing the coins spent did not provide a complete view of the actual balance and supply changes. In the Cosmos SDK universe, rewards are earned by staking and actions like delegating add more dimensions to how balances and supply can be queried.

To integrate the Rosetta API into the Cosmos SDK, we changed the Cosmos SDK to emit events for each supply and balance change. These events are emitted no matter where (which handler of which module) and when (DeliverTx, BeginBlock, EndBlock).

The second challenge was to enable the Rosetta API to support all blockchain applications and their supported messages. Supporting only common actions like sending coins, delegating, and so on was not enough. We wanted the full set of messages for all Cosmos SDK blockchain applications to be queryable and sendable using the Rosetta API.

Now that you know how we overcame our interesting challenges, here is how you can integrate the Rosetta API into your Cosmos SDK blockchain application!

Rosetta API integration

The changes to support the Rosetta API integration are introduced in the Cosmos SDK 0.43 release series. If you are on a lower version, upgrade to Cosmos SDK v0.43.

Add the RosettaCommandto your application root command file.

After the initRootCmd(rootCmd, encodingConfig)line, add the following line:

rootCmd.AddCommand(server.RosettaCommand(encodingConfig.InterfaceRegistry, encodingConfig.Marshaler))

For example, in this root command file, add the Rosetta command to line 96.

The application root command file is in the server package in github.com/cosmos/cosmos-sdk/server.

Since we’ve updated the Cosmos SDK to work with the Rosetta API, updating the application root command file is all you need to do.

To run Rosetta in your application CLI, use the following command:

appd rosetta --help

To test and run Rosetta API endpoints for applications that are running and exposed, use the following command:

appd rosetta
     --blockchain "your application name (ex: gaia)"
     --network "your chain identifier (ex: testnet-1)"
     --tendermint "tendermint endpoint (ex: localhost:26657)"
     --grpc "gRPC endpoint (ex: localhost:9090)"
     --addr "rosetta binding address (ex: :8080)"

What’s next?

The current implementation of Rosetta API in the Cosmos SDK supports one chain at a time and requires the compile time information (the interface registry and the codec). As always, ongoing developments and feature enhancements are happening in the Cosmos SDK. Future implementations are planned to allow for reflection clients that are capable of real-time builds of the codec and the interface registry.

We all look forward to using Rosetta API endpoints to query and simultaneously write txs to multiple chains at runtime, without requiring chain-specific codecs. Join us on this journey and stay tuned for future updates!