3. Approval workflows
Previous: Conditions and mappings · Learning path · Next: Java integration
An approval workflow pauses in persisted state while people decide. Proposing an item does not wait inside a running cascade for votes. The proposal commits, each vote arrives as a later message, and the threshold-reaching vote triggers the next action. Only that final vote and its derived actions share one atomic cascade.
Declarative bindings remain experimental. This page first rehearses the small
consensus-member approvals machine offline, then explains the separate
actor-signed DPP/feed path. The public fixture identities below are rehearsal
data, not credentials or an authorization scheme for a live application.
Rehearse a proposal and two approvals
Section titled “Rehearse a proposal and two approvals”You need a matching extracted Yano X JVM distribution, its plugins directory,
Java 25, and jq. Run the documented commands from that distribution directory,
using new files for this exercise. They execute offline; they do not start a
node or submit messages. This is the exact worked scenario from the
canonical CLI guide,
whose YAML and fixtures are exercised by the packaged distribution acceptance
test.
Save 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}The reviews component receives ordinary proposal and vote commands at
reviews.command.v1. Only its approved event appends to audit. No baseline
event is needed, and there is no external effect to configure.
Save the complete offline context as approval-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", "3333333333333333333333333333333333333333333333333333333333333333" ], "threshold": 2 }}The context’s membership threshold describes consensus membership. The proposal command separately asks for two business approvals. Both are 2 in this exercise, but they represent different decisions. Do not substitute this zero genesis ID or these public identities into a retained deployment.
Save propose.json:
{ "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" }]}The body is the public codec output of
ApprovalsContract.propose("a", new byte[]{1}, 2, 0): item a, payload 01,
two approvals required, and no business deadline. The envelope expiry is a
different field. The synthetic authProofHex is allowed only because dry-run
assumes envelope authentication has already happened.
Create two distinct vote fixtures. The first voter is also the proposer;
proposing does not itself cast that voter’s approval. The second vote comes
from the other member. 82016161 is ApprovalsContract.approve("a").
jq '.height = 2 | .timestamp = 200 | .messages[0] |= (.messageIdHex = ("44" * 32) | .senderSeq = 2 | .bodyHex = "82016161")' \ propose.json > approve-1.jsonjq '.height = 3 | .timestamp = 300 | .messages[0] |= (.messageIdHex = ("55" * 32) | .senderHex = ("33" * 32) | .senderSeq = 1)' \ approve-1.json > approve-2.jsonValidate, then execute each block while carrying the previous result:
./yano.sh appchain bindings validate approval.yml --plugins-directory plugins \ --context approval-context.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.jsonjq '[.receipts[].receiptHex], .stateChanges' approved.jsonExpect this progression:
| Block | New source message | Result | Receipt steps |
|---|---|---|---|
| 1 | Propose a | Pending, no approvals | Source only |
| 2 | First member approves | Pending, one approval | Source only |
| 3 | Second member approves | Approved, audit appended | Source plus derived append |
The third result’s complete postState retains the approved item, two distinct
voters, the audit state, and all three receipts. The result’s receipts list
describes the current block’s messages; it is not the complete receipt history.
These are fresh commands acting on carried state, not three replays of one ID.
An idle block still has a lifecycle. Advance exactly one height:
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.jsonThere are no source receipts in this idle result. A jump directly from height
3 to height 5 is rejected. With --prior-result, keep the new fixture’s
state: []; the CLI carries the full previous postState, not just its last
change set. Context and executable identity must match. For larger rehearsals,
see compact continuation.
Dry-run neither verifies signatures nor authenticates the predecessor root. The explicit zero roots above are assumptions, and no post-state root is computed. Results are not backups, proofs, finality certificates, or an import format for a running chain.
Understand the atomic boundary
Section titled “Understand the atomic boundary”Each message in the rehearsal is its own cascade in its own block. Step through them, then try the “What if” scenarios.
What you're seeing: two consensus members approve item a, then a binding appends an audit entry. Each message is its own cascade in its own block. Try the “What if” scenarios to see what one cascade can and cannot roll back.
- Propose Height 1. Member A submits
propose("a", 01, 2, 0)toreviews.command.v1: itema, two approvals required, no deadline. The cascade has one step. It emitsapprovals.item-proposed.v1, and no binding subscribes to that event. Proposing is not a vote.State after this block Item Status Approvals Audit entries for aaPENDING 0 of 2 0 - First vote Height 2. Member A approves
a. The vote commits in its own cascade. Below the threshold the machine emits noitem-approvedevent, so nothing is derived. Nothing waits in memory between blocks: the workflow’s progress is the item’s state.State after this block Item Status Approvals Audit entries for aaPENDING 1 of 2 0 - Second vote Height 3. Member B approves. Its vote reaches the threshold, so the machine emits
approvals.item-approved.v1. Therecord-approvedbinding has no conditions; it maps the item id and payload hash into anappendforaudit, in the same cascade. - Commit together The vote and the append commit together. The receipt for Member B’s message is ACCEPTED with two steps. Only this last vote and its follow-up share one atomic cascade, not the whole conversation.
State after this block Item Status Approvals Audit entries for aaAPPROVED 2 of 2 1
What if: The append is rejected
Suppose the derived append fails, for example because a rule attached to audit refuses it.
- Propose Height 1. Member A submits
propose("a", 01, 2, 0)toreviews.command.v1: itema, two approvals required, no deadline. The cascade has one step. It emitsapprovals.item-proposed.v1, and no binding subscribes to that event. Proposing is not a vote.State after this block Item Status Approvals Audit entries for aaPENDING 0 of 2 0 - First vote Height 2. Member A approves
a. The vote commits in its own cascade. Below the threshold the machine emits noitem-approvedevent, so nothing is derived. Nothing waits in memory between blocks: the workflow’s progress is the item’s state.State after this block Item Status Approvals Audit entries for aaPENDING 1 of 2 0 - Second vote Height 3. Member B approves. Its vote reaches the threshold, so the machine emits
approvals.item-approved.v1. Therecord-approvedbinding has no conditions; it maps the item id and payload hash into anappendforaudit, in the same cascade. - Roll back the vote The append is the failed step, ordinal 1, so the whole cascade rejects. Member B’s vote is rolled back with it. The proposal and Member A’s vote were committed in earlier blocks and stay. The receipt for Member B’s message is REJECTED.
State after this block Item Status Approvals Audit entries for aaPENDING 1 of 2 0 - Vote again The rejected receipt stays under that message id; replaying the same id returns it. Correct the cause, then Member B submits a new vote, which is a new message with a new id.
What if: Member A votes twice
Two votes from one member are one approval.
- Propose Height 1. Member A submits
propose("a", 01, 2, 0)toreviews.command.v1: itema, two approvals required, no deadline. The cascade has one step. It emitsapprovals.item-proposed.v1, and no binding subscribes to that event. Proposing is not a vote.State after this block Item Status Approvals Audit entries for aaPENDING 0 of 2 0 - First vote Height 2. Member A approves
a. The vote commits in its own cascade. Below the threshold the machine emits noitem-approvedevent, so nothing is derived. Nothing waits in memory between blocks: the workflow’s progress is the item’s state.State after this block Item Status Approvals Audit entries for aaPENDING 1 of 2 0 - A repeated vote Height 3. Member A approves again. The machine counts distinct members, so the vote changes nothing: an empty plan, no event, nothing derived. The receipt is still ACCEPTED, because accepted means the cascade committed, not that state changed. Read the item, not just the receipt.
State after this block Item Status Approvals Audit entries for aaPENDING 1 of 2 0
- consensus member
- component
- committed
- rolled back
If the third block’s derived append rejects, that source cascade rolls back both the threshold-reaching vote and the append. Earlier committed messages remain: the proposal and first vote are still pending state. The rejection receipt survives, and work already attempted remains charged. A repeated vote from the same member is accepted but changes nothing, because the machine counts distinct members: check the item, not only the receipt.
This gives the application a useful guarantee: approval and its automatic follow-up cannot partially commit within that cascade. It does not make the entire human conversation one transaction. An approved event is also not an external HTTP call. For external delivery, use an explicit effect binding and the effect/outbox model; delivery is a separate boundary, not an exactly-once promise. Do not combine a composable approval leaf with its legacy on-approved effect activation path.
For a larger example, the procurement recipe starts with an order put, checks supplier registration, derives a proposal, then waits for ordinary vote messages before auditing and planning an outbox intent. The attestation recipe extracts a document hash from the approved payload. A derived trail append is not a separately signed finalized message, so it cannot be passed off as an ADR-047 signed-message attestation certificate. Prove its receipt and trail state instead.
Governed DPP and feed examples
Section titled “Governed DPP and feed examples”Consensus-member voting is useful for the small exercise. Business actors in
different organizations need the actor-signed policy path, which does not
replace authorization with a boolean binding condition. The distribution ships
two examples of it over real authenticated-map schemas and policies:
examples/bindings/dpp-approval.yaml, a product passport certification, and
examples/bindings/feed-approval.yaml, a data feed round approval. Their genesis
uses deterministic demo identities: never use their keys in production.
Validate the DPP example with the governed context shipped beside its role-gated variant, which uses the same demo genesis:
./yano.sh appchain bindings validate examples/bindings/dpp-approval.yaml \ --plugins-directory plugins \ --context examples/bindings/fixtures/dpp-role-gated/context.jsonThe DPP roles are manufacturer, operator, claim-issuer, certifier, and
auditor, with dpp-admin administration; certification needs two auditors
from two different organizations. Feed uses source, feed-operator, and
publisher, with feed-admin administration. Actors need not be consensus
members. 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.
The DPP and feed starter generators moved with those products to
yano-x-products. The feed example
has no shipped context, so read it alongside the DPP one rather than validating
it.
Each example connects three catalog leaves:
domain-actors-componentsupplies genesis-fixed actor authority.governed-role-approvalsaccepts actor-signed proposals/votes and stages the proposed action throughStagedActorCommandV1.authenticated-map-componentverifies and applies the approved action.
The binding is small because the target owns the hard checks:
- id: apply-approved from: {component: reviews, event: role-approvals.proposal-approved.v1} to: component: registry command: apply-action map: action: {field: action} approvalReference: {field: proposalId}The genesis configuration in each example is fixed. A proposal stages at most 32,768 action bytes.
At approval, the map recomputes the signed scoped action hash and verifies the
approval reference. A mismatched action rolls back the threshold vote and map
write together, preserves the pending proposal/action, and retains the crypto
work charge. Selecting apply-basic-action does not bypass a collection’s
authorization policy.
Restrict who may approve or write
Section titled “Restrict who may approve or write”The approval policy decides who can approve. A deployment can narrow that further
with admission rules that read the facts the kernels have
already verified. examples/bindings/dpp-role-gated.yaml adds two rules to the
DPP recipe above: allowed-organization refuses approvals from actors outside
cert-body-a after the approval kernel verified the signature, and
operator-for-direct-writes refuses direct actor-signed map writes by actors
without the operator role. Approval-referenced writes through apply-approved
carry no direct actor, so the approval policy alone governs them. A forged
approval never reaches a rule: the kernel rejects it with its own code.
BindingRecipesIT runs this recipe on three nodes, and its fixtures with a
governed context are in examples/bindings/fixtures/dpp-role-gated/.
Know what the recipes do not supply
Section titled “Know what the recipes do not supply”The initial actor leaf is genesis-fixed: it has no actor rotation or derived governance-command route. It is not feature-equivalent to every standalone governed preset. List projections that replay original map envelopes do not automatically discover derived map writes; exact known-key proofs are the qualified read path. Feed aggregation stays off chain and independently recomputable, not an on-chain price oracle or Cardano publication.
Continue with the domain-role tutorial for the role commands and policies. Before evolving the configuration, read operations and upgrades: a new generation does not migrate genesis-bound state.
Source coverage for this exercise is
AppChainFinalDistributionAcceptanceTest.packagedProposalAndTwoVotesCarryStateAndRejectSkippedEmptyHeights.
BindingRecipesIT covers the checked-in recipes through live/offline receipt
parity; BindingCliIT covers catalog validation. These are existing verification
sources, not newly run tests.