Models

AccountBalanceRequest

An AccountBalanceRequest is utilized to make a balance request on the /account/balance endpoint. If the block_identifier is populated, a historical balance query should be performed.

Properties

NameTypeDescriptionRequired
network_identifierNetworkIdentifierThe network_identifier specifies which network a particular object is associated with.True
account_identifierAccountIdentifierThe account_identifier uniquely identifies an account within a network. All fields in the account_identifier are utilized to determine this uniqueness (including the metadata field, if populated).True
block_identifierPartialBlockIdentifierWhen 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.False
currencies[]CurrencyIn some cases, the caller may not want to retrieve all available balances for an AccountIdentifier. If the currencies field is populated, only balances for the specified currencies will be returned. If not populated, all available balances will be returned.False

Example

{
    "network_identifier": {
        "blockchain": "bitcoin",
        "network": "mainnet",
        "sub_network_identifier": {
            "network": "shard 1",
            "metadata": {
                "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
            }
        }
    },
    "account_identifier": {
        "address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
        "sub_account": {
            "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
            "metadata": {}
        },
        "metadata": {}
    },
    "block_identifier": {
        "index": 1123941,
        "hash": "0x1f2cc6c5027d2f201a5453ad1119574d2aed23a392654742ac3c78783c071f85"
    },
    "currencies": [
        {
            "symbol": "BTC",
            "decimals": 8,
            "metadata": {
                "Issuer": "Satoshi"
            }
        }
    ]
}

Full Reference

AccountBalanceResponse

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 coins field was removed and replaced by by /account/coins in v1.4.7.

Properties

NameTypeDescriptionRequired
block_identifierBlockIdentifierThe block_identifier uniquely identifies a block in a particular network.True
balances[]AmountA single account may have a balance in multiple currencies.True
metadataObjectAccount-based blockchains that utilize a nonce or sequence number should include that number in the metadata. This number could be unique to the identifier or global across the account address.False

Example

{
    "block_identifier": {
        "index": 1123941,
        "hash": "0x1f2cc6c5027d2f201a5453ad1119574d2aed23a392654742ac3c78783c071f85"
    },
    "balances": [
        {
            "value": "1238089899992",
            "currency": {
                "symbol": "BTC",
                "decimals": 8,
                "metadata": {
                    "Issuer": "Satoshi"
                }
            },
            "metadata": {}
        }
    ],
    "metadata": {
        "sequence_number": 23
    }
}

Full Reference

AccountCoinsRequest

AccountCoinsRequest is utilized to make a request on the /account/coins endpoint.

Properties

NameTypeDescriptionRequired
network_identifierNetworkIdentifierThe network_identifier specifies which network a particular object is associated with.True
account_identifierAccountIdentifierThe account_identifier uniquely identifies an account within a network. All fields in the account_identifier are utilized to determine this uniqueness (including the metadata field, if populated).True
include_mempoolBooleanInclude state from the mempool when looking up an account's unspent coins. Note, using this functionality breaks any guarantee of idempotency.True
currencies[]CurrencyIn some cases, the caller may not want to retrieve coins for all currencies for an AccountIdentifier. If the currencies field is populated, only coins for the specified currencies will be returned. If not populated, all unspent coins will be returned.False

Example

{
    "network_identifier": {
        "blockchain": "bitcoin",
        "network": "mainnet",
        "sub_network_identifier": {
            "network": "shard 1",
            "metadata": {
                "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
            }
        }
    },
    "account_identifier": {
        "address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
        "sub_account": {
            "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
            "metadata": {}
        },
        "metadata": {}
    },
    "include_mempool": true,
    "currencies": [
        {
            "symbol": "BTC",
            "decimals": 8,
            "metadata": {
                "Issuer": "Satoshi"
            }
        }
    ]
}

Full Reference

AccountCoinsResponse

AccountCoinsResponse is returned on the /account/coins endpoint and includes all unspent Coins owned by an AccountIdentifier.

Properties

NameTypeDescriptionRequired
block_identifierBlockIdentifierThe block_identifier uniquely identifies a block in a particular network.True
coins[]CoinIf a blockchain is UTXO-based, all unspent Coins owned by an account_identifier should be returned alongside the balance. It is highly recommended to populate this field so that users of the Rosetta API implementation don't need to maintain their own indexer to track their UTXOs.True
metadataObjectAccount-based blockchains that utilize a nonce or sequence number should include that number in the metadata. This number could be unique to the identifier or global across the account address.False

Example

{
    "block_identifier": {
        "index": 1123941,
        "hash": "0x1f2cc6c5027d2f201a5453ad1119574d2aed23a392654742ac3c78783c071f85"
    },
    "coins": [
        {
            "coin_identifier": {
                "identifier": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f:1"
            },
            "amount": {
                "value": "1238089899992",
                "currency": {
                    "symbol": "BTC",
                    "decimals": 8,
                    "metadata": {
                        "Issuer": "Satoshi"
                    }
                },
                "metadata": {}
            }
        }
    ],
    "metadata": {
        "sequence_number": 23
    }
}

Full Reference

AccountIdentifier

The account_identifier uniquely identifies an account within a network. All fields in the account_identifier are utilized to determine this uniqueness (including the metadata field, if populated).

Properties

NameTypeDescriptionRequired
addressStringThe address may be a cryptographic public key (or some encoding of it) or a provided username.True
sub_accountSubAccountIdentifierAn account may have state specific to a contract address (ERC-20 token) and/or a stake (delegated balance). The sub_account_identifier should specify which state (if applicable) an account instantiation refers to.False
metadataObjectBlockchains that utilize a username model (where the address is not a derivative of a cryptographic public key) should specify the public key(s) owned by the address in metadata.False

Example

{
    "address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
    "sub_account": {
        "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
        "metadata": {}
    },
    "metadata": {}
}

Full Reference

Allow

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.

Properties

NameTypeDescriptionRequired
operation_statuses[]OperationStatusAll Operation.Status this implementation supports. Any status that is returned during parsing that is not listed here will cause client validation to error.True
operation_types[]StringAll Operation.Type this implementation supports. Any type that is returned during parsing that is not listed here will cause client validation to error.True
errors[]ErrorAll Errors that this implementation could return. Any error that is returned during parsing that is not listed here will cause client validation to error.True
historical_balance_lookupBooleanAny Rosetta implementation that supports querying the balance of an account at any height in the past should set this to true.True
timestamp_start_indexInt64 (>= 0)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.False
call_methods[]StringAll 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).True
balance_exemptions[]BalanceExemptionBalanceExemptions 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).True
mempool_coinsBooleanAny 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.True

Example

{
    "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.",
            "retriable": true,
            "details": {
                "address": "0x1dcc4de8dec75d7aab85b567b6",
                "error": "not base64"
            }
        }
    ],
    "historical_balance_lookup": true,
    "timestamp_start_index": 0,
    "call_methods": [
        "eth_call"
    ],
    "balance_exemptions": [
        {
            "sub_account_address": "staking",
            "currency": {
                "symbol": "BTC",
                "decimals": 8,
                "metadata": {
                    "Issuer": "Satoshi"
                }
            },
            "exemption_type": "greater_or_equal"
        }
    ],
    "mempool_coins": true
}

Full Reference

Amount

Amount is some Value of a Currency. It is considered invalid to specify a Value without a Currency.

Properties

NameTypeDescriptionRequired
valueStringValue of the transaction in atomic units represented as an arbitrary-sized signed integer. For example, 1 BTC would be represented by a value of 100000000.True
currencyCurrencyCurrency 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).True
metadataObjectFalse

Example

{
    "value": "1238089899992",
    "currency": {
        "symbol": "BTC",
        "decimals": 8,
        "metadata": {
            "Issuer": "Satoshi"
        }
    },
    "metadata": {}
}

Full Reference

BalanceExemption

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).

Properties

NameTypeDescriptionRequired
sub_account_addressStringSubAccountAddress is the SubAccountIdentifier.Address that the BalanceExemption applies to (regardless of the value of SubAccountIdentifier.Metadata).False
currencyCurrencyCurrency 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).False
exemption_typeExemptionTypeExemptionType 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.False

Example

{
    "sub_account_address": "staking",
    "currency": {
        "symbol": "BTC",
        "decimals": 8,
        "metadata": {
            "Issuer": "Satoshi"
        }
    },
    "exemption_type": "greater_or_equal"
}

