@waterx/sdk 4.3.3 → 5.0.0

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

@@ -1,14 +1,14 @@
 /**
  * `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`.
+ * update on-chain (e.g. Lazer's single signature-verify step). 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: `PythLazerRule` (Lazer signed
+ * updates) and `WaterxRule` (quote-center ed25519). `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` resolves a concrete rule per `host.oracleSources`
@@ -17,25 +17,29 @@
  */
 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";
+export type PriceUpdateRuleKind = "pyth_lazer_rule" | "supra_rule" | "constant_rule" | "waterx_rule";
 /**
  * The canonical list of selectable oracle sources — the SINGLE authority the
  * {@link OracleSource} union derives from (the value-list→union derive
  * idiom of `unified-client.ts`'s `NON_CLIENT_FIRST`, plus `Object.freeze`
  * so the immutability is RUNTIME truth: `as const` alone would let a JS
- * consumer push into the array and desync the membership Set built from it
- * in `source-list.ts`). Runtime membership checks and the `ORACLE_SOURCE`
- * env parser live there, on `isOracleSource` / `parseOracleSourceList`.
+ * consumer push into the array, and `deriveOracleSources` (`source-list.ts`)
+ * walks exactly this list to decide the fed set — a pushed entry would name a
+ * source with no rule module behind it.
  * Only sources belong here: `supra_rule` and `constant_rule` are auxiliary
  * rules fed alongside whichever sources are selected (see
  * `aggregateTicker`), not sources themselves — the `satisfies` keeps
  * entries inside `PriceUpdateRuleKind` but adding an auxiliary rule to this
  * list is an (incorrect) editorial decision this comment exists to prevent.
+ *
+ * `pyth_rule` (Pyth Core, Hermes VAA) was RETIRED in 5.0.0 — it is no longer
+ * a `PriceUpdateRuleKind` at all. Its config block is still published in the
+ * live deployments and is inert precisely because it is absent from this
+ * list: `deriveOracleSources` can never select it.
  */
