@waterx/sdk 2.1.0 → 2.3.1-dev.0

package/README.md

@@ -1,204 +1,110 @@
 # @waterx/sdk
 
-TypeScript SDK for the WaterX perpetual protocol on Sui: build PTBs with **gRPC** (`@mysten/sui`), run read-only **simulateTransaction** queries, and optional **Pyth** helpers.
+TypeScript SDK for the WaterX protocol on Sui — **two product lines in one package**: **perpetuals** and **prediction markets**. Build PTBs with **gRPC** (`@mysten/sui`), run read-only **simulateTransaction** queries, and optional **Pyth** helpers.
 
-> **ABI note:** PTB entry points follow `contracts/waterx_perp` in this repo. **Read-only `view::*` helpers** resolve the module package from each **shared object’s on-chain type** (so `Market` / `WlpPool` can sit on a newer publish than `GlobalConfig` / `AccountRegistry`). BCS layouts for `MarketSummary`, `PositionInfo`, and `TokenPoolSummary` match the **deployed** `view` structs (see `contracts/waterx_perp/package_summaries/waterx_perp/view.json`). Pin `WaterXConfig` to your environment’s package and object IDs.
+> Package name is `@waterx/sdk` (renamed from `@waterx/perp-sdk` in 2.3.0).
 
-## Install & build
+## Two lines, one package
 
-```bash
-pnpm install
-pnpm build
-```
-
-Consumers:
-
-```bash
-pnpm add @waterx/sdk @mysten/sui
-```
-
-### Breaking changes (WLP high-level builders)
-
-`buildMintWlpTx` and `buildSettleRedeemWlpTx` are **`async`** and return `Promise<Transaction>` (they resolve deposit / redeem coin oracle wiring). Callers must **`await`**:
+The perp and prediction lines expose builder functions with **colliding names** (`placeOrder`, `createAccount`, `deposit`, …), so they are kept in separate namespaces:
 
 ```ts
-const tx = await buildMintWlpTx(client, params);
-const tx2 = await buildSettleRedeemWlpTx(client, { requestId: 1n });
-```
-
-### Size calculation requires explicit price
-
-`buildOpenPositionTx` and `buildPlaceOrderTx` no longer fall back to hardcoded prices when computing position size from leverage. You must provide either **`size`** (exact) or **`approxPrice`** (USD price for leverage math). Omitting both throws.
-
-### Naming: collateral on an open position
-
-Move entry points are `deposit_collateral_request` / `withdraw_collateral_request`. The SDK exposes **`depositCollateral`** / **`withdrawCollateral`** as the preferred names; **`increaseCollateral`** / **`releaseCollateral`** remain as deprecated aliases (same parameters). High-level helpers: **`buildDepositCollateralTx`** / **`buildWithdrawCollateralTx`** (deprecated: `buildIncreaseCollateralTx` / `buildReleaseCollateralTx`).
-
-Withdraw paths take **`collateralAmount`** for the size to pull from margin; **`amount`** is a deprecated alias (if both are passed, `collateralAmount` wins).
-
-### UserAccount address in PTB params
-
-Trading (`openPosition`, `closePosition`, …), account helpers (`depositToAccount`, delegates, …), high-level `build*Tx`, and orders (`placeOrder`, `cancelOrder`) all use **`accountObjectAddress`**: the **UserAccount object id** (hex). Trading paths pass it as `tx.pure.address`; registry calls use `tx.pure.id`. It is **not** a numeric registry index.
-
-`getAccountsByOwner` returns a `string[]` of `accountObjectAddress`es (the on-chain `account::account_ids` view returns `vector<ID>`).
-
-High-level `build*Tx` helpers also accept optional **`collateralTokenType`** (defaults to `WaterXConfig.usdcType`). Only token types wired in `resolveTokenPriceFeed` (`src/tx-builders.ts`) get automatic Pyth updates; extend there when the protocol adds collaterals.
-
----
-
-## Initialize the client
-
-All network I/O uses **gRPC** (`SuiGrpcClient`). Trading helpers require `bucketFrameworkPackageId` (Bucket `bucket_v2_framework` package) so the PTB can call `account::request`.
-
-**Testnet (built-in constants):**
-
-```ts
-import { WaterXClient } from "@waterx/sdk";
-
-const client = WaterXClient.testnet();
-// optional: custom fullnode gRPC URL
-// const client = WaterXClient.testnet({ grpcUrl: "https://fullnode.testnet.sui.io:443" });
-```
-
-**Custom config (any network):**
+import { Client } from "@waterx/sdk";
 
