Skip to content

1. Your first declarative workflow

Build a registry that automatically records an audit entry when a value is written. You will author the workflow, check it against actual plugin bundles, and execute a synthetic command through the real composite engine offline.

This is a rehearsal, not a deployed chain. No private keys or running nodes are needed. Read the overview first if components and bindings are new.

Use Java 25 and an extracted Yano X JVM distribution containing declarative bindings. Run the commands below from its root, where yano.sh and plugins/ are present. If building from this checkout, follow the distribution build guide. Keep the launcher and plugins from the same build; upstream Yano alone is not the Yano X distribution. jq is needed only for extracting the Studio snapshot.

Create three text files in a disposable working directory. These instructions use files in the distribution root for shorter commands; absolute paths work too. Do not reuse the synthetic chain identity below for a retained deployment.

Save this as bindings.yaml:

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}

records and audit are your instance names; kv-registry and doc-trail select installed machines. The registry receives commands at the default topic records.command.v1. A successful put emits kv-registry.entry-put.v1.

The condition matches values shorter than 100 bytes. The mapping converts the binary registry key to a text entity ID, copies the value’s hash into the audit entry, and sets a text label. The field names belong to the machine contracts, not arbitrary application variables. Consult the registry and document trail references for their semantics.

Save this as context.json. This strict JSON supplies chain identity, membership and host limits; it is neither a node properties file nor a place for secrets. The zero genesis and repeated public-key bytes are synthetic offline inputs.

Show context.json
{
"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
}
}
Terminal window
./yano.sh appchain bindings validate bindings.yaml \
--plugins-directory plugins --context context.json > validated.json
./yano.sh appchain bindings compile bindings.yaml \
--plugins-directory plugins --context context.json > bindings.ir.hex
./yano.sh appchain bindings graph bindings.yaml \
--plugins-directory plugins --context context.json > bindings.dot

All three commands must exit successfully. Validation constructs the actual catalog-selected profile, catching errors such as an unknown event or mapping type mismatch. Compilation prints canonical IR hex; graphing prints DOT, not an image. Neither submits a transaction or installs a workflow into a running node.

If Graphviz is installed, render the graph with dot -Tsvg bindings.dot -o bindings.svg. Graphviz is optional and separate from Yano X. For the browser viewer, extract the capability manifest from validation as described below; a DOT file is not Studio’s import format.

Save this as fixture.json:

{
"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"
}]
}

The canonical CBOR command means “put bytes 0304 at key 0102.” The synthetic authentication byte is only valid for this rehearsal: dry-run assumes envelope authentication has already happened. Do not send this fixture as a real signed message. Java integration uses the command codecs instead of requiring application developers to hand-write CBOR.

Terminal window
./yano.sh appchain bindings dry-run bindings.yaml \
--plugins-directory plugins --context context.json \
--fixture fixture.json > result.json

The CLI preserves the receipt’s versioned positional-array encoding in its decoded JSON. For a compact view of this v1 receipt:

Terminal window
jq '.receipts[] | {outcome: .receipt[3], components: [.receipt[6][] | .[3]]}' result.json

Expect ACCEPTED and components ["records", "audit"]. Also inspect stateChanges for physical state writes. Expect an accepted source cascade with a registry step and a derived audit step. The audit entity is text 0102 and its entry is the registry value hash. The doc-trail state keeps only the entry count and the chained head hash, so the step’s reference does not appear in stateChanges. There are no external effects in this example. postState contains the complete rehearsal state, including internal markers and the receipt—not just your two business records.

Dry-run does not authenticate the input state, verify signatures or finality, compute a post-state root, or prove anything about a live chain. Success here is one useful test, not a substitute for multi-node deployment validation.

Every source message that reaches a block gets exactly one receipt, accepted or rejected. It is a positional array: .receipt[3] above is its status, and .receipt[6] its steps. Select a position to see what it records.

Anatomy of a binding receiptIllustrative data

What you're seeing: the receipt of chapter 1’s accepted cascade. bindings dry-run prints it as this positional array under .receipts[].receipt; a --report file and Studio show the same fields by name. The lower zone is one element of steps, the derived audit append.

RECEIPT · 7 POSITIONSONE STEP · 11 POSITIONSversion[0] 1sourceMessageId[1] 1111…1111height[2] 1status[3] ACCEPTEDfailedStepOrdinal[4] nullcode[5] ""steps[6] 2 stepsordinal[0] 1depth[1] 1bindingId[2] audit-recordtargetComponentId[3] auditmessageId[4] 1abf2641…eventsProduced[5] 2 event idsconditions[6] []rules[7] [0, null]status[8] PLANNEDcode[9] ""rawBody[10] falseone array per stepRECEIPT · 7 POSITIONSONE STEP · 11 POSITIONSversion[0] 1sourceMessageId[1] 1111…1111height[2] 1status[3] ACCEPTEDfailedStepOrdinal[4] nullcode[5] ""steps[6] 2 stepsordinal[0] 1depth[1] 1bindingId[2] audit-recordtargetComponentId[3] auditmessageId[4] 1abf2641…eventsProduced[5] 2 event idsconditions[6] []rules[7] [0, null]status[8] PLANNEDcode[9] ""rawBody[10] falseone array per step
  • Receipt · 7 positions: version, sourceMessageId, height, status, failedStepOrdinal, code, steps.
  • One step · 11 positions: ordinal, depth, bindingId, targetComponentId, messageId, eventsProduced, conditions, rules, status, code, rawBody.
  • steps → One step · 11 positions (one array per step).
