@waterx/sdk 4.3.3 → 5.0.0

package/.claude/skills/waterx-sdk-integration/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: waterx-sdk-integration
-description: Use when integrating @waterx/sdk into an app, keeper, or bot — wiring a WaterX client, creating and funding a wxa account, building perp or prediction transactions, or debugging a WaterX build/simulate failure. Covers the required waterxConfigUrl and oracleSource options, the build→simulate→execute discipline, and the aborts integrators hit first.
+description: Use when integrating @waterx/sdk into an app, keeper, or bot — wiring a WaterX client, creating and funding a wxa account, building perp or prediction transactions, or debugging a WaterX build/simulate failure. Covers the required waterxConfigUrl option, the config-derived oracle fed set, the build→simulate→execute discipline, and the aborts integrators hit first.
 ---
 
 # Integrating `@waterx/sdk`
 
 WaterX is a perpetual futures DEX and prediction market on Sui. The SDK **builds
 transactions**; it never signs on your behalf and never reads `process.env`. Every
-chain-specific value comes from a config JSON *you* supply.
+chain-specific value comes from a config JSON _you_ supply.
 
 Work the steps in order. Each one has a decision you must make explicitly — the SDK has
 no defaults for the first two on purpose, so that every environment runs the same build
@@ -15,11 +15,11 @@ and differs only by configuration.
 
 ## Step 1 — Choose the entry point
 
-| You need                     | Import                                                | Client                    |
-| ---------------------------- | ----------------------------------------------------- | ------------------------- |
-| Both product lines           | `@waterx/sdk`                                         | `WaterXClient.create()`   |
-| Perpetuals only              | `@waterx/sdk/perp`                                    | `PerpClient.create()`     |
-| Prediction markets only      | `@waterx/sdk/prediction`                              | `PredictClient.create()`  |
+| You need                | Import                   | Client                   |
+| ----------------------- | ------------------------ | ------------------------ |
+| Both product lines      | `@waterx/sdk`            | `WaterXClient.create()`  |
+| Perpetuals only         | `@waterx/sdk/perp`       | `PerpClient.create()`    |
+| Prediction markets only | `@waterx/sdk/prediction` | `PredictClient.create()` |
 
 The umbrella exposes three namespaces: `client.account` (shared wxa account + funding),
 `client.perp`, `client.predict`. The two lines have colliding builder names
@@ -33,17 +33,15 @@ pnpm add @waterx/sdk @mysten/sui @mysten/bcs   # the two Mysten packages are pee
 
 Node ≥ 22. ESM and CJS both resolve.
 
-## Step 2 — Supply the two required options
+## Step 2 — Supply the config URL
 
 ```ts
 import { WaterXClient } from "@waterx/sdk";
-import { parseOracleSourceList } from "@waterx/sdk/oracle";
 
 const client = await WaterXClient.create({
   network: "TESTNET",
   waterxConfigUrl: process.env.WATERX_CONFIG_URL, // REQUIRED — no default, no env fallback
-  oracleSource: parseOracleSourceList(process.env.ORACLE_SOURCE), // REQUIRED — no default
-  pythApiKey: process.env.PYTH_API_KEY, // required iff the set includes 'pyth_lazer_rule'
+  pythApiKey: process.env.PYTH_API_KEY, // required iff the config wires pyth_lazer_rule
 });
 ```
 
@@ -53,28 +51,36 @@ as-is — the SDK appends no `<network>.json` and no git ref. Your app reads the
 the SDK never does. Look up ids through the client (`client.perp.getMarket(ticker)`,
 `client.perp.creditType()`, `client.perp.wlpType()`) rather than hardcoding them.
 
-**`oracleSource`** is one source or a **list — the fed set**. Every listed source's data
-is fetched and fed in one PTB, and the chain's per-ticker weight tables arbitrate.
+**The oracle fed set is DERIVED from that config** — there is no `oracleSource` option
+and no `ORACLE_SOURCE` env var. A source is fed when its block is published, carries at
+least one feed, and is not explicitly `enabled: false`. Every derived source's data is
+fetched and fed in one PTB, and the chain's per-ticker weight tables arbitrate. Read the
+answer for a live deployment with `client.perp.oracleSources`, or before a client exists
+with `deriveOracleSources(config)`.
 
-| Source            | Notes                                                                    |
-| ----------------- | ------------------------------------------------------------------------ |
-| `pyth_rule`       | Pyth Core; per-feed update fees; no credential                            |
-| `pyth_lazer_rule` | one signed verify per PTB, no per-feed fees; **requires `pythApiKey`**    |
+| Source            | Notes                                                                            |
+| ----------------- | -------------------------------------------------------------------------------- |
+| `pyth_lazer_rule` | one signed verify per PTB, no per-feed fees; **requires `pythApiKey`**           |
 | `waterx_rule`     | first-party TEE quote-center; no credential; browser needs a CORS-allowed origin |
 
-The rule that decides the value: **the fed set must be a superset of every ticker's
+(`pyth_rule` — Pyth Core / Hermes — was retired in 5.0.0. Its block is still published
+in the live configs and is inert: it is not a derivable source, so nothing feeds it.)
+
+Why derived rather than declared: **the fed set must be a superset of every ticker's
 on-chain weighted rules.** Starving a weighted rule aborts `EMissingPriceSource`; feeding
-an unweighted one is silently dropped. That asymmetry is what makes a weight migration an
-env edit rather than an SDK release.
+an unweighted one is silently dropped. Because the failure is one-sided, taking every
+source the config wires is the fail-safe answer — and a hand-typed list could only err
+in the fatal direction (the classic being one copied between networks). A weight
+migration is then a config change, never an env edit and never an SDK release.
 
-Never guess the set — read it off chain:
+Inspect what a network actually weights when you are debugging:
 
 ```bash
 pnpm oracle:aggregates:testnet   # per-ticker aggregator sources + weights
 ```
 