-export declare const ORACLE_SOURCES: readonly ["pyth_rule", "pyth_lazer_rule", "waterx_rule"];
+export declare const ORACLE_SOURCES: readonly ["pyth_lazer_rule", "waterx_rule"];
 /**
- * The kinds listable in a client's `oracleSource` create option (see
+ * The implementable price-update sources — the candidates `deriveOracleSources` picks from (see
  * `OracleHost.oracleSources`) — i.e. rules that can serve as the on-chain
  * price *update* leg `refreshOraclePrices` runs before aggregating. Derived
  * from {@link ORACLE_SOURCES}. The SDK never reads `process.env` — consumers
@@ -45,8 +49,8 @@ export type OracleSource = (typeof ORACLE_SOURCES)[number];
 /**
  * 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
+ * each rule implementation narrows it to its own shape (e.g. `PythLazerRule`'s
+ * `{ update: Uint8Array; feedIds: number[] }`). `null` for rules with no
  * off-chain fetch (e.g. `ConstantRule`) or when there is nothing to fetch.
  */
 export type RuleUpdateData = {
@@ -62,9 +66,8 @@ export type RuleUpdateData = {
  *    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.
+ *    shape, 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).
  *
@@ -75,18 +78,18 @@ export type RuleUpdateData = {
  *   `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[] }"`).
+ *   shape-mismatch error (e.g. `"{ update: Uint8Array; feedIds: number[] }"`).
  */
 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-update result of its network's verify entry — 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).
+ * *within the same PTB*. The Lazer rule returns the verified-update result of
+ * its network's verify entry — 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). `WaterxRule` needs none
+ * (its verify+feed is bundled into the per-ticker collect call), so it
+ * returns `void`.
  */
 export type RuleUpdateHandle = {
     readonly kind: "pyth_lazer_rule";
@@ -101,26 +104,12 @@ export type RuleUpdateHandle = {
      */
     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
+ * A BE consumer (e.g. a prefetch cache that polls Lazer/quote-center
+ * 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
@@ -137,6 +126,40 @@ export interface BuildUpdateOpts {
 export interface UpdateDataProvider {
     get(source: OracleSource, tickers: string[]): Promise<RuleUpdateData | null>;
 }
+/** The credential kinds a rule can declare via {@link PriceUpdateRule.credential}. */
+export type OracleCredentialKind = "pyth_api_key";
+/**
+ * Caller-supplied credential values keyed BY {@link OracleCredentialKind} —
+ * the one shape both enforcement points check against, so neither has to
+ * branch on the kind. `refreshOraclePrices` builds it from a live
+ * `OracleHost` ({@link oracleCredentialsFromHost}); `missingOracleCredentials`
+ * builds it from a consumer's raw env values. Adding a kind means extending
+ * the union above plus those two adapters — never an `if` chain at a check
+ * site.
+ */
+export type OracleCredentials = Partial<Record<OracleCredentialKind, string>>;
+/** The credentials a live client carries, in {@link OracleCredentials} shape. */
+export declare function oracleCredentialsFromHost(host: OracleHost): OracleCredentials;
+/**
+ * A rule's off-chain credential requirement — the KIND it needs plus the error
+ * it wants raised when that credential is absent, as ONE object so the two can
+ * never drift apart.
+ *
+ * Both enforcement points are fully generic over this: neither names a kind,
+ * and neither constructs another rule's error. `refreshOraclePrices`'s hoisted
+ * pre-check (`aggregate.ts`) throws `missing()` before any fetch or PTB
+ * mutation; `missingOracleCredentials` (`validate.ts`) reports `kind` for a
+ * consumer's boot-time env audit.
+ */
+export interface OracleCredentialRequirement {
+    readonly kind: OracleCredentialKind;
+    /**
+     * The rule's OWN error for "declared credential absent". Owning it here is
+     * what keeps the orchestrator from importing (and mis-attributing) one
+     * rule's error type on behalf of every rule that shares a kind.
+     */
+    missing(): Error;
+}
 export interface PriceUpdateRule {
     /**
      * `OracleSource`, not the wider `PriceUpdateRuleKind`: only selectable
@@ -147,22 +170,18 @@ export interface PriceUpdateRule {
      */
     readonly kind: OracleSource;
     /**
-     * `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.
+     * The credential this rule's `fetchUpdateData` cannot run without, or absent
+     * for a credential-free rule. `PythLazerRule` declares `"pyth_api_key"`
+     * (Lazer is auth-first: `host.pyth.api_key` Bearer) with its own
+     * `LazerApiKeyMissingError`; `WaterxRule` declares nothing (the quote-center
+     * read surface is public).
+     *
+     * Two consumers key off this instead of hardcoding per-rule knowledge —
+     * `refreshOraclePrices`'s hoisted pre-check and `missingOracleCredentials` —
+     * and neither branches on the kind or names an error type. See
+     * {@link OracleCredentialRequirement}.
      */
-    readonly requiresFeeSource: boolean;
+    readonly credential?: OracleCredentialRequirement;
     /** Tickers this rule can serve in this environment (from config feeds + enabled). */
     supportedTickers(host: OracleHost): string[];
     /**
@@ -182,9 +201,10 @@ export interface PriceUpdateRule {
      * 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.
+     *   exactly `tickers` — a divisible payload (waterx's per-symbol leaves)
+     *   returns a subset; an indivisible payload (Lazer's single signed message,
+     *   waterx's batch envelope) 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.
@@ -195,14 +215,32 @@ export interface PriceUpdateRule {
      *   bug), it does not miss.
      */
     narrowUpdateData(host: OracleHost, data: RuleUpdateData, tickers: string[]): RuleUpdateData;
+    /**
+     * The per-symbol single-use identity of a payload's signed data, or `null`
+     * when this rule's updates carry no replay-guarded identity (then the
+     * method may also be absent entirely). This is the rule-owned key of the
+     * on-chain F-014 replay guard: submitting the SAME identity twice for a
+     * symbol is at best a paid-for abstain (the dual-rule collect entries) and
+     * at worst an `EReplayedSignature` abort (the single-rule feed entries) —
+     * so a consumer serving cached update data (e.g. a BE serve-at-most-once
+     * cache) keys its guard off this map instead of re-implementing each
+     * rule's payload anatomy.
+     *
+     * `WaterxRule`: leaves → `symbol → signed_timestamp_ms`; envelope →
+     * `symbol → timestamp_ms` (per item; the envelope's one signing timestamp
+     * is every covered symbol's identity). `PythLazerRule` does not implement
+     * it — a Lazer verify is not identity-replay-guarded on-chain.
+     */
+    updateIdentityBySymbol?(data: RuleUpdateData): Map<string, bigint> | null;
     /**
      * 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 —
+     * needs nothing from it 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).
+     * built that payload) — and no options: nothing a rule needs at build time
+     * is caller-tunable, so there is no bag to thread.
      */
-    buildUpdateCalls(tx: Transaction, host: OracleHost, data: RuleUpdateData, opts?: BuildUpdateOpts): Promise<RuleUpdateHandle | void> | RuleUpdateHandle | void;
+    buildUpdateCalls(tx: Transaction, host: OracleHost, data: RuleUpdateData): Promise<RuleUpdateHandle | void> | RuleUpdateHandle | void;
 }

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

@@ -2,14 +2,14 @@
 /**
  * `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`.
+ * update on-chain (e.g. Lazer's single signature-verify step). 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: `PythLazerRule` (Lazer signed
+ * updates) and `WaterxRule` (quote-center ed25519). `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` resolves a concrete rule per `host.oracleSources`
@@ -19,22 +19,27 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ORACLE_SOURCES = void 0;
 exports.assertRuleUpdateData = assertRuleUpdateData;
+exports.oracleCredentialsFromHost = oracleCredentialsFromHost;
 /**
  * The canonical list of selectable oracle sources — the SINGLE authority the
  * {@link OracleSource} union derives from (the value-list→union derive
  * idiom of `unified-client.ts`'s `NON_CLIENT_FIRST`, plus `Object.freeze`
  * so the immutability is RUNTIME truth: `as const` alone would let a JS
- * consumer push into the array and desync the membership Set built from it
- * in `source-list.ts`). Runtime membership checks and the `ORACLE_SOURCE`
- * env parser live there, on `isOracleSource` / `parseOracleSourceList`.
+ * consumer push into the array, and `deriveOracleSources` (`source-list.ts`)
+ * walks exactly this list to decide the fed set — a pushed entry would name a
+ * source with no rule module behind it.
  * Only sources belong here: `supra_rule` and `constant_rule` are auxiliary
  * rules fed alongside whichever sources are selected (see
  * `aggregateTicker`), not sources themselves — the `satisfies` keeps
  * entries inside `PriceUpdateRuleKind` but adding an auxiliary rule to this
  * list is an (incorrect) editorial decision this comment exists to prevent.
+ *
+ * `pyth_rule` (Pyth Core, Hermes VAA) was RETIRED in 5.0.0 — it is no longer
+ * a `PriceUpdateRuleKind` at all. Its config block is still published in the
+ * live deployments and is inert precisely because it is absent from this
+ * list: `deriveOracleSources` can never select it.
  */
 exports.ORACLE_SOURCES = Object.freeze([
-    "pyth_rule",
     "pyth_lazer_rule",
     "waterx_rule",
 ]);
@@ -47,9 +52,8 @@ exports.ORACLE_SOURCES = Object.freeze([
  *    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.
+ *    shape, 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).
  *
@@ -60,7 +64,7 @@ exports.ORACLE_SOURCES = Object.freeze([
  *   `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[] }"`).
+ *   shape-mismatch error (e.g. `"{ update: Uint8Array; feedIds: number[] }"`).
  */
 function assertRuleUpdateData(data, kind, isShape, shapeDescription) {
     if (!data)
@@ -74,3 +78,7 @@ function assertRuleUpdateData(data, kind, isShape, shapeDescription) {
     }
     return data.payload;
 }
+/** The credentials a live client carries, in {@link OracleCredentials} shape. */
+function oracleCredentialsFromHost(host) {
+    return { pyth_api_key: host.pyth.api_key };
+}

package/dist/cjs/src/oracle/pyth-pro-history.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `pyth-pro-history.ts` — Pyth Pro chart history
+ * (`GET /v1/{channel}/history`), the TradingView-UDF-shaped bar source that
+ * replaces Benchmarks for chart backfill. Bearer-REQUIRED (unlike the symbol
+ * catalog): consumers call this server-side with their `PYTH_API_KEY` and
+ * keep their own fallback policy (e.g. Benchmarks on 403/5xx while its
+ * keyless window lasts).
+ *
+ * The `symbol` must be FULLY QUALIFIED (`Crypto.BTC/USD`,
+ * `Equity.US.AAPL/USD` — the catalog's `symbol` field); a bare pair 404s.
+ * `channel` picks the aggregation cadence the key's grant allows (e.g.
+ * `fixed_rate@1000ms`).
+ */
+import { type FetchPolicy } from "./update-fetch.ts";
+/**
+ * Fetch one history window. Returns the endpoint's TradingView-UDF-style JSON
+ * body VERBATIM (`unknown` — e.g. `{ s: "ok", t: [...], o: [...], h: [...],
+ * l: [...], c: [...] }`): bar-shape interpretation stays with the charting
+ * consumer, the SDK only owns transport + auth. Throws on non-2xx with the
+ * body attached (a 403 here is the caller's fallback trigger).
+ */
+export declare function fetchPythProHistory(opts: {
+    /** Aggregation channel path segment, e.g. `"fixed_rate@1000ms"`. */
+    channel: string;
+    /** Fully-qualified reference symbol, e.g. `"Crypto.BTC/USD"`. */
+    symbol: string;
+    /** UDF resolution, e.g. `"1"`, `"60"`, `"1D"`. */
+    resolution: string;
+    /** Window start (unix seconds, inclusive). */
+    fromSec: number;
+    /** Window end (unix seconds, inclusive). */
+    toSec: number;
+    /** Pyth Pro Bearer key — REQUIRED by the endpoint. */
+    apiKey: string;
+    fetch?: FetchPolicy;
+}): Promise<unknown>;

package/dist/cjs/src/oracle/pyth-pro-history.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * `pyth-pro-history.ts` — Pyth Pro chart history
+ * (`GET /v1/{channel}/history`), the TradingView-UDF-shaped bar source that
+ * replaces Benchmarks for chart backfill. Bearer-REQUIRED (unlike the symbol
+ * catalog): consumers call this server-side with their `PYTH_API_KEY` and
+ * keep their own fallback policy (e.g. Benchmarks on 403/5xx while its
+ * keyless window lasts).
+ *
+ * The `symbol` must be FULLY QUALIFIED (`Crypto.BTC/USD`,
+ * `Equity.US.AAPL/USD` — the catalog's `symbol` field); a bare pair 404s.
+ * `channel` picks the aggregation cadence the key's grant allows (e.g.
+ * `fixed_rate@1000ms`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchPythProHistory = fetchPythProHistory;
+const symbol_catalog_ts_1 = require("./symbol-catalog.js");
+const update_fetch_ts_1 = require("./update-fetch.js");
+/**
+ * Fetch one history window. Returns the endpoint's TradingView-UDF-style JSON
+ * body VERBATIM (`unknown` — e.g. `{ s: "ok", t: [...], o: [...], h: [...],
+ * l: [...], c: [...] }`): bar-shape interpretation stays with the charting
+ * consumer, the SDK only owns transport + auth. Throws on non-2xx with the
+ * body attached (a 403 here is the caller's fallback trigger).
+ */
+async function fetchPythProHistory(opts) {
+    const url = (0, update_fetch_ts_1.joinEndpointPath)(symbol_catalog_ts_1.PYTH_PRO_API_ENDPOINT, `v1/${opts.channel}/history`);
+    url.searchParams.set("symbol", opts.symbol);
+    url.searchParams.set("resolution", opts.resolution);
+    url.searchParams.set("from", String(opts.fromSec));
+    url.searchParams.set("to", String(opts.toSec));
+    // `opts.fetch` is the full `FetchPolicy`, which itself has an `apiKey`, so
+    // spreading it AFTER the explicit one let `{ fetch: { apiKey: undefined } }`
+    // silently strip the Bearer this endpoint requires — a 403 with no clue why.
+    // The dedicated argument wins; the policy supplies it only as a fallback.
+    const res = await (0, update_fetch_ts_1.fetchWithPolicy)(url.toString(), {}, { ...opts.fetch, apiKey: opts.apiKey ?? opts.fetch?.apiKey });
+    if (!res.ok) {
+        throw new Error(`Pyth Pro history fetch failed: ${res.status} ${await res.text()}`);
+    }
+    return res.json();
+}

package/dist/cjs/src/oracle/read-plane.d.ts

@@ -1,70 +1,52 @@
 /**
  * `read-plane.ts` — per-source READ-plane resolution: which of a caller's
- * tickers a source can PRICE off-chain, and with which ids. The write plane
- * (`PriceUpdateRule` + each source's `feeds` block) and the read plane are
- * DIFFERENT namespaces for the pyth sources: Lazer WRITES with the integer
- * ids in `pyth_lazer_rule.feeds`, but every Hermes-compatible price READ is
- * keyed by the hex ids only `pyth_rule.feeds` carries. That cross-block
- * dependency is a config invariant ("a lazer-fed ticker must also carry a
- * Core hex entry to be read-visible"), and it lives HERE, once — consumers
- * (FE/BE price facades) resolve through this instead of hardcoding which
- * sources share which feeds namespace.
+ * tickers a source can PRICE off-chain, and with which ids. Every source
+ * reads through ITS OWN feeds namespace — `pyth_lazer_rule` via its integer
+ * ids on the Lazer HTTP API, `waterx_rule` via its tickers on the
+ * quote-center — so a source's write set and read set coincide by
+ * construction. (Until 5.0.0 Lazer reads borrowed `pyth_rule.feeds` hex ids
+ * on a Hermes-compatible endpoint; that cross-block dependency, the whole
+ * hermes plane, and the `unreadable` diagnostic are gone with the `pyth_rule`
+ * retirement.) Consumers (FE/BE price facades) resolve through this instead
+ * of hardcoding feed namespaces, and execute plans via the sibling
+ * `read-prices.ts` executors.
  */
-import type { Network } from "../constants.ts";
 import type { OracleHost } from "./host.ts";
 import type { OracleSource } from "./price-update-rule.ts";
 /**
  * One source's read plan for a requested ticker set.
  *
- * - `plane: "hermes"` (pyth sources) — price via a Hermes-compatible REST
- *   endpoint, one entry per servable ticker mapped to its HEX feed id. The
- *   endpoint to execute against is {@link resolveHermesReadEndpoint} — the
- *   plan (ids) plus that resolver (host) is the complete read contract.
- * - `plane: "quote_center"` (waterx) — price via the quote-center symbols
- *   api, keyed by ticker; served set = the `waterx_rule.feeds` block. An
- *   ABSENT block (source listed, package missing from the loaded config)
- *   serves NOTHING: claiming tickers would silently reroute reads to the
- *   quote-center — it happily serves symbols regardless of on-chain config —
- *   and swallow tickers a later-listed source could price. The
- *   misconfiguration is caught loudly by the consumer's feeds assert at
- *   client creation instead.
- * - `unreadable` — requested tickers this source WRITES on-chain (its update
- *   leg serves them) but its read plane cannot price: the silent-invisibility
- *   trap (e.g. a lazer-fed ticker with no `pyth_rule.feeds` hex entry).
- *   Callers should surface these loudly; empty for sources whose write and
- *   read namespaces coincide.
+ * - `plane: "lazer"` (`pyth_lazer_rule`) — price via the Lazer HTTP API
+ *   (`readLazerPrices` in `read-prices.ts`), one entry per servable ticker
+ *   mapped to its INTEGER Lazer feed id from `pyth_lazer_rule.feeds`. Auth is
+ *   the caller's `pythApiKey` Bearer; the endpoint is `LAZER_INFRA`'s own.
+ * - `plane: "quote_center"` (`waterx_rule`) — price via the quote-center
+ *   (`readQuoteCenterPrices` in `read-prices.ts`), keyed by ticker; served
+ *   set = the `waterx_rule.feeds` block. An ABSENT block (source listed,
+ *   package missing from the loaded config) serves NOTHING: claiming tickers
+ *   would silently reroute reads to the quote-center — it happily serves
+ *   symbols regardless of on-chain config — and swallow tickers a
+ *   later-listed source could price. The misconfiguration is caught loudly by
+ *   `assertOracleWriteCoverage` (`validate.ts`) at client creation instead.
+ *
+ * A ticker absent from a plan is simply not servable by THIS source's read
+ * plane — callers decide how to degrade (typically: ask the next source in
+ * their fed set, then omit). Because every source reads its own
+ * feeds, write set == read set — there is no separate read-coverage
+ * diagnostic to carry.
  */
 export type OracleReadPlan = {
-    unreadable: string[];
-} & ({
-    plane: "hermes";
-    feedIdByTicker: Map<string, string>;
+    plane: "lazer";
+    feedIdByTicker: Map<string, number>;
 } | {
     plane: "quote_center";
     tickers: string[];
-});
+};
+/** The tickers a resolved plan can actually serve, regardless of plane. */
+export declare function readPlanTickers(plan: OracleReadPlan): string[];
 /**
  * Resolve `source`'s read plan for `tickers`. Pure config lookup — no
- * network, no endpoint resolution (endpoints come from
- * `pythCoreHermesEndpoint` / `waterxQuoteCenterEndpoint` / the deployment's
- * own env). A ticker absent from the returned plan is simply not servable by
- * THIS source's read plane — callers decide how to degrade (typically: ask
- * the next source in their `ORACLE_SOURCE` list, then omit).
- */
-/**
- * The Hermes-compatible REST base a deployment's hermes-plane read plans
- * execute against — the endpoint half of the read contract
- * ({@link resolveOracleReadPlan} is the ids half):
- *
- * - `pyth_rule` in the fed set → the Core source's own keyless endpoint
- *   (`pythCoreHermesEndpoint(network)`).
- * - otherwise → `override` when the deployment set one (a proxy or
- *   self-hosted mirror), else the documented Pyth Pro base
- *   (`pythProHermesEndpoint()` — identical for every subscriber; auth is the
- *   caller's `pythApiKey` Bearer, not a per-deployment URL).
- *
- * Total — never throws, never falls back Core-ward: a fed set without
- * `pyth_rule` reads Pro (or the override), full stop.
+ * network, no endpoint resolution (endpoints come from `LAZER_INFRA` /
+ * `waterxQuoteCenterEndpoint` / the deployment's own env).
  */
-export declare function resolveHermesReadEndpoint(network: Network, sources: readonly OracleSource[], override?: string): string;
 export declare function resolveOracleReadPlan(host: OracleHost, source: OracleSource, tickers: string[]): OracleReadPlan;