Skip to content

Declarative binding authoring commands

For a guided introduction, start with your first workflow. The learning path explains separate YAML versus inline documents, and the Studio editor chapter shows the guided editor that uses the catalog and report files described below.

appchain bindings compiles and checks ADR-031.1 documents against the actual plugin bundles selected for the application. It does not start a node or submit transactions. Use the matching Yano X CLI, Yano host API, and dependency-complete plugin bundles from one build.

Terminal window
./yano.sh appchain bindings compile bindings.yml \
--plugins-directory /absolute/path/to/plugins --context context.json
./yano.sh appchain bindings validate bindings.yml \
--plugins-directory /absolute/path/to/plugins --context context.json
./yano.sh appchain bindings graph bindings.yml \
--plugins-directory /absolute/path/to/plugins --context context.json
./yano.sh appchain bindings dry-run bindings.yml \
--plugins-directory /absolute/path/to/plugins --context context.json \
--fixture fixture.json

All results go to stdout. Redirect them to a new file when needed. compile prints canonical IR hex. validate prints JSON containing the actual profile’s manifest and diagnostic status. graph prints Graphviz DOT. dry-run prints canonical receipt hex, decoded receipt arrays, effect intents, and physical state changes and a complete postState rehearsal snapshot. Construction failures retain authored paths such as $.composite.components[0].config; JSON conversion failures retain field/index paths rather than only an underlying constructor message.

Terminal window
./yano.sh appchain bindings receipt-key "$SOURCE_MESSAGE_ID"

This data-only command accepts exactly one 32-byte source message ID and prints stateKeyHex, receiptQueryPath, and keyQueryPath. It uses the public workflow namespace encoder; no manual CBOR or namespace concatenation is needed. The key survives replacement of the same logical workflow. It does not assert that the receipt exists or prove anything by itself. Use stateKeyHex with the normal chain state-proof endpoint and verify against a separately trusted root. The runtime composite/binding-receipt-key-v1/<id> query discovers the same raw physical key: the generic HTTP query envelope’s payloadHex is directly usable as the proof key, with no CBOR decoding. This query takes empty parameters and works even when the receipt is absent; it is not a presence claim.

Terminal window
./yano.sh appchain bindings dry-run bindings.yml \
--plugins-directory /absolute/path/to/plugins --context context.json \
--fixture block-1.json > result-1.json
./yano.sh appchain bindings dry-run bindings.yml \
--plugins-directory /absolute/path/to/plugins --context context.json \
--fixture block-2.json --prior-result result-1.json > result-2.json

For a bounded continuation without duplicated receipt diagnostics, add --continuation-only to dry-run; its output is directly accepted by the next --prior-result. To preserve a full diagnostic result and a compact continuation without executing twice:

Terminal window
jq '{assurance,height,executionIdentity,postState}' result-1.json > continuation-1.json

The compact artifact fits the continuation input bound even at maximum fixture state size. Full diagnostic results may be larger because they repeat state and receipt encodings; extract the compact fields before continuing those results.

The next fixture must have state: [] and the immediately following height. Its messages, timestamp, assumed predecessor stateRootHex, and pendingEffects remain explicit. The CLI carries the previous complete physical postState, including retained receipts, rather than incorrectly treating a change set as complete state. A fresh catalog machine is constructed for each invocation. The continuation identity checks canonical IR, explicit chain/context, and the catalog-created capability manifest; a changed profile/context is rejected. Same-ID replay therefore retains the original receipt without reapplying its business effects.

These artifacts are editable, unverified rehearsal inputs, not authenticated node exports or backups. Their identity detects accidental mixing, not tampering. No post-state root is computed; no finality, proof, signature, or effect delivery is verified. Do not import postState into a running chain. Keep predecessor root and pending-effect assumptions appropriate to the scenario being rehearsed. Continuation input is capped at 64 MiB and still obeys the fixture’s independent state-entry and memory bounds; it is intended for bounded application rehearsals.

