Skip to content

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.

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").

Terminal window
jq '.height = 2 | .timestamp = 200 | .messages[0] |=
(.messageIdHex = ("44" * 32) | .senderSeq = 2 | .bodyHex = "82016161")' \
propose.json > approve-1.json
jq '.height = 3 | .timestamp = 300 | .messages[0] |=
(.messageIdHex = ("55" * 32) | .senderHex = ("33" * 32) | .senderSeq = 1)' \
approve-1.json > approve-2.json

Validate, then execute each block while carrying the previous result:

Terminal window
./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.json
jq '[.receipts[].receiptHex], .stateChanges' approved.json

Expect this progression:

BlockNew source messageResultReceipt steps
1Propose aPending, no approvalsSource only
2First member approvesPending, one approvalSource only
3Second member approvesApproved, audit appendedSource 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:

Terminal window
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.json

There 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.

Each message in the rehearsal is its own cascade in its own block. Step through them, then try the “What if” scenarios.

An approval across blocksIllustrative data

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.

  1. Propose Height 1. Member A submits propose("a", 01, 2, 0) to reviews.command.v1: item a, two approvals required, no deadline. The cascade has one step. It emits approvals.item-proposed.v1, and no binding subscribes to that event. Proposing is not a vote.
    State after this block
    ItemStatusApprovalsAudit entries for a
    aPENDING0 of 20
  2. First vote Height 2. Member A approves a. The vote commits in its own cascade. Below the threshold the machine emits no item-approved event, so nothing is derived. Nothing waits in memory between blocks: the workflow’s progress is the item’s state.
    State after this block
    ItemStatusApprovalsAudit entries for a
    aPENDING1 of 20
  3. Second vote Height 3. Member B approves. Its vote reaches the threshold, so the machine emits approvals.item-approved.v1. The record-approved binding has no conditions; it maps the item id and payload hash into an append for audit, in the same cascade.
  4. 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
    ItemStatusApprovalsAudit entries for a
    aAPPROVED2 of 21

What if: The append is rejected

Suppose the derived append fails, for example because a rule attached to audit refuses it.

  1. Propose Height 1. Member A submits propose("a", 01, 2, 0) to reviews.command.v1: item a, two approvals required, no deadline. The cascade has one step. It emits approvals.item-proposed.v1, and no binding subscribes to that event. Proposing is not a vote.
    State after this block
    ItemStatusApprovalsAudit entries for a
    aPENDING0 of 20
  2. First vote Height 2. Member A approves a. The vote commits in its own cascade. Below the threshold the machine emits no item-approved event, so nothing is derived. Nothing waits in memory between blocks: the workflow’s progress is the item’s state.
    State after this block
    ItemStatusApprovalsAudit entries for a
    aPENDING1 of 20
  3. Second vote Height 3. Member B approves. Its vote reaches the threshold, so the machine emits approvals.item-approved.v1. The record-approved binding has no conditions; it maps the item id and payload hash into an append for audit, in the same cascade.
  4. 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
    ItemStatusApprovalsAudit entries for a
    aPENDING1 of 20
  5. 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.

  1. Propose Height 1. Member A submits propose("a", 01, 2, 0) to reviews.command.v1: item a, two approvals required, no deadline. The cascade has one step. It emits approvals.item-proposed.v1, and no binding subscribes to that event. Proposing is not a vote.
    State after this block
    ItemStatusApprovalsAudit entries for a
    aPENDING0 of 20
  2. First vote Height 2. Member A approves a. The vote commits in its own cascade. Below the threshold the machine emits no item-approved event, so nothing is derived. Nothing waits in memory between blocks: the workflow’s progress is the item’s state.
    State after this block
    ItemStatusApprovalsAudit entries for a
    aPENDING1 of 20
  3. 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
    ItemStatusApprovalsAudit entries for a
    aPENDING1 of 20
  • 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.

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:

Terminal window
./yano.sh appchain bindings validate examples/bindings/dpp-approval.yaml \
--plugins-directory plugins \
--context examples/bindings/fixtures/dpp-role-gated/context.json

The 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:

  1. domain-actors-component supplies genesis-fixed actor authority.
  2. governed-role-approvals accepts actor-signed proposals/votes and stages the proposed action through StagedActorCommandV1.
  3. authenticated-map-component verifies 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.

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/.

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.

Next: Submit commands and inspect receipts from Java