version
Receipt layout version, always 1. ADR-031.3 and ADR-031.4 changed the step and rule-failure arrays in place, so a receipt written by an older runtime fails to decode with a “predates” error instead of being misread.
sourceMessageId
The 32-byte id of the message your application submitted. The receipt is stored under it; bindings receipt-key <id> prints the state key you need for a proof.
height
The block height of the source message.
status
ACCEPTED: every planned write and effect intent committed. REJECTED: none did, including the source command. Only the receipt and the work charge remain.
failedStepOrdinal
The ordinal of the step that failed, or null when the cascade was accepted.
code
Empty when accepted. Otherwise a stable rejection code such as MAPPING_MISSING_FIELD or ADMISSION_RULE_DENIED. The reference lists every code.
steps
One array per visited step, ordered by ordinal: the source first, then derived steps. At most 257 steps, and the encoded receipt at most 65,536 bytes.
ordinal
0 for the source command. Derived steps count from 1, in the order the bindings derived them.
depth
Distance from the source. The cascade runs breadth first, so all depth-1 steps run before any at depth 2.
bindingId
The binding that derived this step, or null for the source command.
targetComponentId
The component that ran the command, or the component that owns an effect intent.
messageId
The source id for step 0. A derived step’s id is Blake2b-256 over yano-x-derived-command-v1, the source id, the binding id and the ordinal, so every member derives the same id.
eventsProduced
Event ids in production order, here doc-trail.entry-appended.v1 and the baseline composite.command-accepted.v1. Ids only: a receipt never stores event payloads.
conditions
One [bindingId, failedClause] pair per binding the step’s events selected. -1: every clause held. 0–7: the first clause that was false or failed. Bindings that were never considered are not listed.
rules
[heldCount, failure]: how many attached admission rules held, and the first that did not, as [ruleId, failedClause, denyCode, writeIndex]. Rule inputs and read values are never recorded.
status
PLANNED, EFFECT_PLANNED or REJECTED. In an accepted receipt, PLANNED steps committed. In a rejected receipt they did not.
code
The step’s failure code. Empty for a step that did not fail.
rawBody
true when a rawBody mapping forwarded opaque command bytes instead of mapped fields.
Every source message that reaches a block gets exactly one receipt, stored under its id, whether the cascade was accepted or rejected. Read status first: it decides whether any step committed.
  • receipt envelope
  • step

Read status first. In an accepted receipt, steps marked PLANNED committed; in a rejected one, nothing did. How a cascade runs walks through how the steps get there.

Change the condition to event.valueLength < 2 and run the same fixture again as a fresh height-1 rehearsal. The two-byte value no longer matches. The registry put still succeeds, but no audit append is derived. A false condition skips a binding; it does not reject the source command. A mapping or target rejection, on the other hand, rejects the cascade and rolls back its business changes. To refuse a command itself, attach an admission rule to its component.

Restore < 100 before continuing. This edit creates a different committed program; on a real chain it would require qualified profile evolution.

Studio is the static site in the distribution’s studio/ directory. Serve it locally from the distribution’s top-level directory, for example with python3 -m http.server 8230 --bind 127.0.0.1 --directory studio, and open http://127.0.0.1:8230/. Any free port works; this tutorial uses 8230 because 8080 is often taken. This starts a local static web server, not a Yano node. See Studio configuration.

Extract the validation result’s manifest into manifest.json:

Terminal window
jq '.manifest' validated.json > manifest.json

Then open Inspect a declarative binding graph and select that file. Use the manifest object itself, not the enclosing validation result. This viewer is read-only: it shows components and edges but cannot edit bindings, conditions or mappings. An imported snapshot is not authenticated chain evidence. To author the document itself with guided forms, use Studio’s Bindings page (chapter 6).

To deploy, name the document as one chain of an application: appchain new <app> --chain <id>=bindings:bindings.yaml. The operators then send member cards, the coordinator seals, and each operator joins and starts. seal compiles the document against the distribution’s plugins/ bundles and copies it into the sealed file. Follow deploying a document and set up an application; do not deploy the dummy context or authentication bytes from this tutorial. Chapter 4 shows a complete local devnet deployment.

Next: Conditions and mappings.