Full Reference

Block

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 inalterable: once a client has requested and received a block identified by a specific BlockIndentifier, all future calls for that same BlockIdentifier must return the same block contents.

Properties

NameTypeDescriptionRequired
block_identifierBlockIdentifierThe block_identifier uniquely identifies a block in a particular network.True
parent_block_identifierBlockIdentifierThe block_identifier uniquely identifies a block in a particular network.True
timestampInt64 (>=0)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.True
transactions[]TransactionTrue
metadataObjectFalse

Example

{
    "block_identifier": {
        "index": 1123941,
        "hash": "0x1f2cc6c5027d2f201a5453ad1119574d2aed23a392654742ac3c78783c071f85"
    },
    "parent_block_identifier": {
        "index": 1123941,
        "hash": "0x1f2cc6c5027d2f201a5453ad1119574d2aed23a392654742ac3c78783c071f85"
    },
    "timestamp": 1582833600000,
    "transactions": [
        {
            "transaction_identifier": {
                "hash": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f"
            },
            "operations": [
                {
                    "operation_identifier": {
                        "index": 5,
                        "network_index": 0
                    },
                    "related_operations": [
                        {
                            "index": 1
                        },
                        {
                            "index": 2
                        }
                    ],
                    "type": "Transfer",
                    "status": "Reverted",
                    "account": {
                        "address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
                        "sub_account": {
                            "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
                            "metadata": {}
                        },
                        "metadata": {}
                    },
                    "amount": {
                        "value": "1238089899992",
                        "currency": {
                            "symbol": "BTC",
                            "decimals": 8,
                            "metadata": {
                                "Issuer": "Satoshi"
                            }
                        },
                        "metadata": {}
                    },
                    "coin_change": {
                        "coin_identifier": {
                            "identifier": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f:1"
                        },
                        "coin_action": "coin_created"
                    },
                    "metadata": {
                        "asm": "304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd01 03301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2",
                        "hex": "48304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd012103301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2"
                    }
                }
            ],
            "related_transactions": [
                {
                    "network_identifier": {
                        "blockchain": "bitcoin",
                        "network": "mainnet",
                        "sub_network_identifier": {
                            "network": "shard 1",
                            "metadata": {
                                "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
                            }
                        }
                    },
                    "transaction_identifier": {
                        "hash": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f"
                    },
                    "direction": "forward"
                }
            ],
            "metadata": {
                "size": 12378,
                "lockTime": 1582272577
            }
        }
    ],
    "metadata": {
        "transactions_root": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
        "difficulty": "123891724987128947"
    }
}

Full Reference

BlockEvent

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.

Properties

NameTypeDescriptionRequired
sequenceInt64 (>= 0)sequence is the unique identifier of a BlockEvent within the context of a NetworkIdentifier.True
block_identifierBlockIdentifierThe block_identifier uniquely identifies a block in a particular network.True
typeBlockEventTypeBlockEventType determines if a BlockEvent represents the addition or removal of a block.True

Example

{
    "sequence": 5,
    "block_identifier": {
        "index": 1123941,
        "hash": "0x1f2cc6c5027d2f201a5453ad1119574d2aed23a392654742ac3c78783c071f85"
    },
    "type": "block_added"
}

Full Reference

BlockEventType

BlockEventType determines if a BlockEvent represents the addition or removal of a block.

Properties

NameDescription
block_addedA block was added to the canonical chain.
block_removedA block was removed from the canonical chain in a reorg.

Example

"block_added"

Full Reference

BlockIdentifier

The block_identifier uniquely identifies a block in a particular network.

Properties

NameTypeDescriptionRequired
indexInt64 (>= 0)This is also known as the block height.True
hashStringTrue

Example

{
    "index": 1123941,
    "hash": "0x1f2cc6c5027d2f201a5453ad1119574d2aed23a392654742ac3c78783c071f85"
}

Full Reference

BlockRequest

A BlockRequest is utilized to make a block request on the /block endpoint.

Properties

NameTypeDescriptionRequired
network_identifierNetworkIdentifierThe network_identifier specifies which network a particular object is associated with.True
block_identifierPartialBlockIdentifierWhen 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.True

Example

{
    "network_identifier": {
        "blockchain": "bitcoin",
        "network": "mainnet",
        "sub_network_identifier": {
            "network": "shard 1",
            "metadata": {
                "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
            }
        }
    },
    "block_identifier": {
        "index": 1123941,
        "hash": "0x1f2cc6c5027d2f201a5453ad1119574d2aed23a392654742ac3c78783c071f85"
    }
}

Full Reference

BlockResponse

A BlockResponse includes a fully-populated block or a partially-populated block with a list of other transactions to fetch (other_transactions). As a result of the consensus algorithm of some blockchains, blocks can be omitted (i.e. certain block indices can be skipped). If a query for one of these omitted indices 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.

Properties

NameTypeDescriptionRequired
blockBlockBlocks 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 inalterable: once a client has requested and received a block identified by a specific BlockIndentifier, all future calls for that same BlockIdentifier must return the same block contents.False
other_transactions[]TransactionIdentifierSome blockchains may require additional transactions to be fetched that weren't returned in the block response (ex: block only returns transaction hashes). For blockchains with a lot of transactions in each block, this can be very useful as consumers can concurrently fetch all transactions returned.False

Example

{
    "block": {
        "block_identifier": {
            "index": 1123941,
            "hash": "0x1f2cc6c5027d2f201a5453ad1119574d2aed23a392654742ac3c78783c071f85"
        },
        "parent_block_identifier": {
            "index": 1123941,
            "hash": "0x1f2cc6c5027d2f201a5453ad1119574d2aed23a392654742ac3c78783c071f85"
        },
        "timestamp": 1582833600000,
        "transactions": [
            {
                "transaction_identifier": {
                    "hash": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f"
                },
                "operations": [
                    {
                        "operation_identifier": {
                            "index": 5,
                            "network_index": 0
                        },
                        "related_operations": [
                            {
                                "index": 1
                            },
                            {
                                "index": 2
                            }
                        ],
                        "type": "Transfer",
                        "status": "Reverted",
                        "account": {
                            "address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
                            "sub_account": {
                                "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
                                "metadata": {}
                            },
                            "metadata": {}
                        },
                        "amount": {
                            "value": "1238089899992",
                            "currency": {
                                "symbol": "BTC",
                                "decimals": 8,
                                "metadata": {
                                    "Issuer": "Satoshi"
                                }
                            },
                            "metadata": {}
                        },
                        "coin_change": {
                            "coin_identifier": {
                                "identifier": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f:1"
                            },
                            "coin_action": "coin_created"
                        },
                        "metadata": {
                            "asm": "304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd01 03301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2",
                            "hex": "48304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd012103301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2"
                        }
                    }
                ],
                "related_transactions": [
                    {
                        "network_identifier": {
                            "blockchain": "bitcoin",
                            "network": "mainnet",
                            "sub_network_identifier": {
                                "network": "shard 1",
                                "metadata": {
                                    "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
                                }
                            }
                        },
                        "transaction_identifier": {
                            "hash": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f"
                        },
                        "direction": "forward"
                    }
                ],
                "metadata": {
                    "size": 12378,
                    "lockTime": 1582272577
                }
            }
        ],
        "metadata": {
            "transactions_root": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
            "difficulty": "123891724987128947"
        }
    },
    "other_transactions": [
        {
            "hash": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f"
        }
    ]
}

Full Reference

BlockTransaction

BlockTransaction contains a populated Transaction and the BlockIdentifier that contains it.

Properties

NameTypeDescriptionRequired
block_identifierBlockIdentifierThe block_identifier uniquely identifies a block in a particular network.True
transactionTransactionTransactions contain an array of Operations that are attributable to the same TransactionIdentifier.True

Example

