# yaml-language-server: $schema=https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.1/schema.json

openapi: 3.0.3
info:
  title: Oasis Nexus API V1
  description: An API for accessing indexed data from the Oasis Network.
  version: 0.1.0

servers:
  - url: http://nexus.oasis.io/v1
    description: Mainnet index endpoint.
  - url: http://testnet.nexus.oasis.io/v1
    description: Testnet index endpoint.

x-query-params:
  - &offset
    in: query
    name: offset
    schema:
      type: integer
      format: uint64
      default: 0
    description: |
      The number of items to skip before starting to collect the result set.
  - &limit
    in: query
    name: limit
    schema:
      type: integer
      format: uint64
      default: 100
      minimum: 1
      maximum: 1000
    description: |
      The maximum numbers of items to return.
  - &height
    in: query
    name: height
    schema:
      type: integer
      format: int64
    description: |
      The block height from which to query state. Oasis Nexus does not
      make any guarantees about availability of historical state data.
  - &runtime
    in: path
    name: runtime
    required: true
    schema:
      allOf: [$ref: '#/components/schemas/Runtime']
    description: |
      The runtime which to query.
  - &window_size_seconds
    in: query
    name: window_size_seconds
    schema:
      type: integer
      format: uint32
      default: 86400
    description: |
      The size of windows into which the statistic is grouped, in seconds.
      The backend supports a limited number of window sizes: 300 (5 minutes) and
      86400 (1 day). Requests with other values may be rejected.
  - &window_step_seconds
    in: query
    name: window_step_seconds
    schema:
      type: integer
      format: uint32
      default: 86400
    description: |
      The size of the step between returned statistic windows, in seconds.
      The backend supports a limited number of step sizes: 300 (5 minutes) and
      86400 (1 day). Requests with other values may be rejected.

x-examples:
  block-height:
    - &block_height_1 8048956
    - &block_height_2 8049555
  block-hash:
    - &block_hash_1 '0a29ac21fa69bb9e43e5cb25d10826ff3946f1ce977e82f99a2614206a50765c'
  tx-hash:
    - &tx_hash_1 '0d0531d6b8a468c07440182b1cdda517f5a076d69fb2199126a83082ecfc0f41'
  tx-body:
    - &tx_body_1 '{"amount":"1000000000","account":"oasis1qpg2xuz46g53737343r20yxeddhlvc2ldqsjh70p"}'
  epoch:
    - &epoch_1 8048956
    - &epoch_2 8048966
  event-type:
    - &event_type_1 'staking.escrow.take'
  entity-id:
    - &entity_id_1 'gb8SHLeDc69Elk7OTfqhtVgE2sqxrBCDQI84xKR+Bjg='
  node-id:
    - &node_id_1 'lbxs4hlud9XNloIOdhJPaCahd7HtiY8QATCgGnFfCM0='
  staking-address:
    - &staking_address_1 'oasis1qpg2xuz46g53737343r20yxeddhlvc2ldqsjh70p'
    - &staking_address_2 'oasis1qprtzrg97jk0wxnqkhxwyzy5qys47r7alvfl3fcg'
  eth-address:
    - &eth_address_1 0xd8A2Ae03f6Edd58999a0F1005db7a6532F2AA79e
  proposal-id:
    - &proposal_id_1 1
  proposal-state:
    - &proposal_state_1 'active'
  runtime-block-round:
    - &runtime_block_round_1 3283246
  runtime-block-hash:
    - &runtime_block_hash_1 '21c243cd34bedfc234f1b45615d10a868f0655f59578f063a7d2fc8c6e5b4009'
  runtime-event-type:
    - &runtime_event_type_1 'consensus_accounts.deposit'
  iso-timestamp:
    - &iso_timestamp_1 '2022-03-01T00:00:00Z'
    - &iso_timestamp_2 '2019-04-01T00:00:00Z'
    - &iso_timestamp_3 '2022-10-15T00:05:34Z'
  time-duration:
    - &time_duration_1 '72h3m0.5s'

x-err-responses:
  common-errors: &common_error_responses
    '400':
      $ref: '#/components/responses/HumanReadableError'
    '404':
      $ref: '#/components/responses/NotFoundError'
    '500':
      $ref: '#/components/responses/HumanReadableError'

