@waterx/sdk 4.3.2 → 5.0.0

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

@@ -2,12 +2,12 @@
  * Oracle aggregation — the orchestrator that composes rules into the shared
  * `Oracle`. This is the ONE file that knows about every rule: it builds a
  * `PriceCollector`, feeds whichever rules a ticker is configured for
- * (Pyth / Lazer / Supra / Constant), then `aggregate`s.
+ * (Lazer / Waterx / Supra / Constant), then `aggregate`s.
  *
  * Per ticker:
  *   collector = oracle::new_collector(ticker)
- *   [pyth_rule::feed]       when the ticker has a pyth_rule.feeds entry
  *   [pyth_lazer_rule::feed] when the update leg produced a verified lazer Update
+ *   [waterx_rule::collect_*] when the update leg fetched signed waterx data
  *   [supra_rule::feed]      when supra is enabled + wired
  *   [constant_rule::feed]   when the ticker is a constant ticker
  *   oracle::aggregate(oracle, collector)
@@ -24,67 +24,68 @@
  */
 import type { Transaction, TransactionArgument } from "@mysten/sui/transactions";
 import type { OracleHost } from "./host.ts";
-import type { OracleSource, PriceUpdateRule, UpdateDataProvider } from "./price-update-rule.ts";
-import { type OracleFeeSource, type PythCache } from "./pyth.ts";
-import { type WaterxSignedEnvelope } from "./rules/waterx-rule.ts";
+import { type OracleSource, type PriceUpdateRule, type UpdateDataProvider } from "./price-update-rule.ts";
+import { type WaterxSignedEnvelope, type WaterxSignedLeaf } from "./rules/waterx-rule.ts";
 /**
  * Aggregate one ticker's price into the shared `Oracle`: build a collector, feed
  * every rule the ticker is configured for, then `aggregate`.
  *
- * - **Pyth** — fed when `priceInfoObjectId` is supplied (i.e. the ticker has a
- *   `pyth_rule.feeds` entry). When this PTB's update leg refreshed the
- *   `PriceInfoObject` it contributes a fresh price; when it did not (a
- *   lazer-routed ticker), the on-chain rule only READS the object and abstains
- *   if it is stale — it never aborts — so the call stays mandatory while
- *   `pyth_rule` remains in the ticker's on-chain weighted set
- *   (`EMissingPriceSource` requires every weighted rule to appear).
  * - **Lazer** — fed when `lazerUpdate` is supplied: the verified update this
  *   PTB's lazer update leg produced with the network's verify entry
  *   (`update_v2::Update` on mainnet, `update::Update` on testnet — see
  *   `PythLazerRule.buildUpdateCalls`). If the ticker's aggregator does
  *   not (yet) weight `PythLazerRule`, the contribution is silently dropped
  *   on-chain — feeding ahead of the weight migration is harmless.
- * - **Supra** — fed alongside Pyth/Lazer when supra is enabled + wired
+ * - **Waterx** — fed when `waterxLeaf` (default shape) or `waterxEnvelope`
+ *   (fallback shape) is supplied; verify AND feed are bundled into the one
+ *   collect call per collector.
+ * - **Supra** — fed alongside the sources when supra is enabled + wired
  *   (abstains on-chain for symbols it has no pair for).
  * - **Constant** — fed when the ticker is a constant ticker
  *   ({@link OracleHost.isConstantTicker}).
  *
- * "Dual-feed" (Pyth + Constant, or Pyth + Lazer) and "constant-only" are not
+ * "Dual-feed" (Lazer + Constant, or Lazer + Waterx) and "constant-only" are not
  * special cases — they fall out of which rules the ticker is in. Throws if no
  * rule applies.
  */
 export declare function aggregateTicker(tx: Transaction, host: OracleHost, args: {
     ticker: string;
-    priceInfoObjectId?: string;
     lazerUpdate?: TransactionArgument;
+    /** This ticker's signed Merkle leaf — the default waterx shape. */
+    waterxLeaf?: WaterxSignedLeaf;
+    /** Batch envelope covering this ticker — the fallback waterx shape. */
     waterxEnvelope?: WaterxSignedEnvelope;
 }): void;
 /**
- * Thin wrapper over {@link aggregateTicker} for a Pyth-fed ticker. Kept for
- * back-compat (e.g. WLP mint builds). Caller must run the Pyth update first.
+ * {@link aggregateTicker} for a **constant-only** ticker (no source update
+ * needed — the price comes from the on-chain `constant_rule::Config`). Kept as
+ * a named entry so constant-only call sites (e.g. WLP builders refreshing the
+ * USDCUSD pool token) read as what they are; it adds nothing over
+ * `aggregateTicker(tx, host, { ticker })`.
  */
