The Pact REST API — the transactional API for a runtime offering Pact smart contracts on a Chainweb chain. Endpoints: /local (non-transactional execution and preflight), /send (submit signed commands), /poll and /listen (retrieve results by request key), /private (private transactions), and /spv (simple payment verification proofs).
openapi: '3.0.0'
# ############################################################################ #
# Info
# ############################################################################ #
info:
title: Pact REST API
description: |
Transactional API for a runtime offering Pact smart contracts.
version: '1.3.7'
x-logo:
url: 'https://i.imgur.com/bAZFAGF.png'
# backgroundColor: '#0033A0'
alttext: Kadena Chainweb Logo
href: 'https://api.chainweb.com/openapi'
# ############################################################################ #
# Servers
# ############################################################################ #
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"
# ############################################################################ #
# Paths
# ############################################################################ #
paths:
# ########################################################################## #
# Local
# ########################################################################## #
/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'
# ########################################################################## #
# Send
# ########################################################################## #
/send:
post:
description: |
Asynchronous submission of one or more public (unencrypted) commands
to the blockchain for execution.
tags: [endpoint-send]
summary: send
requestBody:
content:
application/json:
schema:
type: object
required: [cmds]
properties:
cmds:
type: array
minItems: 1
items:
$ref: '#/components/schemas/command'
responses:
"200":
description: The commands were successfully submitted. The response contains their request keys.
content:
application/json:
schema:
type: object
required: [requestKeys]
properties:
requestKeys:
description: Request keys for use with `poll` or `listen` to retrieve results.
type: array
minItems: 1
items:
$ref: '#/components/schemas/request-key'
"400":
description: The command failed.
content:
text/plain:
type: string
example: 'Validation failed for hash "j5f3mZaF9pVA7OmV4nTuw5-paG9LzLQJWAMuGGRRLeQ": Attempt to buy gas failed with: (read coin-table sender): Failure: Tx Failed: read: row not found: 368820f80c324bbc7c2b0610688a7da43e39f91d118732671cd9c7500ff43cca'
schema:
$ref: '#/components/schemas/validation-failure'
# ########################################################################## #
# Poll
# ########################################################################## #
/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'
# ########################################################################## #
# Listen
# ########################################################################## #
/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'
# ########################################################################## #
# Private
# ########################################################################## #
/private:
post:
description: |
Asynchronous submission of a single addressed command which
will be transmitted with end-to-end encryption only between addressed entity nodes.
Private payload metadata required.
tags: [endpoint-private]
summary: private
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/command'
responses:
"200":
description:
The command was accepted.
content:
application/json:
type: object
schema:
properties:
requestKeys:
description: Request keys for use with `poll` or `listen` to retrieve results.
type: array
minItems: 1
maxItems: 1
items:
$ref: '#/components/schemas/request-key'
# ########################################################################## #
# SPV
# ########################################################################## #
/spv:
servers:
- url: "https://api.chainweb.com/chainweb/{apiVersion}/mainnet01/chain/{chainId}/pact"
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"
description: Pact API for a chain on the Kadena testnet.
variables:
apiVersion:
default: "0.0"
chainId:
default: "0"
post:
description: |
Blocking request to fetch spv proof of a cross chain transaction. Request must be sent to the chain where the transaction is initiated.
summary: spv
tags: [endpoint-spv]
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/spv-object'
responses:
"200":
description: The requested spv proof.
content:
application/json:
schema:
$ref: '#/components/schemas/spv-proof'
"400":
description: The requested spv proof was not findable.
content:
text/plain:
example: "SPV target not reachable: target chain not reachable. Chainweb instance is too young"
schema:
description: Error message with the description of failed proof requests.
type: string
# ############################################################################ #
# Components
# ############################################################################ #
components:
# ########################################################################## #
# Schemas
schemas:
# ######################################################################## #
# Command Schema and related
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'
webauthn-sig-string:
type: string
# contentMediaType: application/json
description: |
Stringified JSON WebAuthn signature object.
For a WebAuthn signature string to be valid, its corresponding `Signer`
must have `scheme: "WebAuthn"`.
The schema of a Pact WebAuthn signature object resembles that of
the WebAuthn standard `CredentialResponse`.
Its fields can be computed from the `response` field of a WebAuthn
`CredentialResponse`. For example, to construct a WebAuthn signature
string in the browser:
```
const resp = await navigator.credentials.get();
const auth = resp.response.authenticatorData();
const sig = resp.response.signature;
JSON.stringify({
authenticatorData: base64url_to_base64(auth),
clientDataJSON: resp.response.clientDataJSON,
signature: base64url_to_base64(sig)
})
```
payload:
description: |
Pact Command Payloads are encoded as strings in Pact commands, and contain all
non-malleable data for a transaction.
tags: [model-payload]
type: object
required: [payload,meta,signers,networkId,nonce]
example:
$ref: '#/components/examples/payload'
properties:
payload:
oneOf:
- title: Exec Message
description: Standard pact execution.
properties:
code:
type: string
description: Executable pact code.
data:
description: Arbitrary JSON to be accessed via `read-msg`, `read-integer` et al in Pact code.
- title: Continuation Message
description: Continuation of a previous transaction defpact.
properties:
pactId:
type: string
description: ID of pact running previous step.
step:
type: number
description: Step in defpact to execute.
rollback:
type: boolean
description: Whether to execute a specified rollback on this step.
data:
description: Arbitrary JSON to be accessed via `read-msg`, `read-integer` et al in Pact code.
proof:
type: string
contentEncoding: base64url
description: Backend-specific data for continuing a cross-chain proof.
meta:
oneOf:
- title: "Public metadata (Chainweb)"
description: "Chainweb/public command metadata."
required: [chainId,sender,gasLimit,gasPrice,ttl,creationTime]
properties:
chainId:
type: string
description: Platform-specific chain identifier. For chainweb this is the stringified chain number.
sender:
type: string
description: Indicates gas-paying account.
gasLimit:
type: number
minimum: 1
description: Limits total amount of gas to be consumed.
gasPrice:
type: number
description: Specifies price per gas unit to be charged.
ttl:
type: number
minimum: 1
maximum: 180000
description: Time in seconds after creation time that transaction can be executed.
creationTime:
type: number
description: POSIX epoch sending time for transaction.
- title: "Private metadata (Kuro)"
description: "Metadata for Kuro endpoints, including `private`."
properties:
address:
description: Private message envelope address. Required only for private messages, otherwise null.
required: [from,to]
properties:
from:
type: string
description: "Sender entity name"
to:
description: "Recipient entity names"
type: array
minItems: 1
items:
type: string
description: "Recipient entity name"
signers:
description: List of signers, corresponding with list of signatures in outer command.
type: array
items:
title: Signer
required: [pubKey]
properties:
pubKey:
type: string
description: "Public key image. Pact default is base16 ED25519 encoding."
address:
type: string
description: "Address, if any. Pact default expects this to match pubKey."
scheme:
type: string
description: |
Signer scheme. Default is ED25519. When the Signer is
`WebAuthn`, the corresponding `sig` must be a WebAuthn
signature string.
enum: [ED25519,WebAuthn]
clist:
description: List of capabilities associated with/installed by this signer.
properties:
name:
type: string
description: Fully-qualified capability name.
args:
type: array
items:
$ref: '#/components/schemas/pact-value'
networkId:
description: Backend-specific identifier of target network.
type: string
enum: [mainnet01,testnet04]
nonce:
description: Arbitrary user-supplied value.
type: string
spv-object:
description: |
Object consisting of data required to fetch proof of a cross chain transaction
type: object
required: [requestKey,targetChainId]
properties:
requestKey:
type: string
description: Request Key of an initiated cross chain transaction at the source chain.
example:
"7af34f24d55d2fcf5de6fccfeeb837698ebff4598303237c64348a47806c8646"
targetChainId:
type: string
description: Target chain id of the cross chain transaction.
example: "1"
# ######################################################################## #
# Command Result and related
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-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
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.
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.
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
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
validation-failure:
title: Validation Failure
type: string
description: Failure message of unexecuted command due to an invalid gas payer, meta, or other environments.
spv-proof:
title: SPV Proof
type: string
description: Backend-specific data for continuing a cross-chain proof.
example: |
"eyJzdWJqZWN0Ijp7ImlucHV0IjoiQUJSN0ltZGhjeUk2TlRRMExDSnlaWE4xYkhRaU9uc2ljM1JoZEhWeklqb2ljM1ZqWTJWemN5SXNJbVJoZEdFaU9pSlhjbWwwWlNCemRXTmpaV1ZrWldRaWZTd2ljbVZ4UzJWNUlqb2lZa0Y0TjNOd1dqZFdUbUpZWTNocVZFUkNTamt5U21SdlUyVlFjWGx0U25KNWNXOUNhMWcyUkVoYWJ5SXNJbXh2WjNNaU9pSnBRVTF4Y0ZwaVUxSkRaR2hQUzA1YVVYZzFTMHBOTFZOUlNGRlZXRzF4UlZoUlRIRkNUVVpSVFVkSklpd2laWFpsYm5SeklqcGJleUp3WVhKaGJYTWlPbHNpZEdWemRDMXpaVzVrWlhJaUxDSXpaRGxsT1dZeFptSTBZemt6TnpneU5qWmpZV1JrTmpObE4yRTBOMkkzWVRZME5UTmlaVGsyTVdSaU1ETTNNMlkxWXpWbVlUUXdZV05sWlRaaVpHVm1JaXd4WFN3aWJtRnRaU0k2SWxSU1FVNVRSa1ZTSWl3aWJXOWtkV3hsSWpwN0ltNWhiV1Z6Y0dGalpTSTZiblZzYkN3aWJtRnRaU0k2SW1OdmFXNGlmU3dpYlc5a2RXeGxTR0Z6YUNJNkluVjBYMHBmV2s1cmIzbGhVRlZGU21ocGQxWmxWMjVyVTFGdU9VcFVP
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kadena/refs/heads/main/openapi/kadena-pact-openapi-original.yml