# ADR 035: Rosetta API Support
- Jonathan Gimeno (@jgimeno)
- David Grierson (@senormonito)
- Alessio Treglia (@alessio)
- Frojdy Dymylja (@fdymylja)
- 2021-05-12: the external library cosmos-rosetta-gateway (opens new window) has been moved within the Cosmos SDK.
Rosetta API (opens new window) is an open-source specification and set of tools developed by Coinbase to standardise blockchain interactions.
Through the use of a standard API for integrating blockchain applications it will
- Be easier for a user to interact with a given blockchain
- Allow exchanges to integrate new blockchains quickly and easily
- Enable application developers to build cross-blockchain applications such as block explorers, wallets and dApps at considerably lower cost and effort.
It is clear that adding Rosetta API support to the Cosmos SDK will bring value to all the developers and Cosmos SDK based chains in the ecosystem. How it is implemented is key.
The driving principles of the proposed design are:
- Extensibility: it must be as riskless and painless as possible for application developers to set-up network configurations to expose Rosetta API-compliant services.
- Long term support: This proposal aims to provide support for all the supported Cosmos SDK release series.
- Cost-efficiency: Backporting changes to Rosetta API specifications from
masterto the various stable branches of Cosmos SDK is a cost that needs to be reduced.
We will achieve these delivering on these principles by the following:
- There will be a package
rosetta/libfor the implementation of the core Rosetta API features, particularly: a. The types and interfaces (
OfflineClient...), this separates design from implementation detail. b. The
Serverfunctionality as this is independent of the Cosmos SDK version. c. The
Online/OfflineNetwork, which is not exported, and implements the rosetta API using the
Clientinterface to query the node, build tx and so on. d. The
errorspackage to extend rosetta errors.
- Due to differences between the Cosmos release series, each series will have its own specific implementation of
- There will be two options for starting an API service in applications: a. API shares the application process b. API-specific process.
# The External Repo
As section will describe the proposed external library, including the service implementation, plus the defined types and interfaces.
Server is a simple
struct that is started and listens to the port specified in the settings. This is meant to be used across all the Cosmos SDK versions that are actively supported.
The constructor follows:
func NewServer(settings Settings) (Server, error)
Settings, which are used to construct a new server, are the following:
Package types uses a mixture of rosetta types and custom defined type wrappers, that the client must parse and return while executing operations.
Every SDK version uses a different format to connect (rpc, gRPC, etc), query and build transactions, we have abstracted this in what is the
The client uses rosetta types, whilst the
Online/OfflineNetwork takes care of returning correctly parsed rosetta responses and errors.
Each Cosmos SDK release series will have their own
Developers can implement their own custom
Clients as required.
# 2. Cosmos SDK Implementation
The Cosmos SDK implementation, based on version, takes care of satisfying the
In Stargate, Launchpad and 0.37, we have introduced the concept of rosetta.Msg, this message is not in the shared repository as the sdk.Msg type differs between Cosmos SDK versions.
The rosetta.Msg interface follows:
Hence developers who want to extend the rosetta set of supported operations just need to extend their module's sdk.Msgs with the
# 3. API service invocation
As stated at the start, application developers will have two methods for invocation of the Rosetta API service:
- Shared process for both application and API
- Standalone API service
# Shared Process (Only Stargate)
Rosetta API service could run within the same execution process as the application. This would be enabled via app.toml settings, and if gRPC is not enabled the rosetta instance would be spinned in offline mode (tx building capabilities only).
# Separate API service
Client application developers can write a new command to launch a Rosetta API server as a separate process too, using the rosetta command contained in the
/server/rosetta package. Construction of the command depends on Cosmos SDK version. Examples can be found inside
simd for stargate, and
contrib/rosetta/simapp for other release series.
- Out-of-the-box Rosetta API support within Cosmos SDK.
- Blockchain interface standardisation