Declarative bindings: developer learning path
Connect existing state machines without writing a Java coordinator. A binding says: when this component emits this event, check these conditions and build that command. The node executes a bounded, committed program identically on every member.
For example, a registry update can append an audit entry. A later human vote can complete an approval and update a record in the same atomic cascade. Your application still owns its UI, command submission, business identities and keys.
This feature is experimental. Admission rules and typed views (chapters 7 and 8)
need a Yano host with plugin API level 12 and the ADR-031.3 and ADR-031.4 host
contract. Yano 0.1.0-pre18 is the first release with that contract. Level 12
alone does not identify the right host, because the typed-view API was added to
level 12 without a new level, so run the Yano host that ships inside the Yano X
distribution. The upstream host alone does not install the optional X machines,
compiler or Studio, and an older Yano X archive may not include these features.
Choose your starting point
Section titled “Choose your starting point”| Level | Chapter | What you will do |
|---|---|---|
| Beginner | 1. Your first workflow | Put a registry value and automatically append an audit entry; validate and rehearse without running a node |
| Intermediate | 2. Conditions and mappings | Filter events, convert types, use expressions and read participant state |
| Intermediate | 3. Approval workflows | Propose, approve twice, and carry state across blocks |
| Application developer | 4. Java integration | Submit normal commands with the Java APIs and inspect the workflow outcome |
| Advanced | 5. Operations and upgrades | Diagnose rejections, discover proof keys, size budgets and plan safe evolution |
| Any level | 6. Author bindings in the Studio editor | Build the same documents with catalog-guided forms, hand them to the CLI and read its reports |
| Intermediate | 7. Admission rules | Attach forbid-only rules to components: limits, arrival checks and verified roles, with refusals as provable receipts |
| Advanced | 8. Typed views | Let rules read other components’ state and judge every write of a batch |
Start with chapter 1; it needs Java 25 and an extracted matching JVM distribution, but no Cardano funds, node cluster or private keys. Familiarity with YAML is enough. For the surrounding app ledger concepts, see the app ledger learning tracks.
Five concepts to keep separate
Section titled “Five concepts to keep separate”| Concept | Meaning in an application |
|---|---|
| Component | A named machine instance with its own state, configuration and ingress topic |
| Command | A request to that machine, encoded using its existing contract |
| Event | A typed result emitted by a successful transition, used to select bindings |
| Binding | Source event + optional conditions + target command or effect mapping |
| Receipt | The recorded outcome of one submitted source message and its derived cascade |
For a registry-to-audit binding the sequence is:
client put command → registry transition → entry-put event → derived audit append
The client submits only the put. The node derives the append. Both business changes commit together or neither does; a finalized rejection still retains its receipt. This atomic boundary is one source message, not a whole human workflow spanning several votes or an external HTTP call.
How a cascade runs
Section titled “How a cascade runs”One source message and everything its bindings derive form one cascade. Step through the registry-to-audit workflow from chapter 1, then try the “What if” scenarios: a false condition skips a binding, but an error rejects the whole cascade.
What you're seeing: the registry-to-audit workflow from chapter 1. One put derives one audit append. Step through the accepted run, then try a “What if”: a false condition skips a binding, but an error rejects everything.
- Submit Your application sends one registry
putto therecordscomponent’s topic,records.command.v1. This is the source message. Bindings decide what else happens; the application submits nothing more. - Ingress checks The member that receives the message runs the composite’s ingress checks in this order, then answers 202. A failed check is an HTTP 400 and nothing is pooled. 202 means queued, not success: the cascade has not run yet.
- passes: The topic routes to a component
UNKNOWN_BINDING_SOURCE - passes: Its mandatory work fits, and so does a subscribed baseline event (
COMMAND_PAYLOAD_TOO_LARGE)COMMAND_WORK_EXCEEDED - passes: The body decodes with the component’s codec
MALFORMED_SOURCE_COMMAND - passes: The kernel’s stateless admission accepts it
- passes: Static admission rules hold (none are attached here)
ADMISSION_RULE_DENIED
- passes: The topic routes to a component
- Replay check A leader puts the message in a block, and every member runs the same cascade when it executes that block. First, the engine looks for a receipt already stored under this source message id. If one exists, nothing runs again and the stored receipt stands.
- Decide step 0 The engine decodes the put, runs the kernel’s admission hooks and any admission-slot rules, reserves any work the kernel requests, and asks the kernel to decide. The approved plan goes into the cascade’s overlay, where later steps can read it. Nothing is committed yet.
- Match bindings The plan emits
kv-registry.entry-put.v1. The engine evaluates the bindings that subscribe to that event, in YAML order.audit-recordchecksevent.valueLength < 100: the value is 2 bytes, so every clause holds and the receipt recordsfailedClause -1.- passes:
event.valueLength < 100(2 < 100)
- passes:
- Derive a command The mapping builds an
appendforaudit: entity idhex(key)= text0102, the value hash, and the referencepublished. Its id is derived from the source id, the binding id and ordinal 1. The command joins the back of the queue at depth 1: the cascade runs breadth first. - Decide step 1 The
auditcomponent decodes, admits and decides the derived append the same way it would a submitted one. It emitsdoc-trail.entry-appended.v1. No binding subscribes to that event, so the queue is now empty. - Preflight and claim Before anything commits, the engine checks the planned effects against the block’s effect capacity (there are none here), claims the source message id, and confirms the receipt fits its 65,536-byte cap.
- passes: Effect intents fit the remaining capacity
EFFECT_CAPACITY_EXCEEDED - passes: The source id is claimed once
REPLAY_OR_CONFLICT - passes: The receipt encodes within its cap
RECEIPT_CAPACITY_EXCEEDED
- passes: Effect intents fit the remaining capacity
- Commit all Every planned write commits together, and the receipt is stored under the source id with status ACCEPTED. Both steps still read
PLANNED: in an accepted receipt that means committed.
What if: Condition false
A value of 100 bytes or more. The binding is skipped, and the put still commits.
- Submit Your application sends one registry
putto therecordscomponent’s topic,records.command.v1. This is the source message. Bindings decide what else happens; the application submits nothing more. - Ingress checks The member that receives the message runs the composite’s ingress checks in this order, then answers 202. A failed check is an HTTP 400 and nothing is pooled. 202 means queued, not success: the cascade has not run yet.
- passes: The topic routes to a component
UNKNOWN_BINDING_SOURCE - passes: Its mandatory work fits, and so does a subscribed baseline event (
COMMAND_PAYLOAD_TOO_LARGE)COMMAND_WORK_EXCEEDED - passes: The body decodes with the component’s codec
MALFORMED_SOURCE_COMMAND - passes: The kernel’s stateless admission accepts it
- passes: Static admission rules hold (none are attached here)
ADMISSION_RULE_DENIED
- passes: The topic routes to a component
- Replay check A leader puts the message in a block, and every member runs the same cascade when it executes that block. First, the engine looks for a receipt already stored under this source message id. If one exists, nothing runs again and the stored receipt stands.
- Decide step 0 The engine decodes the put, runs the kernel’s admission hooks and any admission-slot rules, reserves any work the kernel requests, and asks the kernel to decide. The approved plan goes into the cascade’s overlay, where later steps can read it. Nothing is committed yet.
- Skip the binding The condition is false at clause 0, so
audit-recordderives nothing. A false condition is not an error: the receipt recordsfailedClause 0and the cascade goes on.- fails:
event.valueLength < 100
- fails:
- Commit the source The queue is empty. The put commits alone, and the receipt is ACCEPTED with one step. To refuse a command rather than skip a follow-up, use an admission rule.
What if: Mapping fails
The mapping copies previousValueHash, which a first insertion does not have.
- Submit Your application sends one registry
putto therecordscomponent’s topic,records.command.v1. This is the source message. Bindings decide what else happens; the application submits nothing more. - Ingress checks The member that receives the message runs the composite’s ingress checks in this order, then answers 202. A failed check is an HTTP 400 and nothing is pooled. 202 means queued, not success: the cascade has not run yet.
- passes: The topic routes to a component
UNKNOWN_BINDING_SOURCE - passes: Its mandatory work fits, and so does a subscribed baseline event (
COMMAND_PAYLOAD_TOO_LARGE)COMMAND_WORK_EXCEEDED - passes: The body decodes with the component’s codec
MALFORMED_SOURCE_COMMAND - passes: The kernel’s stateless admission accepts it
- passes: Static admission rules hold (none are attached here)
ADMISSION_RULE_DENIED
- passes: The topic routes to a component
- Replay check A leader puts the message in a block, and every member runs the same cascade when it executes that block. First, the engine looks for a receipt already stored under this source message id. If one exists, nothing runs again and the stored receipt stands.
- Decide step 0 The engine decodes the put, runs the kernel’s admission hooks and any admission-slot rules, reserves any work the kernel requests, and asks the kernel to decide. The approved plan goes into the cascade’s overlay, where later steps can read it. Nothing is committed yet.
- Match bindings The plan emits
kv-registry.entry-put.v1. The engine evaluates the bindings that subscribe to that event, in YAML order.audit-recordchecksevent.valueLength < 100: the value is 2 bytes, so every clause holds and the receipt recordsfailedClause -1.- passes:
event.valueLength < 100(2 < 100)
- passes:
- Mapping error Building the append fails: the event has no
previousValueHash. An evaluation error is not a false condition. It rejects the whole cascade withMAPPING_MISSING_FIELDat step 1.- fails: Map
entryHashfrompreviousValueHashMAPPING_MISSING_FIELD
- fails: Map
- Roll back No business state is written: not the append, and not the put that started it. Only the receipt is stored, REJECTED with failed step 1, and the work it used stays charged. Step 0 reads
PLANNED, which in a rejected receipt means not committed.
What if: Body does not decode
A malformed body never reaches a block.
- Submit Your application sends bytes to
records.command.v1that are not a registry command. - Refused at ingress The registry codec cannot decode the body, so the member answers 400 with
MALFORMED_SOURCE_COMMAND. The message is not pooled or gossiped, and no receipt exists. Fix the encoding and submit again.- passes: The topic routes to a component
UNKNOWN_BINDING_SOURCE - passes: Its mandatory work fits, and so does a subscribed baseline event (
COMMAND_PAYLOAD_TOO_LARGE)COMMAND_WORK_EXCEEDED - fails: The body decodes with the component’s codec
MALFORMED_SOURCE_COMMAND - not reached: The kernel’s stateless admission accepts it
- not reached: Static admission rules hold (none are attached here)
ADMISSION_RULE_DENIED
- passes: The topic routes to a component
- your application
- member node
- cascade engine
- component
- committed
- refused or rolled back
Operations and upgrades helps when a command did not do what you expected.
Do I need a separate bindings.yml?
Section titled “Do I need a separate bindings.yml?”No particular filename is required. There are two authoring arrangements:
- Separate document: keep
chain/bindings.yaml(or any chosen filename) in source control. Use it withappchain bindingscommands, and deploy it withappchain new <app> --chain <id>=bindings:chain/bindings.yaml, which copies it beside the setup draft as<id>.bindings.yamland references it withbindings:. You can also writebindings: ./chain/bindings.yamlunder a chain in the draft yourself. - Inline in the draft: select the
declarative-compositerecipe and put the document body under that chain’scomposite:key in<app>.draft.yaml.
The standalone CLI document may contain the composite body directly or wrap it
in one composite: property. Do not pass a whole setup draft to
appchain bindings compile; that command expects the composite document.
appchain seal reads the referenced document, compiles it against the plugin
bundles in the distribution’s plugins/ directory, and copies it into the
sealed <app>.chain file. It is not a live include: editing the original
file after seal does not change the sealed chain. The sealed genesis also pins
the digest of every plugin bundle the chain runs on.
Nodes execute that committed definition, not a YAML file watched for changes. Editing YAML or replacing a JAR does not update a running chain. See deploying a document and upgrade planning.
Can I define bindings graphically?
Section titled “Can I define bindings graphically?”Yes, with guided forms. Studio’s Bindings page edits the same composite document you would write in YAML: components, bindings, conditions, typed mappings and limits, with a synchronized YAML view and dependency graph. An authoring catalog exported from your plugin bundles supplies the events, commands and fields. See chapter 6.
The editor is not a separate workflow language or a drag-to-connect designer. The YAML document and its compiled IR stay authoritative, graph positions are presentation only, and Studio never compiles, runs or deploys anything: you hand the document to the version-matched CLI and import its reports to see diagnostics and rehearsal outcomes. Imported reports are unauthenticated files.
Studio also keeps its read-only graph viewer for a capability-manifest
snapshot, such as the one chapter 1 extracts from validate output. The CLI’s graph command
exports Graphviz DOT. Neither graph authenticates chain identity or authorizes an
upgrade.
When to use Java instead
Section titled “When to use Java instead”Use bindings when existing catalog machines expose the commands and events you need. Use a Java plugin for new state transitions or rules outside the bounded language. Expressions cannot call arbitrary Java, query the network or create authority. A condition is not a signature, and a derived command still passes the target’s authorization checks.
Reference material remains available for lookup:
- Language, event execution, limits and rejection codes
- CLI documents, context, fixtures and deployment
- Retained-chain compatibility and profile preflight
Next: Your first workflow.