@waterx/sdk 4.3.2 → 5.0.0

package/dist/src/oracle/rules/waterx-rule.d.ts

@@ -1,43 +1,71 @@
 /**
  * `WaterxRule` — `PriceUpdateRule` for the first-party WaterX quote-center
- * (Nautilus-TEE, ed25519), plus `feedWaterxRule`, the collector-feed leg
- * `aggregateTicker` appends per waterx-routed ticker. Pulls one enclave-signed
- * batch envelope covering every requested ticker from the quote-center
- * (`GET /v1/quotes/update?symbols=…`, endpoint from `host.waterx` — the
- * `waterxEndpoint`/`waterxFetch` create options — else its own `WATERX_INFRA`), then —
- * unlike Pyth Lazer, whose verify is a single shared PTB step — verifies AND
- * feeds in ONE `waterx_rule::collect_batch_latest` call per collector (the Move
- * API bundles the two). So `buildUpdateCalls` emits nothing and the signed
- * envelope is handed straight to the per-ticker feed leg.
- *
- * `collect_batch_latest` is the dual-rule path: it feeds the item matching
- * `collector.symbol()` WITHOUT aggregating, so a waterx-routed ticker composes
- * onto the same collector as Pyth/Supra (compose-then-aggregate). On-chain a
- * FRESHNESS miss ABSTAINS (the other weighted rules cover); a config/
- * integrity mismatch, bad signature, future timestamp — or a REPLAYED signed
- * timestamp — ABORTS (`EReplayedSignature`, audit F-014: a signed tuple is
- * single-use per symbol, enforced by a per-symbol high-water mark BEFORE any
- * weight arbitration). Consequence for concurrent builds: two PTBs carrying
- * the same envelope for the same symbol cannot both land — the second aborts
- * even if the rule is unweighted for that ticker. Never share one fetched
- * envelope across builds that may execute concurrently for the same symbol.
+ * (Nautilus-TEE, ed25519), plus the collector-feed legs `aggregateTicker`
+ * appends per waterx-routed ticker. Endpoint comes from `host.waterx` (the
+ * `waterxEndpoint`/`waterxFetch` create options), else this source's own
+ * `WATERX_INFRA`. Unlike Pyth Lazer, whose verify is a single shared PTB step,
+ * the Move API bundles verify AND feed into ONE call per collector, so
+ * `buildUpdateCalls` emits nothing and the signed data is handed straight to
+ * the per-ticker feed leg.
+ *
+ * TWO wire shapes carry the same prices, and this rule prefers the first:
+ *
+ * 1. **Merkle leaves** (default) — `GET /v1/quotes/leaves?symbols=…` returns one
+ *    `SignedLeaf` per symbol: the price fields, a Merkle `proof`, and the
+ *    enclave's signature over the snapshot ROOT (`MERKLE_ROOT_INTENT`). Fed via
+ *    {@link feedWaterxRuleWithProof} → `waterx_rule::collect_single_with_proof`,
+ *    which re-derives the root from the leaf + proof. One symbol costs ONE
+ *    `new_batch_item` plus ~log2(n) 32-byte proof hashes.
+ * 2. **Batch envelope** (fallback) — `GET /v1/quotes/update?symbols=…` returns
+ *    ONE signature over the whole item vector (`BATCH_PRICE_INTENT`). It is
+ *    indivisible: {@link feedWaterxRule} must rebuild EVERY item in-PTB for
+ *    `waterx_rule::collect_batch_latest` to re-verify, even to use one symbol's
+ *    price. With the 29-feed mainnet registry that is 58 extra moveCalls and
+ *    ~320 extra pure inputs on every trade, which is why it is no longer the
+ *    default. Used only when the quote-center has no leaf route yet (404),
+ *    and by callers that still push whole batches.
+ *
+ * Both collect entries are the dual-rule path: they feed `collector.symbol()`
+ * WITHOUT aggregating, so a waterx-routed ticker composes onto the same
+ * collector as Pyth/Supra (compose-then-aggregate). Their abort-vs-abstain
+ * disposition is identical: a config/integrity mismatch, a bad signature or a
+ * signed timestamp AHEAD of the on-chain `Clock` ABORTS; a freshness miss
+ * ABSTAINS so the other weighted rules cover a lagging TEE, and so does a
+ * REPLAYED signed timestamp (the per-symbol high-water mark of audit F-014 —
+ * already-recorded means the chain holds a price at least this fresh, so two
+ * PTBs carrying the same snapshot for the same symbol no longer kill each
+ * other; only the single-rule `feed_*` entries abort on a replay).
  */
 import type { Transaction, TransactionArgument } from "@mysten/sui/transactions";
 import type { Network } from "../../constants.ts";
 import type { OracleHost } from "../host.ts";
 import { type PriceUpdateRule, type RuleUpdateData } from "../price-update-rule.ts";
-/** The single signing intent the quote-center emits — exported so read-plane
- *  consumers can mirror the rule's own envelope intent check (a mispointed
- *  endpoint must be rejected by reads exactly as tx-builds reject it). */
+import type { OraclePriceEntry } from "../read-prices.ts";
+import { type FetchPolicy } from "../update-fetch.ts";
+/** Intent the quote-center signs a whole BATCH payload under. Exported to NAME
+ *  the signing scheme only — consumers no longer mirror the intent gate
+ *  themselves: every quote-center pull (tx-build fetch, read executor, BE
+ *  prefetch) goes through {@link fetchWaterxSignedUpdate} /
+ *  {@link fetchWaterxSignedLeaves}, which enforce it, so a mispointed endpoint
+ *  is rejected identically on every path. */
 export declare const BATCH_PRICE_INTENT = 1;
+/**
+ * Intent the quote-center signs a snapshot's Merkle ROOT under
+ * (`waterx_rule::MERKLE_ROOT_INTENT`). Distinct from
+ * {@link BATCH_PRICE_INTENT} on purpose: the intent byte is the first field of
+ * the signed `IntentMessage`, so a batch signature can never be replayed as a
+ * root signature or vice versa. Leaves carry no `intent` field of their own —
+ * they are only ever submitted through `collect_single_with_proof`, which pins
+ * the intent on-chain — so this exists to name the scheme, not to gate a parse.
+ */
+export declare const MERKLE_ROOT_INTENT = 2;
 /**
  * WaterX quote-center external infra — owned by THIS source, by network.
- * Mirrors `PYTH_CORE_INFRA` (oracle/pyth.ts) and `LAZER_INFRA`
- * (rules/pyth-lazer-rule.ts): per-network constants for infrastructure the
- * source's operator runs, co-located with the only rule that reads them — no
- * other oracle source ever touches a quote-center endpoint. Public read (no
- * auth), so there is no api_key. `endpoint` has no trailing slash — the rule
- * appends the path.
+ * Mirrors `LAZER_INFRA` (rules/pyth-lazer-rule.ts): per-network constants for
+ * infrastructure the source's operator runs, co-located with the only rule
+ * that reads them — no other oracle source ever touches a quote-center
+ * endpoint. Public read (no auth), so there is no api_key. `endpoint` has no
+ * trailing slash — the rule appends the path.
  *
  * These are the DEFAULTS behind the caller's `client.waterx` access slice
  * (`waterxEndpoint` / `waterxFetch` create options) — the browser-CORS proxy
@@ -49,11 +77,32 @@ export declare const WATERX_INFRA: Record<Network, {
 /**
  * The waterx source's quote-center base for `network` — the ONE accessor
  * consumers (BE/FE read planes) use when, and only when, their own
- * `ORACLE_SOURCE` resolves to `'waterx_rule'`. Mirrors
- * `pythCoreHermesEndpoint`. Under any other source the read endpoint is that
- * source's own configuration — never this one.
+ * the config wires `waterx_rule`. Under any other source the
+ * read endpoint is that source's own configuration — never this one.
  */
 export declare function waterxQuoteCenterEndpoint(network: Network): string;
+/**
+ * Off-chain mirror of the on-chain `waterx_rule` `FeedConfig.max_age` DEFAULT
+ * (90s): a price older than this ABSTAINS on-chain, so a read plane serving it
+ * as live would show a price no trade could execute against. The single
+ * source of truth for consumers' post-cache freshness filters — import this,
+ * never re-declare the number. (A deployment that overrides `max_age`
+ * per-feed on-chain diverges from this mirror; none does today.)
+ */
+export declare const WATERX_MAX_PRICE_AGE_MS = 90000;
+/**
+ * `true` iff a quote-center read entry is still within
+ * {@link WATERX_MAX_PRICE_AGE_MS} of `nowMs` — the freshness predicate
+ * consumers apply to `readQuoteCenterPrices` output (post-cache), matching
+ * the on-chain abstain boundary instead of each inventing a policy.
+ */
+export declare function isFreshWaterxEntry(entry: OraclePriceEntry, nowMs: number): boolean;
+/**
+ * How far ahead of the reader's clock a quote-center timestamp may sit before
+ * it is treated as broken rather than merely skewed. Two independent clocks
+ * drift; a price minutes in the future does not.
+ */
+export declare const WATERX_CLOCK_SKEW_TOLERANCE_MS = 5000;
 /**
  * One item inside a signed batch payload, mirroring the quote-center
  * `/v1/quotes/update` JSON 1:1 (snake_case). The u64 integer fields are the
@@ -88,39 +137,204 @@ export interface WaterxSignedEnvelope {
     /** ed25519 signature over `BCS(IntentMessage<BatchPricePayload>)`, hex (± `0x`). */
     signature: string;
 }
-/** `waterx_rule`'s narrowed `RuleUpdateData.payload` shape. */
-export interface WaterxUpdatePayload {
+/**
+ * One enclave-signed Merkle leaf from `GET /v1/quotes/leaves` — identical shape
+ * to the `/v1/quote/stream/signed` SSE/WS events (quote-center serves both from
+ * one conversion), so a leaf from either transport submits the same way.
+ *
+ * It is the batch item's fields PLUS its membership proof: on-chain,
+ * `collect_single_with_proof` recomputes `keccak256(0x00 || BCS(item))`, folds
+ * it through `proof` (sorted pairs, no direction flags), and verifies the
+ * enclave's signature over THAT root — so every item field must round-trip
+ * byte-for-byte, exactly as for the batch path.
+ */
+export interface WaterxSignedLeaf extends WaterxBatchItem {
+    /**
+     * Enclave signing timestamp of the SNAPSHOT ROOT (ms) — the on-chain
+     * `timestamp_ms` argument. Shared by every leaf of one snapshot, and distinct
+     * from `price_timestamp_ms` (when the price itself was observed).
+     */
+    signed_timestamp_ms: bigint;
+    /** keccak256 Merkle root (hex). Diagnostic only — the chain re-derives it. */
+    root: string;
+    /** Sibling hashes (hex, 32 bytes each) folding this leaf to `root`. Empty for a one-leaf snapshot. */
+    proof: string[];
+    /** ed25519 signature over `BCS(IntentMessage<MerkleRoot>)`, hex (± `0x`). */
+    signature: string;
+}
+/** Leaf variant of `waterx_rule`'s `RuleUpdateData.payload` — the default path. */
+export interface WaterxLeafPayload {
+    readonly leaves: readonly WaterxSignedLeaf[];
+}
+/** Batch-envelope variant of `waterx_rule`'s `RuleUpdateData.payload` — the fallback path. */
+export interface WaterxEnvelopePayload {
     readonly envelope: WaterxSignedEnvelope;
 }
+/**
+ * `waterx_rule`'s narrowed `RuleUpdateData.payload` shape: a per-symbol leaf set
+ * OR one indivisible batch envelope. The variant a payload carries decides which
+ * on-chain entry the feed leg emits, so consumers must route on it via
+ * {@link waterxLeavesOf} / {@link waterxEnvelopeOf} rather than assuming either.
+ */
+export type WaterxUpdatePayload = WaterxLeafPayload | WaterxEnvelopePayload;
 /**
  * Parse a quote-center `/v1/quotes/update` response body into a
- * {@link WaterxSignedEnvelope} with the u64 fields decoded as `bigint`, exact.
- *
- * The signature is over `BCS(IntentMessage<BatchPricePayload>)`, so every u64
- * the SDK rebuilds in-PTB must equal the enclave's byte-for-byte or
- * `collect_batch_latest` aborts the whole trade PTB (bad signature — not an
- * abstain). A plain `JSON.parse` yields IEEE-754 doubles that lose precision
- * above 2^53, so instead we recover each integer's exact source literal via the
- * ES2023 reviver `context.source` (Node 21+ / modern browsers) and `BigInt()`
- * it. On an older runtime that passes no `context`, a value within 2^53 is
- * still exact (`BigInt(number)`); a value ABOVE it throws loudly here rather
- * than silently corrupting the payload into an on-chain abort. `num_sources`
- * (u8) and `intent` are coerced back to `number` — both are tiny.
+ * {@link WaterxSignedEnvelope} with the u64 fields decoded as `bigint`, exact
+ * (see {@link parseWithExactIntegers}). `num_sources` (u8) and `intent` are
+ * coerced back to `number` — both are tiny.
  */
 export declare function parseSignedEnvelope(text: string): WaterxSignedEnvelope;
-/** Narrow a `RuleUpdateData` to its `WaterxSignedEnvelope`, or `null`. */
+/**
+ * Parse a quote-center `/v1/quotes/leaves` response body (`{ leaves: [...] }`)
+ * into {@link WaterxSignedLeaf}s, u64s exact as `bigint`, rejecting a malformed
+ * leaf or proof element on the wire — before any PTB is touched.
+ */
+export declare function parseSignedLeaves(text: string): WaterxSignedLeaf[];
+/**
+ * Pull one enclave-signed batch envelope covering `symbols` — the fallback
+ * update shape AND the read executor's transport
+ * (`readQuoteCenterPrices` in `../read-prices.ts`). Public seam (WL-2345):
+ * consumers that need the raw envelope (BE prefetch caches, read planes)
+ * call this instead of re-rolling the fetch + intent/shape gate.
+ * `fellBackFrom`, when set, names the leaf-route failure that sent us here,
+ * so a deployment whose quote-center serves NEITHER route reports both
+ * statuses instead of only the second one.
+ */
+export declare function fetchWaterxSignedUpdate(endpoint: string, symbols: string[], fetchOpts?: FetchPolicy, fellBackFrom?: string): Promise<WaterxSignedEnvelope>;
+/** A leaf pull either produced leaves, or the route isn't there to pull from. */
+export type LeafPull = {
+    leaves: WaterxSignedLeaf[];
+} | {
+    unavailable: string;
+};
+/**
+ * Pull per-symbol signed Merkle leaves — the DEFAULT update-data shape (see the
+ * module header for why it beats the indivisible batch envelope on a trade path).
+ *
+ * Returns `{ unavailable }` on `404` — and ONLY on 404, the one status that
+ * means "this route isn't here": a quote-center older than `/v1/quotes/leaves`
+ * has no handler registered for the path. That is the version-skew case the
+ * caller answers by falling back to the batch envelope, so the SDK and the
+ * quote-center can be deployed in either order.
+ *
+ * Everything else THROWS rather than falling back, INCLUDING 5xx (`501` among
+ * them — `fetchWithPolicy` classifies every 5xx as retryable and has already
+ * spent its retry budget by the time one surfaces here). A degraded or
+ * unreachable quote-center would fail the envelope route the same way — same
+ * service, same enclave behind it — so falling back would only double the
+ * latency of an already-failing money-path build, and would report an outage as
+ * a version skew.
+ *
+ * A 404 can ALSO mean "unknown symbol" (the quote-center 404s a symbol missing
+ * from its feed registry). That is config drift between this SDK's `feeds` and
+ * the quote-center's registry, and the fallback surfaces it honestly: the
+ * envelope route 404s on the same symbol, and its error names both attempts.
+ *
+ * Public seam (WL-2345): consumers holding per-symbol leaves (BE prefetch
+ * caches) pull through this instead of re-rolling the fetch + parse gate.
+ */
+export declare function fetchWaterxSignedLeaves(endpoint: string, symbols: string[], fetchOpts?: FetchPolicy): Promise<LeafPull>;
+/**
+ * The quote-center enclave signs at most this many symbols per request
+ * (`MAX_BATCH_SIZE` in `quote-service`). Over the cap it answers a
+ * non-retryable 400.
+ */
+export declare const WATERX_MAX_BATCH_SYMBOLS = 32;
+/**
+ * Narrow a `RuleUpdateData` to its per-symbol {@link WaterxSignedLeaf}s, or
+ * `null` when it carries a batch envelope instead (the fallback shape).
+ */
+export declare function waterxLeavesOf(data: RuleUpdateData): readonly WaterxSignedLeaf[] | null;
+/**
+ * Narrow a `RuleUpdateData` to its `WaterxSignedEnvelope`, or `null` when it
+ * carries per-symbol leaves instead (the default shape).
+ */
 export declare function waterxEnvelopeOf(data: RuleUpdateData): WaterxSignedEnvelope | null;
+/**
+ * `waterx_rule::collect_single_with_proof(collector, config, clock,
+ * enclave_config, enclave, timestamp_ms, item, proof, sig)` — the DEFAULT feed
+ * leg. Rebuilds ONE item in-PTB and hands it over with its Merkle proof; on-chain
+ * the leaf is hashed, folded through the proof, and the enclave's signature over
+ * the resulting root is verified before the price reaches the collector.
+ *
+ * Cost is what makes this the default: one item + `proof.length` 32-byte hashes
+ * (~log2 of the snapshot width — 4 to 5 for the 29-feed mainnet registry),
+ * against {@link feedWaterxRule}'s obligation to rebuild every item the batch
+ * signature covers.
+ *
+ * Abort vs abstain is identical to the batch path (see the module header): a
+ * mismatched root, a bad signature, a future signed timestamp, or a config
+ * mismatch ABORTS; a freshness miss or a replayed signed timestamp abstains. One
+ * extra abort of its own — `ECollectorSymbolMismatch` if the leaf's symbol isn't
+ * the collector's — which `aggregateTicker` prevents by construction, since it
+ * looks the leaf up BY the ticker it just built the collector for.
+ */
+export declare function feedWaterxRuleWithProof(tx: Transaction, host: OracleHost, collector: TransactionArgument, leaf: WaterxSignedLeaf): void;
 /**
  * `waterx_rule::collect_batch_latest(collector, config, clock, enclave_config,
- * enclave, timestamp_ms, payload, sig)` — rebuild the enclave-signed batch
- * payload in-PTB (`new_batch_payload` + one `new_batch_item`/`push_batch_item`
- * per item, the exact shape the enclave signed) and contribute the price for
- * `collector.symbol()` to the collector. One collect call re-verifies the batch
- * signature and picks this collector's symbol out of the batch; on-chain it
- * abstains (records `none`) when the symbol is stale or absent from the batch,
- * but ABORTS `EReplayedSignature` when the symbol's signed timestamp was
- * already accepted (per-symbol high-water mark, audit F-014) — see the module
- * header for the concurrent-build consequence.
+ * enclave, timestamp_ms, payload, sig)` — the FALLBACK feed leg, for a
+ * quote-center with no leaf route (and for callers that hold a whole batch).
+ * Rebuilds the enclave-signed batch payload in-PTB (`new_batch_payload` + one
+ * `new_batch_item`/`push_batch_item` per item, the exact shape the enclave
+ * signed) and contributes the price for `collector.symbol()` to the collector.
+ *
+ * Every item must be rebuilt, not just this collector's: the signature covers
+ * `BCS(IntentMessage)` over the whole vector, so a missing item is a failed
+ * verify. That is the cost {@link feedWaterxRuleWithProof} exists to avoid.
+ *
+ * On-chain it abstains (records `none`) when the symbol is stale, absent from the
+ * batch, or already recorded at this signed timestamp; it ABORTS on a bad
+ * signature, a signed timestamp ahead of the `Clock`, or a config mismatch.
  */
 export declare function feedWaterxRule(tx: Transaction, host: OracleHost, collector: TransactionArgument, envelope: WaterxSignedEnvelope): void;
+/**
+ * THE quote-center route ladder, owned by the rule that owns the protocol:
+ * pull per-symbol Merkle leaves (the default), and fall back to one batch
+ * envelope only when this quote-center has no leaf route (see
+ * {@link fetchWaterxSignedLeaves} for exactly which statuses mean that, and
+ * why nothing else falls back).
+ *
+ * Both the write path ({@link pullWaterxData}, which layers coverage policy on
+ * top) and the READ executor (`readQuoteCenterPrices` in `../read-prices.ts`,
+ * which only decodes prices) go through here, so which route wins, which
+ * status falls back, and how the fallback context is threaded are stated once.
+ * `items` is the flat symbol-bearing view both callers actually want —
+ * `WaterxSignedLeaf extends WaterxBatchItem`, so leaves widen to it for free —
+ * while `payload` keeps the shape-specific form the on-chain feed leg needs.
+ */
+export declare function pullWaterxQuotes(endpoint: string, symbols: string[], fetchOpts?: FetchPolicy): Promise<{
+    route: "leaves" | "envelope";
+    payload: WaterxUpdatePayload;
+    items: readonly WaterxBatchItem[];
+}>;
 export declare const WaterxRule: PriceUpdateRule;
+/**
+ * Coverage-policy seam over the rule's quote-center pull (WL-2345): fetch
+ * signed waterx update data for `tickers` with the caller choosing what a
+ * coverage gap means.
+ *
+ * - `coverage: "strict"` (default) — exactly `WaterxRule.fetchUpdateData`:
+ *   every requested ticker must be config-listed AND served, or the fetch
+ *   THROWS (`assertCoverage`); `missing` is always `[]`. Trade-path semantics
+ *   — `refreshOraclePrices` keeps consuming the rule's own strict fetch, so
+ *   `aggregate.ts`'s uncarried-ticker throw (04117a1) still can't be reached
+ *   by a payload that under-covers its group.
+ * - `coverage: "partial"` — universe-prefetch semantics (a BE cache warming
+ *   every known ticker at once): a ticker with no `waterx_rule.feeds` entry,
+ *   or one the quote-center response does not serve, lands in `missing`
+ *   instead of throwing, and `data` covers the rest. On the leaf route the
+ *   payload is the covering leaf SUBSET; on the envelope route the envelope
+ *   is kept iff it covers ≥1 requested ticker (it is indivisible — an
+ *   envelope serving none is `data: null`). `data: null` + all-missing when
+ *   nothing is servable.
+ *
+ * Consumers must not hand a partial payload to a build for tickers in
+ * `missing` — those tickers are simply not servable by waterx right now (log
+ * the gap; the chain's weight tables decide whether that starves anything).
+ */
+export declare function fetchWaterxUpdateData(host: OracleHost, tickers: string[], opts?: {
+    coverage?: "strict" | "partial";
+}): Promise<{
+    data: RuleUpdateData;
+    missing: string[];
+}>;