@waterx/sdk 4.0.1 → 4.3.0

package/README.md

@@ -11,19 +11,21 @@ The perp and prediction lines expose builder functions with **colliding names**
 ```ts
 import { WaterXClient } from "@waterx/sdk";
 
-// waterxConfigUrl is REQUIRED — the SDK has no built-in default and never reads env.
+// waterxConfigUrl and oracleSource are REQUIRED — the SDK has no built-in
+// defaults and never reads env. oracleSource: 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",
 });
 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:
-//   WaterXClient.create({ perp: { network: "MAINNET", waterxConfigUrl: mainnetUrl }, predict: { network: "TESTNET", waterxConfigUrl: testnetUrl } })
+// 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 } })
 ```
 
 > `WaterXClient` is the umbrella entry point. `Client` is kept as a **deprecated alias** for one major cycle.
@@ -56,6 +58,7 @@ 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"
 });
 const signer = /* your Ed25519Keypair or wallet Signer */;
 
@@ -94,34 +97,36 @@ 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 }); // or PerpClient.testnet({ waterxConfigUrl })
-const predict = await PredictClient.create("TESTNET", { waterxConfigUrl }); // or PredictClient.testnet({ waterxConfigUrl })
+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
 ```
 
 Read-only queries use gRPC `simulateTransaction` (no signer) — the `getX` view helpers, e.g. `await perp.simulate(tx)` or `getMarketData(perp, …)`.
 
 ## Oracle sources
 
-ONE client create option, `oracleSource`, selects the price-update source. Each source is **self-contained** — it owns its own infra + config and does **not** back-stop any other source. 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:
+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:
 
-| Option         | Values                                         | What it selects                                                                                                                                                                                                                                                                           |
-| -------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `oracleSource` | `'pyth_rule'` (default) \| `'pyth_lazer_rule'` | The price-update source. `'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`. |
+| 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. |
 
-**No cross-source fallback, no init guard.** Selecting a source whose feed for a requested ticker is absent is **not** an error at client creation — it fails at **tx-build** for exactly those tickers (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.
+**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.)
 
-The Pyth Core infra (`client.pyth`: state ids + Hermes endpoint) is **fixed per network** by `PYTH_DEFAULTS` and is **not** deployment-overridable — the canonical `waterx-config` JSON carries no `pyth` block. The `pyth_lazer_rule` source reads only the credential/policy (`api_key`/`fetch`) from `client.pyth`; its on-chain infra comes from `LAZER_DEFAULTS` + config. The credential and fetch policy are passed at client init (`pythApiKey` / `pythFetch`), never through the JSON.
+**No cross-source fallback, no feeds guard at init.** Construction rejects an empty/nullish `oracleSource`, 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.
+
+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.
 
 ```ts
 // Per-environment wiring — the consumer owns the env var, not the SDK:
 const perp = await PerpClient.create(network, {
   waterxConfigUrl,
-  oracleSource: process.env.ORACLE_SOURCE as OracleSource | undefined, // e.g. staging: 'pyth_lazer_rule'
-  pythApiKey: process.env.PYTH_API_KEY, // Lazer is auth-first; unused by 'pyth_rule'
+  oracleSource: process.env.ORACLE_SOURCE!.split(",") as OracleSource[], // REQUIRED; comma list = the fed set
+  pythApiKey: process.env.PYTH_API_KEY, // required iff 'pyth_lazer_rule' is listed (Lazer is auth-first)
 });
 ```
 
-This is the staging-Lazer / prod-Core rollout pattern: staging sets `ORACLE_SOURCE=pyth_lazer_rule` (+ `PYTH_API_KEY`) while production leaves it unset — flipping an environment is an env-var change, never an SDK release.
+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.
 
 ### Adding an oracle source (runbook)
 
