@waterx/sdk 3.1.1 → 4.0.1

package/dist/src/oracle/price-update-rule.d.ts

@@ -0,0 +1,180 @@
+/**
+ * `PriceUpdateRule` — the strategy port for one oracle rule generation: fetch
+ * its off-chain update payload and emit the PTB calls that verify/push that
+ * update on-chain (e.g. Pyth's wormhole-verify + price-feed-update block).
+ * Feeding the refreshed price into an oracle `PriceCollector` is a separate
+ * step that stays in `aggregate.ts` — this port covers fetch + verify/push
+ * only (`buildUpdateCalls` may hand the feed step a PTB value via
+ * {@link RuleUpdateHandle}). Implementations: `PythCoreRule` (Hermes VAA) and
+ * `PythLazerRule` (Lazer signed updates), with `WaterxRule` (ed25519) to
+ * follow. `ConstantRule` and `SupraRule` do NOT implement this port — they
+ * remain plain collector-feed helpers wired directly into `aggregate.ts`.
+ *
+ * This file defines the port only — routing IS wired: `aggregate.ts`'s
+ * `refreshOraclePrices` selects the concrete rule per `host.oracleSource` via
+ * `rule-registry.ts`, then drives fetch + `buildUpdateCalls` through this
+ * port; `aggregate.ts` stays the sole orchestrator.
+ */
+import type { Transaction, TransactionArgument } from "@mysten/sui/transactions";
+import type { OracleHost } from "./host.ts";
+import type { OracleFeeSource, PythCache } from "./pyth.ts";
+export type PriceUpdateRuleKind = "pyth_rule" | "pyth_lazer_rule" | "supra_rule" | "constant_rule" | "waterx_rule";
+/**
+ * The subset of `PriceUpdateRuleKind`s selectable via a client's `oracleSource`
+ * create option (see `OracleHost.oracleSource`) — i.e. rules that can serve as
+ * the on-chain price *update* leg `refreshOraclePrices` runs before aggregating.
+ * `supra_rule` and `constant_rule` are auxiliary rules fed alongside whichever
+ * source is selected (see `aggregateTicker`), not sources themselves;
+ * `waterx_rule` has no `PriceUpdateRule` implementation yet. The SDK never
+ * reads `process.env` — consumers resolve their own env var to this type.
+ */
+export type OracleSource = "pyth_rule" | "pyth_lazer_rule";
+/**
+ * Off-chain payload fetched by a rule, tagged by `kind` so a caller holding
+ * several rules' results can tell them apart. `payload` is `unknown` here —
+ * each rule implementation narrows it to its own shape (e.g. `PythCoreRule`'s
+ * `{ updates: Uint8Array[]; feedIds: string[] }`). `null` for rules with no
+ * off-chain fetch (e.g. `ConstantRule`) or when there is nothing to fetch.
+ */
+export type RuleUpdateData = {
+    kind: PriceUpdateRuleKind;
+    payload: unknown;
+} | null;
+/**
+ * Shared null → kind → shape guard ladder for a `PriceUpdateRule.buildUpdateCalls`
+ * payload — every rule's `buildUpdateCalls` needs the exact same three checks,
+ * in the exact same order, before it can trust `data.payload`:
+ *
+ * 1. `data === null` passes straight through as `null` — the no-op case (an
+ *    empty ticker list upstream produced nothing to build).
+ * 2. `data.kind !== kind` throws BEFORE the shape check runs. This order is
+ *    load-bearing, not stylistic: two rules' payloads can share an identical
+ *    shape (e.g. Pyth Core's `{ updates, feedIds }` also satisfies a
+ *    hypothetical same-shaped rule), so checking shape first would let a
+ *    wrong-kind payload silently pass as this rule's own.
+ * 3. `!isShape(data.payload)` throws for a same-`kind` payload whose shape
+ *    doesn't match this rule's own (e.g. a hand-built test double).
+ *
+ * Returns `data.payload` narrowed to `T` once both checks pass.
+ *
+ * @param data - The `RuleUpdateData` handed to `buildUpdateCalls`.
+ * @param kind - This rule's own {@link PriceUpdateRuleKind} — the only `kind`
+ *   `data` may carry past step 2.
+ * @param isShape - Type predicate narrowing `data.payload` to `T`.
+ * @param shapeDescription - Human-readable shape, quoted verbatim into the
+ *   shape-mismatch error (e.g. `"{ updates: Uint8Array[]; feedIds: string[] }"`).
+ */
+export declare function assertRuleUpdateData<T>(data: RuleUpdateData, kind: PriceUpdateRuleKind, isShape: (payload: unknown) => payload is T, shapeDescription: string): T | null;
+/**
+ * PTB value handle a rule's {@link PriceUpdateRule.buildUpdateCalls} may
+ * return when its collector-feed leg needs a value produced by the update leg
+ * *within the same PTB*. Pyth Core needs none (its feed leg reads the shared
+ * `PriceInfoObject` the update leg refreshed), so it returns `void`. The Lazer
+ * rule returns the verified `pyth_lazer::update::Update` result — one
+ * signature verification covers every feed in the payload, and
+ * `pyth_lazer_rule::feed` takes it by reference per ticker (see
+ * `aggregateTicker`'s `lazerUpdate` arg).
+ */
+export type RuleUpdateHandle = {
+    readonly kind: "pyth_lazer_rule";
+    /** Result of `pyth_lazer::parse_and_verify_le_ecdsa_update` in this PTB. */
+    readonly update: TransactionArgument;
+};
+/**
+ * Options for {@link PriceUpdateRule.buildUpdateCalls}. Mirrors
+ * `buildPythPriceUpdateCalls` / `updatePythPrices`'s own opts shape in
+ * `./pyth.ts` — `cache` shares on-chain Pyth state reads across builders;
+ * `feeSource` is the single {@link OracleFeeSource} already resolved by the
+ * caller (see its own doc for where/how). Both fields are Pyth-Core-specific
+ * mechanics; `refreshOraclePrices` passes the same `BuildUpdateOpts` to every
+ * rule uniformly, so a non-Pyth-Core rule (e.g. `PythLazerRule`, which
+ * charges no update fee) simply ignores whichever fields it has no use for.
+ */
+export interface BuildUpdateOpts {
+    readonly cache?: PythCache;
+    readonly feeSource?: OracleFeeSource;
+}
+/**
+ * Injectable update-data cache seam for `refreshOraclePrices` (`aggregate.ts`).
+ * A BE consumer (e.g. a prefetch cache that polls Hermes/Lazer out-of-band and
+ * keeps a hot in-memory/Redis entry per source) implements this and passes it
+ * as `refreshOraclePrices`'s `updateDataProvider` opt; the SDK itself never
+ * implements one. `get` is checked before the rule's own live
+ * `fetchUpdateData` for that group of tickers — a `null` return means "no
+ * cached data, fetch live" (mirrors {@link RuleUpdateData}'s own `null`
+ * variant: there is no separate signal for "the cache legitimately has
+ * nothing" vs "go fetch live", they're the same instruction to the caller).
+ *
+ * A non-null hit MAY be a payload for a WIDER ticker set than `tickers` — a
+ * provider is free to cache one whole-universe payload per source and return
+ * it verbatim; `refreshOraclePrices` narrows it down to exactly the requested
+ * tickers via the rule's {@link PriceUpdateRule.narrowUpdateData} before use,
+ * so an implementer need not (and should not) subset it by hand. The only
+ * hard requirement on a hit is that its `kind` matches the requested
+ * `source`'s rule — a mismatch is a routing bug and throws.
+ */
+export interface UpdateDataProvider {
+    get(source: OracleSource, tickers: string[]): Promise<RuleUpdateData | null>;
+}
+export interface PriceUpdateRule {
+    readonly kind: PriceUpdateRuleKind;
+    /**
+     * `true` when this rule's on-chain update leg charges a per-update fee
+     * that must be paid from either a sponsor fund or `tx.gas` (Pyth Core:
+     * `true`, via `pyth::update_single_price_feed`'s `base_update_fee`).
+     * `false` for a fee-free update leg (Lazer: signature verification only,
+     * no `Coin` argument). `refreshOraclePrices` (`aggregate.ts`) reads this
+     * BEFORE fetching any group's off-chain payload — for every group whose
+     * rule sets it `true`, `opts.feeSource` must already be resolved, or the
+     * whole call throws `OracleFeeSourceUnavailable` before
+     * any group builds (mixed-shape atomicity: a fee-free group ordered
+     * ahead of a fee-charging one in the same PTB must never get to mutate
+     * `tx` while the fee-charging group is left unpayable). A referential
+     * check against a specific rule instance (e.g. `=== PythCoreRule`) would
+     * silently stop protecting a future fee-charging rule, or a test double
+     * standing in for one — this field is the honest, extensible signal.
+     */
+    readonly requiresFeeSource: boolean;
+    /** Tickers this rule can serve in this environment (from config feeds + enabled). */
+    supportedTickers(host: OracleHost): string[];
+    /**
+     * Fetch the off-chain payload for these tickers (no-op rules return null).
+     * `tickers` must already be a subset of {@link supportedTickers} — an
+     * unsupported ticker's feed lookup throws and that throw propagates
+     * uncaught; callers pre-filter via `supportedTickers`, this method does not
+     * re-validate.
+     */
+    fetchUpdateData(host: OracleHost, tickers: string[]): Promise<RuleUpdateData>;
+    /**
+     * Narrow a payload previously produced by {@link fetchUpdateData} — typically
+     * for a superset of tickers (e.g. a consumer's whole-universe prefetch cache)
+     * — down to exactly `tickers`, without any re-fetch. Each rule owns its
+     * payload's divisibility semantics, so consumers must never subset a payload
+     * themselves (that knowledge branching on `kind` in a consumer is exactly the
+     * altitude violation this method removes):
+     *
+     * - A non-null result MUST be valid {@link buildUpdateCalls} input covering
+     *   exactly `tickers` — a divisible payload (Pyth Core's per-feed entries)
+     *   returns a subset; an indivisible payload (Lazer's single signed message)
+     *   returns the whole payload iff every requested ticker is covered.
+     * - A ticker this payload cannot serve → `null` (miss), NEVER a silent
+     *   partial. `null` mirrors {@link UpdateDataProvider.get}'s convention: the
+     *   caller falls back to a live {@link fetchUpdateData} for those tickers.
+     * - An empty `tickers` list → `null`, mirroring {@link fetchUpdateData}'s own
+     *   empty-list convention (nothing to build); `data === null` → `null`.
+     * - `data` must be this rule's own payload: kind/shape are enforced via
+     *   {@link assertRuleUpdateData}, so a wrong-`kind` payload throws (a routing
+     *   bug), it does not miss.
+     */
+    narrowUpdateData(host: OracleHost, data: RuleUpdateData, tickers: string[]): RuleUpdateData;
+    /**
+     * Emit verify/update moveCalls + any per-rule setup into the PTB. Returns a
+     * {@link RuleUpdateHandle} when the rule's collector-feed leg needs a PTB
+     * value from this step (Lazer's verified `Update`); rules whose feed leg
+     * reads shared on-chain objects return `void`. Takes no `tickers` param —
+     * every implementation derives everything it needs from `data.payload`
+     * (the tickers a group covers were already fixed when `fetchUpdateData`
+     * built that payload).
+     */
+    buildUpdateCalls(tx: Transaction, host: OracleHost, data: RuleUpdateData, opts?: BuildUpdateOpts): Promise<RuleUpdateHandle | void> | RuleUpdateHandle | void;
+}

package/dist/src/oracle/price-update-rule.js

@@ -0,0 +1,53 @@
+/**
+ * `PriceUpdateRule` — the strategy port for one oracle rule generation: fetch
+ * its off-chain update payload and emit the PTB calls that verify/push that
+ * update on-chain (e.g. Pyth's wormhole-verify + price-feed-update block).
+ * Feeding the refreshed price into an oracle `PriceCollector` is a separate
+ * step that stays in `aggregate.ts` — this port covers fetch + verify/push
+ * only (`buildUpdateCalls` may hand the feed step a PTB value via
+ * {@link RuleUpdateHandle}). Implementations: `PythCoreRule` (Hermes VAA) and
+ * `PythLazerRule` (Lazer signed updates), with `WaterxRule` (ed25519) to
+ * follow. `ConstantRule` and `SupraRule` do NOT implement this port — they
+ * remain plain collector-feed helpers wired directly into `aggregate.ts`.
+ *
+ * This file defines the port only — routing IS wired: `aggregate.ts`'s
+ * `refreshOraclePrices` selects the concrete rule per `host.oracleSource` via
+ * `rule-registry.ts`, then drives fetch + `buildUpdateCalls` through this
+ * port; `aggregate.ts` stays the sole orchestrator.
+ */
+/**
+ * Shared null → kind → shape guard ladder for a `PriceUpdateRule.buildUpdateCalls`
+ * payload — every rule's `buildUpdateCalls` needs the exact same three checks,
+ * in the exact same order, before it can trust `data.payload`:
+ *
+ * 1. `data === null` passes straight through as `null` — the no-op case (an
+ *    empty ticker list upstream produced nothing to build).
+ * 2. `data.kind !== kind` throws BEFORE the shape check runs. This order is
+ *    load-bearing, not stylistic: two rules' payloads can share an identical
+ *    shape (e.g. Pyth Core's `{ updates, feedIds }` also satisfies a
+ *    hypothetical same-shaped rule), so checking shape first would let a
+ *    wrong-kind payload silently pass as this rule's own.
+ * 3. `!isShape(data.payload)` throws for a same-`kind` payload whose shape
+ *    doesn't match this rule's own (e.g. a hand-built test double).
+ *
+ * Returns `data.payload` narrowed to `T` once both checks pass.
+ *
+ * @param data - The `RuleUpdateData` handed to `buildUpdateCalls`.
+ * @param kind - This rule's own {@link PriceUpdateRuleKind} — the only `kind`
+ *   `data` may carry past step 2.
+ * @param isShape - Type predicate narrowing `data.payload` to `T`.
+ * @param shapeDescription - Human-readable shape, quoted verbatim into the
+ *   shape-mismatch error (e.g. `"{ updates: Uint8Array[]; feedIds: string[] }"`).
+ */
+export function assertRuleUpdateData(data, kind, isShape, shapeDescription) {
+    if (!data)
+        return null;
+    if (data.kind !== kind) {
+        throw new Error(`assertRuleUpdateData: received a payload of kind '${data.kind}', expected '${kind}'`);
+    }
+    if (!isShape(data.payload)) {
+        throw new Error(`assertRuleUpdateData: received a '${kind}' payload with an unexpected shape ` +
+            `(expected ${shapeDescription})`);
+    }
+    return data.payload;
+}

