Skip to content

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.

L1 observersGeneric certified observations
Brings inCardano facts: deposits to an address, transactions with a metadata label, epoch dataFacts from outside Cardano, such as a signed shipment report
Who checks itEvery member re-derives the fact from its own Cardano viewMembers, or configured external reporters, sign matching reports; a certificate carries them
Arrives asA framework message on ~l1/<observer-id>A certified result on ~obs/result/v1
Your code receives it incontext.l1Observations() during apply()onObservationResult(...)
StatusBundled, previewPreview, disabled by default

Both are consensus inputs: every member must use the same observer settings and the same genesis-pinned observation profile.

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.

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 expiry

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

This round comes from the shipment reference workflow, described below.

Certify an external factIllustrative data

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.

  1. Payment lands A buyer pays the order’s Cardano address. Each member’s address-deposit observer sees it, and once it is l1.stability-depth blocks deep it is sequenced into a block. Followers re-derive it from their own Cardano view. apply() receives it in context.l1Observations().
  2. 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.
  3. 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.
  4. Fetch Outside block execution, each member’s https-attested-merkle-v1 adapter 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.
  5. 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
  6. 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.
  7. Include The proposer adds the certified result to a block as a ~obs/result/v1 input. Followers verify the certificate before they vote PREPARE; an invalid certificate for an open round rejects the block.
  8. Apply When the block is final, every member calls onObservationResult with status VALUE and value DELIVERED. The state machine emits a cardano.payment effect with a CHAIN result to pay the merchant, and moves to RELEASE_PENDING.
  9. 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.

  1. Payment lands A buyer pays the order’s Cardano address. Each member’s address-deposit observer sees it, and once it is l1.stability-depth blocks deep it is sequenced into a block. Followers re-derive it from their own Cardano view. apply() receives it in context.l1Observations().
  2. 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.
  3. 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.
  4. Fetch Member A fetches valid evidence. Member B receives a path that does not reach the signed root.
  5. 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
  6. Deadline passes The round stays open until its report deadline. After that and the inclusion grace, every member derives EXPIRED from committed state, without a certificate.
  7. Shipment unresolved onObservationResult receives status EXPIRED. The workflow stops at SHIPMENT_UNRESOLVED, and no payment effect is emitted.

What if: The attestor reports another value

A certified value is still only what the attestor committed.

  1. Payment lands A buyer pays the order’s Cardano address. Each member’s address-deposit observer sees it, and once it is l1.stability-depth blocks deep it is sequenced into a block. Followers re-derive it from their own Cardano view. apply() receives it in context.l1Observations().
  2. 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.
  3. 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.
  4. Fetch Outside block execution, each member’s https-attested-merkle-v1 adapter 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.
  5. 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
  6. 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.
  7. Include The proposer adds the certified result to a block as a ~obs/result/v1 input. Followers verify the certificate before they vote PREPARE; an invalid certificate for an open round rejects the block.
  8. Shipment unresolved The result is VALUE, but the value is not DELIVERED. The state machine moves to SHIPMENT_UNRESOLVED and releases nothing.
  • deterministic, on every member
  • reporting member
  • external source
  • Cardano
  • final
  • rejected or unresolved
StatusMeaning
VALUEA certified value was finalized. Under exact-value-quorum-v1, exactly the round’s report threshold of reports agreed on it.
EXPIREDNo valid certificate was included in time. Members derive it from committed round state, without a certificate.
CANCELLEDThe application cancelled the subscription.
NO_RESULTReserved. 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.

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.
ProblemExampleWhat happens
Local acquisitionDNS failure, timeout, rate limitThe member retries locally. It signs nothing about the failure.
Evidence or reportBad signature, broken Merkle path, stale proofThe member rejects it locally. It is never turned into a “false” answer.
Round or policyToo few or disagreeing reports, deadline passedThe round stays open until its deadline, then becomes EXPIRED.
Policy or verifierWhat it checks
exact-value-quorum-v1Exactly the threshold of member reports agree on one value, source, and version.
ed25519-merkle-inclusion-v1 with the https-attested-merkle-v1 adapterA 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 reportersEach 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-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:

PhaseNameMeaning
0WAITING_PAYMENTWaiting for a deposit of at least the minimum to the payment address
1WAITING_SHIPMENTWaiting for a certified delivery result
2RELEASE_PENDINGWaiting for the payment effect’s result
3WAITING_SETTLEMENTWaiting for a merchant deposit with the release transaction’s hash
4COMPLETETerminal: all four authorities agree
5SHIPMENT_UNRESOLVEDTerminal: the result was EXPIRED, or a value other than DELIVERED
6RELEASE_FAILEDTerminal: 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.

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.

NeedCapability
Bring supported external evidence into the applicationObservations
Decide who may propose or approve a business actionDomain roles and approvals
Authorize work in an external system after a transitionEffects

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.