Two additions serve Studio’s guided editor. Neither changes what the commands above print, their diagnostics or their exit codes; only the usage text gains the new command and option.

Terminal window
./yano.sh appchain bindings catalog [bindings.yaml] \
--plugins-directory /absolute/path/to/plugins --context context.json \
[--machine <selector>]... [--all] > catalog.json

This writes yano-x-binding-authoring-catalog-v1 JSON (at most 8 MiB; larger output fails rather than truncating). It lists every installed machine selector without constructing it, then describes only the instances you ask for: the components of the given document with their exact authored configuration, each --machine with empty configuration, or every selector with --all. Each instance records its status (available, requires-configuration, construction-failed, descriptor-failed or not-composable), configuration descriptor, normalized configuration, events, commands and whether raw bodies may target it. For admission rules (ADR-031.3) an available instance also records commandSelectable (whether a rule may select one of its commands), unselectableReason (why not, or null) and ruleFacts (each declared fact’s name and type: integer, text, bytes, boolean or text-set). For typed views (ADR-031.4) it records ruleValueViews, one entry per view with its namespace, its fields and the schema-member valueFields that rules read as reads.<name>.value.<member>. A kernel with a write view adds ruleWriteFields and ruleWriteCoverageFields, the content and verified-coverage fields of one write element; both are absent for other kernels. Every field entry has a name and type. The file also carries the binding language tables (functions, expression operators, limits, the baseline event and receipt codes) and the identity of the tool, host, plugin catalog and context digest.

Probing constructs your installed plugins exactly as compilation does, running their code unsandboxed, so export catalogs only from bundles you trust. The catalog installs, activates and trusts nothing, and describes descriptors for this plugin catalog, context and configuration only. Reports match only a catalog exported by the same tool from the same plugin directory and context. Studio never normalizes configuration: a component whose settings differ from a described instance is shown as not described, so export the catalog again from the edited document.

compile, validate and dry-run accept --report <file> and then also write a yano-x-binding-report-v1 JSON file for Studio. Standard output, standard error and the exit status stay exactly as without the option (the report is written before standard output). The report is not written for usage errors (exit 64) or unreadable inputs (exit 74). Writing it fails with exit 74 and no standard output if the file cannot be written or would exceed 16 MiB. The target must not be one of the inputs or inside the plugin directory, and it is replaced atomically with owner-only permissions where the filesystem supports them.

A report records:

  • the operation and whether it completed or failed;
  • the producer, host and plugin-catalog identities (versions, JAR digests and the catalog fingerprint) and the authoring-environment id;
  • each input’s role, read state, byte count and the SHA-256 of its exact bytes;
  • for success: canonical IR hex and its SHA-256, the active profile digest and execution version, and component/binding counts;
  • for dry-run: the assumed height, timestamp, prior root and pending effects, every source message with its disposition (executed, replay-existing-receipt or duplicate-in-fixture), canonical receipt hex and decoded view, effects, the number of state changes and a post-state digest;
  • structured diagnostics: a stable code, controlled text, the bounded historical detail with absolute paths redacted, and the exact authored location when known;
  • the receipt-code table used to explain outcomes.

The post-state digest is SHA-256 over the ASCII bytes yano-x-binding-post-state-v1, a zero byte, and then, for each post-state entry in ascending unsigned byte order of its key (the order of the lowercase hexadecimal keys), the 4-byte big-endian key length, the key bytes, the 4-byte big-endian value length and the value bytes. A continued rehearsal records the previous result’s digest so Studio can check that consecutive reports form one sequence.

Reports are ordinary, unauthenticated files. Studio decodes every receipt from its canonical bytes and rejects reports that contradict themselves. It treats a report as describing the current draft only when the document digest, the context digest, the tool and host identities and the plugin catalog all match. A dry-run’s rehearsal is verified only when, in addition, the fixture file is imported and matches its recorded digest, and every earlier block it continues is verified in the same way. A match shows the same inputs were used; it is not an attestation, a finality certificate or deployment approval.

