@waterx/sdk 2.1.0

package/dist/src/utils/pyth.js

@@ -0,0 +1,316 @@
+/**
+ * Pyth price feed integration for the WaterX v3 oracle (ticker-based).
+ *
+ * Hermes REST fetches price update VAAs; on-chain a single PTB:
+ *   1. wormhole::vaa::parse_and_verify
+ *   2. pyth::create_authenticated_price_infos_using_accumulator
+ *   3. pyth::update_single_price_feed (one per feed)
+ *   4. for each ticker: oracle::new_collector(symbol) → pyth_rule::feed → oracle::aggregate
+ *
+ * No type parameters on `feed` / `aggregate` anymore — the oracle is one
+ * shared object keyed by ticker. `pyth_rule::feed` looks up the on-chain
+ * `PriceInfoObject` ID by ticker via the `pyth_rule::Config` identifier map.
+ */
+import { fromHex, toHex } from "@mysten/bcs";
+import { bcs } from "@mysten/sui/bcs";
+// ============================================================================
+// Pyth-sponsor flow — pays Pyth update fees from a shared sponsor pool AND
+// attaches the `PythSponsorRule` witness to a TradingRequest. Required when
+// the market's `request_checklist` contains `PythSponsorRule`.
+// ============================================================================
+import { reimburse as sponsorReimburse, request as sponsorRequest, } from "../generated/pyth_sponsor_rule/pyth_sponsor_rule.js";
+import { aggregate as aggregateCall, newCollector } from "../generated/waterx_oracle/oracle.js";
+import { feed as pythRuleFeed } from "../generated/waterx_pyth_rule/pyth_rule.js";
+export class PythCache {
+    pythStateInfo;
+    wormholePackageId;
+    priceTableInfo;
+    priceFeedObjectIdCache = new Map();
+}
+// ============================================================================
+// Hermes REST
+// ============================================================================
+export async function fetchPriceFeedsUpdateData(endpoint, priceIds) {
+    if (priceIds.length === 0)
+        return [];
+    const url = new URL("/v2/updates/price/latest", endpoint);
+    priceIds.forEach((id) => url.searchParams.append("ids[]", id));
+    const res = await fetch(url.toString(), { signal: AbortSignal.timeout(15_000) });
+    if (!res.ok)
+        throw new Error(`Hermes price fetch failed: ${res.status} ${await res.text()}`);
+    const json = (await res.json());
+    const data = json.binary?.data;
+    if (!Array.isArray(data) || data.length === 0) {
+        throw new Error("Hermes returned no binary price data");
+    }
+    return data.map((hex) => fromHex(hex));
+}
+// ============================================================================
+// On-chain helpers (cached)
+// ============================================================================
+function pkgFromUpgradeCap(json, objectId) {
+    const upgradeCap = json.upgrade_cap ??
+        json.fields?.upgrade_cap;
+    const nested = upgradeCap?.fields?.package;
+    const pkg = typeof upgradeCap?.package === "string"
+        ? upgradeCap.package
+        : typeof nested === "string"
+            ? nested
+            : undefined;
+    if (!pkg)
+        throw new Error(`Cannot resolve package id for object ${objectId}`);
+    return pkg;
+}
+async function getPythStateInfo(client, pythStateId, cache) {
+    if (cache?.pythStateInfo)
+        return cache.pythStateInfo;
+    const result = await client.getObject({ objectId: pythStateId, include: { json: true } });
+    const json = result.object?.json;
+    if (!json)
+        throw new Error("Unable to fetch pyth state");
+    const packageId = pkgFromUpgradeCap(json, pythStateId);
+    const fields = json.fields;
+    const fee = (fields?.base_update_fee ?? json.base_update_fee);
+    if (fee === undefined)
+        throw new Error("Unable to fetch pyth state base_update_fee");
+    const info = { packageId, baseUpdateFee: BigInt(fee) };
+    if (cache)
+        cache.pythStateInfo = info;
+    return info;
+}
+async function getWormholePackageId(client, wormholeStateId, cache) {
+    if (cache?.wormholePackageId)
+        return cache.wormholePackageId;
+    const result = await client.getObject({ objectId: wormholeStateId, include: { json: true } });
+    const json = result.object?.json;
+    if (!json)
+        throw new Error(`Cannot resolve wormhole package id from ${wormholeStateId}`);
+    const pkg = pkgFromUpgradeCap(json, wormholeStateId);
+    if (cache)
+        cache.wormholePackageId = pkg;
+    return pkg;
+}
+async function getPriceTableInfo(client, pythStateId, cache) {
+    if (cache?.priceTableInfo)
+        return cache.priceTableInfo;
+    const list = await client.listDynamicFields({ parentId: pythStateId });
+    const entry = list.dynamicFields.find((e) => {
+        const vt = e.valueType || e.objectType || "";
+        return vt.includes("PriceIdentifier") || vt.includes("price_info");
+    });
+    if (!entry)
+        throw new Error("Price table not found in Pyth state dynamic fields");
+    const childId = entry.childId ?? entry.objectId;
+    const typeStr = entry.valueType || entry.objectType || "";
+    if (!childId)
+        throw new Error("Price table missing childId");
+    const pkgMatch = typeStr.match(/(0x[a-fA-F0-9]+)::price_identifier::PriceIdentifier/);
+    if (!pkgMatch)
+        throw new Error(`Cannot extract package from price table type: ${typeStr}`);
+    const info = { id: childId, fieldType: pkgMatch[1] };
+    if (cache)
+        cache.priceTableInfo = info;
+    return info;
+}
+async function getPriceFeedObjectId(client, table, feedId, cache, pythStateId) {
+    const normalized = feedId.replace(/^0x/, "");
+    const cacheKey = pythStateId ? `${pythStateId}:${normalized}` : normalized;
+    if (cache?.priceFeedObjectIdCache.has(cacheKey)) {
+        return cache.priceFeedObjectIdCache.get(cacheKey);
+    }
+    const keyBytes = bcs
+        .struct("PriceIdentifier", { bytes: bcs.vector(bcs.u8()) })
+        .serialize({ bytes: fromHex(normalized) })
+        .toBytes();
+    const result = await client.getDynamicField({
+        parentId: table.id,
+        name: { type: `${table.fieldType}::price_identifier::PriceIdentifier`, bcs: keyBytes },
+    });
+    const value = result.dynamicField?.value;
+    const objectId = !value?.bcs || value.bcs.length < 32 ? undefined : "0x" + toHex(value.bcs);
+    if (cache)
+        cache.priceFeedObjectIdCache.set(cacheKey, objectId);
+    return objectId;
+}
+// ============================================================================
+// Accumulator parsing
+// ============================================================================
+function extractVaaBytes(accumulatorMessage) {
+    const view = new DataView(accumulatorMessage.buffer, accumulatorMessage.byteOffset, accumulatorMessage.byteLength);
+    const trailingPayloadSize = view.getUint8(6);
+    const vaaSizeOffset = 7 + trailingPayloadSize + 1; // +1 for proof_type
+    const vaaSize = view.getUint16(vaaSizeOffset, false);
+    const vaaOffset = vaaSizeOffset + 2;
+    return accumulatorMessage.subarray(vaaOffset, vaaOffset + vaaSize);
+}
+// ============================================================================
+// Pyth update calls
+// ============================================================================
+/**
+ * Append the on-chain Pyth update PTB block. Returns `PriceInfoObject` IDs
+ * (one per `feedIds`, same order). After this you can call
+ * `pyth_rule::feed` per ticker against the matching `PriceInfoObject`.
+ *
+ * If `sponsorFund` is provided, the per-feed update fee comes from the
+ * sponsor pool (`pyth_sponsor_rule::split`) instead of `tx.gas`.
+ */
+export async function buildPythPriceUpdateCalls(tx, client, updates, feedIds, cache, sponsorFund) {
+    if (updates.length === 0) {
+        throw new Error("No price update data provided; Hermes returned empty results");
+    }
+    if (updates.length > 1) {
+        throw new Error("Only a single accumulator message is supported per transaction");
+    }
+    const pyth = client.pyth;
+    const [stateInfo, wormholePackageId, table] = await Promise.all([
+        getPythStateInfo(client.grpcClient, pyth.state_id, cache),
+        getWormholePackageId(client.grpcClient, pyth.wormhole_state_id, cache),
+        getPriceTableInfo(client.grpcClient, pyth.state_id, cache),
+    ]);
+    const priceInfoObjectIds = await Promise.all(feedIds.map((feedId) => getPriceFeedObjectId(client.grpcClient, table, feedId, cache, pyth.state_id)));
+    const { packageId: pythPackageId, baseUpdateFee } = stateInfo;
+    // 1. Verify VAA
+    const vaa = extractVaaBytes(updates[0]);
+    const [verifiedVaa] = tx.moveCall({
+        target: `${wormholePackageId}::vaa::parse_and_verify`,
+        arguments: [tx.object(pyth.wormhole_state_id), tx.pure.vector("u8", vaa), tx.object.clock()],
+    });
+    // 2. Authenticate price infos
+    const [hotPotato0] = tx.moveCall({
+        target: `${pythPackageId}::pyth::create_authenticated_price_infos_using_accumulator`,
+        arguments: [
+            tx.object(pyth.state_id),
+            tx.pure.vector("u8", updates[0]),
+            verifiedVaa,
+            tx.object.clock(),
+        ],
+    });
+    // 3. Per-feed update
+    let hotPotato = hotPotato0;
+    for (let i = 0; i < feedIds.length; i++) {
+        const priceInfoObjectId = priceInfoObjectIds[i];
+        if (!priceInfoObjectId) {
+            throw new Error(`Pyth feed ${feedIds[i]} not registered on-chain in Pyth state`);
+        }
+        const feeCoin = sponsorFund
+            ? tx.moveCall({
+                target: `${sponsorFund.packageId}::pyth_sponsor_rule::split`,
+                arguments: [sponsorFund.fund],
+            })[0]
+            : tx.splitCoins(tx.gas, [tx.pure.u64(baseUpdateFee)])[0];
+        [hotPotato] = tx.moveCall({
+            target: `${pythPackageId}::pyth::update_single_price_feed`,
+            arguments: [
+                tx.object(pyth.state_id),
+                hotPotato,
+                tx.object(priceInfoObjectId),
+                feeCoin,
+                tx.object.clock(),
+            ],
+        });
+    }
+    // 4. Destroy hot potato
+    tx.moveCall({
+        target: `${pythPackageId}::hot_potato_vector::destroy`,
+        arguments: [hotPotato],
+        typeArguments: [`${pythPackageId}::price_info::PriceInfo`],
+    });
+    return priceInfoObjectIds;
+}
+/** All-in-one: fetch from Hermes, append update calls. Returns PriceInfoObject IDs. */
+export async function updatePythPrices(tx, client, feedIds, cache, sponsorFund) {
+    const updates = await fetchPriceFeedsUpdateData(client.pyth.hermes_endpoint, feedIds);
+    return buildPythPriceUpdateCalls(tx, client, updates, feedIds, cache, sponsorFund);
+}
+// ============================================================================
+// Per-ticker refresh: collector → pyth_rule::feed → oracle::aggregate
+// ============================================================================
+/**
+ * For a given ticker, build the collector → feed → aggregate chain that
+ * refreshes the on-chain `Oracle` aggregator for that ticker.
+ *
+ * Caller must have first called `buildPythPriceUpdateCalls` /
+ * `updatePythPrices` so the corresponding `PriceInfoObject` is fresh.
+ */
+export function aggregateTickerWithPyth(tx, client, args) {
+    const collector = newCollector({
+        package: client.config.packages.waterx_oracle.published_at,
+        arguments: { symbol: args.ticker },
+    })(tx);
+    pythRuleFeed({
+        package: client.config.packages.pyth_rule.published_at,
+        arguments: {
+            collector: collector,
+            config: tx.object(client.config.packages.pyth_rule.config),
+            pythState: tx.object(client.pyth.state_id),
+            pythPriceInfo: tx.object(args.priceInfoObjectId),
+        },
+    })(tx);
+    aggregateCall({
+        package: client.config.packages.waterx_oracle.published_at,
+        arguments: {
+            oracle: tx.object(client.config.packages.waterx_oracle.oracle),
+            collector: collector,
+        },
+    })(tx);
+}
+/**
+ * Refresh multiple tickers via Pyth in one PTB. Updates Pyth on-chain
+ * first (one accumulator), then runs the collector → feed → aggregate
+ * cycle for each ticker.
+ */
+export async function refreshOraclePrices(tx, client, tickers, opts = {}) {
+    if (tickers.length === 0)
+        return;
+    // tickers are oracle tickers (e.g. "BTCUSD"); look up each one's pyth feed
+    // entry from config — both feed_id (off-chain) and price_info_object
+    // (on-chain) are consumed by the per-ticker aggregate cycle.
+    const entries = tickers.map((t) => client.getPythFeed(t));
+    const feedIds = entries.map((e) => e.feed_id);
+    await updatePythPrices(tx, client, feedIds, opts.cache, opts.sponsorFund);
+    tickers.forEach((ticker, i) => {
+        aggregateTickerWithPyth(tx, client, {
+            ticker,
+            priceInfoObjectId: entries[i].price_info_object,
+        });
+    });
+}
+/**
+ * Opens a `Fund` hot potato from the shared PythSponsor pool. Pass the
+ * returned `{ fund, packageId }` straight to `refreshOraclePrices` as
+ * `sponsorFund`, then `reimbursePythSponsor` once the TradingRequest is
+ * built to attach the `PythSponsorRule` witness and return leftover
+ * balance.
+ */
+export function openPythSponsorFund(tx, client) {
+    const entry = client.config.packages.pyth_sponsor_rule;
+    if (!entry?.published_at || !entry.pyth_sponsor) {
+        throw new Error("pyth_sponsor_rule.{published_at,pyth_sponsor} missing — sponsor flow unavailable");
+    }
+    const [fund] = sponsorRequest({
+        package: entry.published_at,
+        arguments: { self: tx.object(entry.pyth_sponsor) },
+    })(tx);
+    return { fund: fund, packageId: entry.published_at };
+}
+/**
+ * Consumes the `Fund` hot potato from `openPythSponsorFund`, returns any
+ * leftover SUI to the sponsor pool, and attaches the `PythSponsorRule`
+ * witness to the given `TradingRequest<C_TOKEN>` so `trading::execute`
+ * can satisfy a checklist that includes `PythSponsorRule`.
+ */
+export function reimbursePythSponsor(tx, client, fund, tradingRequest, collateralType) {
+    const entry = client.config.packages.pyth_sponsor_rule;
+    if (!entry?.published_at || !entry.pyth_sponsor) {
+        throw new Error("pyth_sponsor_rule missing from config");
+    }
+    sponsorReimburse({
+        package: entry.published_at,
+        arguments: {
+            self: tx.object(entry.pyth_sponsor),
+            fund: fund,
+            tradingReq: tradingRequest,
+        },
+        typeArguments: [collateralType],
+    })(tx);
+}

