openapi: 3.0.0
info:
  title: Trace API
  description: >-
    Nodeos Trace API Specification. See developer documentation at
    https://docs.eosnetwork.com for information on enabling this plugin.
  version: 1.0.0
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  contact:
    url: https://eosnetwork.com
servers:
  - url: '{protocol}://{host}:{port}/v1/'
    variables:
      protocol:
        enum:
          - http
          - https
        default: http
      host:
        default: localhost
      port:
        default: '8080'
components:
  schemas:
    Sha256:
      type: string
      pattern: ^[0-9A-Fa-f]{64}$
      title: Sha256
    DateTimeSeconds:
      type: string
      description: Date/time string in the format YYYY-MM-DDTHH:MM:SS.sss
      pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{3}$
      title: DateTimeSeconds
    EmptyString:
      type: string
      maxLength: 0
      title: EmptyString
    NamePrivileged:
      type: string
      description: String representation of privileged EOSIO name type
      pattern: ^(eosio[\.][a-z1-5]{1,6})([a-j]{1})?$
      title: NamePrivileged
    NameBasic:
      type: string
      description: >-
        String representation of basic EOSIO name type, must be 12 characters
        and contain only a-z and 0-5
      pattern: ^([a-z]{1}[a-z1-5]{11})([a-j]{1})?$
      title: NameBasic
    NameBid:
      type: string
      description: >-
        String representation of EOSIO bid name type, 1-12 characters and only
        a-z and 0-5 are allowed
      pattern: ^([a-z1-5]{1,12})([a-j]{1})?$
      title: NameBid
    NameCatchAll:
      type: string
      description: String representation of EOSIO name type
      pattern: ^([a-z1-5]{1}[a-z1-5\.]{0,10}[a-z1-5]{1})([a-j]{1})?$
      title: NameCatchAll
    Name:
      anyOf:
        - $ref: '#/components/schemas/NamePrivileged'
        - $ref: '#/components/schemas/NameBasic'
        - $ref: '#/components/schemas/NameBid'
        - $ref: '#/components/schemas/NameCatchAll'
      title: Name
    AuthorizationTraceV0:
      type: object
      additionalProperties: false
      minProperties: 2
      required:
        - account
        - permission
      properties:
        account:
          $ref: '#/components/schemas/Name'
        permission:
          $ref: '#/components/schemas/Name'
      title: AuthorizationTraceV0
    ActionTraceV0:
      type: object
      additionalProperties: false
      minProperties: 6
      required:
        - global_sequence
        - receiver
        - account
        - action
        - authorization
        - data
      properties:
        global_sequence:
          type: integer
        receiver:
          $ref: '#/components/schemas/Name'
        account:
          $ref: '#/components/schemas/Name'
        action:
          $ref: '#/components/schemas/Name'
        authorization:
          type: array
          items:
            $ref: '#/components/schemas/AuthorizationTraceV0'
        data:
          type: object
          additionalProperties: true
      title: ActionTraceV0
    TransactionTraceV0:
      type: object
      additionalProperties: false
      minProperties: 2
      required:
        - id
        - actions
      properties:
        id:
          $ref: '#/components/schemas/Sha256'
        actions:
          type: array
          items:
            $ref: '#/components/schemas/ActionTraceV0'
      title: TransactionTraceV0
    BlockTraceV0:
      type: object
      additionalProperties: false
      minProperties: 7
      required:
        - id
        - number
        - previous_id
        - status
        - timestamp
        - producer
        - transactions
      properties:
        id:
          $ref: '#/components/schemas/Sha256'
        number:
          description: height of this block in the chain
          type: integer
        previous_id:
          $ref: '#/components/schemas/Sha256'
        status:
          description: pending or irreversible
          type: string
        timestamp:
          $ref: '#/components/schemas/DateTimeSeconds'
        producer:
          oneOf:
            - $ref: '#/components/schemas/EmptyString'
            - $ref: '#/components/schemas/Name'
        transactions:
          description: list of transaction traces generated from block
          type: array
          items:
            $ref: '#/components/schemas/TransactionTraceV0'
      title: BlockTraceV0
    Signature:
      type: string
      description: Base58 encoded EOSIO cryptographic signature
      pattern: ^SIG_([RK]1|WA)_[1-9A-HJ-NP-Za-km-z]+$
      title: Signature
    DateTime:
      type: string
      description: Date/time string in the format YYYY-MM-DDTHH:MM:SS
      pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}$
      title: DateTime
    WholeNumber:
      description: A whole number
      anyOf:
        - type: string
          pattern: ^\d+$
        - type: integer
      title: WholeNumber
    TransactionHeader:
      type: object
      additionalProperties: false
      minProperties: 6
      required:
        - expiration
        - ref_block_num
        - ref_block_prefix
        - max_net_usage_words
        - max_cpu_usage_ms
        - delay_sec
      properties:
        expiration:
          description: Time that transaction must be confirmed by.
          $ref: '#/components/schemas/DateTime'
        ref_block_num:
          type: integer
        ref_block_prefix:
          description: 32-bit portion of block ID
          type: integer
        max_net_usage_words:
          $ref: '#/components/schemas/WholeNumber'
        max_cpu_usage_ms:
          $ref: '#/components/schemas/WholeNumber'
        delay_sec:
          type: integer
      title: TransactionHeader
    TransactionTraceV1:
      type: object
      additionalProperties: false
      minProperties: 7
      required:
        - id
        - actions
        - status
        - cpu_usage_us
        - net_usage_words
        - signatures
        - transaction_header
      properties:
        id:
          $ref: '#/components/schemas/Sha256'
        actions:
          type: array
          items:
            $ref: '#/components/schemas/ActionTraceV0'
        status:
          type: string
          enum:
            - executed
            - soft_fail
            - hard_fail
            - delayed
            - expired
          description: |
            status:
              * `executed` - Succeed, no error handler executed
              * `soft_fail` - Objectively failed (not executed), error handler executed
              * `hard_fail` - Objectively failed and error handler objectively failed thus no state change
              * `delayed` - Used by delayed-user transactions for timer-based executions
              * `expired` - Transaction expired and storage space refunded to user
        cpu_usage_us:
          type: integer
        net_usage_words:
          type: integer
        signatures:
          type: array
          items:
            $ref: '#/components/schemas/Signature'
        transaction_header:
          $ref: '#/components/schemas/TransactionHeader'
      title: TransactionTraceV1
    BlockTraceV1:
      type: object
      additionalProperties: false
      minProperties: 10
      required:
        - id
        - number
        - previous_id
        - status
        - timestamp
        - producer
        - transaction_mroot
        - action_mroot
        - schedule_version
        - transactions
      properties:
        id:
          $ref: '#/components/schemas/Sha256'
        number:
          description: height of this block in the chain
          type: integer
        previous_id:
          $ref: '#/components/schemas/Sha256'
        status:
          description: pending or irreversible
          type: string
        timestamp:
          $ref: '#/components/schemas/DateTimeSeconds'
        producer:
          oneOf:
            - $ref: '#/components/schemas/EmptyString'
            - $ref: '#/components/schemas/Name'
        transaction_mroot:
          $ref: '#/components/schemas/Sha256'
        action_mroot:
          $ref: '#/components/schemas/Sha256'
        schedule_version:
          description: number of times producer schedule has changed since genesis
          type: integer
        transactions:
          description: list of transaction traces generated from block
          type: array
          items:
            $ref: '#/components/schemas/TransactionTraceV1'
      title: BlockTraceV1
    ActionTraceV2:
      type: object
      properties:
        global_squence:
          type: integer
          example: 669
        receiver:
          type: string
          example: myproducer
        account:
          type: string
          example: eosio.token
        action:
          type: string
          example: transfer
        authorization:
          type: array
          items:
            type: object
            properties:
              account:
                type: string
                example: myaccount
              permission:
                type: string
                example: active
        data:
          type: string
          $ref: '#/components/schemas/Sha256'
        return_value:
          type: string
          example: ''
        params:
          type: object
          properties:
            from:
              type: string
              example: eosio
            to:
              type: string
              example: myproducer
            quantity:
              type: string
              example: 10.000 SYS
            memo:
              type: string
              example: first transfer
    BlockTraceV2:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Sha256'
        number:
          type: integer
          example: 31
        previous_id:
          $ref: '#/components/schemas/Sha256'
        status:
          type: string
          enum:
            - irreversible
            - executed
            - pending
            - soft_fail
            - hard_fail
            - delayed
            - expired
          example: executed
        timestamp:
          type: string
          example: '2019-06-18T00:00:00'
        producer:
          type: string
          example: myproducer
        transaction_mroot:
          $ref: '#/components/schemas/Sha256'
        action_mroot:
          $ref: '#/components/schemas/Sha256'
        schedule_version:
          type: integer
          example: 1
        transactions:
          oneOf:
            - title: transaction type v3
              type: array
              items:
                type: object
                properties:
                  block_num:
                    type: integer
                    example: 31
                  block_time:
                    type: string
                    example: '2019-06-18T00:00:00'
                  producer_block_id:
                    $ref: '#/components/schemas/Sha256'
            - title: transaction type v2
              type: array
              items:
                type: object
                properties:
                  id:
                    $ref: '#/components/schemas/Sha256'
                  block_num:
                    type: integer
                    example: 31
                  block_time:
                    type: string
                    example: '2019-06-18T00:00:00'
                  producer_block_id:
                    $ref: '#/components/schemas/Sha256'
                  actions:
                    type: array
                    items:
                      $ref: '#/components/schemas/ActionTraceV2'
                transaction_header:
                  type: object
                  $ref: TransactionHeader.yaml
    TransactionTraceV2:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Sha256'
        number:
          type: integer
          example: 31
        previous_id:
          $ref: '#/components/schemas/Sha256'
        status:
          type: string
          enum:
            - irreversible
            - executed
            - pending
            - soft_fail
            - hard_fail
            - delayed
            - expired
          example: executed
        timestamp:
          type: string
          example: '2019-06-18T00:00:00'
        producer:
          type: string
          example: myproducer
        transaction_mroot:
          $ref: '#/components/schemas/Sha256'
        action_mroot:
          $ref: '#/components/schemas/Sha256'
        schedule_version:
          type: integer
          example: 1
        transactions:
          type: array
          items:
            type: object
            properties:
              id:
                $ref: '#/components/schemas/Sha256'
              block_num:
                type: integer
                example: 31
              block_time:
                type: string
                example: '2019-06-18T00:00:00'
              producer_block_id:
                $ref: '#/components/schemas/Sha256'
              actions:
                type: array
                items:
                  $ref: '#/components/schemas/ActionTraceV2'
              transaction_header:
                type: object
                $ref: '#/components/schemas/TransactionHeader'
    TransactionTraceV3:
      type: object
      additionalProperties: false
      minProperties: 2
      required:
        - block_num
        - block_time
      properties:
        block_num:
          number: null
          type: integer
        block_time:
          $ref: '#/components/schemas/DateTimeSeconds'
        producer_block_id:
          $ref: '#/components/schemas/Sha256'
      title: TransactionTraceV3
