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.
1. Prepare the tools
Section titled “1. Prepare the tools”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.
2. Define the components and connection
Section titled “2. Define the components and connection”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.
3. Declare the rehearsal context
Section titled “3. Declare the rehearsal context”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 }}4. Validate, compile and inspect
Section titled “4. Validate, compile and inspect”./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.dotAll 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.
5. Submit an offline test command
Section titled “5. Submit an offline test command”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.
./yano.sh appchain bindings dry-run bindings.yaml \ --plugins-directory plugins --context context.json \ --fixture fixture.json > result.jsonThe CLI preserves the receipt’s versioned positional-array encoding in its decoded JSON. For a compact view of this v1 receipt:
jq '.receipts[] | {outcome: .receipt[3], components: [.receipt[6][] | .[3]]}' result.jsonExpect 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.
Read the receipt
Section titled “Read the receipt”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.
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 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).
Select a position to see what it records.
- 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
nullwhen the cascade was accepted. - code
- Empty when accepted. Otherwise a stable rejection code such as
MAPPING_MISSING_FIELDorADMISSION_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
0for the source command. Derived steps count from1, 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
nullfor 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.v1and the baselinecomposite.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_PLANNEDorREJECTED. In an accepted receipt,PLANNEDsteps committed. In a rejected receipt they did not.- code
- The step’s failure code. Empty for a step that did not fail.
- rawBody
truewhen arawBodymapping forwarded opaque command bytes instead of mapped fields.
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.
6. See a condition skip
Section titled “6. See a condition skip”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.
7. View the graph in Studio
Section titled “7. View the graph in Studio”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:
jq '.manifest' validated.json > manifest.jsonThen 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).
From rehearsal to a deployment
Section titled “From rehearsal to a deployment”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.