@waterx/sdk 4.3.2 → 5.0.0

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

@@ -0,0 +1,225 @@
+---
+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 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.
+
+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
+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()` |
+
+The umbrella exposes three namespaces: `client.account` (shared wxa account + funding),
+`client.perp`, `client.predict`. The two lines have colliding builder names
+(`placeOrder`, `deposit`), which is why they are namespaced rather than flat.
+
+**All factories are async** — they fetch deployment config.
+
+```bash
+pnpm add @waterx/sdk @mysten/sui @mysten/bcs   # the two Mysten packages are peers
+```
+
+Node ≥ 22. ESM and CJS both resolve.
+
+## Step 2 — Supply the config URL
+
+```ts
+import { WaterXClient } from "@waterx/sdk";
+
+const client = await WaterXClient.create({
+  network: "TESTNET",
+  waterxConfigUrl: process.env.WATERX_CONFIG_URL, // REQUIRED — no default, no env fallback
+  pythApiKey: process.env.PYTH_API_KEY, // required iff the config wires pyth_lazer_rule
+});
+```
+
+**`waterxConfigUrl`** points at the canonical
+[`waterx-config`](https://github.com/WaterXProtocol/waterx-config) JSON. It is fetched
+as-is — the SDK appends no `<network>.json` and no git ref. Your app reads the env var;
+the SDK never does. Look up ids through the client (`client.perp.getMarket(ticker)`,
+`client.perp.creditType()`, `client.perp.wlpType()`) rather than hardcoding them.
+
+**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_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 |
+
+(`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. 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.
+
+Inspect what a network actually weights when you are debugging:
+
+```bash
+pnpm oracle:aggregates:testnet   # per-ticker aggregator sources + weights
+```
+
+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
+
+Every trading call needs a `waterx_account` account id. One account serves both lines.
+It is **not** a Sui address — it is an object id returned by `create_account` and emitted
+in the `AccountCreated` event.
+
+```ts
+import { Transaction } from "@mysten/sui/transactions";
+import { AccountCreated } from "@waterx/sdk/generated/waterx_account/events";
+
+const tx = new Transaction();
+client.account.createAccount(tx, { alias: "alice" });
+const exec = await client.perp.signAndExecuteTransaction({ transaction: tx, signer });
+const digest = exec.Transaction?.digest ?? "";
+
+// The id is NOT a builder return value — read it back off the digest. Decode the
+// event's `bcs`, never its `json`: only the BCS layout is the Move struct itself.
+// (`as const` is load-bearing — it is what types `events` as present.)
+const res = await client.perp.grpcClient.getTransaction({
+  digest,
+  include: { events: true } as const,
+});
+const ev = res.Transaction?.events?.find((e) => e.eventType.endsWith("::events::AccountCreated"));
+const accountId = ev ? AccountCreated.parse(ev.bcs).account_object_address : undefined; // persist
+```
+
+A **simulate emits the same `AccountCreated` event but creates nothing** — the address
+in a dry run's events is not on chain and reusing it aborts `EAccountNotFound`. Only read
+an id back after a real execute. Runnable version:
+`accountIdFromDigest` in `examples/_shared.ts`.
+
+## Step 4 — Fund it
+
+Collateral must sit **inside** the account. Depositing is two calls in one PTB:
+`requestDeposit(coin)` returns a `DepositRequest` hot potato, then
+`direct_rule::consume_deposit_direct(req)` finalizes it. Leaving out the second call is a
+build error, not a silent no-op.
+
+Cross-chain CREDIT (`credit.ts`) and the native PSM (`custody.ts`) are the other funding
+routes.
+
+## Step 5 — Build → simulate → execute
+
+Builders are **build-only**: they return or mutate a `Transaction`. Signing stays with
+you — a keypair, or a browser wallet.
+
+```ts
+import { rawPrice } from "@waterx/sdk/perp";
+
+const tx = await client.perp.buildPlaceOrderTx({
+  ticker: "BTCUSD",
+  collateralType: client.perp.creditType(),
+  accountId,
+  main: {
+    isLong: true,
+    isStopOrder: false,
+    reduceOnly: false,
+    size: rawPrice(0.001),
+    triggerPrice: undefined, // omit ⇒ market order
+    acceptablePrice: rawPrice(120_000), // slippage cap
+    collateralAmount: 5_000_000n,
+  },
+  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.signAndExecuteTransaction({ transaction: tx, signer });
+```
+
+`build*Tx` helpers are **async** because they prepend the oracle refresh legs. The
+low-level `*Request` builders are sync and do not refresh — pair them with
+`executeTrading` in the same PTB if you compose by hand.
+
+There is no `open_position_request`. A market order is a limit order with
+`triggerPrice: undefined` and a non-zero `acceptablePrice`; a keeper fills it.
+
+## Step 6 — Read state
+
+Reads are `simulateTransaction` + BCS decode: no signer, no gas, zero-address sender.
+
+```ts
+const positions = await client.perp.getAccountPositions({
+  ticker: "BTCUSD",
+  accountObjectAddress: accountId,
+  basePriceUsd: 0n,
+});
+```
+
+Returned structs keep their **snake_case** Move field names
+(`account_object_address`, `create_timestamp`) — use them as-is.
+
+## Red flags
+
+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.)
+- **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.
+- **Reusing one `waterx_rule` envelope across concurrent builds for the same symbol.**
+  A signed timestamp is single-use per symbol and the second one aborts
+  `EReplayedSignature` — weight-independent (audit F-014). Fetch per build.
+- **Expecting a fallback between oracle sources.** There is none. Sources are
+  self-contained; an absent feed fails at tx-build.
+- **Reaching for `process.env` inside SDK calls.** Read env at your app's boundary and
+  pass values in.
+- **Assuming SemVer.** This package may ship a breaking change in a patch. Pin exact and
+  read the CHANGELOG before upgrading.
+
+## Aborts and errors
+
+Which step a failure sends you back to. The **full messages, causes, and fixes live in
+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`                         |
+| `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
+
+1. `client.perp.simulate(tx)` returns without `FailedTransaction` for one order build.
+2. A read path returns real rows for a funded account.
+3. The fed set covers every ticker you trade — cross-check `pnpm oracle:aggregates`.
+4. Only then execute, and confirm the digest.
+
+## Reference
+
+- Runnable walkthrough: `examples/quickstart.ts`
+- Every perp recipe, one file per entry point: `examples/`
+- Prediction reference flows: `test/prediction/e2e/`
+- Authoritative export lists: `src/perp/index.ts`, `src/prediction/index.ts`
+- Architecture and contract surface: `CLAUDE.md`

