[jhayniffy]

Summary

Oracle integrity: schema drift, consistency rules, rewards, and review queue

What was solved

#279 — Detect Upstream Provider Schema Drift and Breaking Changes Before Ingestion Breaks

Add a versioned, per-adapter response-shape declaration and a schema-drift validator that runs before parsing/normalization on every provider fetch, classifying mismatches as drift (warn + redacted sample capture) or breaking (reject ingestion, quarantine source, fire alert), persisting drift events with last-known-good samples, attaching detection results to the evidence record, and exposing a per-source drift report via the operator API/CLI.

Addressed:

• Changed: src/oracle/validation/schemaDrift.ts, src/services/oracleMonitor.ts, src/db/schema.sql
• Each adapter (CoinGecko, Horizon, DeFiLlama) declares an expected response shape — structural schema plus required units and nullability — in a module separate from parsing code.
• Every fetch validates the payload against the declared shape before parsing/normalization so tolerant parsing cannot mask a shape change.
• Unexpected structures are classified as drift (informational warn + redacted sample capture) or breaking (ingestion rejected, source quarantined, alert fired).

#280 — Implement Cross-Feed Economic Consistency Checks Between Related Metrics

Add a declarative cross-feed economic consistency layer: define rules between economically related feeds (LiquidationShield vs price/TVL, FlightDelay vs route disruption) in a new rules module, evaluate them post-consensus with point-in-time semantics, emit anomaly events with human-readable explanations, and support warn/block severity (block holds publication and trips the relevant circuit breaker). Declare feed relationships in the coverage catalog, persist rule evaluations via schema/migration, and document rationale. Rules must skip (not fail) when one side is missing and never block publication when skipped.

Addressed:

• Changed: src/oracle/consistency/rules.ts, src/oracle/consistency/rules.ts, src/oracle/consistency/evaluate.ts, src/oracle/consistency/rules.ts
• Create src/oracle/consistency/rules.ts with declarative consistency rules between feed pairs/groups (correlation expectation, allowed lead/lag, sign/ratio constraints) for existing coverage types: LiquidationShield vs price/TVL and FlightDelay vs route disruption, each documented with rationale.
• Create src/oracle/consistency/evaluate.ts that runs rules on canonicalized consensus values plus timestamps with the same point-in-time semantics as consensus so replay reproduces the verdict.
• Integrate a post-consensus gate in src/services/oracleMonitor.ts that runs after per-feed consensus and before publication of the dependent feed; a violation emits an anomaly event with a human-readable explanation.

#281 — Add Operator Reward Accrual and Distribution for Honest Oracle Participation

Implement operator reward accrual and scheduled distribution for honest oracle participation: derive per-round accruals from committed consensus evidence (not live submissions), weight by stake and reputation with a per-operator cap, persist a durable idempotent ledger of accruals/adjustments/payouts, run scheduled distribution with a minimum payout threshold and dispute window, and expose an operator-facing reward history API.

Addressed:

• Changed: src/services/operatorRewards.ts, src/db/schema.sql
• Accrue rewards only for readings included in a committed consensus decision; late, quarantined, or duplicate submissions accrue nothing
• Weight accruals by stake and reputation score using a documented formula, with a cap preventing a single operator from dominating the pool
• Persist a durable ledger of accruals, adjustments, and payouts with an idempotency key per accrual (exactly-once under retries/re-orgs)

#282 — Implement a Human Review Queue for High-Value and Ambiguous Oracle Decisions

Add a durable human review queue that gates settlement for high-value, low-confidence, evidence-immature, and post-remediation oracle decisions. Queue entries are created from claimProcessor with full evidence packets, reviewer actions (approve/reject/escalate) are audit-logged, SLA expiry escalates rather than auto-settles, and settlement rejects decisions lacking a queue entry or approval reference.

Addressed:

• Changed: src/services/reviewQueue.ts, src/services/reviewQueue.ts, src/services/claimProcessor.ts, src/routes/review.ts
• Create new src/services/reviewQueue.ts implementing queue entry creation, reviewer actions (approve, reject with reason, escalate), audit logging with actor and timestamp, SLA tracking with escalation on expiry, and queue depth metric exposure.
• Modify src/services/claimProcessor.ts to hold decisions instead of settling when triggers fire: value above threshold, confidence below floor, evidence immaturity, and post-remediation re-decisions; attach decision, contributing readings, source attributions, anomaly flags, and plain-language explanation.
• Add new src/routes/review.ts exposing API endpoints for listing queue items, approving, rejecting, and escalating; enforce authorization on approve/reject.

Changes

• src/oracle/validation/schemaDrift.ts (create)
• src/oracle/consistency/rules.ts (create)
• src/services/oracleMonitor.ts (create)
• src/oracle/consistency/evaluate.ts (create)
• src/db/schema.sql (modify)
• src/services/operatorRewards.ts (create)
• src/services/reviewQueue.ts (create)
• src/services/claimProcessor.ts (create)
• src/routes/review.ts (create)

Approach

1. Detect Upstream Provider Schema Drift and Breaking Changes Before Ingestion Breaks #279 — Detect Upstream Provider Schema Drift and Breaking Changes Before Ingestion Breaks (Changed: src/oracle/validation/schemaDrift.ts, src/services/oracleMonitor.ts, src/db/schema.sql)
2. Implement Cross-Feed Economic Consistency Checks Between Related Metrics #280 — Implement Cross-Feed Economic Consistency Checks Between Related Metrics (Changed: src/oracle/consistency/rules.ts, src/oracle/consistency/rules.ts, src/oracle/consistency/evaluate.ts, src/oracle/consistency/rules.ts)
3. Add Operator Reward Accrual and Distribution for Honest Oracle Participation #281 — Add Operator Reward Accrual and Distribution for Honest Oracle Participation (Changed: src/services/operatorRewards.ts, src/db/schema.sql)
4. Implement a Human Review Queue for High-Value and Ambiguous Oracle Decisions #282 — Implement a Human Review Queue for High-Value and Ambiguous Oracle Decisions (Changed: src/services/reviewQueue.ts, src/services/reviewQueue.ts, src/services/claimProcessor.ts, src/routes/review.ts)

Issues

Closes #279
Closes #280
Closes #281
Closes #282

[drips-wave]

@jhayniffy Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits