@waterx/sdk 4.3.3 → 5.0.0

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

@@ -40,9 +40,14 @@ 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";
-/** Intent the quote-center signs a whole BATCH payload under — 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
@@ -56,12 +61,11 @@ export declare const BATCH_PRICE_INTENT = 1;
 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
@@ -73,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
@@ -165,6 +190,56 @@ export declare function parseSignedEnvelope(text: string): WaterxSignedEnvelope;
  * 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).
@@ -212,4 +287,54 @@ export declare function feedWaterxRuleWithProof(tx: Transaction, host: OracleHos
  * 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[];
+}>;