State machines

A state machine holds the rules of an app ledger. Every member applies the same machine to the same finalized messages, so every member reaches the same state and the same state root. A chain selects exactly one machine id with state-machine.

Two ideas apply to every machine on these pages:

Final does not mean changed. A message can be final and still have no effect, because it broke a rule against the state it actually ran on. Read the resulting state, or its proof, before you treat a command as applied.
Admission is only a first filter. The member that receives a message checks its shape before answering 202. The authoritative decision happens when the block is applied.

Choose a machine

Which state machine?Decision aid

What you're seeing: two or three questions about what the ledger must keep and who decides. Each answer names a machine, its maturity and recipe, where it keeps state, and what its proofs can and cannot show.

What must the ledger keep for you?

Only the order of events; my applications read the payloads
ordered-log
The built-in machine. It records where each message was finalized and never rejects one for business reasons.
Maturity
stable
Recipe
audit-log
State key
sha256("~yano/finalized-message/v1/" ‖ message id)
Proof subject
finalized-message-v1, claim recorded
Proves
the height, index, topic and sender of a finalized message
Cannot prove
anything about what the payload means
ordered-log →
Current records that writers can change
Who may change a record?
- The member that wrote it first; that is enough
  kv-registry
  The first member to write a key owns it until the key is deleted.
  Maturity
  stable
  Recipe
  owned-registry
  State key
  the key bytes; value [owner, value]
  Proof subject
  registry-entry-v1, claims owner-equals, value-digest-equals
  Proves
  the current owner and value, or that the key is absent
  Cannot prove
  earlier values, or any transfer of ownership
  kv-registry reference →
- It depends on the collection: open, owner, member, a role or an approval; with revisions, tombstones and atomic batches
  authenticated-map
  Named collections, each with its own authorization, bounds, encoding and optional validator, all fixed at genesis.
  Maturity
  preview
  Recipe
  authenticated-map
  State key
  collection and key, inside the composite state
  Proof subject
  authenticated-map-entry-v1, claims status, revision-exact, value-digest
  Proves
  ACTIVE, REVOKED or ABSENT, the revision, and the value digest
  Cannot prove
  rules that relate two entries; it has no secondary indexes
  authenticated-map reference →
Quantities that move between accounts
balances
A configured minter mints. A member spends only from its own account. Balances never go negative.
Maturity
stable
Recipe
none; configure state-machine: balances
State key
b/<account>
Proof subject
account-balance-v1, claims exact, minimum, maximum
Proves
the balance of one account
Cannot prove
total supply, or anything about Cardano assets
balances reference →
An ordered history of document hashes per product or case
doc-trail
Each append chains an entry hash and its author into a per-entity head. Documents stay off the ledger.
Maturity
stable
Recipe
document-trail
State key
e/<entityId>
Proof subject
document-head-v1, claims revision-exact, revision-minimum, digest-equals
Proves
the entry count and the chained head hash
Cannot prove
that a referenced document is still available
doc-trail reference →
A decision that several approvers make
Who approves?
A member is a node that votes on blocks. A business actor is a person, service or device with its own key.
- The member nodes themselves
  approvals
  A proposal becomes APPROVED when enough distinct members approve it. One member rejection ends it.
  Maturity
  stable
  Recipe
  approval-workflow
  State key
  i/<itemId>
  Proof subject
  basic-approval-outcome-v1, claims status, quorum-reached, payload-digest
  Proves
  the status, approval count and payload hash of one item
  Cannot prove
  which person stands behind a member key
  approvals reference →
- Business actors with roles and organizations, separate from the members
  role-approvals
  Actors sign statements over a payload hash; a governed policy decides. Any member can relay them.
  Maturity
  preview
  Recipe
  role-approval
  State key
  proposal record in the role-approvals component
  Proof subject
  role-approval-outcome-v1, claims status, payload-digest
  Proves
  the policy outcome for one payload hash
  Cannot prove
  what the payload says; the machine stores and runs no payload
  role-approvals reference →

Stock state machines

Machine	Maturity	Use it for	State key	Proof subject
`ordered-log`	stable	One agreed order of opaque events	hash of the message id	`finalized-message-v1`
`kv-registry`	stable	Mutable records owned by their first writer	the key bytes	`registry-entry-v1`
`authenticated-map`	preview	Several collections with their own authorization and validation	collection and key	`authenticated-map-entry-v1`
`approvals`	stable	Decisions taken by member nodes	`i/<itemId>`	`basic-approval-outcome-v1`
`role-approvals`	preview	Decisions signed by business actors under a policy	proposal record	`role-approval-outcome-v1`
`balances`	stable	Member-owned units with a minter	`b/<account>`	`account-balance-v1`
`doc-trail`	stable	A chained history of document hashes per entity	`e/<entityId>`	`document-head-v1`

ordered-log is built into Yano. The others ship in the Yano X standard library and role-workflow bundles. Value validation for authenticated-map has its own page.

Each reference page has the same shape: At a glance, How it works with an interactive illustration, the commands to use it, and Advanced topics such as typed views and composites.

Other state machines

These machines are in the capability catalog but are not stock references here.

Machine id	Maturity	What it is	Read more
`declarative-composite`	preview	Committed, bounded event-to-command and event-to-effect workflows over stock components	Declarative bindings
`evidence-registry`	preview	Inspection and compliance evidence records with exact query proofs	Tutorial 4
`composite`	preview	Stock evidence workflow; select it with `machines.composite.preset` set to `evidence-v1` or `evidence-v1-gated`	Tutorial 4
`role-evidence`	preview	Evidence registration with governed actors and role-aware release approval	Tutorial 5
`eutxo-ledger`	experimental	A Cardano-shaped EUTxO engine; you select it through a ledger profile, not directly	EUTxO ledger

Before you configure one

Every chain carries three state-identity settings, and the host refuses to start a chain unless all three are present:

Setting	Meaning
`state.commitment-profile`	How state is committed, for example `mpf-blake2b256-v1`
`state.format-fingerprint`	The fingerprint of that profile’s format; it must match the profile
`state.genesis-id`	32 bytes, as 64 lowercase hex characters, naming this chain generation

In a generated project, appchain render writes all three; do not edit them by hand. The stock cluster file, $YANO_HOME/config/application-appchain.yml, already contains them for its chains. When you add a chain to that file yourself, copy the profile and fingerprint from an existing chain and give the new chain a fresh genesis id, for example from openssl rand -hex 32. The configuration examples on these pages show the three settings in that form.

Selecting a machine is a consensus decision. Every member must use the same machine id and the same consensus-affecting settings. Changing either on an existing chain needs a governed profile activation or a new chain.

Go deeper

Choose a stock state machine, the hands-on companion to this page.
Consensus guide in Yano: how blocks are ordered, re-executed and certified.
Plugins and composites, for rules the stock machines do not cover.