Kadena endpoint-listen API

openapi: 3.0.0
info:
  title: Kadena Chainweb Node block endpoint-listen API
  description: 'API of [chainweb-node](https://github.com/kadena-io/chainweb-node)


    Chainweb is a scalable Proof-Of-Work (PoW) consensus algorithm. It is an

    conservative extension of Bitcoin''s Nakamoto consensus that extends

    Bitcoin''s single chain algorithm to multiple chains. This allows for

    unlimited transaction throughput by horizontally scaling the number of chains.


    Feedback and bug reports for the content of this site are welcome. Please

    open an issue at [this github repository](https://github.com/kadena-io/chainweb-openapi/issues).

    '
  version: '0.0'
  x-logo:
    url: https://cdn.sanity.io/images/agrhq0bu/production/73f06e78e066f86e21cb84f82292494fe04b9be8-1438x472.png
    alttext: Kadena Chainweb Logo
servers:
- url: https://api.chainweb.com/chainweb/{apiVersion}/mainnet01
  description: 'Chainweb mainnet service API. It also serves some endpoints of the P2P API.

    '
  variables:
    apiVersion:
      default: '0.0'
- url: https://api.testnet.chainweb.com/chainweb/{apiVersion}/testnet04
  description: 'Chainweb testnet service API. It also serves some endpoints of the P2P API.

    '
  variables:
    apiVersion:
      default: '0.0'
- url: '{schema}://{domain}:{port}/chainweb/{apiVersion}/{chainwebVersion}'
  description: 'An generic chainweb-node. It may serve only a subset of the endpoints.

    '
  variables:
    schema:
      default: http
      enum:
      - http
      - https
    domain:
      default: api.chainweb.com
    port:
      default: '1848'
    chainwebVersion:
      default: mainnet01
      enum:
      - test-singleton
      - development
      - mainnet01
      - testnet04
    apiVersion:
      default: '0.0'
- url: https://{location}.chainweb.com/chainweb/{apiVersion}/mainnet01
  description: Chainweb mainnet P2P bootstrap node. Only P2P API endpoints are served.
  variables:
    location:
      default: us-e1
      enum:
      - us-e1
      - us-e2
      - us-e3
      - us-w1
      - us-w2
      - us-w3
      - fr1
      - fr2
      - fr3
      - jp1
      - jp2
      - jp3
    apiVersion:
      default: '0.0'
- url: https://{location}.testnet.chainweb.com/chainweb/{apiVersion}/testnet04
  description: Chainweb testnet P2P bootstrap node. Only P2P API endpoints are served.
  variables:
    location:
      default: us-e1
      enum:
      - us1
      - us2
      - eu1
      - eu2
      - ap1
      - ap2
    apiVersion:
      default: '0.0'
tags:
- name: endpoint-listen
  x-displayName: Blocking listen for single transaction result
paths:
  /listen:
    post:
      description: 'Blocking request for single command result.

        '
      summary: listen
      tags:
      - endpoint-listen
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - listen
              properties:
                listen:
                  $ref: '#/components/schemas/request-key'
      responses:
        '200':
          description: The request key was found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/command-result'
components:
  schemas:
    pact-value:
      description: Pact value compound type.
      tags:
      - model-pact-value
      anyOf:
      - title: String
        description: Pact strings encode directly to JSON strings.
        type: string
      - title: Decimal
        description: There are two alternative JSON representations for Decimal.
        oneOf:
        - title: Number
          description: 'JSON numbers can be used whenever the precision is adequate

            '
          type: number
        - title: Object
          description: 'When JSON number precision is not enough, you can use an object with the number''s decimal representation as a string

            '
          type: object
          required:
          - decimal
          properties:
            decimal:
              type: string
              description: String representation of number to avoid rounding error
              example: '1.23498218000001'
      - title: Integer
        description: There are two alternative JSON representations for Integer.
        type: object
        required:
        - int
        properties:
          int:
            oneOf:
            - title: Number
              description: 'JSON numbers are rounded to integer values.

                '
              type: number
              example: 12345
            - title: String
              description: 'When JSON number precision is not enough, you can specify the integer as a string

                '
              type: string
              example: '123456789'
      - title: Boolean
        description: JSON booleans encode to Pact booleans.
        type: boolean
      - title: Object
        type: object
        description: JSON objects not matching other Pact Value schemas become Pact objects.
        additionalProperties:
          $ref: '#/components/schemas/pact-value'
      - title: Time
        type: object
        required:
        - time
        properties:
          time:
            type: string
            description: Literal time value using the UTC time format.
            example: '1970-01-01T00:00:00Z'
      - title: List
        description: JSON lists become Pact lists.
        type: array
        items:
          $ref: '#/components/schemas/pact-value'
      - title: Module Reference
        description: Special pact value to directly reference a module or interface.
        type: object
        required:
        - refName
        - refSpec
        example:
          $ref: '#/components/examples/module_reference'
        properties:
          refName:
            type: object
            required:
            - name
            - namespace
            description: The module name
            properties:
              name:
                type: string
                description: Bare name of a module
              namespace:
                type: string
                nullable: true
                description: Namespace of the indicated module
          refSpec:
            type: array
            description: The module names to substitute for any references present in the module code
            items:
              type: object
              required:
              - name
              - namespace
              properties:
                name:
                  type: string
                  description: Bare name of a module
                namespace:
                  type: string
                  nullable: true
                  description: Namespace of the indicated module
      - title: Guard
        description: Special pact value for guard types.
        type: object
        oneOf:
        - title: Keyset
          description: 'A keyset forms a rule made from a set of key/address values and a predicate function.

            When enforced, transaction signer list is evaluated against keyset.

            '
          required:
          - keys
          - pred
          properties:
            keys:
              type: array
              description: Set of public key/address values. Native pact public keys are ED25519 in base16 encoding.
              items:
                type: string
            pred:
              type: string
              description: 'A pact function name. Built-in values are `keys-all` (match all keys in set),

                `keys-any` (match at least one), and `keys-2` (match at least 2).

                Custom functions have a fully-qualified name and

                must accept two integer arguments `count` (number of keys in set) and `matched`

                (number of set keys found in transaction set).

                '
        - title: Keyset Reference
          description: Refers to a keyset in the Pact environment/database installed with `define-keyset`.
          required:
          - keysetref
          properties:
            keysetref:
              type: string
              description: Installed keyset name.
        - title: User Guard
          description: 'Closure of call to "guard function" which is a boolean user function with arguments.

            '
          required:
          - fun
          - args
          properties:
            fun:
              description: Fully-qualified guard function name.
              type: string
            args:
              description: Argument values to the guard function.
              type: array
              items:
                $ref: '#/components/schemas/pact-value'
        - title: Module Guard
          type: object
          description: 'Autonomous guard that only allows module code access, or requires module admin.

            '
          required:
          - moduleName
          - name
          properties:
            moduleName:
              required:
              - name
              - namespace
              properties:
                name:
                  type: string
                  description: module bare name
                namespace:
                  type: string
                  description: module namespace
            name:
              type: string
              description: Distinguishing/informative name for module guard.
        - title: Pact Guard
          type: object
          description: 'Autonomous guard that only allows a particular pact execution, referenced by ID, to pass.

            Two executions of the same defpact code result in distinct pact IDs. A pact guard

            created inside of this execution will only pass when running that particular pact.

            '
          required:
          - pactId
          - name
          properties:
            pactId:
              description: Defpact execution ID.
              type: string
            name:
              type: string
              description: Distinguishing/informative name for pact guard.
    pact-error:
      description: 'Verbose object describing failed execution.

        '
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: Descriptive error text.
        callStack:
          type: array
          items:
            type: string
        info:
          type: string
        type:
          type: string
    event:
      description: Pact output event.
      type: object
      properties:
        name:
          type: string
          description: Event defcap name.
        module:
          type: object
          description: Qualified module name of event defcap.
          required:
          - name
          properties:
            name:
              type: string
              description: module bare name
            namespace:
              type: string
              description: module namespace
        params:
          type: array
          items:
            $ref: '#/components/schemas/pact-value'
        moduleHash:
          type: string
          description: Hash of emitting module.
    command-result:
      title: Command Result
      tags:
      - model-command-result
      example:
        $ref: '#/components/examples/command-result'
      description: The result of attempting to execute a single well-formed Pact command.
      type: object
      required:
      - reqKey
      - result
      - logs
      - metaData
      - gas
      properties:
        reqKey:
          $ref: '#/components/schemas/request-key'
        result:
          oneOf:
          - title: Success
            type: object
            properties:
              status:
                type: string
                enum:
                - success
              data:
                $ref: '#/components/schemas/pact-value'
          - title: Failure
            type: object
            properties:
              status:
                type: string
                enum:
                - failure
              error:
                $ref: '#/components/schemas/pact-error'
        txId:
          type: number
          description: Database-internal transaction tracking ID.
        logs:
          type: string
          description: Backend-specific value providing image of database logs.
        metaData:
          properties:
            blockTime:
              type: number
              description: POSIX time of block
            prevBlockHash:
              type: string
              description: Parent Block hash of containing block.
            blockHash:
              type: string
              description: Block hash of containing block.
            blockHeight:
              type: number
              description: Block height of containing block.
            publicMeta:
              type: object
              description: Public metadata.
              properties:
                creationTime:
                  type: number
                  description: POSIX time the command was created
                ttl:
                  type: number
                  description: Transaction time to live
                gasLimit:
                  type: number
                  description: The transaction's gas limit
                chainId:
                  type: string
                  description: Chain identifier
                gasPrice:
                  type: number
                  description: The price of each unit of gas in KDA
                sender:
                  type: string
        events:
          type: array
          items:
            $ref: '#/components/schemas/event'
        continuation:
          description: Describes result of a defpact execution.
          properties:
            pactId:
              type: string
              description: Identifies this defpact execution. On first step generally matches request key.
            step:
              type: number
              description: Identifies which step executed in defpact.
            stepCount:
              type: number
              description: Total number of steps in pact.
            executed:
              type: boolean
              description: optional value for private pacts, indicates if step was skipped.
            stepHasRollback:
              type: boolean
              description: indicates if pact step has rollback.
            continuation:
              description: Closure describing executed pact.
              properties:
                def:
                  type: string
                  description: Fully-qualified defpact name.
                args:
                  type: array
                  items:
                    $ref: '#/components/schemas/pact-value'
            yield:
              description: Value yielded during pact step, optionally indicating cross-chain execution.
              properties:
                data:
                  type: object
                  description: Pact value object containing yielded data.
                  additionalProperties:
                    $ref: '#/components/schemas/pact-value'
                source:
                  type: string
                  description: Source chain ID.
                provenance:
                  properties:
                    targetChainId:
                      type: string
                      description: Chain ID of target chain for next step.
                    moduleHash:
                      description: Hash of module executing defpact.
                      type: string
        gas:
          type: number
    request-key:
      title: Request Key
      type: string
      description: Unique ID of a pact transaction consisting of its hash.
      pattern: ^[a-zA-Z0-9_-]{43}$
      contentEncoding: base64url
      minLength: 43
      maxLength: 43
      example: y3aWL72-3wAy7vL9wcegGXnstH0lHi-q-cfxkhD5JCw
  examples:
    module_reference:
      refName:
        namespace: null
        name: coin
      refSpec:
      - namespace: null
        name: fungible-v2
    command-result:
      gas: 123
      result:
        status: success
        data: 3
      reqKey: cQ-guhschk0wTvMBtrqc92M7iYm4S2MYhipQ2vNKxoI
      logs: wsATyGqckuIvlm89hhd2j4t6RMkCrcwJe_oeCYr7Th8
      metaData: null
      continuation: null
      txId: '456'
      events:
      - name: TRANSFER
        params:
        - Alice
        - Bob
        - 10.0
        module: coin
        moduleHash: ut_J_ZNkoyaPUEJhiwVeWnkSQn9JT9sQCWKdjjVVrWo
x-tagGroups:
- name: chainweb_p2p
  x-displayName: Chainweb P2P API
  tags:
  - p2p_api
  - cut
  - blockhash
  - header
  - payload
  - mempool
  - peer
  - config
- name: chainweb_service
  x-displayName: Chainweb Service API
  tags:
  - service_api
  - block
  - misc
  - mining
  - pact
- name: Common HTTP Headers
  tags:
  - commonResponseHeaders
- name: Data Models
  tags:
  - cut_model
  - header_model
  - payload_model
  - payloadWithOutputs_model
  - peer_model
  - nodeInfo_model
  - page_model
  - minerInfo_model
  - miningUpdateEventStream_model
- name: Binary Encodings
  tags:
  - binaryHeader
  - binaryWorkHeader