package/dist/src/utils/wormhole.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Wormhole / Wormholescan integration for the cross-chain credit bridge.
+ *
+ * Single source of truth for VAA discovery + (de)serialization — mirrors
+ * `utils/pyth.ts`'s role for Pyth's Hermes endpoint. Two directions:
+ *
+ *   - Mint (EVM → Sui): fetch the signed VAA for an EVM `Deposit` by
+ *     (emitter chain, emitter address, sequence); the raw bytes feed
+ *     `wormhole_bridge::redeem_vaa`.
+ *   - Withdraw (Sui → EVM): list recent VAAs emitted by the bridge's
+ *     `EmitterCap` to submit on the EVM side.
+ *
+ * Endpoints / chain ids come from `client.wormhole` (network defaults in
+ * `WORMHOLE_DEFAULTS`, overridable via `WaterXConfig.wormhole`).
+ */
+import type { WaterXClient } from "../client.ts";
+/**
+ * Normalize an emitter id to Wormholescan's `emitter` path segment:
+ * 64-char lowercase hex, no `0x`. Accepts a 0x EVM address (left-padded to
+ * 32 bytes) or a 32-byte Sui object id (the bridge `EmitterCap` id).
+ */
+export declare function toWormholescanEmitter(idOrAddress: string): string;
+/** EVM-side naming alias of {@link toWormholescanEmitter}. */
+export declare const padEvmEmitter: typeof toWormholescanEmitter;
+export interface VaaResponse {
+    /** Base64-encoded signed VAA. */
+    vaa: string;
+    sequence: number;
+    emitterAddr: string;
+    guardianSetIndex: number;
+}
+export interface VaaListItem {
+    /** Wormholescan returns u64 as a string — keep it that way to avoid `number` precision loss. */
+    sequence: string;
+    /** Base64 VAA; absent until guardians have signed. */
+    vaa?: string;
+    emitterAddr?: string;
+}
+export interface WormholescanOptions {
+    /** Override `fetch` (tests / non-global-fetch environments). */
+    fetchImpl?: typeof fetch;
+    /** Request timeout in ms. Default 10_000. */
+    timeoutMs?: number;
+}
+/**
+ * Fetch a single signed VAA. Returns `null` while guardians haven't signed
+ * it yet (HTTP 404 or no `vaa` field) so callers can retry on the next tick.
+ */
+export declare function fetchVaa(apiBase: string, chainId: number, emitter: string, sequence: number | string | bigint, opts?: WormholescanOptions): Promise<VaaResponse | null>;
+/**
+ * List recent VAAs emitted by `emitter` on `chainId`, newest first. Used by
+ * the burn relayer to discover Sui→EVM `WithdrawalInitiated` messages
+ * (Wormholescan only returns guardian-signed VAAs, so the await is implicit).
+ */
+export declare function listVaasByEmitter(apiBase: string, chainId: number, emitter: string, opts?: WormholescanOptions & {
+    page?: number;
+    pageSize?: number;
+}): Promise<VaaListItem[]>;
+/** Poll {@link fetchVaa} until the VAA is signed or `timeoutMs` elapses. */
+export declare function waitForVaa(apiBase: string, chainId: number, emitter: string, sequence: number | string | bigint, opts?: WormholescanOptions & {
+    intervalMs?: number;
+    timeoutMs?: number;
+    onTick?: (attempt: number) => void;
+    signal?: AbortSignal;
+}): Promise<VaaResponse>;
+/** Base64 VAA → raw bytes (the form Sui `redeem_vaa(vector<u8>)` expects). */
+export declare function vaaBase64ToBytes(b64: string): Uint8Array;
+/** Raw bytes → base64 (round-trips a VAA pulled off-chain). */
+export declare function vaaBytesToBase64(bytes: Uint8Array): string;
+/** Base64 VAA → `0x`-prefixed hex (the form EVM `submitWithdrawalVAA(bytes)` expects). */
+export declare function vaaBase64ToHex(b64: string): `0x${string}`;
+/**
+ * Fetch the signed VAA for an inbound EVM `Deposit` using the client's
+ * configured Wormholescan endpoint. `emitter` is the EVM-side bridge
+ * address (0x form accepted — left-padded automatically); `chainId` is the
+ * source EVM chain's Wormhole chain id.
+ */
+export declare function fetchDepositVaa(client: WaterXClient, evmWormholeChainId: number, evmEmitter: string, sequence: number | string | bigint, opts?: WormholescanOptions): Promise<VaaResponse | null>;
+/**
+ * List recent Sui→EVM VAAs from the configured bridge `EmitterCap` (burn
+ * relayer). Requires `packages.wormhole_bridge.emitter_cap` in config.
+ */
+export declare function listBridgeWithdrawalVaas(client: WaterXClient, opts?: WormholescanOptions & {
+    page?: number;
+    pageSize?: number;
+}): Promise<VaaListItem[]>;

