@waterx/sdk 4.3.2 → 4.3.3

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

@@ -0,0 +1,219 @@
+---
+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.
+---
+
+# 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 two required options
+
+```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'
+});
+```
+
+**`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.
+
+**`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.
+
+| 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`**    |
+| `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
+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.
+
+Never guess the set — read it off chain:
+
+```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(",")`.
+
+## 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` |
+| `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 |
+
+## 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

@@ -17,7 +17,8 @@ const client = await WaterXClient.create({
   network: "TESTNET",
   waterxConfigUrl:
     "https://raw.githubusercontent.com/WaterXProtocol/waterx-config/main/testnet.json",
-  oracleSource: "pyth_rule",
+  oracleSource: ["pyth_rule", "pyth_lazer_rule"],
+  pythApiKey: process.env.PYTH_API_KEY, // required iff 'pyth_lazer_rule' is listed
 });
 client.account.createAccount(tx, { alias }); // shared waterx_account + funding (credit/custody)
 client.perp.buildPlaceOrderTx(params); // perpetuals
@@ -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,20 @@ 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"
+  // 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
 });
 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 +95,116 @@ 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 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
+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 — 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:
+
+```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,7 +215,12 @@ 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({ ... })
+// oracleSource must cover each ticker's weighted rules — 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
+}); // or PerpClient.testnet({ ... })
 const predict = await PredictClient.create("TESTNET", { waterxConfigUrl }); // predict line needs no oracle source
 ```
 
@@ -143,7 +266,9 @@ Every source plugs in the same way — routing is driven **only** by the client'
 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.
 
-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.
+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.
 
 > **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:
 >
@@ -152,7 +277,7 @@ The in-house `waterx_rule` (ed25519 enclave-signed CEX prices, `src/oracle/rules
 >   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
 > });
@@ -164,22 +289,64 @@ The in-house `waterx_rule` (ed25519 enclave-signed CEX prices, `src/oracle/rules
 
 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).
 
+## 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`. |
+
+## 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
 
+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.

package/SKILLS.md

@@ -0,0 +1,34 @@
+# Skills
+
+Agent Skills shipped with `@waterx/sdk`. A skill is a written procedure an AI coding agent
+loads on demand — the same flow a developer would follow, in a form an agent can execute
+without being re-taught it each session.
+
+[**`waterx-sdk-integration`**](./.claude/skills/waterx-sdk-integration/SKILL.md) is the one
+skill here: it covers integrating the SDK into an app, keeper, or bot. Its frontmatter
+`description` states exactly when it triggers.
+
+## Using it in this repo
+
+Nothing to do. Claude Code discovers `.claude/skills/` automatically; ask for the skill by
+name, or just describe an integration task and it loads.
+
+## Using it in your own repo
+
+The skill ships inside the published package, so copy it out of `node_modules`:
+
+```bash
+mkdir -p .claude/skills
+cp -r node_modules/@waterx/sdk/.claude/skills/waterx-sdk-integration .claude/skills/
+```
+
+Agents other than Claude Code can read the file directly — it is plain Markdown with a
+YAML header, and nothing in it is Claude-specific.
+
+Re-copy after upgrading the SDK; the skill tracks the API surface and changes with it.
+
+## For humans
+
+The skill is readable on its own and doubles as an integration checklist. If you are
+reading rather than delegating, [`README.md`](./README.md) covers the same ground with
+more prose — start with [First integration](./README.md#first-integration).