examples/bindings/dpp-approval.yaml and examples/bindings/feed-approval.yaml connect actor-signed approvals to a governed authenticated map with real schemas and policies, over a deterministic demo genesis. Validate the DPP example with the context shipped for its role-gated variant, which uses the same genesis:

Terminal window
./yano.sh appchain bindings validate examples/bindings/dpp-approval.yaml \
--plugins-directory /absolute/path/to/plugins \
--context examples/bindings/fixtures/dpp-role-gated/context.json

Never use the demo keys in production. For your own organizations, actors, and keys, declare a governed map’s genesis in the authenticatedMap section of a setup draft and seal it, as described in governed collections; each actor signs its proof of key possession offline with appchain role key-proof-signature. The DPP and feed starter generators moved with those products to yano-x-products. No context ships for the feed example.

Before changing plugin bundles for retained profiles, run:

Terminal window
./yano.sh appchain bindings profile-check --profiles profiles.json \
--context context.json --plugins-directory /absolute/path/to/candidate-plugins

profiles.json is a bounded JSON array of retained canonical composite profile hex strings. The checker constructs the real candidate catalog and verifies byte-exact reproduction, reporting reproducesProfiles, expected profile digests, and bounded diagnostics. Exit zero means all supplied profiles were reproduced; exit 2 means invalid/incompatible input, 64 is usage, and 74 is I/O. Use the original explicit chain context. This is an upgrade preflight, not a migration tool, replay test, proof verification, or semantic-equivalence claim. Retain independent replay/proof regression evidence before deploying an upgrade. The upgrade reference steps through each check and its failures.

The default event allowance is 65,536 encoded bytes. A baseline payload contains command-body metadata only when a binding subscribes to that event; other sources have no baseline-wrapper command cap. Admission checks any required baseline size and statically impossible mandatory work before execution. A fixture containing an admission-invalid source fails validation rather than fabricating a finalized rejection receipt. Dynamic cascade failures still produce receipts. See submission validity and retry for HTTP outcomes, fresh-message retry semantics, and committed work budgets.

For a document with admission rules, validate adds an admission list: each component with attached rules and its rules in evaluation order (the admission slot in attachment order, then the verified-fact slot), with each rule’s command selector (* for any), deny code, slot, whether it is static, its reads (name = component/namespace, or name = component for the default namespace) and whether it quantifies over writes (writes). The slot and static-ness are the profile’s resolved values: a rule that reads write coverage is a fact rule because its kernel says so. graph draws a guard node (an octagon with a dashed edge) on each such component, listing its rules in the same order with their reads; graph --ir, which loads no plugin, marks a write rule it cannot place as (writes; slot resolved by the kernel). profile-check reconstructs profiles with rules like any other; rules are part of the profile digest. A rule failure found while constructing the profile is located at its authored path in the --report diagnostic (plain output names the component and attachment in its message), for example $.composite.components[3].admission[0].params.binding.

Pass --ir to read an IR hex file instead of YAML. graph --ir is a data-only operation and needs neither a plugin directory nor context; it does not claim the graph is executable. The other commands always construct the real profile through the host plugin catalog. Unmanifested libraries, missing providers, incompatible API levels, invalid mappings, and cyclic command graphs fail closed. Optional providers are never instantiated as a fallback. The sole host builtin, OrderedLog, uses the same explicit resolution branch as a running node.

The input is a chain’s composite object, either directly or wrapped in one composite property. This example copies every accepted key/value change to an audit trail:

composite:
components:
- {id: records, machine: kv-registry}
- {id: audit, machine: doc-trail}
bindings:
- id: audit-record
from: {component: records, event: kv-registry.entry-put.v1}
when: [{expr: 'event.valueLength < 100'}]
to:
component: audit
command: append
map:
entityId: {fn: hex, args: [{field: key}]}
entryHash: {field: valueHash}
reference: {literal: published}

