GuidesAPI Reference
DocumentationLog In

Flow of operations

Before diving into the specification and documentation, we recommend reviewing the high-level diagrams below to gain some familiarity with the functionality of the Rosetta APIs.

The Rosetta APIs are organized into two distinct categories, the Data API and the Construction API. Simply put, the Data API is for retrieving data from a blockchain network and the Construction API is for constructing and submitting transactions to a blockchain network.

The Data API was previously known as the Data API and the Construction API was previously known as the Construction API. Their names were changed to better reflect their functionality.

Data API

                                  Caller (i.e. Coinbase)                              + Data API Implementation
                                 +------------------------------------------------------------------------------------+
                               X                                                      |
                               X      Get Supported Networks +---------------------------------> /network/list
                               X                                                      |                +
                               X  +-----------+--------------------------------------------------------+
      Get supported networks,  X  |           v                                       |
      their supported options, X  |   Get Network Options +------------------------------------> /network/options
      and their status         X  |                                                   |
                               X  +-----------+                                       |
                               X              v                                       |
                               X      Get Network Status +-------------------------------------> /network/status
                               X                                                      |
                                                                                      |
                                   X                                                  |
                                   X  Get Block +----------------------------------------------> /block
                                   X                                                  |             +
                        +---------+X                +-----------------------------------------------+
                        |          X                v                                 |
Ensure balance computed |          X  [Optional] Get Additional Block Transactions +-----------> /block/transaction
from block operations   |          X                                                  |
equals balance on node  |                                                             |
                        |                                                             |
                        +-----------> Get account balance for each +---------------------------> /account/balance
                                      account seen in a block                         |
                                                                                      |
                                                                                      |
                                   X                                                  |
                                   X  Get Mempool Transactions +-------------------------------> /mempool
      Monitor the mempool for      X                                                  |              +
      broadcast transaction status X                 +-----------------------------------------------+
      and incoming deposits        X                 v                                |
                                   X  Get a Specific Mempool Transaction +---------------------> /mempool/transaction
                                   X                                                  |
                                                                                      |
                                                                                      |
                                   X                                                  |
  Make arbitrary call to to access X  Make Arbitrary Procedure Call +--------------------------> /call
  network-specific data            X                                                  |
                                   X                                                  |
                                                                                      +

Construction API

If you have seen illustrations of the flow of transaction construction in other blockchain SDKs, the following diagrams may seem peculiar to you. Unlike traditional SDKs, Construction API implementations are fully stateless, can perform construction offline (when metadata like an account nonce is pre-fetched), and never have access to private key material.

                               Caller (i.e. Coinbase)                + Construction API Implementation
                              +-------------------------------------------------------------------------------------------+
                                                                     |
                               Derive Address   +----------------------------> /construction/derive
                               from Public Key                       |
                                                                     |
                             X                                       |
                             X Create Metadata Request +---------------------> /construction/preprocess
                             X (array of operations)                 |                    +
    Get metadata needed      X                                       |                    |
    to construct transaction X            +-----------------------------------------------+
                             X            v                          |
                             X Fetch Online Metadata +-----------------------> /construction/metadata (online)
                             X                                       |
                                                                     |
                             X                                       |
                             X Construct Payloads to Sign +------------------> /construction/payloads
                             X (array of operations)                 |                   +
                             X                                       |                   |
 Create unsigned transaction X          +------------------------------------------------+
                             X          v                            |
                             X Parse Unsigned Transaction +------------------> /construction/parse
                             X to Confirm Correctness                |
                             X                                       |
                                                                     |
                             X                                       |
                             X Sign Payload(s) +-----------------------------> /construction/combine
                             X (using caller's own detached signer)  |                 +
                             X                                       |                 |
   Create signed transaction X         +-----------------------------------------------+
                             X         v                             |
                             X Parse Signed Transaction +--------------------> /construction/parse
                             X to Confirm Correctness                |
                             X                                       |
                                                                     |
                             X                                       |
                             X Get hash of signed transaction +--------------> /construction/hash
Broadcast Signed Transaction X to monitor status                     |
                             X                                       |
                             X Submit Transaction +--------------------------> /construction/submit (online)
                             X                                       |
                                                                     +

Simplified Flow using a Higher-Level Interface

Many developers may not have security constraints that dictate construction must occur offline or that they use their own detached signer (making the previously described flow much more cumbersome than other transaction construction and signing SDKs).

Fortunately, it is possible (and encouraged) to build higher-level interfaces on top of these low-level endpoints to simplify development for integrators. For example, an interface developer may wish to automatically fetch metdata during their call to construct a transaction so users would not even know there are multiple interactions occurring. One could also provide a signing library with their higher-level interface so users do not need to use a detached signer. Here is an example of a simplified flow:

                               Caller (i.e. Mobile Wallet)           + Construction API Implementation
                              +-------------------------------------------------------------------------------------------+
                                                                     |
                               Derive Address   +----------------------------> /construction/derive
                               from Public Key                       |
                                                                     |                                  X
                                                                     |                                  X   Fetch metadata needed for
                                                                     |                                  X   construction automatically
                             X                                       |                                  X
 Create unsigned transaction X Construct Payloads to Sign +------------------> /construction/payloads   X   /construction/preprocess
                             X (array of operations)                 |                                  X             +
                             X                                       |                                  X             v
                                                                     |                                  X   /construction/metadata
                             X                                       |                                  X
                             X Sign Payload(s) +-----------------------------> /construction/combine
                             X (using rosetta-sdk-go keys package)   |                 +
                             X                                       |                 |
   Create signed transaction X         +-----------------------------------------------+
                             X         v                             |
                             X Parse Signed Transaction +--------------------> /construction/parse
                             X to Confirm Correctness                |
                             X                                       |
                                                                     |
                             X                                       |
                             X Get hash of signed transaction +--------------> /construction/hash
Broadcast Signed Transaction X to monitor status                     |
                             X                                       |
                             X Submit Transaction +--------------------------> /construction/submit
                             X                                       |
                                                                     +

Why go through all this trouble to build a higher-level interface on this Construction API instead of just using existing SDKs, you may be wondering? Any interface built on top of the Construction API could support the construction of transactions on any blockchain that supports Rosetta with no modification. You could, for example, build a WalletLink service that worked with any blockchain.