package/dist/src/oracle/pyth.d.ts

@@ -14,6 +14,7 @@
  *   4. hot_potato_vector::destroy
  */
 import type { Transaction, TransactionArgument } from "@mysten/sui/transactions";
+import type { PythFetchPolicy } from "./config.ts";
 import type { OracleHost } from "./host.ts";
 type PriceTableInfo = {
     id: string;
@@ -29,24 +30,154 @@ export declare class PythCache {
     priceTableInfo?: PriceTableInfo;
     priceFeedObjectIdCache: Map<string, string | undefined>;
 }
-export declare function fetchPriceFeedsUpdateData(endpoint: string, priceIds: string[]): Promise<Uint8Array[]>;
+type FetchOpts = {
+    apiKey?: string;
+    fetch?: PythFetchPolicy;
+};
+/**
+ * How long a "this endpoint lacks feed X" verdict stays memoized. The verdict
+ * is a claim about *someone else's* deployment — a feed can be added to the
+ * catalog, an entitlement can be granted, a Pro plan can be upgraded — so it
+ * must expire rather than bind the whole process lifetime. Long enough that a
+ * genuinely-absent feed costs one discovery per window instead of one per
+ * build; short enough that a recovered endpoint self-heals without a restart.
+ */
+export declare const MISSING_FEED_MEMO_TTL_MS: number;
+/**
+ * Thrown when discovery concludes that an endpoint rejects EVERY requested
+ * feed id without a catalog vouching for that verdict. `instanceof`-able
+ * (mirrors `FetchPolicyError` / {@link OracleFeeSourceUnavailableError}).
+ *
+ * "All of them are missing" is the signature of an endpoint/credential fault —
+ * a wrong base path (the Pyth Pro `/hermes` prefix dropped), a changed route,
+ * a revoked or downgraded entitlement — not of N individually-absent feeds.
+ * Memoizing it would convert a loud, fixable misconfiguration into a silent
+ * permanent one: every id marked missing ⇒ `fetchPriceFeedsUpdateData` returns
+ * `[]` ⇒ `buildPythPriceUpdateCalls` throws "Hermes returned empty results",
+ * blaming Hermes for having no data, for the rest of the process's life. So
+ * this case writes NOTHING to the memo and throws instead; the next call
+ * re-probes and recovers on its own once the endpoint does.
+ *
+ * The message keeps the `Hermes price fetch failed: <status>` prefix on its
+ * first line — the documented contract downstream consumers string-match (see
+ * {@link fetchPriceFeedsUpdateData} and the e2e transient detector).
+ */
+export declare class HermesEndpointRejectedAllFeedsError extends Error {
+    readonly endpoint: string;
+    readonly requestedCount: number;
+    constructor(endpoint: string, requestedCount: number, catalogState: "unreadable" | "empty");
+}
+/**
+ * The subset of `feedIds` this `endpoint` is known to serve — i.e. minus any
+ * discovered to be absent within the last {@link MISSING_FEED_MEMO_TTL_MS}
+ * (see {@link fetchPriceFeedsUpdateData}). Callers building a
+ * `{ updates, feedIds }` payload use this to keep `feedIds` aligned with the
+ * feeds the fetch actually returned data for, so `buildPythPriceUpdateCalls`
+ * (one moveCall per feed id) never references a feed the accumulator blob
+ * doesn't cover.
+ *
+ * Expired entries are pruned here rather than on a timer: the memo is only
+ * ever consulted through this function, so a lazy sweep is both sufficient and
+ * free of a dangling interval in a library.
+ */
+export declare function endpointSupportedFeedIds(endpoint: string, feedIds: string[], apiKey?: string): string[];
+/** Test-only: forget everything learned about which feeds an endpoint lacks. */
+export declare function __resetMissingFeedCacheForTest(): void;
+/**
+ * Discovery-only entry for consumers that fetch Hermes THEMSELVES (e.g. a
+ * parsed latest-price reader) and just observed a whole-batch 404: resolves
+ * which ids the endpoint lacks, memoizes them (see {@link
+ * endpointSupportedFeedIds}), fetches NO survivor data. Without this, such a
+ * consumer's only way to populate the memo was calling {@link
+ * fetchPriceFeedsUpdateData} and discarding its accumulator blob — two full
+ * redundant transfers per cold discovery.
+ *
+ * @throws HermesEndpointRejectedAllFeedsError when the rejection looks
+ * endpoint-wide rather than per-feed — the caller's own 404 is then a
+ * misconfiguration to surface, not a set of feeds to quietly drop.
+ */
+export declare function probeMissingFeeds(endpoint: string, ids: string[], opts?: FetchOpts): Promise<void>;
+export declare function fetchPriceFeedsUpdateData(endpoint: string, priceIds: string[], opts?: FetchOpts): Promise<Uint8Array[]>;
+/**
+ * Resolved source for the Pyth Core on-chain update fee. Deliberately a
+ * closed two-variant union, not a `{ sponsorFund?, allowGasFee? }` pair — a
+ * caller can no longer construct the "both supplied" or "neither supplied
+ * but some other truthy flag" shapes that used to require a priority rule to
+ * disambiguate.
+ *
+ * Resolved exactly ONCE, at the edges (`wrapRequestAndExecute` and the WLP
+ * builders' equivalent in `perp/tx-builders/`) from config presence
+ * (`pyth_sponsor_rule` deployed → open a fund → `'sponsor'`) and the
+ * caller's ergonomic `allowGasFee` opt-in (→ `'gas'`), then threaded
+ * verbatim through `refreshOraclePrices` → `BuildUpdateOpts` →
+ * `PythCoreRule` → {@link buildPythPriceUpdateCalls}. The sponsor-beats-gas
+ * priority from the old two-flag design is now structural — whichever edge
+ * resolves this value decides once; no downstream layer re-derives or
+ * re-documents a priority because none of them ever see more than one
+ * candidate source.
+ */
+export type OracleFeeSource = {
+    readonly kind: "sponsor";
+    readonly fund: TransactionArgument;
+    readonly packageId: string;
+} | {
+    readonly kind: "gas";
+};
+/**
+ * Thrown when no {@link OracleFeeSource} is available for the Pyth update fee
+ * — from `buildPythPriceUpdateCalls`'s own per-call guard, or `aggregate.ts`'s
+ * hoisted `refreshOraclePrices` pre-check (see its docblock). `instanceof`-able
+ * (mirrors `FetchPolicyError` in `update-fetch.ts`) so a consumer — e.g. a BE
+ * integration wiring its own `allowGasFee` decision — can branch on the error
+ * type directly instead of string-matching `error.message`.
+ */
+export declare class OracleFeeSourceUnavailableError extends Error {
+    constructor();
+}
 /**
  * Append the on-chain Pyth update PTB block. Returns `PriceInfoObject` IDs
  * (one per `feedIds`, same order). After this you can feed `pyth_rule` per
  * ticker against the matching `PriceInfoObject` (see `rules/pyth-rule.ts`).
  *
- * If `sponsorFund` is provided, the per-feed update fee comes from the
- * sponsor pool (`pyth_sponsor_rule::split`) instead of `tx.gas`. Opening and
- * reimbursing that fund is the sponsor rule's job (`rules/sponsor.ts`); here we
- * only draw a fee coin from the already-open `fund` hot potato.
+ * `opts.feeSource` is resolved BEFORE any PTB mutation and is never silently
+ * defaulted — this function trusts whatever single {@link OracleFeeSource}
+ * it's handed, it does not choose between competing candidates:
+ *   - `{ kind: 'sponsor' }` → the per-feed update fee is drawn from the
+ *     sponsor pool (`pyth_sponsor_rule::split`) instead of `tx.gas`. Opening
+ *     and reimbursing that fund is the caller's job (`rules/sponsor.ts` /
+ *     `wrapRequestAndExecute`, which opens it whenever the client's config
+ *     has `pyth_sponsor_rule` deployed) — this function only draws a fee
+ *     coin from the already-open `fund` hot potato.
+ *   - `{ kind: 'gas' }` → the fee is drawn from `tx.gas` via `tx.splitCoins`.
+ *     Only safe in a non-sponsored context — Enoki-sponsored transactions
+ *     reject any `tx.gas` draw.
+ *   - `undefined` → throws `OracleFeeSourceUnavailable` instead of silently
+ *     drawing from `tx.gas` (the old default), which broke under Enoki and,
+ *     worse, could fail ON-CHAIN when the market's `request_checklist`
+ *     requires the `PythSponsorRule` witness that only a real sponsor fund
+ *     attaches.
+ *
+ * This function's own check runs AFTER `updates`/`feedIds` are already in
+ * hand, so for `updatePythPrices` (which fetches from Hermes, then calls
+ * straight into this function) the off-chain fetch has already completed by
+ * the time this throws — a wasted network call, never a stray PTB command.
+ * `refreshOraclePrices` avoids that waste entirely: it hoists an EQUIVALENT
+ * check ABOVE its off-chain fetch AND its per-group build loop (see its
+ * docblock in `aggregate.ts`), keyed on `PriceUpdateRule.requiresFeeSource`
+ * rather than waiting for a specific rule's fetch to complete — so for that
+ * route neither the network call NOR any PTB command happens before the
+ * throw. This function's own (later, per-call) guard alone could not
+ * provide that "before any group builds" guarantee in a mixed shape (e.g. a
+ * fee-free Lazer group ordered ahead of a Pyth Core fallback group in the
+ * same PTB) — `refreshOraclePrices`'s pre-check is what closes it.
  */
-export declare function buildPythPriceUpdateCalls(tx: Transaction, host: OracleHost, updates: Uint8Array[], feedIds: string[], cache?: PythCache, sponsorFund?: {
-    fund: TransactionArgument;
-    packageId: string;
+export declare function buildPythPriceUpdateCalls(tx: Transaction, host: OracleHost, updates: Uint8Array[], feedIds: string[], opts?: {
+    cache?: PythCache;
+    feeSource?: OracleFeeSource;
 }): Promise<string[]>;
 /** All-in-one: fetch from Hermes, append update calls. Returns PriceInfoObject IDs. */
-export declare function updatePythPrices(tx: Transaction, host: OracleHost, feedIds: string[], cache?: PythCache, sponsorFund?: {
-    fund: TransactionArgument;
-    packageId: string;
+export declare function updatePythPrices(tx: Transaction, host: OracleHost, feedIds: string[], opts?: {
+    cache?: PythCache;
+    feeSource?: OracleFeeSource;
 }): Promise<string[]>;
 export {};