Kadena endpoint-poll API

openapi: 3.2.0
info:
  title: Pact REST Endpoint Poll API
  description: Transactional API for a runtime offering Pact smart contracts.
  version: 1.3.7
  x-logo:
    url: https://i.imgur.com/bAZFAGF.png
    alttext: Kadena Chainweb Logo
    href: https://api.chainweb.com/openapi
servers:
- url: https://api.chainweb.com/chainweb/{apiVersion}/mainnet01/chain/{chainId}/pact/api/v1
  description: Pact API for a chain on the Kadena mainnet.
  variables:
    apiVersion:
      default: '0.0'
    chainId:
      default: '0'
- url: https://api.testnet.chainweb.com/chainweb/{apiVersion}/testnet04/chain/{chainId}/pact/api/v1
  description: Pact API for a chain on the Kadena testnet.
  variables:
    apiVersion:
      default: '0.0'
    chainId:
      default: '0'
tags:
- name: endpoint-poll
  x-displayName: Batch polling for results
paths:
  /poll:
    post:
      description: Allows polling for one or more command results by request key.
      summary: poll
      tags:
      - endpoint-poll
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - requestKeys
              properties:
                requestKeys:
                  type: array
                  minItems: 1
                  items:
                    $ref: '#/components/schemas/request-key'
      parameters:
      - name: confirmationDepth
        in: query
        description: 'Configures how many blocks should be mined until the requested transaction is ready.

          '
        required: false
        schema:
          type: integer
          minimum: 0
      responses:
        '200':
          description: The command results for some of the requested request keys.
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/command-result'
      operationId: postPoll
      x-operation-id-source: derived
components:
  schemas:
    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
    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
    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
    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
                - 'null'
                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
                  - 'null'
                  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.
    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.
  examples:
    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
    module_reference:
      refName:
        namespace: null
        name: coin
      refSpec:
      - namespace: null
        name: fungible-v2
x-tagGroups:
- name: std-pact-api
  x-displayName: Standard Pact API
  tags:
  - endpoint-local
  - endpoint-send
  - endpoint-poll
  - endpoint-listen
- name: private-api
  x-displayName: Private Pact API
  tags:
  - endpoint-private
- name: spv-api
  x-displayName: SPV API
  tags:
  - endpoint-spv
- name: models
  x-displayName: Pact API models
  tags:
  - model-command
  - model-command-result
  - model-payload
  - model-pact-value