Kadena endpoint-local API

openapi: 3.2.0
info:
  title: Pact REST Endpoint Local 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-local
  x-displayName: Non-transactional execution
paths:
  /local:
    post:
      description: 'Blocking/sync call to submit a command for non-transactional execution. In a

        blockchain environment this would be a node-local “dirty read”, which can

        either serve as a node-local repl execution, or fully gassed transaction

        simulation and transaction validation. Any database writes or changes to the

        environment are rolled back.'
      tags:
      - endpoint-local
      summary: local
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/command'
      parameters:
      - name: preflight
        in: query
        description: 'Trigger fully-gassed mainnet transaction execution simulation and

          transaction metadata validations.

          '
        required: false
        schema:
          type: boolean
      - name: rewindDepth
        in: query
        description: 'Rewind transaction execution environment by a number of block

          heights.

          '
        required: false
        schema:
          type: integer
          minimum: 0
      - name: signatureVerification
        in: query
        description: 'Require user signature verification when validating transaction

          metadata.

          '
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: The command's result.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/command-result'
                - $ref: '#/components/schemas/preflight-result'
        '400':
          description: The command was invalid.
          content:
            text/plain:
              type: string
              example: 'Validation failed: Invalid command: Failed reading: empty'
              schema:
                $ref: '#/components/schemas/validation-failure'
      operationId: postLocal
      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
    validation-failure:
      title: Validation Failure
      type: string
      description: Failure message of unexecuted command due to an invalid gas payer, meta, or other environments.
    preflight-result:
      title: Preflight /local result
      tags:
      - model-preflight-result
      example:
        $ref: '#/components/examples/preflight-result'
      description: The result of attempting to execute preflight simulation for a single well-formed Pact command.
      type: object
      required:
      - preflightResult
      - preflightWarnings
      properties:
        preflightResult:
          $ref: '#/components/schemas/command-result'
        preflightWarnings:
          description: A list of warnings associated with deprecated features in upcoming pact releases.
          type: array
          items:
            type: string
    command:
      title: Pact Command
      tags:
      - model-command
      description: Represents a single blockchain Pact transaction.
      type: object
      required:
      - cmd
      - hash
      - sigs
      example:
        $ref: '#/components/examples/command'
      properties:
        cmd:
          description: 'Stringified JSON `payload` object. Canonic non-malleable signed transaction data.

            '
          type: string
        hash:
          description: 'Unpadded Base64URL of Blake2s-256 hash of the `cmd` field value. Serves as a command

            `requestKey` since each transaction must be unique.

            '
          type: string
          contentEncoding: base64url
          example: H6XjdPHzMai2HLa3_yVkXfkFYMgA0bGfsB0kOsHAMuI
        sigs:
          description: 'List of signatures corresponding one-to-one with `signers` array in the payload.

            '
          type: array
          minItems: 0
          items:
            properties:
              sig:
                anyOf:
                - type: string
                  contentEncoding: base16
                  description: 'Base16-encoded Ed25519 signature of `hash` field

                    for corresponding signer in payload.

                    '
                  example: 8d452109cc0439234c093b5e204a7428bc0a54f22704402492e027aaa9375a34c910d8a468a12746d0d29e9353f4a3fbebe920d63bcc7963853995db015d060f
                - $ref: '#/components/schemas/webauthn-sig-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.
    webauthn-sig-string:
      type: string
      description: "Stringified JSON WebAuthn signature object.\n\nFor a WebAuthn signature string to be valid, its corresponding `Signer`\nmust have `scheme: \"WebAuthn\"`.\n\nThe schema of a Pact WebAuthn signature object resembles that of\nthe WebAuthn standard `CredentialResponse`.\nIts fields can be computed from the `response` field of a WebAuthn\n`CredentialResponse`. For example, to construct a WebAuthn signature\nstring in the browser:\n\n```\nconst resp = await navigator.credentials.get();\nconst auth = resp.response.authenticatorData();\nconst sig = resp.response.signature;\nJSON.stringify({\n  authenticatorData: base64url_to_base64(auth),\n  clientDataJSON: resp.response.clientDataJSON,\n  signature: base64url_to_base64(sig)\n})\n```\n"
  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
    preflight-result:
      preflightResult:
        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
      preflightWarnings:
      - 'Warning: Using deprecated native +: decimal/integer operator overload is deprecated'
    command:
      hash: H6XjdPHzMai2HLa3_yVkXfkFYMgA0bGfsB0kOsHAMuI
      sigs:
      - sig: 8d452109cc0439234c093b5e204a7428bc0a54f22704402492e027aaa9375a34c910d8a468a12746d0d29e9353f4a3fbebe920d63bcc7963853995db015d060f
      cmd: '{"payload":{"exec":{"data":null,"code":"(+ 1 2)"}},"signers":[{"pubKey":"368820f80c324bbc7c2b0610688a7da43e39f91d118732671cd9c7500ff43cca"}],"meta":{"gasLimit":1000,"chainId":"0","gasPrice":1.0e-2,"sender":"368820f80c324bbc7c2b0610688a7da43e39f91d118732671cd9c7500ff43cca"},"nonce":"nonce-value"}'
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