@augustdigital/sdk 9.11.0 → 9.12.0

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

@@ -0,0 +1,488 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.queueHint = queueHint;
+exports.deriveWithdrawalRequestPda = deriveWithdrawalRequestPda;
+exports.handleSolanaRequestRedeem = handleSolanaRequestRedeem;
+exports.handleSolanaClaimRedeem = handleSolanaClaimRedeem;
+exports.handleSolanaCancelRedeemRequest = handleSolanaCancelRedeemRequest;
+/**
+ * Write paths for the august_withdrawal_queue program: request a withdrawal,
+ * claim (finalize) a ready one, cancel a pending one.
+ *
+ * Built like the vault's deposit and redeem handlers (`vault.actions.ts`):
+ * every check the SDK can make runs before the wallet is asked to sign, every
+ * account the transaction needs is created inside it with an idempotent
+ * instruction, and failures surface as `AugustValidationError` (bad input or
+ * state the caller can fix) or `AugustSDKError` (the transaction failed, with
+ * the program's reason and the numeric code).
+ */
+const anchor_1 = require("@coral-xyz/anchor");
+const spl_token_1 = require("@solana/spl-token");
+const web3_js_1 = require("@solana/web3.js");
+const core_1 = require("../../core");
+const vault_idl_1 = require("./idl/vault-idl");
+const withdrawal_queue_idl_1 = require("./idl/withdrawal-queue-idl");
+const pricing_1 = require("./pricing");
+const utils_1 = require("./utils");
+const token_reads_1 = require("./token-reads");
+const vault_actions_1 = require("./vault.actions");
+const withdrawal_queue_1 = require("./withdrawal-queue");
+const WITHDRAWAL_REQUEST_SEED = 'withdrawal_request';
+/** Largest request id the program's `u64` can hold. */
+const U64_MAX = 18446744073709551615n;
+/**
+ * What to do next, for the queue errors a caller can act on. Matched by the
+ * error's name, not its number: both programs number their errors from 6000,
+ * so a bare code is ambiguous between them.
+ */
+const QUEUE_HINTS = {
+    WithdrawalQueueRequired: ' This vault redeems through its withdrawal queue: request with `vaultRequestRedeem`, then claim with `vaultRedeem` and `options.request`.',
+    CooldownNotElapsed: ' The request is still in its cooldown; claim it once its eligibility time has passed.',
+    RequestExpired: ' The request is past its fulfillment window and can no longer be claimed; cancel it to get the shares back.',
+    FinalizerNotAllowed: ' Only the holder or the finalizer the request names may claim it.',
+    StaleRequestSequence: ' The request changed since it was read (it was claimed or cancelled, and possibly recreated); read it again.',
+    QueueNotActiveOnVault: ' The vault is no longer attached to this queue, so it takes no new requests; redeem directly instead.',
+    NotRequestOwner: ' Only the holder who made the request may cancel it.',
+    PayoutBelowFloor: ' The shares are worth less than the floor set when the request was made; claim once the price recovers, or cancel and request again with a lower `minAssetsOut` or higher `slippageBps`.',
+    // Raised by the vault inside the claim's CPI; only claims reach this map.
+    NotEnoughLiquidity: " The vault's liquid reserve cannot cover this payout yet; the request stays pending, so claim it again later.",
+};
+/** The sentence to append for a queue error the caller can act on, else empty. */
+function queueHint(e) {
+    const name = e
+        ?.error?.errorCode?.code;
+    return (name && QUEUE_HINTS[name]) || '';
+}
+/** A queue program client that signs through `provider`'s wallet. */
+function queueProgram(provider, queueProgramId) {
+    return new anchor_1.Program({ ...withdrawal_queue_idl_1.withdrawalQueueIdl, address: queueProgramId.toBase58() }, provider);
+}
+/**
+ * The queue's instruction builders, typed by what these handlers call. The IDL
+ * is a plain object here, not Anchor's generated type, so `program.methods` is
+ * untyped without this.
+ */
+function queueMethods(program) {
+    return program.methods;
+}
+/** A vault program client, used only for its account coder. */
+function vaultCoder(provider) {
+    return new anchor_1.Program(vault_idl_1.vaultIdl, provider).coder.accounts;
+}
+/** The request PDA: `["withdrawal_request", queue, owner, request_id as u64 LE]`. */
+function deriveWithdrawalRequestPda(queue, owner, requestId, queueProgramId) {
+    return web3_js_1.PublicKey.findProgramAddressSync([
+        Buffer.from(WITHDRAWAL_REQUEST_SEED),
+        queue.toBuffer(),
+        owner.toBuffer(),
+        new anchor_1.BN(requestId.toString()).toArrayLike(Buffer, 'le', 8),
+    ], queueProgramId)[0];
+}
+/**
+ * A random `u64` request id. `crypto.getRandomValues` is available in every
+ * browser and in Node 19+, the SDK's floor being 22. A collision needs another
+ * pending request of the same holder with the same id: about 2^-64 per pair,
+ * and it would fail cleanly, the request account already existing.
+ */
+function randomRequestId() {
+    const bytes = new Uint8Array(8);
+    globalThis.crypto.getRandomValues(bytes);
+    return bytes.reduce((id, byte) => (id << 8n) | BigInt(byte), 0n);
+}
+/** The commitment reads use, so writes confirm where reads will see them. */
+function commitmentOf(connection) {
+    return connection.commitment ?? 'finalized';
+}
+/** Decode `info` as `name` with `coder`, or throw naming the account. */
+function decodeOrThrow(coder, name, address, info, missing) {
+    if (!info)
+        throw new core_1.AugustValidationError('INVALID_INPUT', missing);
+    try {
+        return coder.decode(name, info.data);
+    }
+    catch (e) {
+        throw new core_1.AugustValidationError('INVALID_INPUT', `Account ${address.toBase58()} is not a ${name} account.`, { cause: e });
+    }
+}
+/** Wrap a non-SDK failure the way the vault handlers do, keeping `cause`. */
+function wrapFailure(operation, e, context) {
+    if (e instanceof core_1.AugustSDKError)
+        throw e;
+    core_1.Logger.log.error(operation, e, context);
+    throw new core_1.AugustSDKError('UNKNOWN', `Solana ${operation} failed: ${(0, vault_actions_1.describeSolanaError)(e)}${queueHint(e)}`, { cause: e, context });
+}
+/**
+ * Escrow shares in a withdrawal request on a vault with a queue attached.
+ *
+ * Reads the vault state and queue in one call, checks the gate points at the
+ * queue, and submits `request_withdrawal` from the holder's share account. The
+ * recipient's deposit-token account is created in the same transaction when it
+ * has none. Unless `minAssetsOut` is given, the request's floor is the current
+ * net quote lowered by `slippageBps`, the floor `vaultRedeem` would use.
+ *
+ * RPC: one `getMultipleAccountsInfo` (vault state and queue), one
+ * `getAccountInfo` for the share mint (decimals for a UI `amount`, supply for
+ * the default floor) unless `amount` is raw and `minAssetsOut` is given, one
+ * `getParsedTokenAccountsByOwner` for the share account, and one more read for
+ * the payout account (the holder's, or another recipient's ATA, which may be
+ * off-curve), then the send.
+ *
+ * @returns The signature, the new request's address and its id.
+ * @throws AugustValidationError for bad input, a vault without an attached
+ *   queue, a frozen account or too few shares, all before signing.
+ * @throws AugustSDKError when the transaction fails.
+ */
+async function handleSolanaRequestRedeem({ provider, connection, queueProgramId, params, }) {
+    const context = {
+        vault: String(params.vault),
+        amount: String(params.amount),
+    };
+    try {
+        const { amount, requestId } = params;
+        if (!params.wallet)
+            throw new core_1.AugustValidationError('INVALID_INPUT', 'vaultRequestRedeem: wallet not connected');
+        if (!params.vault)
+            throw new core_1.AugustValidationError('INVALID_INPUT', 'vaultRequestRedeem: vault is required');
+        if ((typeof amount === 'bigint' && amount <= 0n) ||
+            (typeof amount === 'number' && !(amount > 0)) ||
+            (typeof amount !== 'bigint' && typeof amount !== 'number'))
+            throw new core_1.AugustValidationError('INVALID_INPUT', 'vaultRequestRedeem: amount is required and must be > 0');
+        if (requestId !== undefined &&
+            (typeof requestId !== 'bigint' || requestId < 0n || requestId > U64_MAX))
+            throw new core_1.AugustValidationError('INVALID_INPUT', `vaultRequestRedeem: requestId must be a bigint between 0 and ${U64_MAX}, got ${String(requestId)}.`);
+        // Before any RPC: an unusable floor should cost the caller nothing.
+        if (params.minAssetsOut !== undefined)
+            (0, vault_actions_1.validateExplicitFloor)(params.minAssetsOut, 'minAssetsOut');
+        else if (params.slippageBps !== undefined)
+            (0, pricing_1.validateSlippageBps)(params.slippageBps);
+        const owner = new web3_js_1.PublicKey(params.wallet);
+        const vaultState = new web3_js_1.PublicKey(params.vault);
+        const queue = (0, withdrawal_queue_1.deriveWithdrawalQueuePda)(vaultState, queueProgramId);
+        const program = queueProgram(provider, queueProgramId);
+        const [stateInfo, queueInfo] = await connection.getMultipleAccountsInfo([
+            vaultState,
+            queue,
+        ]);
+        const vaultStateData = decodeOrThrow(vaultCoder(provider), 'vaultState', vaultState, stateInfo, `vaultRequestRedeem: no vault state at ${vaultState.toBase58()}.`);
+        const gate = vaultStateData.withdrawalQueueAuthority;
+        if (!gate || !new web3_js_1.PublicKey(gate).equals(queue)) {
+            throw new core_1.AugustValidationError('INVALID_INPUT', `vaultRequestRedeem: vault ${vaultState.toBase58()} has no withdrawal queue attached; redeem directly with \`vaultRedeem\`.`);
+        }
+        const queueState = decodeOrThrow(program.coder.accounts, 'withdrawalQueue', queue, queueInfo, `vaultRequestRedeem: the vault's queue ${queue.toBase58()} does not exist.`);
+        const shareMint = new web3_js_1.PublicKey(queueState.shareMint);
+        const depositMint = new web3_js_1.PublicKey(queueState.depositMint);
+        // Decimals for a UI amount, supply for the default floor: read at most once.
+        let shareMintState;
+        const readShareMint = async () => {
+            if (shareMintState)
+                return shareMintState;
+            const mintInfo = await connection.getAccountInfo(shareMint);
+            if (!mintInfo)
+                throw new core_1.AugustSDKError('UNKNOWN', `Share mint ${shareMint.toBase58()} does not exist.`);
+            shareMintState = (0, spl_token_1.unpackMint)(shareMint, mintInfo, spl_token_1.TOKEN_PROGRAM_ID);
+            return shareMintState;
+        };
+        let shares;
+        if (typeof amount === 'bigint') {
+            shares = new anchor_1.BN(amount.toString());
+        }
+        else {
+            const { decimals } = await readShareMint();
+            shares = (0, utils_1.uiAmountToRawBn)(amount, decimals);
+            if (shares.lten(0)) {
+                throw new core_1.AugustValidationError('INVALID_INPUT', `vaultRequestRedeem: ${amount} is below one raw unit of a ${decimals}-decimal share mint.`);
+            }
+        }
+        const shareAccount = await (0, token_reads_1.resolveUserTokenAccount)({
+            connection,
+            owner,
+            mint: shareMint,
+        });
+        if (shareAccount.frozen) {
+            throw new core_1.AugustValidationError('INVALID_INPUT', 'Your share account is frozen by the token issuer, so these shares cannot be escrowed.');
+        }
+        if (shareAccount.balance < BigInt(shares.toString())) {
+            throw new core_1.AugustValidationError('INVALID_INPUT', `Insufficient shares to request: this wallet holds ${shareAccount.balance} raw share units, and the request needs ${shares.toString()}.`);
+        }
+        // The holder pays out to their own richest deposit-token account, as a
+        // direct redeem does; anyone else, to their associated account.
+        const preInstructions = [];
+        let recipientTokenAccount;
+        const recipient = params.recipient
+            ? new web3_js_1.PublicKey(params.recipient)
+            : owner;
+        if (recipient.equals(owner)) {
+            const payout = await (0, token_reads_1.resolveUserTokenAccount)({
+                connection,
+                owner,
+                mint: depositMint,
+            });
+            if (payout.frozen) {
+                throw new core_1.AugustValidationError('INVALID_INPUT', 'Your token account for the deposit mint is frozen by the token issuer, so it cannot receive the payout.');
+            }
+            recipientTokenAccount = payout.address;
+            if (payout.createIx)
+                preInstructions.push(payout.createIx);
+        }
+        else {
+            // Off-curve owners are allowed: a multisig vault or another program's
+            // PDA is a valid recipient, and the program accepts it.
+            recipientTokenAccount = (0, spl_token_1.getAssociatedTokenAddressSync)(depositMint, recipient, true);
+            const existing = await connection.getAccountInfo(recipientTokenAccount);
+            if (!existing) {
+                preInstructions.push((0, spl_token_1.createAssociatedTokenAccountIdempotentInstruction)(owner, recipientTokenAccount, recipient, depositMint));
+            }
+            else if ((0, spl_token_1.unpackAccount)(recipientTokenAccount, existing, existing.owner).isFrozen) {
+                // The request would land, but every claim would then fail paying it.
+                throw new core_1.AugustValidationError('INVALID_INPUT', `The recipient's token account ${recipientTokenAccount.toBase58()} is frozen by the token issuer, so it could not receive the payout.`);
+            }
+        }
+        // Quoted from the vault state read above and the mint's supply. The program
+        // checks it at claim time against the shares' value then, net of the fee.
+        // The two reads can straddle a state change; the slippage allowance absorbs
+        // that, and an exact floor goes in `minAssetsOut`.
+        let minAssetsOut;
+        if (params.minAssetsOut !== undefined) {
+            minAssetsOut = params.minAssetsOut;
+        }
+        else {
+            const { supply } = await readShareMint();
+            const totalAssets = (0, pricing_1.totalAssetsOf)(vaultStateData);
+            // A marked-down vault can still queue a request, just not at a quote.
+            if (!(0, pricing_1.hasSharePrice)(supply, totalAssets)) {
+                throw new core_1.AugustValidationError('INVALID_INPUT', 'vaultRequestRedeem: this vault holds no assets while shares are outstanding, so there is no share price to quote a floor from; pass `minAssetsOut: 0n` to request without a floor.');
+            }
+            minAssetsOut = (0, pricing_1.quoteRedeemFloor)({
+                supply,
+                totalAssets,
+                shares: BigInt(shares.toString()),
+                offset: (0, pricing_1.resolveShareOffset)(vaultStateData.shareOffset),
+                feePpm: (0, pricing_1.toBigInt)(vaultStateData.withdrawalFee, 'withdrawalFee'),
+                slippageBps: params.slippageBps ?? pricing_1.DEFAULT_SLIPPAGE_BPS,
+            });
+        }
+        const id = requestId ?? randomRequestId();
+        const request = deriveWithdrawalRequestPda(queue, owner, id, queueProgramId);
+        const finalizer = params.finalizer
+            ? new web3_js_1.PublicKey(params.finalizer)
+            : web3_js_1.PublicKey.default;
+        const commitment = commitmentOf(connection);
+        const signature = await queueMethods(program)
+            .requestWithdrawal(new anchor_1.BN(id.toString()), shares, new anchor_1.BN(minAssetsOut.toString()), finalizer)
+            .accountsPartial({
+            queue,
+            vaultState,
+            owner,
+            ownerShareAccount: shareAccount.address,
+            escrowShares: queueState.escrowShares,
+            shareMint,
+            recipientTokenAccount,
+            request,
+            tokenProgram: spl_token_1.TOKEN_PROGRAM_ID,
+        })
+            .preInstructions(preInstructions)
+            .rpc({
+            skipPreflight: false,
+            preflightCommitment: commitment,
+            commitment,
+        });
+        core_1.Logger.log.info('vaultRequestRedeem', 'Request submitted:', signature);
+        return { signature, request: request.toBase58(), requestId: id.toString() };
+    }
+    catch (e) {
+        wrapFailure('withdrawal request', e, context);
+    }
+}
+/**
+ * Read a request and the queue it names: two reads in turn, since the queue's
+ * address comes from the request.
+ */
+async function loadRequest({ provider, connection, queueProgramId, request, operation, }) {
+    const program = queueProgram(provider, queueProgramId);
+    const requestInfo = await connection.getAccountInfo(request);
+    const requestState = decodeOrThrow(program.coder.accounts, 'withdrawalRequest', request, requestInfo, `${operation}: no pending request at ${request.toBase58()}; it may already have been claimed or cancelled.`);
+    const queue = new web3_js_1.PublicKey(requestState.queue);
+    const [queueInfo] = await connection.getMultipleAccountsInfo([queue]);
+    const queueState = decodeOrThrow(program.coder.accounts, 'withdrawalQueue', queue, queueInfo, `${operation}: the request's queue ${queue.toBase58()} does not exist.`);
+    return { program, requestState, queue, queueState };
+}
+/**
+ * Claim a request whose cooldown has run: `finalize_withdrawal`, which redeems
+ * the escrowed shares through the vault and pays the request's recipient.
+ *
+ * Anyone the request permits may claim it: the holder always, and anyone else
+ * unless it names a finalizer, in which case only that key. It is refused here,
+ * before signing, when the caller is not permitted, the cooldown has not run,
+ * or the window has closed; the wall clock stands in for the chain's, so at the
+ * boundary the program may still disagree by a slot. The vault's fee-recipient
+ * account is created in the same transaction when it has none, and so is the
+ * request's payout account when it is the holder's own ATA and has been closed
+ * since; any other closed or a frozen payout account is refused before
+ * signing, since the claim could only fail.
+ *
+ * RPC: three reads in turn, each address coming from the account before it
+ * (the request, its queue, then the queue's vault together with the payout
+ * account), then the send.
+ *
+ * @throws AugustValidationError for a missing request or one the caller cannot
+ *   claim yet, before signing.
+ * @throws AugustSDKError when the transaction fails, e.g. `NotEnoughLiquidity`
+ *   while the vault's reserve is deployed; the request stays pending.
+ */
+async function handleSolanaClaimRedeem({ provider, connection, vaultProgramId, queueProgramId, wallet, request: requestAddress, nowSeconds, }) {
+    const context = { request: String(requestAddress) };
+    try {
+        if (!wallet)
+            throw new core_1.AugustValidationError('INVALID_INPUT', 'vaultRedeem: wallet not connected');
+        const finalizer = new web3_js_1.PublicKey(wallet);
+        const request = new web3_js_1.PublicKey(requestAddress);
+        const { program, requestState, queue, queueState } = await loadRequest({
+            provider,
+            connection,
+            queueProgramId,
+            request,
+            operation: 'vaultRedeem',
+        });
+        const named = new web3_js_1.PublicKey(requestState.finalizer);
+        const permitted = finalizer.equals(new web3_js_1.PublicKey(requestState.owner)) ||
+            named.equals(web3_js_1.PublicKey.default) ||
+            named.equals(finalizer);
+        if (!permitted) {
+            throw new core_1.AugustValidationError('INVALID_INPUT', `vaultRedeem: only the holder or ${named.toBase58()} may claim this request.`);
+        }
+        const now = BigInt(nowSeconds ?? Math.floor(Date.now() / 1000));
+        const expiresAt = BigInt(requestState.expiresAt.toString());
+        if (expiresAt !== 0n && now >= expiresAt) {
+            throw new core_1.AugustValidationError('INVALID_INPUT', 'vaultRedeem: this request is past its fulfillment window and can no longer be claimed; cancel it with `vaultCancelRedeemRequest` to get the shares back.');
+        }
+        const eligibleAt = BigInt(requestState.eligibleAt.toString());
+        if (now < eligibleAt) {
+            throw new core_1.AugustValidationError('INVALID_INPUT', `vaultRedeem: this request is still in its cooldown; it can be claimed from ${new Date(Number(eligibleAt) * 1000).toISOString()}.`);
+        }
+        const vaultState = new web3_js_1.PublicKey(queueState.vaultState);
+        const recipientTokenAccount = new web3_js_1.PublicKey(requestState.recipientTokenAccount);
+        const [vaultInfo, recipientInfo] = await connection.getMultipleAccountsInfo([vaultState, recipientTokenAccount]);
+        const vault = decodeOrThrow(vaultCoder(provider), 'vaultState', vaultState, vaultInfo, `vaultRedeem: the request's vault ${vaultState.toBase58()} does not exist.`);
+        const depositMint = new web3_js_1.PublicKey(queueState.depositMint);
+        const feeRecipient = new web3_js_1.PublicKey(vault.feeRecipient);
+        // Off-curve allowed: a multisig vault or program PDA can be the fee recipient.
+        const feeRecipientAccount = (0, spl_token_1.getAssociatedTokenAddressSync)(depositMint, feeRecipient, true);
+        const preInstructions = [
+            (0, spl_token_1.createAssociatedTokenAccountIdempotentInstruction)(finalizer, feeRecipientAccount, feeRecipient, depositMint),
+        ];
+        // The payout account is fixed by the request, and may have been closed
+        // since: a wallet's cleanup closes an empty token account. The holder's own
+        // ATA can be recreated here, as the fee recipient's is; any other account
+        // cannot be rebuilt from its address, so say so before signing.
+        const requestOwner = new web3_js_1.PublicKey(requestState.owner);
+        if (!recipientInfo) {
+            const ownerAta = (0, spl_token_1.getAssociatedTokenAddressSync)(depositMint, requestOwner, true);
+            if (!recipientTokenAccount.equals(ownerAta)) {
+                throw new core_1.AugustValidationError('INVALID_INPUT', `vaultRedeem: this request pays ${recipientTokenAccount.toBase58()}, which no longer exists; it must be recreated before the request can be claimed, or the holder can cancel it.`);
+            }
+            preInstructions.push((0, spl_token_1.createAssociatedTokenAccountIdempotentInstruction)(finalizer, ownerAta, requestOwner, depositMint));
+        }
+        else if ((0, spl_token_1.unpackAccount)(recipientTokenAccount, recipientInfo, recipientInfo.owner)
+            .isFrozen) {
+            throw new core_1.AugustValidationError('INVALID_INPUT', `vaultRedeem: this request pays ${recipientTokenAccount.toBase58()}, which is frozen by the token issuer, so the claim would fail; the holder can cancel the request.`);
+        }
+        const commitment = commitmentOf(connection);
+        const signature = await queueMethods(program)
+            .finalizeWithdrawal(requestState.sequence)
+            .accountsPartial({
+            queue,
+            vaultState,
+            vaultDepositAta: utils_1.SolanaUtils.deriveVaultTokenAtaPda(vaultProgramId, depositMint, vault.vaultVersion[0]),
+            feeRecipientAccount,
+            escrowShares: queueState.escrowShares,
+            escrowAssets: queueState.escrowAssets,
+            shareMint: queueState.shareMint,
+            depositMint,
+            finalizer,
+            request,
+            owner: requestOwner,
+            recipientTokenAccount,
+            vaultProgram: vaultProgramId,
+            tokenProgram: spl_token_1.TOKEN_PROGRAM_ID,
+        })
+            .preInstructions(preInstructions)
+            .rpc({
+            skipPreflight: false,
+            preflightCommitment: commitment,
+            commitment,
+        });
+        core_1.Logger.log.info('vaultRedeem', 'Request claimed:', signature);
+        return signature;
+    }
+    catch (e) {
+        wrapFailure('withdrawal claim', e, context);
+    }
+}
+/**
+ * Cancel a pending request: `cancel_withdrawal` returns its shares to the
+ * holder's share account (created in the same transaction when they closed
+ * theirs) and closes the request, refunding its rent. Allowed at any time
+ * while the request exists, cooldown or not, expired or not, paused or not.
+ *
+ * RPC: two reads in turn (the request, then its queue), one
+ * `getParsedTokenAccountsByOwner`, then the send.
+ *
+ * @returns The confirmed transaction's signature.
+ * @throws AugustValidationError for a missing request or one `wallet` did not
+ *   make, before signing.
+ * @throws AugustSDKError when the transaction fails.
+ */
+async function handleSolanaCancelRedeemRequest({ provider, connection, queueProgramId, params, }) {
+    const context = { request: String(params.request) };
+    try {
+        if (!params.wallet)
+            throw new core_1.AugustValidationError('INVALID_INPUT', 'vaultCancelRedeemRequest: wallet not connected');
+        if (!params.request)
+            throw new core_1.AugustValidationError('INVALID_INPUT', 'vaultCancelRedeemRequest: request is required');
+        const owner = new web3_js_1.PublicKey(params.wallet);
+        const request = new web3_js_1.PublicKey(params.request);
+        const { program, requestState, queue, queueState } = await loadRequest({
+            provider,
+            connection,
+            queueProgramId,
+            request,
+            operation: 'vaultCancelRedeemRequest',
+        });
+        if (!owner.equals(new web3_js_1.PublicKey(requestState.owner))) {
+            throw new core_1.AugustValidationError('INVALID_INPUT', 'vaultCancelRedeemRequest: only the holder who made this request may cancel it.');
+        }
+        const shareMint = new web3_js_1.PublicKey(queueState.shareMint);
+        const destination = await (0, token_reads_1.resolveUserTokenAccount)({
+            connection,
+            owner,
+            mint: shareMint,
+        });
+        if (destination.frozen) {
+            throw new core_1.AugustValidationError('INVALID_INPUT', 'Your share account is frozen by the token issuer, so it cannot take the shares back.');
+        }
+        const commitment = commitmentOf(connection);
+        const signature = await queueMethods(program)
+            .cancelWithdrawal(requestState.sequence)
+            .accountsPartial({
+            queue,
+            owner,
+            request,
+            escrowShares: queueState.escrowShares,
+            shareMint,
+            destinationShareAccount: destination.address,
+            tokenProgram: spl_token_1.TOKEN_PROGRAM_ID,
+        })
+            .preInstructions(destination.createIx ? [destination.createIx] : [])
+            .rpc({
+            skipPreflight: false,
+            preflightCommitment: commitment,
+            commitment,
+        });
+        core_1.Logger.log.info('vaultCancelRedeemRequest', 'Request cancelled:', signature);
+        return signature;
+    }
+    catch (e) {
+        wrapFailure('withdrawal cancel', e, context);
+    }
+}
+//# sourceMappingURL=queue.actions.js.map