-Parse env with `parseOracleSourceList` (it trims, drops empties, validates, dedupes, and
-throws actionably), never a bare `split(",")`.
+Want to fail at BOOT rather than at the first trade that needs a missing feed? Pass the
+tickers you care about to `assertOracleWriteCoverage(client.perp, tickers)`.
 
 ## Step 3 — Ensure a wxa account
 
@@ -134,15 +140,15 @@ const tx = await client.perp.buildPlaceOrderTx({
     isStopOrder: false,
     reduceOnly: false,
     size: rawPrice(0.001),
-    triggerPrice: undefined,          // omit ⇒ market order
+    triggerPrice: undefined, // omit ⇒ market order
     acceptablePrice: rawPrice(120_000), // slippage cap
     collateralAmount: 5_000_000n,
   },
-  preOrders: [],                      // optional reduce-only TP/SL legs
+  preOrders: [], // optional reduce-only TP/SL legs
 });
 
 tx.setSender(address);
-await client.perp.simulate(tx);       // ALWAYS. Free, and catches every step-2 mistake.
+await client.perp.simulate(tx); // ALWAYS. Free, and catches every step-2 mistake.
 await client.perp.signAndExecuteTransaction({ transaction: tx, signer });
 ```
 
@@ -174,7 +180,7 @@ Stop if you catch yourself doing any of these:
 
 - **Hardcoding an object id.** It belongs in the config JSON, read via the client.
 - **Writing `BTC/USD` or `BTC`.** Tickers are concatenated: `BTCUSD`, `ETHUSD`, `SUIUSD`.
-  (Collateral *tokens* keep a plain symbol — `USDC` — and are a different thing.)
+  (Collateral _tokens_ keep a plain symbol — `USDC` — and are a different thing.)
 - **Passing a plain number as a price or size.** Wrap in `rawPrice()`. The exception:
   view `basePriceUsd` arguments take a whole-dollar u64 — `parseWholeDollarU64`.
 - **Skipping simulate.** Every failure in the table below is free to find at simulate.
@@ -194,14 +200,14 @@ Which step a failure sends you back to. The **full messages, causes, and fixes l
 one place** — `README.md`'s Troubleshooting table — so that they stay accurate; do not
 re-derive them from here.
 
-| Error | Go back to |
-| ----- | ---------- |
-| `loadConfig: no config URL …` | Step 2 — `waterxConfigUrl` |
-| `oracleSource is REQUIRED …` / `… has no feed configured for ticker(s)` | Step 2 — `oracleSource` |
-| `EMissingPriceSource` | Step 2 — the fed set is too narrow for that ticker |
-| `LazerApiKeyMissing …` | Step 2 — `pythApiKey` |
-| `EAccountNotFound` | Step 3 — the account id is not on this network |
-| `EReplayedSignature` | Step 5 — an envelope was reused across builds |
+| Error                                                                 | Go back to                                         |
+| --------------------------------------------------------------------- | -------------------------------------------------- |
+| `loadConfig: no config URL …`                                         | Step 2 — `waterxConfigUrl`                         |
+| `fed set […] has no feed for ticker(s)` (`OracleTickerUnservedError`) | Step 2 — the config's feeds                        |
+| `EMissingPriceSource`                                                 | Step 2 — the fed set is too narrow for that ticker |
+| `LazerApiKeyMissing …`                                                | Step 2 — `pythApiKey`                              |
+| `EAccountNotFound`                                                    | Step 3 — the account id is not on this network     |
+| `EReplayedSignature`                                                  | Step 5 — an envelope was reused across builds      |
 
 ## Verifying an integration
 

package/README.md

@@ -11,22 +11,22 @@ The perp and prediction lines expose builder functions with **colliding names**
 ```ts
 import { WaterXClient } from "@waterx/sdk";
 
-// waterxConfigUrl and oracleSource are REQUIRED — the SDK has no built-in
-// defaults and never reads env. oracleSource: see "Oracle sources" below.
+// waterxConfigUrl is REQUIRED — the SDK has no built-in default and never
+// reads env. The oracle fed set is DERIVED from that config; there is nothing
+// to pick. See "Oracle sources" below.
 const client = await WaterXClient.create({
   network: "TESTNET",
   waterxConfigUrl:
     "https://raw.githubusercontent.com/WaterXProtocol/waterx-config/main/testnet.json",
-  oracleSource: ["pyth_rule", "pyth_lazer_rule"],
-  pythApiKey: process.env.PYTH_API_KEY, // required iff 'pyth_lazer_rule' is listed
+  pythApiKey: process.env.PYTH_API_KEY, // required iff the config wires pyth_lazer_rule
 });
 client.account.createAccount(tx, { alias }); // shared waterx_account + funding (credit/custody)
 client.perp.buildPlaceOrderTx(params); // perpetuals
 client.predict.placeOrder(tx, params); // prediction markets
 // client.perp / client.predict ARE the line clients — sign/execute on them directly:
 //   await client.perp.signAndExecuteTransaction({ transaction: tx, signer })
