@augustdigital/sdk 9.11.0 → 9.13.0

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

@@ -2,6 +2,7 @@
 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");
@@ -11,6 +12,7 @@ const constants_1 = require("./constants");
 const pricing_1 = require("./pricing");
 const utils_1 = require("./utils");
 const core_1 = require("../../core");
+const token_reads_1 = require("./token-reads");
 /**
  * User-facing fallback for a throwable that carries no extractable reason.
  * Surfaces as e.g. `"Solana deposit failed: please try again"` — actionable,
@@ -145,128 +147,6 @@ function sendsCheckedInstruction({ program, checkedMethod, floor, slippageBps, h
         'enable slippage protection.');
     return false;
 }
-/**
- * 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.
- * @returns The decoded `VaultState`, the share mint's raw `supply`, and its
- *   `decimals` — all from the same slot.
- * @throws {@link AugustSDKError} when either account is absent, or is not the
- *   account type it should be.
- */
-async function readPricingSnapshot({ connection, program, vaultStatePda, shareMintAddr, }) {
-    const [vaultStateInfo, shareMintInfo] = await connection.getMultipleAccountsInfo([vaultStatePda, shareMintAddr]);
-    if (!vaultStateInfo) {
-        throw new core_1.AugustSDKError('UNKNOWN', `Vault state account ${vaultStatePda.toBase58()} does not exist; it cannot be priced.`);
-    }
-    if (!shareMintInfo) {
-        throw new core_1.AugustSDKError('UNKNOWN', `Share mint ${shareMintAddr.toBase58()} does not exist; it cannot be priced.`);
-    }
-    // `vaultState`, not the IDL's own `VaultState`: `Program` runs the IDL
-    // through `convertIdlToCamelCase`, so its coder only answers to the
-    // camelCase name and the IDL spelling throws `Account not found`. (A coder
-    // built directly from the raw IDL behaves the opposite way — which is why
-    // this has to be checked against a real `Program`, as its test does.)
-    //
-    // Decoded by name rather than `decodeAny`, so a `vaultAddress` pointing at
-    // some other account of this program fails here instead of being decoded as
-    // whatever it happens to be.
-    let vaultStateData;
-    try {
-        vaultStateData = program.coder.accounts.decode('vaultState', vaultStateInfo.data);
-    }
-    catch (e) {
-        throw new core_1.AugustSDKError('UNKNOWN', `Account ${vaultStatePda.toBase58()} is not a vault state account for this program.`, { cause: e });
-    }
-    let mint;
-    try {
-        mint = (0, spl_token_1.unpackMint)(shareMintAddr, shareMintInfo, spl_token_1.TOKEN_PROGRAM_ID);
-    }
-    catch (e) {
-        throw new core_1.AugustSDKError('UNKNOWN', `Account ${shareMintAddr.toBase58()} is not an SPL Token mint.`, { cause: e });
-    }
-    return {
-        vaultStateData,
-        supply: mint.supply,
-        shareDecimals: mint.decimals,
-    };
-}
-/**
- * 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), and `TokenOwnerOffCurveError` when
- *   `owner` is off-curve and an ATA has to be derived.
- */
-async function resolveUserTokenAccount({ connection, owner, mint, }) {
-    const existing = await connection.getParsedTokenAccountsByOwner(owner, {
-        mint,
-    });
-    const richest = (0, utils_1.selectRichestTokenAccount)(existing.value);
-    if (richest)
-        return {
-            address: richest.pubkey,
-            balance: richest.amount,
-            frozen: richest.frozen,
-        };
-    const ata = await (0, spl_token_1.getAssociatedTokenAddress)(mint, owner);
-    return {
-        address: ata,
-        balance: BigInt(0),
-        frozen: false,
-        createIx: (0, spl_token_1.createAssociatedTokenAccountIdempotentInstruction)(owner, // payer
-        ata, // associated token account
-        owner, // owner
-        mint),
-    };
-}
 /**
  * Resolve the two token accounts a vault instruction needs, concurrently.
  *
@@ -283,7 +163,7 @@ async function resolveUserTokenAccount({ connection, owner, mint, }) {
  * @param mints - `[first, second]`; the returned tuple matches this order.
  */
 async function resolveUserTokenAccountPair({ connection, owner, mints, }) {
-    const settled = await Promise.allSettled(mints.map((mint) => resolveUserTokenAccount({ connection, owner, mint })));
+    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;
@@ -466,7 +346,7 @@ async function handleSolanaDeposit({ provider, connection, network = constants_1
             // 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 readPricingSnapshot({
+            const { vaultStateData, supply } = await (0, token_reads_1.readPricingSnapshot)({
                 connection,
                 program,
                 vaultStatePda,
@@ -613,12 +493,21 @@ async function handleSolanaRedeem({ provider, connection, vaultProgramId, vaultA
         // 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 readPricingSnapshot({
+        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.AugustValidationError('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());

package/lib/adapters/solana/withdrawal-queue.d.ts

@@ -0,0 +1,125 @@
+import { type Connection, PublicKey } from '@solana/web3.js';
+import type { IAddress, ISolanaNetwork, IVaultAvailableRedemption } from '../../types';
+import { VaultRedemptionStatus } from '../../types/vaults';
+import type { IVaultWithdrawalQueue } from '../../types/vaults';
+import type { ISolanaVaultState, ISolanaWithdrawalRequestState } from './types';
+/**
+ * The queue PDA for a vault: `["withdrawal_queue", vault_state]` under the queue
+ * program. The vault only ever attaches this address.
+ *
+ * @param vaultState - The vault's `VaultState` account.
+ * @param queueProgramId - The august_withdrawal_queue program id for the network.
+ */
+export declare function deriveWithdrawalQueuePda(vaultState: PublicKey, queueProgramId: PublicKey): PublicKey;
+/**
+ * Where a request stands at `nowSeconds`, by the program's own rules
+ * (`WithdrawalRequest::is_expired` / `is_eligible`): a non-zero `expiresAt` at
+ * or before now is expired, and that is checked first because an expired
+ * request can only be cancelled; otherwise it is claimable from `eligibleAt`.
+ *
+ * @param request - Decoded request; `eligibleAt` / `expiresAt` in Unix seconds.
+ * @param nowSeconds - Unix seconds. Wall-clock time stands in for the chain's
+ *   clock, so a request within seconds of a boundary may be classified a slot
+ *   early or late.
+ */
+export declare function classifyWithdrawalRequest(request: Pick<ISolanaWithdrawalRequestState, 'eligibleAt' | 'expiresAt'>, nowSeconds: number): VaultRedemptionStatus;
+/**
+ * What finalizing `shares` would pay the recipient at the vault's current
+ * state: the offset-aware `assets_for_redeem`, less the ceil-rounded
+ * withdrawal fee. Finalize prices at execution, so this is an estimate.
+ *
+ * @returns Raw deposit-mint units, net of fee.
+ * @throws AugustValidationError when the vault has no share price.
+ */
+export declare function estimateRequestPayout(input: {
+    vaultState: Pick<ISolanaVaultState, 'localAum' | 'deployedAum' | 'withdrawalFee' | 'shareOffset'>;
+    supply: bigint;
+    shares: bigint;
+}): bigint;
+/**
+ * The withdrawal queue program id a Solana service names, or `undefined` when
+ * it names none: the queue is not deployed on its network (mainnet-beta until
+ * its upgrade), or the service has neither `network` nor `getProgramId`. Read
+ * paths treat that as "no queue" rather than a failed read, so they make no RPC
+ * call and log nothing.
+ *
+ * Prefers `network`, read straight from `programIds`: `getProgramId` is an
+ * instrumented public method, and calling it where it throws by design would
+ * record an error breadcrumb on every vault read.
+ *
+ * @param service - The SolanaAdapter (or a stand-in) the read was given.
+ * @returns The queue program id, or `undefined`.
+ * @throws When the service names a malformed id; callers read inside their
+ *   own `try`, so that is logged as a failed queue read.
+ */
+export declare function resolveQueueProgramId(service: {
+    network?: ISolanaNetwork;
+    getProgramId?: (type: 'vault' | 'withdrawalQueue') => string;
+}): PublicKey | undefined;
+/**
+ * The vault's withdrawal queue summary for `IVault.withdrawalQueue`, or
+ * `undefined` when the vault has no queue.
+ *
+ * `enabled` is whether the vault's redeem gate points at this queue, read from
+ * the vault state in the same call as the queue, so an attach or release shows
+ * at once rather than when a cached vault state expires. A queue that was
+ * released keeps its account and may still hold pending requests, so it is
+ * reported with `enabled: false`.
+ *
+ * RPC: one `getMultipleAccountsInfo` (the queue and the vault state). Not
+ * cached: the counters change with every request.
+ *
+ * @param input - The vault and where to read.
+ */
+export declare function getSolanaWithdrawalQueueSummary(input: {
+    connection: Connection;
+    queueProgramId: PublicKey;
+    /** The vault's `VaultState` account. */
+    vaultState: PublicKey;
+    /** Decimals of the vault's share mint, for `pendingShares`. */
+    shareDecimals: number;
+}): Promise<IVaultWithdrawalQueue | undefined>;
+/**
+ * `owner`'s pending requests on a vault's queue, split the way the EVM path
+ * splits them: `availableRedemptions` holds requests still waiting
+ * (`AWAITING_COOLDOWN`) or past their window (`EXPIRED`, cancel-only);
+ * `pendingRedemptions` holds requests finalizable now (`READY_TO_CLAIM`).
+ *
+ * Each entry's `amount` is the escrowed shares and `estimatedAssets` the net
+ * payout at the current share price (see {@link estimateRequestPayout}),
+ * priced from the vault state and share supply of a single slot, never from a
+ * cached state. `receiver` is the wallet that owns the request's payout token
+ * account, which need not be the requester; if that account is gone it is the
+ * account address itself. `id` and `hash` are the request account's address:
+ * the program keeps no creation transaction to point at. `date` and
+ * `day` / `month` / `year` are the eligibility time (UTC); `timestamp` is when
+ * the request was made.
+ *
+ * RPC, worst case: one `getAccountInfo` (skipped once the queue is known to
+ * exist), one `getProgramAccounts` filtered on queue and owner, and, when the
+ * owner has any request, one `getMultipleAccountsInfo` carrying the vault
+ * state, share mint and up to 98 distinct payout accounts. Each further 100
+ * distinct payout accounts cost one more `getMultipleAccountsInfo`, at most
+ * four in flight. A vault without a queue costs the single `getAccountInfo`.
+ *
+ * @param input - The vault, the owner, and where to read.
+ */
+export declare function getSolanaWithdrawalRedemptions(input: {
+    connection: Connection;
+    queueProgramId: PublicKey;
+    /** The vault's `VaultState` account, read fresh for pricing. */
+    vaultStateAddress: PublicKey;
+    /** The vault's share mint, read in the same call for the supply. */
+    shareMint: PublicKey;
+    /** The holder whose requests to list. */
+    owner: PublicKey;
+    /** The vault address to stamp on each entry. */
+    vault: IAddress;
+    /** Deposit mint decimals, for `estimatedAssets`. */
+    depositDecimals: number;
+    /** Unix seconds to classify against; defaults to now. */
+    nowSeconds?: number;
+}): Promise<{
+    availableRedemptions: IVaultAvailableRedemption[];
+    pendingRedemptions: IVaultAvailableRedemption[];
+}>;

package/lib/adapters/solana/withdrawal-queue.js

@@ -0,0 +1,301 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveWithdrawalQueuePda = deriveWithdrawalQueuePda;
+exports.classifyWithdrawalRequest = classifyWithdrawalRequest;
+exports.estimateRequestPayout = estimateRequestPayout;
+exports.resolveQueueProgramId = resolveQueueProgramId;
+exports.getSolanaWithdrawalQueueSummary = getSolanaWithdrawalQueueSummary;
+exports.getSolanaWithdrawalRedemptions = getSolanaWithdrawalRedemptions;
+/**
+ * Read paths for the august_withdrawal_queue program: the per-vault queue
+ * summary and a holder's pending withdrawal requests.
+ *
+ * Internal to the SDK. `getSolanaVault` uses {@link getSolanaWithdrawalQueueSummary};
+ * `getVaultPositions` and `getVaultAvailableRedemptions` use
+ * {@link getSolanaWithdrawalRedemptions}. Nothing here signs or writes.
+ */
+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 cache_1 = require("../../core/cache");
+const concurrency_1 = require("../../core/helpers/concurrency");
+const vaults_1 = require("../../types/vaults");
+const vault_idl_1 = require("./idl/vault-idl");
+const withdrawal_queue_idl_1 = require("./idl/withdrawal-queue-idl");
+const pricing_1 = require("./pricing");
+const constants_1 = require("./constants");
+const utils_1 = require("./utils");
+const token_reads_1 = require("./token-reads");
+const WITHDRAWAL_QUEUE_SEED = 'withdrawal_queue';
+/** Byte offsets of `queue` and `owner` in a `WithdrawalRequest`, after the 8-byte discriminator. */
+const REQUEST_QUEUE_OFFSET = 8;
+const REQUEST_OWNER_OFFSET = 40;
+/** `getMultipleAccountsInfo` accepts at most this many accounts per call. */
+const MAX_ACCOUNTS_PER_CALL = 100;
+/** Payout-account batches beyond the first, in flight at once. */
+const PAYOUT_BATCH_CONCURRENCY = 4;
+/**
+ * The queue PDA for a vault: `["withdrawal_queue", vault_state]` under the queue
+ * program. The vault only ever attaches this address.
+ *
+ * @param vaultState - The vault's `VaultState` account.
+ * @param queueProgramId - The august_withdrawal_queue program id for the network.
+ */
+function deriveWithdrawalQueuePda(vaultState, queueProgramId) {
+    return web3_js_1.PublicKey.findProgramAddressSync([Buffer.from(WITHDRAWAL_QUEUE_SEED), vaultState.toBuffer()], queueProgramId)[0];
+}
+/** A read-only queue program client on `connection`. No wallet, no RPC on construction. */
+function queueProgram(connection, queueProgramId) {
+    return new anchor_1.Program({ ...withdrawal_queue_idl_1.withdrawalQueueIdl, address: queueProgramId.toBase58() }, utils_1.SolanaUtils.getReadOnlyProvider({ connection }));
+}
+/** A read-only vault program client, used only for its account coder. */
+function vaultProgram(connection) {
+    return new anchor_1.Program(vault_idl_1.vaultIdl, utils_1.SolanaUtils.getReadOnlyProvider({ connection }));
+}
+/**
+ * Where a request stands at `nowSeconds`, by the program's own rules
+ * (`WithdrawalRequest::is_expired` / `is_eligible`): a non-zero `expiresAt` at
+ * or before now is expired, and that is checked first because an expired
+ * request can only be cancelled; otherwise it is claimable from `eligibleAt`.
+ *
+ * @param request - Decoded request; `eligibleAt` / `expiresAt` in Unix seconds.
+ * @param nowSeconds - Unix seconds. Wall-clock time stands in for the chain's
+ *   clock, so a request within seconds of a boundary may be classified a slot
+ *   early or late.
+ */
+function classifyWithdrawalRequest(request, nowSeconds) {
+    const expiresAt = BigInt(request.expiresAt.toString());
+    const now = BigInt(nowSeconds);
+    if (expiresAt !== 0n && now >= expiresAt) {
+        return vaults_1.VaultRedemptionStatus.EXPIRED;
+    }
+    if (now >= BigInt(request.eligibleAt.toString())) {
+        return vaults_1.VaultRedemptionStatus.READY_TO_CLAIM;
+    }
+    return vaults_1.VaultRedemptionStatus.AWAITING_COOLDOWN;
+}
+/**
+ * What finalizing `shares` would pay the recipient at the vault's current
+ * state: the offset-aware `assets_for_redeem`, less the ceil-rounded
+ * withdrawal fee. Finalize prices at execution, so this is an estimate.
+ *
+ * @returns Raw deposit-mint units, net of fee.
+ * @throws AugustValidationError when the vault has no share price.
+ */
+function estimateRequestPayout(input) {
+    const { vaultState, supply, shares } = input;
+    const gross = (0, pricing_1.assetsForRedeem)({
+        supply,
+        totalAssets: (0, pricing_1.totalAssetsOf)(vaultState),
+        shares,
+        offset: (0, pricing_1.resolveShareOffset)(vaultState.shareOffset),
+    });
+    return (gross -
+        (0, pricing_1.withdrawalFee)(gross, (0, pricing_1.toBigInt)(vaultState.withdrawalFee, 'withdrawalFee')));
+}
+/**
+ * Whether the vault's queue account exists, remembering a yes. A queue is never
+ * closed once created (release keeps it so the vault can re-attach), so a
+ * positive answer is safe to cache; a negative one is not, and costs one
+ * `getAccountInfo` each time.
+ */
+async function queueExists(connection, queue) {
+    const cacheKey = `withdrawalQueueExists-${queue.toBase58()}`;
+    if (await (0, cache_1.getSafeCache)(cacheKey))
+        return true;
+    const exists = (await connection.getAccountInfo(queue)) !== null;
+    if (exists)
+        await (0, cache_1.setSafeCache)(cacheKey, true);
+    return exists;
+}
+/**
+ * The wallet a request pays: the owner (authority) of its payout token account.
+ * A request may pay someone other than its requester, so this is read from the
+ * account rather than assumed. If the account is gone or is not a token
+ * account, its address is the best identification there is, and is returned
+ * as is; finalizing such a request would fail until the account is restored.
+ */
+function payoutWallet(tokenAccount, info) {
+    if (!info)
+        return tokenAccount.toBase58();
+    try {
+        return (0, spl_token_1.unpackAccount)(tokenAccount, info, info.owner).owner.toBase58();
+    }
+    catch {
+        return tokenAccount.toBase58();
+    }
+}
+/**
+ * The withdrawal queue program id a Solana service names, or `undefined` when
+ * it names none: the queue is not deployed on its network (mainnet-beta until
+ * its upgrade), or the service has neither `network` nor `getProgramId`. Read
+ * paths treat that as "no queue" rather than a failed read, so they make no RPC
+ * call and log nothing.
+ *
+ * Prefers `network`, read straight from `programIds`: `getProgramId` is an
+ * instrumented public method, and calling it where it throws by design would
+ * record an error breadcrumb on every vault read.
+ *
+ * @param service - The SolanaAdapter (or a stand-in) the read was given.
+ * @returns The queue program id, or `undefined`.
+ * @throws When the service names a malformed id; callers read inside their
+ *   own `try`, so that is logged as a failed queue read.
+ */
+function resolveQueueProgramId(service) {
+    if (service.network) {
+        const id = (0, constants_1.getDeployedProgramIds)(service.network)?.withdrawalQueue;
+        return id ? new web3_js_1.PublicKey(id) : undefined;
+    }
+    if (!service.getProgramId)
+        return undefined;
+    try {
+        return new web3_js_1.PublicKey(service.getProgramId('withdrawalQueue'));
+    }
+    catch (error) {
+        if (error instanceof core_1.AugustValidationError)
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * The vault's withdrawal queue summary for `IVault.withdrawalQueue`, or
+ * `undefined` when the vault has no queue.
+ *
+ * `enabled` is whether the vault's redeem gate points at this queue, read from
+ * the vault state in the same call as the queue, so an attach or release shows
+ * at once rather than when a cached vault state expires. A queue that was
+ * released keeps its account and may still hold pending requests, so it is
+ * reported with `enabled: false`.
+ *
+ * RPC: one `getMultipleAccountsInfo` (the queue and the vault state). Not
+ * cached: the counters change with every request.
+ *
+ * @param input - The vault and where to read.
+ */
+async function getSolanaWithdrawalQueueSummary(input) {
+    const queue = deriveWithdrawalQueuePda(input.vaultState, input.queueProgramId);
+    const [queueInfo, vaultStateInfo] = await input.connection.getMultipleAccountsInfo([queue, input.vaultState]);
+    if (!queueInfo || !vaultStateInfo)
+        return undefined;
+    // Decoded by name, so an account of another type at either address throws
+    // rather than being read as this one.
+    const state = queueProgram(input.connection, input.queueProgramId).coder.accounts.decode('withdrawalQueue', queueInfo.data);
+    const gate = vaultProgram(input.connection).coder.accounts.decode('vaultState', vaultStateInfo.data).withdrawalQueueAuthority;
+    return {
+        address: queue.toBase58(),
+        enabled: gate ? new web3_js_1.PublicKey(gate).equals(queue) : false,
+        cooldownSeconds: state.cooldownSeconds.toNumber(),
+        fulfillmentWindowSeconds: state.fulfillmentWindowSeconds.toNumber(),
+        pendingCount: state.pendingRequests.toNumber(),
+        pendingShares: (0, core_1.toNormalizedBn)(BigInt(state.pendingShares.toString()), input.shareDecimals),
+    };
+}
+/**
+ * `owner`'s pending requests on a vault's queue, split the way the EVM path
+ * splits them: `availableRedemptions` holds requests still waiting
+ * (`AWAITING_COOLDOWN`) or past their window (`EXPIRED`, cancel-only);
+ * `pendingRedemptions` holds requests finalizable now (`READY_TO_CLAIM`).
+ *
+ * Each entry's `amount` is the escrowed shares and `estimatedAssets` the net
+ * payout at the current share price (see {@link estimateRequestPayout}),
+ * priced from the vault state and share supply of a single slot, never from a
+ * cached state. `receiver` is the wallet that owns the request's payout token
+ * account, which need not be the requester; if that account is gone it is the
+ * account address itself. `id` and `hash` are the request account's address:
+ * the program keeps no creation transaction to point at. `date` and
+ * `day` / `month` / `year` are the eligibility time (UTC); `timestamp` is when
+ * the request was made.
+ *
+ * RPC, worst case: one `getAccountInfo` (skipped once the queue is known to
+ * exist), one `getProgramAccounts` filtered on queue and owner, and, when the
+ * owner has any request, one `getMultipleAccountsInfo` carrying the vault
+ * state, share mint and up to 98 distinct payout accounts. Each further 100
+ * distinct payout accounts cost one more `getMultipleAccountsInfo`, at most
+ * four in flight. A vault without a queue costs the single `getAccountInfo`.
+ *
+ * @param input - The vault, the owner, and where to read.
+ */
+async function getSolanaWithdrawalRedemptions(input) {
+    const availableRedemptions = [];
+    const pendingRedemptions = [];
+    const queue = deriveWithdrawalQueuePda(input.vaultStateAddress, input.queueProgramId);
+    if (!(await queueExists(input.connection, queue))) {
+        return { availableRedemptions, pendingRedemptions };
+    }
+    const requests = await queueProgram(input.connection, input.queueProgramId).account.withdrawalRequest.all([
+        { memcmp: { offset: REQUEST_QUEUE_OFFSET, bytes: queue.toBase58() } },
+        { memcmp: { offset: REQUEST_OWNER_OFFSET, bytes: input.owner.toBase58() } },
+    ]);
+    if (requests.length === 0) {
+        return { availableRedemptions, pendingRedemptions };
+    }
+    // Payout accounts, deduplicated: requests often share one. The first batch
+    // rides with the vault state and share mint, which must share a slot to
+    // price coherently; the rest only name receivers, so they need not.
+    const payoutAccounts = [
+        ...new Map(requests.map(({ account }) => [
+            account.recipientTokenAccount.toBase58(),
+            account.recipientTokenAccount,
+        ])).values(),
+    ];
+    const firstBatch = payoutAccounts.slice(0, MAX_ACCOUNTS_PER_CALL - 2);
+    const laterBatches = [];
+    for (let i = firstBatch.length; i < payoutAccounts.length; i += MAX_ACCOUNTS_PER_CALL) {
+        laterBatches.push(payoutAccounts.slice(i, i + MAX_ACCOUNTS_PER_CALL));
+    }
+    const [snapshot, laterInfos] = await Promise.all([
+        (0, token_reads_1.readPricingSnapshot)({
+            connection: input.connection,
+            program: vaultProgram(input.connection),
+            vaultStatePda: input.vaultStateAddress,
+            shareMintAddr: input.shareMint,
+            extraAccounts: firstBatch,
+        }),
+        (0, concurrency_1.mapWithConcurrency)(laterBatches, PAYOUT_BATCH_CONCURRENCY, (batch) => input.connection.getMultipleAccountsInfo(batch)),
+    ]);
+    const { vaultStateData, supply, shareDecimals } = snapshot;
+    const payoutInfos = [...snapshot.extraAccountInfos, ...laterInfos.flat()];
+    const payoutInfoOf = new Map(payoutAccounts.map((address, i) => [address.toBase58(), payoutInfos[i]]));
+    const now = input.nowSeconds ?? Math.floor(Date.now() / 1000);
+    for (const { publicKey, account } of requests) {
+        const shares = BigInt(account.shares.toString());
+        const eligibleAt = account.eligibleAt.toNumber();
+        const date = new Date(eligibleAt * 1000);
+        const status = classifyWithdrawalRequest(account, now);
+        let estimatedAssets;
+        try {
+            estimatedAssets = (0, core_1.toNormalizedBn)(estimateRequestPayout({ vaultState: vaultStateData, supply, shares }), input.depositDecimals);
+        }
+        catch (error) {
+            // A vault with no share price (assets zero against outstanding shares)
+            // has nothing to quote; the request itself is still listed.
+            core_1.Logger.log.warn('getSolanaWithdrawalRedemptions', 'No payout estimate', {
+                request: publicKey.toBase58(),
+                error,
+            });
+        }
+        const entry = {
+            id: publicKey.toBase58(),
+            hash: publicKey.toBase58(),
+            timestamp: account.requestedAt.toNumber(),
+            receiver: payoutWallet(account.recipientTokenAccount, payoutInfoOf.get(account.recipientTokenAccount.toBase58()) ?? null),
+            day: (0, core_1.toNormalizedBn)(date.getUTCDate(), 0),
+            month: (0, core_1.toNormalizedBn)(date.getUTCMonth() + 1, 0),
+            year: (0, core_1.toNormalizedBn)(date.getUTCFullYear(), 0),
+            amount: (0, core_1.toNormalizedBn)(shares, shareDecimals),
+            date,
+            vault: input.vault,
+            status,
+            ...(estimatedAssets && { estimatedAssets }),
+        };
+        if (status === vaults_1.VaultRedemptionStatus.READY_TO_CLAIM) {
+            pendingRedemptions.push(entry);
+        }
+        else {
+            availableRedemptions.push(entry);
+        }
+    }
+    return { availableRedemptions, pendingRedemptions };
+}
+//# sourceMappingURL=withdrawal-queue.js.map

package/lib/core/analytics/method-taxonomy.js

@@ -141,6 +141,8 @@ exports.METHOD_CATEGORIES = {
     vaultRedeem: 'write.redeem',
     claimWithdrawal: 'write.redeem',
     vaultRequestRedeem: 'write.redeem',
+    // Solana withdrawal queue: cancelling a request is part of the redeem flow.
+    vaultCancelRedeemRequest: 'write.redeem',
     rwaRedeemAsset: 'write.redeem',
     vaultApprove: 'write.approve',
     approve: 'write.approve',

package/lib/core/analytics/version.d.ts

@@ -3,4 +3,4 @@
  * Generated during publish from package.json version
  * This file is gitignored and created at publish time
  */
-export declare const SDK_VERSION = "9.11.0";
+export declare const SDK_VERSION = "9.13.0";

package/lib/core/analytics/version.js

@@ -6,5 +6,5 @@ exports.SDK_VERSION = void 0;
  * Generated during publish from package.json version
  * This file is gitignored and created at publish time
  */
-exports.SDK_VERSION = '9.11.0';
+exports.SDK_VERSION = '9.13.0';
 //# sourceMappingURL=version.js.map

package/lib/main.d.ts

@@ -206,8 +206,24 @@ export declare class AugustSDK extends AugustBase {
     }): Promise<number>;
     /**
      * Get redemption requests that are ready to be claimed.
+     *
+     * For a Solana vault, `wallet` is the holder's base58 address and the result
+     * lists their withdrawal-queue requests: waiting (`AWAITING_COOLDOWN`) and
+     * past-window (`EXPIRED`, cancel-only) ones in `availableRedemptions`, and
+     * claimable ones (`READY_TO_CLAIM`) in `pendingRedemptions`, each with
+     * `estimatedAssets`, the net payout at the current share price. Without a
+     * Solana wallet, or for a vault with no queue, both lists are empty. Solana
+     * RPC: the vault state, one `getAccountInfo` for the queue, and, when it
+     * exists, one `getProgramAccounts` and one `getMultipleAccountsInfo` (the
+     * vault state, share mint and payout accounts, read together).
+     *
      * @param props - Vault address, chain ID, and optional wallet filter
      * @returns Array of available redemption requests with amounts and timestamps
+     * @example
+     * ```ts
+     * const { availableRedemptions, pendingRedemptions } =
+     *   await sdk.getVaultAvailableRedemptions({ vault: solanaVault, wallet: holder });
+     * ```
      */
     getVaultAvailableRedemptions(props: {
         vault: IAddress;