@waterx/sdk 4.3.3 → 5.0.0

package/dist/src/oracle/read-prices.d.ts

@@ -0,0 +1,105 @@
+/**
+ * `read-prices.ts` — the READ-plane executors for the two live sources: parsed
+ * (display-grade) prices from the Lazer HTTP API and the WaterX quote-center.
+ * The sibling `read-plane.ts` resolves WHICH tickers a source can price and
+ * with which ids; these functions execute that plan. Consumers (FE/BE price
+ * facades) fold onto these instead of hand-rolling per-source fetch + decode —
+ * the price DECODING here is the one place each source's wire scaling is
+ * interpreted (the retired hermes decode was deleted, not re-homed).
+ *
+ * Both executors return a Map keyed the way the plan is keyed (integer Lazer
+ * feed id / ticker) of {@link OraclePriceEntry} — plain numbers, for display
+ * and freshness policy, NEVER for rebuilding signed payloads (tx-builds carry
+ * the exact signed bytes through `refreshOraclePrices`).
+ */
+import type { Network } from "../constants.ts";
+import type { PythFetchPolicy } from "./config.ts";
+import type { FetchPolicy } from "./update-fetch.ts";
+/**
+ * One decoded read-plane price. `price` / `conf` are display-grade floats in
+ * quote units (USD); `publishTimeMs` is the feed's own publish timestamp in
+ * ms — the input to freshness policy (`isFreshWaterxEntry`, consumers'
+ * max-age gates).
+ */
+export type OraclePriceEntry = {
+    price: number;
+    publishTimeMs: number;
+    conf: number;
+};
+/**
+ * Thrown by {@link readLazerPrices} on a Lazer `403` — the key's grant does
+ * not cover one of the requested feeds (Lazer rejects the WHOLE batch). The
+ * message carries the endpoint's own PLAIN-TEXT body verbatim (e.g.
+ * `Not entitled: feed 327 (no grant accepts this feed (asset type 'fx',
+ * instrument type 'spot'))`) — it names the offending feed and grant reason
+ * better than anything the SDK could synthesize. `instanceof`-able so a
+ * consumer can drop unentitled feeds and retry rather than string-matching.
+ */
+export declare class LazerNotEntitledError extends Error {
+    /** The integer Lazer feed ids the rejected request asked for. */
+    readonly feedIds: number[];
+    constructor(body: string, feedIds: number[]);
+}
+/**
+ * Read parsed prices for `feedIds` (integer Lazer ids — the `"lazer"` arm of
+ * `resolveOracleReadPlan`) via `POST /v1/latest_price`.
+ *
+ * - `network` is REQUIRED: it selects the Lazer endpoint AND the channel, and
+ *   the integer feed ids in a plan are network-specific, so defaulting it
+ *   would silently read mainnet infra with testnet ids. Every caller already
+ *   holds one (`resolveOracleReadPlan` takes the same host).
+ * - `channel` defaults to `LAZER_INFRA[network].channel` (the same channel
+ *   the write leg uses — bounded by the feeds' `min_channel` AND the key's
+ *   grant). A `400` naming an unsupported/rate-limited channel propagates as
+ *   a plain error with the body attached — that is an operator
+ *   misconfiguration, not a retry case.
+ * - Decoding: `price = Number(price) * 10 ** exponent` (the wire `price` is a
+ *   decimal STRING), `conf = Number(confidence) * 10 ** exponent`,
+ *   `publishTimeMs = feedUpdateTimestamp / 1000` (the wire value is µs). An
+ *   entry with NO `feedUpdateTimestamp` is SKIPPED — never timestamped off
+ *   the response's batch `timestampUs`, which says when Lazer answered, not
+ *   when that feed last printed (a closed-market feed would masquerade as
+ *   fresh).
+ * - `403` → {@link LazerNotEntitledError} (whole batch rejected; body text
+ *   verbatim).
+ */
+export declare function readLazerPrices(opts: {
+    apiKey: string;
+    feedIds: number[];
+    network: Network;
+    channel?: string;
+    fetch?: PythFetchPolicy;
+}): Promise<Map<number, OraclePriceEntry>>;
+/**
+ * Read prices for `tickers` (the `"quote_center"` arm of
+ * `resolveOracleReadPlan`) through {@link pullWaterxQuotes}, the rule-owned
+ * route ladder the write path uses: per-symbol Merkle leaves by default, the
+ * batch envelope only against a quote-center with no leaf route. Public read,
+ * no auth, same retry/timeout policy as every oracle fetch.
+ *
+ * Going through the shared ladder is what keeps the read plane from drifting
+ * off the write plane, and it is why reads do not pull a whole-registry
+ * envelope: that is one signature over every symbol, so a plane polling a
+ * handful of them would transfer and bigint-revive the lot on every tick.
+ *
+ * Decoding per item: `price = Number(price_n) / Number(price_scale)` and
+ * `conf = Number(confidence_n) / Number(confidence_scale)`, each `0` when its
+ * scale is `0` (a zero divisor is "no value", not `Infinity`);
+ * `publishTimeMs = Number(price_timestamp_ms)`. Reads share the write path's
+ * fetch — a mispointed endpoint fails the same intent/shape checks tx-builds
+ * fail — but this NEVER hands its signed data to a tx-build: the on-chain
+ * per-symbol replay guard (F-014) burns one submission per signed timestamp,
+ * and reads must not race trades for it.
+ */
+export declare function readQuoteCenterPrices(opts: {
+    endpoint: string;
+    /**
+     * Oracle TICKERS, per the repo convention — this is the consumer boundary,
+     * fed directly by `readPlanTickers(plan)`, and naming the same values
+     * `symbols` here made every call site cross a rename. Below this point the
+     * wire helpers keep `symbols`: that mirrors the literal `?symbols=` query
+     * parameter and the `symbol` field the quote-center returns.
+     */
+    tickers: string[];
+    fetch?: FetchPolicy;
+}): Promise<Map<string, OraclePriceEntry>>;