-// each line can target a different network + URL (oracleSource stays top-level):
-//   WaterXClient.create({ oracleSource: "pyth_rule", perp: { network: "MAINNET", waterxConfigUrl: mainnetUrl }, predict: { network: "TESTNET", waterxConfigUrl: testnetUrl } })
+// each line can target a different network + URL (each derives its own fed set):
+//   WaterXClient.create({ perp: { network: "MAINNET", waterxConfigUrl: mainnetUrl }, predict: { network: "TESTNET", waterxConfigUrl: testnetUrl } })
 ```
 
 > `WaterXClient` is the umbrella entry point. `Client` is kept as a **deprecated alias** for one major cycle.
@@ -68,11 +68,9 @@ import { Transaction } from "@mysten/sui/transactions";
 const client = await WaterXClient.create({
   network: "TESTNET",
   waterxConfigUrl: "https://raw.githubusercontent.com/WaterXProtocol/waterx-config/main/testnet.json",
-  // REQUIRED — single source or a list (the fed set). The set must COVER each
-  // ticker's on-chain weighted rules; testnet majors need both of these today.
-  // Verify with `pnpm oracle:aggregates:testnet`. See "Oracle sources".
-  oracleSource: ["pyth_rule", "pyth_lazer_rule"],
-  pythApiKey: process.env.PYTH_API_KEY, // required iff 'pyth_lazer_rule' is listed
+  // The fed set is derived from this config — nothing to declare. Inspect it
+  // with `pnpm oracle:aggregates:testnet`. See "Oracle sources".
+  pythApiKey: process.env.PYTH_API_KEY, // required iff the config wires pyth_lazer_rule
 });
 const signer = /* your Ed25519Keypair or wallet Signer */;
 const accountId = "0x..."; // wxa account object id — see "First integration"
@@ -123,8 +121,7 @@ walkthrough as one runnable file** — being real code, it is covered by `pnpm l
 
 ```bash
 export WATERX_CONFIG_URL=https://raw.githubusercontent.com/WaterXProtocol/waterx-config/main/testnet.json
-export ORACLE_SOURCE=pyth_rule,pyth_lazer_rule   # step 2 — must cover the ticker's weighted rules
-export PYTH_API_KEY=...                          # required whenever pyth_lazer_rule is listed
+export PYTH_API_KEY=...                          # required iff the config wires pyth_lazer_rule
 pnpm exec tsx examples/quickstart.ts             # simulate-only; WATERX_EXECUTE=1 to sign + send
 ```
 
@@ -133,10 +130,12 @@ pnpm exec tsx examples/quickstart.ts             # simulate-only; WATERX_EXECUTE
 built-in default and the SDK never reads `process.env`: your app reads the URL and passes
 it in. Hardcoding object ids instead is the single most common integration mistake.
 
-**2 — Pick your oracle source(s).** `oracleSource` is required, and the fed set must
-**cover every ticker's on-chain weighted rules** — starving a weighted rule aborts
-`EMissingPriceSource` at simulate. Check what a network actually weights before you wire
-it up:
+**2 — Nothing to pick: the fed set is derived.** Every source the config wires (a
+published package with a non-empty feeds map) is fed. That is what keeps the fed set a
+**superset of every ticker's on-chain weighted rules**, which is the property that
+matters — starving a weighted rule aborts `EMissingPriceSource` at simulate, while
+feeding an unweighted one is dropped harmlessly on chain. Inspect what a network
+weights when you are debugging:
 
 ```bash
 pnpm oracle:aggregates:testnet    # per-ticker aggregator sources + weights
@@ -172,7 +171,7 @@ const accountId = ev ? AccountCreated.parse(ev.bcs).account_object_address : und
 
 → [`examples/actions/action-create-account.ts`](./examples/actions/action-create-account.ts)
 
-**4 — Fund it.** Collateral must sit *inside* the account before an order will fill.
+**4 — Fund it.** Collateral must sit _inside_ the account before an order will fill.
 Deposit is two calls in one PTB — `requestDeposit(coin)` then
 `direct_rule::consume_deposit_direct(req)`.
 
@@ -215,58 +214,64 @@ import { PredictClient } from "@waterx/sdk/prediction";
 
 const waterxConfigUrl =
   "https://raw.githubusercontent.com/WaterXProtocol/waterx-config/main/testnet.json";
-// oracleSource must cover each ticker's weighted rules — see "Oracle sources".
+// The fed set comes from the config — see "Oracle sources".
 const perp = await PerpClient.create("TESTNET", {
   waterxConfigUrl,
-  oracleSource: ["pyth_rule", "pyth_lazer_rule"],
-  pythApiKey: process.env.PYTH_API_KEY, // required iff 'pyth_lazer_rule' is listed
+  pythApiKey: process.env.PYTH_API_KEY, // required iff the config wires pyth_lazer_rule
 }); // or PerpClient.testnet({ ... })
-const predict = await PredictClient.create("TESTNET", { waterxConfigUrl }); // predict line needs no oracle source
+const predict = await PredictClient.create("TESTNET", { waterxConfigUrl }); // predict line has no oracle plane
 ```
 
 Read-only queries use gRPC `simulateTransaction` (no signer) — the `getX` view helpers, e.g. `await perp.simulate(tx)` or `getMarketData(perp, …)`.
 
 ## Oracle sources
 
-ONE **required** client create option, `oracleSource`, names the price-update source(s) — a single value or a **list (the fed set)**. Each source is **self-contained** — it owns its own infra + config and does **not** back-stop any other source. There is **no default source**: a client that has not named its sources fails at creation. The name is source-neutral on purpose: a future source need not be Pyth. The SDK **never reads `process.env`** — each consumer wires it from its own env var, so every environment runs the **same SDK version** and differs only by env:
+The fed set is **derived from the deployment config** — there is no `oracleSource` create option and no `ORACLE_SOURCE` env var. A source is fed when its block is published AND carries at least one feed, so mainnet derives `[pyth_lazer_rule, waterx_rule]` and testnet `[waterx_rule]` with no per-environment wiring at all. Each source remains **self-contained** — it owns its own infra + config and does **not** back-stop any other source.
 