-```ts
-import { createTestnetConfig, WaterXClient, type WaterXConfig } from "@waterx/sdk";
-
-const config: WaterXConfig = {
-  ...createTestnetConfig(),
-  packageId: "0x...", // your deployed waterx_perp package
-  globalConfig: "0x...",
-  // ...all other object IDs and token type strings
-};
-const client = new WaterXClient(config);
+const client = await Client.create({ network: "TESTNET" });
+client.perp.buildPlaceOrderTx(params);   // perpetuals
+client.predict.placeOrder(tx, params);   // prediction markets
+// raw line clients for signing/executing: client.perpClient / client.predictClient
+// each line can target a different network: Client.create({ perp: { network: "MAINNET" }, predict: { network: "TESTNET" } })
 ```
 
----
-
-## Examples
-
-### Read-only: pool summary & WLP metrics
-
-Uses gRPC `simulateTransaction` + BCS (no signer).
-
-```ts
-import { getPoolSummary, getWlpTotalSupply, getWlpTvlUsd, WaterXClient } from "@waterx/sdk";
+Import surfaces:
 
-const client = WaterXClient.testnet();
+| Import | What |
+|--------|------|
+| `@waterx/sdk` | `Client` (unified) + `perp` / `prediction` namespaces. Perp's API is also re-exported flat here (**deprecated** — prefer `client.perp` or the `perp` namespace; removed next major). |
+| `@waterx/sdk/perp` | Perp line: `WaterXClient`, builders, fetch, Pyth/Wormhole utils. |
+| `@waterx/sdk/prediction` | Prediction line: `PredictClient`, builders, fetch, utils. |
 
-const pool = await getPoolSummary(client);
-console.log("LP supply (raw):", pool.totalLpSupply.toString());
-console.log("TVL (u128):", pool.tvlUsd.toString());
+## Install
 
-const supply = await getWlpTotalSupply(client);
-const tvl = await getWlpTvlUsd(client);
+```bash
+pnpm install
+pnpm build
 ```
 
-### Read-only: accounts & position
+Consumers: `pnpm add @waterx/sdk @mysten/sui`
 
-```ts
-import { getAccountsByOwner, getPosition, positionExists, WaterXClient } from "@waterx/sdk";
-
-const client = WaterXClient.testnet();
-const owner = "0x..."; // Sui address
+## Quickstart (unified client)
 
-const accounts = await getAccountsByOwner(client, owner);
-const accountObjectAddress = accounts[0]!;
-
-const market = client.config.btcMarket;
-const has = await positionExists(client, market, 0n);
-if (has) {
-  const pos = await getPosition(client, market, 0n);
-  // `accountObjectAddress` = on-chain `user_address`; `marketIndex` = pool row index (not Market object id).
-  console.log(pos.accountObjectAddress, pos.marketIndex, pos.sizeAmount);
-}
-```
-
-### High-level PTB: open position (Pyth + testnet IDs wired in)
-
-Returns a `Transaction` you sign and execute with the same client.
+`Client.create()` loads each line's deployment config from the canonical `waterx-config` JSON and returns a ready client. Builders are **build-only** — they return / mutate a `Transaction`; signing & execution stay with the caller (the line client, or a frontend wallet), so multi-step Pyth injection and wallet flows keep working.
 
 ```ts