package/dist/src/utils/wormhole.js

@@ -0,0 +1,154 @@
+/**
+ * Wormhole / Wormholescan integration for the cross-chain credit bridge.
+ *
+ * Single source of truth for VAA discovery + (de)serialization — mirrors
+ * `utils/pyth.ts`'s role for Pyth's Hermes endpoint. Two directions:
+ *
+ *   - Mint (EVM → Sui): fetch the signed VAA for an EVM `Deposit` by
+ *     (emitter chain, emitter address, sequence); the raw bytes feed
+ *     `wormhole_bridge::redeem_vaa`.
+ *   - Withdraw (Sui → EVM): list recent VAAs emitted by the bridge's
+ *     `EmitterCap` to submit on the EVM side.
+ *
+ * Endpoints / chain ids come from `client.wormhole` (network defaults in
+ * `WORMHOLE_DEFAULTS`, overridable via `WaterXConfig.wormhole`).
+ */
+import { fromBase64, toBase64, toHex } from "@mysten/bcs";
+// ============================================================================
+// Emitter address formatting
+// ============================================================================
+/**
+ * Normalize an emitter id to Wormholescan's `emitter` path segment:
+ * 64-char lowercase hex, no `0x`. Accepts a 0x EVM address (left-padded to
+ * 32 bytes) or a 32-byte Sui object id (the bridge `EmitterCap` id).
+ */
+export function toWormholescanEmitter(idOrAddress) {
+    const raw = idOrAddress.startsWith("0x") ? idOrAddress.slice(2) : idOrAddress;
+    return raw.toLowerCase().padStart(64, "0");
+}
+/** EVM-side naming alias of {@link toWormholescanEmitter}. */
+export const padEvmEmitter = toWormholescanEmitter;
+async function doFetch(url, opts) {
+    const fetchImpl = opts?.fetchImpl ?? globalThis.fetch;
+    if (!fetchImpl) {
+        throw new Error("wormhole: no global `fetch` available; pass opts.fetchImpl");
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts?.timeoutMs ?? 10_000);
+    const onOuterAbort = () => controller.abort();
+    opts?.signal?.addEventListener("abort", onOuterAbort, { once: true });
+    try {
+        return await fetchImpl(url, { cache: "no-store", signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timer);
+        opts?.signal?.removeEventListener("abort", onOuterAbort);
+    }
+}
+/**
+ * Fetch a single signed VAA. Returns `null` while guardians haven't signed
+ * it yet (HTTP 404 or no `vaa` field) so callers can retry on the next tick.
+ */
+export async function fetchVaa(apiBase, chainId, emitter, sequence, opts) {
+    const url = `${apiBase}/vaas/${chainId}/${emitter}/${sequence}`;
+    const res = await doFetch(url, opts);
+    if (res.status === 404)
+        return null;
+    if (!res.ok) {
+        throw new Error(`Wormholescan ${res.status}: ${await res.text()}`);
+    }
+    const json = (await res.json());
+    if (!json?.data?.vaa)
+        return null;
+    return json.data;
+}
+/**
+ * List recent VAAs emitted by `emitter` on `chainId`, newest first. Used by
+ * the burn relayer to discover Sui→EVM `WithdrawalInitiated` messages
+ * (Wormholescan only returns guardian-signed VAAs, so the await is implicit).
+ */
+export async function listVaasByEmitter(apiBase, chainId, emitter, opts) {
+    const page = opts?.page ?? 0;
+    const pageSize = opts?.pageSize ?? 20;
+    const url = `${apiBase}/vaas/${chainId}/${emitter}?page=${page}&pageSize=${pageSize}`;
+    const res = await doFetch(url, opts);
+    if (!res.ok) {
+        throw new Error(`Wormholescan list ${res.status}: ${await res.text()}`);
+    }
+    const json = (await res.json());
+    return json.data ?? [];
+}
+/** Poll {@link fetchVaa} until the VAA is signed or `timeoutMs` elapses. */
+export async function waitForVaa(apiBase, chainId, emitter, sequence, opts = {}) {
+    const intervalMs = opts.intervalMs ?? 30_000;
+    const timeoutMs = opts.timeoutMs ?? 25 * 60_000;
+    const start = Date.now();
+    let attempt = 0;
+    while (Date.now() - start < timeoutMs) {
+        if (opts.signal?.aborted)
+            throw new Error("waitForVaa: aborted");
+        attempt++;
+        opts.onTick?.(attempt);
+        const vaa = await fetchVaa(apiBase, chainId, emitter, sequence, opts);
+        if (vaa)
+            return vaa;
+        await abortableSleep(intervalMs, opts.signal);
+    }
+    throw new Error("waitForVaa: timeout");
+}
+function abortableSleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new Error("waitForVaa: aborted"));
+        };
+        if (signal?.aborted) {
+            clearTimeout(timer);
+            reject(new Error("waitForVaa: aborted"));
+            return;
+        }
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+// ============================================================================
+// VAA (de)serialization — portable (Node + edge/browser)
+// ============================================================================
+/** Base64 VAA → raw bytes (the form Sui `redeem_vaa(vector<u8>)` expects). */
+export function vaaBase64ToBytes(b64) {
+    return fromBase64(b64);
+}
+/** Raw bytes → base64 (round-trips a VAA pulled off-chain). */
+export function vaaBytesToBase64(bytes) {
+    return toBase64(bytes);
+}
+/** Base64 VAA → `0x`-prefixed hex (the form EVM `submitWithdrawalVAA(bytes)` expects). */
+export function vaaBase64ToHex(b64) {
+    return `0x${toHex(fromBase64(b64))}`;
+}
+// ============================================================================
+// Client-aware convenience
+// ============================================================================
+/**
+ * Fetch the signed VAA for an inbound EVM `Deposit` using the client's
+ * configured Wormholescan endpoint. `emitter` is the EVM-side bridge
+ * address (0x form accepted — left-padded automatically); `chainId` is the
+ * source EVM chain's Wormhole chain id.
+ */
+export function fetchDepositVaa(client, evmWormholeChainId, evmEmitter, sequence, opts) {
+    return fetchVaa(client.wormhole.wormholescan_api, evmWormholeChainId, toWormholescanEmitter(evmEmitter), sequence, opts);
+}
+/**
+ * List recent Sui→EVM VAAs from the configured bridge `EmitterCap` (burn
+ * relayer). Requires `packages.wormhole_bridge.emitter_cap` in config.
+ */
+export function listBridgeWithdrawalVaas(client, opts) {
+    const emitterCap = client.config.packages.wormhole_bridge?.emitter_cap;
+    if (!emitterCap) {
+        throw new Error("wormhole_bridge.emitter_cap missing from config");
+    }
+    return listVaasByEmitter(client.wormhole.wormholescan_api, client.wormhole.sui_chain_id, toWormholescanEmitter(emitterCap), opts);
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@waterx/sdk",
+  "version": "2.1.0",
+  "description": "WaterX Perpetual Protocol SDK",
+  "license": "MIT",
+  "author": "WaterX",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/WaterXProtocol/waterx-sdk.git"
+  },
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "package.json"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && tsc-alias",
+    "codegen": "tsx scripts/codegen-summaries.ts && npx sui-ts-codegen generate && tsx scripts/fix-generated-imports.ts",
+    "lint": "pnpm lint:eslint && pnpm lint:prettier",
+    "lint:eslint": "eslint \"src/**/*.ts\" \"test/**/*.ts\" \"scripts/**/*.ts\" \"examples/**/*.ts\" \"vitest.config.ts\"",
+    "lint:prettier": "prettier --check \"src/**/*.ts\" \"test/**/*.ts\" \"scripts/**/*.ts\" \"examples/**/*.ts\" \"vitest.config.ts\" \"eslint.config.mjs\" \"sui-codegen.config.mjs\"",
+    "lint:fix": "eslint \"src/**/*.ts\" \"test/**/*.ts\" \"scripts/**/*.ts\" \"examples/**/*.ts\" \"vitest.config.ts\" --fix",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\" \"scripts/**/*.ts\" \"examples/**/*.ts\" \"vitest.config.ts\" \"eslint.config.mjs\" \"sui-codegen.config.mjs\"",
+    "env:init": "tsx scripts/init-local-env.ts",
+    "typecheck": "tsc --noEmit",
+    "test:integration": "tsx scripts/run-integration.ts --testnet",
+    "test:integration:mainnet": "tsx scripts/run-integration.ts --mainnet",
+    "test:integration:lifecycle": "tsx scripts/run-integration.ts --testnet test/integration/user/trader-position-lifecycle.test.ts",
+    "test:integration:market-config": "tsx scripts/run-integration.ts --testnet test/integration/user/trader-market-onchain-config.test.ts",
+    "test:integration:persistent-state": "tsx scripts/run-integration.ts --testnet test/integration/user/trader-e2e-persistent-state.test.ts",
+    "test:integration:gap": "tsx scripts/run-integration.ts --testnet test/integration/user/trader-wlp-redeem.test.ts test/integration/user/trader-staking.test.ts test/integration/user/trader-keeper-roundtrip.test.ts test/integration/user/trader-custody.test.ts test/integration/user/trader-credit-pipeline.test.ts",
+    "test:integration:onboarding": "tsx scripts/run-integration.ts --testnet test/integration/user/trader-full-onboarding.test.ts",
+    "smoke:chain": "tsx scripts/run-smoke-chain.ts",
+    "smoke:chain:dry": "tsx scripts/run-smoke-chain.ts --dry-run"
+  },
+  "peerDependencies": {
+    "@mysten/bcs": "^1.9.0",
+    "@mysten/sui": "^2.9.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "@ianvs/prettier-plugin-sort-imports": "^4.7.1",
+    "@mysten/bcs": "^1.9.2",
+    "@mysten/sui": "^2.9.1",
+    "@mysten/codegen": "^0.8.3",
+    "@types/node": "^24.12.0",
+    "@typescript-eslint/eslint-plugin": "^8.58.0",
+    "@typescript-eslint/parser": "^8.58.0",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.4.0",
+    "prettier": "^3.8.1",
+    "tsc-alias": "^1.8.16",
+    "tsconfig-paths": "^4.2.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.58.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "dotenv": "^17.4.0",
+    "vitest": "^3.2.4"
+  },
+  "packageManager": "pnpm@9.15.0"
+}