An AccountBalanceRequest is utilized to make a balance request
on the /account/balance endpoint.
If the blockIdentifier is populated, a historical balance query
should be performed.
An AccountBalanceResponse is returned on the /account/balance endpoint.
If an account has a balance for each AccountIdentifier describing it
(ex: an ERC-20 token balance on a few smart contracts),
an account balance request must be made with each AccountIdentifier.
The account identifier uniquely identifies an account within a network.
All fields in the AccountIdentifier are utilized to determine
this uniqueness (including the metadata field, if populated).
Allow specifies supported Operation status, Operation types,
and all possible error statuses. This Allow object is used by clients to
validate the correctness of a Rosetta Server implementation.
It is expected that these clients will error if they receive some response
that contains any of the above information that is not specified here.
BalanceExemption indicates that the balance for an exempt account
could change without a corresponding Operation. This typically occurs with
staking rewards, vesting balances, and Currencies with a dynamic supply.
Currently, it is possible to exempt an account from strict reconciliation
by SubAccountIdentifier.Address or by Currency. This means that any account
with SubAccountIdentifier.Address would be exempt or any balance of a
particular Currency would be exempt, respectively. BalanceExemptions
should be used sparingly as they may introduce significant complexity for
integrators that attempt to reconcile all account balance changes.
If your implementation relies on any BalanceExemptions, you MUST implement
historical balance lookup
(the ability to query an account balance at any BlockIdentifier).
Blocks contain an array of Transactions that occurred at
a particular BlockIdentifier. A hard requirement for blocks returned by
Rosetta implementations is that they MUST be unalterable:
once a client has requested and received a block identified by a specific
BlockIdentifier, all future calls for that same BlockIdentifier must
return the same block contents.
BlockEvent represents the addition or removal of a BlockIdentifier
from storage. Streaming BlockEvents allows lightweight clients to update
their own state without needing to implement their own syncing logic.
A BlockResponse includes a fully-populated block or a partially-populated
block with a list of other transactions to fetch otherTransactions.
As a result of the consensus algorithm of some blockchains,
blocks can be omitted (i.e. certain block indexes can be skipped).
If a query for one of these omitted indexes is made, the response should not
include a Block object. It is VERY important to note that blocks MUST
still form a canonical, connected chain of blocks where each block has a
unique index. In other words, the PartialBlockIdentifier of a block after
an omitted block should reference the last non-omitted block.
CoinChange is used to represent a change in state of a some coin identified
by a coinIdentifier. This object is part of the Operation model
and must be populated for UTXO-based blockchains. Coincidentally,
this abstraction of UTXOs allows for supporting both account-based transfers
and UTXO-based transfers on the same blockchain
(when a transfer is account-based, don't poputhis model).
ConstructionCombineRequest is the input to the
/construction/combine endpoint. It contains the unsigned transaction blob
returned by /construction/payloads and all required signatures to
create a network transaction.
Passed to the /construction/derive endpoint.
Network is provided in the request because some blockchains have
different address formats for different networks. Metadata is provided
in the request because some blockchains allow for multiple address types
(i.e. different address for validators vs normal accounts).
Utilized to get information required to construct a transaction.
The options object used to specify which metadata to return is
left purposely unstructured to allow flexibility for implementers.
options is not required in the case that there is network-wide metadata
of interest. Optionally, the request can also include an array of
WalletPublicKeys associated with the AccountIdentifiers returned in
ConstructionPreprocessResponse.
The ConstructionMetadataResponse returns network-specific metadata
used for transaction construction. Optionally, the implementer can return
the suggested fee associated with the transaction being constructed.
The caller may use this info to adjust the intent of the transaction or
to create a transaction with a different account that can pay the
suggested fee. Suggested fee is an array in case fee payment must occur
in multiple currencies.
ConstructionParseResponse contains an array of operations that occur in
a transaction blob. This should match the array of operations provided to
/construction/preprocess and /construction/payloads.
ConstructionTransactionResponse is returned by /construction/payloads.
It contains an unsigned transaction blob (that is usually needed to
construct the a network transaction from a collection of signatures) and
an array of payloads that must be signed by the caller.
Passed to the
/construction/preprocess endpoint so that a Rosetta implementation
can determine which metadata it needs to request for construction.
metadata provided in this object should NEVER be a product of live data
(i.e. the caller must follow some network-specific data fetching strategy
outside of the Construction API to populate required metadata).
ConstructionPreprocessResponse contains options
that will be sent unmodified to /construction/metadata.
If it is not necessary to make a request to /construction/metadata,
options should be omitted.
Currency is composed of a canonical Symbol and Decimals.
This Decimals value is used to convert an Amount.Value from atomic units
(Satoshi) to standard units (Bitcoin).
EventsBlocksRequest is utilized to fetch a sequence of BlockEvents
indicating which blocks were added and removed from storage to reach
the current state.
A MempoolTransactionResponse contains an estimate of a mempool transaction.
It may not be possible to know the full impact of a transaction
in the mempool (ex: fee paid).
NetworkStatusResponse contains basic information about the node's view of
a blockchain network. It is assumed that any BlockIdentifier.Index
less than or equal to CurrentBlockIdentifier.Index can be queried.
If a Rosetta implementation prunes historical state,
it should populate the optional oldest_block_identifier field with
the oldest block available to query. If this is not populated,
it is assumed that the genesis_block_identifier is the oldest
queryable block. If a Rosetta implementation performs some pre-sync
before it is possible to query blocks, sync_status should be populated
so that clients can still monitor healthiness. Without this field, it may
appear that the implementation is stuck syncing and needs to be terminated.
Operations contain all balance-changing information within a transaction.
They are always one-sided (only affect 1 AccountIdentifier) and can succeed
or fail independently from a Transaction. Operations are used both to
represent on-chain data (Data API) and to construct new transactions
(Construction API), creating a standard interface for reading
and writing to blockchains.
When fetching data by BlockIdentifier, it may be possible to only specify
the index or hash. If neither property is specified, it is assumed that
the client is making a request at the current block.
Instead of utilizing HTTP status codes to describe node errors
(which often do not have a good analog),
rich errors are returned using this object.
Both the code and message fields can be individually used to correctly
identify an error. Implementations MUST use unique values for both fields.
SigningPayload is signed by the client with the keypair associated with an
accountIdentifier using the specified signatureType.
signatureType can be optionally populated if there is a restriction on the
signature scheme that can be used to sign the payload.
An account may have state specific to a contract address (ERC-20 token)
and/or a stake (delegated balance). The SubAccountIdentifier should
specify which state (if applicable) an account instantiation refers to.
In blockchains with sharded state, the SubNetworkIdentifier is required to
query some object on a specific shard. This identifier is optional for all
non-sharded blockchains.
SyncStatus is used to provide additional context about an implementation's
sync status. It is often used to indicate that an implementation is healthy
when it cannot be queried until some sync phase occurs.
If an implementation is immediately queryable,
this model is often not populated.
PublicKey contains a public key byte array for a particular CurveType
encoded in hex. Note that there is no PrivateKey struct as this is
NEVER the concern of an implementation.
WalletSignature contains the payload that was signed, the public keys of the
key-pairs used to produce the signature, the signature (encoded in hex),
and the SignatureType. PublicKey is often times not known during
construction of the signing payloads but may be needed to
combine signatures properly.
The timestamp of the block in milliseconds since the Unix Epoch.
The timestamp is stored in milliseconds because some blockchains produce
blocks more often than once a second.