package/dist/src/oracle/read-prices.js

@@ -0,0 +1,156 @@
+/**
+ * `read-prices.ts` — the READ-plane executors for the two live sources: parsed
+ * (display-grade) prices from the Lazer HTTP API and the WaterX quote-center.
+ * The sibling `read-plane.ts` resolves WHICH tickers a source can price and
+ * with which ids; these functions execute that plan. Consumers (FE/BE price
+ * facades) fold onto these instead of hand-rolling per-source fetch + decode —
+ * the price DECODING here is the one place each source's wire scaling is
+ * interpreted (the retired hermes decode was deleted, not re-homed).
+ *
+ * Both executors return a Map keyed the way the plan is keyed (integer Lazer
+ * feed id / ticker) of {@link OraclePriceEntry} — plain numbers, for display
+ * and freshness policy, NEVER for rebuilding signed payloads (tx-builds carry
+ * the exact signed bytes through `refreshOraclePrices`).
+ */
+import { LAZER_INFRA, postLazerLatestPrice } from "./rules/pyth-lazer-rule.js";
+import { pullWaterxQuotes } from "./rules/waterx-rule.js";
+/**
+ * Thrown by {@link readLazerPrices} on a Lazer `403` — the key's grant does
+ * not cover one of the requested feeds (Lazer rejects the WHOLE batch). The
+ * message carries the endpoint's own PLAIN-TEXT body verbatim (e.g.
+ * `Not entitled: feed 327 (no grant accepts this feed (asset type 'fx',
+ * instrument type 'spot'))`) — it names the offending feed and grant reason
+ * better than anything the SDK could synthesize. `instanceof`-able so a
+ * consumer can drop unentitled feeds and retry rather than string-matching.
+ */
+export class LazerNotEntitledError extends Error {
+    /** The integer Lazer feed ids the rejected request asked for. */
+    feedIds;
+    constructor(body, feedIds) {
+        super(`Lazer price read not entitled: ${body}`);
+        this.name = "LazerNotEntitledError";
+        this.feedIds = [...feedIds];
+    }
+}
+/**
+ * The parsed-read request pins, mirroring the live-probed Lazer contract:
+ * `formats: []` is REQUIRED — an ABSENT `formats` is rejected while an empty
+ * array means "parsed only, no signed blob", which is exactly what a read
+ * plane wants (no signature bytes to pay bandwidth for). `properties` pins
+ * the fields the decoder below consumes; `marketSession` rides along for
+ * consumers that surface venue state.
+ */
+const LAZER_PARSED_READ_REQUEST = {
+    properties: ["price", "exponent", "confidence", "feedUpdateTimestamp", "marketSession"],
+    formats: [],
+    parsed: true,
+};
+/**
+ * Read parsed prices for `feedIds` (integer Lazer ids — the `"lazer"` arm of
+ * `resolveOracleReadPlan`) via `POST /v1/latest_price`.
+ *
+ * - `network` is REQUIRED: it selects the Lazer endpoint AND the channel, and
+ *   the integer feed ids in a plan are network-specific, so defaulting it
+ *   would silently read mainnet infra with testnet ids. Every caller already
+ *   holds one (`resolveOracleReadPlan` takes the same host).
+ * - `channel` defaults to `LAZER_INFRA[network].channel` (the same channel
+ *   the write leg uses — bounded by the feeds' `min_channel` AND the key's
+ *   grant). A `400` naming an unsupported/rate-limited channel propagates as
+ *   a plain error with the body attached — that is an operator
+ *   misconfiguration, not a retry case.
+ * - Decoding: `price = Number(price) * 10 ** exponent` (the wire `price` is a
+ *   decimal STRING), `conf = Number(confidence) * 10 ** exponent`,
+ *   `publishTimeMs = feedUpdateTimestamp / 1000` (the wire value is µs). An
+ *   entry with NO `feedUpdateTimestamp` is SKIPPED — never timestamped off
+ *   the response's batch `timestampUs`, which says when Lazer answered, not
+ *   when that feed last printed (a closed-market feed would masquerade as
+ *   fresh).
+ * - `403` → {@link LazerNotEntitledError} (whole batch rejected; body text
+ *   verbatim).
+ */
+export async function readLazerPrices(opts) {
+    const out = new Map();
+    if (opts.feedIds.length === 0)
+        return out;
+    const infra = LAZER_INFRA[opts.network];
+    // Same POST transport the rule's write leg uses (URL join, method, headers,
+    // Bearer + retry policy) — only the request pins and the decoding below are
+    // read-specific.
+    const res = await postLazerLatestPrice(infra.endpoint, opts.channel ?? infra.channel, opts.apiKey, opts.feedIds, LAZER_PARSED_READ_REQUEST, opts.fetch);
+    if (res.status === 403) {
+        // Plain-text body naming the unentitled feed + grant reason — verbatim.
+        throw new LazerNotEntitledError((await res.text()).trim(), opts.feedIds);
+    }
+    if (!res.ok) {
+        // Includes the 400 channel rejections ("Feeds do not support channel …" /
+        // rate-limit minimum-channel) — deterministic misconfigurations that must
+        // reach the operator with the endpoint's own wording.
+        throw new Error(`Lazer price read failed: ${res.status} ${await res.text()}`);
+    }
+    const json = (await res.json());
+    for (const feed of json.parsed?.priceFeeds ?? []) {
+        if (typeof feed.priceFeedId !== "number" ||
+            feed.price === undefined ||
+            typeof feed.exponent !== "number" ||
+            // No per-feed timestamp ⇒ no honest freshness claim ⇒ skip (see doc).
+            typeof feed.feedUpdateTimestamp !== "number") {
+            continue;
+        }
+        const scale = 10 ** feed.exponent;
+        const price = Number(feed.price) * scale;
+        const conf = typeof feed.confidence === "number" ? feed.confidence * scale : 0;
+        // A non-finite decode is a MISSING price, not a price. `Number("abc")` is
+        // NaN and an absurd exponent overflows to Infinity; either would flow
+        // straight into a consumer's staleness/deviation maths, where NaN silently
+        // fails every comparison it appears in. Skipping matches how a feed with no
+        // timestamp is handled above — omitted, so the caller sees it as unserved.
+        if (!Number.isFinite(price) || !Number.isFinite(conf))
+            continue;
+        out.set(feed.priceFeedId, {
+            price,
+            conf,
+            publishTimeMs: feed.feedUpdateTimestamp / 1000,
+        });
+    }
+    return out;
+}
+/**
+ * Read prices for `tickers` (the `"quote_center"` arm of
+ * `resolveOracleReadPlan`) through {@link pullWaterxQuotes}, the rule-owned
+ * route ladder the write path uses: per-symbol Merkle leaves by default, the
+ * batch envelope only against a quote-center with no leaf route. Public read,
+ * no auth, same retry/timeout policy as every oracle fetch.
+ *
+ * Going through the shared ladder is what keeps the read plane from drifting
+ * off the write plane, and it is why reads do not pull a whole-registry
+ * envelope: that is one signature over every symbol, so a plane polling a
+ * handful of them would transfer and bigint-revive the lot on every tick.
+ *
+ * Decoding per item: `price = Number(price_n) / Number(price_scale)` and
+ * `conf = Number(confidence_n) / Number(confidence_scale)`, each `0` when its
+ * scale is `0` (a zero divisor is "no value", not `Infinity`);
+ * `publishTimeMs = Number(price_timestamp_ms)`. Reads share the write path's
+ * fetch — a mispointed endpoint fails the same intent/shape checks tx-builds
+ * fail — but this NEVER hands its signed data to a tx-build: the on-chain
+ * per-symbol replay guard (F-014) burns one submission per signed timestamp,
+ * and reads must not race trades for it.
+ */
+export async function readQuoteCenterPrices(opts) {
+    const out = new Map();
+    if (opts.tickers.length === 0)
+        return out;
+    const { items } = await pullWaterxQuotes(opts.endpoint, opts.tickers, opts.fetch);
+    const requested = new Set(opts.tickers);
+    for (const item of items) {
+        if (!requested.has(item.symbol))
+            continue;
+        out.set(item.symbol, {
+            price: item.price_scale === 0n ? 0 : Number(item.price_n) / Number(item.price_scale),
+            conf: item.confidence_scale === 0n
+                ? 0
+                : Number(item.confidence_n) / Number(item.confidence_scale),
+            publishTimeMs: Number(item.price_timestamp_ms),
+        });
+    }
+    return out;
+}