package/README.md

@@ -11,21 +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",
+  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.
@@ -41,11 +42,20 @@ Import surfaces:
 ## Install
 
 ```bash
-pnpm install
-pnpm build
+pnpm add @waterx/sdk @mysten/sui @mysten/bcs
 ```
 
-Consumers: `pnpm add @waterx/sdk @mysten/sui`
+`@mysten/sui` (`^2.9.0`) and `@mysten/bcs` (`^1.9.0`) are **peer** dependencies — the SDK
+does not bundle them, so your app and the SDK share one Sui client and one BCS registry.
+
+- **Node ≥ 22** (declared in `engines`; CI builds and tests on 24).
+- **ESM and CJS** both resolve, including on every subpath export.
+- **One runtime dependency** (`@noble/hashes`), plus the two peers above.
+- **Browser supported** — see the CORS note under [Oracle sources](#oracle-sources) if you
+  use `waterx_rule`.
+
+Contributor setup (building this repo rather than consuming it) is under
+[Development](#development).
 
 ## Quickstart (unified client)
 
@@ -58,15 +68,18 @@ import { Transaction } from "@mysten/sui/transactions";
 const client = await WaterXClient.create({
   network: "TESTNET",
   waterxConfigUrl: "https://raw.githubusercontent.com/WaterXProtocol/waterx-config/main/testnet.json",
-  oracleSource: "pyth_rule", // REQUIRED — single source or a list (the fed set); see "Oracle sources"
+  // 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"
 
 // --- Perp: place a market order ---
 const tx = await client.perp.buildPlaceOrderTx({
   ticker: "BTCUSD",
   collateralType: client.perp.creditType(),
-  accountId: "0x...", // UserAccount object id (hex)
+  accountId,
   main: {
     isLong: true,
     isStopOrder: false,
@@ -80,13 +93,117 @@ const tx = await client.perp.buildPlaceOrderTx({
 await client.perp.signAndExecuteTransaction({ transaction: tx, signer });
 
 // --- Prediction: same pattern under client.predict ---
+// Preconditions: `accountId` is a wxa account registered with the prediction
+// protocol and holding settlement collateral; `marketId` is an OPEN market.
+// Object ids (globalConfig / marketRegistry / accountRegistry / settlement coin
+// type) are resolved from config — pass them only to override.
 const ptx = new Transaction();
-client.predict.placeOrder(ptx, params);
+client.predict.placeOrder(ptx, {
+  accountId, // payer; `receiverAccountId` defaults to this
+  marketId: "0x...", // market id bytes or 0x-hex
+  selection: "YES", // "YES" | "NO"
+  maxSpend: 1_000_000n, // cap in settlement-coin base units
+  minShares: 1n, // fill floor — chain asserts filled_shares >= this; 0 accepts any fill
+  priceCapBps: 5_000n, // max price per share, bps of the 1-unit payout; MUST be <= 10_000
+  expiryTs: BigInt(Date.now() + 60_000), // ms epoch
+});
 await client.predict.signAndExecuteTransaction({ transaction: ptx, signer });
 ```
 
 > Account creation is shared: `client.account.*` builds accounts via the one on-chain `waterx_account` system (perp-backed), so an account created through `client.account.createAccount` is usable by both `client.perp.*` and `client.predict.*`. (On split-network setups `client.account` follows the perp line — reach the predict line's generic account builders via the `prediction` namespace.)
 
+## First integration
+
+The quickstart above starts from an `accountId` you already have. If you have none yet,
+this is the whole arc. **[`examples/quickstart.ts`](./examples/quickstart.ts) is this
+walkthrough as one runnable file** — being real code, it is covered by `pnpm lint` and
+`pnpm typecheck`, so the API it exercises cannot go stale unnoticed:
+
+```bash
+export WATERX_CONFIG_URL=https://raw.githubusercontent.com/WaterXProtocol/waterx-config/main/testnet.json
+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
+```
+
+**1 — Get a config URL.** Every chain-specific id comes from the canonical
+[`waterx-config`](https://github.com/WaterXProtocol/waterx-config) JSON. There is no
+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 — 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
+```
+
+Weights are on-chain state that changes without an SDK release, so read them rather than
+trusting any list written here. [Oracle sources](#oracle-sources) has the full model.
+
+**3 — Create a wxa account.** One account serves both product lines; every trading call
+needs one. The id is **not** a builder return value — it lands in the `AccountCreated`
+event, so read it back off the digest, then treat it as the user's durable handle. (A
+simulate emits the same event but creates nothing; only read an id back after a real
+execute.)
+
+```ts
+import { Transaction } from "@mysten/sui/transactions";
+import { AccountCreated } from "@waterx/sdk/generated/waterx_account/events";
+
+const tx = new Transaction();
+client.account.createAccount(tx, { alias: "alice" });
+const exec = await client.perp.signAndExecuteTransaction({ transaction: tx, signer });
+const digest = exec.Transaction?.digest ?? "";
+
+// Decode the event's `bcs`, never its `json` — only the BCS layout is the Move
+// struct. (`as const` is load-bearing: it is what types `events` as present.)
+const res = await client.perp.grpcClient.getTransaction({
+  digest,
+  include: { events: true } as const,
+});
+const ev = res.Transaction?.events?.find((e) => e.eventType.endsWith("::events::AccountCreated"));
+const accountId = ev ? AccountCreated.parse(ev.bcs).account_object_address : undefined;
+```
+
+→ [`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.
+Deposit is two calls in one PTB — `requestDeposit(coin)` then
+`direct_rule::consume_deposit_direct(req)`.
+
+→ [`examples/actions/action-request-deposit.ts`](./examples/actions/action-request-deposit.ts)
+· cross-chain CREDIT and the native PSM are in
+[`src/account/funding/credit.ts`](./src/account/funding/credit.ts) and
+[`src/account/funding/custody.ts`](./src/account/funding/custody.ts)
+
+**5 — Build, simulate, then execute.** Builders are **build-only**: they return or mutate
+a `Transaction` and never sign. Always simulate first — that is where a bad fed set, an
+unfunded account, or a stale id surfaces, for free.
+
+```ts
+const tx = await client.perp.buildPlaceOrderTx({ ... });   // async: prepends oracle legs
+tx.setSender(address);
+const result = await client.perp.simulate(tx);             // no signer, no gas
+await client.perp.signAndExecuteTransaction({ transaction: tx, signer });
+```
+
+**6 — Read state back.** Reads are `simulateTransaction` + BCS decode — no signer, no gas,
+zero-address sender.
+
+```ts
+const positions = await client.perp.getAccountPositions({
+  ticker: "BTCUSD",
+  accountObjectAddress: accountId,
+  basePriceUsd: 0n, // WHOLE-DOLLAR u64 (not rawPrice); 0n zero-bases the PnL fields
+});
+```
+
+→ [`examples/views/`](./examples/views) for every read path
+
 ## Per-line clients
 
 If you only need one line, construct it directly (both factories are **async** — they fetch deployment config; `waterxConfigUrl` is **required**):
@@ -97,89 +214,143 @@ import { PredictClient } from "@waterx/sdk/prediction";
 
 const waterxConfigUrl =
   "https://raw.githubusercontent.com/WaterXProtocol/waterx-config/main/testnet.json";
-const perp = await PerpClient.create("TESTNET", { waterxConfigUrl, oracleSource: "pyth_rule" }); // or PerpClient.testnet({ ... })
-const predict = await PredictClient.create("TESTNET", { waterxConfigUrl }); // predict line needs no oracle source
+// The fed set comes from the config — see "Oracle sources".
+const perp = await PerpClient.create("TESTNET", {
+  waterxConfigUrl,
+  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 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.
+
+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.
+
+| 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. |
 
-| 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. |
+`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.)
 
-**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.)
+**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, 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.
+**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: `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.
+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 enclave-signed batch envelope covering the requested tickers from the quote-center (`GET /v1/quotes/update?symbols=…`, public read — no auth), then verifies **and** feeds in a single `waterx_rule::collect_batch_latest` call per collector, so it emits no shared verify step. On-chain a **freshness** miss abstains (the other weighted rules cover); a config mismatch or bad signature aborts — and so does a **replayed** signed timestamp (`EReplayedSignature`, audit F-014: a signed tuple is single-use per symbol, weight-independent). Consequence: two PTBs carrying the same envelope for the same symbol cannot both land — never share one fetched envelope across concurrent builds for the same symbol.
+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.
 
 > **Browser consumers:** this source fetches the quote-center directly from the page, so the quote-center deployment must return `Access-Control-Allow-Origin` for the app's origin. For an origin that is not on that allowlist, point the SDK at your own proxy instead of the default host — the endpoint and the transport are both overridable at client init:
 >
 > ```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/update
+>   // fetches https://app.example/api/quote-center/v1/quotes/leaves
 >   waterxEndpoint: "https://app.example/api/quote-center",
 >   waterxFetch: { fetchImpl: myFetch, timeoutMs: 8_000 }, // optional custom transport / policy
 > });
 > ```
 >
-> 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
 
 To avoid doc drift, per-action usage lives in maintained, lint-checked code rather than this README:
 
+- **Start here:** [`examples/quickstart.ts`](./examples/quickstart.ts) — the [First integration](#first-integration) walkthrough as one runnable file.
 - **Perp recipes:** [`examples/`](./examples) — ~30 runnable scripts (place orders, WLP mint/redeem, account/delegates, reads). Each uses `buildClient()` + a builder + `simThenMaybeExecute`.
 - **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()`.                                                                                                                                                                                                                                            |
+| `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                                       |
 
 ## Development
 
-| Command                        | Use                                                        |
-| ------------------------------ | ---------------------------------------------------------- |
-| `pnpm typecheck`               | Typecheck the whole tree                                   |
-| `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 seed:testnet`            | Seed prediction testnet fixtures (needs `SUI_PRIVATE_KEY`) |
+Working on the SDK itself (rather than consuming it):
+
+```bash
+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                                     |
+| `pnpm oracle:aggregates:testnet` | Per-ticker aggregator sources + weights (diagnose `EMissingPriceSource`) |
+| `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.