@upshiftfinance/sdk 0.0.0-stage → 0.2.0

package/lib/adapters/solana/vault.actions.js

@@ -0,0 +1,657 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeSolanaError = describeSolanaError;
+exports.slippageHint = slippageHint;
+exports.validateExplicitFloor = validateExplicitFloor;
+exports.handleSolanaDeposit = handleSolanaDeposit;
+exports.handleSolanaRedeem = handleSolanaRedeem;
+const anchor_1 = require("@coral-xyz/anchor");
+const web3_js_1 = require("@solana/web3.js");
+const spl_token_1 = require("@solana/spl-token");
+const pricing_1 = require("./pricing");
+const utils_1 = require("./utils");
+const core_1 = require("../../core");
+const token_reads_1 = require("./token-reads");
+const queue_hints_1 = require("./queue-hints");
+/**
+ * User-facing fallback for a throwable that carries no extractable reason.
+ * Surfaces as e.g. `"Solana deposit failed: please try again"` — actionable,
+ * and without telling the user we couldn't classify the failure.
+ */
+const REASONLESS_SOLANA_ERROR = 'please try again';
+/**
+ * Extract a human- and machine-readable reason from a thrown Solana/Anchor
+ * error.
+ *
+ * Anchor's {@link https://github.com/coral-xyz/anchor `ProgramError`} calls
+ * `super()` with no argument, so its `.message` is the empty string by
+ * construction — the real reason lives on `.msg`/`.code` (and `.toString()`).
+ * `AnchorError` puts it on `.error.errorMessage` / `.error.errorCode.number`.
+ * Reading `.message` directly (as this file used to) therefore rendered
+ * `"Solana deposit failed: "` for every recognized on-chain revert — dropping
+ * the numeric code the team needs to tell "Vault is paused" from
+ * "Insufficient amount" from an account-constraint violation.
+ *
+ * When no reason can be extracted, returns an actionable, user-facing fallback
+ * rather than an "unknown error" admission — the raw throwable is still
+ * preserved on the wrapped error's `cause` and in telemetry for diagnosis.
+ */
+function describeSolanaError(e) {
+    if (!(e instanceof Error))
+        return REASONLESS_SOLANA_ERROR;
+    const anchor = e;
+    const reason = anchor.error?.errorMessage ?? anchor.msg ?? '';
+    const code = anchor.error?.errorCode?.number ?? anchor.code;
+    if (reason)
+        return code === undefined ? reason : `${reason} (code ${code})`;
+    // SendTransactionError / generic Error carry a non-empty `.message`.
+    if (e.message)
+        return e.message;
+    // Last resort: a subclass may override `toString()` (never the empty string).
+    const str = e.toString();
+    return str && str !== e.name && str !== `${e.name}: `
+        ? str
+        : REASONLESS_SOLANA_ERROR;
+}
+/** `SlippageExceeded` in `august_vault`'s error enum (ordinal 18 + Anchor's 6000 offset). */
+const SLIPPAGE_EXCEEDED_CODE = 6018;
+/**
+ * A sentence to append when the program rejected the instruction for
+ * slippage, so the caller learns what to do rather than just what happened.
+ * Empty for every other error.
+ *
+ * Not merely a restatement of the program's reason string. Both checked
+ * instructions share error 6018, whose on-chain message is share-worded —
+ * "Received fewer shares than the caller's minimum" — so on a *redeem*, where
+ * the floor is denominated in assets, the program describes the wrong
+ * quantity. This sentence is what makes that case readable. The numeric code
+ * `describeSolanaError` renders alongside it is kept deliberately: it is the
+ * handle support and telemetry group on, and it survives a reword of the
+ * program's message.
+ */
+function slippageHint(e) {
+    const anchor = e;
+    const code = anchor?.error?.errorCode?.number ?? anchor?.code;
+    const name = anchor?.error?.errorCode?.code;
+    return code === SLIPPAGE_EXCEEDED_CODE || name === 'SlippageExceeded'
+        ? ' The share price moved past your slippage tolerance between the quote and execution; retry, or pass a higher `slippageBps`.'
+        : '';
+}
+/** Largest value Anchor's `u64` encoder can represent. */
+const U64_MAX = 18446744073709551615n;
+/**
+ * Validate a caller-supplied slippage floor before it reaches Anchor's `u64`
+ * encoder.
+ *
+ * Anchor serializes a `BN` to `u64` via `toArrayLike`, which writes the
+ * magnitude and drops the sign — a `-1n` floor would reach the program as a
+ * floor of `1`, inverting the caller's intent instead of failing. Values above
+ * `u64` fare no better: they surface as an untyped "byte array longer than
+ * desired length" from inside the encoder, naming nothing the caller passed.
+ * Both are caught here, at the public-API boundary.
+ *
+ * @param value - The caller's `minSharesOut` / `minAssetsOut`, in raw base units.
+ * @param label - Option name, quoted in the error.
+ * @returns `value`, once known to fit an unsigned 64-bit integer.
+ * @throws {@link UpshiftValidationError} when it is not a `bigint` in `0 .. 2^64-1`.
+ */
+function validateExplicitFloor(value, label) {
+    if (typeof value !== 'bigint' || value < 0n || value > U64_MAX) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', `${label} must be a bigint between 0 and ${U64_MAX} raw base units, got ${String(value)}.`);
+    }
+    return value;
+}
+/**
+ * Decide whether a handler can send the slippage-checked instruction, or must
+ * fall back to the plain one.
+ *
+ * `idl` is caller-supplied, and an IDL generated before the program shipped
+ * `deposit_checked` / `redeem_checked` produces a `Program` with no such
+ * method. Until 9.4.0 the handlers sent the plain instructions, so those same
+ * inputs used to work; calling the checked method on them throws a TypeError
+ * before anything is sent (AUGUST-8023). The program still accepts the plain
+ * instructions, with the behaviour a floor of `0` gives the checked ones, so
+ * falling back preserves what those callers had.
+ *
+ * The fallback is refused when the caller asked for protection — a non-zero
+ * explicit floor, or any `slippageBps` — since the plain instruction would
+ * silently drop it. An explicit floor of `0n` is the documented "no floor" and
+ * falls back.
+ *
+ * Probes `program.methods` rather than `idl.instructions`: that is the object
+ * the handler calls, and it already reflects Anchor's camelCase conversion.
+ *
+ * @param program - Anchor program built from the caller's IDL.
+ * @param checkedMethod - `'depositChecked'` or `'redeemChecked'`.
+ * @param floor - The caller's explicit `minSharesOut` / `minAssetsOut`, if any.
+ * @param slippageBps - The caller's tolerance, if any.
+ * @param handler - Handler name, for the log line and the error.
+ * @returns `true` to send the checked instruction, `false` for the plain one.
+ * @throws {@link UpshiftValidationError} when the IDL lacks the checked
+ *   instruction and the caller asked for a floor.
+ */
+function sendsCheckedInstruction({ program, checkedMethod, floor, slippageBps, handler, }) {
+    const methods = program.methods;
+    if (typeof methods[checkedMethod] === 'function')
+        return true;
+    const instruction = checkedMethod === 'depositChecked' ? 'deposit_checked' : 'redeem_checked';
+    const floorOption = checkedMethod === 'depositChecked' ? 'minSharesOut' : 'minAssetsOut';
+    if ((floor !== undefined && floor !== 0n) || slippageBps !== undefined) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', `${handler}: the supplied IDL does not declare \`${instruction}\`, so ` +
+            `the requested ${floorOption} / slippageBps cannot be enforced. Pass ` +
+            "the SDK's bundled IDL (`Solana.constants.vaultIdl`), or omit both " +
+            'options to send the unguarded instruction.');
+    }
+    core_1.Logger.log.warn(handler, `Supplied IDL does not declare \`${instruction}\`; sending the plain ` +
+        "instruction without a slippage floor. Pass the SDK's bundled IDL to " +
+        'enable slippage protection.');
+    return false;
+}
+/**
+ * Resolve the two token accounts a vault instruction needs, concurrently.
+ *
+ * The lookups are independent, so running them in sequence doubles the
+ * round-trip latency on the hot path for no benefit — both results are needed
+ * before anything is submitted either way.
+ *
+ * Rejections are surfaced in argument order rather than in whichever order the
+ * RPC happened to fail, so the error a user sees does not depend on network
+ * timing. `Promise.all` would reject with whichever call failed *first*, which
+ * on a malformed RPC response (both lookups throwing) would name a different
+ * account run to run.
+ *
+ * @param mints - `[first, second]`; the returned tuple matches this order.
+ */
+async function resolveUserTokenAccountPair({ connection, owner, mints, }) {
+    const settled = await Promise.allSettled(mints.map((mint) => (0, token_reads_1.resolveUserTokenAccount)({ connection, owner, mint })));
+    const resolved = settled.map((outcome) => {
+        if (outcome.status === 'rejected')
+            throw outcome.reason;
+        return outcome.value;
+    });
+    return [resolved[0], resolved[1]];
+}
+/**
+ * Deposit funds into a Solana Upshift vault and mint share tokens.
+ *
+ * @param depositAmount  `bigint` is treated as raw on-chain units (preferred
+ *   — no JS-float round-trip). `number` is treated as a UI amount and
+ *   scaled by the deposit mint's decimals via {@link uiAmountToRawBn}.
+ * @throws UpshiftValidationError on missing wallet/programId or invalid amount,
+ *   or when the wallet's deposit-mint balance is below `depositAmount`.
+ * @throws UpshiftSDKError when a candidate token account's balance cannot be
+ *   read, or wrapping any downstream failure (`cause` preserved).
+ * @throws UpshiftTransactionError (`TRANSACTION_UNCONFIRMED`) when the
+ *   transaction was sent but its outcome could not be established; check
+ *   `signature` before resubmitting.
+ * @remarks **Side effects.** Submits exactly one transaction, signed by the
+ *   provider's wallet. When the wallet has no share account, that transaction
+ *   also creates one, and `publicKey` pays its rent — roughly 0.00204 SOL,
+ *   non-refundable while the account stays open — on top of the network fee.
+ *   Callers should ensure the wallet holds enough SOL for both before
+ *   prompting the user to sign.
+ * @remarks Sends `deposit_checked`, not `deposit`. Unless `options.minSharesOut`
+ *   is given, the vault state and share mint are read to quote the shares this
+ *   deposit should mint, and that quote lowered by `options.slippageBps`
+ *   (default {@link DEFAULT_SLIPPAGE_BPS}) is passed as the floor; the program
+ *   reverts with `SlippageExceeded` if execution would mint fewer. An `idl`
+ *   that predates `deposit_checked` gets the plain `deposit` with no floor,
+ *   unless `options` asks for one — then it throws {@link UpshiftValidationError}.
+ */
+async function handleSolanaDeposit({ provider, connection, vaultProgramId, vaultAddress, depositAmount, publicKey, idl, options = {}, }) {
+    try {
+        if (!publicKey)
+            throw new core_1.UpshiftValidationError('INVALID_INPUT', 'handleSolanaDeposit: wallet not connected');
+        if (depositAmount === undefined ||
+            depositAmount === null ||
+            (typeof depositAmount === 'bigint' && depositAmount <= 0n) ||
+            (typeof depositAmount === 'number' && !(depositAmount > 0)))
+            throw new core_1.UpshiftValidationError('INVALID_INPUT', 'handleSolanaDeposit: depositAmount is required and must be > 0');
+        if (!vaultProgramId)
+            throw new core_1.UpshiftValidationError('INVALID_INPUT', 'handleSolanaDeposit: vaultProgramId is required');
+        // Before any RPC: an unusable floor should cost the caller nothing.
+        if (options.minSharesOut !== undefined)
+            validateExplicitFloor(options.minSharesOut, 'minSharesOut');
+        const _vaultProgramId = new web3_js_1.PublicKey(vaultProgramId);
+        const program = utils_1.SolanaUtils.getProgram({
+            provider,
+            idl,
+            programId: _vaultProgramId.toBase58(),
+        });
+        // Also before any RPC: a floor the caller's IDL cannot enforce is refused
+        // on the spot rather than after the mint and token-account reads.
+        const checked = sendsCheckedInstruction({
+            program,
+            checkedMethod: 'depositChecked',
+            floor: options.minSharesOut,
+            slippageBps: options.slippageBps,
+            handler: 'handleSolanaDeposit',
+        });
+        // `getVaultMints` throws a typed `UpshiftSDKError` when the state cannot be
+        // read, so both mints are present here.
+        const { depositMint, shareMint, vaultVersion } = await utils_1.SolanaUtils.getVaultMints({
+            connection,
+            vaultProgramId,
+            vaultAddress,
+            idl,
+        });
+        const _publicKey = new web3_js_1.PublicKey(publicKey);
+        const _depositMint = new web3_js_1.PublicKey(depositMint);
+        core_1.Logger.log.info('handleSolanaDeposit', 'Program', program);
+        const vaultStatePda = vaultAddress
+            ? new web3_js_1.PublicKey(vaultAddress)
+            : utils_1.SolanaUtils.deriveVaultStatePda(_vaultProgramId);
+        core_1.Logger.log.info('handleSolanaDeposit', 'Vault state PDA', vaultStatePda.toBase58());
+        const vaultTokenAtaPda = utils_1.SolanaUtils.deriveVaultTokenAtaPda(_vaultProgramId, _depositMint, vaultVersion);
+        core_1.Logger.log.info('handleSolanaDeposit', 'Vault token ATA PDA', vaultTokenAtaPda.toBase58());
+        // Use on-chain share mint from vault state instead of deriving a PDA,
+        // since PDA derivation assumes one share mint per program (single-vault only).
+        const shareMintAddr = new web3_js_1.PublicKey(shareMint);
+        core_1.Logger.log.info('handleSolanaDeposit', 'Share mint', shareMintAddr.toBase58());
+        // Get mint info to handle decimals
+        const mintInfo = await connection.getParsedAccountInfo(_depositMint);
+        if (!mintInfo.value) {
+            throw new core_1.UpshiftSDKError('UNKNOWN', `Could not fetch deposit mint info: account ${_depositMint.toBase58()} not found on the connected RPC`, { context: { depositMint: _depositMint.toBase58() } });
+        }
+        const { decimals } = mintInfo.value.data.parsed.info;
+        let depositAmountRaw;
+        if (typeof depositAmount === 'bigint') {
+            depositAmountRaw = new anchor_1.BN(depositAmount.toString());
+        }
+        else {
+            if (isNaN(depositAmount)) {
+                throw new core_1.UpshiftValidationError('INVALID_INPUT', 'Please enter a valid number for the deposit amount');
+            }
+            if (depositAmount <= 0) {
+                throw new core_1.UpshiftValidationError('INVALID_INPUT', 'Deposit amount must be greater than 0');
+            }
+            depositAmountRaw = (0, utils_1.uiAmountToRawBn)(depositAmount, decimals);
+        }
+        // Re-check *after* scaling. The guard above tests the caller's number, but
+        // a positive UI amount below one raw unit (1e-7 into a 6-decimal mint)
+        // truncates to zero here. Zero would then pass the balance gate below
+        // (`0n < 0n` is false) and submit a no-op transfer — from an account that
+        // may not even exist, since a zero balance is also what an absent account
+        // reports.
+        if (depositAmountRaw.lten(0)) {
+            throw new core_1.UpshiftValidationError('INVALID_INPUT', `Deposit amount is too small: ${depositAmount} is below one raw unit ` +
+                `of a ${decimals}-decimal mint.`);
+        }
+        // Match whatever this connection *reads* at. A `Connection` built without
+        // a commitment omits the parameter, so its reads take the RPC's default —
+        // `finalized`. Confirming writes at `confirmed` there would put reads
+        // behind writes again, which is the mismatch this whole change removes.
+        // `SolanaAdapter` always sets one explicitly, so this fallback only
+        // applies to callers reaching these handlers directly via `Solana.actions`.
+        const txCommitment = connection.commitment ?? 'finalized';
+        // `depositAccount` funds the transfer; `shareAccount` receives the minted
+        // shares. Independent lookups, so they run concurrently — but the guards
+        // below stay in a fixed order so the first problem a user hits is always
+        // reported the same way.
+        const [depositAccount, shareAccount] = await resolveUserTokenAccountPair({
+            connection,
+            owner: _publicKey,
+            mints: [_depositMint, shareMintAddr],
+        });
+        // Gate on the balance, not on whether an account exists: an empty leftover
+        // account is a real state, and letting it through only trades this error
+        // for an insufficient-funds revert the user pays a signature to discover.
+        // The balance is already in hand from the lookup, so this costs no extra
+        // RPC.
+        if (depositAccount.frozen) {
+            throw new core_1.UpshiftValidationError('INVALID_INPUT', 'Your token account for the deposit mint is frozen by the token issuer, ' +
+                'so the deposit cannot be transferred out of it.');
+        }
+        if (depositAccount.balance < BigInt(depositAmountRaw.toString())) {
+            throw new core_1.UpshiftValidationError('INVALID_INPUT', `Insufficient balance to deposit: this wallet holds ${depositAccount.balance} ` +
+                `raw units of the deposit mint, and the deposit requires ${depositAmountRaw.toString()}.`);
+        }
+        const senderTokenAccount = depositAccount.address;
+        // A missing share account is routine — every first-time depositor starts
+        // here, as does anyone whose account was closed after redeeming their full
+        // balance — so it is created inline rather than rejecting the deposit.
+        // Minting into a *frozen* one fails just as transferring out of one does,
+        // so this destination needs the same guard as the funding account above.
+        if (shareAccount.frozen) {
+            throw new core_1.UpshiftValidationError('INVALID_INPUT', 'Your share account is frozen by the token issuer, so it cannot ' +
+                'receive the shares this deposit would mint.');
+        }
+        const senderShareAccount = shareAccount.address;
+        const preInstructions = shareAccount.createIx
+            ? [shareAccount.createIx]
+            : [];
+        core_1.Logger.log.info('handleSolanaDeposit', 'Sender token account', senderTokenAccount.toBase58());
+        core_1.Logger.log.info('handleSolanaDeposit', shareAccount.createIx
+            ? 'Sender share account (created in this tx)'
+            : 'Sender share account (existing)', senderShareAccount.toBase58());
+        core_1.Logger.log.info('handleSolanaDeposit', '\n\nDeposit TX Params:\n');
+        core_1.Logger.log.info('handleSolanaDeposit', 'Program', depositAmountRaw);
+        core_1.Logger.log.info('handleSolanaDeposit', 'Vault state PDA', vaultStatePda.toBase58());
+        core_1.Logger.log.info('handleSolanaDeposit', 'Vault token ATA PDA', vaultTokenAtaPda.toBase58());
+        core_1.Logger.log.info('handleSolanaDeposit', 'Share mint', shareMintAddr.toBase58());
+        core_1.Logger.log.info('handleSolanaDeposit', 'Deposit mint', _depositMint?.toBase58());
+        core_1.Logger.log.info('handleSolanaDeposit', 'Signer', _publicKey.toBase58());
+        let minSharesOut;
+        if (!checked) {
+            // The plain instruction takes no floor, so there is nothing to quote.
+        }
+        else if (options.minSharesOut !== undefined) {
+            minSharesOut = options.minSharesOut;
+        }
+        else {
+            // One read the unguarded `deposit` never needed: the vault state (assets
+            // and offset) and the share mint (supply) in a single snapshot, since
+            // pricing against a mismatched pair is worse than not quoting at all —
+            // see `readPricingSnapshot`. A caller already holding a quote can pass
+            // `minSharesOut` and skip it.
+            const { vaultStateData, supply } = await (0, token_reads_1.readPricingSnapshot)({
+                connection,
+                program,
+                vaultStatePda,
+                shareMintAddr,
+            });
+            minSharesOut = (0, pricing_1.quoteDepositFloor)({
+                supply,
+                totalAssets: (0, pricing_1.totalAssetsOf)(vaultStateData),
+                amount: BigInt(depositAmountRaw.toString()),
+                offset: (0, pricing_1.resolveShareOffset)(vaultStateData.shareOffset),
+                slippageBps: options.slippageBps ?? pricing_1.DEFAULT_SLIPPAGE_BPS,
+            });
+        }
+        core_1.Logger.log.info('handleSolanaDeposit', 'Min shares out (raw)', minSharesOut?.toString() ?? 'none (plain deposit)');
+        const methods = program.methods;
+        const tx = await (minSharesOut === undefined
+            ? methods.deposit(depositAmountRaw)
+            : methods.depositChecked(depositAmountRaw, new anchor_1.BN(minSharesOut.toString())))
+            .accounts({
+            vaultState: vaultStatePda,
+            vaultTokenAta: vaultTokenAtaPda,
+            senderTokenAccount,
+            senderShareAccount,
+            shareMint: shareMintAddr,
+            depositMint: _depositMint,
+            signer: _publicKey,
+            tokenProgram: spl_token_1.TOKEN_PROGRAM_ID,
+        })
+            .preInstructions(preInstructions)
+            // `.rpc()` builds, signs, submits and confirms in one step. The extra
+            // `getLatestBlockhash` + `confirmTransaction` this module used to run
+            // afterwards re-confirmed an already-confirmed signature against a
+            // blockhash the transaction never carried.
+            //
+            // Commitment is taken from the same `Connection` every read in this
+            // adapter uses, so a caller who asks for 'finalized' gets it on both
+            // sides rather than finalized reads racing confirmed writes.
+            .rpc({
+            skipPreflight: false,
+            preflightCommitment: txCommitment,
+            commitment: txCommitment,
+        });
+        core_1.Logger.log.info('handleSolanaDeposit', 'Deposit successful:', tx);
+        return tx;
+    }
+    catch (e) {
+        if (e instanceof core_1.UpshiftSDKError)
+            throw e;
+        const depositAmountForLog = typeof depositAmount === 'bigint'
+            ? depositAmount.toString()
+            : depositAmount;
+        core_1.Logger.log.error('handleSolanaDeposit', e, {
+            vaultProgramId: String(vaultProgramId),
+            vaultAddress: vaultAddress ? String(vaultAddress) : undefined,
+            depositAmount: depositAmountForLog,
+        });
+        throw new core_1.UpshiftSDKError('UNKNOWN', `Solana deposit failed: ${describeSolanaError(e)}${slippageHint(e)}`, {
+            cause: e,
+            context: {
+                vaultProgramId: String(vaultProgramId),
+                vaultAddress: vaultAddress ? String(vaultAddress) : undefined,
+                depositAmount: depositAmountForLog,
+            },
+        });
+    }
+}
+/**
+ * Redeem vault shares back into the underlying mint on a Solana Upshift vault.
+ *
+ * @param redeemShares  `bigint` is treated as raw share-token units;
+ *   `number` is treated as a UI amount.
+ * @remarks Sends `redeem_checked`, not `redeem`. Unless `options.minAssetsOut`
+ *   is given, the payout is quoted from the vault state and share supply the
+ *   handler already reads, **net of the withdrawal fee**, and that quote
+ *   lowered by `options.slippageBps` (default {@link DEFAULT_SLIPPAGE_BPS}) is
+ *   passed as the floor; the program reverts with `SlippageExceeded` below it.
+ *   An `idl` that predates `redeem_checked` gets the plain `redeem` with no
+ *   floor, unless `options` asks for one — then it throws
+ *   {@link UpshiftValidationError}.
+ * @throws UpshiftValidationError on missing wallet/programId or invalid amount,
+ *   or when the wallet holds fewer shares than `redeemShares`.
+ * @throws UpshiftSDKError when a candidate token account's balance cannot be
+ *   read, or wrapping any downstream failure (`cause` preserved).
+ * @throws UpshiftTransactionError (`TRANSACTION_UNCONFIRMED`) when the
+ *   transaction was sent but its outcome could not be established; check
+ *   `signature` before resubmitting.
+ * @remarks **Side effects.** Submits exactly one transaction, signed by the
+ *   provider's wallet. That transaction also creates the payout account when
+ *   the wallet has none, and the vault's fee-recipient account when *it* has
+ *   none — `publicKey` pays rent for both, roughly 0.00204 SOL each and
+ *   non-refundable, on top of the network fee. Callers should ensure the
+ *   wallet holds enough SOL for all of it before prompting the user to sign.
+ */
+async function handleSolanaRedeem({ provider, connection, vaultProgramId, vaultAddress, publicKey, redeemShares, idl, options = {}, }) {
+    try {
+        if (!publicKey)
+            throw new core_1.UpshiftValidationError('INVALID_INPUT', 'handleSolanaRedeem: wallet not connected');
+        if (redeemShares === undefined ||
+            redeemShares === null ||
+            (typeof redeemShares === 'bigint' && redeemShares <= 0n) ||
+            (typeof redeemShares === 'number' && !(redeemShares > 0)))
+            throw new core_1.UpshiftValidationError('INVALID_INPUT', 'handleSolanaRedeem: redeemShares is required and must be > 0');
+        if (!vaultProgramId)
+            throw new core_1.UpshiftValidationError('INVALID_INPUT', 'handleSolanaRedeem: vaultProgramId is required');
+        // Before any RPC: an unusable floor should cost the caller nothing.
+        if (options.minAssetsOut !== undefined)
+            validateExplicitFloor(options.minAssetsOut, 'minAssetsOut');
+        const _vaultProgramId = new web3_js_1.PublicKey(vaultProgramId);
+        const program = utils_1.SolanaUtils.getProgram({
+            provider,
+            idl,
+            programId: _vaultProgramId.toBase58(),
+        });
+        // See `handleSolanaDeposit`: refused before any RPC.
+        const checked = sendsCheckedInstruction({
+            program,
+            checkedMethod: 'redeemChecked',
+            floor: options.minAssetsOut,
+            slippageBps: options.slippageBps,
+            handler: 'handleSolanaRedeem',
+        });
+        // `getVaultMints` throws a typed `UpshiftSDKError` when the state cannot be
+        // read, so both mints are present here.
+        const { depositMint, shareMint, vaultVersion } = await utils_1.SolanaUtils.getVaultMints({
+            connection,
+            vaultProgramId,
+            vaultAddress,
+            idl,
+        });
+        const _depositMint = new web3_js_1.PublicKey(depositMint);
+        const _publicKey = new web3_js_1.PublicKey(publicKey);
+        const vaultStatePda = vaultAddress
+            ? new web3_js_1.PublicKey(vaultAddress)
+            : utils_1.SolanaUtils.deriveVaultStatePda(_vaultProgramId);
+        const vaultTokenAtaPda = utils_1.SolanaUtils.deriveVaultTokenAtaPda(_vaultProgramId, _depositMint, vaultVersion);
+        // Use on-chain share mint from vault state instead of deriving a PDA,
+        // since PDA derivation assumes one share mint per program (single-vault only).
+        const shareMintAddr = new web3_js_1.PublicKey(shareMint);
+        // Share-mint decimals and supply plus the vault state, from one slot. This
+        // replaces a `getParsedAccountInfo` here and a `vaultState.fetch` further
+        // down — one round trip rather than two, and supply and assets can no
+        // longer be read either side of someone else's deposit.
+        const { vaultStateData, supply: shareSupply, shareDecimals, } = await (0, token_reads_1.readPricingSnapshot)({
+            connection,
+            program,
+            vaultStatePda,
+            shareMintAddr,
+        });
+        // A vault with a queue attached accepts a redeem from the queue alone, so
+        // a holder's direct redeem can only revert with `WithdrawalQueueRequired`.
+        // Say so before the wallet is asked to sign.
+        const gate = vaultStateData.withdrawalQueueAuthority;
+        if (gate && !new web3_js_1.PublicKey(gate).equals(web3_js_1.PublicKey.default)) {
+            throw new core_1.UpshiftValidationError('INVALID_INPUT', 'This vault redeems through its withdrawal queue: request with ' +
+                '`vaultRequestRedeem`, then claim the request with `vaultRedeem` and ' +
+                '`options.request` once its cooldown has run.');
+        }
+        let redeemSharesRaw;
+        if (typeof redeemShares === 'bigint') {
+            redeemSharesRaw = new anchor_1.BN(redeemShares.toString());
+        }
+        else {
+            if (isNaN(redeemShares)) {
+                throw new core_1.UpshiftValidationError('INVALID_INPUT', 'Please enter a valid number for the shares to redeem');
+            }
+            if (redeemShares <= 0) {
+                throw new core_1.UpshiftValidationError('INVALID_INPUT', 'Shares to redeem must be greater than 0');
+            }
+            redeemSharesRaw = (0, utils_1.uiAmountToRawBn)(redeemShares, shareDecimals);
+        }
+        // See `handleSolanaDeposit` — a positive UI amount can truncate to zero,
+        // which would pass the share-balance gate below and burn nothing.
+        if (redeemSharesRaw.lten(0)) {
+            throw new core_1.UpshiftValidationError('INVALID_INPUT', `Redemption amount is too small: ${redeemShares} is below one raw unit ` +
+                `of a ${shareDecimals}-decimal share mint.`);
+        }
+        // Match whatever this connection *reads* at. A `Connection` built without
+        // a commitment omits the parameter, so its reads take the RPC's default —
+        // `finalized`. Confirming writes at `confirmed` there would put reads
+        // behind writes again, which is the mismatch this whole change removes.
+        // `SolanaAdapter` always sets one explicitly, so this fallback only
+        // applies to callers reaching these handlers directly via `Solana.actions`.
+        const txCommitment = connection.commitment ?? 'finalized';
+        // `shareAccount` is burned from; `payoutAccount` receives the underlying.
+        // Independent lookups, so they run concurrently — guards stay ordered.
+        const [shareAccount, payoutAccount] = await resolveUserTokenAccountPair({
+            connection,
+            owner: _publicKey,
+            mints: [shareMintAddr, _depositMint],
+        });
+        // Gated on balance for the same reason as the deposit's funding account.
+        if (shareAccount.frozen) {
+            throw new core_1.UpshiftValidationError('INVALID_INPUT', 'Your share account is frozen by the token issuer, so these shares ' +
+                'cannot be redeemed.');
+        }
+        if (shareAccount.balance < BigInt(redeemSharesRaw.toString())) {
+            throw new core_1.UpshiftValidationError('INVALID_INPUT', `Insufficient shares to redeem: this wallet holds ${shareAccount.balance} ` +
+                `raw share units, and the redemption requires ${redeemSharesRaw.toString()}.`);
+        }
+        const senderShareAccount = shareAccount.address;
+        // Redeeming is precisely how a holder first receives the deposit mint, so
+        // requiring the payout account to pre-exist (as this module used to) left
+        // shares unredeemable through this SDK for everyone who acquired them any
+        // way other than depositing from this same wallet — a transfer, an
+        // airdrop, a market buy — as well as any depositor who later closed their
+        // deposit-mint account. A frozen account cannot receive either, so the
+        // payout would revert.
+        if (payoutAccount.frozen) {
+            throw new core_1.UpshiftValidationError('INVALID_INPUT', 'Your token account for the deposit mint is frozen by the token issuer, ' +
+                'so it cannot receive the redemption proceeds.');
+        }
+        const senderTokenAccount = payoutAccount.address;
+        // No extra reads here: the share mint (supply) and vault state (assets,
+        // offset, fee, fee recipient) came from the snapshot above.
+        let minAssetsOut;
+        if (!checked) {
+            // The plain instruction takes no floor, so there is nothing to quote.
+        }
+        else if (options.minAssetsOut !== undefined) {
+            minAssetsOut = options.minAssetsOut;
+        }
+        else {
+            minAssetsOut = (0, pricing_1.quoteRedeemFloor)({
+                supply: shareSupply,
+                totalAssets: (0, pricing_1.totalAssetsOf)(vaultStateData),
+                shares: BigInt(redeemSharesRaw.toString()),
+                offset: (0, pricing_1.resolveShareOffset)(vaultStateData.shareOffset),
+                feePpm: (0, pricing_1.toBigInt)(vaultStateData.withdrawalFee, 'withdrawalFee'),
+                slippageBps: options.slippageBps ?? pricing_1.DEFAULT_SLIPPAGE_BPS,
+            });
+        }
+        // The fee recipient's token account. Off-curve allowed (as in the queue
+        // claim path): a multisig vault or program PDA can be the fee recipient,
+        // and the default `allowOwnerOffCurve: false` throws
+        // `TokenOwnerOffCurveError` for one, blocking every direct redeem.
+        const feeRecipientTokenAccount = (0, spl_token_1.getAssociatedTokenAddressSync)(_depositMint, vaultStateData.feeRecipient, // This is the actual fee recipient from vault state
+        true);
+        // Every account this handler might have to create is created in the same
+        // transaction that uses it. The fee recipient's ATA is created
+        // unconditionally: the idempotent instruction is a no-op when the account
+        // already exists (costing the user nothing), which buys us one fewer RPC
+        // round trip and removes the read-then-create window entirely. The user
+        // pays the rent when it is genuinely absent, as before.
+        const preInstructions = [
+            (0, spl_token_1.createAssociatedTokenAccountIdempotentInstruction)(_publicKey, // payer (user pays for the account creation)
+            feeRecipientTokenAccount, // associated token account
+            vaultStateData.feeRecipient, // owner (the actual fee recipient)
+            _depositMint),
+        ];
+        if (payoutAccount.createIx)
+            preInstructions.push(payoutAccount.createIx);
+        core_1.Logger.log.info('handleSolanaRedeem', '\n\nRedeem TX Params:\n');
+        core_1.Logger.log.info('handleSolanaRedeem', 'Redeem shares (UI):', redeemShares);
+        core_1.Logger.log.info('handleSolanaRedeem', 'Redeem shares (raw):', redeemSharesRaw);
+        core_1.Logger.log.info('handleSolanaRedeem', 'Share decimals:', shareDecimals);
+        core_1.Logger.log.info('handleSolanaRedeem', 'Vault state PDA:', vaultStatePda.toBase58());
+        core_1.Logger.log.info('handleSolanaRedeem', 'Vault token ATA PDA:', vaultTokenAtaPda.toBase58());
+        core_1.Logger.log.info('handleSolanaRedeem', 'Sender token account:', senderTokenAccount?.toBase58());
+        core_1.Logger.log.info('handleSolanaRedeem', 'Sender share account:', senderShareAccount?.toBase58());
+        core_1.Logger.log.info('handleSolanaRedeem', 'Fee recipient account:', feeRecipientTokenAccount.toBase58());
+        core_1.Logger.log.info('handleSolanaRedeem', 'Share mint:', shareMintAddr.toBase58());
+        core_1.Logger.log.info('handleSolanaRedeem', 'Deposit mint:', _depositMint?.toBase58());
+        core_1.Logger.log.info('handleSolanaRedeem', 'Signer:', _publicKey.toBase58());
+        core_1.Logger.log.info('handleSolanaRedeem', 'Min assets out, net of fee (raw):', minAssetsOut?.toString() ?? 'none (plain redeem)');
+        const methods = program.methods;
+        const tx = await (minAssetsOut === undefined
+            ? methods.redeem(redeemSharesRaw)
+            : methods.redeemChecked(redeemSharesRaw, new anchor_1.BN(minAssetsOut.toString())))
+            .accounts({
+            vaultState: vaultStatePda,
+            vaultDepositAta: vaultTokenAtaPda,
+            senderTokenAccount,
+            senderShareAccount,
+            feeRecipientAccount: feeRecipientTokenAccount, // The actual fee recipient's token account
+            shareMint: shareMintAddr,
+            depositMint: _depositMint,
+            signer: _publicKey,
+            tokenProgram: spl_token_1.TOKEN_PROGRAM_ID,
+        })
+            .preInstructions(preInstructions)
+            // See `handleSolanaDeposit` for why `.rpc()` owns the confirmation and
+            // why the commitment comes from the connection.
+            .rpc({
+            skipPreflight: false,
+            preflightCommitment: txCommitment,
+            commitment: txCommitment,
+        });
+        core_1.Logger.log.info('handleSolanaRedeem', 'Redeem successful:', tx);
+        return tx;
+    }
+    catch (e) {
+        if (e instanceof core_1.UpshiftSDKError)
+            throw e;
+        const redeemSharesForLog = typeof redeemShares === 'bigint' ? redeemShares.toString() : redeemShares;
+        core_1.Logger.log.error('handleSolanaRedeem', e, {
+            vaultProgramId: String(vaultProgramId),
+            vaultAddress: vaultAddress ? String(vaultAddress) : undefined,
+            redeemShares: redeemSharesForLog,
+        });
+        throw new core_1.UpshiftSDKError('UNKNOWN', `Solana redeem failed: ${describeSolanaError(e)}${slippageHint(e)}${(0, queue_hints_1.redeemQueueHint)(e)}`, {
+            cause: e,
+            context: {
+                vaultProgramId: String(vaultProgramId),
+                vaultAddress: vaultAddress ? String(vaultAddress) : undefined,
+                redeemShares: redeemSharesForLog,
+            },
+        });
+    }
+}
+//# sourceMappingURL=vault.actions.js.map