-| Option         | Values                                                                             | What it selects                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| -------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `oracleSource` | `OracleSource \| OracleSource[]` of `'pyth_rule'` \| `'pyth_lazer_rule'` \| `'waterx_rule'` — REQUIRED, no default | The price-update source(s). `'pyth_rule'` = Pyth Core updates (Hermes VAA + per-feed update fees, keyless `hermes.pyth.network`). `'pyth_lazer_rule'` = Pyth Lazer signed updates (ONE `leEcdsa` verify per PTB, no per-feed fees); needs `packages.pyth_lazer_rule` feeds + a `pythApiKey`. `'waterx_rule'` = the first-party WaterX quote-center (Nautilus-TEE, ed25519-signed CEX prices): one signed batch envelope per build, no API key and no per-update fee; needs `packages.waterx_rule` feeds. |
+Why derived rather than declared: the chain arbitrates. Per-ticker weights decide which contributions count, feeding an **unweighted** rule is dropped on-chain, and starving a **weighted** one aborts `EMissingPriceSource`. The failure is one-sided, so a hand-typed list can only err in the fatal direction — the classic being one copied between networks, naming a source that deployment does not carry. The config cannot, because it _is_ what wires the rules. Retired blocks are inert: `pyth_rule` and `pyth_sponsor_rule` still sit in the live configs, and neither is an `ORACLE_SOURCES` member, so neither can ever be derived.
 