-export declare function aggregateTickerWithPyth(tx: Transaction, host: OracleHost, args: {
+export declare function aggregateTickerWithConstant(tx: Transaction, host: OracleHost, args: {
     ticker: string;
-    priceInfoObjectId: string;
 }): void;
 /**
- * {@link aggregateTicker} for a **constant-only** ticker (no Pyth update needed —
- * the price comes from the on-chain `constant_rule::Config`).
+ * What {@link refreshOraclePrices} actually put on chain.
  *
- * Throws if the ticker ALSO has a `pyth_rule.feeds` entry (a dual-feed transition
- * ticker): feeding only the constant leg would leave the still-weighted Pyth rule
- * absent from the collector and abort `aggregate` with `EMissingPriceSource`. Such
- * tickers must go through {@link aggregateTicker} with a `priceInfoObjectId` (or
- * {@link refreshOraclePrices}), which feeds both.
+ * `skipped` holds the requested tickers NO listed source can price (and that
+ * `constant_rule` does not pin). They got no collector and no aggregate, so
+ * their on-chain price is whatever a previous transaction left — which is why
+ * every caller whose ACTION depends on a ticker must check this rather than
+ * assume the refresh covered its whole request.
  */
-export declare function aggregateTickerWithConstant(tx: Transaction, host: OracleHost, args: {
-    ticker: string;
-}): void;
+export interface OracleRefreshSummary {
+    /** Tickers aggregated in this PTB — includes constant-pinned ones. */
+    refreshed: string[];
+    /** Requested tickers no listed source serves. */
+    skipped: string[];
+}
 /**
  * Refresh multiple tickers in one PTB. For each ticker {@link aggregateTicker}
- * feeds whichever rules it is configured for (Pyth if it has a `pyth_rule.feeds`
- * entry, Lazer if the lazer update leg served it — see below — Supra when
- * enabled, Constant when it's a constant ticker).
+ * feeds whichever rules it is configured for (Lazer if the lazer update leg
+ * served it, Waterx if the waterx leg fetched signed data for it — see below —
+ * Supra when enabled, Constant when it's a constant ticker).
  *
  * Before that, the on-chain price *update* leg is routed by the
  * `host.oracleSources` fed set (see `rule-registry.ts`): EVERY listed source
@@ -98,11 +99,15 @@ export declare function aggregateTickerWithConstant(tx: Transaction, host: Oracl
  * source's feeds is caught here.
  *
  * Each source's fetch + build runs against its own infra, guaranteeing
- * per-rule PTB atomicity. A fee-source pre-check runs first (any listed
- * source's `requiresFeeSource`) BEFORE any off-chain fetch or PTB mutation —
- * so a fee-charging source with no `opts.feeSource` throws
- * `OracleFeeSourceUnavailable` with zero wasted network calls and zero stray
- * moveCalls. Only once that check passes do the off-chain fetches run — in
+ * per-rule PTB atomicity. A credential pre-check runs early: any group that
+ * still needs to fetch, whose rule declares a `credential` the host does not
+ * carry while `host.pyth.api_key` is unset, throws `LazerApiKeyMissing`
+ * BEFORE any ORACLE fetch or PTB mutation — zero wasted oracle calls, zero
+ * stray moveCalls. (With an `updateDataProvider` configured, its per-source
+ * lookups run first so the check can be scoped to the groups the cache did
+ * NOT serve; a consumer-implemented provider may do I/O of its own, so the
+ * guarantee is about oracle fetches, not about every possible round trip.)
+ * Only once that check passes do the off-chain fetches run — in
  * parallel across sources — and ALL settle before the first PTB mutation;
  * on-chain reads inside `buildUpdateCalls` can still fail mid-append for
  * other reasons — callers discard the tx on any throw.
@@ -111,32 +116,14 @@ export declare function aggregateTickerWithConstant(tx: Transaction, host: Oracl
  * `buildUpdateCalls` returns the verified `Update` PTB value
  * ({@link RuleUpdateHandle}), and every ticker in that group is aggregated
  * with `lazerUpdate` set so {@link aggregateTicker} appends
- * `pyth_lazer_rule::feed` against it. A lazer-routed ticker that still has a
- * `pyth_rule.feeds` entry ALSO keeps its `pyth_rule::feed` leg — required
- * on-chain while `pyth_rule` stays in the ticker's weighted set
- * (`aggregator::remove_outliers` aborts `EMissingPriceSource` unless every
- * weighted rule appears in the collector; an abstention counts as
- * appearing), and safe: `pyth_rule::feed` only READS the `PriceInfoObject`
- * this PTB never refreshed and abstains when it is stale rather than
- * aborting. Conversely, a lazer feed call on an aggregator that does not
- * (yet) weight `PythLazerRule` is silently dropped on-chain — so
- * lazer-routing a ticker ahead of its on-chain weight migration prices it
- * from the remaining weighted rules instead of failing.
+ * `pyth_lazer_rule::feed` against it. A waterx-served group's signed data is
+ * carried straight from its fetched payload to the per-ticker collect call.
+ * A feed call on an aggregator that does not (yet) weight that rule is
+ * silently dropped on-chain — so routing a ticker ahead of its on-chain
+ * weight migration prices it from the remaining weighted rules instead of
+ * failing.
  */
 export declare function refreshOraclePrices(tx: Transaction, host: OracleHost, tickers: string[], opts?: {
-    cache?: PythCache;
-    /**
-     * The single resolved fee source for the Pyth update fee, forwarded
-     * verbatim to each group's `PriceUpdateRule.buildUpdateCalls` as
-     * `BuildUpdateOpts.feeSource`. Already-resolved by the caller (see
-     * {@link OracleFeeSource}'s own doc for where/how) — this function makes
-     * no sponsor-vs-gas decision itself, it only checks whether a source was
-     * resolved at all. Ignored by rules with no update fee (e.g.
-     * `pyth_lazer_rule`). Building with `feeSource` unset throws
-     * `OracleFeeSourceUnavailable` (see `oracle/pyth.ts`) instead of
-     * silently drawing from `tx.gas`.
-     */
-    feeSource?: OracleFeeSource;
     /**
      * @internal Test-only: layer fake `PriceUpdateRule`s on top of the
      * production registry (see `rule-registry.ts`'s `resolveOracleRule`).
@@ -153,4 +140,4 @@ export declare function refreshOraclePrices(tx: Transaction, host: OracleHost, t
      * payload) throws instead, since that is a caller bug, not a cache miss.
      */
     updateDataProvider?: UpdateDataProvider;
-}): Promise<void>;
+}): Promise<OracleRefreshSummary>;