{
    "block_identifier": {
        "index": 1123941,
        "hash": "0x1f2cc6c5027d2f201a5453ad1119574d2aed23a392654742ac3c78783c071f85"
    },
    "transaction": {
        "transaction_identifier": {
            "hash": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f"
        },
        "operations": [
            {
                "operation_identifier": {
                    "index": 5,
                    "network_index": 0
                },
                "related_operations": [
                    {
                        "index": 1
                    },
                    {
                        "index": 2
                    }
                ],
                "type": "Transfer",
                "status": "Reverted",
                "account": {
                    "address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
                    "sub_account": {
                        "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
                        "metadata": {}
                    },
                    "metadata": {}
                },
                "amount": {
                    "value": "1238089899992",
                    "currency": {
                        "symbol": "BTC",
                        "decimals": 8,
                        "metadata": {
                            "Issuer": "Satoshi"
                        }
                    },
                    "metadata": {}
                },
                "coin_change": {
                    "coin_identifier": {
                        "identifier": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f:1"
                    },
                    "coin_action": "coin_created"
                },
                "metadata": {
                    "asm": "304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd01 03301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2",
                    "hex": "48304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd012103301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2"
                }
            }
        ],
        "related_transactions": [
            {
                "network_identifier": {
                    "blockchain": "bitcoin",
                    "network": "mainnet",
                    "sub_network_identifier": {
                        "network": "shard 1",
                        "metadata": {
                            "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
                        }
                    }
                },
                "transaction_identifier": {
                    "hash": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f"
                },
                "direction": "forward"
            }
        ],
        "metadata": {
            "size": 12378,
            "lockTime": 1582272577
        }
    }
}

Full Reference

BlockTransactionRequest

A BlockTransactionRequest is used to fetch a Transaction included in a block that is not returned in a BlockResponse.

Properties

NameTypeDescriptionRequired
network_identifierNetworkIdentifierThe network_identifier specifies which network a particular object is associated with.True
block_identifierBlockIdentifierThe block_identifier uniquely identifies a block in a particular network.True
transaction_identifierTransactionIdentifierThe transaction_identifier uniquely identifies a transaction in a particular network and block or in the mempool.True

Example

{
    "network_identifier": {
        "blockchain": "bitcoin",
        "network": "mainnet",
        "sub_network_identifier": {
            "network": "shard 1",
            "metadata": {
                "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
            }
        }
    },
    "block_identifier": {
        "index": 1123941,
        "hash": "0x1f2cc6c5027d2f201a5453ad1119574d2aed23a392654742ac3c78783c071f85"
    },
    "transaction_identifier": {
        "hash": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f"
    }
}

Related Articles

[Community] block_identifier parameter as required parameter

Full Reference

BlockTransactionResponse

A BlockTransactionResponse contains information about a block transaction.

Properties

NameTypeDescriptionRequired
transactionTransactionTransactions contain an array of Operations that are attributable to the same TransactionIdentifier.True

Example

{
    "transaction": {
        "transaction_identifier": {
            "hash": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f"
        },
        "operations": [
            {
                "operation_identifier": {
                    "index": 5,
                    "network_index": 0
                },
                "related_operations": [
                    {
                        "index": 1
                    },
                    {
                        "index": 2
                    }
                ],
                "type": "Transfer",
                "status": "Reverted",
                "account": {
                    "address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
                    "sub_account": {
                        "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
                        "metadata": {}
                    },
                    "metadata": {}
                },
                "amount": {
                    "value": "1238089899992",
                    "currency": {
                        "symbol": "BTC",
                        "decimals": 8,
                        "metadata": {
                            "Issuer": "Satoshi"
                        }
                    },
                    "metadata": {}
                },
                "coin_change": {
                    "coin_identifier": {
                        "identifier": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f:1"
                    },
                    "coin_action": "coin_created"
                },
                "metadata": {
                    "asm": "304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd01 03301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2",
                    "hex": "48304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd012103301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2"
                }
            }
        ],
        "related_transactions": [
            {
                "network_identifier": {
                    "blockchain": "bitcoin",
                    "network": "mainnet",
                    "sub_network_identifier": {
                        "network": "shard 1",
                        "metadata": {
                            "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
                        }
                    }
                },
                "transaction_identifier": {
                    "hash": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f"
                },
                "direction": "forward"
            }
        ],
        "metadata": {
            "size": 12378,
            "lockTime": 1582272577
        }
    }
}

Full Reference

CallRequest

CallRequest is the input to the /call endpoint.

Properties

NameTypeDescriptionRequired
network_identifierNetworkIdentifierThe network_identifier specifies which network a particular object is associated with.True
methodStringMethod is some network-specific procedure call. This method could map to a network-specific RPC endpoint, a method in an SDK generated from a smart contract, or some hybrid of the two. The implementation must define all available methods in the Allow object. However, it is up to the caller to determine which parameters to provide when invoking /call.True
parametersObjectParameters is some network-specific argument for a method. It is up to the caller to determine which parameters to provide when invoking /call.True

Example

{
    "network_identifier": {
        "blockchain": "bitcoin",
        "network": "mainnet",
        "sub_network_identifier": {
            "network": "shard 1",
            "metadata": {
                "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
            }
        }
    },
    "method": "eth_call",
    "parameters": {
        "block_number": 23,
        "address": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
    }
}

Full Reference

CallResponse

CallResponse contains the result of a /call invocation.

Properties

NameTypeDescriptionRequired
resultObjectResult contains the result of the /call invocation. This result will not be inspected or interpreted by Rosetta tooling and is left to the caller to decode.True
idempotentBooleanIdempotent indicates that if /call is invoked with the same CallRequest again, at any point in time, it will return the same CallResponse. Integrators may cache the CallResponse if this is set to true to avoid making unnecessary calls to the Rosetta implementation. For this reason, implementers should be very conservative about returning true here or they could cause issues for the caller.True

Example

{
    "result": {
        "count": 1000
    },
    "idempotent": true
}

Full Reference

Coin

Coin contains its unique identifier and the amount it represents.

Properties

NameTypeDescriptionRequired
coin_identifierCoinIdentifierCoinIdentifier uniquely identifies a Coin.True
amountAmountAmount is some Value of a Currency. It is considered invalid to specify a Value without a Currency.True

Example

{
    "coin_identifier": {
        "identifier": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f:1"
    },
    "amount": {
        "value": "1238089899992",
        "currency": {
            "symbol": "BTC",
            "decimals": 8,
            "metadata": {
                "Issuer": "Satoshi"
            }
        },
        "metadata": {}
    }
}

Full Reference

CoinAction

CoinActions are different state changes that a Coin can undergo. It is assumed that a single Coin cannot be created or spent more than once.

Properties

Type: enum (string)

Values

NameDescription
coin_createdCoinAction indicating a Coin was created.
coin_spentCoinAction indicating a Coin was spent.

Example

"coin_created"

Full Reference

CoinChange

CoinChange is used to represent a change in state of a some coin identified by a coin_identifier. 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 populate this model).

Properties

NameTypeDescriptionRequired
coin_identifierCoinIdentifierCoinIdentifier uniquely identifies a Coin.True
coin_actionCoinActionCoinActions are different state changes that a Coin can undergo. When a Coin is created, it is coin_created. When a Coin is spent, it is coin_spent. It is assumed that a single Coin cannot be created or spent more than once.True

Example

{
    "coin_identifier": {
        "identifier": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f:1"
    },
    "coin_action": "coin_created"
}

Full Reference

CoinIdentifier

CoinIdentifier uniquely identifies a Coin.

Properties

NameTypeDescriptionRequired
identifierStringIdentifier should be populated with a globally unique identifier of a Coin. In Bitcoin, this identifier would be transaction_hash:index.True

Example

{
    "identifier": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f:1"
}

Full Reference

ConstructionCombineRequest

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.

Properties

NameTypeDescriptionRequired
network_identifierNetworkIdentifierThe network_identifier specifies which network a particular object is associated with.True
unsigned_transactionStringTrue
signatures[]SignatureTrue

Example

{
    "network_identifier": {
        "blockchain": "bitcoin",
        "network": "mainnet",
        "sub_network_identifier": {
            "network": "shard 1",
            "metadata": {
                "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
            }
        }
    },
    "unsigned_transaction": "string",
    "signatures": [
        {
            "signing_payload": {
                "address": "string",
                "account_identifier": {
                    "address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
                    "sub_account": {
                        "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
                        "metadata": {}
                    },
                    "metadata": {}
                },
                "hex_bytes": "string",
                "signature_type": "ecdsa"
            },
            "public_key": {
                "hex_bytes": "string",
                "curve_type": "secp256k1"
            },
            "signature_type": "ecdsa",
            "hex_bytes": "string"
        }
    ]
}

Full Reference

ConstructionCombineResponse

ConstructionCombineResponse is returned by /construction/combine. The network payload will be sent directly to the construction/submit endpoint.

Properties