-**Multi-source fed sets.** With a list, ONE build fetches and feeds EVERY listed source's data in the same PTB; the chain's per-ticker aggregator **weight tables** decide which contributions count — feeding an unweighted rule's price is dropped on-chain, while starving a weighted rule aborts. That asymmetry is what makes weight migrations (Core→Pro, Pyth↔waterx coexistence) safe: keep the list a **superset** of every ticker's weighted rule set and flip weights per ticker at any time — an env edit, never an SDK release. (One caveat: waterx's feed call burns a per-symbol signed-timestamp high-water mark regardless of weights — see the replay note below.)
+| Source            | Fed when                                           | What it is                                                                                                                                                                |
+| ----------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pyth_lazer_rule` | `packages.pyth_lazer_rule` is published with feeds | Pyth Lazer signed updates — ONE `leEcdsa` verify per PTB, no per-feed fees. Auth-first, so it needs a `pythApiKey`.                                                       |
+| `waterx_rule`     | `packages.waterx_rule` is published with feeds     | The first-party WaterX quote-center (Nautilus-TEE, ed25519-signed CEX prices): one signed Merkle leaf per ticker, batch-envelope fallback. No API key, no per-update fee. |
 
-**No cross-source fallback, no feeds guard at init.** Construction rejects an empty/nullish `oracleSource` **and any value outside `ORACLE_SOURCES`** (a legacy `'core'` / `'pyth'` string fails at `create`), but a listed source whose feed for a requested ticker is absent is **not** an error at client creation — the build fails at **tx-build** only when **no** listed source serves the ticker (constant-only tickers, which need no price update, are exempt). A present-but-wrong feed id is not validated by the SDK; it aborts on-chain at dry-run.
+`deriveOracleSources(config)` is exported if you need the answer before a client exists (e.g. to pair with `missingOracleCredentials` in a boot assert); `client.oracleSources` is the same value on a live client. (`pyth_rule` — Pyth Core / Hermes — was RETIRED in 5.0.0.)
 
-Every source's external infra is a **rule-owned per-network table**, never deployment-overridable and never in the config JSON: `PYTH_CORE_INFRA` (`src/oracle/pyth.ts` — Pyth state ids + the keyless Core Hermes endpoint, read-plane accessor `pythCoreHermesEndpoint(network)`), `LAZER_INFRA` (`src/oracle/rules/pyth-lazer-rule.ts`), `WATERX_INFRA` (`src/oracle/rules/waterx-rule.ts` — testnet `quote-center-staging.waterx.app` / mainnet `quote-center.waterx.app`, accessor `waterxQuoteCenterEndpoint(network)`). For **price READS** under a fed set without `pyth_rule`, the documented Pyth Pro base (`pythProHermesEndpoint()` — identical for every subscriber, auth via the Bearer key) applies: resolve the read endpoint with `resolveHermesReadEndpoint(network, sources, override?)` instead of branching by hand, and pair it with `resolveOracleReadPlan` for the per-source served-sets/ids. `client.pyth` is the access-only `PythAccessConfig` — just the caller-supplied `pythApiKey` / `pythFetch` create options (a secret has no place in a public CDN JSON); `client.waterx` is likewise `WaterxAccessConfig` (`waterxEndpoint` / `waterxFetch` overrides only; fetch policy resolves **`waterxFetch` → built-in defaults** — deliberately no `pythFetch` fallback, sources never share config). See the browser/CORS note below.
+**Multi-source fed sets.** When the config wires more than one, ONE build fetches and feeds EVERY derived source's data in the same PTB; the chain's per-ticker aggregator **weight tables** decide which contributions count. That asymmetry is what makes weight migrations (Lazer↔waterx coexistence) safe: the derived set is a superset of every ticker's weighted rule set by construction, so weights flip per ticker at any time — a config edit, never an SDK release and never an env edit. (One caveat: waterx's feed call burns a per-symbol signed-timestamp high-water mark regardless of weights — see the replay note below.)
+
+**No cross-source fallback.** Construction fails only when the config wires **no** price-update source at all (nothing could ever be priced). A derived source whose feed for a particular ticker is absent is not an error: `refreshOraclePrices` **skips** that ticker and reports it in `OracleRefreshSummary.skipped`, so a sweep over 30 markets does not lose 29 because the 30th is unconfigured. The `build*Tx` composers then fail closed with `OracleTickerUnservedError` on the tickers their specific action depends on — the traded market plus collateral, or **every pool asset** for WLP — unless you pass `allowUnrefreshedPrices: true`. Constant-only tickers need no price update and are exempt. A present-but-wrong feed id is not validated by the SDK; it aborts on-chain at dry-run.
+
+Every source's external infra is a **rule-owned per-network table**, never deployment-overridable and never in the config JSON: `LAZER_INFRA` (`src/oracle/rules/pyth-lazer-rule.ts` — Lazer HTTP endpoint, verifier package, per-network channel), `WATERX_INFRA` (`src/oracle/rules/waterx-rule.ts` — testnet `quote-center-staging.waterx.app` / mainnet `quote-center.waterx.app`, accessor `waterxQuoteCenterEndpoint(network)`). For **price READS**, every source reads through its OWN feeds namespace (write set == read set by construction): resolve the per-source served-set/ids with `resolveOracleReadPlan` (`lazer` = integer Lazer ids, `quote_center` = tickers; `readPlanTickers` flattens either) and execute the plan with `readLazerPrices` / `readQuoteCenterPrices` (`src/oracle/read-prices.ts`). `client.pyth` is the access-only `PythAccessConfig` — just the caller-supplied `pythApiKey` / `pythFetch` create options (a secret has no place in a public CDN JSON); `client.waterx` is likewise `WaterxAccessConfig` (`waterxEndpoint` / `waterxFetch` overrides only; fetch policy resolves **`waterxFetch` → built-in defaults** — deliberately no `pythFetch` fallback, sources never share config). See the browser/CORS note below.
 
 ```ts
-// Per-environment wiring — the consumer owns the env var, not the SDK.
-// parseOracleSourceList is THE canonical parser (trim, drop empty entries,
-// validate every value, dedupe, throw operator-actionably) — never a bare
-// split-and-cast, which would hand the strict constructor untrimmed junk.
-import { parseOracleSourceList } from "@waterx/sdk/oracle";
+// Need the fed set before a client exists (boot asserts, health checks)?
+import { deriveOracleSources, missingOracleCredentials } from "@waterx/sdk/oracle";
 
+// Per-environment wiring is just the config URL: point an environment at a
+// different config and its fed set follows.
 const perp = await PerpClient.create(network, {
   waterxConfigUrl,
-  oracleSource: parseOracleSourceList(process.env.ORACLE_SOURCE), // REQUIRED; comma list = the fed set
-  pythApiKey: process.env.PYTH_API_KEY, // required iff 'pyth_lazer_rule' is listed (Lazer is auth-first)
+  pythApiKey: process.env.PYTH_API_KEY, // required iff that config wires pyth_lazer_rule (auth-first)
+});
+
+const missing = missingOracleCredentials(deriveOracleSources(config), {
+  pythApiKey: process.env.PYTH_API_KEY,
 });
 ```
 
-This is the coexistence rollout pattern: staging lists every source under migration (`ORACLE_SOURCE=pyth_rule,pyth_lazer_rule,waterx_rule` + `PYTH_API_KEY`) while production stays single-value (`ORACLE_SOURCE=pyth_rule`) until its weight tables move — flipping an environment is an env-var change, never an SDK release.
+This is the coexistence rollout pattern: staging's config wires every source under migration while production's trails until its weight tables move — flipping an environment is a **config** change, never an env edit and never an SDK release.
 
 ### Adding an oracle source (runbook)
 
-Every source plugs in the same way — routing is driven **only** by the client's `oracleSource` option (never a config `enabled` flag, never `process.env`):
+Every source plugs in the same way — routing is driven **only** by what the deployment config wires (never a config `enabled` flag, never `process.env`):
 
-1. **Implement `PriceUpdateRule`** in `src/oracle/rules/<name>-rule.ts` — all port fields (`src/oracle/price-update-rule.ts`): `kind`, `requiresFeeSource` (`true` iff the on-chain verify draws a per-update fee — gates the fail-fast fee-source check), `supportedTickers`, `fetchUpdateData`, `narrowUpdateData` (subset a cached whole-universe payload to one build's tickers — a divisible payload returns a per-feed subset, an indivisible one returns itself whole iff fully covered; uncovered ticker → `null` miss), `buildUpdateCalls`.
+1. **Implement `PriceUpdateRule`** in `src/oracle/rules/<name>-rule.ts` — all port fields (`src/oracle/price-update-rule.ts`): `kind`, `credential` (set iff the off-chain fetch needs a caller credential — one object carrying the credential KIND and the rule's OWN error, which the fail-fast pre-check throws and `missingOracleCredentials` reports), `supportedTickers`, `fetchUpdateData`, `narrowUpdateData` (subset a cached whole-universe payload to one build's tickers — a divisible payload returns a per-feed subset, an indivisible one returns itself whole iff fully covered; uncovered ticker → `null` miss), `updateIdentityBySymbol` (iff the on-chain verify is replay-guarded per symbol), `buildUpdateCalls`.
 2. **Register it** in `src/oracle/rule-registry.ts` (`DEFAULT_RULES`) under a new `OracleSource` value — added to `ORACLE_SOURCES` in `price-update-rule.ts` (the union derives from that list; a registry test pins every listed value to a registered rule).
 3. **Publish the on-chain rule package** — its config entry (package ids, per-ticker `feeds`) arrives via the normal `waterx-config` deploy pipeline; type it in `OraclePackages` (`src/oracle/config.ts`).
 4. **Add SDK infra constants** if the source needs external infra that is not part of the config JSON (API endpoints, verifier packages, state objects) — a **rule-owned** per-network table inside the rule's own file, mirroring `LAZER_INFRA` / `WATERX_INFRA` (never on the shared client, never in `oracle/config.ts`). Wire its read-plane served-set/ids into `resolveOracleReadPlan` (`src/oracle/read-plane.ts`).
-5. **Consumers flip `oracleSource`** per environment — no consumer code change, no SDK re-release.
+5. **Publish the block in the config** for the deployments that should feed it — every client on that config picks it up. No consumer code change, no env edit, no SDK re-release.
 
-The in-house `waterx_rule` (ed25519 enclave-signed CEX prices, `src/oracle/rules/waterx-rule.ts`) took exactly this path: it pulls one signed Merkle **leaf** per requested ticker from the quote-center (`GET /v1/quotes/leaves?symbols=…`, public read — no auth), then verifies **and** feeds in a single `waterx_rule::collect_single_with_proof` call per collector, so it emits no shared verify step. Each leaf carries its own membership proof and the enclave's signature over the snapshot root, so a PTB rebuilds exactly ONE price item however wide the snapshot was. Against a quote-center with no leaf route (404) it falls back to the older shape — one signature over a whole batch (`GET /v1/quotes/update`) fed through `collect_batch_latest`, which is indivisible and therefore has to rebuild *every* item in the batch in-PTB just to use one symbol's price.
+The in-house `waterx_rule` (ed25519 enclave-signed CEX prices, `src/oracle/rules/waterx-rule.ts`) took exactly this path: it pulls one signed Merkle **leaf** per requested ticker from the quote-center (`GET /v1/quotes/leaves?symbols=…`, public read — no auth), then verifies **and** feeds in a single `waterx_rule::collect_single_with_proof` call per collector, so it emits no shared verify step. Each leaf carries its own membership proof and the enclave's signature over the snapshot root, so a PTB rebuilds exactly ONE price item however wide the snapshot was. Against a quote-center with no leaf route (404) it falls back to the older shape — one signature over a whole batch (`GET /v1/quotes/update`) fed through `collect_batch_latest`, which is indivisible and therefore has to rebuild _every_ item in the batch in-PTB just to use one symbol's price.
 
 On-chain, both entries dispose of failures identically: a **freshness** miss abstains (the other weighted rules cover), and so does a **replayed** signed timestamp (the per-symbol high-water mark of audit F-014 — already recorded means the chain already holds a price at least this fresh, so concurrent builds sharing one snapshot no longer kill each other; only the single-rule `feed_*` entries abort on a replay). A config mismatch, a bad signature, or a signed timestamp **ahead of the on-chain `Clock`** aborts.
 
@@ -275,7 +280,6 @@ On-chain, both entries dispose of failures identically: a **freshness** miss abs
 > ```ts
 > const perp = await PerpClient.create(network, {
 >   waterxConfigUrl,
->   oracleSource: "waterx_rule",
 >   // absolute URL on your own origin; its base path is PRESERVED, so this
 >   // fetches https://app.example/api/quote-center/v1/quotes/leaves
 >   waterxEndpoint: "https://app.example/api/quote-center",
@@ -283,7 +287,7 @@ On-chain, both entries dispose of failures identically: a **freshness** miss abs
 > });
 > ```
 >
-> Unset, `waterxEndpoint` falls back to the rule-owned `WATERX_INFRA[network]` and `waterxFetch` to the built-in policy (15s timeout, 2 retries) — there is deliberately no `pythFetch` fallback. Both are inert under the Pyth sources. They are also top-level options on the umbrella `WaterXClient.create({ oracleSource, waterxEndpoint, waterxFetch, … })`, which forwards them to the perp line. Node/keeper consumers are unaffected by CORS either way.
+> Unset, `waterxEndpoint` falls back to the rule-owned `WATERX_INFRA[network]` and `waterxFetch` to the built-in policy (15s timeout, 2 retries) — there is deliberately no `pythFetch` fallback. Both are inert under the Pyth sources. They are also top-level options on the umbrella `WaterXClient.create({ waterxEndpoint, waterxFetch, … })`, which forwards them to the perp line. Node/keeper consumers are unaffected by CORS either way.
 
 ## Recipes & full surface
 
@@ -294,39 +298,39 @@ To avoid doc drift, per-action usage lives in maintained, lint-checked code rath
 - **Prediction recipes:** [`test/prediction/e2e/`](./test/prediction/e2e) — the live reference for `client.predict.*` flows.
 - **Authoritative export list:** [`src/perp/index.ts`](./src/perp/index.ts) (perp) and [`src/prediction/index.ts`](./src/prediction/index.ts) — clients, builders, view helpers, BCS types, and `*Calls` generated namespaces. The package root (`.`) is [`src/sdk.ts`](./src/sdk.ts) (umbrella + flat-perp re-export); the shared base is published at `@waterx/sdk/account` and `@waterx/sdk/oracle`.
 
-Perp `build*Tx` helpers are oracle-backed (`async`; they refresh prices before the call) — through whichever source `oracleSource` selects, not Pyth specifically. The oracle layer (sources, rules, refresh) lives in [`src/oracle/`](./src/oracle).
+Perp `build*Tx` helpers are oracle-backed (`async`; they refresh prices before the call) — through whichever sources the deployment config wires, not Pyth specifically. The oracle layer (sources, rules, refresh) lives in [`src/oracle/`](./src/oracle).
 
 ## Troubleshooting
 
 Every row below is a message the SDK or the chain actually emits. Simulate first — all of
 these surface at simulate, before you spend gas.
 
-| Message | What it means, and what to do |
-| ------- | ------------------------------ |
-| `loadConfig: no config URL — pass opts.waterxConfigUrl` | `waterxConfigUrl` is unset; there is no default and no env fallback. Read the URL in your app and pass it to `create()`. |
-| `oracleSource is REQUIRED and must name at least one of …` | Missing, empty, or a retired value (`'core'`, `'pyth'`). Parse env with `parseOracleSourceList`, not a bare `split`. |
-| `oracleSource [...] has no feed configured for ticker(s): …` | No listed source serves that ticker in this deployment. Raised at **tx-build**, not at client creation. Add the feed under a listed source, or list a source that serves it. Constant-only tickers are exempt. |
-| `EMissingPriceSource` (Move abort in `aggregator::remove_outliers`) | The fed set does not cover that ticker's on-chain weighted rules — starving a weighted rule aborts, feeding an unweighted one is a no-op. Run `pnpm oracle:aggregates:testnet` and widen `oracleSource` to a superset. |
-| `LazerApiKeyMissing: pyth_lazer_rule requires a Pyth Lazer access token` | `'pyth_lazer_rule'` is listed but `pythApiKey` was not passed. The SDK never reads `process.env` for it — pass it at client creation. |
-| `EAccountNotFound` (Move abort in `account::borrow_account`) | The `accountId` does not exist on this network — usually a fixture from another deployment, or a Sui address used where a wxa account id belongs. Create one with `client.account.createAccount`. |
-| `EReplayedSignature` | One `waterx_rule` envelope was fed twice for the same symbol; a signed timestamp is single-use per symbol (audit F-014). Fetch per build — never share one across concurrent builds. |
-| CORS failure fetching the quote-center (browser only) | `waterx_rule` fetches from the page and your origin is not on the allowlist. Point `waterxEndpoint` at a same-origin proxy; its base path is preserved. Node and keeper consumers are unaffected. |
-| Ticker lookups return nothing | Wrong format. Tickers are concatenated — `BTCUSD`, never `BTC/USD` or `BTC`. Canonical list: the config JSON's `markets` keys. |
-| Prices off by 10⁹, or an order fills far from the intended level | A human-readable number was passed where a raw 1e9-scaled `u64` belongs. Wrap in `rawPrice()`. Exception: view `basePriceUsd` args take a **whole-dollar** u64 — use `parseWholeDollarU64`. |
-| `… has no feed configured for ticker(s)` on `MAINNET` with a fed set copied from testnet | The two networks configure **different sources**. Today's `mainnet.json` carries `pyth_rule` (plus `constant_rule` for `USDCUSD`) and **no** `pyth_lazer_rule` / `waterx_rule` block, so an `ORACLE_SOURCE` naming only those serves nothing there. Listing an unconfigured source *alongside* `pyth_rule` is harmless — it contributes no tickers. Confirm per network with `pnpm oracle:aggregates:mainnet`. |
+| Message                                                                    | What it means, and what to do                                                                                                                                                                                                                                                                                                                                       |
+| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `loadConfig: no config URL — pass opts.waterxConfigUrl`                    | `waterxConfigUrl` is unset; there is no default and no env fallback. Read the URL in your app and pass it to `create()`.                                                                                                                                                                                                                                            |
+| `this deployment's config wires no price-update source …`                  | The loaded config publishes no `pyth_lazer_rule` / `waterx_rule` block with feeds, so nothing could ever be priced. Raised at client creation. Check you loaded the config you meant to.                                                                                                                                                                            |
+| `fed set [...] has no feed for ticker(s): …` (`OracleTickerUnservedError`) | No derived source serves a ticker this build depends on. `refreshOraclePrices` itself SKIPS such tickers; the `build*Tx` composers raise this for the ones their action needs (traded ticker + collateral, or every pool asset for WLP). Add the feed, or pass `allowUnrefreshedPrices: true` to build anyway. Constant-only tickers are exempt.                    |
+| `EMissingPriceSource` (Move abort in `aggregator::remove_outliers`)        | The fed set does not cover that ticker's on-chain weighted rules — starving a weighted rule aborts, feeding an unweighted one is a no-op. Run `pnpm oracle:aggregates:testnet`, then publish the missing source's feeds in the config so it is derived.                                                                                                             |
+| `LazerApiKeyMissing: pyth_lazer_rule requires a Pyth Lazer access token`   | The config wires `pyth_lazer_rule` but `pythApiKey` was not passed. The SDK never reads `process.env` for it — pass it at client creation.                                                                                                                                                                                                                          |
+| `EAccountNotFound` (Move abort in `account::borrow_account`)               | The `accountId` does not exist on this network — usually a fixture from another deployment, or a Sui address used where a wxa account id belongs. Create one with `client.account.createAccount`.                                                                                                                                                                   |
+| `EReplayedSignature`                                                       | A `waterx_rule` signed timestamp was replayed on a **single-rule `feed_*`** entry, where it aborts. The `build*Tx` composers do NOT use those — they feed through `collect_*`, where a replay ABSTAINS (audit F-014's high-water mark means the chain already holds a price at least that fresh). If you see this, a custom PTB is calling a `feed_*` leg directly. |
+| CORS failure fetching the quote-center (browser only)                      | `waterx_rule` fetches from the page and your origin is not on the allowlist. Point `waterxEndpoint` at a same-origin proxy; its base path is preserved. Node and keeper consumers are unaffected.                                                                                                                                                                   |
+| Ticker lookups return nothing                                              | Wrong format. Tickers are concatenated — `BTCUSD`, never `BTC/USD` or `BTC`. Canonical list: the config JSON's `markets` keys.                                                                                                                                                                                                                                      |
+| Prices off by 10⁹, or an order fills far from the intended level           | A human-readable number was passed where a raw 1e9-scaled `u64` belongs. Wrap in `rawPrice()`. Exception: view `basePriceUsd` args take a **whole-dollar** u64 — use `parseWholeDollarU64`.                                                                                                                                                                         |
+| A ticker prices on one network but not another                             | The two networks wire **different sources**, and the fed set follows the config — mainnet derives `[pyth_lazer_rule, waterx_rule]`, testnet `[waterx_rule]`. This is the drift a hand-declared list used to cause and derivation removes. Confirm per network with `pnpm oracle:aggregates:mainnet`.                                                                |
 
 ## Documentation map
 
-| Document                                                     | What it answers                                                            |
-| ------------------------------------------------------------ | -------------------------------------------------------------------------- |
-| [`SKILLS.md`](./SKILLS.md)                                   | The fixed integration flow, for an agent or a developer                    |
-| [`examples/README.md`](./examples/README.md)                 | Every runnable perp recipe, one file per entry point                       |
-| [`CHANGELOG.md`](./CHANGELOG.md)                             | What changed per release — **read before upgrading** (see versioning note) |
-| [`PACKAGES.md`](./PACKAGES.md)                               | The Move packages behind the SDK                                           |
-| [`CLAUDE.md`](./CLAUDE.md)                                   | Architecture and contract surface, for people hacking on the SDK           |
-| [`test/perp/README.md`](./test/perp/README.md)               | Perp test tiers, fixtures, and known skips                                 |
-| [`test/prediction/README.md`](./test/prediction/README.md)   | Prediction test tiers and the live `client.predict.*` reference            |
-| [`waterx-config`](https://github.com/WaterXProtocol/waterx-config) | The canonical deployment JSON schema                                  |
+| Document                                                           | What it answers                                                            |
+| ------------------------------------------------------------------ | -------------------------------------------------------------------------- |
+| [`SKILLS.md`](./SKILLS.md)                                         | The fixed integration flow, for an agent or a developer                    |
+| [`examples/README.md`](./examples/README.md)                       | Every runnable perp recipe, one file per entry point                       |
+| [`CHANGELOG.md`](./CHANGELOG.md)                                   | What changed per release — **read before upgrading** (see versioning note) |
+| [`PACKAGES.md`](./PACKAGES.md)                                     | The Move packages behind the SDK                                           |
+| [`CLAUDE.md`](./CLAUDE.md)                                         | Architecture and contract surface, for people hacking on the SDK           |
+| [`test/perp/README.md`](./test/perp/README.md)                     | Perp test tiers, fixtures, and known skips                                 |
+| [`test/prediction/README.md`](./test/prediction/README.md)         | Prediction test tiers and the live `client.predict.*` reference            |
+| [`waterx-config`](https://github.com/WaterXProtocol/waterx-config) | The canonical deployment JSON schema                                       |
 
 ## Development
 
@@ -337,16 +341,16 @@ pnpm install
 pnpm build
 ```
 
-| Command                        | Use                                                        |
-| ------------------------------ | ---------------------------------------------------------- |
-| `pnpm typecheck`               | Typecheck the whole tree                                   |
-| `pnpm docs:check`              | Resolve every relative link in the docs                    |
-| `pnpm test` / `pnpm test:unit` | Unit tests (perp + prediction)                             |
-| `pnpm test:e2e`                | Testnet simulate e2e (perp + prediction)                   |
-| `pnpm test:integration`        | On-chain integration (needs `SUI_PRIVATE_KEY`; local-only) |
-| `pnpm lint` / `pnpm format`    | ESLint + Prettier                                          |
-| `pnpm codegen`                 | Regenerate `src/generated` from Move                       |
+| Command                          | Use                                                                      |
+| -------------------------------- | ------------------------------------------------------------------------ |
+| `pnpm typecheck`                 | Typecheck the whole tree                                                 |
+| `pnpm docs:check`                | Resolve every relative link in the docs                                  |
+| `pnpm test` / `pnpm test:unit`   | Unit tests (perp + prediction)                                           |
+| `pnpm test:e2e`                  | Testnet simulate e2e (perp + prediction)                                 |
+| `pnpm test:integration`          | On-chain integration (needs `SUI_PRIVATE_KEY`; local-only)               |
+| `pnpm lint` / `pnpm format`      | ESLint + Prettier                                                        |
+| `pnpm codegen`                   | Regenerate `src/generated` from Move                                     |
 | `pnpm oracle:aggregates:testnet` | Per-ticker aggregator sources + weights (diagnose `EMissingPriceSource`) |
-| `pnpm seed:testnet`            | Seed prediction testnet fixtures (needs `SUI_PRIVATE_KEY`) |
+| `pnpm seed:testnet`              | Seed prediction testnet fixtures (needs `SUI_PRIVATE_KEY`)               |
 
 Tests are split per line under `test/perp/` and `test/prediction/`, each with `unit` / `e2e` / `integration` tiers. See the per-line `README.md` in each.

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

@@ -71,11 +71,9 @@ export interface WithdrawalQueuePackage {
     queue?: string;
 }
 /**
- * Wormhole infra for the cross-chain credit bridge. `state_id` is the same
- * shared Sui Wormhole `State` object Pyth uses (kept in sync with
- * `PYTH_CORE_INFRA[*].wormhole_state_id` in `oracle/pyth.ts`). Override
- * per-deployment via `WaterXConfig.wormhole` if a deployment ever points
- * elsewhere.
+ * Wormhole infra for the cross-chain credit bridge. `state_id` is the shared
+ * Sui Wormhole `State` object for the network. Override per-deployment via
+ * `WaterXConfig.wormhole` if a deployment ever points elsewhere.
  */
 export interface WormholeInfraConfig {
     /** Shared Sui Wormhole `State` object. */

package/dist/cjs/src/account/funding/wormhole.d.ts

@@ -1,8 +1,7 @@
 /**
  * Wormhole / Wormholescan integration for the cross-chain credit bridge.
  *
- * Single source of truth for VAA discovery + (de)serialization — mirrors
- * `oracle/pyth.ts`'s role for Pyth's Hermes endpoint. Two directions:
+ * Single source of truth for VAA discovery + (de)serialization. Two directions:
  *
  *   - Mint (EVM → Sui): fetch the signed VAA for an EVM `Deposit` by
  *     (emitter chain, emitter address, sequence); the raw bytes feed

package/dist/cjs/src/account/funding/wormhole.js

@@ -2,8 +2,7 @@
 /**
  * Wormhole / Wormholescan integration for the cross-chain credit bridge.
  *
- * Single source of truth for VAA discovery + (de)serialization — mirrors
- * `oracle/pyth.ts`'s role for Pyth's Hermes endpoint. Two directions:
+ * Single source of truth for VAA discovery + (de)serialization. Two directions:
  *
  *   - Mint (EVM → Sui): fetch the signed VAA for an EVM `Deposit` by
  *     (emitter chain, emitter address, sequence); the raw bytes feed