The registry key is bytes, whereas document-trail entity IDs are text. The explicit hex conversion is required; mappings never silently coerce types.

Authoring rules:

  • Component ingress topics default to <id>.command.v1. Configuration defaults come from the exact selected kernel and are included in the IR.
  • Component fromHeight and top-level workflowFromHeight default to 1. Replacements still need the normal governed profile activation procedure.
  • Scalar literals are signed int64, text, boolean, or bytes written as {bytesHex: '00ff'}. For example: {literal: {bytesHex: '00ff'}}.
  • Sources are exactly one of {field: name}, {context: name}, {literal: value}, {fn: name, args: [...]}, or {expr: 'restricted CEL'}. {field} reads the triggering event and {context} the step context. Rules, their lookup keys and their read keys use {command: name}, {param: name}, {config: name} and {fact: name} instead of {field}; those four are not available to bindings.
  • Field conditions are {field: name, eq: value}, using one of eq, ne, lt, le, gt, ge, in, exists, or absent. The last two require true. CEL conditions use {expr: 'boolean expression'}.
  • Lookup conditions are {lookup: {component: registry, key: {field: key}, exists: true}}. Alternatives are absent: true or eq: {literal: {bytesHex: '01'}} / eq: {field: eventBytes}. Keys follow the selected kernel’s logical-key contract.
  • A command target uses component, command, and map. An opaque bytes mapping uses rawBody: fieldName instead of map; evidence-bearing target commands reject this bypass.
  • An effect target is to: {effect: {type: webhook.post, gate: app-final, result: none, map: identity}}. Its originating component needs an explicit positive maxEffectsPerBlock quota and the consensus context must enable effects. No effect executor is invoked by these commands.
  • Unknown or duplicate fields, ambiguous operators/sources, unsupported CEL, YAML aliases, and multiple YAML documents are errors. Component/binding order is preserved; assignment/configuration map ordering is normalized.

The context is strict JSON, not a node configuration. Copy the exact chain identity, consensus profile, and membership epoch of the intended application. Never generate a replacement genesis ID for an existing chain. Component machines.* settings are rejected here: put them in the document’s component configuration so they are committed.

The following values are an offline-only example, not a retained deployment’s identity or an instruction to provision a chain:

{
"chainId": "offline-test",
"settings": {
"state.commitment-profile": "mpf-blake2b256-v1",
"state.format-fingerprint": "91ee14091200f1e24659112d640e877e9177779dcc81dd06117f013e9190082b",
"state.genesis-id": "0000000000000000000000000000000000000000000000000000000000000000"
},
"consensusProfile": {
"schemaVersion": 2,
"maxMessageBytes": 65536,
"maxBlockMessages": 100,
"maxBlockBytes": 1048576,
"l1StabilityDepth": 0,
"epochStabilityDepth": 0,
"blockMaxForwardSkewMs": 5000,
"enforceSenderSeq": false,
"effectsEnabled": false,
"effectsMaxPerBlock": 0,
"effectsMaxPayloadBytes": 0,
"effectsMaxExpiryBlocks": 0,
"effectsResultWindowBlocks": 0,
"effectsDefaultGate": "APP_FINAL",
"effectsOutcomeCommitment": "PER_EFFECT",
"effectsStrictReservedPrefix": true,
"effectResultSigners": []
},
"membership": {
"fromHeight": 0,
"members": ["2222222222222222222222222222222222222222222222222222222222222222"],
"threshold": 1
}
}

A fixture executes one block containing zero or more ordinary source messages. Message order is the original block order. state contains physical composite keys, not machine-local keys; each entry is {keyHex, valueHex}. Empty state and height 1 exercise genesis initialization. For a later height, supply the actual preceding state, including composite/profile markers. Use explicit messages: [] to rehearse an empty block. It still initializes the machine and executes its full block lifecycle, including height-driven work; it emits no source receipts. Continue through every intervening height rather than jumping directly to a later height.

{
"height": 1,
"timestamp": 123,
"stateRootHex": "0000000000000000000000000000000000000000000000000000000000000000",
"pendingEffects": 0,
"state": [],
"messages": [{
"messageIdHex": "1111111111111111111111111111111111111111111111111111111111111111",
"senderHex": "2222222222222222222222222222222222222222222222222222222222222222",
"senderSeq": 1,
"expiresAt": 9223372036854775807,
"topic": "records.command.v1",
"bodyHex": "8300420102420304",
"authProofHex": "00"
}]
}

This deliberately synthetic authentication proof is acceptable only because dry-run assumes that envelope authentication already happened. The ordinary registry command puts bytes 0304 at key 0102; the audit entity becomes text 0102. The returned receipt bytes come from the real composite query, not a separate simulation of its transition logic.

When any step evaluated admission rules, a receipt entry in the dry-run output also carries rules: each step’s ordinal, depth, component, the number of rules that held and the first failure (rule, zero-based clause, deny code, and the index of the deciding write when a quantifier stopped early). A receipt refused by a rule carries refusal: the step, the rule and clause, the deny code, the deciding write if any, and an explanation. A refusal at depth 1 or deeper states that the whole cascade, including the source command, was rolled back. A message that a static rule refuses never reaches a block, as at a node’s ingress: dry-run stops with the full reason on standard error, and with the diagnostic code FIXTURE_ADMISSION_REJECTED in a --report file, for example ADMISSION_RULE_DENIED/transfer-limit/TRANSFER_LIMIT_EXCEEDED, followed by at write N when a quantifier decided. A node’s REST refusal carries the same code, rule, deny code and write as structured details.

The rule recipes ship with fixtures, one block per file, meant to be run in order with --prior-result: examples/bindings/fixtures/balances-transfer-limit/ (block 3 is an over-limit transfer that stops at fixture admission), procurement-admission/ (blocks 1 and 4 are block-time refusals), and dpp-role-gated/, which also contains the governed context.json that recipe’s genesis requires. The ADR-031.4 recipes asset-governed-limits/, dpp-namespace-isolation/, feed-slot-rules/ and balances-holding-cap/ each ship a context.json and one fixture per block, including their refusals (block 3 of dpp-namespace-isolation/ is a batch refused at write 1).

Dry-run does not verify message signatures, membership proofs, certificates, fixture state roots, or anchors; it does not calculate a post-state root. It does not process reserved framework inputs or deliver effects. It is not a substitute for node, replay, distribution, or multi-node acceptance testing. Fixture input, memory, state entry sizes, and output mutation counts are bounded independently of the committed workflow limits. A fixture-capacity error is a tooling failure, not a new consensus rejection code.

Worked proposal and two approvals through the packaged launcher

Section titled “Worked proposal and two approvals through the packaged launcher”

This small approvals example uses consensus-member voting, separate from the actor-signed DPP/feed policies above. Save this as approval.yml:

composite:
components:
- {id: reviews, machine: approvals}
- {id: audit, machine: doc-trail}
bindings:
- id: record-approved
from: {component: reviews, event: approvals.item-approved.v1}
to:
component: audit
command: append
map:
entityId: {field: itemId}
entryHash: {field: payloadHash}
reference: {literal: approved}

Start with the offline context.json above and add the second public member. These repeated-byte identities and assumed envelope authentication are rehearsal data only; there are no private keys or valid envelope signatures here.

Terminal window
jq '.membership.members += [("33" * 32)] | .membership.threshold = 2' \
context.json > approval-context.json

Save this as propose.json. The short body is the public ApprovalsContract.propose("a", new byte[]{1}, 2, 0) encoding: item a, payload 01, two votes required, no deadline. The approval body 82016161 is ApprovalsContract.approve("a"). No manual physical state encoding is needed.