NameTypeDescriptionRequired
signed_transactionStringTrue

Example

{
    "signed_transaction": "string"
}

Full Reference

ConstructionDeriveRequest

ConstructionDeriveRequest is 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).

Properties

NameTypeDescriptionRequired
network_identifierNetworkIdentifierThe network_identifier specifies which network a particular object is associated with.True
public_keyPublicKeyPublicKey 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.True
metadataObjectFalse

Example

{
    "network_identifier": {
        "blockchain": "bitcoin",
        "network": "mainnet",
        "sub_network_identifier": {
            "network": "shard 1",
            "metadata": {
                "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
            }
        }
    },
    "public_key": {
        "hex_bytes": "string",
        "curve_type": "secp256k1"
    },
    "metadata": {}
}

Full Reference

ConstructionDeriveResponse

ConstructionDeriveResponse is returned by the /construction/derive endpoint.

Properties

NameTypeDescriptionRequired
addressString[DEPRECATED by account_identifier in v1.4.4] Address in network-specific format.False
account_identifierAccountIdentifierThe account_identifier uniquely identifies an account within a network. All fields in the account_identifier are utilized to determine this uniqueness (including the metadata field, if populated).False
metadataObjectFalse

Example

{
    "address": "string",
    "account_identifier": {
        "address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
        "sub_account": {
            "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
            "metadata": {}
        },
        "metadata": {}
    },
    "metadata": {}
}

Full Reference

ConstructionHashRequest

ConstructionHashRequest is the input to the /construction/hash endpoint.

Properties

NameTypeDescriptionRequired
network_identifierNetworkIdentifierThe network_identifier specifies which network a particular object is associated with.True
signed_transactionStringTrue

Example

{
    "network_identifier": {
        "blockchain": "bitcoin",
        "network": "mainnet",
        "sub_network_identifier": {
            "network": "shard 1",
            "metadata": {
                "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
            }
        }
    },
    "signed_transaction": "string"
}

Full Reference

ConstructionMetadataRequest

A ConstructionMetadataRequest is 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 PublicKeys associated with the AccountIdentifiers returned in ConstructionPreprocessResponse.

Properties

NameTypeDescriptionRequired
network_identifierNetworkIdentifierThe network_identifier specifies which network a particular object is associated with.True
optionsObjectSome blockchains require different metadata for different types of transaction construction (ex: delegation versus a transfer). Instead of requiring a blockchain node to return all possible types of metadata for construction (which may require multiple node fetches), the client can populate an options object to limit the metadata returned to only the subset required.False
public_keys[]PublicKeyFalse

Example

{
    "network_identifier": {
        "blockchain": "bitcoin",
        "network": "mainnet",
        "sub_network_identifier": {
            "network": "shard 1",
            "metadata": {
                "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
            }
        }
    },
    "options": {},
    "public_keys": [
        {
            "hex_bytes": "string",
            "curve_type": "secp256k1"
        }
    ]
}

Full Reference

ConstructionMetadataResponse

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.

Properties

NameTypeDescriptionRequired
metadataObjectTrue
suggested_fee[]AmountFalse

Example

{
    "metadata": {
        "account_sequence": 23,
        "recent_block_hash": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
    },
    "suggested_fee": [
        {
            "value": "1238089899992",
            "currency": {
                "symbol": "BTC",
                "decimals": 8,
                "metadata": {
                    "Issuer": "Satoshi"
                }
            },
            "metadata": {}
        }
    ]
}

Full Reference

ConstructionParseRequest

ConstructionParseRequest is the input to the /construction/parse endpoint. It allows the caller to parse either an unsigned or signed transaction.

Properties

NameTypeDescriptionRequired
network_identifierNetworkIdentifierThe network_identifier specifies which network a particular object is associated with.True
signedBooleanSigned is a boolean indicating whether the transaction is signed.True
transactionStringThis must be either the unsigned transaction blob returned by /construction/payloads or the signed transaction blob returned by /construction/combine.True

Example

{
    "network_identifier": {
        "blockchain": "bitcoin",
        "network": "mainnet",
        "sub_network_identifier": {
            "network": "shard 1",
            "metadata": {
                "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
            }
        }
    },
    "signed": true,
    "transaction": "string"
}

Full Reference

ConstructionParseResponse

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.

Properties

NameTypeDescriptionRequired
operations[]OperationTrue
signers[]String[DEPRECATED by account_identifier_signers in v1.4.4] All signers (addresses) of a particular transaction. If the transaction is unsigned, it should be empty.False
account_identifier_signers[]AccountIdentifierFalse
metadataObjectFalse

Example

{
    "operations": [
        {
            "operation_identifier": {
                "index": 5,
                "network_index": 0
            },
            "related_operations": [
                {
                    "index": 1
                },
                {
                    "index": 2
                }
            ],
            "type": "Transfer",
            "status": "Reverted",
            "account": {
                "address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
                "sub_account": {
                    "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
                    "metadata": {}
                },
                "metadata": {}
            },
            "amount": {
                "value": "1238089899992",
                "currency": {
                    "symbol": "BTC",
                    "decimals": 8,
                    "metadata": {
                        "Issuer": "Satoshi"
                    }
                },
                "metadata": {}
            },
            "coin_change": {
                "coin_identifier": {
                    "identifier": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f:1"
                },
                "coin_action": "coin_created"
            },
            "metadata": {
                "asm": "304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd01 03301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2",
                "hex": "48304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd012103301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2"
            }
        }
    ],
    "signers": [
        "string"
    ],
    "account_identifier_signers": [
        {
            "address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
            "sub_account": {
                "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
                "metadata": {}
            },
            "metadata": {}
        }
    ],
    "metadata": {}
}

Full Reference

ConstructionPayloadsRequest

ConstructionPayloadsRequest is the request to /construction/payloads. It contains the network, a slice of operations, and arbitrary metadata that was returned by the call to /construction/metadata. Optionally, the request can also include an array of PublicKeys associated with the AccountIdentifiers returned in ConstructionPreprocessResponse.

Properties

NameTypeDescriptionRequired
network_identifierNetworkIdentifierThe network_identifier specifies which network a particular object is associated with.True
operations[]OperationTrue
metadataObjectFalse
public_keys[]PublicKeyFalse

Example

{
    "network_identifier": {
        "blockchain": "bitcoin",
        "network": "mainnet",
        "sub_network_identifier": {
            "network": "shard 1",
            "metadata": {
                "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
            }
        }
    },
    "operations": [
        {
            "operation_identifier": {
                "index": 5,
                "network_index": 0
            },
            "related_operations": [
                {
                    "index": 1
                },
                {
                    "index": 2
                }
            ],
            "type": "Transfer",
            "status": "Reverted",
            "account": {
                "address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
                "sub_account": {
                    "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
                    "metadata": {}
                },
                "metadata": {}
            },
            "amount": {
                "value": "1238089899992",
                "currency": {
                    "symbol": "BTC",
                    "decimals": 8,
                    "metadata": {
                        "Issuer": "Satoshi"
                    }
                },
                "metadata": {}
            },
            "coin_change": {
                "coin_identifier": {
                    "identifier": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f:1"
                },
                "coin_action": "coin_created"
            },
            "metadata": {
                "asm": "304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd01 03301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2",
                "hex": "48304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd012103301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2"
            }
        }
    ],
    "metadata": {},
    "public_keys": [
        {
            "hex_bytes": "string",
            "curve_type": "secp256k1"
        }
    ]
}

Full Reference

ConstructionPayloadsResponse

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.

Properties

NameTypeDescriptionRequired
unsigned_transactionStringTrue
payloads[]SigningPayloadTrue

Example

{
    "unsigned_transaction": "string",
    "payloads": [
        {
            "address": "string",
            "account_identifier": {
                "address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
                "sub_account": {
                    "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
                    "metadata": {}
                },
                "metadata": {}
            },
            "hex_bytes": "string",
            "signature_type": "ecdsa"
        }
    ]
}

Full Reference

ConstructionPreprocessRequest

ConstructionPreprocessRequest is 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). If live data is required for construction, it MUST be fetched in the call to /construction/metadata. The caller can provide a max fee they are willing to pay for a transaction. This is an array in the case fees must be paid in multiple currencies. The caller can also provide a suggested fee multiplier to indicate that the suggested fee should be scaled. This may be used to set higher fees for urgent transactions or to pay lower fees when there is less urgency. It is assumed that providing a very low multiplier (like 0.0001) will never lead to a transaction being created with a fee less than the minimum network fee (if applicable). In the case that the caller provides both a max fee and a suggested fee multiplier, the max fee will set an upper bound on the suggested fee (regardless of the multiplier provided).

