Skip to content

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.

LevelChapterWhat you will do
Beginner1. Your first workflowPut a registry value and automatically append an audit entry; validate and rehearse without running a node
Intermediate2. Conditions and mappingsFilter events, convert types, use expressions and read participant state
Intermediate3. Approval workflowsPropose, approve twice, and carry state across blocks
Application developer4. Java integrationSubmit normal commands with the Java APIs and inspect the workflow outcome
Advanced5. Operations and upgradesDiagnose rejections, discover proof keys, size budgets and plan safe evolution
Any level6. Author bindings in the Studio editorBuild the same documents with catalog-guided forms, hand them to the CLI and read its reports
Intermediate7. Admission rulesAttach forbid-only rules to components: limits, arrival checks and verified roles, with refusals as provable receipts
Advanced8. Typed viewsLet 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.

ConceptMeaning in an application
ComponentA named machine instance with its own state, configuration and ingress topic
CommandA request to that machine, encoded using its existing contract
EventA typed result emitted by a successful transition, used to select bindings
BindingSource event + optional conditions + target command or effect mapping
ReceiptThe 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.

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.

How a cascade runsIllustrative data

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.

  1. Submit Your application sends one registry put to the records component’s topic, records.command.v1. This is the source message. Bindings decide what else happens; the application submits nothing more.
  2. 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
  3. 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.
  4. 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.
  5. Match bindings The plan emits kv-registry.entry-put.v1. The engine evaluates the bindings that subscribe to that event, in YAML order. audit-record checks event.valueLength < 100: the value is 2 bytes, so every clause holds and the receipt records failedClause -1.
    • passes: event.valueLength < 100 (2 < 100)
  6. Derive a command The mapping builds an append for audit: entity id hex(key) = text 0102, the value hash, and the reference published. 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.
  7. Decide step 1 The audit component decodes, admits and decides the derived append the same way it would a submitted one. It emits doc-trail.entry-appended.v1. No binding subscribes to that event, so the queue is now empty.
  8. 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
  9. 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.

  1. Submit Your application sends one registry put to the records component’s topic, records.command.v1. This is the source message. Bindings decide what else happens; the application submits nothing more.
  2. 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
  3. 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.
  4. 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.
  5. Skip the binding The condition is false at clause 0, so audit-record derives nothing. A false condition is not an error: the receipt records failedClause 0 and the cascade goes on.
    • fails: event.valueLength < 100
  6. 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.

  1. Submit Your application sends one registry put to the records component’s topic, records.command.v1. This is the source message. Bindings decide what else happens; the application submits nothing more.
  2. 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
  3. 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.
  4. 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.
  5. Match bindings The plan emits kv-registry.entry-put.v1. The engine evaluates the bindings that subscribe to that event, in YAML order. audit-record checks event.valueLength < 100: the value is 2 bytes, so every clause holds and the receipt records failedClause -1.
    • passes: event.valueLength < 100 (2 < 100)
  6. Mapping error Building the append fails: the event has no previousValueHash. An evaluation error is not a false condition. It rejects the whole cascade with MAPPING_MISSING_FIELD at step 1.
    • fails: Map entryHash from previousValueHash MAPPING_MISSING_FIELD
  7. 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.

  1. Submit Your application sends bytes to records.command.v1 that are not a registry command.
  2. 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
  • 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.

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 with appchain bindings commands, and deploy it with appchain new <app> --chain <id>=bindings:chain/bindings.yaml, which copies it beside the setup draft as <id>.bindings.yaml and references it with bindings:. You can also write bindings: ./chain/bindings.yaml under a chain in the draft yourself.
  • Inline in the draft: select the declarative-composite recipe and put the document body under that chain’s composite: 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.

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.

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:

Next: Your first workflow.