api.yaml

# 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.4.11
  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/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/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'

    # 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
    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
        - peers
      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`.

        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).
      type: object
      required:
        - network_identifier
        - operations
      properties:
        network_identifier:
          $ref: '#/components/schemas/NetworkIdentifier'
        operations:
          type: array
          items:
            $ref: '#/components/schemas/Operation'
        metadata:
          type: object
        max_fee:
          type: array
          items:
            $ref: '#/components/schemas/Amount'
        suggested_fee_multiplier:
          type: number
          format: double
          minimum: 0.0
    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'
    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'