Properties

NameTypeDescriptionRequired
network_identifierNetworkIdentifierThe network_identifier specifies which network a particular object is associated with.True
operations[]OperationTrue
metadataObjectFalse
max_fee[]AmountFalse
suggested_fee_multiplierDoubleFalse

Example

{
    "network_identifier": {
        "blockchain": "bitcoin",
        "network": "mainnet",
        "sub_network_identifier": {
            "network": "shard 1",
            "metadata": {
                "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
            }
        }
    },
    "operations": [
        {
            "operation_identifier": {
                "index": 5,
                "network_index": 0
            },
            "related_operations": [
                {
                    "index": 1
                },
                {
                    "index": 2
                }
            ],
            "type": "Transfer",
            "status": "Reverted",
            "account": {
                "address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
                "sub_account": {
                    "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
                    "metadata": {}
                },
                "metadata": {}
            },
            "amount": {
                "value": "1238089899992",
                "currency": {
                    "symbol": "BTC",
                    "decimals": 8,
                    "metadata": {
                        "Issuer": "Satoshi"
                    }
                },
                "metadata": {}
            },
            "coin_change": {
                "coin_identifier": {
                    "identifier": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f:1"
                },
                "coin_action": "coin_created"
            },
            "metadata": {
                "asm": "304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd01 03301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2",
                "hex": "48304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd012103301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2"
            }
        }
    ],
    "metadata": {},
    "max_fee": [
        {
            "value": "1238089899992",
            "currency": {
                "symbol": "BTC",
                "decimals": 8,
                "metadata": {
                    "Issuer": "Satoshi"
                }
            },
            "metadata": {}
        }
    ],
    "suggested_fee_multiplier": 0
}

Full Reference

ConstructionPreprocessResponse

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. Some blockchains require the PublicKey of particular AccountIdentifiers to construct a valid transaction. To fetch these PublicKeys, populate required_public_keys with the AccountIdentifiers associated with the desired PublicKeys. If it is not necessary to retrieve any PublicKeys for construction, required_public_keys should be omitted.

Properties

NameTypeDescriptionRequired
optionsObjectThe options that will be sent directly to /construction/metadata by the caller.False
required_public_keys[]AccountIdentifierFalse

Example

{
    "options": {},
    "required_public_keys": [
        {
            "address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
            "sub_account": {
                "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
                "metadata": {}
            },
            "metadata": {}
        }
    ]
}

Full Reference

ConstructionSubmitRequest

The transaction submission request includes a signed transaction.

Properties

NameTypeDescriptionRequired
network_identifierNetworkIdentifierThe network_identifier specifies which network a particular object is associated with.True
signed_transactionStringTrue

Example

{
    "network_identifier": {
        "blockchain": "bitcoin",
        "network": "mainnet",
        "sub_network_identifier": {
            "network": "shard 1",
            "metadata": {
                "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
            }
        }
    },
    "signed_transaction": "string"
}

Full Reference

Currency

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).

Properties

NameTypeDescriptionRequired
symbolStringCanonical symbol associated with a currency.True
decimalsInt (>= 0)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.True
metadataObjectAny 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.False

Example

{
    "symbol": "BTC",
    "decimals": 8,
    "metadata": {
        "Issuer": "Satoshi"
    }
}

Full Reference

CurveType

CurveType is the type of cryptographic curve associated with a PublicKey.

Properties

Type: enum (string)

Values

NameFormatSizeDescription
secp256k1SEC Compressed33 byteshttps://secg.org/sec1-v2.pdf#subsubsection.2.3.3
secp256r1SEC compressed33 byteshttps://secg.org/sec1-v2.pdf#subsubsection.2.3.3
edwards25519y (255-bits) + x-sign-bit (1-bit)32 byteshttps://ed25519.cr.yp.to/ed25519-20110926.pdf
tweedle1st pk : Fq.t (32 bytes) + 2nd pk : Fq.t (32 bytes)64 byteshttps://github.com/CodaProtocol/coda/blob/develop/rfcs/0038-rosetta-construction-api.md#marshal-keys

Example

"secp256k1"

Full Reference

Direction

Used by RelatedTransaction to indicate the direction of the relation (i.e. cross-shard/cross-network sends may reference backward to an earlier transaction and async execution may reference forward). Can be used to indicate if a transaction relation is from child to parent or the reverse.

Properties

Type: enum (string)

Values

NameDescription
forwardDirection indicating a transaction relation is from parent to child.
backwardDirection indicating a transaction relation is from child to parent.

Example

"forward"

Full Reference

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.

Properties

NameTypeDescriptionRequired
codeInt (>= 0)Code is a network-specific error code. If desired, this code can be equivalent to an HTTP status code.True
messageStringMessage 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.True
descriptionStringDescription 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).False
retriableBooleanAn error is retriable if the same request may succeed if submitted again.True
detailsObjectOften 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.False

Example

{
    "code": 12,
    "message": "Invalid account format",
    "description": "This error is returned when the requested AccountIdentifier is improperly formatted.",
    "retriable": true,
    "details": {
        "address": "0x1dcc4de8dec75d7aab85b567b6",
        "error": "not base64"
    }
}

Full Reference

EventsBlocksRequest

EventsBlocksRequest is utilized to fetch a sequence of BlockEvents indicating which blocks were added and removed from storage to reach the current state.

Properties

NameTypeDescriptionRequired
network_identifierNetworkIdentifierThe network_identifier specifies which network a particular object is associated with.True
offsetInt64 (>= 0)offset is the offset into the event stream to sync events from. If this field is not populated, we return the limit events backwards from tip. If this is set to 0, we start from the beginning.False
limitInt64 (>= 0)limit is the maximum number of events to fetch in one call. The implementation may return "= limit events.False

Example

{
    "network_identifier": {
        "blockchain": "bitcoin",
        "network": "mainnet",
        "sub_network_identifier": {
            "network": "shard 1",
            "metadata": {
                "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
            }
        }
    },
    "offset": 5,
    "limit": 5
}

Full Reference

EventsBlocksResponse

EventsBlocksResponse contains an ordered collection of BlockEvents and the max retrievable sequence.

Properties

NameTypeDescriptionRequired
max_sequenceInt64 (>= 0)max_sequence is the maximum available sequence number to fetch.True
events[]BlockEventevents is an array of BlockEvents indicating the order to add and remove blocks to maintain a canonical view of blockchain state. Lightweight clients can use this event stream to update state without implementing their own block syncing logic.True

Example

{
    "max_sequence": 5,
    "events": [
        {
            "sequence": 5,
            "block_identifier": {
                "index": 1123941,
                "hash": "0x1f2cc6c5027d2f201a5453ad1119574d2aed23a392654742ac3c78783c071f85"
            },
            "type": "block_added"
        }
    ]
}

Full Reference

ExemptionType

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.

Properties

NameDescription
greater_or_equalThe live balance may increase above or equal the computed balance. This typically occurs with staking rewards that accrue on each block.
less_or_equalThe live balance may decrease below or equal the computed balance. This typically occurs as balance moves from locked to spendable on a vesting account.
dynamicThe live balance may increase above, decrease below, or equal the computed balance. This typically occurs with tokens that have a dynamic supply.

Example

"greater_or_equal"

Full Reference

MempoolResponse

A MempoolResponse contains all transaction identifiers in the mempool for a particular network_identifier.

Properties

NameTypeDescriptionRequired
transaction_identifiers[]TransactionIdentifierTrue

Example

{
    "transaction_identifiers": [
        {
            "hash": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f"
        }
    ]
}

Full Reference

MempoolTransactionRequest

A MempoolTransactionRequest is utilized to retrieve a transaction from the mempool.

Properties

NameTypeDescriptionRequired
network_identifierNetworkIdentifierThe network_identifier specifies which network a particular object is associated with.True
transaction_identifierTransactionIdentifierThe transaction_identifier uniquely identifies a transaction in a particular network and block or in the mempool.True

Example

{
    "network_identifier": {
        "blockchain": "bitcoin",
        "network": "mainnet",
        "sub_network_identifier": {
            "network": "shard 1",
            "metadata": {
                "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
            }
        }
    },
    "transaction_identifier": {
        "hash": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f"
    }
}

