@lightconexyz/lightcone-sdk 0.8.1 → 0.8.2

package/dist/domain/position/client.js

@@ -1,13 +1,92 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Positions = void 0;
+exports.nativeWithdrawSeed = nativeWithdrawSeed;
 const web3_js_1 = require("@solana/web3.js");
+const spl_token_1 = require("@solana/spl-token");
+const sha256_1 = require("@noble/hashes/sha256");
+const bs58_1 = __importDefault(require("bs58"));
+const auth_1 = require("../../auth");
 const context_1 = require("../../context");
+const error_1 = require("../../error");
 const http_1 = require("../../http");
 const instructions_1 = require("../../program/instructions");
+const rpc_1 = require("../../rpc");
 const pda_1 = require("../../program/pda");
 const accounts_1 = require("../../program/accounts");
+const utils_1 = require("../../program/utils");
+const signing_1 = require("../../shared/signing");
+const state_1 = require("./state");
 const builders_1 = require("./builders");
+/** Byte allocation for a legacy SPL Token Program (Tokenkeg) account. */
+const TOKEN_ACCOUNT_SPACE = 165;
+/** Largest exact lamport amount accepted by Solana transaction instructions. */
+const MAX_U64 = 0xffffffffffffffffn;
+/** Reject non-bigint, non-positive, or non-u64 lamports before any RPC side effect. */
+function assertSolActionAmount(amountLamports, action) {
+    if (typeof amountLamports !== "bigint") {
+        throw error_1.SdkError.validation(`${action} amount must be exact bigint lamports`);
+    }
+    if (amountLamports <= 0n) {
+        throw error_1.SdkError.validation(`${action} amount must be greater than zero`);
+    }
+    if (amountLamports > MAX_U64) {
+        throw error_1.SdkError.validation(`${action} amount must fit u64`);
+    }
+}
+function assertUnsponsoredPlan(sponsored) {
+    if (sponsored) {
+        throw error_1.SdkError.validation("sponsored SOL action planning is not supported");
+    }
+}
+/**
+ * Derive the cross-SDK temporary-account seed for native withdrawal.
+ *
+ * SHA-256 receives the ASCII domain `lightcone:wsol-withdraw:v1`, one zero byte,
+ * raw 32-byte blockhash, wallet, and recipient keys, the amount as unsigned
+ * eight-byte big-endian lamports, then the one-byte attempt. The first 16 digest
+ * bytes become 32 lowercase hexadecimal ASCII characters for Solana's seed limit.
+ */
+function nativeWithdrawSeed(recentBlockhash, wallet, recipient, amountLamports, attempt) {
+    if (!Number.isInteger(attempt) || attempt < 0 || attempt > 255) {
+        throw error_1.SdkError.validation("temporary WSOL seed attempt must fit u8");
+    }
+    if (amountLamports < 0n || amountLamports > MAX_U64) {
+        throw error_1.SdkError.validation("withdraw amount must fit u64");
+    }
+    const domain = new TextEncoder().encode("lightcone:wsol-withdraw:v1");
+    const blockhash = bs58_1.default.decode(recentBlockhash);
+    if (blockhash.length !== 32) {
+        throw error_1.SdkError.validation("recent blockhash must decode to 32 bytes");
+    }
+    const preimage = new Uint8Array(domain.length + 1 + 32 + 32 + 32 + 8 + 1);
+    let offset = 0;
+    preimage.set(domain, offset);
+    offset += domain.length;
+    preimage[offset++] = 0;
+    preimage.set(blockhash, offset);
+    offset += 32;
+    preimage.set(wallet.toBytes(), offset);
+    offset += 32;
+    preimage.set(recipient.toBytes(), offset);
+    offset += 32;
+    new DataView(preimage.buffer).setBigUint64(offset, amountLamports, false);
+    offset += 8;
+    preimage[offset] = attempt;
+    return Array.from((0, sha256_1.sha256)(preimage).slice(0, 16), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/**
+ * Plans position operations and explicit canonical WSOL conversions.
+ *
+ * Explicit conversion state flows as follows: complete matching wallet state and
+ * native keypair -> live account and cost reads -> signer, account, reserve, and
+ * amount guards -> fee-prepared plan -> unchanged prepared submission -> complete
+ * snapshot covering the confirmed slot. An uncertain submission returns control
+ * to the caller, which refreshes authoritative state before planning again.
+ */
 class Positions {
     client;
     constructor(client) {
@@ -71,9 +150,12 @@ class Positions {
         return this.client.http.getWithCookies(url, http_1.RetryPolicy.Idempotent, cookieHeader);
     }
     /**
-     * Get a confirmed-slot snapshot of the authenticated user's deposit-token
-     * balances. When supplied, `minContextSlot` prevents an older cached
-     * snapshot from satisfying the request.
+     * Fetch a complete authenticated SPL and native-SOL balance snapshot.
+     *
+     * `minContextSlot` lower-bounds the cross-component snapshot. Native SOL is
+     * required canonical nine-decimal text and remains outside the SPL map. The
+     * generic HTTP layer trusts that shape at runtime; WebSocket frames are decoded
+     * strictly, while malformed REST exact values fail later when state scales them.
      */
     async depositTokenBalances(minContextSlot) {
         const query = minContextSlot === undefined
@@ -88,7 +170,8 @@ class Positions {
      *
      * Intended for server-side cookie forwarding (SSR / server functions)
      * where the per-request browser cookie can't propagate to the shared
-     * client. In a browser context this is equivalent to
+     * client. The complete response has the same separate, exact native-SOL
+     * contract as {@link depositTokenBalances}. In a browser this is equivalent to
      * {@link depositTokenBalances} because the runtime is already attaching
      * the cookie via `credentials: "include"`.
      */
@@ -99,6 +182,511 @@ class Positions {
         const url = `${this.client.http.baseUrl()}/api/users/deposit-token-balances${query}`;
         return this.client.http.getWithCookies(url, http_1.RetryPolicy.Idempotent, cookieHeader);
     }
+    /**
+     * Return a fee-prepared plan for an exact canonical WSOL wrap.
+     *
+     * The authenticated Trading Wallet must have a local native keypair and complete
+     * balance state. Live canonical account data must match that state. An existing
+     * account must have account lamports equal to its token amount plus native
+     * reserve. Otherwise a later `SyncNative` instruction would recalculate the WSOL
+     * token amount from account lamports and wrap donated excess beyond
+     * `amountLamports`. The returned transaction contains strict Tokenkeg ATA
+     * creation only when the account is absent. It then contains the exact transfer
+     * and `SyncNative`. Availability uses the ordinary reserve floor.
+     *
+     * Callers rebuild immediately before prepared submission. They retain the
+     * returned component projection until a complete snapshot covers the confirmed
+     * slot. An uncertain outcome requires authoritative refresh before another plan.
+     */
+    async planWrapSol(amountLamports, state) {
+        assertSolActionAmount(amountLamports, "wrap");
+        const wallet = this.conversionPlanningWallet(state);
+        const components = state.solComponents();
+        const rpc = new rpc_1.Rpc(this.client);
+        const canonical = (0, spl_token_1.getAssociatedTokenAddressSync)(spl_token_1.NATIVE_MINT, wallet);
+        const account = await rpc.canonicalWsolAccountInfo(canonical, wallet);
+        if (!account && components.canonicalWsolLamports > 0n) {
+            throw error_1.SdkError.validation("canonical WSOL balance is positive but its account is unavailable");
+        }
+        if (account &&
+            account.tokenAmountLamports !== components.canonicalWsolLamports) {
+            throw error_1.SdkError.validation("live canonical WSOL amount does not match wallet balance state");
+        }
+        if (account &&
+            account.accountLamports !==
+                account.tokenAmountLamports + account.nativeReserveLamports) {
+            throw error_1.SdkError.validation("canonical WSOL account has unsynchronized native lamports");
+        }
+        if (account &&
+            (account.tokenAmountLamports + amountLamports > MAX_U64 ||
+                account.accountLamports + amountLamports > MAX_U64)) {
+            throw error_1.SdkError.validation("wrap would exceed canonical WSOL token or account u64 range");
+        }
+        const createsCanonicalWsolAccount = account === null;
+        const upfrontRentLamports = createsCanonicalWsolAccount
+            ? await rpc.minimumBalanceForRentExemption(TOKEN_ACCOUNT_SPACE)
+            : 0n;
+        const transaction = this.buildWrapSolTransaction(wallet, amountLamports, createsCanonicalWsolAccount);
+        const feeLamports = await rpc.prepareAndEstimateTransactionFee(transaction);
+        const costs = {
+            feeLamports,
+            upfrontRentLamports,
+            createsCanonicalWsolAccount,
+            sponsored: false,
+        };
+        const availability = (0, state_1.solBalanceAvailability)(components, costs);
+        const requiredNativeLamports = amountLamports + availability.reserveLamports;
+        if (requiredNativeLamports > MAX_U64) {
+            throw error_1.SdkError.validation("wrap amount and transaction reserve exceed u64 lamports");
+        }
+        if (components.nativeLamports < requiredNativeLamports) {
+            throw error_1.SdkError.validation("native SOL cannot fund the wrap amount and transaction reserve");
+        }
+        return {
+            kind: "wrap",
+            transaction,
+            costs,
+            availability,
+            expectedDelta: {
+                nativeLamports: -amountLamports - feeLamports - upfrontRentLamports,
+                canonicalWsolLamports: amountLamports,
+            },
+        };
+    }
+    /**
+     * Return a fee-prepared plan for closing the complete canonical WSOL account.
+     *
+     * The Trading Wallet must have a local native keypair. Canonical WSOL in the
+     * complete balance state must be positive and equal the live token amount. The
+     * returned transaction contains one `CloseAccount` instruction whose authority,
+     * destination, and fee payer are that wallet. If submitted successfully, the
+     * instruction transfers the complete account balance, including rent and donated
+     * lamports. The returned costs contain only the fresh fee. Availability requires
+     * native SOL to fund that fee without relying on the later account transfer.
+     *
+     * Callers rebuild immediately before prepared submission. They retain the
+     * returned component projection until a complete snapshot covers the confirmed
+     * slot. Signing, submission, or confirmation uncertainty requires authoritative
+     * refresh and does not authorize automatic resubmission.
+     */
+    async planUnwrapWsolAll(state) {
+        const wallet = this.conversionPlanningWallet(state);
+        const components = state.solComponents();
+        if (components.canonicalWsolLamports === 0n) {
+            throw error_1.SdkError.validation("unwrap-all requires a positive canonical WSOL balance");
+        }
+        const rpc = new rpc_1.Rpc(this.client);
+        const canonical = (0, spl_token_1.getAssociatedTokenAddressSync)(spl_token_1.NATIVE_MINT, wallet);
+        const account = await rpc.canonicalWsolAccountInfo(canonical, wallet);
+        if (!account) {
+            throw error_1.SdkError.validation("canonical WSOL account is required for unwrap-all");
+        }
+        if (account.tokenAmountLamports !== components.canonicalWsolLamports) {
+            throw error_1.SdkError.validation("live canonical WSOL amount does not match wallet balance state");
+        }
+        const transaction = this.buildUnwrapWsolAllTransaction(wallet);
+        const feeLamports = await rpc.prepareAndEstimateTransactionFee(transaction);
+        const costs = {
+            feeLamports,
+            upfrontRentLamports: 0n,
+            createsCanonicalWsolAccount: false,
+            sponsored: false,
+        };
+        // Unwrap-all removes the persistent account, so its availability validates
+        // SolActionCosts and reserves the fee without the ordinary account floor.
+        const availability = (0, state_1.unwrapAllSolBalanceAvailability)(components, costs);
+        const projectedNativeLamports = components.nativeLamports + account.accountLamports - feeLamports;
+        if (projectedNativeLamports > MAX_U64) {
+            throw error_1.SdkError.validation("unwrap-all projected native SOL exceeds the transaction u64 range");
+        }
+        return {
+            kind: "unwrapAll",
+            transaction,
+            costs,
+            availability,
+            expectedDelta: {
+                nativeLamports: account.accountLamports - feeLamports,
+                canonicalWsolLamports: -components.canonicalWsolLamports,
+            },
+        };
+    }
+    /**
+     * Plan one atomic split that consumes canonical WSOL before wrapping a shortfall.
+     * Amounts and live costs are lamports; unavailable account, fee, or rent reads
+     * fail closed, and sponsored planning is rejected until a sponsor owns costs.
+     */
+    async planSolSplit(market, amountLamports, state, sponsored) {
+        assertUnsponsoredPlan(sponsored);
+        assertSolActionAmount(amountLamports, "split");
+        const wallet = this.planningWallet(state);
+        const components = state.solComponents();
+        const rpc = new rpc_1.Rpc(this.client);
+        const canonical = (0, spl_token_1.getAssociatedTokenAddressSync)(spl_token_1.NATIVE_MINT, wallet);
+        const canonicalExists = await rpc.canonicalWsolAccountExists(canonical, wallet);
+        if (components.canonicalWsolLamports > 0n && !canonicalExists) {
+            throw error_1.SdkError.validation("canonical WSOL balance is positive but its account is unavailable");
+        }
+        const shortfall = amountLamports > components.canonicalWsolLamports
+            ? amountLamports - components.canonicalWsolLamports
+            : 0n;
+        const upfrontRentLamports = canonicalExists
+            ? 0n
+            : await rpc.minimumBalanceForRentExemption(TOKEN_ACCOUNT_SPACE);
+        const transaction = new web3_js_1.Transaction({ feePayer: wallet });
+        if (!canonicalExists) {
+            transaction.add((0, spl_token_1.createAssociatedTokenAccountIdempotentInstruction)(wallet, canonical, wallet, spl_token_1.NATIVE_MINT, spl_token_1.TOKEN_PROGRAM_ID));
+        }
+        if (shortfall > 0n) {
+            transaction.add(web3_js_1.SystemProgram.transfer({ fromPubkey: wallet, toPubkey: canonical, lamports: shortfall }), (0, spl_token_1.createSyncNativeInstruction)(canonical, spl_token_1.TOKEN_PROGRAM_ID));
+        }
+        transaction.add((0, instructions_1.buildDepositIx)({
+            user: wallet,
+            market: new web3_js_1.PublicKey(market.pubkey),
+            depositMint: spl_token_1.NATIVE_MINT,
+            amount: amountLamports,
+        }, market.numOutcomes, this.client.programId));
+        const feeLamports = await rpc.prepareAndEstimateTransactionFee(transaction);
+        const costs = {
+            feeLamports,
+            upfrontRentLamports,
+            createsCanonicalWsolAccount: !canonicalExists,
+            sponsored,
+        };
+        const availability = (0, state_1.solBalanceAvailability)(components, costs);
+        if (amountLamports > availability.spendableLamports) {
+            throw error_1.SdkError.validation("split amount exceeds spendable SOL after transaction reserve");
+        }
+        if (shortfall + availability.reserveLamports > components.nativeLamports) {
+            throw error_1.SdkError.validation("native SOL cannot fund the wrap shortfall and transaction reserve");
+        }
+        const walletCosts = sponsored ? 0n : feeLamports + upfrontRentLamports;
+        return {
+            kind: "split",
+            transaction,
+            costs,
+            availability,
+            expectedDelta: {
+                nativeLamports: -shortfall - walletCosts,
+                canonicalWsolLamports: shortfall - amountLamports,
+            },
+        };
+    }
+    /**
+     * Plan a merge that leaves returned WSOL in the persistent canonical ATA.
+     * The prepared transaction does not mutate cached state; refresh authority
+     * after confirmed submission.
+     */
+    async planSolMerge(market, amountLamports, state, sponsored) {
+        assertUnsponsoredPlan(sponsored);
+        assertSolActionAmount(amountLamports, "merge");
+        const wallet = this.planningWallet(state);
+        const transaction = new web3_js_1.Transaction({ feePayer: wallet });
+        const { rpc, components, canonicalExists, upfrontRentLamports } = await this.receivePlanContext(wallet, state);
+        if (!canonicalExists) {
+            transaction.add(this.createCanonicalWsolAccount(wallet));
+        }
+        transaction.add((0, instructions_1.buildMergeIx)({
+            user: wallet,
+            market: new web3_js_1.PublicKey(market.pubkey),
+            depositMint: spl_token_1.NATIVE_MINT,
+            amount: amountLamports,
+        }, market.numOutcomes, this.client.programId));
+        return this.finishReceivePlan("merge", amountLamports, transaction, rpc, components, upfrontRentLamports, !canonicalExists, sponsored);
+    }
+    /**
+     * Plan a redemption that leaves returned WSOL in the persistent canonical ATA.
+     * `amountLamports` is exact collateral scale; `outcomeIndex` is validated
+     * against the supplied authoritative `numOutcomes`.
+     */
+    async planSolRedeem(market, amountLamports, outcomeIndex, numOutcomes, state, sponsored) {
+        assertUnsponsoredPlan(sponsored);
+        assertSolActionAmount(amountLamports, "redeem");
+        (0, utils_1.validateOutcomes)(numOutcomes);
+        (0, utils_1.validateOutcomeIndex)(outcomeIndex, numOutcomes);
+        const wallet = this.planningWallet(state);
+        const transaction = new web3_js_1.Transaction({ feePayer: wallet });
+        const { rpc, components, canonicalExists, upfrontRentLamports } = await this.receivePlanContext(wallet, state);
+        if (!canonicalExists) {
+            transaction.add(this.createCanonicalWsolAccount(wallet));
+        }
+        transaction.add((0, instructions_1.buildRedeemWinningsIx)({
+            user: wallet,
+            market,
+            depositMint: spl_token_1.NATIVE_MINT,
+            amount: amountLamports,
+        }, outcomeIndex, this.client.programId));
+        return this.finishReceivePlan("redeem", amountLamports, transaction, rpc, components, upfrontRentLamports, !canonicalExists, sponsored);
+    }
+    /**
+     * Plan exact native SOL delivery without closing the canonical WSOL ATA.
+     *
+     * Native funds are preferred. A shortfall uses a bounded seeded Tokenkeg
+       * account whose rent returns on close; all account, rent, and fee reads fail
+       * closed. At most eight blockhash-scoped candidates bound RPC latency while
+       * making accidental exhaustion negligible. The returned transaction already
+       * carries its prepared message.
+     */
+    async planNativeSolWithdrawal(recipient, amountLamports, state, sponsored) {
+        assertUnsponsoredPlan(sponsored);
+        assertSolActionAmount(amountLamports, "withdraw");
+        const wallet = this.planningWallet(state);
+        const components = state.solComponents();
+        const rpc = new rpc_1.Rpc(this.client);
+        const direct = new web3_js_1.Transaction({ feePayer: wallet }).add(web3_js_1.SystemProgram.transfer({ fromPubkey: wallet, toPubkey: recipient, lamports: amountLamports }));
+        const directFee = await rpc.prepareAndEstimateTransactionFee(direct);
+        const directCosts = {
+            feeLamports: directFee,
+            upfrontRentLamports: 0n,
+            createsCanonicalWsolAccount: false,
+            sponsored,
+        };
+        const directAvailability = (0, state_1.solBalanceAvailability)(components, directCosts);
+        if (amountLamports > directAvailability.spendableLamports) {
+            throw error_1.SdkError.validation("withdraw amount exceeds spendable SOL after transaction reserve");
+        }
+        if (components.nativeLamports >=
+            amountLamports + directAvailability.reserveLamports) {
+            return {
+                kind: "nativeWithdraw",
+                transaction: direct,
+                costs: directCosts,
+                availability: directAvailability,
+                expectedDelta: {
+                    nativeLamports: -amountLamports - (sponsored ? 0n : directFee),
+                    canonicalWsolLamports: 0n,
+                },
+            };
+        }
+        const canonical = (0, spl_token_1.getAssociatedTokenAddressSync)(spl_token_1.NATIVE_MINT, wallet);
+        if (!(await rpc.canonicalWsolAccountExists(canonical, wallet))) {
+            throw error_1.SdkError.validation("canonical WSOL is required for this native withdrawal");
+        }
+        const temporaryRent = await rpc.minimumBalanceForRentExemption(TOKEN_ACCOUNT_SPACE);
+        const { blockhash, lastValidBlockHeight } = await rpc.getLatestBlockhash();
+        let seed;
+        let temporary;
+        // Bound account-existence RPCs; the blockhash and attempt byte make eight collisions remote.
+        for (let attempt = 0; attempt <= 7; attempt++) {
+            const candidateSeed = nativeWithdrawSeed(blockhash, wallet, recipient, amountLamports, attempt);
+            const candidate = await web3_js_1.PublicKey.createWithSeed(wallet, candidateSeed, spl_token_1.TOKEN_PROGRAM_ID);
+            if (!(await rpc.accountExists(candidate))) {
+                seed = candidateSeed;
+                temporary = candidate;
+                break;
+            }
+        }
+        if (!seed || !temporary) {
+            throw error_1.SdkError.validation("temporary WSOL seed attempts are exhausted");
+        }
+        let transaction = this.buildTemporaryNativeWithdrawal(wallet, recipient, amountLamports, 1n, temporaryRent, seed, temporary);
+        transaction.recentBlockhash = blockhash;
+        transaction.lastValidBlockHeight = lastValidBlockHeight;
+        const initialFee = await rpc.estimatePreparedTransactionFee(transaction);
+        const initialCosts = {
+            feeLamports: initialFee,
+            upfrontRentLamports: temporaryRent,
+            createsCanonicalWsolAccount: false,
+            sponsored,
+        };
+        const initialAvailability = (0, state_1.solBalanceAvailability)(components, initialCosts);
+        const initialRequired = amountLamports + initialAvailability.reserveLamports;
+        if (initialRequired < components.nativeLamports) {
+            throw error_1.SdkError.validation("invalid temporary withdrawal requirement");
+        }
+        const initialTransfer = initialRequired - components.nativeLamports;
+        transaction = this.buildTemporaryNativeWithdrawal(wallet, recipient, amountLamports, initialTransfer, temporaryRent, seed, temporary);
+        transaction.recentBlockhash = blockhash;
+        transaction.lastValidBlockHeight = lastValidBlockHeight;
+        const finalFee = await rpc.estimatePreparedTransactionFee(transaction);
+        const costs = {
+            feeLamports: finalFee,
+            upfrontRentLamports: temporaryRent,
+            createsCanonicalWsolAccount: false,
+            sponsored,
+        };
+        const availability = (0, state_1.solBalanceAvailability)(components, costs);
+        const finalRequired = amountLamports + availability.reserveLamports;
+        if (finalRequired < components.nativeLamports) {
+            throw error_1.SdkError.validation("invalid temporary withdrawal requirement");
+        }
+        const canonicalTransfer = finalRequired - components.nativeLamports;
+        if (canonicalTransfer > components.canonicalWsolLamports) {
+            throw error_1.SdkError.validation("canonical WSOL cannot fund the native withdrawal shortfall");
+        }
+        if (canonicalTransfer !== initialTransfer) {
+            transaction = this.buildTemporaryNativeWithdrawal(wallet, recipient, amountLamports, canonicalTransfer, temporaryRent, seed, temporary);
+            transaction.recentBlockhash = blockhash;
+            transaction.lastValidBlockHeight = lastValidBlockHeight;
+            const stableFee = await rpc.estimatePreparedTransactionFee(transaction);
+            if (stableFee !== finalFee) {
+                throw error_1.SdkError.validation("transaction fee changed while rebuilding native withdrawal");
+            }
+        }
+        return {
+            kind: "nativeWithdraw",
+            transaction,
+            costs,
+            availability,
+            expectedDelta: {
+                nativeLamports: canonicalTransfer - amountLamports - (sponsored ? 0n : finalFee),
+                canonicalWsolLamports: -canonicalTransfer,
+            },
+        };
+    }
+    /** Resolve the authenticated wallet only from fresh matching cached authority. */
+    planningWallet(state) {
+        // Cached identity is a signing trust boundary: validate expiry, complete
+        // state initialization, and wallet equality before constructing a transaction.
+        const credentials = this.client.authCredentials;
+        if (!credentials) {
+            throw error_1.SdkError.validation("authenticated credentials are required");
+        }
+        if (!(0, auth_1.isAuthenticated)(credentials)) {
+            throw error_1.SdkError.validation("authenticated credentials have expired");
+        }
+        if (state.walletAddress === undefined ||
+            state.contextSlot === undefined ||
+            state.nativeSolBalance === undefined) {
+            throw error_1.SdkError.validation("wallet balance state is not initialized");
+        }
+        if (state.walletAddress !== credentials.wallet_address) {
+            throw error_1.SdkError.validation("authenticated wallet does not match wallet balance state");
+        }
+        let wallet;
+        try {
+            wallet = new web3_js_1.PublicKey(credentials.wallet_address);
+        }
+        catch (error) {
+            throw error_1.SdkError.validation(`authenticated wallet is invalid: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const strategy = (0, context_1.requireSigningStrategy)(this.client);
+        const signingAddress = (0, signing_1.signingStrategyWalletAddress)(strategy);
+        if (!signingAddress) {
+            throw error_1.SdkError.validation("signing strategy wallet identity is required");
+        }
+        let signingWallet;
+        try {
+            signingWallet = new web3_js_1.PublicKey(signingAddress);
+        }
+        catch (error) {
+            throw error_1.SdkError.validation(`signing strategy wallet is invalid: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (!signingWallet.equals(wallet)) {
+            throw error_1.SdkError.validation("signing strategy does not control authenticated wallet");
+        }
+        return wallet;
+    }
+    /**
+     * Return the authenticated Trading Wallet after native-keypair validation.
+     *
+     * Complete wallet state and identity are validated by `planningWallet`. This
+     * additional guard rejects wallet-adapter and Privy strategies before conversion
+     * RPC reads. Ordinary planners do not call this method.
+     */
+    conversionPlanningWallet(state) {
+        (0, signing_1.requireNativeSigningStrategy)((0, context_1.requireSigningStrategy)(this.client));
+        return this.planningWallet(state);
+    }
+    /**
+     * Return an unsigned wrap transaction with exact instruction ordering.
+     *
+     * When planning observed no canonical ATA, the first instruction is strict ATA
+     * creation. A concurrently created ATA therefore makes execution fail instead of
+     * using account state that was absent from the plan. The transfer and `SyncNative`
+     * instructions follow. Fee preparation later attaches the live blockhash.
+     */
+    buildWrapSolTransaction(wallet, amountLamports, createsCanonicalWsolAccount) {
+        const canonical = (0, spl_token_1.getAssociatedTokenAddressSync)(spl_token_1.NATIVE_MINT, wallet);
+        const transaction = new web3_js_1.Transaction({ feePayer: wallet });
+        if (createsCanonicalWsolAccount) {
+            transaction.add((0, spl_token_1.createAssociatedTokenAccountInstruction)(wallet, canonical, wallet, spl_token_1.NATIVE_MINT, spl_token_1.TOKEN_PROGRAM_ID));
+        }
+        return transaction.add(web3_js_1.SystemProgram.transfer({
+            fromPubkey: wallet,
+            toPubkey: canonical,
+            lamports: amountLamports,
+        }), (0, spl_token_1.createSyncNativeInstruction)(canonical, spl_token_1.TOKEN_PROGRAM_ID));
+    }
+    /**
+     * Return an unsigned transaction containing one canonical `CloseAccount`.
+     *
+     * The Trading Wallet is the fee payer, close authority, and destination. A later
+     * successful submission transfers the complete account balance to that wallet.
+     */
+    buildUnwrapWsolAllTransaction(wallet) {
+        const canonical = (0, spl_token_1.getAssociatedTokenAddressSync)(spl_token_1.NATIVE_MINT, wallet);
+        return new web3_js_1.Transaction({ feePayer: wallet }).add((0, spl_token_1.createCloseAccountInstruction)(canonical, wallet, wallet, [], spl_token_1.TOKEN_PROGRAM_ID));
+    }
+    /**
+     * Build idempotent creation of the persistent Tokenkeg WSOL ATA.
+     * Tokenkeg is Solana's legacy SPL Token Program; canonical native-mint ATA
+     * derivation is pinned to it rather than Token-2022 across the protocol.
+     */
+    createCanonicalWsolAccount(wallet) {
+        const canonical = (0, spl_token_1.getAssociatedTokenAddressSync)(spl_token_1.NATIVE_MINT, wallet);
+        return (0, spl_token_1.createAssociatedTokenAccountIdempotentInstruction)(wallet, canonical, wallet, spl_token_1.NATIVE_MINT, spl_token_1.TOKEN_PROGRAM_ID);
+    }
+    /** Read canonical-account existence and upfront rent for merge/redeem plans. */
+    async receivePlanContext(wallet, state) {
+        const rpc = new rpc_1.Rpc(this.client);
+        const canonical = (0, spl_token_1.getAssociatedTokenAddressSync)(spl_token_1.NATIVE_MINT, wallet);
+        const canonicalExists = await rpc.canonicalWsolAccountExists(canonical, wallet);
+        const components = state.solComponents();
+        if (components.canonicalWsolLamports > 0n && !canonicalExists) {
+            throw error_1.SdkError.validation("canonical WSOL balance is positive but its account is unavailable");
+        }
+        return {
+            rpc,
+            components,
+            canonicalExists,
+            upfrontRentLamports: canonicalExists
+                ? 0n
+                : await rpc.minimumBalanceForRentExemption(TOKEN_ACCOUNT_SPACE),
+        };
+    }
+    /** Finish merge/redeem planning with live fee authority and component deltas. */
+    async finishReceivePlan(kind, amountLamports, transaction, rpc, components, upfrontRentLamports, createsCanonicalWsolAccount, sponsored) {
+        const feeLamports = await rpc.prepareAndEstimateTransactionFee(transaction);
+        const costs = {
+            feeLamports,
+            upfrontRentLamports,
+            createsCanonicalWsolAccount,
+            sponsored,
+        };
+        const availability = (0, state_1.solBalanceAvailability)(components, costs);
+        const walletCosts = sponsored ? 0n : feeLamports + upfrontRentLamports;
+        return {
+            kind,
+            transaction,
+            costs,
+            availability,
+            expectedDelta: {
+                nativeLamports: -walletCosts,
+                canonicalWsolLamports: amountLamports,
+            },
+        };
+    }
+    /**
+     * Build the sole WSOL-to-native path without closing canonical authority.
+     * The temporary Tokenkeg account is initialized, funded, and closed back to
+     * the wallet before the exact recipient transfer in the same transaction.
+     */
+    buildTemporaryNativeWithdrawal(wallet, recipient, amountLamports, canonicalTransfer, temporaryRent, seed, temporary) {
+        const canonical = (0, spl_token_1.getAssociatedTokenAddressSync)(spl_token_1.NATIVE_MINT, wallet);
+        return new web3_js_1.Transaction({ feePayer: wallet }).add(web3_js_1.SystemProgram.createAccountWithSeed({
+            fromPubkey: wallet,
+            newAccountPubkey: temporary,
+            basePubkey: wallet,
+            seed,
+            lamports: Number(temporaryRent),
+            space: TOKEN_ACCOUNT_SPACE,
+            programId: spl_token_1.TOKEN_PROGRAM_ID,
+        }), (0, spl_token_1.createInitializeAccount3Instruction)(temporary, spl_token_1.NATIVE_MINT, wallet, spl_token_1.TOKEN_PROGRAM_ID), (0, spl_token_1.createTransferInstruction)(canonical, temporary, wallet, canonicalTransfer, [], spl_token_1.TOKEN_PROGRAM_ID), (0, spl_token_1.createCloseAccountInstruction)(temporary, wallet, wallet, [], spl_token_1.TOKEN_PROGRAM_ID), web3_js_1.SystemProgram.transfer({
+            fromPubkey: wallet,
+            toPubkey: recipient,
+            lamports: amountLamports,
+        }));
+    }
     // ── On-chain transaction builders ────────────────────────────────────
     redeemWinningsIx(params, outcomeIndex) {
         return (0, instructions_1.buildRedeemWinningsIx)(params, outcomeIndex, this.client.programId);