security:
  - {}
paths:
  /trace_api/get_block:
    post:
      summary: get block
      description: >-
        Returns a block trace object containing retired actions and related
        metadata.
      operationId: get_block
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - block_num
              properties:
                block_num:
                  type: integer
                  description: Provide a `block number`
      responses:
        '200':
          description: OK - valid response payload
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/BlockTraceV0'
                  - $ref: '#/components/schemas/BlockTraceV1'
                  - $ref: '#/components/schemas/BlockTraceV2'
        '400':
          description: >-
            Error - requested block number is invalid (not a number, larger than
            max int)
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 400
                  message:
                    type: string
                    example: bad or missing block_num
                  error:
                    $ref: '#/component/schema/ERROR_DETAILS'
        '404':
          description: Error - requested data not present on node
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 400
                  message:
                    type: string
                    example: bad or missing block_num
                  error:
                    $ref: '#/component/schema/ERROR_DETAILS'
        '500':
          description: >-
            Error - exceptional condition while processing get_block; e.g.
            corrupt files
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 500
                  message:
                    type: string
                    example: >-
                      Trace API encountered an Error which it cannot recover
                      from.  Please resolve the error and relaunch the process
                  error:
                    $ref: '#/component/schema/ERROR_DETAILS'
  /trace_api/get_transaction_trace:
    post:
      summary: transaction trace
      description: Does a scan of the trace files looking for the transaction
      optionationId: get_transaction_trace
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
              properties:
                id:
                  type: integer
                  description: Proviade a transaction id
      responses:
        '200':
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/TransactionTraceV0'
                  - $ref: '#/components/schemas/TransactionTraceV1'
                  - $ref: '#/components/schemas/TransactionTraceV2'
                  - $ref: '#/components/schemas/TransactionTraceV3'
        '400':
          description: >-
            Error - requested block number is invalid (not a number, larger than
            max int)
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 400
                  message:
                    type: string
                    example: bad or missing block_num
                  error:
                    $ref: '#/component/schema/ERROR_DETAILS'
        '404':
          description: Error - requested data not present on node
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 400
                  message:
                    type: string
                    example: bad or missing block_num
                  error:
                    $ref: '#/component/schema/ERROR_DETAILS'
        '500':
          description: >-
            Error - exceptional condition while processing get_block; e.g.
            corrupt files
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 500
                  message:
                    type: string
                    example: >-
                      Trace API encountered an Error which it cannot recover
                      from.  Please resolve the error and relaunch the process
                  error:
                    $ref: '#/component/schema/ERROR_DETAILS'
component:
  schema:
    TRACE:
      type: object
      properties:
        global_squence:
          type: integer
          example: 669
        receiver:
          type: string
          example: myproducer
        account:
          type: string
          example: esio.token
        action:
          type: string
          example: transfer
        authorization:
          type: array
          items:
            type: object
            properties:
              account:
                type: string
                example: myaccount
              permission:
                type: string
                example: active
        data:
          type: string
          $ref: ../../../static/openapi/v2.0/Sha256.yaml
        return_value:
          type: string
          example: ''
        params:
          type: object
          properties:
            from:
              type: string
              example: eosio
            to:
              type: string
              example: myproducer
            quantity:
              type: string
              example: 10.000 SYS
            memo:
              type: string
              example: first transfer
    ERROR_DETAILS:
      type: object
      properties:
        code:
          type: integer
          example: 0
        name:
          type: string
        what:
          type: string
        details:
          type: array
        items:
          type: string