Full Reference

MempoolTransactionResponse

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).

Properties

NameTypeDescriptionRequired
transactionTransactionTransactions contain an array of Operations that are attributable to the same TransactionIdentifier.True
metadataObjectFalse

Example

{
    "transaction": {
        "transaction_identifier": {
            "hash": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f"
        },
        "operations": [
            {
                "operation_identifier": {
                    "index": 5,
                    "network_index": 0
                },
                "related_operations": [
                    {
                        "index": 1
                    },
                    {
                        "index": 2
                    }
                ],
                "type": "Transfer",
                "status": "Reverted",
                "account": {
                    "address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
                    "sub_account": {
                        "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
                        "metadata": {}
                    },
                    "metadata": {}
                },
                "amount": {
                    "value": "1238089899992",
                    "currency": {
                        "symbol": "BTC",
                        "decimals": 8,
                        "metadata": {
                            "Issuer": "Satoshi"
                        }
                    },
                    "metadata": {}
                },
                "coin_change": {
                    "coin_identifier": {
                        "identifier": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f:1"
                    },
                    "coin_action": "coin_created"
                },
                "metadata": {
                    "asm": "304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd01 03301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2",
                    "hex": "48304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd012103301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2"
                }
            }
        ],
        "related_transactions": [
            {
                "network_identifier": {
                    "blockchain": "bitcoin",
                    "network": "mainnet",
                    "sub_network_identifier": {
                        "network": "shard 1",
                        "metadata": {
                            "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
                        }
                    }
                },
                "transaction_identifier": {
                    "hash": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f"
                },
                "direction": "forward"
            }
        ],
        "metadata": {
            "size": 12378,
            "lockTime": 1582272577
        }
    },
    "metadata": {
        "descendant_fees": 123923,
        "ancestor_count": 2
    }
}

Full Reference

MetadataRequest

A MetadataRequest is utilized in any request where the only argument is optional metadata.

Properties

NameTypeDescriptionRequired
metadataObjectFalse

Example

{
    "metadata": {}
}

Full Reference

NetworkIdentifier

The network_identifier specifies which network a particular object is associated with.

Properties

NameTypeDescriptionRequired
blockchainStringTrue
networkStringIf 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.True
sub_network_identifierSubNetworkIdentifierIn 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.False

Example

{
    "blockchain": "bitcoin",
    "network": "mainnet",
    "sub_network_identifier": {
        "network": "shard 1",
        "metadata": {
            "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
        }
    }
}

Full Reference

NetworkListResponse

A NetworkListResponse contains all NetworkIdentifiers that the node can serve information for.

Properties

NameTypeDescriptionRequired
network_identifiers[]NetworkIdentifierTrue

Example

{
    "network_identifiers": [
        {
            "blockchain": "bitcoin",
            "network": "mainnet",
            "sub_network_identifier": {
                "network": "shard 1",
                "metadata": {
                    "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
                }
            }
        }
    ]
}

Full Reference

NetworkOptionsResponse

NetworkOptionsResponse contains information about the versioning of the node and the allowed operation statuses, operation types, and errors.

Properties

NameTypeDescriptionRequired
versionVersionThe Version object is utilized to inform the client of the versions of different components of the Rosetta implementation.True
allowAllowAllow 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.True

Example

{
    "version": {
        "rosetta_version": "1.2.5",
        "node_version": "1.0.2",
        "middleware_version": "0.2.7",
        "metadata": {}
    },
    "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.",
                "retriable": true,
                "details": {
                    "address": "0x1dcc4de8dec75d7aab85b567b6",
                    "error": "not base64"
                }
            }
        ],
        "historical_balance_lookup": true,
        "timestamp_start_index": 0,
        "call_methods": [
            "eth_call"
        ],
        "balance_exemptions": [
            {
                "sub_account_address": "staking",
                "currency": {
                    "symbol": "BTC",
                    "decimals": 8,
                    "metadata": {
                        "Issuer": "Satoshi"
                    }
                },
                "exemption_type": "greater_or_equal"
            }
        ],
        "mempool_coins": true
    }
}

Full Reference

NetworkRequest

A NetworkRequest is utilized to retrieve some data specific exclusively to a NetworkIdentifier.

Properties

NameTypeDescriptionRequired
network_identifierNetworkIdentifierThe network_identifier specifies which network a particular object is associated with.True
metadataObjectFalse

Example

{
    "network_identifier": {
        "blockchain": "bitcoin",
        "network": "mainnet",
        "sub_network_identifier": {
            "network": "shard 1",
            "metadata": {
                "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
            }
        }
    },
    "metadata": {}
}

Full Reference

NetworkStatusResponse

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.

Properties

NameTypeDescriptionRequired
current_block_identifierBlockIdentifierThe block_identifier uniquely identifies a block in a particular network.True
current_block_timestampInt64 (>=0)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.True
genesis_block_identifierBlockIdentifierThe block_identifier uniquely identifies a block in a particular network.True
oldest_block_identifierBlockIdentifierThe block_identifier uniquely identifies a block in a particular network.False
sync_statusSyncStatusSyncStatus is used to provide additional context about an implementation's sync status. This object is often used by implementations to indicate healthiness when block data cannot be queried until some sync phase completes or cannot be determined by comparing the timestamp of the most recent block with the current time.False
peers[]PeerTrue

Example

{
    "current_block_identifier": {
        "index": 1123941,
        "hash": "0x1f2cc6c5027d2f201a5453ad1119574d2aed23a392654742ac3c78783c071f85"
    },
    "current_block_timestamp": 1582833600000,
    "genesis_block_identifier": {
        "index": 1123941,
        "hash": "0x1f2cc6c5027d2f201a5453ad1119574d2aed23a392654742ac3c78783c071f85"
    },
    "oldest_block_identifier": {
        "index": 1123941,
        "hash": "0x1f2cc6c5027d2f201a5453ad1119574d2aed23a392654742ac3c78783c071f85"
    },
    "sync_status": {
        "current_index": 100,
        "target_index": 150,
        "stage": "header sync",
        "synced": true
    },
    "peers": [
        {
            "peer_id": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5",
            "metadata": {}
        }
    ]
}

Full Reference

Operation

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.

Properties

NameTypeDescriptionRequired
operation_identifierOperationIdentifierThe operation_identifier uniquely identifies an operation within a transaction.True
related_operations[]OperationIdentifierRestrict referenced related_operations to identifier indices " the current operation_identifier.index. This ensures there exists a clear DAG-structure of relations. Since operations are one-sided, one could imagine relating operations in a single transfer or linking operations in a call tree.False
typeStringType is the network-specific type of the operation. Ensure that any type that can be returned here is also specified in the NetworkOptionsResponse. This can be very useful to downstream consumers that parse all block data.True
statusStringStatus is the network-specific status of the operation. Status is not defined on the transaction object because blockchains with smart contracts may have transactions that partially apply (some operations are successful and some are not). Blockchains with atomic transactions (all operations succeed or all operations fail) will have the same status for each operation. On-chain operations (operations retrieved in the /block and /block/transaction endpoints) MUST have a populated status field (anything on-chain must have succeeded or failed). However, operations provided during transaction construction (often times called "intent" in the documentation) MUST NOT have a populated status field (operations yet to be included on-chain have not yet succeeded or failed).False
accountAccountIdentifierThe account_identifier uniquely identifies an account within a network. All fields in the account_identifier are utilized to determine this uniqueness (including the metadata field, if populated).False
amountAmountAmount is some Value of a Currency. It is considered invalid to specify a Value without a Currency.False
coin_changeCoinChangeCoinChange is used to represent a change in state of a some coin identified by a coin_identifier. 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 populate this model).False
metadataObjectFalse

Example

{
    "operation_identifier": {
        "index": 5,
        "network_index": 0
    },
    "related_operations": [
        {
            "index": 1
        },
        {
            "index": 2
        }
    ],
    "type": "Transfer",
    "status": "Reverted",
    "account": {
        "address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
        "sub_account": {
            "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
            "metadata": {}
        },
        "metadata": {}
    },
    "amount": {
        "value": "1238089899992",
        "currency": {
            "symbol": "BTC",
            "decimals": 8,
            "metadata": {
                "Issuer": "Satoshi"
            }
        },
        "metadata": {}
    },
    "coin_change": {
        "coin_identifier": {
            "identifier": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f:1"
        },
        "coin_action": "coin_created"
    },
    "metadata": {
        "asm": "304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd01 03301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2",
        "hex": "48304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd012103301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2"
    }
}

