[H3] Volume + savings: publisher write path, REST mirror, reconciliation (contract landed in #826)

[BigManly4]

Part of epic #808.

ROADMAP.md line 113. The corridor rate oracle proves a rate was correct at a point in time; this is the companion oracle that publishes cumulative volume routed and fees saved (vs. a naive baseline) so the "fees saved" number quoted anywhere in this product's marketing is independently checkable on-chain, not just a number this app's own backend asserts.

Scope

• Define the baseline "fees saved" is measured against (e.g. worst quoted rate in the comparison set at execution time) and publish that methodology, not just the number
• On-chain contract that accumulates volume + savings per settlement, written by the same publisher pipeline that already writes reputation outcomes (packages/publisher)
• Public read path (contract read, mirrored in the REST API) so the aggregate is queryable without trusting this app's own database
• Reconciliation: the on-chain aggregate must be derivable from the same outcome log reputation scoring already uses (lib/reputation/*), not a second, divergent accounting path

Depends on

• The existing reputation/outcome-log pipeline (lib/reputation, packages/publisher) as the source of truth this oracle publishes from

[ezedike-evan]

Rescoping — the on-chain half shipped.

Done:

• Contract storage and entrypoints — add_volume_savings / get_volume_savings (contracts/reputation/src/lib.rs:251-268, volume_savings.rs), publisher-gated
• Baseline methodology published, not just the number — docs/VOLUME_SAVINGS.md defines savings = baseline_received - actual_received and has a Baseline selection section

Still open:

• Public read path mirrored in the REST API. Nothing outside lib/oracle/read.ts references the accessor — there is no route exposing volume/savings, so the aggregate is not queryable over HTTP and the "checkable without trusting our database" claim only holds for someone who can read the contract directly.
• Reconciliation between the on-chain accumulator and the settlement rows that produced it.

Retitled to the remaining scope.

[ezedike-evan]

Retitled. This is a second-pass duplicate of #826, which is closed — the contract half shipped there. Here is the honest state against this issue's own four bullets:

Bullet	Reality
Define + publish the baseline "fees saved" is measured against	Done — docs/VOLUME_SAVINGS.md § "Baseline selection", three-tier priority order
On-chain contract accumulating volume + savings per settlement	Done — contracts/reputation/src/volume_savings.rs, add_volume_savings / get_volume_savings, publisher-auth-gated, cumulative and monotonic
Public read path, contract read mirrored in the REST API	Half — lib/oracle/read.ts::getVolumeSavings exists; there is no REST route and no volume-savings path in public/openapi.json
Reconciliation derivable from the same outcome log	Not started

The blocking piece is in none of those bullets: nothing computes volume or savings, and nothing calls add_volume_savings. There is no lib/oracle/volume-savings.ts. docs/VOLUME_SAVINGS.md currently states that the publisher writes it on every settlement — that claim is false today and should be corrected regardless of when the rest of this lands.

And the documented baseline is not computable from what is stored. types/reputation.ts::OutcomeLogRow keeps only the routed anchor's quotedRate / deliveredRate / quotedAmount / deliveredAmount:

• Priority 1 ("the anchor's own indicative rate at intent time") is the same anchor's quote, so it measures slippage, not savings against an alternative.
• Priority 2 ("corridor median across available anchors at execution time") needs the comparison set, which is never persisted — lib/stellar/snapshot.ts is in-process memoized behind a revalidate = 600, and app/api/snapshot/route.ts writes nothing durable.
• Priority 3 ("previous published corridor rate") is the only one derivable from durable state — and it is empty, because publish_corridor_rate has never been called.

So the real dependency chain is: wire publish_corridor_rate (filed separately, residual of the closed #810) → then either persist a rate_comparison_log or amend the doc to say only baseline 3 is in force → lib/oracle/volume-savings.ts mirroring lib/oracle/corridor-rate.ts (watch the unit mismatch: the contract uses microUSDC at 1e6, corridor-rate.ts uses RATE_DECIMALS = 7) → publisher writes deltas, not totals → REST mirror at app/api/v1/oracle/volume-savings/[corridor]/route.ts with a matching registry.registerPath in lib/api/openapi.ts, or tests/openapi-coverage.spec.ts fails the build → /reconcile route returning { onChain, derived, drift }, copying the shape of app/api/reputation/reconcile/route.ts.

Blocked on the corridor-rate wiring; buildable immediately after.