curl --request POST \
--url https://example.com/network/options \
--header 'Content-Type: application/json' \
--data '{
"network_identifier": {
"blockchain": "bitcoin",
"network": "mainnet",
"sub_network_identifier": {
"network": "shard 1",
"metadata": {
"producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
}
}
}
}'{
"version": {
"rosetta_version": "1.2.5",
"node_version": "1.0.2",
"middleware_version": "0.2.7"
},
"allow": {
"operation_statuses": [
{
"status": "SUCCESS",
"successful": true
}
],
"operation_types": [
"TRANSFER"
],
"errors": [
{
"code": 12,
"message": "Invalid account format",
"description": "This error is returned when the requested AccountIdentifier is improperly formatted.",
"details": {
"address": "0x1dcc4de8dec75d7aab85b567b6",
"error": "not base64"
}
}
],
"call_methods": [
"eth_call"
],
"balance_exemptions": [
{
"sub_account_address": "staking",
"currency": {
"symbol": "BTC",
"decimals": 8,
"metadata": {
"Issuer": "Satoshi"
}
}
}
]
}
}Get Network Options
This endpoint returns the version information and allowed network-specific types for a NetworkIdentifier. Any NetworkIdentifier returned by /network/list should be accessible here. Because options are retrievable in the context of a NetworkIdentifier, it is possible to define unique options for each network.
curl --request POST \
--url https://example.com/network/options \
--header 'Content-Type: application/json' \
--data '{
"network_identifier": {
"blockchain": "bitcoin",
"network": "mainnet",
"sub_network_identifier": {
"network": "shard 1",
"metadata": {
"producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
}
}
}
}'{
"version": {
"rosetta_version": "1.2.5",
"node_version": "1.0.2",
"middleware_version": "0.2.7"
},
"allow": {
"operation_statuses": [
{
"status": "SUCCESS",
"successful": true
}
],
"operation_types": [
"TRANSFER"
],
"errors": [
{
"code": 12,
"message": "Invalid account format",
"description": "This error is returned when the requested AccountIdentifier is improperly formatted.",
"details": {
"address": "0x1dcc4de8dec75d7aab85b567b6",
"error": "not base64"
}
}
],
"call_methods": [
"eth_call"
],
"balance_exemptions": [
{
"sub_account_address": "staking",
"currency": {
"symbol": "BTC",
"decimals": 8,
"metadata": {
"Issuer": "Satoshi"
}
}
}
]
}
}Body
A NetworkRequest is utilized to retrieve some data specific exclusively to a NetworkIdentifier.
The network_identifier specifies which network a particular object is associated with.
Show child attributes
Show child attributes
"bitcoin"
If a blockchain has a specific chain-id or network identifier, it should go in this field. It is up to the client to determine which network-specific identifier is mainnet or testnet.
"mainnet"
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.
Response
Expected response to a valid request
NetworkOptionsResponse contains information about the versioning of the node and the allowed operation statuses, operation types, and errors.
The Version object is utilized to inform the client of the versions of different components of the Rosetta implementation.
Show child attributes
Show child attributes
The rosetta_version is the version of the Rosetta interface the implementation adheres to. This can be useful for clients looking to reliably parse responses.
"1.2.5"
The node_version is the canonical version of the node runtime. This can help clients manage deployments.
"1.0.2"
When a middleware server is used to adhere to the Rosetta interface, it should return its version here. This can help clients manage deployments.
"0.2.7"
Any other information that may be useful about versioning of dependent services should be returned here.
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.
Show child attributes
Show child attributes
All Operation.Status this implementation supports. Any status that is returned during parsing that is not listed here will cause client validation to error.
OperationStatus is utilized to indicate which Operation status are considered successful.
Show child attributes
Show child attributes
The status is the network-specific status of the operation.
An Operation is considered successful if the Operation.Amount should affect the Operation.Account. Some blockchains (like Bitcoin) only include successful operations in blocks but other blockchains (like Ethereum) include unsuccessful operations that incur a fee. To reconcile the computed balance from the stream of Operations, it is critical to understand which Operation.Status indicate an Operation is successful and should affect an Account.
{ "status": "SUCCESS", "successful": true }All Operation.Type this implementation supports. Any type that is returned during parsing that is not listed here will cause client validation to error.
"TRANSFER"
All Errors that this implementation could return. Any error that is returned during parsing that is not listed here will cause client validation to error.
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.
Show child attributes
Show child attributes
Code is a network-specific error code. If desired, this code can be equivalent to an HTTP status code.
x >= 012
Message is a network-specific error message. The message MUST NOT change for a given code. In particular, this means that any contextual information should be included in the details field.
"Invalid account format"
An error is retriable if the same request may succeed if submitted again.
Description allows the implementer to optionally provide additional information about an error. In many cases, the content of this field will be a copy-and-paste from existing developer documentation. Description can ONLY be populated with generic information about a particular type of error. It MUST NOT be populated with information about a particular instantiation of an error (use details for this). Whereas the content of Error.Message should stay stable across releases, the content of Error.Description will likely change across releases (as implementers improve error documentation). For this reason, the content in this field is not part of any type assertion (unlike Error.Message).
"This error is returned when the requested AccountIdentifier is improperly formatted."
Often times it is useful to return context specific to the request that caused the error (i.e. a sample of the stack trace or impacted account) in addition to the standard error message.
{
"address": "0x1dcc4de8dec75d7aab85b567b6",
"error": "not base64"
}Any Rosetta implementation that supports querying the balance of an account at any height in the past should set this to true.
All methods that are supported by the /call endpoint. Communicating which parameters should be provided to /call is the responsibility of the implementer (this is en lieu of defining an entire type system and requiring the implementer to define that in Allow).
"eth_call"
BalanceExemptions is an array of BalanceExemption indicating which account balances could change without a corresponding Operation. 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).
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).
Show child attributes
Show child attributes
SubAccountAddress is the SubAccountIdentifier.Address that the BalanceExemption applies to (regardless of the value of SubAccountIdentifier.Metadata).
"staking"
Currency is composed of a canonical Symbol and Decimals. This Decimals value is used to convert an Amount.Value from atomic units (Satoshis) to standard units (Bitcoins).
Show child attributes
Show child attributes
Canonical symbol associated with a currency.
"BTC"
Number of decimal places in the standard unit representation of the amount. For example, BTC has 8 decimals. Note that it is not possible to represent the value of some currency in atomic units that is not base 10.
x >= 08
Any additional information related to the currency itself. For example, it would be useful to populate this object with the contract address of an ERC-20 token.
{ "Issuer": "Satoshi" }ExemptionType is used to indicate if the live balance for an account subject to a BalanceExemption could increase above, decrease below, or equal the computed balance. * greater_or_equal: The live balance may increase above or equal the computed balance. This typically occurs with staking rewards that accrue on each block. * less_or_equal: The live balance may decrease below or equal the computed balance. This typically occurs as balance moves from locked to spendable on a vesting account. * dynamic: The live balance may increase above, decrease below, or equal the computed balance. This typically occurs with tokens that have a dynamic supply.
greater_or_equal, less_or_equal, dynamic Any Rosetta implementation that can update an AccountIdentifier's unspent coins based on the contents of the mempool should populate this field as true. If false, requests to /account/coins that set include_mempool as true will be automatically rejected.
If populated, timestamp_start_index indicates the first block index where block timestamps are considered valid (i.e. all blocks less than timestamp_start_index could have invalid timestamps). This is useful when the genesis block (or blocks) of a network have timestamp 0. If not populated, block timestamps are assumed to be valid for all available blocks.
x >= 0Was this page helpful?