[achiever2110]

Implements #26 (SEP-40-correct price resolution) and #27 (TWAP resolution variant) in contracts/resolver, rebased onto current develop and re-resolved against PR #176's shared-types layout.

Closes #26
Closes #27

What landed

#26 — SEP-40 price resolution (original scope of this PR):

• Grid-aligned feed lookups: price(asset, ts) is queried at close_time - close_time % resolution() and walked back along the grid, bounded by MAX_LOOKBACK_RECORDS = 12 (fixes every off-boundary close missing its record).
• InvalidPrice for non-positive prices and resolution() == 0 feeds; PriceUnavailable for trapping feeds — never a host error.
• Decimal-explicit scaled thresholds: ScaledPriceConfig (+ MAX_THRESHOLD_DECIMALS = 38) rescales threshold and feed price to max(feed_decimals, threshold_decimals) with checked i128 arithmetic; register_scaled_price_spec; PriceResolutionScaled event; faithful SEP-40 exact-grid test mock.
• scripts/spec-hash price-scaled mode (incl. --decimal 0.20, exact no-float conversion).

#27 — TWAP resolution variant (folded on top as separate commits):

• TwapConfig { reflector, asset, threshold, direction, window, min_samples, max_gap } with register_twap_spec / resolve_twap (resolve_price dispatches TWAP markets too, mirroring the scaled dispatch).
• Sampling at resolution()-aligned timestamps in (close_time − window, close_time]; missing records skipped; duplicate timestamps (nearest-earlier feeds) counted once; < min_samples or any gap (start→first, consecutive, last→close) > max_gap → StalePrice; price ≤ 0 or overflow → InvalidPrice.
• Integer-only time-weighted average: i128 checked_mul/checked_add/checked_div, weight = time to next sample, newest sample weighted close_time − last_ts + 1 (closing second included; both sides of the division use one convention), floor division before the committed comparison.
• MAX_TWAP_SAMPLES = 32 hard cap as a cap on reads inspected, not samples found (the loop in the issue sketch is unbounded when records are missing — this closes that).
• DataKey::PriceTwap(u64) appended last; assert_unconfigured extended to the third key (no double-registration across the three price shapes); snapshot_price/preview_price reply WrongMode; TwapResolution { market_id, twap, samples, first_ts, last_ts, outcome } emitted alongside the unchanged PriceResolution/V2 pair; expire_market prefers a resolvable TWAP settle and voids on a dead feed like the other price shapes.
• scripts/spec-hash price-twap subcommand + tests.

Conflict resolution against develop (why the commits differ from the pre-rebase head)