Full Reference

OperationIdentifier

The operation_identifier uniquely identifies an operation within a transaction.

Properties

NameTypeDescriptionRequired
indexInt64 (>= 0)The operation index is used to ensure each operation has a unique identifier within a transaction. This index is only relative to the transaction and NOT GLOBAL. The operations in each transaction should start from index 0. To clarify, there may not be any notion of an operation index in the blockchain being described.True
network_indexInt64 (>= 0)Some blockchains specify an operation index that is essential for client use. For example, Bitcoin uses a network_index to identify which UTXO was used in a transaction. network_index should not be populated if there is no notion of an operation index in a blockchain (typically most account-based blockchains).False

Example

{
    "index": 5,
    "network_index": 0
}

Full Reference

OperationStatus

OperationStatus is utilized to indicate which Operation status are considered successful.

Properties

NameTypeDescriptionRequired
statusStringThe status is the network-specific status of the operation.True
successfulBooleanAn 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.True

Example

{
    "status": "SUCCESS",
    "successful": true
}

Full Reference

Operator

Operator is used by query-related endpoints to determine how to apply conditions.

If this field is not populated, the default and value will be used.

Properties

NameDescription
orIf any condition is satisfied, it is considered a match.
andIf all conditions are satisfied, it is considered a match.

Example

"or"

Full Reference

PartialBlockIdentifier

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.

Properties

NameTypeDescriptionRequired
indexInt64 (>= 0)False
hashStringFalse

Example

{
    "index": 1123941,
    "hash": "0x1f2cc6c5027d2f201a5453ad1119574d2aed23a392654742ac3c78783c071f85"
}

Full Reference

Peer

A Peer is a representation of a node's peer.

Properties

NameTypeDescriptionRequired
peer_idStringTrue
metadataObjectFalse

Example

{
    "peer_id": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5",
    "metadata": {}
}

Full Reference

PublicKey

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.

Properties

NameTypeDescriptionRequired
hex_bytesStringHex-encoded public key bytes in the format specified by the CurveType.True
curve_typeCurveTypeCurveType is the type of cryptographic curve associated with a PublicKey.True

Example

{
    "hex_bytes": "string",
    "curve_type": "secp256k1"
}

Full Reference

RelatedTransaction

The related_transaction allows implementations to link together multiple transactions. An unpopulated network identifier indicates that the related transaction is on the same network.

Properties

NameTypeDescriptionRequired
network_identifierNetworkIdentifierThe network_identifier specifies which network a particular object is associated with.False
transaction_identifierTransactionIdentifierThe transaction_identifier uniquely identifies a transaction in a particular network and block or in the mempool.True
directionDirectionUsed by RelatedTransaction to indicate the direction of the relation (i.e. cross-shard/cross-network sends may reference backward to an earlier transaction and async execution may reference forward). Can be used to indicate if a transaction relation is from child to parent or the reverse.True

Example

{
    "network_identifier": {
        "blockchain": "bitcoin",
        "network": "mainnet",
        "sub_network_identifier": {
            "network": "shard 1",
            "metadata": {
                "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
            }
        }
    },
    "transaction_identifier": {
        "hash": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f"
    },
    "direction": "forward"
}

Full Reference

SearchTransactionsRequest

SearchTransactionsRequest is used to search for transactions matching a set of provided conditions in canonical blocks.

Properties

NameTypeDescriptionRequired
network_identifierNetworkIdentifierThe network_identifier specifies which network a particular object is associated with.True
operatorOperatorOperator is used by query-related endpoints to determine how to apply conditions. If this field is not populated, the default and value will be used.False
max_blockInt64 (>= 0)max_block is the largest block index to consider when searching for transactions. If this field is not populated, the current block is considered the max_block. If you do not specify a max_block, it is possible a newly synced block will interfere with paginated transaction queries (as the offset could become invalid with newly added rows).False
offsetInt64 (>= 0)offset is the offset into the query result to start returning transactions. If any search conditions are changed, the query offset will change and you must restart your search iteration.False
limitInt64 (>= 0)limit is the maximum number of transactions to return in one call. The implementation may return "= limit transactions.False
transaction_identifierTransactionIdentifierThe transaction_identifier uniquely identifies a transaction in a particular network and block or in the mempool.False
account_identifierAccountIdentifierThe account_identifier uniquely identifies an account within a network. All fields in the account_identifier are utilized to determine this uniqueness (including the metadata field, if populated).False
coin_identifierCoinIdentifierCoinIdentifier uniquely identifies a Coin.False
currencyCurrencyCurrency 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).False
statusStringstatus is the network-specific operation type.False
typeStringtype is the network-specific operation type.False
addressStringaddress is AccountIdentifier.Address. This is used to get all transactions related to an AccountIdentifier.Address, regardless of SubAccountIdentifier.False
successBooleansuccess is a synthetic condition populated by parsing network-specific operation statuses (using the mapping provided in /network/options).False

Example

{
    "network_identifier": {
        "blockchain": "bitcoin",
        "network": "mainnet",
        "sub_network_identifier": {
            "network": "shard 1",
            "metadata": {
                "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
            }
        }
    },
    "operator": "or",
    "max_block": 5,
    "offset": 5,
    "limit": 5,
    "transaction_identifier": {
        "hash": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f"
    },
    "account_identifier": {
        "address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
        "sub_account": {
            "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
            "metadata": {}
        },
        "metadata": {}
    },
    "coin_identifier": {
        "identifier": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f:1"
    },
    "currency": {
        "symbol": "BTC",
        "decimals": 8,
        "metadata": {
            "Issuer": "Satoshi"
        }
    },
    "status": "reverted",
    "type": "transfer",
    "address": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
    "success": true
}

Full Reference

SearchTransactionsResponse

SearchTransactionsResponse contains an ordered collection of BlockTransactions that match the query in SearchTransactionsRequest. These BlockTransactions are sorted from most recent block to oldest block.

Properties

NameTypeDescriptionRequired
transactions[]BlockTransactiontransactions is an array of BlockTransactions sorted by most recent BlockIdentifier (meaning that transactions in recent blocks appear first). If there are many transactions for a particular search, transactions may not contain all matching transactions. It is up to the caller to paginate these transactions using the max_block field.True
total_countInt64 (>= 0)total_count is the number of results for a given search. Callers typically use this value to concurrently fetch results by offset or to display a virtual page number associated with results.True
next_offsetInt64 (>= 0)next_offset is the next offset to use when paginating through transaction results. If this field is not populated, there are no more transactions to query.False

Example

{
    "transactions": [
        {
            "block_identifier": {
                "index": 1123941,
                "hash": "0x1f2cc6c5027d2f201a5453ad1119574d2aed23a392654742ac3c78783c071f85"
            },
            "transaction": {
                "transaction_identifier": {
                    "hash": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f"
                },
                "operations": [
                    {
                        "operation_identifier": {
                            "index": 5,
                            "network_index": 0
                        },
                        "related_operations": [
                            {
                                "index": 1
                            },
                            {
                                "index": 2
                            }
                        ],
                        "type": "Transfer",
                        "status": "Reverted",
                        "account": {
                            "address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
                            "sub_account": {
                                "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
                                "metadata": {}
                            },
                            "metadata": {}
                        },
                        "amount": {
                            "value": "1238089899992",
                            "currency": {
                                "symbol": "BTC",
                                "decimals": 8,
                                "metadata": {
                                    "Issuer": "Satoshi"
                                }
                            },
                            "metadata": {}
                        },
                        "coin_change": {
                            "coin_identifier": {
                                "identifier": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f:1"
                            },
                            "coin_action": "coin_created"
                        },
                        "metadata": {
                            "asm": "304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd01 03301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2",
                            "hex": "48304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd012103301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2"
                        }
                    }
                ],
                "related_transactions": [
                    {
                        "network_identifier": {
                            "blockchain": "bitcoin",
                            "network": "mainnet",
                            "sub_network_identifier": {
                                "network": "shard 1",
                                "metadata": {
                                    "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
                                }
                            }
                        },
                        "transaction_identifier": {
                            "hash": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f"
                        },
                        "direction": "forward"
                    }
                ],
                "metadata": {
                    "size": 12378,
                    "lockTime": 1582272577
                }
            }
        }
    ],
    "total_count": 5,
    "next_offset": 5
}

