@augustdigital/sdk 9.11.0 → 9.12.0

package/lib/adapters/solana/token-reads.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readPricingSnapshot = readPricingSnapshot;
+exports.resolveUserTokenAccount = resolveUserTokenAccount;
+/**
+ * Account reads shared by the Solana write handlers (`vault.actions.ts`,
+ * `queue.actions.ts`) and the withdrawal-queue readers.
+ *
+ * Internal: kept out of `vault.actions.ts` because `Solana.actions` is that
+ * whole module, so anything exported from it becomes public API.
+ */
+const spl_token_1 = require("@solana/spl-token");
+const core_1 = require("../../core");
+const utils_1 = require("./utils");
+/**
+ * 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.
+ */
+async function readPricingSnapshot({ connection, program, vaultStatePda, shareMintAddr, extraAccounts = [], }) {
+    const [vaultStateInfo, shareMintInfo, ...extraAccountInfos] = await connection.getMultipleAccountsInfo([
+        vaultStatePda,
+        shareMintAddr,
+        ...extraAccounts,
+    ]);
+    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,
+        extraAccountInfos,
+    };
+}
+/**
+ * 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).
+ */
+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,
+        };
+    // Off-curve allowed: a multisig vault holds and signs as a PDA.
+    const ata = await (0, spl_token_1.getAssociatedTokenAddress)(mint, owner, true);
+    return {
+        address: ata,
+        balance: BigInt(0),
+        frozen: false,
+        createIx: (0, spl_token_1.createAssociatedTokenAccountIdempotentInstruction)(owner, // payer
+        ata, // associated token account
+        owner, // owner
+        mint),
+    };
+}
+//# sourceMappingURL=token-reads.js.map

package/lib/adapters/solana/types.d.ts

@@ -1,4 +1,4 @@
-import type { AnchorProvider } from '@coral-xyz/anchor';
+import type { AnchorProvider, BN } from '@coral-xyz/anchor';
 import type { Connection, PublicKey } from '@solana/web3.js';
 export type ISolanaRpcEndpoint = `https://${string}`;
 export type ISolanaNetwork = 'devnet' | 'mainnet-beta' | 'testnet' | 'localnet';