paths:
  /:
    get:
      operationId: getStatus
      summary: Returns the status of indexing.
      responses:
        '200':
          description: A JSON object containing status metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        <<: *common_error_responses

  /consensus/blocks:
    get:
      summary: Returns a list of consensus blocks, sorted from most to least recent.
      parameters:
        - *limit
        - *offset
        - in: query
          name: from
          schema:
            type: integer
            format: int64
          description: A filter on minimum block height, inclusive.
          example: *block_height_1
        - in: query
          name: to
          schema:
            type: integer
            format: int64
          description: A filter on maximum block height, inclusive.
          example: *block_height_2
        - in: query
          name: after
          schema:
            type: string
            format: date-time
          description: A filter on minimum block time, inclusive.
          example: *iso_timestamp_1
        - in: query
          name: before
          schema:
            type: string
            format: date-time
          description: A filter on maximum block time, exclusive.
          example: *iso_timestamp_2
        - in: query
          name: hash
          schema:
            type: string
          description: A filter on the block hash.
          example: *block_hash_1
      responses:
        '200':
          description: A JSON object containing a list of consensus blocks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockList'
        <<: *common_error_responses

  /consensus/blocks/{height}:
    get:
      summary: Returns a consensus block.
      parameters:
        - in: path
          name: height
          required: true
          schema:
            type: integer
            format: int64
          description: The block height of the block to return.
          example: *block_height_1
      responses:
        '200':
          description: A JSON object containing a consensus block.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Block'
        <<: *common_error_responses

  /consensus/transactions:
    get:
      summary: Returns a list of consensus transactions.
      parameters:
        - *limit
        - *offset
        - in: query
          name: block
          schema:
            type: integer
            format: int64
          description: A filter on block height.
          example: *block_height_1
        - in: query
          name: method
          schema:
            allOf: [$ref: '#/components/schemas/ConsensusTxMethod']
          description: A filter on transaction method.
        - in: query
          name: sender
          schema:
            allOf: [$ref: '#/components/schemas/StakingAddress']
          description: A filter on transaction sender.
        - in: query
          name: rel
          schema:
            type: string
          description: A filter on related accounts.
          example: *staking_address_1
        - in: query
          name: minFee
          schema:
            allOf: [$ref: '#/components/schemas/TextBigInt']
          description: A filter on minimum transaction fee, inclusive.
          example: "1000"
        - in: query
          name: maxFee
          schema:
            allOf: [$ref: '#/components/schemas/TextBigInt']
          description: A filter on maximum transaction fee, inclusive.
          example: "100000000000000000000000"
        - in: query
          name: code
          schema:
            type: integer
          description: A filter on transaction status code.
        - in: query
          name: after
          schema:
            type: string
            format: date-time
          description: A filter on minimum transaction time, inclusive.
          example: *iso_timestamp_1
        - in: query
          name: before
          schema:
            type: string
            format: date-time
          description: A filter on maximum transaction time, exclusive.
          example: *iso_timestamp_2
      responses:
        '200':
          description: |
            A JSON object containing a list of consensus transactions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionList'
        <<: *common_error_responses

  /consensus/transactions/{tx_hash}:
    get:
      summary: Returns a consensus transaction.
      parameters:
        - in: path
          name: tx_hash
          required: true
          schema:
            type: string
          description: The transaction hash of the transaction to return.
          example: *tx_hash_1
      responses:
        '200':
          description: A JSON object containing a consensus transaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
        <<: *common_error_responses

  /consensus/events:
    get:
      summary: Returns a list of consensus events.
      parameters:
        - *limit
        - *offset
        - in: query
          name: block
          schema:
            type: integer
            format: int64
          description: A filter on block height.
          example: *block_height_1
        - in: query
          name: tx_index
          schema:
            type: integer
            format: int32
          description: |
            A filter on transaction index. The returned events all need to originate
            from a transaction that appeared in `tx_index`-th position in the block.
            It is invalid to specify this filter without also specifying a `block`.
            Specifying `tx_index` and `block` is an alternative to specifying `tx_hash`;
            either works to fetch events from a specific transaction.
          example: 3
        - in: query
          name: tx_hash
          schema:
            type: string
          description: |
            A filter on the hash of the transaction that originated the events.
            Specifying `tx_index` and `block` is an alternative to specifying `tx_hash`;
            either works to fetch events from a specific transaction.
          example: *tx_hash_1
        - in: query
          name: rel
          schema:
            allOf: [$ref: '#/components/schemas/StakingAddress']
          description: |
            A filter on related accounts. Every returned event will refer to
            this account. For example, for a `Transfer` event, this will be the
            the sender or the recipient of tokens.
        - in: query
          name: type
          schema:
            allOf: [$ref: '#/components/schemas/ConsensusEventType']
          description: A filter on the event type.
          example: *event_type_1
      responses:
        '200':
          description: |
            Consensus events matching the filters, sorted by most recent first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsensusEventList'
        <<: *common_error_responses

  /consensus/entities:
    get:
      summary: Returns a list of entities registered at the consensus layer.
      parameters:
        - *limit
        - *offset
      responses:
        '200':
          description: |
            A JSON object containing a list of entities registered
            at the consensus layer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityList'
        <<: *common_error_responses

  /consensus/entities/{entity_id}:
    get:
      summary: Returns an entity registered at the consensus layer.
      parameters:
        - in: path
          name: entity_id
          required: true
          schema:
            allOf: [$ref: '#/components/schemas/Ed25519PubKey']
          description: The entity ID of the entity to return.
      responses:
        '200':
          description: |
            A JSON object containing an entity registered
            at the consensus layer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entity'
        <<: *common_error_responses

  /consensus/entities/{entity_id}/nodes:
    get:
      summary: Returns a list of nodes registered at the consensus layer.
      parameters:
        - *limit
        - *offset
        - in: path
          name: entity_id
          required: true
          schema:
            allOf: [$ref: '#/components/schemas/Ed25519PubKey']
          description: |
            The entity ID of the controlling entity of the nodes to return.
      responses:
        '200':
          description: |
            A JSON object containing a list of nodes registered at the consensus layer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodeList'
        <<: *common_error_responses

  /consensus/entities/{entity_id}/nodes/{node_id}:
    get:
      summary: Returns a node registered at the consensus layer.
      parameters:
        - in: path
          name: entity_id
          required: true
          schema:
            allOf: [$ref: '#/components/schemas/Ed25519PubKey']
          description: |
            The entity ID of the entity controlling the node to return.
          example: *entity_id_1
        - in: path
          name: node_id
          required: true
          schema:
            allOf: [$ref: '#/components/schemas/Ed25519PubKey']
          description: The node ID of the node to return.
      responses:
        '200':
          description: |
            A JSON object containing a node registered at the consensus layer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Node'
        <<: *common_error_responses

  /consensus/validators:
    get:
      summary: Returns a list of validators registered at the consensus layer.
      parameters:
        - *limit
        - *offset
      responses:
        '200':
          description: |
            A JSON object containing a list of validators registered
            at the consensus layer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidatorList'
        <<: *common_error_responses

  /consensus/validators/{entity_id}:
    get:
      summary: Returns a validator registered at the consensus layer.
      parameters:
        - in: path
          name: entity_id
          required: true
          schema:
            allOf: [$ref: '#/components/schemas/Ed25519PubKey']
          description: The entity ID of the entity to return.
      responses:
        '200':
          description: |
            A JSON object containing a validator registered at the
            consensus layer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Validator'
        <<: *common_error_responses

  /consensus/accounts:
    get:
      summary: Returns a list of consensus layer accounts.
      parameters:
        - *limit
        - *offset
        - in: query
          name: minAvailable
          schema:
            allOf: [$ref: '#/components/schemas/TextBigInt']
          description: A filter on the minimum available account balance.
        - in: query
          name: maxAvailable
          schema:
            allOf: [$ref: '#/components/schemas/TextBigInt']
          description: A filter on the maximum available account balance.
        - in: query
          name: minEscrow
          schema:
            allOf: [$ref: '#/components/schemas/TextBigInt']
          description: A filter on the minimum active escrow account balance.
        - in: query
          name: maxEscrow
          schema:
            allOf: [$ref: '#/components/schemas/TextBigInt']
          description: A filter on the maximum active escrow account balance.
        - in: query
          name: minDebonding
          schema:
            allOf: [$ref: '#/components/schemas/TextBigInt']
          description: A filter on the minimum debonding account balance.
        - in: query
          name: maxDebonding
          schema:
            allOf: [$ref: '#/components/schemas/TextBigInt']
          description: A filter on the maximum debonding account balance.
        - in: query
          name: minTotalBalance
          schema:
            allOf: [$ref: '#/components/schemas/TextBigInt']
          description: A filter on the minimum total account balance.
        - in: query
          name: maxTotalBalance
          schema:
            allOf: [$ref: '#/components/schemas/TextBigInt']
          description: A filter on the maximum total account balance.
      responses:
        '200':
          description: |
            A JSON object containing a list of consensus layer accounts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountList'
        <<: *common_error_responses

  /consensus/accounts/{address}:
    get:
      summary: Returns a consensus layer account.
      parameters:
        - in: path
          name: address
          required: true
          schema:
            allOf: [$ref: '#/components/schemas/StakingAddress']
          description: The staking address of the account to return.
      responses:
        '200':
          description: A JSON object containing a consensus layer account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        <<: *common_error_responses

  /consensus/accounts/{address}/delegations:
    get:
      summary: Returns an account's delegations.
      parameters:
        - *limit
        - *offset
        - in: path
          name: address
          required: true
          schema:
            allOf: [$ref: '#/components/schemas/StakingAddress']
          description: The staking address of the account that delegated.
      responses:
        '200':
          description: A JSON object containing a list of delegations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DelegationList'
        <<: *common_error_responses

  /consensus/accounts/{address}/delegations_to:
    get:
      summary: Returns a list of delegations to an account.
      parameters:
        - *limit
        - *offset
        - in: path
          name: address
          required: true
          schema:
            allOf: [$ref: '#/components/schemas/StakingAddress']
          description: The staking address of the account that is being delegated to.
      responses:
        '200':
          description: A JSON object containing a list of delegations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DelegationList'
        <<: *common_error_responses

  /consensus/accounts/{address}/debonding_delegations:
    get:
      summary: Returns an account's debonding delegations.
      parameters:
        - *limit
        - *offset
        - in: path
          name: address
          required: true
          schema:
            allOf: [$ref: '#/components/schemas/StakingAddress']
          description: The staking address of the account that delegated.
      responses:
        '200':
          description: A JSON object containing a list of debonding delegations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DebondingDelegationList'
        <<: *common_error_responses

  /consensus/accounts/{address}/debonding_delegations_to:
    get:
      summary: Returns a list of debonding delegations to an account.
      parameters:
        - *limit
        - *offset
        - in: path
          name: address
          required: true
          schema:
            allOf: [$ref: '#/components/schemas/StakingAddress']
          description: The staking address of the that is being delegated to.
      responses:
        '200':
          description: A JSON object containing a list of debonding delegations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DebondingDelegationList'
        <<: *common_error_responses

  /consensus/epochs:
    get:
      summary: Returns a list of consensus epochs.
      parameters:
        - *limit
        - *offset
      responses:
        '200':
          description: A JSON object containing a list of consensus epochs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpochList'
        <<: *common_error_responses

  /consensus/epochs/{epoch}:
    get:
      summary: Returns a consensus epoch.
      parameters:
        - in: path
          name: epoch
          required: true
          schema:
            type: integer
            format: int64
          description: The epoch number of the epoch to return.
          example: *epoch_1
      responses:
        '200':
          description: A JSON object containing a consensus epoch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Epoch'
        <<: *common_error_responses

  /consensus/proposals:
    get:
      summary: Returns a list of governance proposals.
      parameters:
        - *limit
        - *offset
        - in: query
          name: submitter
          schema:
            allOf: [$ref: '#/components/schemas/StakingAddress']
          description: Filter on the submitter of the proposal.
        - in: query
          name: state
          schema:
            allOf: [$ref: '#/components/schemas/ProposalState']
          description: Filter on the state of the proposal.
          example: *proposal_state_1
      responses:
        '200':
          description: A JSON object containing a list of governance proposals.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProposalList'
        <<: *common_error_responses

  /consensus/proposals/{proposal_id}:
    get:
      summary: Returns a governance proposal.
      parameters:
        - in: path
          name: proposal_id
          required: true
          schema:
            type: integer
            format: uint64
          description: The unique identifier of the proposal to return.
          example: *proposal_id_1
      responses:
        '200':
          description: A JSON object containing a governance proposal.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Proposal'
        <<: *common_error_responses

  /consensus/proposals/{proposal_id}/votes:
    get:
      summary: Returns a list of votes for a governance proposal.
      parameters:
        - *limit
        - *offset
        - in: path
          name: proposal_id
          required: true
          schema:
            type: integer
            format: uint64
          description: |
            The unique identifier of the proposal for which votes are returned.
          example: *proposal_id_1
      responses:
        '200':
          description: |
            A JSON object containing a list of votes for a governance proposal.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProposalVotes'
        <<: *common_error_responses

  /{runtime}/blocks:
    get:
      summary: Returns a list of Runtime blocks.
      parameters:
        - *limit
        - *offset
        - *runtime
        - in: query
          name: from
          schema:
            type: integer
            format: int64
          description: A filter on minimum block height, inclusive.
          example: *block_height_1
        - in: query
          name: to
          schema:
            type: integer
            format: int64
          description: A filter on maximum block height, inclusive.
          example: *block_height_2
        - in: query
          name: after
          schema:
            type: string
            format: date-time
          description: A filter on minimum block time, inclusive.
          example: *iso_timestamp_1
        - in: query
          name: before
          schema:
            type: string
            format: date-time
          description: A filter on maximum block time, exclusive.
          example: *iso_timestamp_2
        - in: query
          name: hash
          schema:
            type: string
          description: A filter on the block hash.
          example: *block_hash_1
      responses:
        '200':
          description: A JSON object containing a list of Runtime blocks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeBlockList'
        <<: *common_error_responses

  /{runtime}/transactions:
    get:
      summary: Returns a list of Runtime transactions.
      parameters:
        - *limit
        - *offset
        - *runtime
        - in: query
          name: block
          schema:
            type: integer
            format: int64
          description: A filter on block round.
          example: *runtime_block_round_1
        - in: query
          name: after
          schema:
            type: string
            format: date-time
          description: A filter on minimum transaction time, inclusive.
          example: *iso_timestamp_1
        - in: query
          name: before
          schema:
            type: string
            format: date-time
          description: A filter on maximum transaction time, exclusive.
          example: *iso_timestamp_2
        - in: query
          name: rel
          schema:
            allOf: [$ref: '#/components/schemas/StakingAddress']
          # TODO: Implement autodetection of Eth addresses, get rid of last sentence.
          description: |
            A filter on related accounts. Every returned transaction will refer to
            this account in a way. For example, for an `accounts.Transfer` tx, this will be
            the sender or the recipient of tokens.
            Nexus detects related accounts inside EVM transactions and events on a
            best-effort basis. For example, it inspects ERC20 methods inside `evm.Call` txs.
            However, you must provide the Oasis-style derived address here, not the Eth address.
            See `AddressPreimage` for more info on Oasis-style vs Eth addresses.
      responses:
        '200':
          description: |
            A JSON object containing a list of Runtime transactions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeTransactionList'
        <<: *common_error_responses

  /{runtime}/transactions/{tx_hash}:
    get:
      summary: Returns runtime transactions with the given transaction hash.
      parameters:
        - *runtime
        - in: path
          name: tx_hash
          required: true
          schema:
            type: string
          description: |
            The transaction hash of the transaction(s) to return. This can be an
            Ethereum transaction hash; the query will compare against both a
            transaction's regular tx_hash and eth_tx_hash (if it exists).
            This endpoint can return multiple transactions in extremely rare cases,
            e.g. when a hash matches multiple Oasis runtime transactions or both
            an Oasis runtime transaction and the eth_tx_hash of an evm-transaction.
          example: *tx_hash_1
      responses:
        '200':
          description: The requested runtime transactions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeTransactionList'
        <<: *common_error_responses

  /{runtime}/events:
    get:
      summary: Returns a list of runtime events.
      parameters:
        - *limit
        - *offset
        - *runtime
        - in: query
          name: block
          schema:
            type: integer
            format: int64
          description: A filter on block round.
          example: *runtime_block_round_1
        - in: query
          name: tx_index
          schema:
            type: integer
            format: int32
          description: |
            A filter on transaction index. The returned events all need to originate
            from a transaction that appeared in `tx_index`-th position in the block.
            It is invalid to specify this filter without also specifying a `block`.
            Specifying `tx_index` and `round` is an alternative to specifying `tx_hash`;
            either works to fetch events from a specific transaction.
          example: 3
        - in: query
          name: tx_hash
          schema:
            type: string
          description: |
            A filter on the hash of the transaction that originated the events.
            Specifying `tx_index` and `round` is an alternative to specifying `tx_hash`;
            either works to fetch events from a specific transaction.
            This can be an Ethereum transaction hash; the query will compare against
            both a transaction's regular tx_hash and eth_tx_hash (if it exists).
          example: *tx_hash_1
        - in: query
          name: type
          schema:
            allOf: [$ref: '#/components/schemas/RuntimeEventType']
          description: A filter on the event type.
        - in: query
          name: rel
          schema:
            type: string
          description: |
            A filter on related accounts. Every returned event will refer to
            this account. For example, for a `accounts.Transfer` event, this will be
            the sender or the recipient of tokens.
          example: *staking_address_1
        - in: query
          name: evm_log_signature
          schema:
            type: string
          description: |
            A filter on the evm log signatures.
            Note: The filter will only match on parsed (verified) EVM events.
          example: '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'
        - in: query
          name: contract_address
          schema:
            type: string
          description: |
            A filter on a smart contract. Every returned event will have been
            emitted by the contract at this Oasis address.
          example: *staking_address_1
        - in: query
          name: nft_id
          schema:
            type: string
          example: "999"
          description: |
            A filter on NFT events. Every returned event will be specifically
            about this NFT instance ID. You must specify the contract_address
            filter with this filter.
            Currently this only supports ERC-721 Transfer events.
            This may expand to support other event types in the future.
            If you want only ERC-721 Transfer events, specify
            evm_log_signature=ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef
            to avoid inadvertently getting other event types if they are
            supported later.
            Using an evm_log_signature filter with this set to any other value
            will match no events.
      responses:
        '200':
          description: |
            Runtime events matching the filters, sorted by most recent first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeEventList'
        <<: *common_error_responses

  /{runtime}/evm_tokens:
    get:
      summary: Returns a list of EVM (ERC-20, ...) tokens on the runtime.
      parameters:
        - *limit
        - *offset
        - *runtime
        - in: query
          name: name
          schema:
            type: string
          description: A filter on the name, the name or symbol must contain this value as a substring.
      responses:
        '200':
          description: The requested tokens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvmTokenList'
        <<: *common_error_responses

  /{runtime}/evm_tokens/{address}:
    get:
      summary: Returns info on an EVM (ERC-20, ...) token on the runtime.
      parameters:
        - *runtime
        - in: path
          name: address
          required: true
          schema:
            allOf: [$ref: '#/components/schemas/StakingAddress']
          description: The staking address of the token contract.
      responses:
        '200':
          description: The requested token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvmToken'
        <<: *common_error_responses

  /{runtime}/evm_tokens/{address}/holders:
    get:
      summary: |
        Returns the list of holders of an EVM (ERC-20, ...) token.
        This endpoint does not verify that `address` is actually an EVM token; if it is not, it will simply return an empty list.
      parameters:
        - *limit
        - *offset
        - *runtime
        - in: path
          name: address
          required: true
          schema:
            allOf: [$ref: '#/components/schemas/StakingAddress']
          description: The staking address of the token contract for which to return the holders.
      responses:
        '200':
          description: The requested holders.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenHolderList'
        <<: *common_error_responses

  /{runtime}/evm_tokens/{address}/nfts:
    get:
      summary: |
        Returns the list of non-fungible token (NFT) instances of an EVM (ERC-721, ...) token.
        This endpoint does not verify that `address` is actually an EVM token; if it is not, it will simply return an empty list.
      parameters:
        - *limit
        - *offset
        - *runtime
        - in: path
          name: address
          required: true
          schema:
            allOf: [$ref: '#/components/schemas/StakingAddress']
          description: The staking address of the token contract for which to return the NFT instances.
      responses:
        '200':
          description: The requested instances.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvmNftList'
        <<: *common_error_responses

  /{runtime}/evm_tokens/{address}/nfts/{id}:
    get:
      summary: |
        Returns the non-fungible token (NFT) instance of an EVM (ERC-721, ...) token.
      parameters:
        - *runtime
        - in: path
          name: address
          required: true
          schema:
            allOf: [$ref: '#/components/schemas/StakingAddress']
          description: The staking address of the token contract of the NFT instance.
        - in: path
          name: id
          required: true
          schema:
            allOf: [$ref: '#/components/schemas/TextBigInt']
          description: The ID of the NFT instance.
      responses:
        '200':
          description: The requested instances.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvmNft'
        <<: *common_error_responses

  /{runtime}/accounts/{address}:
    get:
      summary: Returns a runtime account.
      parameters:
        - *runtime
        - in: path
          name: address
          required: true
          schema:
            allOf: [$ref: '#/components/schemas/StakingAddress']
          description: The staking address of the account to return.
      responses:
        '200':
          description: A JSON object containing a runtime layer account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeAccount'
        <<: *common_error_responses

  /{runtime}/accounts/{address}/nfts:
    get:
      summary: |
        Returns the list of non-fungible token (NFT) instances owned by an account.
      parameters:
        - *limit
        - *offset
        - *runtime
        - in: path
          name: address
          required: true
          schema:
            allOf: [$ref: '#/components/schemas/StakingAddress']
          description: The staking address of the owner of the NFT instances.
        - in: query
          name: token_address
          schema:
            allOf: [$ref: '#/components/schemas/StakingAddress']
          description: Only return NFT instances from the token contract at the given staking address.
      responses:
        '200':
          description: The requested instances.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvmNftList'
        <<: *common_error_responses

  /{runtime}/status:
    get:
      summary: Returns the runtime status.
      parameters:
        - *runtime
      responses:
        '200':
          description: A JSON object containing latest runtime status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeStatus'
        <<: *common_error_responses

  /{layer}/stats/tx_volume:
    get:
      summary: |
        Returns a timeline of the transaction volume at the chosen granularity,
        for either consensus or one of the paratimes.
      parameters:
        - *limit
        - *offset
        - *window_size_seconds
        - *window_step_seconds
        - in: path
          name: layer
          required: true
          schema:
            allOf: [$ref: '#/components/schemas/Layer']
          description: |
            The layer for which to return the transaction volume timeline.
      responses:
        '200':
          description: |
            A JSON object containing a list of TPS values for each interval.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TxVolumeList'
        <<: *common_error_responses

  /{layer}/stats/active_accounts:
    get:
      summary: |
        Returns a (sliding) timeline of the recorded daily unique active accounts for
        either consensus or one of the paratimes.
      parameters:
        - *limit
        - *offset
        - *window_step_seconds
        - in: path
          name: layer
          required: true
          schema:
            allOf: [$ref: '#/components/schemas/Layer']
          description: |
            The layer for which to return the active accounts timeline.
      responses:
        '200':
          description: |
            A JSON object containing a list of unique active accounts values for each interval.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActiveAccountsList'
        <<: *common_error_responses