The previous head was based on 5cba67b2; develop@655974c4 moved PriceConfig/SignerConfig/ResolutionSpec/ResolutionSpecV2 into contracts/oracledesk-types (PR #176), which the resolver re-exports. Router and treasury flow resolver::ResolutionSpec straight into ResolutionSpecV2.rule, so the enum cannot be shadowed locally and the types crate is not ours to edit here. Resolution, append-only and hash-safe:

• The scaled mode (Make PriceThreshold resolution SEP-40 correct: decimals, resolution periods, bad prices #26) and the TWAP mode (Add TWAP-based price resolution sampled from Reflector history #27) each commit through their own domain-tagged preimage — resolver::scaled_spec_hash = sha256("oracledesk:scaled-price-spec" || XDR(cfg)), resolver::twap_spec_hash = sha256("oracledesk:price-twap-spec" || XDR(cfg)) — the same disjointness construction ADR 0004 uses for V2 (legacy preimages are ScVal XDR starting 00 00 00 10; the four tags differ at fixed offsets). Every already-committed Price / Signers / V2 resolution_hash is byte-for-byte unchanged, and the ADR-0001 golden vectors still pin that.
• DataKey::PriceScaled / PriceTwap are appended last in the resolver's own key enum (positional discriminants; earlier keys keep their encoding).
• scripts/spec-hash delegates to the contract's own hash functions, so tool and contract cannot drift. The literal price-scaled golden hex pre-dates Feat/multi 60 59 58 57 #176 and is not re-pinnable by any runnable test at this tip (see Gates); its test now pins delegation equality + hash-space disjointness + --v2 rejection, with the re-pin listed as maintainer follow-up. Same discipline for the new price-twap vector.
• Canonical end state (append PriceScaled/PriceTwap variants into oracledesk-types::ResolutionSpec, then simplify the CLI) is documented in ADR 0001 as maintainer follow-up.

Issue-text traps, handled honestly

• Add TWAP-based price resolution sampled from Reflector history #27 "reuse whatever alignment helper Add on-chain market directories indexed by status, category and holder #25 introduces": Add on-chain market directories indexed by status, category and holder #25 did not land any helper on this base; the alignment machinery that exists on this branch is Make PriceThreshold resolution SEP-40 correct: decimals, resolution periods, bad prices #26's (read_feed_on_grid and its grid math), and the TWAP sampler reuses exactly that pattern. Nothing from Add on-chain market directories indexed by status, category and holder #25 was implemented here.
• Add TWAP-based price resolution sampled from Reflector history #27 "hard cap chosen from measured CPU cost": the measurement (env.cost_estimate() against the registered wasm) is not executable at this tip — no cargo test runs at all (verbatim below). MAX_TWAP_SAMPLES = 32 is therefore reasoned, not measured: it matches the crate's own accepted ceilings MAX_WEIGHTED_SIGNERS = 32 / MAX_COMMITTEE = 32, and the weighted-keys path already verifies up to 32 ed25519 signatures in one call (documented at 23.1M instructions in ADR 0001), a per-item cost strictly above one bounded price read. No benchmark number is claimed; a measured re-derivation is a maintainer follow-up. Stated in the code, ADR 0001, and here.

Gates — actual numbers at the pushed head

develop itself does not compile, so no cargo test suite can execute at this tip. Two independent, upstream-owned death vectors (neither file appears in git diff --name-only 655974c4 HEAD — verified count 0):

1. contracts/oracledesk-types/src/lib.rs:27 never imports contracttype (used ~16×) → 21 errors on +1.91.0 for every dependent crate; the pinned 1.90.0 is refused by soroban-sdk@27.0.6's MSRV. (Recorded in the lane log runs/L139__abercrombie04__OracleDesk__184-rebase-develop-17-19/gate_attempt_rebase_tip_191.log.)
2. The resolver's build.rs chain compiles scripts/verify-wasm-hash.rs, which fails with 14× E0753 (inner doc comments in a non-module file).

The gate this PR was expected to clear, run twice around Phase B (cargo +1.91.0 test --manifest-path scripts/spec-hash/Cargo.toml, via the repo sandbox, warm dep cache):

• Before Phase B: exit 101, 0 tests executed (test result lines: 0), 14× E0753.
• After Phase B: exit 101, 0 tests executed (test result lines: 0), 14× E0753 — byte-identical failure mode. Verbatim (path elided):

  error[E0753]: expected outer doc comment
    --> .../contracts/resolver/../../scripts/verify-wasm-hash.rs:1:1
  ...
  error: could not compile `resolver` (build script) due to 14 previous errors
  

  My diff adds no new errors (identical counts and error set pre/post), but the golden-hash suite genuinely executes 0 tests at this tip — I am not claiming a pass. Last green for these suites was at the old pre-rebase base: resolver 117 passed / 0 failed, spec-hash 12 passed (recorded in the rescue lane for the previous head). Restoring the build gate (oracledesk-types import fix, verify-wasm-hash.rs comment fix) is repo-owned and out of this PR's scope; once restored, the suites here are expected to run unchanged.
• contracts/treasury is red at develop independently (E0081, contracts/treasury/src/lib.rs:473-498); nothing in this PR touches it, and no --workspace run is used to average the two together.

Gates that do execute here, and did:

• Standalone rustfmt --edition 2021 --check: scripts/spec-hash/src/lib.rs clean; contracts/resolver/src/lib.rs complaint set identical to pristine develop (12 pre-existing sites, content-compared via normalized multiset diff — 0 new complaints introduced, upstream sites deliberately not reformatted).
• git diff 655974c4 HEAD -- '*.wasm' | wc -c → 0 (and *.sha256 → 0): no deployed blob was silently mutated; bindings/wasm rebuild is listed below.

Tests added (source-level; execution blocked as above)

#26: grid alignment incl. off-boundary close, walkback cap & staleness, resolution()==0, zero/negative price, direction×price matrix, foreign-asset isolation, preview/snapshot mode guards, --decimal equivalence, scaled comparison/equality/overflow/mutual-exclusion, commitment cross-checks against scripts/spec-hash vectors. #27 (16 new tests): twap_resolves_yes_when_average_above_threshold_despite_last_print_below, twap_resolves_no_when_single_spike_at_close, twap_rejects_insufficient_samples, twap_rejects_gap_larger_than_max_gap (all three gap kinds), twap_weighting_exact_known_value (hand-computed 4-sample case), twap_overflow_returns_invalid_price, twap_rejects_nonpositive_sample, register_twap_spec_infeasible_window_rejected (incl. unreachable-reflector PriceUnavailable), cannot_register_twap_when_price_spec_exists (both directions + scaled + WrongMode guards), resolve_twap_lifecycle, resolve_price_dispatches_twap_markets, twap_emits_resolution_events_with_avg_and_window, twap_read_cap_bounds_window_of_missing_records, twap_ignores_duplicate_records_from_nearest_earlier_feed (mock gains a nearest-earlier mode), plus expire-resolve-preferred and expire-void-on-dead-feed; spec-hash gains golden_price_twap_vector (delegation, disjointness vs price/signers/scaled, verify round-trip, --v2 rejection) and arity/type rejection cases.

Maintainer follow-ups (deliberately not done here)

1. Rebuild wasm + regenerate bindings once the build gate compiles (7 .wasm blobs are unverifiable here — this PR proves a zero-diff instead of a fake rebuild).
2. Re-pin the literal price-scaled/price-twap golden hexes by an actual host run.
3. Append PriceScaled/PriceTwap variants into oracledesk-types::ResolutionSpec (append-only) once that crate's toolchain wall is fixed.
4. Measure MAX_TWAP_SAMPLES CPU per the issue text and reconcile with 32.

No approving review was invalidated by the force-pushes: the review count on this PR was 0 before and is 0 after (three --force-with-lease pushes: rescue rebase f3d71e30 → 255f760, then Phase B in two steps 255f760 → 84310df → 05c508c).

[drips-wave]

@achiever2110 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