openapi: 3.1.0
info:
  title: Polkadot REST Account rc blocks API
  description: High-performance Rust REST API for Substrate/Polkadot blockchain data. Drop-in replacement for substrate-api-sidecar.
  contact:
    url: https://github.com/paritytech/polkadot-rest-api
  license:
    name: GPL-3.0-or-later
  version: 0.1.3
servers:
- url: http://localhost:8080/v1
  description: Localhost
tags:
- name: rc blocks
paths:
  /rc/blocks:
    get:
      tags:
      - rc blocks
      summary: Get a range of relay chain blocks by their height.
      description: Given a range query parameter return an array of all the relay chain blocks within that range.
      operationId: getRcBlocks
      parameters:
      - name: range
        in: query
        description: A range of integers. There is a max limit of 500 blocks per request.
        required: true
        example: 0-499
        schema:
          type: string
      - name: eventDocs
        in: query
        description: When set to `true`, every event will have an extra `docs` property.
        schema:
          type: boolean
          default: false
      - name: extrinsicDocs
        in: query
        description: When set to `true`, every extrinsic will have an extra `docs` property.
        schema:
          type: boolean
          default: false
      - name: noFees
        in: query
        description: When set to `true`, no fee information is calculated.
        schema:
          type: boolean
          default: false
      - name: useEvmFormat
        in: query
        description: When set to `true`, every extrinsic's event emitted by pallet-revive will have the address data formatted to EVM.
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Block'
        '400':
          description: invalid blockId supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /rc/blocks/{blockId}:
    get:
      tags:
      - rc blocks
      summary: Get a relay chain block by its height or hash.
      description: Returns a relay chain block. Can be identified by either its height or hash.
      operationId: getRcBlock
      parameters:
      - name: blockId
        in: path
        description: Block identifier, as the block height or block hash.
        required: true
        schema:
          type: string
      - name: eventDocs
        in: query
        description: When set to `true`, every event will have an extra `docs` property.
        schema:
          type: boolean
          default: false
      - name: extrinsicDocs
        in: query
        description: When set to `true`, every extrinsic will have an extra `docs` property.
        schema:
          type: boolean
          default: false
      - name: noFees
        in: query
        description: When set to `true`, no fee information is calculated.
        schema:
          type: boolean
          default: false
      - name: useEvmFormat
        in: query
        description: When set to `true`, every extrinsic's event emitted by pallet-revive will have the address data formatted to EVM.
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Block'
        '400':
          description: invalid blockId supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /rc/blocks/{blockId}/header:
    get:
      tags:
      - rc blocks
      summary: Get a relay chain block's header by its height or hash.
      description: Returns a relay chain block's header. Can be identified by either its height or hash.
      operationId: getRcBlockHeader
      parameters:
      - name: blockId
        in: path
        description: Block identifier, as the block height or block hash.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockHeader'
        '400':
          description: invalid blockId supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /rc/blocks/{blockId}/extrinsics/{extrinsicIndex}:
    get:
      tags:
      - rc blocks
      summary: Get a relay chain block's extrinsic by its block height or hash and the extrinsic index.
      description: Returns an extrinsic from a relay chain block. Can be identified by either its height or hash and the extrinsic index.
      operationId: getRcBlockExtrinsic
      parameters:
      - name: blockId
        in: path
        description: Block identifier, as the block height or block hash.
        required: true
        schema:
          type: string
      - name: extrinsicIndex
        in: path
        description: Extrinsic index within the block.
        required: true
        schema:
          type: string
      - name: eventDocs
        in: query
        description: When set to `true`, every event will have an extra `docs` property.
        schema:
          type: boolean
          default: false
      - name: extrinsicDocs
        in: query
        description: When set to `true`, every extrinsic will have an extra `docs` property.
        schema:
          type: boolean
          default: false
      - name: noFees
        in: query
        description: When set to `true`, no fee information is calculated.
        schema:
          type: boolean
          default: false
      - name: useEvmFormat
        in: query
        description: When set to `true`, every extrinsic's event emitted by pallet-revive will have the address data formatted to EVM.
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Extrinsic'
        '400':
          description: invalid blockId or extrinsicIndex supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /rc/blocks/head:
    get:
      tags:
      - rc blocks
      summary: Get the latest relay chain block.
      description: Returns the latest relay chain block.
      operationId: getRcBlockHead
      parameters:
      - name: finalized
        in: query
        description: When set to `false`, it will fetch the head of the node's canon chain, which might not be finalized.
        schema:
          type: boolean
          default: true
      - name: eventDocs
        in: query
        description: When set to `true`, every event will have an extra `docs` property.
        schema:
          type: boolean
          default: false
      - name: extrinsicDocs
        in: query
        description: When set to `true`, every extrinsic will have an extra `docs` property.
        schema:
          type: boolean
          default: false
      - name: noFees
        in: query
        description: When set to `true`, no fee information is calculated.
        schema:
          type: boolean
          default: false
      - name: useEvmFormat
        in: query
        description: When set to `true`, every extrinsic's event emitted by pallet-revive will have the address data formatted to EVM.
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Block'
        '400':
          description: invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /rc/blocks/head/header:
    get:
      tags:
      - rc blocks
      summary: Get the latest relay chain block's header.
      description: Returns the latest relay chain block's header.
      operationId: getRcBlockHeadHeader
      parameters:
      - name: finalized
        in: query
        description: When set to `false`, it will fetch the head of the node's canon chain, which might not be finalized.
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockHeader'
        '400':
          description: invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /rc/blocks/{blockId}/extrinsics-raw:
    get:
      tags:
      - rc blocks
      summary: Get a relay chain block's raw extrinsics by its height or hash.
      description: Returns a relay chain block's raw extrinsics. Can be identified by either its height or hash.
      operationId: getRcBlockRawExtrinsics
      parameters:
      - name: blockId
        in: path
        description: Block identifier, as the block height or block hash.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockRaw'
        '400':
          description: invalid blockId supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /rc/blocks/{blockId}/para-inclusions:
    get:
      tags:
      - rc blocks
      summary: Get all parachain inclusion information for a relay chain block.
      description: Returns all decoded parachain inclusion events (CandidateIncluded) for a relay chain block from the relay chain API. BlockId can either be a block hash or a block height. This endpoint extracts and decodes the candidate descriptor, commitments hash, and parachain header information for each included parachain block.
      operationId: getRcBlockParaInclusions
      parameters:
      - name: blockId
        in: path
        description: Relay chain block identifier, as the block height or block hash.
        required: true
        schema:
          pattern: ^0[xX][0-9a-fA-F]{1,64}$|[0-9]{1,12}
          type: string
      - name: paraId
        in: query
        description: Optional parachain ID to filter results. When provided, only the inclusion information for the specified parachain will be returned.
        required: false
        schema:
          type: string
          format: unsignedInteger
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockParaInclusions'
        '400':
          description: invalid Block identifier supplied or block does not contain paraInclusion events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ParaInclusion:
      type: object
      description: Information about a single parachain inclusion event
      properties:
        paraId:
          type: string
          description: The parachain ID
          format: unsignedInteger
        paraBlockNumber:
          type: number
          description: The parachain block number that was included (decoded from HeadData)
          format: unsignedInteger
        paraBlockHash:
          type: string
          description: The parachain block hash that was included (decoded from HeadData)
          format: hex
        descriptor:
          $ref: '#/components/schemas/ParaInclusionDescriptor'
        commitmentsHash:
          type: string
          description: Hash of the candidate commitments
          format: hex
        coreIndex:
          type: string
          description: Core index assigned to this parachain block
          format: unsignedInteger
        groupIndex:
          type: string
          description: Validator group index that backed this parachain block
          format: unsignedInteger
    Block:
      type: object
      properties:
        number:
          type: string
          description: The block's height.
          format: unsignedInteger
        hash:
          type: string
          description: The block's hash.
          format: hex
        parentHash:
          type: string
          description: The hash of the parent block.
          format: hex
        stateRoot:
          type: string
          description: The state root after executing this block.
          format: hex
        extrinsicRoot:
          type: string
          description: The Merkle root of the extrinsics.
          format: hex
        authorId:
          type: string
          description: The account ID of the block author (may be undefined for some chains).
          format: ss58
        logs:
          type: array
          items:
            $ref: '#/components/schemas/DigestItem'
          description: Array of `DigestItem`s associated with the block.
        onInitialize:
          $ref: '#/components/schemas/BlockInitialize'
        extrinsics:
          type: array
          description: Array of extrinsics (inherents and transactions) within the block.
          items:
            $ref: '#/components/schemas/Extrinsic'
        onFinalize:
          $ref: '#/components/schemas/BlockFinalize'
        finalized:
          type: boolean
          description: 'A boolean identifying whether the block is finalized or not. Note: on chains that do not have deterministic finality this field is omitted.'
        rcBlockHash:
          type: string
          description: The relay chain block hash used for the query. Only present when `useRcBlock` parameter is used.
        rcBlockNumber:
          type: string
          description: The relay chain block number used for the query. Only present when `useRcBlock` parameter is used.
          format: unsignedInteger
        ahTimestamp:
          type: string
          description: The Asset Hub block timestamp. Only present when `useRcBlock` parameter is used.
          format: unsignedInteger
      description: 'Note: Block finalization does not correspond to consensus, i.e. whether the block is in the canonical chain. It denotes the finalization of block _construction._'
    Signature:
      type: object
      properties:
        signature:
          type: string
          format: hex
        signer:
          type: string
          format: ss58
      description: Object with `signature` and `signer`, or `null` if unsigned.
    BlockInitialize:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/SanitizedEvent'
      description: Object with an array of `SanitizedEvent`s that occurred during block initialization with the `method` and `data` for each.
    ExtrinsicMethod:
      type: object
      properties:
        pallet:
          type: string
        method:
          type: string
      description: Extrinsic method
    Extrinsic:
      type: object
      properties:
        method:
          $ref: '#/components/schemas/ExtrinsicMethod'
        signature:
          $ref: '#/components/schemas/Signature'
        nonce:
          type: string
          description: Account nonce, if applicable.
          format: unsignedInteger
        args:
          type: object
          description: 'Object of arguments keyed by parameter name. Note: if you are expecting an [`OpaqueCall`](https://substrate.dev/rustdocs/v2.0.0/pallet_multisig/type.OpaqueCall.html) and it is not decoded in the response (i.e. it is just a hex string), then Sidecar was not able to decode it and likely that it is not a valid call for the runtime.'
        tip:
          type: string
          description: Any tip added to the transaction.
          format: unsignedInteger
        hash:
          type: string
          description: The transaction's hash.
          format: hex
        info:
          $ref: '#/components/schemas/RuntimeDispatchInfo'
        era:
          $ref: '#/components/schemas/GenericExtrinsicEra'
        events:
          type: array
          description: An array of `SanitizedEvent`s that occurred during extrinsic execution.
          items:
            $ref: '#/components/schemas/SanitizedEvent'
        success:
          type: boolean
          description: Whether or not the extrinsic succeeded.
        paysFee:
          type: boolean
          description: Whether the extrinsic requires a fee. Careful! This field relates to whether or not the extrinsic requires a fee if called as a transaction. Block authors could insert the extrinsic as an inherent in the block and not pay a fee. Always check that `paysFee` is `true` and that the extrinsic is signed when reconciling old blocks.
    RuntimeDispatchInfo:
      type: object
      properties:
        weight:
          $ref: '#/components/schemas/WeightsV2'
          description: Weights represented as WeightsV2 (two dimensional weights). When querying historical blocks that use WeightsV1, the weight will be returned as a weight key that points to a number represented as a string.
        class:
          type: string
          description: Extrinsic class.
          enum:
          - Normal
          - Operational
          - Mandatory
        partialFee:
          type: string
          description: The _inclusion fee_ of a transaction, i.e. the minimum fee required for a transaction. Includes weight and encoded length fees, but does not have access to any signed extensions, e.g. the `tip`.
          format: unsignedInteger
        kind:
          type: string
          description: Information on the partialFee that is collected. Can be either `preDispatch`, `postDispatch` or `fromEvent`. `preDispatch` means the information used to collect the fee was from `payment_queryInfo`, `postDispatch` means the information used to calculate the fee was from finalized weights for the extrinsic, and `fromEvent` means that the partialFee was abstracted from the `TransactionPayment::TransactionPaidFee` event.
      description: RuntimeDispatchInfo for the transaction. Includes the `partialFee`.
    WeightsV2:
      type: object
      properties:
        refTime:
          type: string
          description: The weight of computational time used based on some reference hardware.
        proofSize:
          type: string
          description: The weight of storage space used by proof of validity.
    ParaInclusionDescriptor:
      type: object
      description: Candidate descriptor containing parachain inclusion metadata
      properties:
        relayParent:
          type: string
          description: The relay chain parent block hash
          format: hex
        persistedValidationDataHash:
          type: string
          description: Hash of the persisted validation data
          format: hex
        povHash:
          type: string
          description: Hash of the Proof of Validity (PoV)
          format: hex
        erasureRoot:
          type: string
          description: Root hash of the erasure encoding
          format: hex
        paraHead:
          type: string
          description: Hash of the parachain head data
          format: hex
        validationCodeHash:
          type: string
          description: Hash of the validation code
          format: hex
    BlockFinalize:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/SanitizedEvent'
      description: Object with an array of `SanitizedEvent`s that occurred during block construction finalization with the `method` and `data` for each.
    DigestItem:
      type: object
      properties:
        type:
          type: string
        index:
          type: string
          format: unsignedInteger
        value:
          type: array
          items:
            type: string
    BlockParaInclusions:
      type: object
      description: Contains all decoded parachain inclusion information for a relay chain block
      properties:
        at:
          $ref: '#/components/schemas/BlockIdentifiers'
        inclusions:
          type: array
          description: Array of parachain inclusions in this relay chain block, sorted by paraId
          items:
            $ref: '#/components/schemas/ParaInclusion'
    Error:
      type: object
      properties:
        code:
          type: number
        message:
          type: string
        stack:
          type: string
        level:
          type: string
    BlockRaw:
      type: object
      properties:
        number:
          type: string
          description: The block's height.
          format: unsignedInteger
        parentHash:
          type: string
          description: The hash of the parent block.
          format: hex
        stateRoot:
          type: string
          description: The state root after executing this block.
          format: hex
        extrinsicRoot:
          type: string
          description: The Merkle root of the extrinsics.
          format: hex
        digest:
          type: object
          properties:
            logs:
              type: array
              items:
                $ref: '#/components/schemas/DigestItem'
              description: Array of `DigestItem`s associated with the block.
        extrinsics:
          type: array
          description: Array of raw extrinsics (inherents and transactions) within the block.
          items:
            type: string
        rcBlockHash:
          type: string
          description: The relay chain block hash used for the query. Only present when `useRcBlock` parameter is used.
        rcBlockNumber:
          type: string
          description: The relay chain block number used for the query. Only present when `useRcBlock` parameter is used.
          format: unsignedInteger
        ahTimestamp:
          type: string
          description: The Asset Hub block timestamp. Only present when `useRcBlock` parameter is used.
          format: unsignedInteger
    SanitizedEvent:
      type: object
      properties:
        method:
          type: string
        data:
          type: array
          items:
            type: string
    BlockIdentifiers:
      type: object
      properties:
        hash:
          type: string
          description: The block's hash.
          format: hex
        height:
          type: string
          description: The block's height.
          format: unsignedInteger
    GenericExtrinsicEra:
      type: object
      description: 'The return value for era can either be `mortalEra`, or `immortalEra` and is represented as an enum in substrate. `immortalEra` meaning

        the transaction is valid forever. `mortalEra` consists of a tuple containing a period and phase.

        ex: `"{"mortalEra": ["64", "11"]}"`. The Period is the period of validity from the block hash found in the signing material.

        The Phase is the period that this transaction''s lifetime begins (and, importantly,

        implies which block hash is included in the signature material).

        '
      properties:
        mortalEra:
          type: array
          items:
            type: string
          description: Tuple of a Phase, and Period. Each item in the array will be a string formatted as an integer.
        immortalEra:
          type: string
          description: Hardcoded constant '0x00'.
          format: hex
      example: '{"mortalEra":["64", "11"]}'
    BlockHeader:
      type: object
      properties:
        parentHash:
          type: string
          description: The hash of the parent block.
          format: hex
        number:
          type: string
          description: The block's height.
          format: unsignedInteger
        stateRoot:
          type: string
          description: The state root after executing this block.
          format: hex
        extrinsicRoot:
          type: string
          description: The Merkle root of the extrinsics.
          format: hex
        digest:
          type: object
          properties:
            logs:
              type: array
              items:
                $ref: '#/components/schemas/DigestItem'
              description: Array of `DigestItem`s associated with the block.
        rcBlockHash:
          type: string
          description: The relay chain block hash used for the query. Only present when `useRcBlock` parameter is used.
        rcBlockNumber:
          type: string
          description: The relay chain block number used for the query. Only present when `useRcBlock` parameter is used.
          format: unsignedInteger
        ahTimestamp:
          type: string
          description: The Asset Hub block timestamp. Only present when `useRcBlock` parameter is used.
          format: unsignedInteger