# Copyright 2020 Coinbase, Inc. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. openapi: 3.0.2 info: version: 1.5.1 title: Rosetta description: | Build Once. Integrate Your Blockchain Everywhere. license: name: Apache 2.0 url: "http://www.apache.org/licenses/LICENSE-2.0.html" paths: /network/list: post: summary: Get List of Available Networks description: | This endpoint returns a list of NetworkIdentifiers that the Rosetta server supports. operationId: networkList tags: - Network requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MetadataRequest' responses: '200': description: Expected response to a valid request content: application/json: schema: $ref: '#/components/schemas/NetworkListResponse' '500': description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /network/status: post: summary: Get Network Status description: | This endpoint returns the current status of the network requested. Any NetworkIdentifier returned by /network/list should be accessible here. operationId: networkStatus tags: - Network requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NetworkRequest' responses: '200': description: Expected response to a valid request content: application/json: schema: $ref: '#/components/schemas/NetworkStatusResponse' '500': description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /network/options: post: summary: Get Network Options description: | This endpoint returns the version information and allowed network-specific types for a NetworkIdentifier. Any NetworkIdentifier returned by /network/list should be accessible here. Because options are retrievable in the context of a NetworkIdentifier, it is possible to define unique options for each network. operationId: networkOptions tags: - Network requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NetworkRequest' responses: '200': description: Expected response to a valid request content: application/json: schema: $ref: '#/components/schemas/NetworkOptionsResponse' '500': description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /block: post: summary: Get a Block description: | Get a block by its Block Identifier. If transactions are returned in the same call to the node as fetching the block, the response should include these transactions in the Block object. If not, an array of Transaction Identifiers should be returned so /block/transaction fetches can be done to get all transaction information. When requesting a block by the hash component of the BlockIdentifier, this request MUST be idempotent: repeated invocations for the same hash-identified block must return the exact same block contents. No such restriction is imposed when requesting a block by height, given that a chain reorg event might cause the specific block at height `n` to be set to a different one. operationId: block tags: - Block requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BlockRequest' responses: '200': description: Expected response to a valid request content: application/json: schema: $ref: '#/components/schemas/BlockResponse' '500': description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /block/transaction: post: summary: Get a Block Transaction description: | Get a transaction in a block by its Transaction Identifier. This endpoint should only be used when querying a node for a block does not return all transactions contained within it. All transactions returned by this endpoint must be appended to any transactions returned by the /block method by consumers of this data. Fetching a transaction by hash is considered an Explorer Method (which is classified under the Future Work section). This method can be used to let consumers to paginate results when the block trasactions count is too big to be returned in a single BlockResponse. Calling this endpoint requires reference to a BlockIdentifier because transaction parsing can change depending on which block contains the transaction. For example, in Bitcoin it is necessary to know which block contains a transaction to determine the destination of fee payments. Without specifying a block identifier, the node would have to infer which block to use (which could change during a re-org). Implementations that require fetching previous transactions to populate the response (ex: Previous UTXOs in Bitcoin) may find it useful to run a cache within the Rosetta server in the /data directory (on a path that does not conflict with the node). operationId: blockTransaction tags: - Block requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BlockTransactionRequest' responses: '200': description: Expected response to a valid request content: application/json: schema: $ref: '#/components/schemas/BlockTransactionResponse' '500': description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /mempool: post: summary: Get All Mempool Transactions description: Get all Transaction Identifiers in the mempool operationId: mempool tags: - Mempool requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NetworkRequest' responses: '200': description: Expected response to a valid request content: application/json: schema: $ref: '#/components/schemas/MempoolResponse' '500': description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /mempool/transaction: post: summary: Get a Mempool Transaction description: | Get a transaction in the mempool by its Transaction Identifier. This is a separate request than fetching a block transaction (/block/transaction) because some blockchain nodes need to know that a transaction query is for something in the mempool instead of a transaction in a block. Transactions may not be fully parsable until they are in a block (ex: may not be possible to determine the fee to pay before a transaction is executed). On this endpoint, it is ok that returned transactions are only estimates of what may actually be included in a block. operationId: mempoolTransaction tags: - Mempool requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MempoolTransactionRequest' responses: '200': description: Expected response to a valid request content: application/json: schema: $ref: '#/components/schemas/MempoolTransactionResponse' '500': description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /account/balance: post: summary: Get an Account's Balance description: | Get an array of all AccountBalances for an AccountIdentifier and the BlockIdentifier at which the balance lookup was performed. The BlockIdentifier must always be returned because some consumers of account balance data need to know specifically at which block the balance was calculated to compare balances they compute from operations with the balance returned by the node. It is important to note that making a balance request for an account without populating the SubAccountIdentifier should not result in the balance of all possible SubAccountIdentifiers being returned. Rather, it should result in the balance pertaining to no SubAccountIdentifiers being returned (sometimes called the liquid balance). To get all balances associated with an account, it may be necessary to perform multiple balance requests with unique AccountIdentifiers. It is also possible to perform a historical balance lookup (if the server supports it) by passing in an optional BlockIdentifier. operationId: accountBalance tags: - Account requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AccountBalanceRequest' responses: '200': description: Expected response to a valid request content: application/json: schema: $ref: '#/components/schemas/AccountBalanceResponse' '500': description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /account/all-balances: post: summary: Get All Account Balances description: | Get an array of all AccountBalances for all sub-accounts of an AccountIdentifier and the BlockIdentifier at which the balance lookup was performed. This endpoint returns balances for the main account and all associated sub-accounts in a single request, eliminating the need to make multiple individual /account/balance calls. The BlockIdentifier must always be returned because some consumers of account balance data need to know specifically at which block the balance was calculated to compare balances they compute from operations with the balance returned by the node. This endpoint automatically returns all available sub-account types for the given account, including the main account balance and all sub-accounts (e.g., delegated, unbonding, rewards, etc.). It is also possible to perform a historical balance lookup (if the server supports it) by passing in an optional BlockIdentifier. This endpoint provides better performance and consistency compared to making multiple individual /account/balance requests, as all balances are guaranteed to be from the same block context. operationId: allAccountBalances tags: - Account requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AllAccountBalancesRequest' responses: '200': description: Expected response to a valid request content: application/json: schema: $ref: '#/components/schemas/AllAccountBalancesResponse' '500': description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /account/coins: post: summary: Get an Account's Unspent Coins description: | Get an array of all unspent coins for an AccountIdentifier and the BlockIdentifier at which the lookup was performed. If your implementation does not support coins (i.e. it is for an account-based blockchain), you do not need to implement this endpoint. If you implementation does support coins (i.e. it is fro a UTXO-based blockchain), you MUST also complete the `/account/balance` endpoint. It is important to note that making a coins request for an account without populating the SubAccountIdentifier should not result in the coins of all possible SubAccountIdentifiers being returned. Rather, it should result in the coins pertaining to no SubAccountIdentifiers being returned. To get all coins associated with an account, it may be necessary to perform multiple coin requests with unique AccountIdentifiers. Optionally, an implementation may choose to support updating an AccountIdentifier's unspent coins based on the contents of the mempool. Note, using this functionality breaks any guarantee of idempotency. operationId: accountCoins tags: - Account requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AccountCoinsRequest' responses: '200': description: Expected response to a valid request content: application/json: schema: $ref: '#/components/schemas/AccountCoinsResponse' '500': description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /construction/derive: post: summary: Derive an AccountIdentifier from a PublicKey description: | Derive returns the AccountIdentifier associated with a public key. Blockchains that require an on-chain action to create an account should not implement this method. operationId: constructionDerive tags: - Construction requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConstructionDeriveRequest' responses: '200': description: Expected response to a valid request content: application/json: schema: $ref: '#/components/schemas/ConstructionDeriveResponse' '500': description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /construction/preprocess: post: summary: Create a Request to Fetch Metadata description: | Preprocess is called prior to `/construction/payloads` to construct a request for any metadata that is needed for transaction construction given (i.e. account nonce). The `options` object returned from this endpoint will be sent to the `/construction/metadata` endpoint UNMODIFIED by the caller (in an offline execution environment). If your Construction API implementation has configuration options, they MUST be specified in the `/construction/preprocess` request (in the `metadata` field). operationId: constructionPreprocess tags: - Construction requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConstructionPreprocessRequest' responses: '200': description: Expected response to a valid request content: application/json: schema: $ref: '#/components/schemas/ConstructionPreprocessResponse' '500': description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /construction/preprocess-operations: post: summary: Parse High-Level Construction Operations description: | PreprocessOperations is called to parse and validate high-level transaction construction operations into Rosetta operations. This endpoint allows the Rosetta implementation to handle operation parsing that might not be supported by local client-side parsers. This endpoint is OPTIONAL and implementations can return HTTP 501 (Not Implemented) if they don't support this functionality. The input format matches TransactionConstructOpInput used by chainstdio, and the output format matches the return values of ParseTransactionConstructOp to maintain compatibility with existing operation parsing workflows. operationId: constructionPreprocessOperations tags: - Construction requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConstructionPreprocessOperationsRequest' responses: '200': description: Expected response to a valid request content: application/json: schema: $ref: '#/components/schemas/ConstructionPreprocessOperationsResponse' '501': description: Not Implemented - This endpoint is optional content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /construction/metadata: post: summary: Get Metadata for Transaction Construction description: | Get any information required to construct a transaction for a specific network. Metadata returned here could be a recent hash to use, an account sequence number, or even arbitrary chain state. The request used when calling this endpoint is created by calling `/construction/preprocess` in an offline environment. You should NEVER assume that the request sent to this endpoint will be created by the caller or populated with any custom parameters. This must occur in `/construction/preprocess`. It is important to clarify that this endpoint should not pre-construct any transactions for the client (this should happen in `/construction/payloads`). This endpoint is left purposely unstructured because of the wide scope of metadata that could be required. operationId: constructionMetadata tags: - Construction requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConstructionMetadataRequest' responses: '200': description: Expected response to a valid request content: application/json: schema: $ref: '#/components/schemas/ConstructionMetadataResponse' '500': description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /construction/payloads: post: summary: Generate an Unsigned Transaction and Signing Payloads description: | Payloads is called with an array of operations and the response from `/construction/metadata`. It returns an unsigned transaction blob and a collection of payloads that must be signed by particular AccountIdentifiers using a certain SignatureType. The array of operations provided in transaction construction often times can not specify all "effects" of a transaction (consider invoked transactions in Ethereum). However, they can deterministically specify the "intent" of the transaction, which is sufficient for construction. For this reason, parsing the corresponding transaction in the Data API (when it lands on chain) will contain a superset of whatever operations were provided during construction. operationId: constructionPayloads tags: - Construction requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConstructionPayloadsRequest' responses: '200': description: Expected response to a valid request content: application/json: schema: $ref: '#/components/schemas/ConstructionPayloadsResponse' '500': description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /construction/combine: post: summary: Create Network Transaction from Signatures description: | Combine creates a network-specific transaction from an unsigned transaction and an array of provided signatures. The signed transaction returned from this method will be sent to the `/construction/submit` endpoint by the caller. operationId: constructionCombine tags: - Construction requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConstructionCombineRequest' responses: '200': description: Expected response to a valid request content: application/json: schema: $ref: '#/components/schemas/ConstructionCombineResponse' '500': description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /construction/parse: post: summary: Parse a Transaction description: | Parse is called on both unsigned and signed transactions to understand the intent of the formulated transaction. This is run as a sanity check before signing (after `/construction/payloads`) and before broadcast (after `/construction/combine`). operationId: constructionParse tags: - Construction requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConstructionParseRequest' responses: '200': description: Expected response to a valid request content: application/json: schema: $ref: '#/components/schemas/ConstructionParseResponse' '500': description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /construction/hash: post: summary: Get the Hash of a Signed Transaction description: | TransactionHash returns the network-specific transaction hash for a signed transaction. operationId: constructionHash tags: - Construction requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConstructionHashRequest' responses: '200': description: Expected response to a valid request content: application/json: schema: $ref: '#/components/schemas/TransactionIdentifierResponse' '500': description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /construction/submit: post: summary: Submit a Signed Transaction description: | Submit a pre-signed transaction to the node. This call should not block on the transaction being included in a block. Rather, it should return immediately with an indication of whether or not the transaction was included in the mempool. The transaction submission response should only return a 200 status if the submitted transaction could be included in the mempool. Otherwise, it should return an error. operationId: constructionSubmit tags: - Construction requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConstructionSubmitRequest' responses: '200': description: Expected response to a valid request content: application/json: schema: $ref: '#/components/schemas/TransactionIdentifierResponse' '500': description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /call: post: summary: Make a Network-Specific Procedure Call description: | Call invokes an arbitrary, network-specific procedure call with network-specific parameters. The guidance for what this endpoint should or could do is purposely left vague. In Ethereum, this could be used to invoke `eth_call` to implement an entire Rosetta API interface for some smart contract that is not parsed by the implementation creator (like a DEX). This endpoint could also be used to provide access to data that does not map to any Rosetta models instead of requiring an integrator to use some network-specific SDK and call some network-specific endpoint (like surfacing staking parameters). Call is NOT a replacement for implementing Rosetta API endpoints or mapping network-specific data to Rosetta models. Rather, it enables developers to build additional Rosetta API interfaces for things they care about without introducing complexity into a base-level Rosetta implementation. Simply put, imagine that the average integrator will use layered Rosetta API implementations that each surfaces unique data. operationId: call tags: - Call requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CallRequest' responses: '200': description: Expected response to a valid request content: application/json: schema: $ref: '#/components/schemas/CallResponse' '500': description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /events/blocks: post: summary: | [INDEXER] Get a range of BlockEvents description: | `/events/blocks` allows the caller to query a sequence of BlockEvents indicating which blocks were added and removed from storage to reach the current state. Following BlockEvents allows lightweight clients to update their state without needing to implement their own syncing logic (like finding the common parent in a reorg). `/events/blocks` is considered an "indexer" endpoint and Rosetta implementations are not required to complete it to adhere to the Rosetta spec. However, any Rosetta "indexer" MUST support this endpoint. operationId: eventsBlocks tags: - Events requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EventsBlocksRequest' responses: '200': description: Expected response to a valid request content: application/json: schema: $ref: '#/components/schemas/EventsBlocksResponse' '500': description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /search/transactions: post: summary: | [INDEXER] Search for Transactions description: | `/search/transactions` allows the caller to search for transactions that meet certain conditions. Some conditions include matching a transaction hash, containing an operation with a certain status, or containing an operation that affects a certain account. `/search/transactions` is considered an "indexer" endpoint and Rosetta implementations are not required to complete it to adhere to the Rosetta spec. However, any Rosetta "indexer" MUST support this endpoint. operationId: searchTransactions tags: - Search requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SearchTransactionsRequest' responses: '200': description: Expected response to a valid request content: application/json: schema: $ref: '#/components/schemas/SearchTransactionsResponse' '500': description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: # Identifiers NetworkIdentifier: $ref: 'models/NetworkIdentifier.yaml' SubNetworkIdentifier: $ref: 'models/SubNetworkIdentifier.yaml' BlockIdentifier: $ref: 'models/BlockIdentifier.yaml' PartialBlockIdentifier: $ref: 'models/PartialBlockIdentifier.yaml' TransactionIdentifier: $ref: 'models/TransactionIdentifier.yaml' OperationIdentifier: $ref: 'models/OperationIdentifier.yaml' AccountIdentifier: $ref: 'models/AccountIdentifier.yaml' SubAccountIdentifier: $ref: 'models/SubAccountIdentifier.yaml' # Models Block: $ref: 'models/Block.yaml' Transaction: $ref: 'models/Transaction.yaml' Operation: $ref: 'models/Operation.yaml' Amount: $ref: 'models/Amount.yaml' Currency: $ref: 'models/Currency.yaml' SyncStatus: $ref: 'models/SyncStatus.yaml' Peer: $ref: 'models/Peer.yaml' Version: $ref: 'models/Version.yaml' Allow: $ref: 'models/Allow.yaml' OperationStatus: $ref: 'models/OperationStatus.yaml' Timestamp: $ref: 'models/Timestamp.yaml' PublicKey: $ref: 'models/PublicKey.yaml' CurveType: $ref: 'models/CurveType.yaml' SigningPayload: $ref: 'models/SigningPayload.yaml' Signature: $ref: 'models/Signature.yaml' SignatureType: $ref: 'models/SignatureType.yaml' CoinAction: $ref: 'models/CoinAction.yaml' CoinIdentifier: $ref: 'models/CoinIdentifier.yaml' CoinChange: $ref: 'models/CoinChange.yaml' Coin: $ref: 'models/Coin.yaml' BalanceExemption: $ref: 'models/BalanceExemption.yaml' ExemptionType: $ref: 'models/ExemptionType.yaml' BlockEvent: $ref: 'models/BlockEvent.yaml' BlockEventType: $ref: 'models/BlockEventType.yaml' Operator: $ref: 'models/Operator.yaml' BlockTransaction: $ref: 'models/BlockTransaction.yaml' RelatedTransaction: $ref: 'models/RelatedTransaction.yaml' Direction: $ref: 'models/Direction.yaml' Case: $ref: 'models/Case.yaml' # Request/Responses AccountBalanceRequest: description: | 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. type: object required: - network_identifier - account_identifier properties: network_identifier: $ref: '#/components/schemas/NetworkIdentifier' account_identifier: $ref: '#/components/schemas/AccountIdentifier' block_identifier: $ref: '#/components/schemas/PartialBlockIdentifier' currencies: type: array description: | In 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. items: $ref: '#/components/schemas/Currency' AccountBalanceResponse: description: | 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`. type: object required: - block_identifier - balances properties: block_identifier: $ref: '#/components/schemas/BlockIdentifier' balances: type: array description: | A single account may have a balance in multiple currencies. items: $ref: '#/components/schemas/Amount' metadata: description: | Account-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. type: object example: sequence_number: 23 AllAccountBalancesRequest: description: | An AllAccountBalancesRequest is utilized to make a balance request for all sub-accounts on the /account/all-balances endpoint. This endpoint returns balances for the main account and all associated sub-accounts in a single request, eliminating the need to make multiple individual /account/balance calls for each sub-account. The endpoint automatically returns all available sub-account types for the given account. If the block_identifier is populated, a historical balance query should be performed. type: object required: - network_identifier - account_identifier properties: network_identifier: $ref: '#/components/schemas/NetworkIdentifier' account_identifier: $ref: '#/components/schemas/AccountIdentifier' block_identifier: $ref: '#/components/schemas/PartialBlockIdentifier' currencies: type: array description: | In 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. items: $ref: '#/components/schemas/Currency' AllAccountBalancesResponse: description: | An AllAccountBalancesResponse is returned on the /account/all-balances endpoint. It contains balances for the main account and all associated sub-accounts, along with their respective sub-account identifiers and balance types. This response provides all account balances in a single request, eliminating the need for multiple calls to /account/balance with different sub-account identifiers. type: object required: - block_identifier - account_balances properties: block_identifier: $ref: '#/components/schemas/BlockIdentifier' account_balances: type: array description: | Array of account balances including main account and all sub-accounts. Each balance includes balance type information and metadata. items: $ref: '#/components/schemas/AccountBalanceWithSubAccount' AccountBalanceWithSubAccount: description: | Represents a balance for a specific account or sub-account, including balance type information and metadata. type: object required: - balances properties: balances: type: array description: | A single account/sub-account may have a balance in multiple currencies. items: $ref: '#/components/schemas/Amount' balance_type: type: string description: | The type of balance (e.g., spendable, delegated, pending_undelegation, etc.) example: "spendable" metadata: description: | Sub-account specific metadata type: object AccountCoinsRequest: description: | AccountCoinsRequest is utilized to make a request on the /account/coins endpoint. type: object required: - network_identifier - account_identifier - include_mempool properties: network_identifier: $ref: '#/components/schemas/NetworkIdentifier' account_identifier: $ref: '#/components/schemas/AccountIdentifier' include_mempool: type: boolean description: | Include state from the mempool when looking up an account's unspent coins. Note, using this functionality breaks any guarantee of idempotency. currencies: type: array description: | In 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. items: $ref: '#/components/schemas/Currency' AccountCoinsResponse: description: | AccountCoinsResponse is returned on the /account/coins endpoint and includes all unspent Coins owned by an AccountIdentifier. type: object required: - block_identifier - coins properties: block_identifier: $ref: '#/components/schemas/BlockIdentifier' coins: type: array description: | If 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. items: $ref: '#/components/schemas/Coin' metadata: description: | Account-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. type: object example: sequence_number: 23 BlockRequest: description: | A BlockRequest is utilized to make a block request on the /block endpoint. type: object required: - network_identifier - block_identifier properties: network_identifier: $ref: '#/components/schemas/NetworkIdentifier' block_identifier: $ref: '#/components/schemas/PartialBlockIdentifier' BlockResponse: description: | 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. type: object properties: block: $ref: '#/components/schemas/Block' other_transactions: description: | Some 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. type: array items: $ref: '#/components/schemas/TransactionIdentifier' BlockTransactionRequest: description: | A BlockTransactionRequest is used to fetch a Transaction included in a block that is not returned in a BlockResponse. type: object required: - network_identifier - block_identifier - transaction_identifier properties: network_identifier: $ref: '#/components/schemas/NetworkIdentifier' block_identifier: $ref: '#/components/schemas/BlockIdentifier' transaction_identifier: $ref: '#/components/schemas/TransactionIdentifier' BlockTransactionResponse: description: | A BlockTransactionResponse contains information about a block transaction. type: object required: - transaction properties: transaction: $ref: '#/components/schemas/Transaction' MempoolResponse: description: | A MempoolResponse contains all transaction identifiers in the mempool for a particular network_identifier. type: object required: - transaction_identifiers properties: transaction_identifiers: type: array items: $ref: '#/components/schemas/TransactionIdentifier' MempoolTransactionRequest: description: | A MempoolTransactionRequest is utilized to retrieve a transaction from the mempool. type: object required: - network_identifier - transaction_identifier properties: network_identifier: $ref: '#/components/schemas/NetworkIdentifier' transaction_identifier: $ref: '#/components/schemas/TransactionIdentifier' MempoolTransactionResponse: description: | 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). type: object required: - transaction properties: transaction: $ref: '#/components/schemas/Transaction' metadata: type: object example: descendant_fees: 123923 ancestor_count: 2 MetadataRequest: description: | A MetadataRequest is utilized in any request where the only argument is optional metadata. type: object properties: metadata: type: object NetworkListResponse: description: | A NetworkListResponse contains all NetworkIdentifiers that the node can serve information for. type: object required: - network_identifiers properties: network_identifiers: type: array items: $ref: '#/components/schemas/NetworkIdentifier' NetworkRequest: description: | A NetworkRequest is utilized to retrieve some data specific exclusively to a NetworkIdentifier. type: object required: - network_identifier properties: network_identifier: $ref: '#/components/schemas/NetworkIdentifier' metadata: type: object NetworkStatusResponse: description: | 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. type: object required: - current_block_identifier - current_block_timestamp - genesis_block_identifier properties: current_block_identifier: $ref: '#/components/schemas/BlockIdentifier' current_block_timestamp: $ref: '#/components/schemas/Timestamp' genesis_block_identifier: $ref: '#/components/schemas/BlockIdentifier' oldest_block_identifier: $ref: '#/components/schemas/BlockIdentifier' sync_status: $ref: '#/components/schemas/SyncStatus' peers: type: array items: $ref: '#/components/schemas/Peer' NetworkOptionsResponse: description: | NetworkOptionsResponse contains information about the versioning of the node and the allowed operation statuses, operation types, and errors. type: object required: - version - allow properties: version: $ref: '#/components/schemas/Version' allow: $ref: '#/components/schemas/Allow' ConstructionMetadataRequest: description: | 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. type: object required: - network_identifier properties: network_identifier: $ref: '#/components/schemas/NetworkIdentifier' options: description: | Some 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. type: object public_keys: type: array items: $ref: '#/components/schemas/PublicKey' ConstructionMetadataResponse: description: | 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. type: object required: - metadata properties: metadata: type: object example: account_sequence: 23 recent_block_hash: "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5" suggested_fee: type: array items: $ref: '#/components/schemas/Amount' ConstructionDeriveRequest: description: | 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). type: object required: - network_identifier - public_key properties: network_identifier: $ref: '#/components/schemas/NetworkIdentifier' public_key: $ref: '#/components/schemas/PublicKey' metadata: type: object ConstructionDeriveResponse: description: | ConstructionDeriveResponse is returned by the `/construction/derive` endpoint. type: object properties: address: type: string description: | [DEPRECATED by `account_identifier` in `v1.4.4`] Address in network-specific format. account_identifier: $ref: '#/components/schemas/AccountIdentifier' metadata: type: object ConstructionPreprocessRequest: description: | 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`. type: object required: - network_identifier - operations properties: network_identifier: $ref: '#/components/schemas/NetworkIdentifier' operations: type: array items: $ref: '#/components/schemas/Operation' metadata: type: object ConstructionPreprocessResponse: description: | 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. type: object properties: options: type: object description: | The options that will be sent directly to `/construction/metadata` by the caller. required_public_keys: type: array items: $ref: '#/components/schemas/AccountIdentifier' ConstructionPreprocessOperationsRequest: description: | ConstructionPreprocessOperationsRequest is passed to the `/construction/preprocess-operations` endpoint so that a Rosetta implementation can parse high-level transaction construction operations into Rosetta operations. This endpoint allows the Rosetta API to handle operation parsing that might not be supported by the local OperationSelector. type: object required: - network_identifier - construct_op properties: network_identifier: $ref: '#/components/schemas/NetworkIdentifier' from_address: type: string description: | The address that will be the source of the transaction. This is optional and may not be required for all construct operations. construct_op: type: string description: | The high-level operation type to be parsed (e.g. "transfer", "stake", "delegate"). options: type: object description: | Operation-specific parameters as a JSON object. The format of this object is specific to the construct_op type and the blockchain implementation. ConstructionPreprocessOperationsResponse: description: | ConstructionPreprocessOperationsResponse contains the parsed operations and related information returned by the Rosetta implementation after processing the high-level transaction construction request. This response mirrors the return values of ParseTransactionConstructOp method to maintain compatibility. type: object required: - operations properties: operations: type: array items: $ref: '#/components/schemas/Operation' description: | The parsed operations that result from processing the construct_op. max_fee: $ref: '#/components/schemas/Amount' description: | Maximum fee for this transaction (optional). metadata: type: string format: byte description: | Metadata as raw JSON bytes, matching ParseTransactionConstructOp return format for compatibility with existing workflows. ConstructionPayloadsRequest: description: | 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. type: object required: - network_identifier - operations properties: network_identifier: $ref: '#/components/schemas/NetworkIdentifier' operations: type: array items: $ref: '#/components/schemas/Operation' metadata: type: object public_keys: type: array items: $ref: '#/components/schemas/PublicKey' ConstructionPayloadsResponse: description: | 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. type: object required: - unsigned_transaction - payloads properties: unsigned_transaction: type: string payloads: type: array items: $ref: '#/components/schemas/SigningPayload' ConstructionCombineRequest: description: | 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. type: object required: - network_identifier - unsigned_transaction - signatures properties: network_identifier: $ref: '#/components/schemas/NetworkIdentifier' unsigned_transaction: type: string signatures: type: array items: $ref: '#/components/schemas/Signature' ConstructionCombineResponse: description: | ConstructionCombineResponse is returned by `/construction/combine`. The network payload will be sent directly to the `construction/submit` endpoint. type: object required: - signed_transaction properties: signed_transaction: type: string ConstructionParseRequest: description: | ConstructionParseRequest is the input to the `/construction/parse` endpoint. It allows the caller to parse either an unsigned or signed transaction. type: object required: - network_identifier - signed - transaction properties: network_identifier: $ref: '#/components/schemas/NetworkIdentifier' signed: type: boolean description: | Signed is a boolean indicating whether the transaction is signed. transaction: type: string description: | This must be either the unsigned transaction blob returned by `/construction/payloads` or the signed transaction blob returned by `/construction/combine`. ConstructionParseResponse: description: | 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`. type: object required: - operations properties: operations: type: array items: $ref: '#/components/schemas/Operation' signers: description: | [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. type: array items: type: string account_identifier_signers: type: array items: $ref: '#/components/schemas/AccountIdentifier' metadata: type: object ConstructionHashRequest: description: | ConstructionHashRequest is the input to the `/construction/hash` endpoint. type: object required: - network_identifier - signed_transaction properties: network_identifier: $ref: '#/components/schemas/NetworkIdentifier' signed_transaction: type: string ConstructionSubmitRequest: description: | The transaction submission request includes a signed transaction. type: object required: - network_identifier - signed_transaction properties: network_identifier: $ref: '#/components/schemas/NetworkIdentifier' signed_transaction: type: string TransactionIdentifierResponse: description: | TransactionIdentifierResponse contains the transaction_identifier of a transaction that was submitted to either `/construction/hash` or `/construction/submit`. type: object required: - transaction_identifier properties: transaction_identifier: $ref: '#/components/schemas/TransactionIdentifier' metadata: type: object CallRequest: description: | CallRequest is the input to the `/call` endpoint. type: object required: - network_identifier - method - parameters properties: network_identifier: $ref: '#/components/schemas/NetworkIdentifier' method: type: string description: | Method 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`. example: "eth_call" parameters: type: object description: | Parameters is some network-specific argument for a method. It is up to the caller to determine which parameters to provide when invoking `/call`. example: block_number: 23 address: "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5" CallResponse: description: | CallResponse contains the result of a `/call` invocation. type: object required: - result - idempotent properties: result: type: object description: | Result 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. example: count: 1000 idempotent: type: boolean description: | Idempotent 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. EventsBlocksRequest: description: | EventsBlocksRequest is utilized to fetch a sequence of BlockEvents indicating which blocks were added and removed from storage to reach the current state. type: object required: - network_identifier properties: network_identifier: $ref: '#/components/schemas/NetworkIdentifier' offset: description: | 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. type: integer format: int64 minimum: 0 example: 5 limit: description: | limit is the maximum number of events to fetch in one call. The implementation may return <= limit events. type: integer format: int64 minimum: 0 example: 5 EventsBlocksResponse: description: | EventsBlocksResponse contains an ordered collection of BlockEvents and the max retrievable sequence. type: object required: - max_sequence - events properties: max_sequence: description: | max_sequence is the maximum available sequence number to fetch. type: integer format: int64 minimum: 0 example: 5 events: type: array description: | events 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. items: $ref: '#/components/schemas/BlockEvent' SearchTransactionsRequest: description: | SearchTransactionsRequest is used to search for transactions matching a set of provided conditions in canonical blocks. type: object required: - network_identifier properties: network_identifier: $ref: '#/components/schemas/NetworkIdentifier' operator: $ref: '#/components/schemas/Operator' max_block: description: | 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). type: integer format: int64 minimum: 0 example: 5 offset: description: | 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. type: integer format: int64 minimum: 0 example: 5 limit: description: | limit is the maximum number of transactions to return in one call. The implementation may return <= limit transactions. type: integer format: int64 minimum: 0 example: 5 transaction_identifier: $ref: '#/components/schemas/TransactionIdentifier' account_identifier: $ref: '#/components/schemas/AccountIdentifier' coin_identifier: $ref: '#/components/schemas/CoinIdentifier' currency: $ref: '#/components/schemas/Currency' status: type: string description: | status is the network-specific operation type. example: "reverted" type: type: string description: | type is the network-specific operation type. example: "transfer" address: type: string description: | address is AccountIdentifier.Address. This is used to get all transactions related to an AccountIdentifier.Address, regardless of SubAccountIdentifier. example: "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347" success: type: boolean description: | success is a synthetic condition populated by parsing network-specific operation statuses (using the mapping provided in `/network/options`). SearchTransactionsResponse: description: | SearchTransactionsResponse contains an ordered collection of BlockTransactions that match the query in SearchTransactionsRequest. These BlockTransactions are sorted from most recent block to oldest block. type: object required: - transactions - total_count properties: transactions: type: array description: | transactions 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. items: $ref: '#/components/schemas/BlockTransaction' total_count: description: | 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. type: integer format: int64 minimum: 0 example: 5 next_offset: description: | 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. type: integer format: int64 minimum: 0 example: 5 # Miscellaneous Error: $ref: 'models/Error.yaml'