package/lib/adapters/solana/token-reads.d.ts

@@ -0,0 +1,108 @@
+import type { AccountInfo, Connection, PublicKey, TransactionInstruction } from '@solana/web3.js';
+/**
+ * The vault state and share-mint supply as of a **single slot**.
+ *
+ * Both figures price the quote, so they have to come from one snapshot. Read
+ * independently — even concurrently, as two RPC requests — a deposit or
+ * redemption landing in between combines a supply and an asset total that
+ * never coexisted, and the quote is wrong in whichever direction the
+ * interleaving fell. Seeing a 10% deposit's new assets against the old supply
+ * quotes ~10% high, and the floor then rejects a redemption whose share price
+ * never moved; the opposite ordering quotes low and silently weakens the
+ * protection. `getMultipleAccountsInfo` is served from one slot, so the pair
+ * is always coherent — and it costs one round trip instead of two.
+ *
+ * @param program - Anchor program, used only for its account coder; the
+ *   provider it was built with is irrelevant, so no read-only program is needed.
+ * @param vaultStatePda - Vault state account to decode.
+ * @param shareMintAddr - Share mint whose supply and decimals are read.
+ * @param extraAccounts - Further accounts to read in the same call and slot,
+ *   returned raw and in order (`null` for an absent one). Lets a caller that
+ *   also needs, say, token accounts avoid a second round trip.
+ * @returns The decoded `VaultState`, the share mint's raw `supply`, its
+ *   `decimals`, and `extraAccountInfos` — all from the same slot.
+ * @throws {@link AugustSDKError} when either account is absent, or is not the
+ *   account type it should be.
+ */
+export declare function readPricingSnapshot({ connection, program, vaultStatePda, shareMintAddr, extraAccounts, }: {
+    connection: Connection;
+    program: any;
+    vaultStatePda: PublicKey;
+    shareMintAddr: PublicKey;
+    extraAccounts?: PublicKey[];
+}): Promise<{
+    vaultStateData: any;
+    supply: bigint;
+    shareDecimals: number;
+    extraAccountInfos: (AccountInfo<Buffer> | null)[];
+}>;
+/**
+ * The token account a vault instruction should use for `mint`, its balance,
+ * and the instruction (if any) needed to bring it into existence.
+ *
+ * `createIx` is present iff the owner holds no *account* for `mint`. It says
+ * nothing about balance — an existing account may hold zero, which is a
+ * distinct state. Callers that need funds must check {@link balance}.
+ */
+export interface IResolvedTokenAccount {
+    /** Account to pass to the program as `sender_token_account` / `sender_share_account`. */
+    address: PublicKey;
+    /** Raw on-chain balance of {@link address}; `0n` when the account is absent. */
+    balance: bigint;
+    /**
+     * True when every account the wallet holds for this mint is frozen. Tokens
+     * can move neither out of nor into a frozen account, so this is fatal for
+     * funding, burning *and* payout — reject before requesting a signature.
+     */
+    frozen: boolean;
+    /**
+     * Idempotent ATA-creation instruction, or `undefined` when an account
+     * already exists. Prepend to the vault instruction — never send on its own.
+     */
+    createIx?: TransactionInstruction;
+}
+/**
+ * Pick which token account to hand the vault program for a given mint, and
+ * describe how to create it when the user has none.
+ *
+ * The vault program constrains these accounts by `token::mint` +
+ * `token::authority` (not `associated_token::…`), so any account the signer
+ * owns qualifies. We therefore keep an existing account when there is one —
+ * that is where the user's balance already lives — and fall back to the
+ * associated token account otherwise.
+ *
+ * Two deliberate choices:
+ *
+ * - **The create is returned, not sent.** Prepended to the deposit/redeem via
+ *   `.preInstructions()` it is atomic with the transfer, so there is no window
+ *   in which the vault instruction can reference an account that has not
+ *   landed. Sent as its own transaction — as this module used to — it raced
+ *   its own confirmation. Observed in production (2026-08-11):
+ *   a deposit failed with `Simulation failed … Logs: []` while the share-ATA
+ *   create was still in flight, then succeeded 17s later on retry. The empty
+ *   log array means the transaction never reached program execution, so there
+ *   was nothing on-chain to debug from.
+ * - **Idempotent.** `createAssociatedTokenAccountIdempotentInstruction` is a
+ *   no-op when the account already exists, so a concurrent create — another
+ *   tab, a wallet's auto-provisioning — cannot turn into an
+ *   `SystemError::AccountAlreadyInUse` ("already in use") failure between our
+ *   read and our submit.
+ *
+ * Which account wins when several exist is decided by
+ * {@link selectRichestTokenAccount} — the same rule every balance *read* in
+ * this adapter uses, so the account a UI reports and the account a transfer
+ * names are never different accounts.
+ *
+ * Classic SPL Token only: the ATA is derived under `TOKEN_PROGRAM_ID`, matching
+ * the `tokenProgram` both handlers pass, even though the program's
+ * `TokenInterface` would also accept Token-2022.
+ *
+ * @param owner - Wallet that owns the account and pays rent for any creation.
+ * @throws AugustSDKError when a candidate account's balance cannot be read
+ *   (propagated from the shared selector).
+ */
+export declare function resolveUserTokenAccount({ connection, owner, mint, }: {
+    connection: Connection;
+    owner: PublicKey;
+    mint: PublicKey;
+}): Promise<IResolvedTokenAccount>;