[DeFi][FIN-23] Optional authenticated price observations and time-weighted quotes #73

Umbrella #43 · work-item FIN-23 · proposal / no release milestone.

What does it do? Plain English

Other programmes may need an average price over time, rather than a manipulable spot quote. Historical samples must be authenticated and missing or stale observations cannot be silently fabricated.

Visual walkthrough

flowchart TD
A["Committed price / liquidity observations"] --> B["Update bounded history"]
B --> C["Authenticate past sample range"]
C --> D{"Enough valid fresh history?"}
D -- No --> X["Reject or unavailable"]
D -- Yes --> E["Compute bounded average price"]

Implementation layer: Oracle/observation protocol and query SDK.

Prerequisites: #65 FIN-15 executed swaps; #69 FIN-19 hook execution; FIN-22 truthful temporal guarantees; #63 FIN-13 or another authenticated history layout.

Detailed design and security review

Observations as authenticated financial data

A time-weighted quote should derive from a reproducible sequence of actual pool price/liquidity state updates. A user-supplied list of plausible samples can omit or forge history; the observation store therefore needs a committed root or selected authenticated Cell sequence and defined continuity. This issue is optional for ordinary pool execution, and should not force every pool to pay an observation storage cost.

Data and time semantics

Freeze observation record identity, previous/current cumulative values, chosen fixed-point domain, sample timestamp/epoch domain, source pool state root, history capacity and overwrite policy. Distinguish pure price cumulative, tick cumulative and time-in-liquidity accumulation, and admit only mathematically specified query forms. A sample can be valid yet stale for a user's requested window. Same-timestamp updates, zero activity, liquidity gaps and chain reorganisation each need an explicit policy, informed by #72's actually enforceable temporal guarantees.

Implementation stages

1. Implement a tiny observation history with deterministic append/update and independently calculated cumulative values.
2. Add optional stateful hook or explicit protocol action for observation updates; prove that skipped updates cannot be interpreted as measurements where continuity is required.
3. Authenticate historical window openings from persistent committed pages, with bounded witness and query cost.
4. Provide typed query SDK returning value plus exact sample provenance and insufficiency/staleness status, not an unqualified trusted number.
5. Have an external consumer contract use the result and test the safety and limitations of its chosen lookback/refresh assumptions.

Attack matrix

Acceptance evidence

Compare to a mathematically independent historical model with regularly and irregularly spaced updates. Measure worst-case reads and storage/capacity growth. Document that TWAP mitigates but does not universally prevent price manipulation; the consumer's trust horizon and stale handling are part of the interface.

Security flow

flowchart TD
    S["Executed pool transitions"] --> O["Append authenticated observations"]
    O --> P["Open exact historical window"]
    P --> Q{"Complete and fresh under declared rule?"}
    Q -- No --> X["Unavailable / reject"]
    Q -- Yes --> A["Compute checked cumulative average"]
    A --> C["Consumer verifies provenance"]

Shared assurance rules

• The protocol owns its economic policy; these issues do not add finance-specific syntax or special compiler behaviour. Any missing business-neutral general primitive needs a separate minimal failing case, versioned contract and evidence.
• Freeze concrete source/chain/ABI/asset roles, numerical bounds, revocation semantics and a named reviewer/waiver disposition before claiming acceptance. No original issue or human review is silently inherited.
• Execute complete actual CKB transactions with all required script groups. Preserve independent model, generated builder, checker mutation, exact source/ELF/CellDep/tx/node evidence and worst success/late-rejection budgets. A valid simulator trace, RPC response or indexer record alone is not authority.

Implementation contract

• Specify optional cumulative price/tick/liquidity observation storage, sample cadence, history capacity, observed chain context and canonical update/lookup codecs.
• Define permitted TWAP/median or truncated profile explicitly, including different sampling assumptions and rounding; keep oracle optional for ordinary pools.
• Authenticate historical pages/root and distinguish query result, refresh, stale cache, same-time updates, skipped observations and chain reorganisation.
• Record manipulation and liquidity/lag assumptions, rather than promising that an average alone removes adversarial price risk.

Acceptance

• Query results over independent model histories match reference at min/typical/max windows.
• Forged history, missing pages, stale roots, insufficient samples, zero liquidity and invalid timing reject or explicitly return unavailable.
• At least one outside protocol consumes an authenticated observation under checked trust/freshness assumptions.
• Compare query and update cycles, bytes and occupied capacity; real node and host/model results are clearly distinguished.

Explicit exclusions: Oracle data is protocol state and verification, not automatic trusted system time or a global compiler primitive.

Programme-wide acceptance discipline

• Proposed only; assign accountable implementer/review disposition, versioned threat/ABI/numeric limits and exact evidence before claiming implementation.
• Financial semantics live in ordinary CellScript protocol packages and generated builders, not hard-coded finance language constructs. A genuine general core gap must become a separate business-neutral issue.
• Preserve exact compiler/checker/source/ELF/CellDep/transaction/model identities, full-transaction positive/hostile cases, frozen resource ceilings and applicable gates. No node deployment or human audit is inferred.

Verified dependencies and implementation sequencing

Hard prerequisites: #65, #69, #72.

Conditional state-data prerequisite: #63 or a separately admitted equivalent.

Unblocks / integrated by: #78.

Security and scheduling rationale: Historical page commitment can reuse #63 or another separately validated authenticated-history contract; the oracle remains optional for basic pool transactions.

These are referenced planning contracts; no automatically enforced GitHub blocking relationship or accepted implementation is claimed.