package/dist/src/oracle/rule-registry.d.ts

@@ -5,26 +5,26 @@
  * every `host.oracleSources` entry through it, and consumers (e.g. a BE
  * prefetch cache keying per source) import `resolveOracleRule` rather than
  * hand-mirroring this map. Selection is driven purely by the value passed in
- * (ultimately `OracleHost.oracleSources`, the `oracleSource` client create
+ * (ultimately `OracleHost.oracleSources`, derived from the deployment config
  * option) — never by a config JSON `enabled` flag and never by `process.env`.
  *
  * Each source is self-contained: it owns its own infra + config and does NOT
- * back-stop any other source. Three are registered: `pyth_rule`
- * (`PythCoreRule`, Hermes VAA), `pyth_lazer_rule` (`PythLazerRule`, Lazer
- * signed updates), and `waterx_rule` (`WaterxRule`, first-party quote-center
- * ed25519 signed batches). Resolving a source with no registered rule throws a
- * clear `OracleSourceNotImplemented` error. There is deliberately no
- * cross-source fallback and no client-creation config guard: selecting a source
- * whose feeds are absent is not an error at init — it surfaces at tx-build time
- * for the specific tickers that source can't serve (see `refreshOraclePrices`).
+ * back-stop any other source. Two are registered: `pyth_lazer_rule`
+ * (`PythLazerRule`, Lazer signed updates) and `waterx_rule` (`WaterxRule`,
+ * first-party quote-center ed25519 signed batches). Resolving a source with
+ * no registered rule throws a clear `OracleSourceNotImplemented` error. There
+ * is deliberately no cross-source fallback and no client-creation config
+ * guard: selecting a source whose feeds are absent is not an error at init —
+ * it surfaces at tx-build time for the specific tickers that source can't
+ * serve (see `refreshOraclePrices`).
  */
 import type { OracleSource, PriceUpdateRule } from "./price-update-rule.ts";
 /**
  * Thrown by {@link resolveOracleRule} when `source` has no `PriceUpdateRule`
  * registered in either the production registry or a test's `overrides` map.
- * `instanceof`-able (mirrors `OracleFeeSourceUnavailableError` in `pyth.ts`)
- * so a consumer can branch on the failure type directly instead of
- * string-matching `error.message`.
+ * `instanceof`-able (mirrors `LazerApiKeyMissingError` in
+ * `rules/pyth-lazer-rule.ts`) so a consumer can branch on the failure type
+ * directly instead of string-matching `error.message`.
  */
 export declare class OracleSourceNotImplementedError extends Error {
     /** The unregistered `OracleSource` that was requested. */

package/dist/src/oracle/rule-registry.js

@@ -5,20 +5,19 @@
  * every `host.oracleSources` entry through it, and consumers (e.g. a BE
  * prefetch cache keying per source) import `resolveOracleRule` rather than
  * hand-mirroring this map. Selection is driven purely by the value passed in
- * (ultimately `OracleHost.oracleSources`, the `oracleSource` client create
+ * (ultimately `OracleHost.oracleSources`, derived from the deployment config
  * option) — never by a config JSON `enabled` flag and never by `process.env`.
  *
  * Each source is self-contained: it owns its own infra + config and does NOT
- * back-stop any other source. Three are registered: `pyth_rule`
- * (`PythCoreRule`, Hermes VAA), `pyth_lazer_rule` (`PythLazerRule`, Lazer
- * signed updates), and `waterx_rule` (`WaterxRule`, first-party quote-center
- * ed25519 signed batches). Resolving a source with no registered rule throws a
- * clear `OracleSourceNotImplemented` error. There is deliberately no
- * cross-source fallback and no client-creation config guard: selecting a source
- * whose feeds are absent is not an error at init — it surfaces at tx-build time
- * for the specific tickers that source can't serve (see `refreshOraclePrices`).
+ * back-stop any other source. Two are registered: `pyth_lazer_rule`
+ * (`PythLazerRule`, Lazer signed updates) and `waterx_rule` (`WaterxRule`,
+ * first-party quote-center ed25519 signed batches). Resolving a source with
+ * no registered rule throws a clear `OracleSourceNotImplemented` error. There
+ * is deliberately no cross-source fallback and no client-creation config
+ * guard: selecting a source whose feeds are absent is not an error at init —
+ * it surfaces at tx-build time for the specific tickers that source can't
+ * serve (see `refreshOraclePrices`).
  */
-import { PythCoreRule } from "./rules/pyth-core-rule.js";
 import { PythLazerRule } from "./rules/pyth-lazer-rule.js";
 import { WaterxRule } from "./rules/waterx-rule.js";
 /**
@@ -26,16 +25,15 @@ import { WaterxRule } from "./rules/waterx-rule.js";
  * `resolveOracleRule`'s `overrides` param instead of mutating this.
  */
 const DEFAULT_RULES = Object.freeze({
-    pyth_rule: PythCoreRule,
     pyth_lazer_rule: PythLazerRule,
     waterx_rule: WaterxRule,
 });
 /**
  * Thrown by {@link resolveOracleRule} when `source` has no `PriceUpdateRule`
  * registered in either the production registry or a test's `overrides` map.
- * `instanceof`-able (mirrors `OracleFeeSourceUnavailableError` in `pyth.ts`)
- * so a consumer can branch on the failure type directly instead of
- * string-matching `error.message`.
+ * `instanceof`-able (mirrors `LazerApiKeyMissingError` in
+ * `rules/pyth-lazer-rule.ts`) so a consumer can branch on the failure type
+ * directly instead of string-matching `error.message`.
  */
 export class OracleSourceNotImplementedError extends Error {
     /** The unregistered `OracleSource` that was requested. */

package/dist/src/oracle/rules/pyth-lazer-rule.d.ts

@@ -10,6 +10,7 @@
  */
 import type { Transaction, TransactionArgument } from "@mysten/sui/transactions";
 import type { Network } from "../../constants.ts";
+import type { PythFetchPolicy } from "../config.ts";
 import type { OracleHost } from "../host.ts";
 import { type PriceUpdateRule } from "../price-update-rule.ts";
 /**
@@ -60,13 +61,33 @@ export interface PythLazerUpdatePayload {
  * Thrown by {@link PythLazerRule.fetchUpdateData} when `pyth_lazer_rule` is
  * deployed in config but no `pythApiKey` was supplied at client init — the
  * Lazer HTTP API requires a Bearer token and the SDK never reads
- * `process.env` to find one. `instanceof`-able (mirrors
- * `OracleFeeSourceUnavailableError` in `pyth.ts`) so a consumer can branch on
- * the failure type directly instead of string-matching `error.message`.
+ * `process.env` to find one. Also thrown by `refreshOraclePrices`'s hoisted
+ * credential pre-check (`aggregate.ts`) BEFORE any fetch, keyed off this
+ * rule's `credential` declaration. `instanceof`-able (mirrors `FetchPolicyError`
+ * in `../update-fetch.ts`) so a consumer can branch on the failure type
+ * directly instead of string-matching `error.message`.
  */
 export declare class LazerApiKeyMissingError extends Error {
     constructor();
 }
+/**
+ * THE `POST {endpoint}/v1/latest_price` transport — shared by BOTH legs of
+ * this endpoint: the signed-update WRITE fetch below and the parsed-price READ
+ * executor (`readLazerPrices` in `../read-prices.ts`). They differ only in the
+ * request pins they send and how they decode/blame the response, so keeping
+ * one transport stops the URL, method, headers, and auth/retry policy drifting
+ * between them.
+ *
+ * `requestPins` is spread into the body alongside `priceFeedIds` + `channel`;
+ * the raw `Response` comes back undecoded so each caller owns its own error
+ * framing (the write leg reframes an exhausted retry, the read leg maps 403 to
+ * an entitlement error).
+ *
+ * Goes through the shared `fetchWithPolicy` (`../update-fetch.ts`) — the one
+ * retry/timeout/Bearer policy every oracle fetch shares, so all sources fail
+ * the same way under upstream degradation.
+ */
+export declare function postLazerLatestPrice(endpoint: string, channel: string, apiKey: string, feedIds: number[], requestPins: Record<string, unknown>, fetchOpts?: PythFetchPolicy): Promise<Response>;
 /**
  * `pyth_lazer_rule::feed(collector, config, clock, &update)` — contribute the
  * verified Lazer price for `collector.symbol()` to the collector. `update` is

package/dist/src/oracle/rules/pyth-lazer-rule.js

@@ -85,7 +85,7 @@ const LAZER_LATEST_PRICE_REQUEST = {
 };
 /**
  * Shape check ONLY — the `kind` discriminant is checked separately by the
- * caller before this runs (mirrors `PythCoreRule`'s guard split), so a
+ * caller before this runs (mirrors `WaterxRule`'s guard split), so a
  * same-shaped payload from a different rule can never silently pass.
  */
 function isPythLazerUpdatePayloadShape(payload) {
@@ -98,9 +98,11 @@ function isPythLazerUpdatePayloadShape(payload) {
  * Thrown by {@link PythLazerRule.fetchUpdateData} when `pyth_lazer_rule` is
  * deployed in config but no `pythApiKey` was supplied at client init — the
  * Lazer HTTP API requires a Bearer token and the SDK never reads
- * `process.env` to find one. `instanceof`-able (mirrors
- * `OracleFeeSourceUnavailableError` in `pyth.ts`) so a consumer can branch on
- * the failure type directly instead of string-matching `error.message`.
+ * `process.env` to find one. Also thrown by `refreshOraclePrices`'s hoisted
+ * credential pre-check (`aggregate.ts`) BEFORE any fetch, keyed off this
+ * rule's `credential` declaration. `instanceof`-able (mirrors `FetchPolicyError`
+ * in `../update-fetch.ts`) so a consumer can branch on the failure type
+ * directly instead of string-matching `error.message`.
  */
 export class LazerApiKeyMissingError extends Error {
     constructor() {
@@ -118,24 +120,39 @@ function requireLazerPackage(host) {
     return entry;
 }
 /**
- * Fetch one signed `leEcdsa` update for `feedIds` from the Lazer HTTP API.
- * Goes through the shared `fetchWithPolicy` (`../update-fetch.ts`) — same
- * retry/timeout/Bearer policy as `fetchPriceFeedsUpdateData`, unified so
- * both oracle sources fail the same way under upstream degradation.
+ * THE `POST {endpoint}/v1/latest_price` transport — shared by BOTH legs of
+ * this endpoint: the signed-update WRITE fetch below and the parsed-price READ
+ * executor (`readLazerPrices` in `../read-prices.ts`). They differ only in the
+ * request pins they send and how they decode/blame the response, so keeping
+ * one transport stops the URL, method, headers, and auth/retry policy drifting
+ * between them.
+ *
+ * `requestPins` is spread into the body alongside `priceFeedIds` + `channel`;
+ * the raw `Response` comes back undecoded so each caller owns its own error
+ * framing (the write leg reframes an exhausted retry, the read leg maps 403 to
+ * an entitlement error).
+ *
+ * Goes through the shared `fetchWithPolicy` (`../update-fetch.ts`) — the one
+ * retry/timeout/Bearer policy every oracle fetch shares, so all sources fail
+ * the same way under upstream degradation.
  */
-async function fetchLazerSignedUpdate(endpoint, channel, apiKey, feedIds, fetchOpts) {
+export function postLazerLatestPrice(endpoint, channel, apiKey, feedIds, requestPins, fetchOpts) {
     // joinEndpointPath preserves any base path on the endpoint — the same
     // leading-slash `new URL` footgun that 404'd every feed on the Pyth Pro
     // Hermes endpoint (see update-fetch.ts). Defensive here: the default
     // Lazer endpoint has no base path, but a config override may.
     const url = joinEndpointPath(endpoint, "v1/latest_price");
+    return fetchWithPolicy(url.toString(), {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ priceFeedIds: feedIds, ...requestPins, channel }),
+    }, { apiKey, ...fetchOpts });
+}
+/** Fetch one signed `leEcdsa` update for `feedIds` from the Lazer HTTP API. */
+async function fetchLazerSignedUpdate(endpoint, channel, apiKey, feedIds, fetchOpts) {
     let res;
     try {
-        res = await fetchWithPolicy(url.toString(), {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ priceFeedIds: feedIds, ...LAZER_LATEST_PRICE_REQUEST, channel }),
-        }, { apiKey, ...fetchOpts });
+        res = await postLazerLatestPrice(endpoint, channel, apiKey, feedIds, LAZER_LATEST_PRICE_REQUEST, fetchOpts);
     }
     catch (err) {
         rethrowExhaustedFetch(err, (e) => `Lazer price fetch failed: ${e.status}${e.bodySnippet ? ` ${e.bodySnippet}` : ""}`);
@@ -167,9 +184,12 @@ export function feedLazerRule(tx, host, collector, update) {
 }
 export const PythLazerRule = {
     kind: "pyth_lazer_rule",
-    // Verification is a flat signature check with no Coin argument — no
-    // update fee — see `PriceUpdateRule.requiresFeeSource`.
-    requiresFeeSource: false,
+    // Lazer is auth-first: the signed-update fetch cannot run without the
+    // caller's `pythApiKey` Bearer. Declared on the port — kind AND error
+    // together — so `refreshOraclePrices`'s hoisted pre-check and consumers'
+    // `missingOracleCredentials` boot asserts both key off the rule itself, and
+    // the orchestrator never constructs this error on the rule's behalf.
+    credential: { kind: "pyth_api_key", missing: () => new LazerApiKeyMissingError() },
     /** Tickers with a `pyth_lazer_rule.feeds` entry (integer Lazer feed ids). */
     supportedTickers(host) {
         return Object.keys(host.config.packages.pyth_lazer_rule?.feeds ?? {});
@@ -222,14 +242,13 @@ export const PythLazerRule = {
      * Appends the single `parse_and_verify_le_ecdsa_update*(state, clock, bytes)`
      * call — one secp256k1 signature check covering every feed in the payload —
      * and returns its `Update` result as the handle the per-ticker feed leg
-     * consumes. `opts.cache` / `opts.feeSource` are Pyth-Core-specific and
-     * ignored (Lazer verification charges no update fee).
+     * consumes.
      *
      * The entry name comes from `LAZER_INFRA[network].verify_entry`: mainnet's
      * rule binds `update_v2`, testnet's is still the v1 publish. Both take
      * `(state, clock, bytes)` and accept the same `leEcdsa` payload.
      */
-    buildUpdateCalls(tx, host, data, _opts) {
+    buildUpdateCalls(tx, host, data) {
         const payload = assertRuleUpdateData(data, "pyth_lazer_rule", isPythLazerUpdatePayloadShape, "{ update: Uint8Array; feedIds: number[] }");
         if (!payload)
             return undefined;