@@ -17,11 +17,129 @@ export interface ISolanaVaultState {
     withdrawalFee: number | null;
     localAum: number | null;
     deployedAum: number | null;
+    /**
+     * Virtual-share offset the program prices with (a power of ten). Absent on
+     * builds that predate it, and `0` on vaults created before it; read it
+     * through `resolveShareOffset`, which maps both to the default.
+     */
+    shareOffset?: BN | null;
     aumIncreaseLimit: number | null;
     aumDecreaseLimit: number | null;
     pdaBump: number[] | null;
     vaultVersion: number[] | null;
     paused: boolean | null;
+    /**
+     * The only key the vault accepts a redeem from, or the default (all-zero)
+     * public key when no withdrawal queue is attached. When set it is this
+     * vault's withdrawal-queue PDA: a direct holder redeem is refused with
+     * `WithdrawalQueueRequired` (6021), and holders exit through the queue
+     * instead. Vaults created before the queue existed read the default key.
+     */
+    withdrawalQueueAuthority: PublicKey | null;
+    /**
+     * Number of registered operator subaccounts. Non-zero means operator
+     * transfers must go to a registered subaccount; `0` on vaults created before
+     * subaccounts existed, and on every mainnet vault today.
+     */
+    subaccountCount: BN | null;
+    /**
+     * Raw deposit-mint units taken out to subaccounts and not yet returned,
+     * across all of them. Distinct from `deployedAum`, which the operator marks
+     * without moving tokens. Informational: nothing on-chain trusts it.
+     */
+    deployedPrincipal: BN | null;
+}
+/**
+ * A vault's withdrawal queue account (`WithdrawalQueue` in the
+ * august_withdrawal_queue program), as Anchor decodes it.
+ *
+ * One per vault, at the PDA `["withdrawal_queue", vault_state]`. Integer fields
+ * are `BN`s in raw on-chain units; times are in seconds.
+ */
+export interface ISolanaWithdrawalQueueState {
+    /** The vault this queue serves. */
+    vaultState: PublicKey;
+    /** The vault's deposit mint, copied at initialization. */
+    depositMint: PublicKey;
+    /** The vault's share mint, copied at initialization. */
+    shareMint: PublicKey;
+    /** The queue's share escrow: holds every pending request's shares. */
+    escrowShares: PublicKey;
+    /**
+     * The queue's deposit-mint escrow. Transit only: a payout passes through it
+     * within the finalizing transaction, so it normally holds nothing.
+     */
+    escrowAssets: PublicKey;
+    /**
+     * Seconds between a request and its eligibility. Stamped on each request when
+     * it is created, so a change applies to later requests only.
+     */
+    cooldownSeconds: BN;
+    /**
+     * Seconds after scheduled eligibility that a request may still be finalized,
+     * or `0` for no expiry. Stamped on each request when it is created.
+     */
+    fulfillmentWindowSeconds: BN;
+    /** Queue-wide counter; the last value stamped on a request (the first is 1). */
+    sequence: BN;
+    /** Number of live (unfinalized, uncancelled) requests. */
+    pendingRequests: BN;
+    /** Raw shares escrowed across all live requests. */
+    pendingShares: BN;
+    /** Canonical bump of the queue PDA. */
+    bump: number;
+}
+/**
+ * One withdrawal request (`WithdrawalRequest` in the august_withdrawal_queue
+ * program), as Anchor decodes it.
+ *
+ * At the PDA `["withdrawal_request", queue, owner, request_id as u64 LE]`. The
+ * account exists while the request is pending and is closed when it is
+ * finalized or cancelled. Integer fields are `BN`s; times are Unix seconds.
+ */
+export interface ISolanaWithdrawalRequestState {
+    /** The queue holding this request's shares. */
+    queue: PublicKey;
+    /** Who requested; may cancel, and may always finalize. */
+    owner: PublicKey;
+    /** Deposit-mint token account the payout goes to. */
+    recipientTokenAccount: PublicKey;
+    /**
+     * Who may finalize besides the owner, or the default (all-zero) public key
+     * for anyone.
+     */
+    finalizer: PublicKey;
+    /** Raw shares escrowed for this request. */
+    shares: BN;
+    /** Owner-chosen id, unique per owner while the request exists. */
+    requestId: BN;
+    /**
+     * Queue-wide stamp given at creation. Instructions that target the request
+     * pass it as `expected_sequence`, so a delayed call cannot land on a
+     * recreated request with the same id.
+     */
+    sequence: BN;
+    /** When the request was created. */
+    requestedAt: BN;
+    /** `requestedAt + cooldown` at creation. Never changes. */
+    scheduledEligibleAt: BN;
+    /**
+     * When finalization may begin. Equals `scheduledEligibleAt` unless an admin
+     * or operator expedited the request, which only ever moves it earlier.
+     */
+    eligibleAt: BN;
+    /**
+     * When the request stops being finalizable (the instant itself counts as
+     * expired), or `0` for never. An expired request can only be cancelled.
+     */
+    expiresAt: BN;
+    /** Bump of the request PDA. */
+    bump: number;
+    /**
+     * The owner's floor on the net payout, in raw deposit-mint units; `0` for
+     * none. A claim that would pay less is refused with `PayoutBelowFloor`.
+     */
+    minAssetsOut: BN;
 }
 export interface ISolanaToken {
     address: string;
@@ -117,4 +235,85 @@ export interface ISolanaRedeemOptions {
      * silently dropped; with neither, the plain `redeem` is sent.
      */
     minAssetsOut?: bigint;
+    /**
+     * Claim this withdrawal request instead of redeeming instantly: the request
+     * account's address, as `id` on the entries `getVaultAvailableRedemptions`
+     * returns. Its shares, recipient and vault come from the request, so the
+     * `redeemShares` and `vaultAddress` arguments are ignored. The queue pays
+     * at the share price of the moment it settles, held to the floor the request
+     * was made with, so `slippageBps` and `minAssetsOut` must not be set
+     * alongside it.
+     *
+     * Required on a vault with a withdrawal queue attached, which refuses a
+     * direct redeem. See {@link SolanaAdapter.vaultRequestRedeem}.
+     */
+    request?: PublicKey | string;
+}
+/**
+ * Input to {@link SolanaAdapter.vaultRequestRedeem}.
+ */
+export interface ISolanaRequestRedeemParams {
+    /** The vault's `VaultState` account address. */
+    vault: PublicKey | string;
+    /** The holder, who signs, escrows the shares and pays rent for the request. */
+    wallet: PublicKey | string;
+    /** Shares to escrow: `bigint` in raw share units, or `number` as a UI amount. */
+    amount: number | bigint;
+    /**
+     * Wallet to pay when the request is claimed; its deposit-token account is
+     * created in the same transaction if it has none, at the holder's expense.
+     * Defaults to the holder.
+     */
+    recipient?: PublicKey | string;
+    /**
+     * The one key besides the holder that may claim the request, e.g. a keeper.
+     * Defaults to anyone, which is what lets a keeper settle requests for
+     * holders who do not come back.
+     */
+    finalizer?: PublicKey | string;
+    /**
+     * The request's id, unique per holder while it is pending. Defaults to a
+     * random `u64`; pass one only to choose it yourself.
+     */
+    requestId?: bigint;
+    /**
+     * Tolerance below the quoted net payout, in basis points (`0` to `10000`).
+     * The floor is fixed now and checked when the request is claimed, so it
+     * guards against a fee rise or an AUM mark-down in between; yield earned in
+     * the meantime only raises the payout. Ignored when `minAssetsOut` is given.
+     * @defaultValue 50 (0.5%)
+     */
+    slippageBps?: number;
+    /**
+     * Explicit floor on the net payout, in raw deposit-mint units, stored on the
+     * request as is. Skips the quote. `0n` means no floor: the claim pays
+     * whatever the shares are worth when it lands.
+     *
+     * Must be a `bigint` in `0 .. 2^64-1`; anything else throws
+     * {@link AugustValidationError} before the transaction is built.
+     */
+    minAssetsOut?: bigint;
+}
+/**
+ * What {@link SolanaAdapter.vaultRequestRedeem} returns.
+ */
+export interface ISolanaRequestRedeemResult {
+    /** The confirmed transaction's signature. */
+    signature: string;
+    /**
+     * The new request account's address: pass it as `request` to claim or
+     * cancel. `getVaultAvailableRedemptions` lists it as `id`.
+     */
+    request: string;
+    /** The request id, as a decimal string (a `u64`). */
+    requestId: string;
+}
+/**
+ * Input to {@link SolanaAdapter.vaultCancelRedeemRequest}.
+ */
+export interface ISolanaCancelRedeemRequestParams {
+    /** The holder who made the request; only they may cancel it. */
+    wallet: PublicKey | string;
+    /** The request account's address, as returned by `vaultRequestRedeem`. */
+    request: PublicKey | string;
 }

package/lib/adapters/solana/utils.d.ts

@@ -2,6 +2,7 @@ import { AnchorProvider, BN, Program, type web3 } from '@coral-xyz/anchor';
 import { PublicKey, type ParsedAccountData, type Transaction } from '@solana/web3.js';
 import type { ISolanaConnectionOptions, ISolanaVaultState } from './types';
 import { BlockhashConfirmingProvider } from './confirm';
+import type { ISolanaProgramIds } from './constants';
 declare function getExplorerLink({ signature, type, network, }: {
     signature: string;
     type: 'tx' | 'address' | 'token';
@@ -9,6 +10,19 @@ declare function getExplorerLink({ signature, type, network, }: {
 import { isSolanaAddress } from '../../core/helpers/chain-address';
 export { isSolanaAddress };
 declare function isSolana(signature: string): boolean;
+/**
+ * Throws unless `type` is a program type `programNames` maps. Checked at
+ * runtime for untyped callers: a typo would otherwise read as an undeployed
+ * program, and a prototype key like `toString` as a program id.
+ * @internal
+ */
+export declare function assertSolanaProgramType(type: unknown): asserts type is keyof ISolanaProgramIds;
+/**
+ * Error text for `program` having no canonical deployment on `network`, naming
+ * the networks it is deployed on.
+ * @internal
+ */
+export declare function undeployedProgramMessage(program: keyof ISolanaProgramIds, network: string): string;
 declare function getProgram({ provider, idl, programId, network, }: {
     idl?: any;
     programId?: string;
@@ -180,12 +194,14 @@ export declare const SolanaUtils: {
     programIds: {
         devnet: {
             vault: string;
+            withdrawalQueue: string;
         };
         "mainnet-beta": {
             vault: string;
         };
         localnet: {
             vault: string;
+            withdrawalQueue: string;
         };
     };
     getVaultMints: typeof getVaultMints;

package/lib/adapters/solana/utils.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SolanaUtils = exports.isSolanaAddress = void 0;
+exports.assertSolanaProgramType = assertSolanaProgramType;
+exports.undeployedProgramMessage = undeployedProgramMessage;
 exports.selectRichestTokenAccount = selectRichestTokenAccount;
 exports.uiAmountToRawBn = uiAmountToRawBn;
 const anchor_1 = require("@coral-xyz/anchor");
@@ -40,8 +42,42 @@ function isSolana(signature) {
     // Check length - Solana signatures are typically 88 characters
     return (signature.length >= 80 && signature.length <= 100);
 }
+/** On-chain name (IDL `metadata.name`) of each program type. */
+const programNames = {
+    vault: 'august_vault',
+    withdrawalQueue: 'august_withdrawal_queue',
+};
+/**
+ * Throws unless `type` is a program type `programNames` maps. Checked at
+ * runtime for untyped callers: a typo would otherwise read as an undeployed
+ * program, and a prototype key like `toString` as a program id.
+ * @internal
+ */
+function assertSolanaProgramType(type) {
+    if (typeof type !== 'string' || !Object.hasOwn(programNames, type)) {
+        throw new core_1.AugustValidationError('INVALID_INPUT', `Unknown Solana program type '${String(type)}'. Expected one of: ${Object.keys(programNames).join(', ')}.`);
+    }
+}
+/**
+ * Error text for `program` having no canonical deployment on `network`, naming
+ * the networks it is deployed on.
+ * @internal
+ */
+function undeployedProgramMessage(program, network) {
+    const deployed = Object.entries(constants_1.programIds)
+        .filter(([, ids]) => ids[program])
+        .map(([name]) => name);
+    return (`No canonical ${programNames[program]} deployment for Solana network '${network}'. ` +
+        `Deployed networks: ${deployed.join(', ')}.`);
+}
 function getProgram({ provider, idl, programId, network, }) {
     const baseIdl = idl ?? constants_1.vaultIdl;
+    // The withdrawal queue IDL resolves through `programIds.withdrawalQueue`;
+    // anything else is treated as the vault. Recognised by name, so the queue IDL
+    // never has to be imported here (and pulled into every bundle).
+    const program = baseIdl?.metadata?.name === programNames.withdrawalQueue
+        ? 'withdrawalQueue'
+        : 'vault';
     // Precedence: explicit `programId` → a custom IDL's `address` → the network
     // default → the bundled IDL's embedded `address`.
     //
@@ -50,7 +86,9 @@ function getProgram({ provider, idl, programId, network, }) {
     // copy (second bundle instance, or JSON round-tripped), silently retargeting
     // devnet callers at mainnet. Every copy carries the same build stamp, so it
     // still defers to the network default — but a genuinely custom IDL is honoured.
-    const suppliedAddress = typeof baseIdl?.address === 'string' && baseIdl.address !== constants_1.vaultIdl.address
+    // A build stamp is the program's canonical id, which some network maps.
+    const isBuildStamp = Object.values(constants_1.programIds).some((ids) => ids[program] === baseIdl?.address);
+    const suppliedAddress = typeof baseIdl?.address === 'string' && !isBuildStamp
         ? baseIdl.address
         : undefined;
     const explicitId = programId ?? suppliedAddress;
@@ -58,10 +96,9 @@ function getProgram({ provider, idl, programId, network, }) {
         return new anchor_1.Program({ ...baseIdl, address: explicitId }, provider);
     }
     if (network) {
-        const networkDefault = (0, constants_1.getDeployedProgramIds)(network)?.vault;
+        const networkDefault = (0, constants_1.getDeployedProgramIds)(network)?.[program];
         if (!networkDefault) {
-            throw new core_1.AugustValidationError('INVALID_INPUT', `No canonical august_vault deployment for Solana network '${network}'. ` +
-                `Deployed networks: ${Object.keys(constants_1.programIds).join(', ')}. ` +
+            throw new core_1.AugustValidationError('INVALID_INPUT', `${undeployedProgramMessage(program, network)} ` +
                 `Pass an explicit \`programId\` (or an IDL carrying the target \`address\`) to target a program on this network.`);
         }
         return new anchor_1.Program({ ...baseIdl, address: networkDefault }, provider);

package/lib/adapters/solana/vault.actions.d.ts

@@ -35,6 +35,23 @@ export declare function describeSolanaError(e: unknown): string;
  * program's message.
  */
 export declare function slippageHint(e: unknown): string;
+/**
+ * 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 AugustValidationError} when it is not a `bigint` in `0 .. 2^64-1`.
+ */
+export declare function validateExplicitFloor(value: bigint, label: string): bigint;
 /**
  * Deposit funds into a Solana August vault and mint share tokens.
  *