Bring external evidence into your application
A state machine cannot read the outside world: every member must compute the same result from the same inputs. Observations bring outside facts in as ordered, checked inputs instead. The network call happens outside deterministic execution, and every member applies the same accepted input.
You’ll learn: the two kinds of observation, how a certified observation round works, its outcomes and deadlines, and what the evidence does and does not prove.
Two kinds of observation
Section titled “Two kinds of observation”| L1 observers | Generic certified observations | |
|---|---|---|
| Brings in | Cardano facts: deposits to an address, transactions with a metadata label, epoch data | Facts from outside Cardano, such as a signed shipment report |
| Who checks it | Every member re-derives the fact from its own Cardano view | Members, or configured external reporters, sign matching reports; a certificate carries them |
| Arrives as | A framework message on ~l1/<observer-id> | A certified result on ~obs/result/v1 |
| Your code receives it in | context.l1Observations() during apply() | onObservationResult(...) |
| Status | Bundled, preview | Preview, disabled by default |
Both are consensus inputs: every member must use the same observer settings and the same genesis-pinned observation profile.
L1 observers
Section titled “L1 observers”Each member watches its own Cardano view. An observed fact is injected only
after it is l1.stability-depth blocks deep, and followers re-derive the claim
from their own L1 stream before they accept it, so a proposer cannot invent an
L1 fact.
yano: app-chain: l1: stability-depth: 36 # observers require stability-depth > 0 observation: l1-network-genesis-id: "<SHA-256 of the exact Shelley genesis file, 64 hex>" observers: deposits: type: address-deposit # built in: lovelace paid to one address address: "addr_test1..." papers: type: metadata-label # built in: transactions with a metadata label label: "20250712"Read them like any messages, for example
GET …/messages/by-topic/~l1%2Fdeposits. Custom block and epoch observers are
plugins; see the
user guide’s L1 observations section.
Generic certified observations (preview)
Section titled “Generic certified observations (preview)”A generic observation asks members to fetch a fact from a configured source, check its evidence, and agree on the value before the application sees it. Yano owns the protocol, verification, certification, and callbacks; your state machine only asks and reacts.
Ask during a deterministic callback, through the AppObservationEmitter
handed to the observation-aware apply(context, writer, effects, observations):
ObservationSubscriptionId id = observations.watch(ObservationIntent.oneShot( "shipment-delivery", // definition id, pinned in the observation profile "shipment-workflow-reference-v1", // route; the example uses its machine id paymentTxHash, // public parameters, opaque to the host ObservationAnchorType.APP_HEIGHT, height + 1, // first due: strictly in the future height + 3, // report deadline height + 3)); // subscription expiryReact in onObservationResult(context, result, writer, effects, observations),
which every member calls when a certified result, or an expiry, is final.
observations.cancel(id) cancels a subscription.
One round, step by step
Section titled “One round, step by step”This round comes from the shipment reference workflow, described below.
What you're seeing: the shipment reference workflow. Members A and B stand for the reporting members, and this round needs 2 matching reports. Try a missed deadline or a different value.
- Payment lands A buyer pays the order’s Cardano address. Each member’s
address-depositobserver sees it, and once it isl1.stability-depthblocks deep it is sequenced into a block. Followers re-derive it from their own Cardano view.apply()receives it incontext.l1Observations(). - Watch The state machine calls
observations.watch(ObservationIntent.oneShot("shipment-delivery", …)), with the payment transaction hash as parameters. The round is due at height h+1 and takes reports until h+3: logical heights, not seconds. The subscription commits with the block; no network call happens yet. - Open a round At height h+1 every member opens the same round. The round record pins the members, the report threshold, and the deadline. Workers start only after that record is committed.
- Fetch Outside block execution, each member’s
https-attested-merkle-v1adapter fetches the attestor’s signed Merkle root and the leaf for this payment. A timeout or network error is retried locally, and nothing about it is signed. - Check and report Each member checks the evidence with
ed25519-merkle-inclusion-v1, saves a signing lock, and gossips a signed report on~obs-diffusion/report/v1. A report is a member’s statement about the evidence, not part of any block.- passes: The root is signed by an attestor key authorized for this definition
- passes: The attestation names this definition, round, and source
- passes: The leaf binds this round’s parameters, the source id, and the value
- passes: The path has at most 20 siblings and reaches the signed root
- Certify A member holding exactly the round’s report threshold of reports, with the same value, source, and version, assembles a certificate and gossips it on
~obs-diffusion/certificate/v1. Any member can do this; here the threshold is 2. - Include The proposer adds the certified result to a block as a
~obs/result/v1input. Followers verify the certificate before they vote PREPARE; an invalid certificate for an open round rejects the block. - Apply When the block is final, every member calls
onObservationResultwith statusVALUEand valueDELIVERED. The state machine emits acardano.paymenteffect with aCHAINresult to pay the merchant, and moves toRELEASE_PENDING. - Release and settle The effect executor pays the merchant and reports the transaction hash, so the workflow waits for settlement. A second stable deposit to the merchant address, with exactly that hash, completes it. An executor receipt alone never does.
What if: No quorum by the deadline
Missing evidence is never turned into an answer.
- Payment lands A buyer pays the order’s Cardano address. Each member’s
address-depositobserver sees it, and once it isl1.stability-depthblocks deep it is sequenced into a block. Followers re-derive it from their own Cardano view.apply()receives it incontext.l1Observations(). - Watch The state machine calls
observations.watch(ObservationIntent.oneShot("shipment-delivery", …)), with the payment transaction hash as parameters. The round is due at height h+1 and takes reports until h+3: logical heights, not seconds. The subscription commits with the block; no network call happens yet. - Open a round At height h+1 every member opens the same round. The round record pins the members, the report threshold, and the deadline. Workers start only after that record is committed.
- Fetch Member A fetches valid evidence. Member B receives a path that does not reach the signed root.
- Reject before signing Member B rejects the evidence before it signs anything. It does not report “not delivered”: bad or missing evidence is never converted into a domain answer. No second valid report arrives.
- passes: The root is signed by an attestor key authorized for this definition
- passes: The attestation names this definition, round, and source
- passes: The leaf binds this round’s parameters, the source id, and the value
- fails: The path has at most 20 siblings and reaches the signed root
- Deadline passes The round stays open until its report deadline. After that and the inclusion grace, every member derives
EXPIREDfrom committed state, without a certificate. - Shipment unresolved
onObservationResultreceives statusEXPIRED. The workflow stops atSHIPMENT_UNRESOLVED, and no payment effect is emitted.
What if: The attestor reports another value
A certified value is still only what the attestor committed.
- Payment lands A buyer pays the order’s Cardano address. Each member’s
address-depositobserver sees it, and once it isl1.stability-depthblocks deep it is sequenced into a block. Followers re-derive it from their own Cardano view.apply()receives it incontext.l1Observations(). - Watch The state machine calls
observations.watch(ObservationIntent.oneShot("shipment-delivery", …)), with the payment transaction hash as parameters. The round is due at height h+1 and takes reports until h+3: logical heights, not seconds. The subscription commits with the block; no network call happens yet. - Open a round At height h+1 every member opens the same round. The round record pins the members, the report threshold, and the deadline. Workers start only after that record is committed.
- Fetch Outside block execution, each member’s
https-attested-merkle-v1adapter fetches the attestor’s signed Merkle root and the leaf for this payment. A timeout or network error is retried locally, and nothing about it is signed. - Check and report The evidence is valid, so both members report the value the attestor committed, which is not
DELIVERED.- passes: The root is signed by an attestor key authorized for this definition
- passes: The attestation names this definition, round, and source
- passes: The leaf binds this round’s parameters, the source id, and the value
- passes: The path has at most 20 siblings and reaches the signed root
- Certify A member holding exactly the round’s report threshold of reports, with the same value, source, and version, assembles a certificate and gossips it on
~obs-diffusion/certificate/v1. Any member can do this; here the threshold is 2. - Include The proposer adds the certified result to a block as a
~obs/result/v1input. Followers verify the certificate before they vote PREPARE; an invalid certificate for an open round rejects the block. - Shipment unresolved The result is
VALUE, but the value is notDELIVERED. The state machine moves toSHIPMENT_UNRESOLVEDand releases nothing.
- deterministic, on every member
- reporting member
- external source
- Cardano
- final
- rejected or unresolved
Outcomes
Section titled “Outcomes”| Status | Meaning |
|---|---|
VALUE | A certified value was finalized. Under exact-value-quorum-v1, exactly the round’s report threshold of reports agreed on it. |
EXPIRED | No valid certificate was included in time. Members derive it from committed round state, without a certificate. |
CANCELLED | The application cancelled the subscription. |
NO_RESULT | Reserved. The current protocol never produces it, and missing reports can never derive it. |
A VALUE is only as good as its source: it says what the configured source
committed, not that it is true.
Deadlines are heights, not seconds
Section titled “Deadlines are heights, not seconds”Due and deadline values are logical anchors. With APP_HEIGHT they count app
ledger blocks, which are produced only when there are messages; an idle chain
does not age. VERIFIED_L1_SLOT scheduling needs logicalTimeVersion=2 in the
observation profile and a positive l1.stability-depth.
- The first due anchor must be strictly in the future.
- A round stays open through its report deadline. After the deadline and a
pinned inclusion grace, it becomes
EXPIRED. - Cadence zero is one-shot; a positive cadence makes the subscription recurring.
When things go wrong
Section titled “When things go wrong”| Problem | Example | What happens |
|---|---|---|
| Local acquisition | DNS failure, timeout, rate limit | The member retries locally. It signs nothing about the failure. |
| Evidence or report | Bad signature, broken Merkle path, stale proof | The member rejects it locally. It is never turned into a “false” answer. |
| Round or policy | Too few or disagreeing reports, deadline passed | The round stays open until its deadline, then becomes EXPIRED. |
Evidence and policies
Section titled “Evidence and policies”| Policy or verifier | What it checks |
|---|---|
exact-value-quorum-v1 | Exactly the threshold of member reports agree on one value, source, and version. |
ed25519-merkle-inclusion-v1 with the https-attested-merkle-v1 adapter | A leaf for this round sits under a Merkle root signed by an authorized attestor, with at most 20 sibling hashes. |
complete-source-median-v1 with external reporters | Each required source has exactly the required number of agreeing reports from configured reporter keys; the value is a lower median after outlier filtering. |
A wake hint, POST …/observations/wake with a subscription id, asks a node to
try sooner. Its 202 HINT_ACCEPTED means only that: it cannot open a round,
extend a deadline, or supply a value.
The observation profile is genesis-pinned through
observations.profile-cbor-hex. Changing it on a retained chain is not an
in-place upgrade. Read Yano’s
certified observations guide
before you create an application identity that uses them.
The shipment reference workflow
Section titled “The shipment reference workflow”The shipment-workflow-reference-v1 stdlib plugin shows one order across four
authorities: a stable Cardano payment, a certified delivery observation, a
cardano.payment effect that pays the merchant, and a second stable Cardano
deposit that settles it. Its workflow query reports one phase:
| Phase | Name | Meaning |
|---|---|---|
| 0 | WAITING_PAYMENT | Waiting for a deposit of at least the minimum to the payment address |
| 1 | WAITING_SHIPMENT | Waiting for a certified delivery result |
| 2 | RELEASE_PENDING | Waiting for the payment effect’s result |
| 3 | WAITING_SETTLEMENT | Waiting for a merchant deposit with the release transaction’s hash |
| 4 | COMPLETE | Terminal: all four authorities agree |
| 5 | SHIPMENT_UNRESOLVED | Terminal: the result was EXPIRED, or a value other than DELIVERED |
| 6 | RELEASE_FAILED | Terminal: the payment effect did not confirm with a transaction hash |
An executor receipt alone never completes the workflow, and an expired or
non-DELIVERED observation never releases funds. The
shipment reference gives the
configuration, pinned inputs, and validation boundaries. It is a single-order
teaching example, not a production escrow contract.
What the evidence means
Section titled “What the evidence means”A valid source signature and inclusion proof establish what the authorized attestor committed. They do not prove that a parcel physically arrived or that a source is honest. The source trust policy remains part of the application design. Generic observations do not replace Cardano validation.
The ADA/USD reference demonstrates multiple source reports and deterministic aggregation with synthetic fixtures. It is a teaching example, not a production price oracle.
Observations, roles, and effects
Section titled “Observations, roles, and effects”| Need | Capability |
|---|---|
| Bring supported external evidence into the application | Observations |
| Decide who may propose or approve a business action | Domain roles and approvals |
| Authorize work in an external system after a transition | Effects |
Yano X provides application examples and domain behavior through the plugin catalog. Observation profiles and source policies are pinned inputs; follow the version-matched reference before creating a new application identity. The examples are preview workflows, not production escrow or oracle products.