-import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
-import { buildOpenPositionTx, WaterXClient } from "@waterx/sdk";
-
-const client = WaterXClient.testnet();
-// Use your own keypair or any @mysten/sui Signer (e.g. wallet adapter).
-const keypair = Ed25519Keypair.generate();
-
-const tx = await buildOpenPositionTx(client, {
-  accountObjectAddress: "0x...", // UserAccount object id (hex), not a numeric id
-  base: "BTC",
-  isLong: true,
-  leverage: 10,
-  collateralAmount: 1_000_000_000n, // 1000 USDC if 6 decimals
-  approxPrice: 95_000, // required when `size` is not provided
+import { Client, rawPrice } from "@waterx/sdk";
+import { Transaction } from "@mysten/sui/transactions";
+
+const client = await Client.create({ network: "TESTNET" });
+const signer = /* your Ed25519Keypair or wallet Signer */;
+
+// --- Perp: place a market order ---
+const tx = await client.perp.buildPlaceOrderTx({
+  ticker: "BTCUSD",
+  collateralType: client.perpClient.creditType(),
+  accountId: "0x...", // UserAccount object id (hex)
+  main: {
+    isLong: true,
+    isStopOrder: false,
+    reduceOnly: false,
+    size: rawPrice(0.001),
+    acceptablePrice: rawPrice(100_000),
+    collateralAmount: 5_000_000n,
+  },
+  preOrders: [],
 });
+await client.perpClient.signAndExecuteTransaction({ transaction: tx, signer });
 
-const result = await client.signAndExecuteTransaction({
-  transaction: tx,
-  signer: keypair,
-});
-console.log(result.digest);
+// --- Prediction: same pattern under client.predict ---
+const ptx = new Transaction();
+client.predict.placeOrder(ptx, params);
+await client.predictClient.signAndExecuteTransaction({ transaction: ptx, signer });
 ```
 
-### Low-level PTB: same flow, your oracle wiring
-
-Create a `Transaction`, append Pyth / aggregator calls (`updatePythPrices`, `buildPythRuleFeedCalls` from this package — mirror `src/tx-builders.ts`), then call `openPosition(client, tx, openPositionParams)` (or any other builder in `src/user/`). Params are typed as `OpenPositionParams`, `ClosePositionParams`, etc.
-
----
-
-## API overview
+> Account creation is shared: both lines build accounts via the same on-chain `waterx_account` system, so an account created through `client.perp.createAccount` is usable by `client.predict.*` (and vice versa).
 
-### Core
+## Per-line clients
 
-| Export                  | Purpose                                                               |
-| ----------------------- | --------------------------------------------------------------------- |
-| `WaterXClient`          | gRPC client, `simulate()`, `signAndExecuteTransaction()`              |
-| `createTestnetConfig()` | Default testnet package/object/token IDs + Pyth config                |
-| `WaterXConfig`          | Full config; must include `bucketFrameworkPackageId` for trading PTBs |
+If you only need one line, construct it directly (both factories are **async** — they fetch deployment config):
 
-### Transaction builders (append to `Transaction`)
-
-| Group    | Functions                                                                                                                                                                                                                   |
-| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Shared   | `accountSenderRequest(tx, client)`                                                                                                                                                                                          |
-| Trading  | `openPosition`, `closePosition`, `increasePosition`, `decreasePosition`, `depositCollateral`, `withdrawCollateral` (`increaseCollateral` / `releaseCollateral` deprecated), `liquidate`, `matchOrders`, `updateFundingRate` |
-| Orders   | `placeOrder`, `cancelOrder`                                                                                                                                                                                                 |
-| WLP      | `mintWlp`, `requestRedeemWlp`, `cancelRedeemWlp`, `settleRedeemWlp`                                                                                                                                                         |
-| Account  | `createAccount`, `depositToAccount`, `receiveCoin`, `transferAccount`, `addDelegate`, `removeDelegate`, `updateDelegatePermissions`                                                                                         |
-| Referral | `setReferralCode`, `useReferralCode`, `registerReferralCode`, `bindReferral`                                                                                                                                                |
-
-Param types: `OpenPositionParams`, `IncreasePositionParams`, `DecreasePositionParams`, etc. (see `src/index.ts`).
-
-### Read-only queries (simulate + BCS)
-
-| Area          | Functions                                                                                                                                                                                      |
-| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Account       | `getAccountsByOwner`, `getAccountDelegates`, `getAccountObjectId` (deprecated — use `accountObjectAddress` directly), `getAccountCoins`, `getAccountBalance`, `selectCoinsForAmount`           |
-| Market / pool | `getMarketSummary` (`view::market_summary<LP>` — optional `typeArgs`: LP type string or `{ lpTokenType? }` only), `getPoolSummary`, `getWlpTotalSupply`, `getWlpTvlUsd`, `getTokenPoolSummary` |
-| Position      | `getPosition`, `positionExists` (same LP type-arg rules as `getMarketSummary`)                                                                                                                 |
+```ts
+import { WaterXClient } from "@waterx/sdk/perp";
+import { PredictClient } from "@waterx/sdk/prediction";
 
-**View return shapes:** `MarketSummary` includes `marketIndex` (on-chain index). `PositionInfoView` exposes `marketIndex` (bigint) and `accountObjectAddress` (from `user_address`). `getTokenPoolSummary` maps `TokenPoolSummary.lastPriceRefreshTimestamp` when the return payload includes it; older 72-byte deployments surface `0n` (see `parseTokenPoolSummaryReturn` in `fetch.ts`).
+const perp = await WaterXClient.create("TESTNET"); // or WaterXClient.testnet()
+const predict = await PredictClient.create("TESTNET"); // or PredictClient.testnet()
+```
 
-### High-level PTB helpers
+Read-only queries use gRPC `simulateTransaction` (no signer) — the `getX` view helpers, e.g. `await perp.simulate(tx)` or `getMarketData(perp, …)`.
 
-`buildOpenPositionTx`, `buildClosePositionTx`, `buildIncreasePositionTx`, `buildDecreasePositionTx`, `buildDepositCollateralTx`, `buildWithdrawCollateralTx` (`buildIncreaseCollateralTx` / `buildReleaseCollateralTx` deprecated), `buildPlaceOrderTx`, `buildCancelOrderTx` (all `async`, Pyth-backed). All WLP builders are `async` and refresh every pool token's Pyth feed before the call (required by `assert_prices_fresh`): `buildMintWlpTx`, `buildMintAndStakeWlpTx`, `buildRequestRedeemWlpTx` (requires `recipient`), `buildSettleRedeemWlpTx`, `buildCancelRedeemWlpTx`, `buildUnstakeAndRequestRedeemWlpTx`.
+## Recipes & full surface
 
-### Constants & Pyth
+To avoid doc drift, per-action usage lives in maintained, lint-checked code rather than this README:
 
-Permission bits, order tags, testnet IDs, Pyth feeds: `src/constants.ts`.  
-On testnet, `TESTNET_TYPES.WLP` is the LP type wired to the live **`WlpPool` / `Market`** (`wlp_token::WLP_TOKEN`); `TESTNET_PACKAGE_IDS.WLP_STANDALONE` points at the standalone `contracts/wlp` publish for reference.  
-Oracle wiring: `fetchPriceFeedsUpdateData`, `updatePythPrices`, `buildPythRuleFeedCalls`, `PythCache`, etc. in `src/utils/pyth.ts`.
+- **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/index.ts`](./src/index.ts) (perp) and [`src/prediction/index.ts`](./src/prediction/index.ts) — clients, builders, view helpers, BCS types, and `*Calls` generated namespaces.
 
----
+Perp `build*Tx` helpers are Pyth-backed (`async`; they refresh feeds before the call). Pyth/Wormhole helpers live in [`src/utils/`](./src/utils).
 
 ## Development
 
-| Command                     | Use                                  |
-| --------------------------- | ------------------------------------ |
-| `pnpm typecheck`            | Typecheck                            |
-| `pnpm test`                 | Tests                                |
-| `pnpm lint` / `pnpm format` | Prettier                             |
-| `pnpm codegen`              | Regenerate `src/generated` from Move |
+| 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`) |
+
+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/src/client.d.ts

@@ -69,8 +69,58 @@ export declare class WaterXClient {
         feed_id: string;
         price_info_object: string;
     };
-    /** `wlp.pool_tokens[ticker]` (fully-qualified Move type), throws if unknown. */
-    getPoolTokenType(ticker: string): string;
+    /**
+     * True when `ticker` is priced by `waterx_constant_rule` (a constant pin,
+     * e.g. `USDCUSD → $1`) rather than Pyth. Such tickers are fed via
+     * `constant_rule::feed` and need no Pyth update; see {@link refreshOraclePrices}.
+     *
+     * All-or-nothing, mirroring {@link getSupraRule} and the keeper: only routes a
+     * ticker to the constant rule when the rule is FULLY wired (`published_at` +
+     * `config` present). A half-populated block — `prices` listed before the rule
+     * is deployed, a realistic mid-rollout state — would otherwise make this true
+     * while {@link aggregateTickerWithConstant} throws, aborting the whole
+     * price-refresh PTB instead of safely falling back to Pyth.
+     */
+    isConstantTicker(ticker: string): boolean;
+    /**
+     * True when `ticker` is mid-migration and must be fed by *both* Pyth and the
+     * constant rule into one collector — so the aggregator can hold the
+     * `{Pyth, Constant}` weight set without an `EMissingPriceSource` window while
+     * rule weights are flipped (on-chain `aggregator::remove_outliers` requires
+     * every weighted rule present in the collector). Listed in
+     * `waterx_constant_rule.dual_feed`; clamped to `prices` so a stray entry that
+     * isn't a real constant ticker can't double-feed against no weight. See
+     * {@link aggregateTickerWithDual} and the USDCUSD runbook in `waterx-contract`.
+     */
+    isDualFeedTicker(ticker: string): boolean;
+    /**
+     * True when `ticker` is fed by the constant rule *alone* (steady state): no
+     * Pyth feed call, so it skips the Pyth update. Dual-feed tickers are constant
+     * *and* Pyth, so they are NOT constant-only.
+     */
+    isConstantOnlyTicker(ticker: string): boolean;
+    /**
+     * The `supra_rule` config when it is deployed, enabled, and fully wired
+     * (`config` + `oracle_holder`), else `undefined`. When present, callers feed
+     * `supra_rule::feed` as a second weighted rule alongside Pyth on the same
+     * collector; see {@link refreshOraclePrices}. Default-off, so a Pyth-only
+     * deployment returns `undefined` here.
+     */
+    getSupraRule(): {
+        published_at: string;
+        config: string;
+        oracle_holder: string;
+    } | undefined;
+    /**
+     * Resolve a WLP pool token's fully-qualified Move type.
+     *
+     * `wlp.pool_tokens` is keyed by **oracle ticker** (e.g. `"USDCUSD"`) — the
+     * Rust keeper requires this, since it reuses each key to look up the token's
+     * aggregator + pyth feed. For ergonomics this also accepts the coin symbol
+     * (the trailing `::Struct` segment, e.g. `"USD"` → `…::usd::USD`): an exact
+     * ticker hit wins, otherwise we match by coin name. Throws if neither hits.
+     */
+    getPoolTokenType(tickerOrName: string): string;
     /** Fully-qualified WLP coin type derived from `wlp.original_id`. */
     wlpType(): string;
     /**

package/dist/src/client.js

@@ -117,12 +117,82 @@ export class WaterXClient {
             throw new Error(`No pyth feed listed for ticker: ${ticker}`);
         return f;
     }
-    /** `wlp.pool_tokens[ticker]` (fully-qualified Move type), throws if unknown. */
-    getPoolTokenType(ticker) {
-        const t = this.config.packages.wlp?.pool_tokens?.[ticker];
-        if (!t)
-            throw new Error(`No pool token registered for ticker: ${ticker}`);
-        return t;
+    /**
+     * True when `ticker` is priced by `waterx_constant_rule` (a constant pin,
+     * e.g. `USDCUSD → $1`) rather than Pyth. Such tickers are fed via
+     * `constant_rule::feed` and need no Pyth update; see {@link refreshOraclePrices}.
+     *
+     * All-or-nothing, mirroring {@link getSupraRule} and the keeper: only routes a
+     * ticker to the constant rule when the rule is FULLY wired (`published_at` +
+     * `config` present). A half-populated block — `prices` listed before the rule
+     * is deployed, a realistic mid-rollout state — would otherwise make this true
+     * while {@link aggregateTickerWithConstant} throws, aborting the whole
+     * price-refresh PTB instead of safely falling back to Pyth.
+     */
+    isConstantTicker(ticker) {
+        const c = this.config.packages.waterx_constant_rule;
+        if (!c?.published_at || !c.config)
+            return false;
+        return c.prices?.[ticker] !== undefined;
+    }
+    /**
+     * True when `ticker` is mid-migration and must be fed by *both* Pyth and the
+     * constant rule into one collector — so the aggregator can hold the
+     * `{Pyth, Constant}` weight set without an `EMissingPriceSource` window while
+     * rule weights are flipped (on-chain `aggregator::remove_outliers` requires
+     * every weighted rule present in the collector). Listed in
+     * `waterx_constant_rule.dual_feed`; clamped to `prices` so a stray entry that
+     * isn't a real constant ticker can't double-feed against no weight. See
+     * {@link aggregateTickerWithDual} and the USDCUSD runbook in `waterx-contract`.
+     */
+    isDualFeedTicker(ticker) {
+        const c = this.config.packages.waterx_constant_rule;
+        if (!c?.published_at || !c.config)
+            return false;
+        if (c.prices?.[ticker] === undefined)
+            return false;
+        return c.dual_feed?.includes(ticker) ?? false;
+    }
+    /**
+     * True when `ticker` is fed by the constant rule *alone* (steady state): no
+     * Pyth feed call, so it skips the Pyth update. Dual-feed tickers are constant
+     * *and* Pyth, so they are NOT constant-only.
+     */
+    isConstantOnlyTicker(ticker) {
+        return this.isConstantTicker(ticker) && !this.isDualFeedTicker(ticker);
+    }
+    /**
+     * The `supra_rule` config when it is deployed, enabled, and fully wired
+     * (`config` + `oracle_holder`), else `undefined`. When present, callers feed
+     * `supra_rule::feed` as a second weighted rule alongside Pyth on the same
+     * collector; see {@link refreshOraclePrices}. Default-off, so a Pyth-only
+     * deployment returns `undefined` here.
+     */
+    getSupraRule() {
+        const s = this.config.packages.supra_rule;
+        if (!s?.enabled || !s.published_at || !s.config || !s.oracle_holder)
+            return undefined;
+        return { published_at: s.published_at, config: s.config, oracle_holder: s.oracle_holder };
+    }
+    /**
+     * Resolve a WLP pool token's fully-qualified Move type.
+     *
+     * `wlp.pool_tokens` is keyed by **oracle ticker** (e.g. `"USDCUSD"`) — the
+     * Rust keeper requires this, since it reuses each key to look up the token's
+     * aggregator + pyth feed. For ergonomics this also accepts the coin symbol
+     * (the trailing `::Struct` segment, e.g. `"USD"` → `…::usd::USD`): an exact
+     * ticker hit wins, otherwise we match by coin name. Throws if neither hits.
+     */
+    getPoolTokenType(tickerOrName) {
+        const poolTokens = this.config.packages.wlp?.pool_tokens ?? {};
+        const exact = poolTokens[tickerOrName];
+        if (exact)
+            return exact;
+        for (const t of Object.values(poolTokens)) {
+            if (typeof t === "string" && t.split("::").pop() === tickerOrName)
+                return t;
+        }
+        throw new Error(`No pool token registered for ticker/name: ${tickerOrName}`);
     }
     /** Fully-qualified WLP coin type derived from `wlp.original_id`. */
     wlpType() {

package/dist/src/config.d.ts

@@ -25,6 +25,39 @@ export interface PythRulePackage extends BasePackageEntry {
 export interface PythSponsorRulePackage extends BasePackageEntry {
     pyth_sponsor: string;
 }
+export interface WaterxConstantRulePackage extends BasePackageEntry {
+    /** Shared `constant_rule::Config` holding the per-ticker constant prices. */
+    config: string;
+    /**
+     * Oracle ticker → constant 1e9-scaled price (decimal string), mirroring the
+     * on-chain `Config.prices` map. A ticker present here is fed via
+     * `constant_rule::feed` instead of `pyth_rule::feed` (e.g. `USDCUSD → "1000000000"`).
+     */
+    prices?: Record<string, string>;
+    /**
+     * Tickers in transition (subset of `prices`): fed via *both* `pyth_rule::feed`
+     * and `constant_rule::feed` into one collector so the aggregator can hold the
+     * `{Pyth, Constant}` weight set without an `EMissingPriceSource` window while
+     * rule weights are flipped. Empty/absent (steady state) → each `prices` ticker
+     * is constant-only. See the USDCUSD migration runbook in `waterx-contract`.
+     */
+    dual_feed?: string[];
+}
+export interface SupraRulePackage extends BasePackageEntry {
+    /** Shared `supra_rule::Config` (per-symbol Supra pair_id + freshness tolerance). */
+    config: string;
+    /** Supra `OracleHolder` shared object id (network-specific). Required to feed. */
+    oracle_holder?: string;
+    /** Oracle ticker → Supra pair id (mirrors the on-chain `Config`; informational). */
+    pairs?: Record<string, number>;
+    /**
+     * When true AND `config` + `oracle_holder` are set, `refreshOraclePrices`
+     * feeds `supra_rule` on the same `PriceCollector` as Pyth before `aggregate`
+     * (a second weighted rule). Defaults to **false** so a Pyth-only deployment
+     * is unaffected — flip on only after `weight_threshold`/feeders are ready.
+     */
+    enabled?: boolean;
+}
 export interface WxaAccountPackage extends BasePackageEntry {
     admin_cap: string;
     account_registry: string;
@@ -93,6 +126,8 @@ export interface WaterxCreditPackage {
 }
 /** One backing-asset row on the native custody vault (PSM). */
 export interface NativeCustodyAsset {
+    /** Human-readable asset label, e.g. `"MOCK_USDC"` / `"USDC"` (from `add_asset`). */
+    name?: string;
     /** Fully-qualified backing asset Move type `T`. */
     type: string;
     decimal: number;
@@ -123,7 +158,12 @@ export interface WormholeBridgePackage {
     max_mint_per_tx?: string;
     hourly_burn_limit?: string;
     max_burn_per_tx?: string;
-    trusted_emitters: TrustedEmitterRow[];
+    /**
+     * @deprecated EVM emitter↔token config now lives solely under `evm.bridge.chains`
+     * (deposit_vault = emitter, wormhole_chain_id = chain key). The runtime allowlist is
+     * read from the on-chain `Bridge` object, not from config. Kept optional for back-compat.
+     */
+    trusted_emitters?: TrustedEmitterRow[];
     /** Shared `Bridge` (phase-5 output). */
     bridge?: string;
     /**
@@ -150,6 +190,8 @@ export interface WaterXPackages {
     waterx_referral?: WaterxReferralPackage;
     pyth_rule: PythRulePackage;
     pyth_sponsor_rule?: PythSponsorRulePackage;
+    waterx_constant_rule?: WaterxConstantRulePackage;
+    supra_rule?: SupraRulePackage;
     waterx_account: WxaAccountPackage;
     waterx_oracle: WaterxOraclePackage;
     waterx_perp: WaterxPerpPackage;
@@ -211,9 +253,17 @@ export interface WaterXConfig {
 export interface LoadConfigOptions {
     /**
      * Override the default config URL. Use this to point at a staging branch
-     * (`?ref=staging`) or a local mirror during development.
+     * (`?ref=staging`) or a local mirror during development. Takes precedence
+     * over {@link configRef}.
      */
     configUrl?: string;
+    /**
+     * Pin the canonical config to a specific git ref — a commit SHA, branch,
+     * or tag — instead of the default `main` branch. Resolves to
+     * `https://raw.githubusercontent.com/WaterXProtocol/waterx-config/<ref>/<network>.json`.
+     * Ignored when {@link configUrl} is set.
+     */
+    configRef?: string;
     /**
      * Reuse a previously-fetched config from the in-memory cache (keyed by
      * the effective URL). Default: false (always fetch fresh).
@@ -224,6 +274,10 @@ export interface LoadConfigOptions {
     /** Optional request timeout in ms. Default 10_000. */
     timeoutMs?: number;
 }
