@waterx/sdk 3.1.0 → 4.0.0

package/dist/cjs/src/oracle/config.d.ts

@@ -22,6 +22,24 @@ export interface PythRulePackage extends BasePackageEntry {
 export interface PythSponsorRulePackage extends BasePackageEntry {
     pyth_sponsor: string;
 }
+/**
+ * `pyth_lazer_rule` deployment entry — present in the deployed testnet
+ * `waterx-config` JSON. Read by `PythLazerRule` (`rules/pyth-lazer-rule.ts`):
+ * `feeds` for ticker support + integer feed-id resolution, `state` for the
+ * verify call, `published_at`/`config` for the per-ticker feed call.
+ *
+ * `enabled` mirrors the JSON field verbatim but MUST NOT be read for routing —
+ * which rule prices a ticker is decided solely by the client's `oracleSource`
+ * create option (see `OracleHost.oracleSource`), never by this flag or any
+ * other config value.
+ */
+export interface PythLazerRulePackage extends BasePackageEntry {
+    config: string;
+    state: string;
+    enabled?: boolean;
+    /** Oracle ticker → integer Pyth Lazer feed id (distinct id scheme from `pyth_rule`'s hex `feed_id`). */
+    feeds: Record<string, number>;
+}
 /** Per-ticker `constant_rule` feed entry (mirrors the `pyth_rule.feeds` shape). */
 export interface ConstantFeedEntry {
     /**
@@ -77,6 +95,8 @@ export interface WaterxOraclePackage extends BasePackageEntry {
 export interface OraclePackages {
     pyth_rule: PythRulePackage;
     pyth_sponsor_rule?: PythSponsorRulePackage;
+    /** See {@link PythLazerRulePackage} — typed only, not read for routing. */
+    pyth_lazer_rule?: PythLazerRulePackage;
     constant_rule?: WaterxConstantRulePackage;
     supra_rule?: SupraRulePackage;
     waterx_oracle: WaterxOraclePackage;
@@ -85,8 +105,91 @@ export interface PythInfraConfig {
     state_id: string;
     wormhole_state_id: string;
     hermes_endpoint: string;
+    /**
+     * Pyth Pro / Lazer access token (`Authorization: Bearer …`) for
+     * `PythLazerRule`'s signed-update fetch — Lazer is auth-first, so there is
+     * no keyless default. Optional: Pyth-Core-only deployments never need it.
+     * Consumers pass it through client config (`config.pyth`); the SDK never
+     * reads `process.env`. Absent when a lazer-routed fetch runs →
+     * `LazerApiKeyMissing` is thrown at fetch time. As of the Pyth Pro
+     * migration (post-2026-08-18, per
+     * https://docs.pyth.network/price-feeds/core/upgrade) this is ALSO required
+     * for `pyth_rule`'s Hermes fetch (`fetchPriceFeedsUpdateData`) — see
+     * `fetch` below.
+     */
+    api_key?: string;
+    /**
+     * Retry/timeout policy override for the Hermes (`fetchPriceFeedsUpdateData`)
+     * and Lazer (`PythLazerRule`) off-chain update fetches — see
+     * `fetchWithPolicy` (`./update-fetch.ts`) for the full policy (backoff,
+     * which statuses retry, Bearer attachment). Optional: both fetches default
+     * to `fetchWithPolicy`'s built-in defaults (15s timeout, 2 retries) when
+     * unset.
+     */
+    fetch?: {
+        timeoutMs?: number;
+        retries?: number;
+    };
 }
 export declare const PYTH_DEFAULTS: Record<Network, PythInfraConfig>;
+/**
+ * Which Pyth Core contract generation feeds `host.pyth` when the config JSON
+ * carries no explicit `pyth` override:
+ *
+ * - `'core'` (default) — the original contracts + keyless Hermes
+ *   ({@link PYTH_DEFAULTS}).
+ * - `'pro'` — the Pro-compatible upgraded contracts + the Hermes-compatible
+ *   endpoint ({@link PYTH_PRO_DEFAULTS}); pair with `pyth.api_key` after the
+ *   2026-08-18 cutover.
+ *
+ * Resolved once at client creation from the `pythGeneration` create option.
+ * Orthogonal to `oracleSource` — this flips the Pyth-Core *infra* (state ids
+ * + endpoint), not which `PriceUpdateRule` routes tickers.
+ */
+export type PythGeneration = "core" | "pro";
+/**
+ * Pyth **Pro-generation** Core-compatible infra — the post-2026-08-18
+ * contracts (cutover date per
+ * https://docs.pyth.network/price-feeds/core/upgrade) from Pyth's Core-Upgrade
+ * docs
+ * (https://docs.pyth.network/price-feeds/core/upgrade/contracts, Sui section;
+ * package revs `sui-pro-compatible-contract-mainnet` /
+ * `sui-pro-compatible-contract-testnet`). Selected via the client's
+ * `pythGeneration: 'pro'` create option; `config.pyth` still overrides
+ * wholesale (see `PerpClient`). All four state ids were verified on-chain
+ * (shared `state::State` objects under the docs' upgraded package ids).
+ *
+ * Kept as a second flat map beside {@link PYTH_DEFAULTS} rather than a nested
+ * `PYTH_INFRA[network][generation]` — `PYTH_DEFAULTS` is a published export
+ * with external consumers, so the smallest honest surface is an additive
+ * sibling (same deferral note as {@link LAZER_DEFAULTS}).
+ *
+ * The Hermes-compatible endpoint (`pyth.dourolabs.app/hermes`) serves the
+ * same REST surface as `hermes.pyth.network` but requires `pyth.api_key`
+ * (`Authorization: Bearer …`) after the cutover — see
+ * {@link PythInfraConfig.api_key}.
+ */
+export declare const PYTH_PRO_DEFAULTS: Record<Network, PythInfraConfig>;
+/**
+ * Pyth Lazer (Pyth Pro) external infra the `PythLazerRule` needs, by network.
+ * Mirrors {@link PYTH_DEFAULTS}: per-network constants for infrastructure Pyth
+ * operates (not part of the `waterx-config` JSON). A fuller `PYTH_INFRA`
+ * restructure is deferred — this stays a minimal map until then.
+ *
+ * - `endpoint` — Lazer HTTP API base; signed updates come from
+ *   `POST /v1/latest_price` (Bearer-authenticated). The service is
+ *   network-agnostic (one signed payload verifies on any chain that trusts the
+ *   Lazer signers), so both networks share the production host.
+ * - `verifier_package` — the Sui package carrying
+ *   `pyth_lazer::parse_and_verify_le_ecdsa_update`. Per-network: testnet is
+ *   still the original v1 publish; mainnet is the v2-upgraded package (which
+ *   still exposes the v1 entry `pyth_lazer_rule` binds). Values mirror the
+ *   contract repo's `pyth_lazer_rule/Move.toml` published-at pins.
+ */
+export declare const LAZER_DEFAULTS: Record<Network, {
+    endpoint: string;
+    verifier_package: string;
+}>;
 /**
  * The narrow config shape the oracle/refresh code needs. `WaterXConfig`
  * (the perp line's full config) is assignable to this, so `PerpClient` satisfies

package/dist/cjs/src/oracle/config.js

@@ -11,7 +11,7 @@
  * mirrors the earlier account-config hoist.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PYTH_DEFAULTS = void 0;
+exports.LAZER_DEFAULTS = exports.PYTH_PRO_DEFAULTS = exports.PYTH_DEFAULTS = void 0;
 exports.PYTH_DEFAULTS = {
     MAINNET: {
         state_id: "0x1f9310238ee9298fb703c3419030b35b22bb1cc37113e3bb5007c99aec79e5b8",
@@ -24,3 +24,66 @@ exports.PYTH_DEFAULTS = {
         hermes_endpoint: "https://hermes-beta.pyth.network",
     },
 };
+/**
+ * Pyth **Pro-generation** Core-compatible infra — the post-2026-08-18
+ * contracts (cutover date per
+ * https://docs.pyth.network/price-feeds/core/upgrade) from Pyth's Core-Upgrade
+ * docs
+ * (https://docs.pyth.network/price-feeds/core/upgrade/contracts, Sui section;
+ * package revs `sui-pro-compatible-contract-mainnet` /
+ * `sui-pro-compatible-contract-testnet`). Selected via the client's
+ * `pythGeneration: 'pro'` create option; `config.pyth` still overrides
+ * wholesale (see `PerpClient`). All four state ids were verified on-chain
+ * (shared `state::State` objects under the docs' upgraded package ids).
+ *
+ * Kept as a second flat map beside {@link PYTH_DEFAULTS} rather than a nested
+ * `PYTH_INFRA[network][generation]` — `PYTH_DEFAULTS` is a published export
+ * with external consumers, so the smallest honest surface is an additive
+ * sibling (same deferral note as {@link LAZER_DEFAULTS}).
+ *
+ * The Hermes-compatible endpoint (`pyth.dourolabs.app/hermes`) serves the
+ * same REST surface as `hermes.pyth.network` but requires `pyth.api_key`
+ * (`Authorization: Bearer …`) after the cutover — see
+ * {@link PythInfraConfig.api_key}.
+ */
+exports.PYTH_PRO_DEFAULTS = {
+    MAINNET: {
+        state_id: "0x03719fae774ddab3cfcaa53bbc046f0cbe21410019b6280811bf3f9f4b05839d",
+        wormhole_state_id: "0xdbca52b9fb4f712e25f61f974586d93ac541bcf8389564f0323bb07215168b5c",
+        hermes_endpoint: "https://pyth.dourolabs.app/hermes",
+    },
+    TESTNET: {
+        state_id: "0x3c48fe392912de6c18087a2b3f5fdbfbfdb4598e180947feff1f12f8e9ea073e",
+        wormhole_state_id: "0x750da8e6d16b6a363a39fe2eaa8295ac224a1e6fce4e47b58845e2e8746164f0",
+        hermes_endpoint: "https://pyth.dourolabs.app/hermes",
+    },
+};
+// ============================================================================
+// Pyth Lazer — external infra, defaults by network
+// ============================================================================
+/**
+ * Pyth Lazer (Pyth Pro) external infra the `PythLazerRule` needs, by network.
+ * Mirrors {@link PYTH_DEFAULTS}: per-network constants for infrastructure Pyth
+ * operates (not part of the `waterx-config` JSON). A fuller `PYTH_INFRA`
+ * restructure is deferred — this stays a minimal map until then.
+ *
+ * - `endpoint` — Lazer HTTP API base; signed updates come from
+ *   `POST /v1/latest_price` (Bearer-authenticated). The service is
+ *   network-agnostic (one signed payload verifies on any chain that trusts the
+ *   Lazer signers), so both networks share the production host.
+ * - `verifier_package` — the Sui package carrying
+ *   `pyth_lazer::parse_and_verify_le_ecdsa_update`. Per-network: testnet is
+ *   still the original v1 publish; mainnet is the v2-upgraded package (which
+ *   still exposes the v1 entry `pyth_lazer_rule` binds). Values mirror the
+ *   contract repo's `pyth_lazer_rule/Move.toml` published-at pins.
+ */
+exports.LAZER_DEFAULTS = {
+    MAINNET: {
+        endpoint: "https://pyth-lazer.dourolabs.app",
+        verifier_package: "0xefbfd064480777699fd9c557a5804d72ace7bc82661fdc8d1f1a44ea6d92ee10",
+    },
+    TESTNET: {
+        endpoint: "https://pyth-lazer.dourolabs.app",
+        verifier_package: "0xf5bd2141967507050a91b58de3d95e77c432cd90d1799ee46effc27430a68c21",
+    },
+};

package/dist/cjs/src/oracle/host.d.ts

@@ -8,14 +8,27 @@
  * clause, and a future `PredictClient` (or a test double) can too.
  */
 import type { SuiGrpcClient } from "@mysten/sui/grpc";
+import type { Network } from "../constants.ts";
 import type { OracleConfig, PythInfraConfig } from "./config.ts";
+import type { OracleSource } from "./price-update-rule.ts";
 export interface OracleHost {
+    /** Sui network this client targets — selects per-network external-infra defaults (e.g. `LAZER_DEFAULTS`). */
+    readonly network: Network;
     /** Oracle slice of the canonical `waterx-config` JSON (rule packages + per-ticker feeds). */
     readonly config: OracleConfig;
     /** External Pyth/Wormhole/Hermes infra (network default, overridable via config). */
     readonly pyth: PythInfraConfig;
     /** gRPC client for the on-chain reads the Pyth update path needs. */
     readonly grpcClient: SuiGrpcClient;
+    /**
+     * Client-selected oracle rule source for `refreshOraclePrices`'s on-chain
+     * update leg — resolved at client creation from the `oracleSource` create
+     * option (default `'pyth_rule'`). Routing is driven by this value ALONE:
+     * never by a config JSON `enabled` flag (e.g. a future `pyth_lazer_rule.enabled`)
+     * and never by `process.env` — the SDK never reads it; consumers (BE/FE) wire
+     * this option from their own env var.
+     */
+    readonly oracleSource: OracleSource;
     /** True when `ticker` is priced by `constant_rule`. */
     isConstantTicker(ticker: string): boolean;
     /** The `supra_rule` config when deployed, enabled, and fully wired; else `undefined`. */

package/dist/cjs/src/oracle/index.d.ts

@@ -2,15 +2,29 @@
  * Oracle module — the single source of truth for price freshness.
  *
  * Layering (no cross-imports between siblings except via `aggregate.ts`):
- *   - `host.ts`     — `OracleHost`, the narrow client slice this module reads.
- *   - `pyth.ts`     — Pyth as a price source: Hermes REST + on-chain update PTB.
- *   - `rules/*`     — one file per oracle rule (pyth / supra / constant / sponsor).
- *   - `aggregate.ts`— the orchestrator that feeds rules into a collector + aggregates.
+ *   - `host.ts`             — `OracleHost`, the narrow client slice this module reads.
+ *   - `update-fetch.ts`     — `fetchWithPolicy`, the shared retry/timeout/Bearer resilience
+ *                             wrapper every off-chain oracle (and config) fetch goes through.
+ *   - `pyth.ts`             — Pyth as a price source: Hermes REST + on-chain update PTB.
+ *   - `price-update-rule.ts`— `PriceUpdateRule`, the fetch/build strategy port a rule
+ *                             implements; `rule-registry.ts` + `aggregate.ts` wire
+ *                             routing across rules.
+ *   - `rules/*`             — one file per oracle rule (pyth / supra / constant / sponsor).
+ *   - `aggregate.ts`        — the orchestrator that feeds rules into a collector + aggregates.
  *
  * `pyth.ts` deliberately imports NO rule package — Pyth-the-source and the
  * rules that consume it are separate concerns.
  */
 export type { OracleHost } from "./host.ts";
-export { PythCache, fetchPriceFeedsUpdateData, buildPythPriceUpdateCalls, updatePythPrices, } from "./pyth.ts";
+export { FetchPolicyError } from "./update-fetch.ts";
+export type { FetchPolicy } from "./update-fetch.ts";
+export { PythCache, fetchPriceFeedsUpdateData, buildPythPriceUpdateCalls, updatePythPrices, OracleFeeSourceUnavailableError, } from "./pyth.ts";
+export type { OracleFeeSource } from "./pyth.ts";
+export type { PriceUpdateRule, PriceUpdateRuleKind, RuleUpdateData, RuleUpdateHandle, BuildUpdateOpts, OracleSource, UpdateDataProvider, } from "./price-update-rule.ts";
+export { PythCoreRule } from "./rules/pyth-core-rule.ts";
+export type { PythCoreUpdatePayload } from "./rules/pyth-core-rule.ts";
+export { PythLazerRule, LazerApiKeyMissingError } from "./rules/pyth-lazer-rule.ts";
+export type { PythLazerUpdatePayload } from "./rules/pyth-lazer-rule.ts";
+export { OracleSourceNotImplementedError } from "./rule-registry.ts";
 export { aggregateTicker, aggregateTickerWithPyth, aggregateTickerWithConstant, refreshOraclePrices, } from "./aggregate.ts";
 export { openPythSponsorFund, reimbursePythSponsor } from "./rules/sponsor.ts";

package/dist/cjs/src/oracle/index.js

@@ -3,22 +3,56 @@
  * Oracle module — the single source of truth for price freshness.
  *
  * Layering (no cross-imports between siblings except via `aggregate.ts`):
- *   - `host.ts`     — `OracleHost`, the narrow client slice this module reads.
- *   - `pyth.ts`     — Pyth as a price source: Hermes REST + on-chain update PTB.
- *   - `rules/*`     — one file per oracle rule (pyth / supra / constant / sponsor).
- *   - `aggregate.ts`— the orchestrator that feeds rules into a collector + aggregates.
+ *   - `host.ts`             — `OracleHost`, the narrow client slice this module reads.
+ *   - `update-fetch.ts`     — `fetchWithPolicy`, the shared retry/timeout/Bearer resilience
+ *                             wrapper every off-chain oracle (and config) fetch goes through.
+ *   - `pyth.ts`             — Pyth as a price source: Hermes REST + on-chain update PTB.
+ *   - `price-update-rule.ts`— `PriceUpdateRule`, the fetch/build strategy port a rule
+ *                             implements; `rule-registry.ts` + `aggregate.ts` wire
+ *                             routing across rules.
+ *   - `rules/*`             — one file per oracle rule (pyth / supra / constant / sponsor).
+ *   - `aggregate.ts`        — the orchestrator that feeds rules into a collector + aggregates.
  *
  * `pyth.ts` deliberately imports NO rule package — Pyth-the-source and the
  * rules that consume it are separate concerns.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.reimbursePythSponsor = exports.openPythSponsorFund = exports.refreshOraclePrices = exports.aggregateTickerWithConstant = exports.aggregateTickerWithPyth = exports.aggregateTicker = exports.updatePythPrices = exports.buildPythPriceUpdateCalls = exports.fetchPriceFeedsUpdateData = exports.PythCache = void 0;
-// Pyth source
+exports.reimbursePythSponsor = exports.openPythSponsorFund = exports.refreshOraclePrices = exports.aggregateTickerWithConstant = exports.aggregateTickerWithPyth = exports.aggregateTicker = exports.OracleSourceNotImplementedError = exports.LazerApiKeyMissingError = exports.PythLazerRule = exports.PythCoreRule = exports.OracleFeeSourceUnavailableError = exports.updatePythPrices = exports.buildPythPriceUpdateCalls = exports.fetchPriceFeedsUpdateData = exports.PythCache = exports.FetchPolicyError = void 0;
+// Shared fetch resilience wrapper — `FetchPolicyError` is re-exported (not
+// just the type) so a consumer (e.g. a BE prefetch cache) can `instanceof`
+// it off the failure `fetchPriceFeedsUpdateData` / `PythLazerRule` /
+// `loadConfig` surface, without a deep import of `./update-fetch.ts`.
+// `fetchWithPolicy` itself stays module-internal (no external caller yet).
+var update_fetch_ts_1 = require("./update-fetch.js");
+Object.defineProperty(exports, "FetchPolicyError", { enumerable: true, get: function () { return update_fetch_ts_1.FetchPolicyError; } });
+// Pyth source — `OracleFeeSourceUnavailableError` is re-exported (not just
+// the type) for the same `instanceof` reason as `FetchPolicyError` above: a
+// consumer of `buildPythPriceUpdateCalls` / `updatePythPrices` /
+// `refreshOraclePrices` can branch on the fee-source failure directly.
 var pyth_ts_1 = require("./pyth.js");
 Object.defineProperty(exports, "PythCache", { enumerable: true, get: function () { return pyth_ts_1.PythCache; } });
 Object.defineProperty(exports, "fetchPriceFeedsUpdateData", { enumerable: true, get: function () { return pyth_ts_1.fetchPriceFeedsUpdateData; } });
 Object.defineProperty(exports, "buildPythPriceUpdateCalls", { enumerable: true, get: function () { return pyth_ts_1.buildPythPriceUpdateCalls; } });
 Object.defineProperty(exports, "updatePythPrices", { enumerable: true, get: function () { return pyth_ts_1.updatePythPrices; } });
+Object.defineProperty(exports, "OracleFeeSourceUnavailableError", { enumerable: true, get: function () { return pyth_ts_1.OracleFeeSourceUnavailableError; } });
+// Pyth Core rule (PriceUpdateRule wrapper over the Pyth source above)
+var pyth_core_rule_ts_1 = require("./rules/pyth-core-rule.js");
+Object.defineProperty(exports, "PythCoreRule", { enumerable: true, get: function () { return pyth_core_rule_ts_1.PythCoreRule; } });
+// Pyth Lazer rule (signed-update generation; `feedLazerRule` stays internal to `aggregate.ts`)
+// `LazerApiKeyMissingError` is re-exported (not just the type) for the same
+// `instanceof` reason as `OracleFeeSourceUnavailableError` above.
+var pyth_lazer_rule_ts_1 = require("./rules/pyth-lazer-rule.js");
+Object.defineProperty(exports, "PythLazerRule", { enumerable: true, get: function () { return pyth_lazer_rule_ts_1.PythLazerRule; } });
+Object.defineProperty(exports, "LazerApiKeyMissingError", { enumerable: true, get: function () { return pyth_lazer_rule_ts_1.LazerApiKeyMissingError; } });
+// `resolveOracleRule` (rule-registry.ts) is NOT re-exported here — it has one
+// production consumer (`refreshOraclePrices` below) and no external caller;
+// per repo convention ("no unused exports") it stays module-internal. Tests
+// import it directly from `./rule-registry.ts`. `OracleSourceNotImplementedError`
+// IS re-exported (the same `instanceof` reason as `OracleFeeSourceUnavailableError`
+// above) — a consumer of `refreshOraclePrices` can catch it without importing
+// `resolveOracleRule` itself.
+var rule_registry_ts_1 = require("./rule-registry.js");
+Object.defineProperty(exports, "OracleSourceNotImplementedError", { enumerable: true, get: function () { return rule_registry_ts_1.OracleSourceNotImplementedError; } });
 // Aggregation orchestrator
 var aggregate_ts_1 = require("./aggregate.js");
 Object.defineProperty(exports, "aggregateTicker", { enumerable: true, get: function () { return aggregate_ts_1.aggregateTicker; } });

package/dist/cjs/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/cjs/src/oracle/price-update-rule.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * `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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertRuleUpdateData = assertRuleUpdateData;
+/**
+ * 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[] }"`).
+ */
+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;
+}