Construction API Overview

Just as the Data API provides the ability to read data from a blockchain in a standard format, the Construction API enables developers to write to a blockchain (i.e., construct transactions) in a standard format. To meet strict security standards, implementations are expected to be stateless, operate entirely offline, and support detached key generation and signing.

For a full list of expectations of any Rosetta API implementation, please take a look at the documents in the Best Practices section. We also recommend taking a look at the Common Mistakes document for a list of some of the mistakes implementers make when meeting these expectations.

Flow of Operations

Standard Format

Rather than defining a new set of types to construct transactions, the Construction API uses the same set of types as the Data API. Just as you would read a stream of operations to a blockchain using the Data API, you can write a stream of operations to the blockchain using the Construction API.

With the same expressiveness as on-chain activity, this standardized format allows for the construction of complex transactions with a general abstraction. Feasibly, you could take the operations observed on-chain using the Data API and construct a new transaction using them (after changing the fields).

Naturally, it is not possible to fully specify everything that will occur in a transaction in many cases (especially in blockchains with invoked events) but it is still possible to deterministically specify intent. Specifying a transfer with a given fee is straightforward enough but specifying a complicated contract invocation is not possible. There is an expectation that what is observed on-chain using the Data API will be a superset of what was provided during construction (not necessarily a strict superset because sometimes it is possible to fully specify a transaction).

It is up to the implementer to responsibly error when a request may lead to non-deterministic transaction construction. One of the largest efforts of the automated testing currently under development is to test this edge case extensively.

Stateless Execution

Construction API implementations must not keep any state. For example, Construction API implementations must not assume that they can persist data to help with transaction construction between calls. Each invocation of a function in the Construction API will be a fresh invocation in a new execution environment (all information needed in later calls must be confined to the responses).

Completely Offline

Construction API implementations will be expected to run in a completely offline environment. However, many blockchains require dynamic information to construct valid transactions (for example, account nonce or recent block hash). Any metadata required for transaction construction can be retrieved by creating a request that must be made to the /construction/metadata endpoint in the Data API. This explicit connectivity boundary allows for comprehensive auditing of all communication that occurs during transaction construction.

It is likely that developers in the community will build on top of these low level constructs to provide tooling that performs online construction (hiding this metadata fetch) while retaining the ability to construct transactions with the Rosetta operations.

Detached Key Generation and Transaction Signing

The Construction API exclusively supports detached key management (for example, key generation and signing). At a high level, this means that Construction API implementations provide a series of payloads to sign during construction instead of signing transactions directly with some provided key. It is up to the the user of the Construction API implementation to return a correctly formatted signature to the implementation (the format of each signature type is explicitly specified).

Check out the keys package in rosetta-sdk-go for an example of a Construction API-compatible signer.

It is likely that developers in the community will build modules that allow for signing these Rosetta-based payloads in many languages (especially for mobile wallet support). This would allow for a Coinbase Wallet SDK-like experience for any blockchain (not just for web3-compatible ones).

If you have any questions about the Construction API, reach out in our community boards.