-export declare function defaultConfigUrl(network: Network): string;
+/**
+ * Build the canonical config URL for `network`, optionally pinned to a
+ * specific git `ref` (commit SHA, branch, or tag). Defaults to `main`.
+ */
+export declare function defaultConfigUrl(network: Network, ref?: string): string;
 export declare function clearConfigCache(): void;
 export declare function loadConfig(network: Network, opts?: LoadConfigOptions): Promise<WaterXConfig>;

package/dist/src/config.js

@@ -34,16 +34,22 @@ export const WORMHOLE_DEFAULTS = {
         wormholescan_api: "https://api.testnet.wormholescan.io/api/v1",
     },
 };
-const DEFAULT_CONFIG_URL_BASE = "https://raw.githubusercontent.com/WaterXProtocol/waterx-config/main";
-export function defaultConfigUrl(network) {
-    return `${DEFAULT_CONFIG_URL_BASE}/${network.toLowerCase()}.json`;
+const CONFIG_REPO_RAW_BASE = "https://raw.githubusercontent.com/WaterXProtocol/waterx-config";
+/** Default git ref for the canonical config when none is pinned. */
+const DEFAULT_CONFIG_REF = "main";
+/**
+ * Build the canonical config URL for `network`, optionally pinned to a
+ * specific git `ref` (commit SHA, branch, or tag). Defaults to `main`.
+ */
+export function defaultConfigUrl(network, ref = DEFAULT_CONFIG_REF) {
+    return `${CONFIG_REPO_RAW_BASE}/${ref}/${network.toLowerCase()}.json`;
 }
 const cache = new Map();
 export function clearConfigCache() {
     cache.clear();
 }
 export async function loadConfig(network, opts = {}) {
-    const url = opts.configUrl ?? defaultConfigUrl(network);
+    const url = opts.configUrl ?? defaultConfigUrl(network, opts.configRef);
     if (opts.cache && cache.has(url)) {
         return cache.get(url);
     }

package/dist/src/constants.d.ts

@@ -62,3 +62,9 @@ export declare const ACTION_ADD_PRE_ORDER = 11;
 export declare const MS_PER_YEAR: number;
 /** Zero-address placeholder used as the sender in dry-run / simulate calls. */
 export declare const DRY_RUN_SENDER = "0x0000000000000000000000000000000000000000000000000000000000000000";
+/**
+ * Well-known address of Sui's native funds-accumulator root shared object
+ * (`@0xacc` in the framework). Pass this to `request_deposit_from_funds<T>`
+ * to drain `Balance<T>` parked at an account's address.
+ */
+export declare const ACCUMULATOR_ROOT = "0xacc";

package/dist/src/constants.js

@@ -69,3 +69,9 @@ export const MS_PER_YEAR = 365 * 24 * 60 * 60 * 1000;
 // ======== Misc ========
 /** Zero-address placeholder used as the sender in dry-run / simulate calls. */
 export const DRY_RUN_SENDER = "0x0000000000000000000000000000000000000000000000000000000000000000";
+/**
+ * Well-known address of Sui's native funds-accumulator root shared object
+ * (`@0xacc` in the framework). Pass this to `request_deposit_from_funds<T>`
+ * to drain `Balance<T>` parked at an account's address.
+ */
+export const ACCUMULATOR_ROOT = "0xacc";

package/dist/src/core/waterx-account.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared `waterx_account` PTB builders.
+ *
+ * Perp and prediction both create/operate accounts through the **same** on-chain
+ * `waterx_account` system (same package + `AccountRegistry`), so the actual PTB
+ * calls are assembled here once. Each product line resolves the deployment
+ * coordinates (`WxaAccountRef`) and builds its own `senderRequest` (via its own
+ * account-request helper), then delegates the moveCall to these functions.
+ *
+ * These builders are raw `tx.moveCall(...)` (no generated-bindings dependency),
+ * so the module is shared by both `src/user/account.ts` (perp) and
+ * `src/prediction/account.ts` (prediction) without coupling to either line's
+ * generated code.
+ */
+import type { Transaction, TransactionArgument } from "@mysten/sui/transactions";
+/** Resolved `waterx_account` deployment coordinates (each line resolves these from its own client). */
+export interface WxaAccountRef {
+    /** `waterx_account` package id (`published_at`). */
+    packageId: string;
+    /** `AccountRegistry` shared-object id. */
+    registry: string;
+}
+/**
+ * `waterx_account::account::create_account`. Returns the new account id
+ * (Move return value). `senderRequest` is the `account::request` hot-potato the
+ * caller built with its own account-request helper.
+ */
+export declare function createAccountCall(tx: Transaction, ref: WxaAccountRef, params: {
+    senderRequest: TransactionArgument;
+    alias: string;
+}): TransactionArgument;

package/dist/src/core/waterx-account.js

@@ -0,0 +1,26 @@
+/**
+ * Shared `waterx_account` PTB builders.
+ *
+ * Perp and prediction both create/operate accounts through the **same** on-chain
+ * `waterx_account` system (same package + `AccountRegistry`), so the actual PTB
+ * calls are assembled here once. Each product line resolves the deployment
+ * coordinates (`WxaAccountRef`) and builds its own `senderRequest` (via its own
+ * account-request helper), then delegates the moveCall to these functions.
+ *
+ * These builders are raw `tx.moveCall(...)` (no generated-bindings dependency),
+ * so the module is shared by both `src/user/account.ts` (perp) and
+ * `src/prediction/account.ts` (prediction) without coupling to either line's
+ * generated code.
+ */
+/**
+ * `waterx_account::account::create_account`. Returns the new account id
+ * (Move return value). `senderRequest` is the `account::request` hot-potato the
+ * caller built with its own account-request helper.
+ */
+export function createAccountCall(tx, ref, params) {
+    const [accountId] = tx.moveCall({
+        target: `${ref.packageId}::account::create_account`,
+        arguments: [tx.object(ref.registry), params.senderRequest, tx.pure.string(params.alias)],
+    });
+    return accountId;
+}