DA-05 · LESSON 09

Oracle freshness and failure modes

KEY DEFINITIONS

Terms used in this lesson

Oracle: A system that reports outside information, such as a market price, for use by a protocol.
Preimage: The original secret data whose hash equals a previously committed value.
Guardian: A Ducat policy-checking signer that can authorize or reject defined protocol transactions.
DON: Decentralized Oracle Network: a group of independent Chainlink oracle nodes that retrieve, check, combine, and sign outside data.
CRE: Chainlink Runtime Environment: the orchestration layer in which a workflow can request data, run checks, and coordinate outputs. It is not itself the price source.
Identifier: Identifier: a value used to distinguish one request, object, or participant from another.
Nostr: A signed-event messaging protocol; Ducat can use relays to distribute oracle material without making those relays Bitcoin validators.

Stale prices, relay availability, signer rotation, incomplete ladders, configuration drift, and undeployed security fixes must fail closed or be surfaced.

35 min Difficulty 5/5 Not started

VISUAL MODEL

See the whole mechanism before going step by step

Use the diagrams to orient yourself. Then the guided explanation below teaches every part in depth.

4 explanatory views

CONCEPT-SPECIFIC MAP · ducat vaultA Ducat action moves one Bitcoin-anchored vault state to a successorSelect any state to inspect its exact role.

RELATIONSHIP MAPInputs, rule, and outputs

01
PREDECESSORCurrent vault outpoint
The current Bitcoin output anchors collateral and identifies the state being spent.
02
REQUESTOracle freshness and failure modes
The Oracle freshness and failure modes workflow proposes one exact action and successor state.
03
POLICYProfile, oracle, signatures
Applicable policy, price evidence, authorization, and transaction shape are checked.
04
BITCOIN SPENDScript-valid transaction
Bitcoin miners and nodes can include only a transaction that satisfies Bitcoin rules.
05
SUCCESSORNew outpoint and state
Ducat validators reconstruct debt, collateral, token, and account changes from the confirmed transaction.

Rule shown: Bitcoin checks the spend; Ducat components independently reconstruct and validate the additional protocol state.

STAGE 1 OF 5PREDECESSOR: Current vault outpoint

The current Bitcoin output anchors collateral and identifies the state being spent.

Governing relationship: Bitcoin checks the spend; Ducat components independently reconstruct and validate the additional protocol state. Complete path: 1. PREDECESSOR, Current vault outpoint. The current Bitcoin output anchors collateral and identifies the state being spent. 2. REQUEST, Oracle freshness and failure modes. The Oracle freshness and failure modes workflow proposes one exact action and successor state. 3. POLICY, Profile, oracle, signatures. Applicable policy, price evidence, authorization, and transaction shape are checked. 4. BITCOIN SPEND, Script-valid transaction. Bitcoin miners and nodes can include only a transaction that satisfies Bitcoin rules. 5. SUCCESSOR, New outpoint and state. Ducat validators reconstruct debt, collateral, token, and account changes from the confirmed transaction.

1. State transitionWhat exists, what changes, and what results

BEFORE

The example report has the expected feed ID, observation time 1,700,000,000, expiry 1,700,000,300, price $100,000, three distinct authorized signatures, and a policy requirin…

MECHANISM

The v3 report has nine 32-byte words: feed ID, valid-from timestamp, observation timestamp, native fee, Chainlink-token fee, expiry, signed price, signed bid, and signed ask.…

AFTER

A report passes only when every configured gate passes. The adjustment control is explicitly development-only in the captured design and is not evidence of a mainnet feature.

Text equivalent: Starting from The example report has the expected feed ID, observation time 1,700,000,000, expiry 1,700,000,300, price $100,000, three distinct authorized signatures, and a policy requiring three signers. A signed development control… The mechanism begins when The v3 report has nine 32-byte words: feed ID, valid-from timestamp, observation timestamp, native fee, Chainlink-token fee, expiry, signed price, signed bid, and signed ask. The outer report also carries three context… The resulting lesson is A report passes only when every configured gate passes. The adjustment control is explicitly development-only in the captured design and is not evidence of a mainnet feature.

2. Mechanism pathSelect a stage to inspect its job

STAGE 1 OF 4

Decode the report fields

The v3 report has nine 32-byte words: feed ID, valid-from timestamp, observation timestamp, native fee, Chainlink-token fee, expiry, signed price, signed bid, and signed ask. The outer report also carries three context words and parallel r, s, and v signature components.

Complete path: 1. Decode the report fields: The v3 report has nine 32-byte words: feed ID, valid-from timestamp, observation timestamp, native fee, Chainlink-token fee, expiry, signed price, signed bid, and signed ask. The outer report also carries three context words and parallel r, s, and v signature components. 2. Validate the Ducat snapshot: Check oracle signature, network, key, base timestamp, ladder range, and complete current promotion. 3. Validate selected contracts: Recompute commitment fields and reject mismatched or expired threshold events. 4. Apply every gate: Check exact feed ID, positive price, observation freshness, expiry, configured bounds, and enough distinct authorized DON signers. Bad reports stop CRE, partial ladders stop promotion, bad events stop clients, unavailable oracle blocks release, and unavailable Guardians block authorization.

3. Rule and failure boundaryWhat accepts the result and where it can stop

ACCEPTED PATH

The worked case executes the named inputs and checks in the displayed order. Check exact feed ID, positive price, observation freshness, expiry, configured bounds, and enough distinct authorized DON signers. Bad reports stop CRE, partial ladders stop promotio…

CHANGED CONDITION

A missing, malformed, stale, unauthorized, or inconsistent required input stops at its first named boundary. Clients also need feed identity, timing, bounds, authorized signer configuration, coherent publication, and an explicit trust assumption about the ups…

Important distinction: A valid Chainlink signature is sufficient evidence that the price is current and correct. Clients also need feed identity, timing, bounds, authorized signer configuration, coherent publication, and an explicit trust assumption about the upstream market report.

Text equivalent: The accepted path is enforced by The worked case executes the named inputs and checks in the displayed order. Check exact feed ID, positive price, observation freshness, expiry, configured bounds, and enough distinct authorized DON signers. Bad reports stop CRE, partial ladders stop promotion, bad events stop clients, unavailable oracle blocks release, and unavailable Guardians block authorization. If the required condition changes, A missing, malformed, stale, unauthorized, or inconsistent required input stops at its first named boundary. Clients also need feed identity, timing, bounds, authorized signer configuration, coherent publication, and an explicit trust assumption about the upstream market report.

Loading lesson visuals...

Learn the idea

Freshness asks whether a signed report or snapshot is recent enough for the active policy. A Data Streams report is Chainlink's signed binary price report. A decentralized oracle network, or DON, is the configured group whose members sign that report. A Chainlink Runtime Environment, or CRE, workflow fetches and checks the report before Ducat creates its own snapshot. A report can include a fee denominated in Chainlink's network token. Authentication alone does not make old data safe.

GUIDED EXPLANATION1/4 ideas inspected

Decode the report fields

The worked example follows the explanation

Inspect every idea above to open it.

Important distinction“A valid Chainlink signature is sufficient evidence that the price is current and correct.”

Clients also need feed identity, timing, bounds, authorized signer configuration, coherent publication, and an explicit trust assumption about the upstream market report.

FINISH LEARNING FIRST

The questions unlock after every required learning activity

Inspect every guided idea, open the worked example, rebuild its mechanism, and complete the deterministic lesson tool. Your progress is saved automatically.