@@ -130,10 +135,25 @@ Every source plugs in the same way — routing is driven **only** by the client'
 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`.
 2. **Register it** in `src/oracle/rule-registry.ts` (`DEFAULT_RULES`) under a new `OracleSource` value (added to the union in `price-update-rule.ts`).
 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 per-network map in `src/oracle/config.ts`, mirroring `LAZER_DEFAULTS`.
+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) follows exactly this path when it lands.
+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.
+
+> **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
+>   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.
 
 ## Recipes & full surface
 
@@ -143,7 +163,7 @@ To avoid doc drift, per-action usage lives in maintained, lint-checked code rath
 - **Prediction recipes:** [`test/prediction/e2e/`](./test/prediction/e2e) — the live reference for `client.predict.*` flows.
 - **Authoritative export list:** [`src/perp/index.ts`](./src/perp/index.ts) (perp) and [`src/prediction/index.ts`](./src/prediction/index.ts) — clients, builders, view helpers, BCS types, and `*Calls` generated namespaces. The package root (`.`) is [`src/sdk.ts`](./src/sdk.ts) (umbrella + flat-perp re-export); the shared base is published at `@waterx/sdk/account` and `@waterx/sdk/oracle`.
 
-Perp `build*Tx` helpers are Pyth-backed (`async`; they refresh feeds before the call). Oracle (Pyth/Hermes) helpers live in [`src/oracle/`](./src/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).
 
 ## Development
 

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

@@ -57,6 +57,7 @@ exports.requestWithdraw = requestWithdraw;
 exports.transferToAccount = transferToAccount;
 exports.receive = receive;
 const wxa = __importStar(require("../generated/waterx_account/account.js"));
+const validate_ts_1 = require("../utils/validate.js");
 const account_request_ts_1 = require("./account-request.js");
 const constants_ts_1 = require("./constants.js");
 const waterx_account_ts_1 = require("./waterx-account.js");
@@ -195,7 +196,7 @@ function requestWithdraw(client, tx, params) {
             registry: tx.object(client.config.packages.waterx_account.account_registry),
             senderRequest: req,
             accountId: params.accountId,
-            amount: params.amount,
+            amount: (0, validate_ts_1.toU64)(params.amount, "amount"),
             recipient: params.recipient,
             extraData: Array.from(params.extraData ?? new Uint8Array()),
         },

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

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

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

@@ -15,7 +15,15 @@ export interface ParkedBackingAssetBalance {
     /** Sum of `listCoins` object balances — TTO'd / owned `Coin<T>` path. */
     coinsRaw: bigint;
 }
-/** Rescale a u64 raw amount between token decimal precisions (truncates on downscale). */
+/**
+ * Rescale a u64 raw amount between token decimal precisions (truncates on
+ * downscale). `toDecimals` defaults to {@link COLLATERAL_DECIMALS} — the
+ * CREDIT/wxUSD (collateral-typed) scale, 6 on every current deployment — for
+ * the common backing-asset → CREDIT direction. When rescaling a custody
+ * backing asset, always pass its per-asset config `decimal`
+ * (`NativeCustodyAsset.decimal`) as `fromDecimals`; never assume flat 6 — a
+ * 9-dec backing asset would otherwise mis-scale by 1000×.
+ */
 export declare function rescaleRawAmount(raw: bigint, fromDecimals: number, toDecimals?: number): bigint;
 /**
  * Probe every backing asset registered on `native_custody` for non-zero balances
@@ -26,7 +34,22 @@ export declare function probeParkedBackingAssets(client: AccountClientLike, acco
 /**
  * Probe non-zero CREDIT parked at `accountId`'s Sui address. Matches the
  * address-CREDIT legs inside {@link appendConsolidateAddressCredit}.
+ *
+ * RPC failures PROPAGATE (no swallow-to-zero): a gRPC error here used to be
+ * silently reported as an authoritative zero balance, which made
+ * `getSpendableCreditBalance` under-report spendable funds and let
+ * `appendConsolidateAddressCredit` build a tx that later aborted on-chain
+ * with a confusing insufficient-balance error. Callers that can tolerate a
+ * missing probe must catch explicitly.
  */
 export declare function probeAddressCreditBalance(client: AccountClientLike, accountId: string): Promise<AddressCreditBalance>;
-/** Sum parked backing assets into CREDIT base units at the 1:1 PSM peg. */
+/**
+ * Sum parked backing assets into CREDIT base units at the 1:1 PSM peg.
+ * Each row rescales from its own per-asset `decimals` (sourced from config
+ * `NativeCustodyAsset.decimal` by {@link probeParkedBackingAssets}), so
+ * mixed-decimal backing sets (e.g. a 9-dec asset next to 6-dec USDC) sum
+ * correctly. `creditDecimals` is the CREDIT/wxUSD **target** scale —
+ * collateral-typed, 6 on all current deployments (the config JSON carries no
+ * credit decimal).
+ */
 export declare function sumParkedBackingAsCreditRaw(parked: readonly ParkedBackingAssetBalance[], creditDecimals?: number): bigint;

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

@@ -10,7 +10,15 @@ exports.sumParkedBackingAsCreditRaw = sumParkedBackingAsCreditRaw;
  * so display totals match what the next async tx-builder would sweep.
  */
 const constants_ts_1 = require("../../constants.js");
-/** Rescale a u64 raw amount between token decimal precisions (truncates on downscale). */
+/**
+ * Rescale a u64 raw amount between token decimal precisions (truncates on
+ * downscale). `toDecimals` defaults to {@link COLLATERAL_DECIMALS} — the
+ * CREDIT/wxUSD (collateral-typed) scale, 6 on every current deployment — for
+ * the common backing-asset → CREDIT direction. When rescaling a custody
+ * backing asset, always pass its per-asset config `decimal`
+ * (`NativeCustodyAsset.decimal`) as `fromDecimals`; never assume flat 6 — a
+ * 9-dec backing asset would otherwise mis-scale by 1000×.
+ */
 function rescaleRawAmount(raw, fromDecimals, toDecimals = constants_ts_1.COLLATERAL_DECIMALS) {
     if (fromDecimals === toDecimals)
         return raw;
@@ -58,39 +66,43 @@ async function probeParkedBackingAssets(client, accountId) {
 /**
  * Probe non-zero CREDIT parked at `accountId`'s Sui address. Matches the
  * address-CREDIT legs inside {@link appendConsolidateAddressCredit}.
+ *
+ * RPC failures PROPAGATE (no swallow-to-zero): a gRPC error here used to be
+ * silently reported as an authoritative zero balance, which made
+ * `getSpendableCreditBalance` under-report spendable funds and let
+ * `appendConsolidateAddressCredit` build a tx that later aborted on-chain
+ * with a confusing insufficient-balance error. Callers that can tolerate a
+ * missing probe must catch explicitly.
  */
 async function probeAddressCreditBalance(client, accountId) {
     if (!client.config.packages.waterx_credit?.credit_type) {
         return { fundsRaw: 0n, coinsRaw: 0n };
     }
     const creditType = client.creditType();
-    let fundsRaw = 0n;
+    const bal = (await client.getBalance({
+        owner: accountId,
+        coinType: creditType,
+    }));
+    const fundsRaw = BigInt(bal.balance?.addressBalance ?? "0");
+    const coins = (await client.listCoins({
+        owner: accountId,
+        coinType: creditType,
+    }));
     let coinsRaw = 0n;
-    try {
-        const bal = (await client.getBalance({
-            owner: accountId,
-            coinType: creditType,
-        }));
-        fundsRaw = BigInt(bal.balance?.addressBalance ?? "0");
-    }
-    catch {
-        // ignore — treat as zero parked funds
-    }
-    try {
-        const coins = (await client.listCoins({
-            owner: accountId,
-            coinType: creditType,
-        }));
-        for (const coin of coins.objects ?? []) {
-            coinsRaw += BigInt(coin.balance ?? "0");
-        }
-    }
-    catch {
-        // ignore — treat as zero owned coins
+    for (const coin of coins.objects ?? []) {
+        coinsRaw += BigInt(coin.balance ?? "0");
     }
     return { fundsRaw, coinsRaw };
 }
-/** Sum parked backing assets into CREDIT base units at the 1:1 PSM peg. */
+/**
+ * Sum parked backing assets into CREDIT base units at the 1:1 PSM peg.
+ * Each row rescales from its own per-asset `decimals` (sourced from config
+ * `NativeCustodyAsset.decimal` by {@link probeParkedBackingAssets}), so
+ * mixed-decimal backing sets (e.g. a 9-dec asset next to 6-dec USDC) sum
+ * correctly. `creditDecimals` is the CREDIT/wxUSD **target** scale —
+ * collateral-typed, 6 on all current deployments (the config JSON carries no
+ * credit decimal).
+ */
 function sumParkedBackingAsCreditRaw(parked, creditDecimals = constants_ts_1.COLLATERAL_DECIMALS) {
     let sum = 0n;
     for (const row of parked) {

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

@@ -35,6 +35,7 @@ const account_ts_1 = require("../../generated/waterx_account/account.js");
 const direct_rule_ts_1 = require("../../generated/waterx_account/direct_rule.js");
 const withdrawal_queue_ts_1 = require("../../generated/withdrawal_queue/withdrawal_queue.js");
 const wormhole_bridge_ts_1 = require("../../generated/wormhole_bridge/wormhole_bridge.js");
+const validate_ts_1 = require("../../utils/validate.js");
 const account_request_ts_1 = require("../account-request.js");
 // ============================================================================
 // Byte helpers
@@ -137,15 +138,10 @@ function consumeCreditDeposit(client, tx, params) {
 }
 /** Build `withdrawal_queue::route_wormhole`. Returns the `extra_data` argument. */
 function routeWormhole(client, tx, params) {
-    if (!Number.isInteger(params.evmDestinationChain) ||
-        params.evmDestinationChain < 0 ||
-        params.evmDestinationChain > 0xffff) {
-        throw new Error(`evmDestinationChain must be a u16 (0..65535), got ${params.evmDestinationChain}`);
-    }
     const out = (0, withdrawal_queue_ts_1.routeWormhole)({
         package: queuePkg(client),
         arguments: {
-            evmDestinationChain: params.evmDestinationChain,
+            evmDestinationChain: (0, validate_ts_1.toU16)(params.evmDestinationChain, "evmDestinationChain"),
             evmRecipient: toEvmAddressBytes(params.evmRecipient, "evmRecipient"),
             evmToken: toEvmAddressBytes(params.evmToken, "evmToken"),
         },
@@ -156,7 +152,7 @@ function routeWormhole(client, tx, params) {
 function routeNative(client, tx, params) {
     const out = (0, withdrawal_queue_ts_1.routeNative)({
         package: queuePkg(client),
-        arguments: { minOutput: BigInt(params.minOutput ?? 0n) },
+        arguments: { minOutput: (0, validate_ts_1.toU64)(params.minOutput ?? 0n, "minOutput") },
         typeArguments: [(0, utils_1.normalizeStructTag)(params.assetType)],
     })(tx);
     return out;
@@ -174,7 +170,7 @@ function requestCreditWithdraw(client, tx, params) {
             registry: tx.object(client.config.packages.waterx_account.account_registry),
             senderRequest: senderRequest,
             accountId: params.accountId,
-            amount: params.amount,
+            amount: (0, validate_ts_1.toU64)(params.amount, "amount"),
             recipient: params.recipient,
             extraData: params.route,
         },
@@ -205,7 +201,7 @@ function executeWithdrawalWormhole(client, tx, params) {
         package: queuePkg(client),
         arguments: {
             queue: tx.object(queueId(client)),
-            key: params.key,
+            key: (0, validate_ts_1.toU64)(params.key, "key"),
             request: request,
             bridge: tx.object(bridgeId(client)),
             creditRegistry: tx.object(creditRegistryId(client)),
@@ -222,7 +218,7 @@ function executeWithdrawalNative(client, tx, params) {
         package: queuePkg(client),
         arguments: {
             queue: tx.object(queueId(client)),
-            key: params.key,
+            key: (0, validate_ts_1.toU64)(params.key, "key"),
             request: request,
             vault: tx.object(custodyVaultId(client)),
             creditRegistry: tx.object(creditRegistryId(client)),

package/dist/cjs/src/constants.d.ts

@@ -9,7 +9,19 @@ export declare const DOUBLE_SCALE = 1000000000000000000n;
 export declare const SUI_DECIMALS = 9;
 /** WLP LP-token decimals. */
 export declare const WLP_DECIMALS = 6;
-/** Shared decimals for trading collateral / WLP backing assets (USDC, USDSUI). */
+/**
+ * Decimals for **collateral-typed** values only: the CREDIT/wxUSD internal
+ * balance and the USD-pegged trading collateral (USDC, USDSUI). All current
+ * collateral and the CREDIT coin are 6-dec, and the config JSON carries no
+ * credit decimal, so this constant is the single source for the CREDIT scale.
+ *
+ * Do NOT use it for custody **backing assets** — those carry a per-asset
+ * `decimal` in config (`NativeCustodyAsset.decimal`), threaded through
+ * `probeParkedBackingAssets` → `sumParkedBackingAsCreditRaw`. If a 9-dec
+ * backing asset ever lists, a path that assumed flat 6 for it would mis-scale
+ * its parked balance by 1000×; only a change to the CREDIT coin itself (or a
+ * non-6-dec collateral listing) would require touching this constant.
+ */
 export declare const COLLATERAL_DECIMALS = 6;
 /**
  * @deprecated Import the individual `SUI_DECIMALS` / `WLP_DECIMALS` /
@@ -23,6 +35,8 @@ export declare const TOKEN_DECIMALS: {
     readonly USDSUI: 6;
     readonly WLP: 6;
 };
+export declare const MS_PER_MINUTE: number;
+export declare const MS_PER_HOUR: number;
 export declare const MS_PER_YEAR: number;
 /**
  * Zero-address placeholder used as the sender in dry-run / simulate calls.

package/dist/cjs/src/constants.js

@@ -1,9 +1,9 @@
 "use strict";
 // Shared, line-agnostic primitives (network id, scaling, decimals, time).
-// Perp-domain enums (permissions / order tags / action codes / fee rates) live
-// in `perp/constants.ts`; prediction has its own `prediction/constants.ts`.
+// Perp-domain enums (permissions / order tags / action codes) live in
+// `perp/constants.ts`; prediction has its own `prediction/constants.ts`.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DRY_RUN_SENDER = exports.MS_PER_YEAR = exports.TOKEN_DECIMALS = exports.COLLATERAL_DECIMALS = exports.WLP_DECIMALS = exports.SUI_DECIMALS = exports.DOUBLE_SCALE = exports.FLOAT_SCALE = exports.BPS_SCALE = void 0;
+exports.DRY_RUN_SENDER = exports.MS_PER_YEAR = exports.MS_PER_HOUR = exports.MS_PER_MINUTE = exports.TOKEN_DECIMALS = exports.COLLATERAL_DECIMALS = exports.WLP_DECIMALS = exports.SUI_DECIMALS = exports.DOUBLE_SCALE = exports.FLOAT_SCALE = exports.BPS_SCALE = void 0;
 // ======== Scaling ========
 /** Basis-point denominator (10_000). Matches BP_SCALE in the Move contracts. */
 exports.BPS_SCALE = 10000n;
@@ -16,7 +16,19 @@ exports.DOUBLE_SCALE = 1000000000000000000n;
 exports.SUI_DECIMALS = 9;
 /** WLP LP-token decimals. */
 exports.WLP_DECIMALS = 6;
-/** Shared decimals for trading collateral / WLP backing assets (USDC, USDSUI). */
+/**
+ * Decimals for **collateral-typed** values only: the CREDIT/wxUSD internal
+ * balance and the USD-pegged trading collateral (USDC, USDSUI). All current
+ * collateral and the CREDIT coin are 6-dec, and the config JSON carries no
+ * credit decimal, so this constant is the single source for the CREDIT scale.
+ *
+ * Do NOT use it for custody **backing assets** — those carry a per-asset
+ * `decimal` in config (`NativeCustodyAsset.decimal`), threaded through
+ * `probeParkedBackingAssets` → `sumParkedBackingAsCreditRaw`. If a 9-dec
+ * backing asset ever lists, a path that assumed flat 6 for it would mis-scale
+ * its parked balance by 1000×; only a change to the CREDIT coin itself (or a
+ * non-6-dec collateral listing) would require touching this constant.
+ */
 exports.COLLATERAL_DECIMALS = 6;
 /**
  * @deprecated Import the individual `SUI_DECIMALS` / `WLP_DECIMALS` /
@@ -31,6 +43,8 @@ exports.TOKEN_DECIMALS = {
     WLP: exports.WLP_DECIMALS,
 };
 // ======== Time ========
+exports.MS_PER_MINUTE = 60 * 1000;
+exports.MS_PER_HOUR = 60 * 60 * 1000;
 exports.MS_PER_YEAR = 365 * 24 * 60 * 60 * 1000;
 // ======== Well-known addresses ========
 /**

package/dist/cjs/src/generated/waterx_rule/deps/bucket_v2_framework/float.d.ts

@@ -0,0 +1,8 @@
+/**************************************************************
+ * THIS FILE IS GENERATED AND SHOULD NOT BE MANUALLY MODIFIED *
+ **************************************************************/
+/** Module for floating points */
+import { MoveStruct } from '../../../utils/index.ts';
+export declare const Float: MoveStruct<{
+    value: import("@mysten/sui/bcs").BcsType<string, string | number | bigint, "u128">;
+}, "bucket_v2_framework::float::Float">;

package/dist/cjs/src/generated/waterx_rule/deps/bucket_v2_framework/float.js

@@ -0,0 +1,13 @@
+"use strict";
+/**************************************************************
+ * THIS FILE IS GENERATED AND SHOULD NOT BE MANUALLY MODIFIED *
+ **************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Float = void 0;
+/** Module for floating points */
+const index_ts_1 = require("../../../utils/index.js");
+const bcs_1 = require("@mysten/sui/bcs");
+const $moduleName = 'bucket_v2_framework::float';
+exports.Float = new index_ts_1.MoveStruct({ name: `${$moduleName}::Float`, fields: {
+        value: bcs_1.bcs.u128()
+    } });

package/dist/cjs/src/generated/waterx_rule/deps/sui/vec_map.d.ts

@@ -0,0 +1,36 @@
+/**************************************************************
+ * THIS FILE IS GENERATED AND SHOULD NOT BE MANUALLY MODIFIED *
+ **************************************************************/
+import { type BcsType } from '@mysten/sui/bcs';
+import { MoveStruct } from '../../../utils/index.ts';
+/** An entry in the map */
+export declare function Entry<K extends BcsType<any>, V extends BcsType<any>>(...typeParameters: [
+    K,
+    V
+]): MoveStruct<{
+    key: K;
+    value: V;
+}, `0x2::vec_map::Entry<${K["name"]}, ${V["name"]}>`>;
+/**
+ * A map data structure backed by a vector. The map is guaranteed not to contain
+ * duplicate keys, but entries are _not_ sorted by key--entries are included in
+ * insertion order. All operations are O(N) in the size of the map--the intention
+ * of this data structure is only to provide the convenience of programming against
+ * a map API. Large maps should use handwritten parent/child relationships instead.
+ * Maps that need sorted iteration rather than insertion order iteration should
+ * also be handwritten.
+ */
+export declare function VecMap<K extends BcsType<any>, V extends BcsType<any>>(...typeParameters: [
+    K,
+    V
+]): MoveStruct<{
+    contents: BcsType<{
+        key: K extends BcsType<infer U, any, string> ? U : never;
+        value: V extends BcsType<infer U, any, string> ? U : never;
+    }[], Iterable<{
+        key: K extends BcsType<any, infer U_1, string> ? U_1 : never;
+        value: V extends BcsType<any, infer U_1, string> ? U_1 : never;
+    }> & {
+        length: number;
+    }, string>;
+}, `0x2::vec_map::VecMap<${K["name"]}, ${V["name"]}>`>;

package/dist/cjs/src/generated/waterx_rule/deps/sui/vec_map.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Entry = Entry;
+exports.VecMap = VecMap;
+/**************************************************************
+ * THIS FILE IS GENERATED AND SHOULD NOT BE MANUALLY MODIFIED *
+ **************************************************************/
+const bcs_1 = require("@mysten/sui/bcs");
+const index_ts_1 = require("../../../utils/index.js");
+const $moduleName = '0x2::vec_map';
+/** An entry in the map */
+function Entry(...typeParameters) {
+    return new index_ts_1.MoveStruct({ name: `${$moduleName}::Entry<${typeParameters[0].name}, ${typeParameters[1].name}>`, fields: {
+            key: typeParameters[0],
+            value: typeParameters[1]
+        } });
+}
+/**
+ * A map data structure backed by a vector. The map is guaranteed not to contain
+ * duplicate keys, but entries are _not_ sorted by key--entries are included in
+ * insertion order. All operations are O(N) in the size of the map--the intention
+ * of this data structure is only to provide the convenience of programming against
+ * a map API. Large maps should use handwritten parent/child relationships instead.
+ * Maps that need sorted iteration rather than insertion order iteration should
+ * also be handwritten.
+ */
+function VecMap(...typeParameters) {
+    return new index_ts_1.MoveStruct({ name: `${$moduleName}::VecMap<${typeParameters[0].name}, ${typeParameters[1].name}>`, fields: {
+            contents: bcs_1.bcs.vector(Entry(typeParameters[0], typeParameters[1]))
+        } });
+}