components:
  schemas:
    Layer:
      type: string
      # NOTE: Change IsValid() in util.go if you change this.
      # https://github.com/oasisprotocol/nexus/blob/v0.0.16/api/v1/types/util.go#L40
      enum: [emerald, sapphire, pontusx, cipher, consensus]

    Runtime:
      type: string
      # NOTE: Change IsValid() in util.go if you change this.
      # https://github.com/oasisprotocol/nexus/blob/v0.0.16/api/v1/types/util.go#L49
      enum: [emerald, sapphire, pontusx, cipher]

    StakingAddress:
      type: string
      pattern: '^oasis1[a-z0-9]{40}$'
      example: "oasis1qpg2xuz46g53737343r20yxeddhlvc2ldqsjh70p"
      x-go-type: staking.Address
      x-go-type-import: { name: staking, path: "github.com/oasisprotocol/nexus/coreapi/v22.2.11/staking/api" }
      description: An Oasis-style (bech32) address.
    TextBigInt:
      type: string
      pattern: '^-?[0-9]+$'
      format: bigint  # Annotation is not used by Nexus's Go codegen; might be helpful to client generators to recognize this type.
      example: "1234567890123456789012"
      x-go-type: common.BigInt
      x-go-type-import: { name: common, path: "github.com/oasisprotocol/nexus/common" }
    Address:
      type: string
      pattern: '^oasis1[a-z0-9]{40}$'
      example: "oasis1qpg2xuz46g53737343r20yxeddhlvc2ldqsjh70p"
      description: An Oasis-style (bech32) address.
    Ed25519PubKey:
      type: string
      format: byte  # means base64-encoded raw bytes
      example: "lbxs4hlud9XNloIOdhJPaCahd7HtiY8QATCgGnFfCM0="
      x-go-type: signature.PublicKey
      x-go-type-import: { name: signature, path: "github.com/oasisprotocol/oasis-core/go/common/crypto/signature" }
      description: A base64-encoded ed25519 public key.
    CallFormat:
      type: string
      example: "encrypted/x25519-deoxysii"
      x-go-type: common.CallFormat
      x-go-type-import: { name: common, path: "github.com/oasisprotocol/nexus/common" }

    List:
      type: object
      required: [total_count, is_total_count_clipped]
      properties:
        total_count:
          type: integer
          format: uint64
          description: |
            The total number of records that match the query, i.e. the number of records
            the query would return with limit=infinity.
          example: 412
        is_total_count_clipped:
          type: boolean
          description: Whether total_count is clipped for performance reasons.
          example: true

    Status:
      type: object
      required: [latest_block, latest_node_block, latest_block_time, latest_update_age_ms]
      properties:
        latest_block:
          type: integer
          format: int64
          description: |
            The height of the most recent indexed block. Compare with latest_node_block to measure
            how far behind Nexus is from the chain.
          example: *block_height_1
        latest_node_block:
          type: integer
          format: int64
          description: The height of the most recently produced block on-chain as seen by Nexus.
          example: *block_height_2
        latest_block_time:
          type: string
          format: date-time
          description: The RFC 3339 formatted consensus time of when the most recently indexed block was produced.
          example: *iso_timestamp_2
        latest_update_age_ms:
          type: integer
          format: int64
          description: The number of milliseconds since Nexus processed the latest block.
          example: 352

    BlockList:
      allOf:
        - $ref: '#/components/schemas/List'
        - type: object
          required: [blocks]
          properties:
            blocks:
              type: array
              items:
                allOf: [$ref: '#/components/schemas/Block']
      description: |
        A list of consensus blocks.

    Block:
      type: object
      required: [height, hash, timestamp, num_transactions] # TODO: size, gas_used
      properties:
        height:
          type: integer
          format: int64
          description: The block height.
          example: *block_height_1
        hash:
          type: string
          description: The block header hash.
          example: *block_hash_1
        timestamp:
          type: string
          format: date-time
          description: The second-granular consensus time.
          example: *iso_timestamp_1
        num_transactions:
          type: integer
          format: int32
          description: Number of transactions in the block.
          example: 17
        # TODO: Not available on backend
        # size:
        #   type: integer
        #   format: int64
        #   description: Size of the block, in bytes. TODO: Be more exact. Should this include results? By far the easiest is to give the total bytesize of txs here.
        #   example: 123456
        # gas_used:
        #   type: integer
        #   format: int64
        #   description: Total gas used by the transactions in the block.
        #   example: 123456
      description: |
        A consensus block.

    Delegation:
      type: object
      required: [amount, shares, validator, delegator]
      properties:
        amount:
          allOf: [$ref: '#/components/schemas/TextBigInt']
          description: The amount of tokens delegated in base units.
        shares:
          allOf: [$ref: '#/components/schemas/TextBigInt']
          description: The shares of tokens delegated.
        validator:
          type: string
          description: The delegatee (validator) address.
          example: *staking_address_1
        delegator:
          type: string
          description: The delegator address.
          example: *staking_address_2
      description: |
        A delegation.

    DelegationList:
      allOf:
        - $ref: '#/components/schemas/List'
        - type: object
          required: [delegations]
          properties:
            delegations:
              type: array
              items:
                allOf: [$ref: '#/components/schemas/Delegation']
          description: |
            A list of delegations.

    DebondingDelegation:
      type: object
      required: [amount, shares, validator, delegator, debond_end]
      properties:
        amount:
          allOf: [$ref: '#/components/schemas/TextBigInt']
          description: The amount of tokens delegated in base units.
        shares:
          allOf: [$ref: '#/components/schemas/TextBigInt']
          description: The shares of tokens delegated.
        validator:
          type: string
          description: The delegatee (validator) address.
          example: *staking_address_1
        delegator:
          type: string
          description: The delegator address.
          example: *staking_address_2
        debond_end:
          type: integer
          format: int64
          description: The epoch at which the debonding ends.
      description: |
        A debonding delegation.

    DebondingDelegationList:
      allOf:
        - $ref: '#/components/schemas/List'
        - type: object
          required: [debonding_delegations]
          properties:
            debonding_delegations:
              type: array
              items:
                allOf: [$ref: '#/components/schemas/DebondingDelegation']
          description: |
            A list of debonding delegations.

    ConsensusTxMethod:
      type: string
      enum:
        - staking.Transfer
        - staking.AddEscrow
        - staking.ReclaimEscrow
        - staking.AmendCommissionSchedule
        - staking.Allow
        - staking.Withdraw
        - roothash.ExecutorCommit
        - roothash.ExecutorProposerTimeout
        - registry.RegisterEntity
        - registry.RegisterNode
        - registry.RegisterRuntime
        - governance.CastVote
        - governance.SubmitProposal
        - beacon.PVSSCommit
        - beacon.PVSSReveal
        - beacon.VRFProve
      example: staking.Transfer

    TransactionList:
      allOf:
        - $ref: '#/components/schemas/List'
        - type: object
          required: [transactions]
          properties:
            transactions:
              type: array
              items:
                allOf: [$ref: '#/components/schemas/Transaction']
          description: |
            A list of consensus transactions.

    Transaction:
      type: object
      required: [block, index, timestamp, hash, sender, nonce, fee, method, body, success]
      properties:
        block:
          type: integer
          format: int64
          description: The block height at which this transaction was executed.
          example: *block_height_1
        index:
          type: integer
          format: int32
          description: 0-based index of this transaction in its block
          example: 17
        timestamp:
          type: string
          format: date-time
          description: |
            The second-granular consensus time of this tx's block, i.e. roughly when the
            [block was proposed](https://github.com/tendermint/tendermint/blob/v0.34.x/spec/core/data_structures.md#header).
          example: *iso_timestamp_3
        hash:
          type: string
          description: The cryptographic hash of this transaction's encoding.
          example: *tx_hash_1
        sender:
          type: string
          description: The address of who sent this transaction.
          example: *staking_address_1
        nonce:
          type: integer
          format: int64
          description: The nonce used with this transaction, to prevent replay.
          example: 0
        fee:
          allOf: [$ref: '#/components/schemas/TextBigInt']
          description: |
            The fee that this transaction's sender committed
            to pay to execute it.
          example: 1000
        method:
          allOf: [$ref: '#/components/schemas/ConsensusTxMethod']
          description: The method that was called.
        body:
          type: object
          description: The method call body. This spec does not encode the many possible types;
            instead, see [the Go API](https://pkg.go.dev/github.com/oasisprotocol/oasis-core/go) of oasis-core.
            This object will conform to one of the types passed to variable instantiations using `NewMethodName` 
            two levels down the hierarchy, e.g. `MethodTransfer` from `oasis-core/go/staking/api` seen 
            [here](https://pkg.go.dev/github.com/oasisprotocol/oasis-core/go@v0.2300.10/staking/api#pkg-variables).
          example: *tx_body_1
        success:
          type: boolean
          description: Whether this transaction successfully executed.
        error:
          allOf: [$ref: '#/components/schemas/TxError']
          description: Error details of a failed transaction.
      description: |
        A consensus transaction.

    TxError:
      type: object
      required: [code]
      properties:
        module:
          type: string
          description: The module of a failed transaction.
        code:
          type: integer
          format: uint32
          description: The status code of a failed transaction.
        message:
          type: string
          description: |
            The message of a failed transaction.
            This field, like `code` and `module`, can represent an error that originated
            anywhere in the paratime, i.e. either inside or outside a smart contract.

            A common special case worth calling out: When the paratime is 
            EVM-compatible (e.g. Emerald or Sapphire) and the error originates 
            inside a smart contract (using `revert` in solidity), the following 
            will be true:
            - `module` will be "evm" and `code` will be 8; see [here](https://github.com/oasisprotocol/oasis-sdk/blob/runtime-sdk/v0.8.3/runtime-sdk/modules/evm/src/lib.rs#L128) for other possible errors in the `evm` module.
            - `message` will contain the best-effort human-readable revert reason.
        revert_params:
          type: array
          items:
            allOf: [$ref: '#/components/schemas/EvmAbiParam']
          description: |
            The error parameters, as decoded using the contract abi. Present only when
            - the error originated from within a smart contract (e.g. via `revert` in Solidity), and 
            - the contract is verified or the revert reason is a plain String.
            If this field is present, `message` will include the name of the error, e.g. 'InsufficentBalance'.
            Note that users should be cautious when evaluating error data since the
            data origin is not tracked and error information can be faked.
            
    ConsensusEventType:
      type: string
      enum:
        - governance.proposal_executed
        - governance.proposal_finalized
        - governance.proposal_submitted
        - governance.vote
        - registry.entity
        - registry.node_unfrozen
        - registry.node
        - registry.runtime
        - registry.runtime_suspended
        - roothash.execution_discrepancy
        - roothash.executor_committed
        - roothash.finalized
        # Note: roothash.message is no longer used as an event since Damask.
        # Message results are now in RoundResults.
        # The MessageEvent structure remains and is used in RoundResults.
        - roothash.message
        - roothash.in_msg_processed
        - staking.allowance_change
        - staking.burn
        - staking.escrow.add
        - staking.escrow.debonding_start
        - staking.escrow.reclaim
        - staking.escrow.take
        - staking.transfer
      example: *event_type_1

    ConsensusEventList:
      allOf:
        - $ref: '#/components/schemas/List'
        - type: object
          required: [events]
          properties:
            events:
              type: array
              items:
                allOf: [$ref: '#/components/schemas/ConsensusEvent']
          description: |
            A list of consensus events.

    ConsensusEvent:
      type: object
      required: [block, type, body]
      properties:
        block:
          type: integer
          format: int64
          description: The block height at which this event was generated.
          example: *block_height_1
        tx_index:
          type: integer
          format: int32
          description: |
            0-based index of this event's originating transaction within its block.
            Absent if the event did not originate from a transaction.
          example: 5
        tx_hash:
          type: string
          description: |
            Hash of this event's originating transaction.
            Absent if the event did not originate from a transaction.
          example: *tx_hash_1
        roothash_runtime_id:
          type: string
          description: |
            The ID of the runtime to which the event relates, encoded in hex.
            Present only for events of type `roothash.*`.
          example: 000000000000000000000000000000000000000000000000e2eaa99fc008f87f
        roothash_runtime:
          allOf: [$ref: '#/components/schemas/Runtime']
          description: |
            The runtime to which the event relates.
            Present only for events of type `roothash.*`.
          example: emerald
        roothash_runtime_round:
          type: integer
          format: int64
          description: |
            When applicable, the round in the runtime to which this event
            relates.
            Present only for events of type `roothash.*` except for
            `roothash.execution_discrepancy` before Eden.
        type:
          allOf: [$ref: '#/components/schemas/ConsensusEventType']
          description: The type of the event.
        body:
          type: object
          description: |
            The event contents. This spec does not encode the many possible types;
            instead, see [the Go API](https://pkg.go.dev/github.com/oasisprotocol/oasis-core/go/consensus/api/transaction/results#Event) of oasis-core.
            This object will conform to one of the `*Event` types two levels down
            the hierarchy, e.g. `TransferEvent` from `Event > staking.Event > TransferEvent`
      description: |
        An event emitted by the consensus layer.

    EntityList:
      allOf:
        - $ref: '#/components/schemas/List'
        - type: object
          required: [entities]
          properties:
            entities:
              type: array
              items:
                allOf: [$ref: '#/components/schemas/Entity']
          description: |
            A list of entities registered at the consensus layer.

    Entity:
      type: object
      required: [id, address, nodes]
      properties:
        id:
          x-go-name: ID
          type: string
          description: The public key identifying this entity.
          example: *entity_id_1
        address:
          type: string
          description: The staking address belonging to this entity; derived from the entity's public key.
          example: *staking_address_1
        nodes:
          type: array
          items:
            type: string
          description: The vector of nodes owned by this entity.
      description: |
        An entity registered at the consensus layer.

    ValidatorList:
      allOf:
        - $ref: '#/components/schemas/List'
        - type: object
          required: [validators]
          properties:
            validators:
              type: array
              items:
                allOf: [$ref: '#/components/schemas/Validator']
          description: |
            A list of validators registered at the consensus layer.

    ValidatorCommissionBound:
      type: object
      required: [lower, upper, epoch_start, epoch_end]
      properties:
        lower:
          type: integer
          format: uint64
        upper:
          type: integer
          format: uint64
        epoch_start:
          type: integer
          format: uint64
        epoch_end:
          type: integer
          format: uint64

    ValidatorMedia:
      type: object
      # All of the fields are optional.
      properties:
        website_link:
          type: string
          description: An URL associated with the entity.
        email_address:
          type: string
          description: An email address for the validator.
        twitter_acc:
          type: string
          description: A Twitter handle.
        tg_chat:
          type: string
          description: An Telegram handle.
        logotype:
          type: string
          description: A logo type.
        name:
          type: string
          description: The human-readable name of this validator.
          example: WhaleStake

    Validator:
      type: object
      required: [entity_address, entity_id, node_id, escrow, active, status, current_rate, current_commission_bound]
      properties:
        entity_address:
            type: string
            description: The staking address identifying this Validator.
            example: *staking_address_1
        entity_id:
          x-go-name: EntityID
          type: string
          description: The public key identifying this Validator.
          example: *entity_id_1
        node_id:
          x-go-name: NodeID
          type: string
          description: The public key identifying this Validator's node.
          example: *node_id_1
        escrow:
          allOf: [$ref: '#/components/schemas/TextBigInt']
          description: The amount staked.
        active:
          type: boolean
          description: Whether the entity is part of validator set (top <scheduler.params.max_validators> by stake).
        status:
          type: boolean
          description: Whether the entity has a node that is registered for being a validator, node is up to date, and has successfully registered itself. It may or may not be part of validator set.
        media:
          allOf: [$ref: '#/components/schemas/ValidatorMedia']
        current_rate:
          type: integer
          format: uint64
          description: Commission rate.
        current_commission_bound:
          allOf: [$ref: '#/components/schemas/ValidatorCommissionBound']
      description: |
        An validator registered at the consensus layer.

    NodeList:
      allOf:
        - $ref: '#/components/schemas/List'
        - type: object
          required: [entity_id, nodes]
          properties:
            entity_id:
              x-go-name: EntityID
              type: string
            nodes:
              type: array
              items:
                allOf: [$ref: '#/components/schemas/Node']
          description: |
            A list of nodes registered at the consensus layer.

    Node:
      type: object
      required: [id, entity_id, expiration, tls_pubkey, tls_next_pubkey, p2p_pubkey, consensus_pubkey, roles]
      properties:
        id:
          x-go-name: ID
          type: string
          description: The public key identifying this node.
          example: *node_id_1
        entity_id:
          x-go-name: EntityID
          type: string
          description: |
            The public key identifying the entity controlling this node.
          example: *entity_id_1
        expiration:
          type: integer
          format: int64
          description: The epoch in which this node's commitment expires.
        tls_pubkey:
          x-go-name: TLSPubkey
          type: string
          description: The public key used for establishing TLS connections.
        tls_next_pubkey:
          x-go-name: TLSNextPubkey
          type: string
          description: |
            The public key that will be used for establishing TLS connections
            upon rotation.
        p2p_pubkey:
          x-go-name: P2PPubkey
          type: string
          description: The unique identifier of this node on the P2P transport.
        consensus_pubkey:
          type: string
          description: The unique identifier of this node as a consensus member
        roles:
          type: string
          description: A bitmask representing this node's roles.
      description: |
        A node registered at the consensus layer.

    AccountList:
      allOf:
        - $ref: '#/components/schemas/List'
        - type: object
          required: [accounts]
          properties:
            accounts:
              type: array
              items:
                allOf: [$ref: '#/components/schemas/Account']
          description: |
            A list of consensus layer accounts.

    AddressDerivationContext:
      type: string
      enum:
        - "oasis-core/address: staking"
        - "oasis-runtime-sdk/address: secp256k1eth"
        - "oasis-runtime-sdk/address: sr25519"
        - "oasis-runtime-sdk/address: multisig"
        - "oasis-runtime-sdk/address: module"
        - "oasis-runtime-sdk/address: runtime"

    AddressPreimage:
      description: |
        The data from which a consensus-style address (`oasis1...`)
        was derived. Notably, for EVM runtimes like Sapphire,
        this links the Oasis address and the Ethereum address.

        Oasis addresses are derived from a piece of data, such as an ed25519
        public key or an Ethereum address. For example, [this](https://github.com/oasisprotocol/oasis-sdk/blob/b37e6da699df331f5a2ac62793f8be099c68469c/client-sdk/go/helpers/address.go#L90-L91)
        is how an Ethereum is converted to an Oasis address. The type of underlying data usually also
        determines how the signatuers for this address are verified.

        Consensus supports only "staking addresses" (`context="oasis-core/address: staking"`
        below; always ed25519-backed).
        Runtimes support all types. This means that every consensus address is also
        valid in every runtime. For example, in EVM runtimes, you can use staking
        addresses, but only with Oasis tools (e.g. a wallet); EVM contracts such as
        ERC20 tokens or tools such as Metamask cannot interact with staking addresses.
      type: object
      required: [context, address_data]
      properties:
        context:
          allOf: [$ref: "#/components/schemas/AddressDerivationContext"]
          description: |
            The method by which the Oasis address was derived from `address_data`.
          example: "oasis-runtime-sdk/address: secp256k1eth"
        context_version:
          type: integer
          default: 0
          description: Version of the `context`.
        address_data:
          type: string
          format: byte
          description: |
            The base64-encoded data from which the Oasis address was derived.
            When `context = "oasis-runtime-sdk/address: secp256k1eth"`, this
            is the Ethereum address (in base64, not hex!).
          example: 'INLp2Ih3YIdcA+zFNhM+SIGyFgKsYYc9SKQeKRKe2uI='

    RuntimeSdkBalance:
      description: Balance of an account for a specific runtime and oasis-sdk token (e.g. ROSE).
      type: object
      required: [balance, token_symbol, token_decimals]
      properties:
        balance:
          allOf: [$ref: '#/components/schemas/TextBigInt']
          description: Number of tokens held, in base units.
        token_symbol:
          type: string
          description: The token ticker symbol. Unique across all oasis-sdk tokens in the same runtime.
          example: ROSE
        token_decimals:
          type: integer
          description: The number of decimals of precision for this token.
          example: 18

    RuntimeEvmBalance:
      description: Balance of an account for a specific runtime and EVM token.
      type: object
      required: [balance, token_contract_addr, token_contract_addr_eth, token_decimals, token_type]
      properties:
        balance:
          allOf: [$ref: '#/components/schemas/TextBigInt']
          description: Number of tokens held, in base units.
        token_contract_addr:
          type: string
          description: The Oasis address of this token's contract.
          example: 'oasis1qzk5pr2x8ah04lgjee3lv06fmyvqvz45egjv4ps0'
        token_contract_addr_eth:
          type: string
          description: The EVM address of this token's contract.
          example: '0xF8E3DE55D24D13607A12628E0A113B66BA578bDC'
        token_symbol:
          type: string
          description: The token ticker symbol. Not guaranteed to be unique across distinct EVM tokens.
        token_name:
          type: string
          description: The name of the token. Not guaranteed to be unique across distinct EVM tokens.
        token_type:
          allOf: [$ref: "#/components/schemas/EvmTokenType"]
        token_decimals:
          type: integer
          description: The number of decimals of precision for this token.
          example: 18

    TokenHolderList:
      allOf:
        - $ref: '#/components/schemas/List'
        - type: object
          required: [holders]
          properties:
            holders:
              type: array
              items:
                allOf: [$ref: '#/components/schemas/BareTokenHolder']
          description: |
            A list of token holders for a specific (implied) runtime and token.

    BareTokenHolder:
      description: |
        Balance of an account for a specific (implied) runtime and token.
      type: object
      required: [holder_address, balance]
      properties:
        holder_address:
          type: string
          description: The Oasis address of the account holder.
          example: *staking_address_1
        eth_holder_address:
          type: string
          description: The Ethereum address of the same account holder, if meaningfully defined.
          example: *eth_address_1
        balance:
          allOf: [$ref: '#/components/schemas/TextBigInt']
          description: Number of tokens held, in base units.


    Account:
      type: object
      required: [address, nonce, available, escrow, debonding, allowances]
      properties:
        address:
          type: string
          description: The staking address for this account.
          example: *staking_address_1
        nonce:
          type: integer
          format: int64
          description: The expected nonce for the next transaction (= last used nonce + 1)
          example: 0
        available:
          allOf: [$ref: '#/components/schemas/TextBigInt']
          description: The available balance, in base units.
        escrow:
          allOf: [$ref: '#/components/schemas/TextBigInt']
          description: The active escrow balance, in base units.
        debonding:
          allOf: [$ref: '#/components/schemas/TextBigInt']
          description: The debonding escrow balance, in base units.
        delegations_balance:
          allOf: [$ref: '#/components/schemas/TextBigInt']
          description: |
            The delegations balance, in base units.
            For efficiency, this field is omitted when listing multiple-accounts.
        debonding_delegations_balance:
          allOf: [$ref: '#/components/schemas/TextBigInt']
          description: |
            The debonding delegations balance, in base units.
            For efficiency, this field is omitted when listing multiple-accounts.
          example: 10000000000
        allowances:
          type: array
          items:
            allOf: [$ref: '#/components/schemas/Allowance']
          description: The allowances made by this account.
      description: |
        A consensus layer account.

    Allowance:
      type: object
      required: [address, amount]
      properties:
        address:
          type: string
          description: The allowed account.
          example: *staking_address_2
        amount:
          allOf: [$ref: '#/components/schemas/TextBigInt']
          description: The amount allowed for the allowed account.

    EpochList:
      allOf:
        - $ref: '#/components/schemas/List'
        - type: object
          required: [epochs]
          properties:
            epochs:
              type: array
              items:
                allOf: [$ref: '#/components/schemas/Epoch']
          description: |
            A list of consensus epochs.

    Epoch:
      type: object
      required: [id, start_height]
      properties:
        id:
          x-go-name: ID
          type: integer
          format: int64
          description: The epoch number.
          example: *epoch_1
        start_height:
          type: integer
          format: uint64
          description: The (inclusive) height at which this epoch started.
          example: *block_height_1
        end_height:
          type: integer
          format: uint64
          description: The (inclusive) height at which this epoch ended. Omitted if the epoch is still active.
          example: *block_height_2
      description: |
        A consensus epoch.

    ProposalList:
      allOf:
        - $ref: '#/components/schemas/List'
        - type: object
          required: [proposals]
          properties:
            proposals:
              type: array
              items:
                allOf: [$ref: '#/components/schemas/Proposal']
          description: |
            A list of governance proposals.

    ProposalTarget:
      type: object
      properties:
        consensus_protocol:
          type: string
        runtime_host_protocol:
          type: string
        runtime_committee_protocol:
          type: string
      description: The target propotocol versions for this upgrade proposal.

    ProposalState:
      type: string
      enum: [active, passed, failed, rejected]
      description: The state of the proposal.
      example: 'active'

    Proposal:
      type: object
      # TODO: Revise required fields. Most fields are required for actual proposals, and only absent
      # for proposal cancellations (which instead have the `cancels` field). Split API and the DB into
      # two types/tables?
      required: [id, submitter, state, deposit, created_at, closes_at, invalid_votes]
      properties:
        id:
          x-go-name: ID
          type: integer
          format: uint64
          description: The unique identifier of the proposal.
          example: *proposal_id_1
        submitter:
          type: string
          description: The staking address of the proposal submitter.
          example: *staking_address_1
        state:
          allOf: [$ref: '#/components/schemas/ProposalState']
        deposit:
          allOf: [$ref: '#/components/schemas/TextBigInt']
          description: The deposit attached to this proposal.
        handler:
          type: string
          description: The name of the upgrade handler.
        target:
          allOf: [$ref: '#/components/schemas/ProposalTarget']
        epoch:
          type: integer
          format: uint64
          description: The epoch at which the proposed upgrade will happen.
          example: *epoch_1
        cancels:
          type: integer
          format: int64
          description: |
            The proposal to cancel, if this proposal proposes
            cancelling an existing proposal.
        parameters_change_module:
          type: string
          description: |
            The name of the module whose parameters are to be changed
            by this 'parameters_change' proposal.
        parameters_change:
          type: string
          format: byte
          description: |
            The base64 encoded raw cbor representing the updated parameters
            which are to be changed by this 'parameters_change' proposal.
        created_at:
          type: integer
          format: int64
          description: The epoch at which this proposal was created.
          example: *epoch_1
        closes_at:
          type: integer
          format: int64
          description: The epoch at which voting for this proposal will close.
          example: *epoch_2
        invalid_votes:
          allOf: [$ref: '#/components/schemas/TextBigInt']
          description: |
            The number of invalid votes for this proposal, after tallying.
      description: |
        A governance proposal.

    ProposalVotes:
      allOf:
        - $ref: '#/components/schemas/List'
        - type: object
          required: [proposal_id, votes]
          properties:
            proposal_id:
              x-go-name: ProposalID
              type: integer
              format: uint64
              description: The unique identifier of the proposal.
            votes:
              type: array
              items:
                allOf: [$ref: '#/components/schemas/ProposalVote']
              description: The list of votes for the proposal.
          description: |
            A list of votes for a governance proposal.

    ProposalVote:
      type: object
      required: [address, vote]
      properties:
        address:
          type: string
          description: The staking address casting this vote.
          example: *staking_address_1
        vote:
          type: string
          description: The vote cast.
          example: 'yes'
        height:
          type: integer
          format: int64
          description: The block height at which this vote was recorded.
          example: *block_height_1
        timestamp:
          type: string
          format: date-time
          description: The second-granular consensus time of the block in which this vote was cast.
          example: *iso_timestamp_1

    RuntimeBlockList:
      allOf:
        - $ref: '#/components/schemas/List'
        - type: object
          required: [blocks]
          properties:
            blocks:
              type: array
              items:
                allOf: [$ref: '#/components/schemas/RuntimeBlock']
          description: |
            A list of consensus blocks.

    RuntimeBlock:
      type: object
      required: [round, hash, timestamp, num_transactions, size, gas_used]
      properties:
        round:
          type: integer
          format: int64
          description: The block round.
          example: *runtime_block_round_1
        hash:
          type: string
          description: The block header hash.
          example: *runtime_block_hash_1
        timestamp:
          type: string
          format: date-time
          description: The second-granular consensus time.
          example: *iso_timestamp_3
        num_transactions:
          type: integer
          format: int32
          description: The number of transactions in the block.
          example: 1
        size:
          type: integer
          format: int32
          description: The total byte size of all transactions in the block.
          example: 203
        gas_used:
          type: integer
          format: int64
          description: The total gas used by all transactions in the block.
          example: 118597
      description: |
        A ParaTime block.

    RuntimeEventList:
      allOf:
        - $ref: '#/components/schemas/List'
        - type: object
          required: [events]
          properties:
            events:
              type: array
              items:
                allOf: [$ref: '#/components/schemas/RuntimeEvent']
          description: |
            A list of runtime events.

    RuntimeEvent:
      type: object
      required: [round, timestamp, type, body]
      properties:
        round:
          type: integer
          format: int64
          description: The block height at which this event was generated.
          example: *runtime_block_round_1
        tx_index:
          type: integer
          format: int32
          description: |
            0-based index of this event's originating transaction within its block.
            Absent if the event did not originate from a transaction.
        tx_hash:
          type: string
          description: |
            Hash of this event's originating transaction.
            Absent if the event did not originate from a transaction.
          example: *tx_hash_1
        eth_tx_hash:
          type: string
          description: |
            Ethereum trasnsaction hash of this event's originating transaction.
            Absent if the event did not originate from an EVM transaction.
        timestamp:
          type: string
          format: date-time
          description: |
            The second-granular consensus time of this event's block.
          example: *iso_timestamp_1
        type:
          allOf: [$ref: '#/components/schemas/RuntimeEventType']
          description: The type of the event.
        body:
          type: object
          description: |
            The decoded event contents, possibly augmented with additional address info.
            This spec does not encode the many possible types; instead, see [the Go API](https://pkg.go.dev/github.com/oasisprotocol/oasis-sdk/client-sdk/go/modules).
            This object will conform to one of the `*Event` types two levels down
            the hierarchy (e.g. `MintEvent` from `accounts > Event > MintEvent`),
            OR `evm > Event`. For object fields that specify an oasis-style address, Nexus
            will add a field specifying the corresponding Ethereum address, if known. Currently, 
            the only such possible fields are `from_eth`, `to_eth`, and `owner_eth`.
        evm_log_name:
          type: string
          description: |
            If the event type is `evm.log`, this field describes the human-readable type of 
            evm event, e.g. `Transfer`. 
            Absent if the event type is not `evm.log`.
          example: 'Transfer'
        evm_log_params:
          type: array
          items:
            allOf: [$ref: '#/components/schemas/EvmAbiParam']
          description: |
            The decoded `evm.log` event data.
            Absent if the event type is not `evm.log`.
        evm_token:
          allOf: [$ref: '#/components/schemas/EvmEventToken']
      description: An event emitted by the runtime layer

    RuntimeEventType:
      type: string
      enum:
        - accounts.transfer
        - accounts.burn
        - accounts.mint
        - consensus_accounts.deposit
        - consensus_accounts.withdraw
        - consensus_accounts.delegate
        - consensus_accounts.undelegate_start
        - consensus_accounts.undelegate_done
        - core.gas_used
        - evm.log
      example: *runtime_event_type_1

    EvmAbiParam:
      type: object
      required: [name, evm_type, value]
      properties:
        name:
          type: string
          description: The parameter name.
        evm_type:
          type: string
          description: The solidity type of the parameter.
        value:
          description: The parameter value.
      description: |
        A decoded parameter of an event or error emitted from an EVM runtime.
        Values of EVM type `int128`, `uint128`, `int256`, `uint256`, `fixed`, and `ufixed` are represented as strings.
        Values of EVM type `address` and `address payable` are represented as lowercase hex strings with a "0x" prefix.
        Values of EVM type `bytes` and `bytes<N>` are represented as base64 strings.
        Values of other EVM types (integer types, strings, arrays, etc.) are represented as their JSON counterpart.

    EvmEventToken:
      type: object
      properties:
        type:
          allOf: [$ref: '#/components/schemas/EvmTokenType']
        symbol:
          type: string
          description: Symbol of the token, as provided by token contract's `symbol()` method.
          example: USDT
        decimals:
          type: integer
          description: |
            The number of least significant digits in base units that should be displayed as
            decimals when displaying tokens. `tokens = base_units / (10**decimals)`.
            Affects display only. Often equals 18, to match ETH.
          example: 18
      description: |
        Details about the EVM token involved in the event, if any.

    RuntimeEvmContract:
      type: object
      required: [gas_used]
      properties:
        creation_tx:
          type: string
          description: |
            The Oasis cryptographic hash of the transaction that created the smart contract.
            Can be omitted for contracts that were created by another contract, as opposed
            to a direct `Create` call.
        eth_creation_tx:
          type: string
          description: |
            The Ethereum transaction hash of the transaction in `creation_tx`.
            Encoded as a lowercase hex string.
          example: 'dc19a122e268128b5ee20366299fc7b5b199c8e3'
        creation_bytecode:
          type: string
          format: byte
          description: |
            The creation bytecode of the smart contract. This includes the constructor logic
            and the constructor parameters. When run, this code generates the runtime bytecode.
            Can be omitted for contracts that were created by another contract, as opposed
            to a direct `Create` call.
        runtime_bytecode:
          type: string
          format: byte
          description: |
            The runtime bytecode of the smart contract. This is the code stored on-chain that
            describes a smart contract. Every contract has this info, but Nexus fetches
            it separately, so the field may be missing for very fresh contracts (or if the fetching
            process is stalled).
        gas_used:
          description: The total amount of gas used to create or call this contract.
          type: integer
          format: uint64
          example: 153852
        verification:
          allOf: [$ref: '#/components/schemas/RuntimeEvmContractVerification']
          description: |
            Additional information obtained from contract verification. Only available for smart
            contracts that have been verified successfully by Sourcify.

    VerificationLevel:
      type: string
      enum: [partial, full]
      description: |
        The level of verification of a smart contract, as defined by Sourcify.
        An absence of this field means that the contract has not been verified.
        See also https://docs.sourcify.dev/docs/full-vs-partial-match/

    RuntimeEvmContractVerification:
      type: object
      properties:
        verification_level:
          allOf: [$ref: '#/components/schemas/VerificationLevel']
        compilation_metadata:
          type: object
          description: |
            The smart contract's [metadata.json](https://docs.soliditylang.org/en/latest/metadata.html) file in JSON format as defined by Solidity.
            Includes the smart contract's [ABI](https://docs.soliditylang.org/en/develop/abi-spec.html).
        source_files:
          type: array
          items:
            type: object
          description: |
            Array of all contract source files, in JSON format as returned by [Sourcify](https://sourcify.dev/server/api-docs/#/Repository/get_files_any__chain___address_).

    RuntimeTransactionList:
      allOf:
        - $ref: '#/components/schemas/List'
        - type: object
          required: [transactions]
          properties:
            transactions:
              type: array
              items:
                allOf: [$ref: '#/components/schemas/RuntimeTransaction']
          description: |
            A list of runtime transactions.

    RuntimeTransaction:
      type: object
      # NOTE: Not guaranteed to be present: eth_hash, to, amount.
      required: [round, index, timestamp, hash, sender_0, nonce_0, fee, charged_fee, gas_limit, gas_used, size]
      properties:
        round:
          type: integer
          format: int64
          description: The block round at which this transaction was executed.
          example: 3379702
        index:
          type: integer
          format: int64
          description: The 0-based index of this transaction in the block.
          example: 0
        timestamp:
          type: string
          format: date-time
          # TODO REVIEW: Is this the time the block was _proposed_, or agreed on, or some other time?
          description: The second-granular consensus time when this tx's block was proposed.
          example: *iso_timestamp_3
        hash:
          type: string
          description: The Oasis cryptographic hash of this transaction's encoding.
          example: 8394f682150e5f62b02f197d16b4769d032cb1c1b7a6dcf853ba1b12626e080b
        eth_hash:
          type: string
          description: |
            The Ethereum cryptographic hash of this transaction's encoding.
            Absent for non-Ethereum-format transactions.
          example: 9e6a5837c6366d4a7e477c71ffe32d40915cdef7ef209792259e5ee70caf2705
        sender_0:
          allOf: [$ref: '#/components/schemas/Address']
          description: |
            The Oasis address of this transaction's 0th signer.
            Unlike Ethereum, Oasis natively supports multiple-signature transactions.
            However, the great majority of transactions only have a single signer in practice.
            Retrieving the other signers is currently not supported by this API.
          # NOTE: To expose the other signers, use the transaction_signers table.
          example: oasis1qz670t637yyxshnlxhjj5074wgwl94d0x5x69zqd
        sender_0_eth:
          type: string
          description: |
            The Ethereum address of this transaction's 0th signer.
          example: *eth_address_1
        nonce_0:
          type: integer
          format: uint64
          description: The nonce used with this transaction's 0th signer, to prevent replay.
          example: 114194
        fee:
          type: string
          description: |
            The fee that this transaction's sender committed to pay to execute
            it (total, native denomination, ParaTime base units, as a string).
          example: "3000000000000000"
        gas_limit:
          type: integer
          format: uint64
          description: |
            The maximum gas that this transaction's sender committed to use to
            execute it.
          example: 30000
        gas_used:
          type: integer
          format: uint64
          description: The total gas used by the transaction.
        charged_fee:
          type: string
          description: |
            The fee that was charged for the transaction execution (total, native denomination,
            ParaTime base units, as a string).
            For EVM transactions this is calculated as `gas_price * gas_used`, where `gas_price = fee / gas_limit`, for compatibility with Ethereum.
            For other transactions this equals to `fee`.
        size:
          type: integer
          format: int32
          description: The total byte size of the transaction.
        method:
          type: string
          description: |
            The method that was called. Defined by the runtime. In theory, this could be any string as the runtimes evolve.
            In practice, Nexus currently expects only the following methods:
              - "accounts.Transfer"
              - "consensus.Deposit"
              - "consensus.Withdraw"
              - "consensus.Delegate"
              - "consensus.Undelegate"
              - "evm.Create"
              - "evm.Call"
            May be null if the transaction was malformed or encrypted.
          example: "evm.Call"
        body:
          type: object
          description: The method call body. May be null if the transaction was malformed.
          example: {"address": "t1mAPucIdVnrYBpJOcLV2nZoOFo=", "data": RBo+cAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=", "value": ""}
        is_likely_native_token_transfer:
          type: boolean
          description: |
            Whether this transaction likely represents a native token transfer.
            This is based on a heuristic, and can change at any time without warning and possibly without updating the documentation.
            The current heuristic sets this to `true` for:
             - Transactions with method "accounts.Transfer". Those are always native token transfers.
             - Transactions with method "evm.Call" that have no `data` field in their `body`. Those tend to be transfers, but the runtimes provides no reliable visibility into whether a transfer happened.
            Note: Other transactions with method "evm.Call", and possibly "evm.Create", may also be (or include) native token transfers. The heuristic will be `false` for those.
          example: true
        to:
          allOf: [$ref: '#/components/schemas/Address']
          description: |
            A reasonable "to" Oasis address associated with this transaction,
            if applicable. The meaning varies based on the transaction method. Some notable examples:
              - For `method = "accounts.Transfer"`, this is the paratime account receiving the funds.
              - For `method = "consensus.Deposit"`, this is the paratime account receiving the funds.
              - For `method = "consensus.Withdraw"`, this is the consensus (!) account receiving the funds.
              - For `method = "consensus.Delegate"`, this is the consensus (!) account receiving the funds.
              - For `method = "consensus.Undelegate"`, this is the consensus (!) account to which funds were previously delegated. Note that this corresponds with the `.from` field in the transaction body.
              - For `method = "evm.Create"`, this is the address of the newly created smart contract.
              - For `method = "evm.Call"`, this is the address of the called smart contract
          example: "oasis1qq6ulxmcagnp5nr56ylva7nhmwnxtf0krumg9dkq"
        to_eth:
          type: string
          description: |
            A reasonable "to" Ethereum address associated with this transaction,
          example: *eth_address_1
        amount:
          type: string
          description: |
            A reasonable "amount" associated with this transaction, if
            applicable. The meaning varies based on the transaction method.
            Usually in native denomination, ParaTime units. As a string.
          example: "100000001666393459"
        encryption_envelope:
          allOf: [$ref: '#/components/schemas/RuntimeTransactionEncryptionEnvelope']
          description: |
            The data relevant to the encrypted transaction. Only present for encrypted
            transactions in confidential EVM runtimes like Sapphire.
            Note: The term "envelope" in this context refers to the [Oasis-style encryption envelopes](https://github.com/oasisprotocol/oasis-sdk/blob/c36a7ee194abf4ca28fdac0edbefe3843b39bf69/runtime-sdk/src/types/callformat.rs)
            which differ slightly from [digital envelopes](hhttps://en.wikipedia.org/wiki/Hybrid_cryptosystem#Envelope_encryption).
        success:
          type: boolean
          description: |
            Whether this transaction successfully executed.
            Can be absent (meaning "unknown") for confidential runtimes.
        evm_fn_name:
          type: string
          description: |
            The name of the smart contract function called by the transaction.
            Only present for `evm.log` transaction calls to contracts that have been verified.
          example: "acceptTaskResults"
        evm_fn_params:
          type: array
          items:
            allOf: [$ref: '#/components/schemas/EvmAbiParam']
          description: |
            The decoded parameters with which the smart contract function was called.
            Only present for `evm.log` transaction calls to contracts that have been verified.
        error:
          allOf: [$ref: '#/components/schemas/TxError']
          description: Error details of a failed transaction.
      description: |
        A runtime transaction.

    RuntimeTransactionEncryptionEnvelope:
      type: object
      required: [format]
      properties:
        format:
          allOf: [$ref: '#/components/schemas/CallFormat']
          description: The format of the encrypted evm transaction envelope.
        public_key:
          type: string
          format: byte
          description: The base64-encoded public key used to encrypt the transaction.
        data_nonce:
          type: string
          format: byte
          description: The base64-encoded nonce used to encrypt the transaction data.
        data:
          type: string
          format: byte
          description: The base64-encoded encrypted transaction data.
        result_nonce:
          type: string
          format: byte
          description: The base64-encoded nonce used to encrypt the transaction results.
        result:
          type: string
          format: byte
          description: The base64-encoded encrypted result data.

    RuntimeAccount:
      type: object
      required: [address, balances, evm_balances, stats]
      properties:
        address:
          type: string
          description: The staking address for this account.
          example: *staking_address_1
        address_preimage:
          allOf: [$ref: '#/components/schemas/AddressPreimage']
        balances:
          description: |
            The balance(s) of this account in this runtime. Most runtimes use only one denomination, and thus
            produce only one balance here. These balances do not include "layer (n+1) tokens", i.e. tokens
            managed by smart contracts deployed in this runtime. For example, in EVM-compatible runtimes,
            this does not include ERC-20 tokens
          type: array
          items:
            allOf: [$ref: '#/components/schemas/RuntimeSdkBalance']
        evm_contract:
          allOf: [$ref: '#/components/schemas/RuntimeEvmContract']
          description: |
            Data on the EVM smart contract associated with this account address. Only present for accounts
            that represent a smart contract on EVM.
        evm_balances:
          description: |
            The balances of this account in each runtime, as managed by EVM smart contracts (notably, ERC-20).
            NOTE: This field is limited to 1000 entries. If you need more, please let us know in a GitHub issue.
          type: array
          items:
            allOf: [$ref: '#/components/schemas/RuntimeEvmBalance']
        stats:
          allOf: [$ref: '#/components/schemas/AccountStats']

    RuntimeStatus:
      type: object
      required: [active_nodes, latest_block, latest_block_time, latest_update_age_ms]
      properties:
        active_nodes:
          type: integer
          description: The number of compute nodes that are registered and can run the runtime.
          example: 42
        latest_block:
          type: integer
          format: int64
          description: The height of the most recent indexed block (also sometimes referred to as "round") for this runtime. Query a synced Oasis node for the latest block produced.
          example: *block_height_1
        latest_block_time:
          type: string
          format: date-time
          description: The RFC 3339 formatted consensus time of when the latest indexed block for this runtime was produced.
          example: *iso_timestamp_2
        latest_update_age_ms:
          type: integer
          format: int64
          description: The number of milliseconds since Nexus processed the latest block.
          example: 352

    EvmTokenType:
      type: string
      enum:
        - ERC20
        - ERC721
        # Desired support in the future, among others:
        # - ERC1155
      description: |
        The type of a EVM token.

    EvmTokenList:
      allOf:
        - $ref: '#/components/schemas/List'
        - type: object
          required: [evm_tokens]
          properties:
            evm_tokens:
              type: array
              items:
                allOf: [$ref: '#/components/schemas/EvmToken']
              description: A list of L2 EVM tokens (ERC-20, ERC-721, ...).
          description: A list of tokens in a runtime.

    EvmToken:
      type: object
      required: [contract_addr, eth_contract_addr, num_holders, type, is_verified]
      properties:
        contract_addr:
          type: string
          description: The Oasis address of this token's contract.
          example: 'oasis1qp2hssandc7dekjdr6ygmtzt783k3gn38uupdeys'
        eth_contract_addr:
          type: string
          description: The Ethereum address of this token's contract.
          example: *eth_address_1
        name:
          type: string
          description: Name of the token, as provided by token contract's `name()` method.
          example: Uniswap
        symbol:
          type: string
          description: Symbol of the token, as provided by token contract's `symbol()` method.
          example: USDT
        decimals:
          type: integer
          description: |
            The number of least significant digits in base units that should be displayed as
            decimals when displaying tokens. `tokens = base_units / (10**decimals)`.
            Affects display only. Often equals 18, to match ETH.
          example: 18
        type:
          allOf: [$ref: '#/components/schemas/EvmTokenType']
          description: |
            The heuristically determined interface that the token contract implements.
            A less specialized variant of the token might be detected; for example, an
            ERC-1363 token might be labeled as ERC-20 here. If the type cannot be
            detected or is not supported, this field will be null/absent.
        total_supply:
          allOf: [$ref: '#/components/schemas/TextBigInt']
          description: The total number of base units available.
        num_transfers:
          type: integer
          format: int64
          description: |
            The total number of transfers of this token.
        num_holders:
          type: integer
          format: int64
          description: |
            The number of addresses that have a nonzero balance of this token.
          example: 123
        is_verified:
          type: boolean
          description: |
            Whether the contract has been successfully verified by Sourcify.
            Additional information on verified contracts is available via
            the `/{runtime}/accounts/{address}` endpoint.
            DEPRECATED: This field will be removed in the future in favor of verification_level
          example: false
        verification_level:
          allOf: [$ref: '#/components/schemas/VerificationLevel']

    EvmNftList:
      allOf:
        - $ref: '#/components/schemas/List'
        - type: object
          required: [evm_nfts]
          properties:
            evm_nfts:
              type: array
              items:
                allOf: [$ref: '#/components/schemas/EvmNft']
              description: A list of L2 EVM NFT (ERC-721, ...) instances.
          description: A list of NFT instances.

    EvmNft:
      type: object
      required:
        - token
        - id
      properties:
        token:
          allOf: [$ref: '#/components/schemas/EvmToken']
        id:
          allOf: [$ref: '#/components/schemas/TextBigInt']
          description: The instance ID of this NFT within the collection represented by `token`.
        owner:
          allOf: [$ref: '#/components/schemas/Address']
          description: The Oasis address of this NFT instance's owner.
          example: "oasis1qpclnnm0wu44pn43mt6vv3me59kl8zk9ty7qyj03"
        owner_eth:
          type: string
          description: The Ethereum address of this NFT instance's owner.
          example: "0xDEF1009df2d6872C214cd9148c6883893B7c4D91"
        num_transfers:
          type: integer
          format: int64
          description: |
            The total number of transfers of this NFT instance.
        metadata_uri:
          type: string
        metadata_accessed:
          type: string
        metadata:
          description: |
            A metadata document for this NFT instance.
            Currently only ERC-721 is supported, where the document is an Asset Metadata from the ERC721 Metadata JSON Schema.
        name:
          type: string
          description: Identifies the asset which this NFT represents
        description:
          type: string
          description: Describes the asset which this NFT represents
        image:
          type: string
          description: |
            A URI pointing to a resource with mime type image/* representing
            the asset which this NFT represents. (Additional
            non-descriptive text from ERC-721 omitted.)

    AccountStats:
      type: object
      required: [total_sent, total_received, num_txns]
      properties:
        total_sent:
          allOf: [$ref: '#/components/schemas/TextBigInt']
          description: The total number of tokens sent, in base units.
        total_received:
          allOf: [$ref: '#/components/schemas/TextBigInt']
          description: The total number of tokens received, in base units.
        num_txns:
          description: The total number of transactions this account was involved with.
          type: integer
          format: uint64
          example: 4184

    TxVolumeList:
      type: object
      required: [window_size_seconds, windows]
      properties:
        window_size_seconds:
          type: integer
          format: uint32
        windows:
          type: array
          items:
            allOf: [$ref: '#/components/schemas/TxVolume']
          description: The list of daily transaction volumes.
      description: |
        A list of daily transaction volumes.

    TxVolume:
      type: object
      required: [window_end, tx_volume]
      properties:
        window_end:
          type: string
          format: date-time
          description: The end timestamp for this daily transaction volume measurement.
          example: *iso_timestamp_1
        tx_volume:
          type: integer
          format: uint64
          description: The transaction volume for this window.
          example: 420

    ActiveAccountsList:
      type: object
      required: [window_size_seconds, windows]
      properties:
        window_size_seconds:
          type: integer
          format: uint32
        windows:
          type: array
          items:
            allOf: [$ref: '#/components/schemas/ActiveAccounts']
          description: The list of daily unique active account windows.
      description: |
        A list of daily unique active account windows.

    ActiveAccounts:
      type: object
      required: [window_end, active_accounts]
      properties:
        window_end:
          type: string
          format: date-time
          description: The date for the end of the daily active accounts measurement window.
          example: *iso_timestamp_1
        active_accounts:
          type: integer
          format: uint64
          description: The number of active accounts for the 24hour window ending at window_end.
          example: 420

  responses:
    HumanReadableError:
      content:
        application/json:
          schema:
            type: object
            required: [msg]
            properties:
              msg:
                type: string
                description: An error message.
                example: 'internal storage error'
      description: "A human-readable error message."
    NotFoundError:
      description: An empty response indicating that the requested resource was not found.
      content:
        application/json:
          schema: {}