Full Reference

Signature

Signature contains the payload that was signed, the public keys of the keypairs 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.

Properties

NameTypeDescriptionRequired
signing_payloadSigningPayloadSigningPayload 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.True
public_keyPublicKeyPublicKey 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.True
signature_typeSignatureTypeSignatureType is the type of a cryptographic signature.True
hex_bytesStringTrue

Example

{
    "signing_payload": {
        "address": "string",
        "account_identifier": {
            "address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
            "sub_account": {
                "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
                "metadata": {}
            },
            "metadata": {}
        },
        "hex_bytes": "string",
        "signature_type": "ecdsa"
    },
    "public_key": {
        "hex_bytes": "string",
        "curve_type": "secp256k1"
    },
    "signature_type": "ecdsa",
    "hex_bytes": "string"
}

Full Reference

SignatureType

SignatureType is the type of a cryptographic signature.

Properties

Type: enum (string)

Values

NameFormatSize
ecdsar (32-bytes) + s (32-bytes)64 bytes
ecdsa_recoveryr (32-bytes) + s (32-bytes) + v (1-byte)65 bytes
ed25519R (32-bytes) + s (32-bytes)64 bytes
schnorr_1r (32-bytes) + s (32-bytes)64 bytes
schnorr_poseidonr (32-bytes) + s (32-bytes) where s = Hash(1st pk + 2nd pk + r)64 bytes

Additional Details

schnorr_1 is a EC-Schnorr signature implemented by Zilliqa where both r and s are scalars encoded as 32-bytes values, most significant byte first. Refer to Zilliqa's Schnorr Library and Zilliqa Technical Whitepaper - Appendix A: Schnorr Digital Signature for details.)

schnorr_poseidon is an EC-schnorr signature with Poseidon hash function implemented by O(1) Labs where both r and s are scalars encoded as 32-bytes little-endian values. Refer to Coda's signer reference implementation

Example

"ecdsa"

Full Reference

SigningPayload

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.

Properties

NameTypeDescriptionRequired
addressString[DEPRECATED by account_identifier in v1.4.4] The network-specific address of the account that should sign the payload.False
account_identifierAccountIdentifierThe account_identifier uniquely identifies an account within a network. All fields in the account_identifier are utilized to determine this uniqueness (including the metadata field, if populated).False
hex_bytesStringTrue
signature_typeSignatureTypeSignatureType is the type of a cryptographic signature.False

Example

{
    "address": "string",
    "account_identifier": {
        "address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
        "sub_account": {
            "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
            "metadata": {}
        },
        "metadata": {}
    },
    "hex_bytes": "string",
    "signature_type": "ecdsa"
}

Full Reference

SubAccountIdentifier

An account may have state specific to a contract address (ERC-20 token) and/or a stake (delegated balance). The sub_account_identifier should specify which state (if applicable) an account instantiation refers to.

Properties

NameTypeDescriptionRequired
addressStringThe SubAccount address may be a cryptographic value or some other identifier (ex: bonded) that uniquely specifies a SubAccount.True
metadataObjectIf the SubAccount address is not sufficient to uniquely specify a SubAccount, any other identifying information can be stored here. It is important to note that two SubAccounts with identical addresses but differing metadata will not be considered equal by clients.False

Example

{
    "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
    "metadata": {}
}

Full Reference

SubNetworkIdentifier

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.

Properties

NameTypeDescriptionRequired
networkStringTrue
metadataObjectFalse

Example

{
    "network": "shard 1",
    "metadata": {
        "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
    }
}

Full Reference

SyncStatus

SyncStatus is used to provide additional context about an implementation's sync status. This object is often used by implementations to indicate healthiness when block data cannot be queried until some sync phase completes or cannot be determined by comparing the timestamp of the most recent block with the current time.

Properties

NameTypeDescriptionRequired
current_indexInt64 (>= 0)CurrentIndex is the index of the last synced block in the current stage. This is a separate field from current_block_identifier in NetworkStatusResponse because blocks with indices up to and including the current_index may not yet be queryable by the caller. To reiterate, all indices up to and including current_block_identifier in NetworkStatusResponse must be queryable via the /block endpoint (excluding indices less than oldest_block_identifier).False
target_indexInt64 (>= 0)TargetIndex is the index of the block that the implementation is attempting to sync to in the current stage.False
stageStringStage is the phase of the sync process.False
syncedBooleansycned is a boolean that indicates if an implementation has synced up to the most recent block. If this field is not populated, the caller should rely on a traditional tip timestamp comparison to determine if an implementation is synced. This field is particularly useful for quiescent blockchains (blocks only produced when there are pending transactions). In these blockchains, the most recent block could have a timestamp far behind the current time but the node could be healthy and at tip.False

Example

{
    "current_index": 100,
    "target_index": 150,
    "stage": "header sync",
    "synced": true
}

Full Reference

Transaction

Transactions contain an array of Operations that are attributable to the same TransactionIdentifier.

Properties

NameTypeDescriptionRequired
transaction_identifierTransactionIdentifierThe transaction_identifier uniquely identifies a transaction in a particular network and block or in the mempool.True
operations[]OperationTrue
related_transactions[]RelatedTransactionFalse
metadataObjectTransactions that are related to other transactions (like a cross-shard transaction) should include the tranaction_identifier of these transactions in the metadata.False

Example

{
    "transaction_identifier": {
        "hash": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f"
    },
    "operations": [
        {
            "operation_identifier": {
                "index": 5,
                "network_index": 0
            },
            "related_operations": [
                {
                    "index": 1
                },
                {
                    "index": 2
                }
            ],
            "type": "Transfer",
            "status": "Reverted",
            "account": {
                "address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
                "sub_account": {
                    "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
                    "metadata": {}
                },
                "metadata": {}
            },
            "amount": {
                "value": "1238089899992",
                "currency": {
                    "symbol": "BTC",
                    "decimals": 8,
                    "metadata": {
                        "Issuer": "Satoshi"
                    }
                },
                "metadata": {}
            },
            "coin_change": {
                "coin_identifier": {
                    "identifier": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f:1"
                },
                "coin_action": "coin_created"
            },
            "metadata": {
                "asm": "304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd01 03301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2",
                "hex": "48304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd012103301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2"
            }
        }
    ],
    "related_transactions": [
        {
            "network_identifier": {
                "blockchain": "bitcoin",
                "network": "mainnet",
                "sub_network_identifier": {
                    "network": "shard 1",
                    "metadata": {
                        "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
                    }
                }
            },
            "transaction_identifier": {
                "hash": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f"
            },
            "direction": "forward"
        }
    ],
    "metadata": {
        "size": 12378,
        "lockTime": 1582272577
    }
}

Full Reference

TransactionIdentifier

The transaction_identifier uniquely identifies a transaction in a particular network and block or in the mempool.

Properties

NameTypeDescriptionRequired
hashStringAny transactions that are attributable only to a block (ex: a block event) should use the hash of the block as the identifier.True

Example

{
    "hash": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f"
}

Full Reference

TransactionIdentifierResponse

TransactionIdentifierResponse contains the transaction_identifier of a transaction that was submitted to either /construction/hash or /construction/submit.

Properties

NameTypeDescriptionRequired
transaction_identifierTransactionIdentifierThe transaction_identifier uniquely identifies a transaction in a particular network and block or in the mempool.True
metadataObjectFalse

Example

{
    "transaction_identifier": {
        "hash": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f"
    },
    "metadata": {}
}

Full Reference

Version

The Version object is utilized to inform the client of the versions of different components of the Rosetta implementation.

Properties

NameTypeDescriptionRequired
rosetta_versionStringThe rosetta_version is the version of the Rosetta interface the implementation adheres to. This can be useful for clients looking to reliably parse responses.True
node_versionStringThe node_version is the canonical version of the node runtime. This can help clients manage deployments.True
middleware_versionStringWhen a middleware server is used to adhere to the Rosetta interface, it should return its version here. This can help clients manage deployments.False
metadataObjectAny other information that may be useful about versioning of dependent services should be returned here.False

Example

{
    "rosetta_version": "1.2.5",
    "node_version": "1.0.2",
    "middleware_version": "0.2.7",
    "metadata": {}
}

Full Reference