{
"height": 1,
"timestamp": 100,
"stateRootHex": "0000000000000000000000000000000000000000000000000000000000000000",
"pendingEffects": 0,
"state": [],
"messages": [{
"messageIdHex": "1111111111111111111111111111111111111111111111111111111111111111",
"senderHex": "2222222222222222222222222222222222222222222222222222222222222222",
"senderSeq": 1,
"expiresAt": 999999999,
"topic": "reviews.command.v1",
"bodyHex": "8500616141010200",
"authProofHex": "00"
}]
}

Create two fresh approval messages, then invoke the packaged CLI once per block:

Terminal window
jq '.height = 2 | .timestamp = 200 | .messages[0] |=
(.messageIdHex = ("44" * 32) | .senderSeq = 2 | .bodyHex = "82016161")' \
propose.json > approve-1.json
jq '.height = 3 | .timestamp = 300 | .messages[0] |=
(.messageIdHex = ("55" * 32) | .senderHex = ("33" * 32) | .senderSeq = 1)' \
approve-1.json > approve-2.json
./yano.sh appchain bindings dry-run approval.yml --plugins-directory plugins \
--context approval-context.json --fixture propose.json > proposed.json
./yano.sh appchain bindings dry-run approval.yml --plugins-directory plugins \
--context approval-context.json --fixture approve-1.json \
--prior-result proposed.json > voted.json
./yano.sh appchain bindings dry-run approval.yml --plugins-directory plugins \
--context approval-context.json --fixture approve-2.json \
--prior-result voted.json > approved.json
jq '[.receipts[].receiptHex], .stateChanges' approved.json

The first two blocks retain a pending proposal and have one source step each. The third has the source step plus the derived audit append. Its complete postState retains all three receipts and the approved item with two distinct voters. These are new commands acting on carried state, not replay of one message. The zero predecessor roots remain explicit, unverified rehearsal assumptions.

To advance one idle height while retaining the state:

Terminal window
jq '.height = 4 | .timestamp = 400 | .messages = []' approve-2.json > idle.json
./yano.sh appchain bindings dry-run approval.yml --plugins-directory plugins \
--context approval-context.json --fixture idle.json \
--prior-result approved.json > idle-result.json

The idle block has no receipts; it still runs the full block lifecycle. Height 5 cannot directly follow approved.json at height 3, even with an empty message list.

A binding document is deployed as one chain of an application. The coordinator names it when creating the setup draft, and the file is copied beside the draft as <chain>.bindings.yaml:

Terminal window
./yano.sh appchain new workflow --network devnet --operators alice,bob,carol \
--chain flow=bindings:bindings.yaml

Equivalently, write the chain into the draft by hand, with either a file reference or the document body inline:

chains:
- id: flow
recipe: declarative-composite
bindings: ./bindings.yaml # or put the body under `composite:`

A relative bindings: path resolves against the draft’s directory. The draft is ordinary YAML, so you can keep editing the referenced document until the application is sealed. seal reads it, compiles it against the dependency-complete bundles in the distribution’s plugins/ directory, and copies it into the sealed <app>.chain file. That file is self-contained: later edits to the original document do not change the sealed chain. The sealed genesis also records the SHA-256 digest of every plugin bundle the chain runs on, and join and start refuse a node whose bundles differ. Every member node therefore needs the same bundles installed.

Run the commands on this page against the same plugins/ directory before you seal, so a seal failure is not the first sign of a problem. The rest of the ceremony (member cards, seal, join, start) is described in set up an application. ./yano.sh appchain try --chain flow=bindings:<file> rehearses that ceremony on one machine for a binding document. Chapter 4 runs the same steps by hand, with three operator directories: deploy the workflow on a local devnet.

The offline commands validate a fixed genesis composite profile. They do not rehearse composite-profile governance activation or accept arbitrary machines.* context overrides. Role and authenticated-map membership context may still use the ordinary governed membership settings where their profiles require it.