@ember-finance/sdk 2.38.0 → 2.39.0

package/dist/src/solana-vaults/on-chain-calls/vault-reader.d.ts

@@ -0,0 +1,190 @@
+import { type Connection, PublicKey } from "@solana/web3.js";
+import { type ISolanaProtocolConfigState, type ISolanaVaultAccount, type ISolanaVaultPdas, type ISolanaVaultState, type ISolanaWithdrawalRequestAccount } from "../interfaces/index.js";
+import { type IWithdrawalFeeBreakdown } from "../utils/math.js";
+import { SolanaDeploymentParser } from "../utils/deployment-parser.js";
+/**
+ * Reads vault state from the chain.
+ *
+ * The quote methods answer locally from decoded state rather than simulating
+ * the program's `quote.rs` view instructions. A simulation costs a round trip
+ * each and the public RPCs throttle hard, so a page rendering a dozen quotes
+ * would stall; the arithmetic is transcribed in `utils/math.ts`, rounding
+ * included, and pinned against the program's own values in the tests.
+ *
+ * Everything else decodes accounts directly. Solana has no view functions in
+ * the EVM sense, so there is nothing cheaper to call.
+ */
+export declare class SolanaVaultReader {
+    private readonly connection;
+    private parser;
+    constructor(connection: Connection, parser: SolanaDeploymentParser);
+    /** Swap in a newer deployment without rebuilding the reader. */
+    updateDeployment(parser: SolanaDeploymentParser): void;
+    get programId(): PublicKey;
+    private key;
+    /** The protocol config, or null when the protocol is not initialised. */
+    getProtocolConfig(): Promise<ISolanaProtocolConfigState | null>;
+    isProtocolPaused(): Promise<boolean>;
+    /** The vault account, by share mint. Throws if it does not exist. */
+    getVaultState(shareMint: PublicKey | string): Promise<ISolanaVaultState>;
+    /**
+     * Delegated to the parser rather than derived here, so the manifest's
+     * recorded vault address is still checked against what this program id
+     * produces. Deriving directly would skip that and go on to read a
+     * different deployment, surfacing as a confusing missing-vault error.
+     */
+    getVaultPdas(shareMint: PublicKey | string): ISolanaVaultPdas;
+    /** Every vault the deployment knows about, keyed by share mint. */
+    getAllVaultAddresses(): string[];
+    getVaultRoles(shareMint: PublicKey | string): Promise<{
+        admin: PublicKey;
+        operator: PublicKey;
+        rateManager: PublicKey | null;
+        subAccounts: PublicKey[];
+    }>;
+    /**
+     * The four pause bits. `vault` is the whole-vault switch and ORs with each
+     * per-operation bit, so a caller checking only the specific one would miss
+     * a globally paused vault.
+     */
+    getVaultPauseStatus(shareMint: PublicKey | string): Promise<{
+        vault: boolean;
+        deposits: boolean;
+        withdrawals: boolean;
+        privileged: boolean;
+    }>;
+    isBlacklisted(shareMint: PublicKey | string, account: PublicKey | string): Promise<boolean>;
+    isSubAccount(shareMint: PublicKey | string, account: PublicKey | string): Promise<boolean>;
+    /** Share supply, read from the mint rather than tracked in the vault. */
+    getTotalSupply(shareMint: PublicKey | string): Promise<bigint>;
+    /** `total_assets`: TVL at the current rate. */
+    getTotalAssets(shareMint: PublicKey | string): Promise<bigint>;
+    /**
+     * What the custody account actually holds, against what the vault believes.
+     *
+     * Solvent means custody covers what the vault owes, not that the two are
+     * equal. Anyone can transfer into the custody account, and an unsolicited
+     * single unit would otherwise make a fully backed vault read as
+     * insolvent. `drift` carries the difference: positive is a donation or a
+     * stuck transfer, negative is a real shortfall.
+     */
+    getVaultBalances(shareMint: PublicKey | string): Promise<{
+        recorded: bigint;
+        custody: bigint;
+        solvent: boolean;
+        drift: bigint;
+    }>;
+    /**
+     * The token program that owns `mint`.
+     *
+     * Resolved from the mint account itself, not assumed. Associated token
+     * addresses derive differently under SPL Token and Token-2022, and
+     * `create_vault` takes the two token programs separately, so a vault's
+     * collateral and shares need not share one. Guessing wrong derives an
+     * address nothing lives at and reports a holder as owning zero.
+     *
+     * The manifest is consulted first where it has an answer, since that
+     * saves a round trip; it only covers collateral mints, and only those it
+     * happens to list.
+     */
+    private resolveTokenProgram;
+    /** An owner's share balance. Zero when they hold no token account. */
+    balanceOf(shareMint: PublicKey | string, owner: PublicKey | string): Promise<bigint>;
+    /** An owner's collateral balance for this vault's deposit token. */
+    getUnderlyingTokenBalance(shareMint: PublicKey | string, owner: PublicKey | string): Promise<bigint>;
+    private tokenBalance;
+    convertToShares(shareMint: PublicKey | string, assets: bigint): Promise<bigint>;
+    convertToAssets(shareMint: PublicKey | string, shares: bigint): Promise<bigint>;
+    /** Shares minted for `assets`. Floors, so a deposit never over-issues. */
+    previewDeposit(shareMint: PublicKey | string, assets: bigint): Promise<bigint>;
+    /** Collateral needed to mint `shares`. Ceils, so the vault is never short. */
+    previewMint(shareMint: PublicKey | string, shares: bigint): Promise<bigint>;
+    /**
+     * Collateral for `shares` at the current rate, **before withdrawal fees**.
+     *
+     * This matches the program's `preview_redeem`, which is also gross — but
+     * settlement subtracts the permanent and time-based fees before paying
+     * out, so on a fee-bearing vault the holder receives less than this.
+     * {@link previewRedeemNet} is what they actually get.
+     */
+    previewRedeem(shareMint: PublicKey | string, shares: bigint): Promise<bigint>;
+    /**
+     * What a holder actually receives for `shares`, fees deducted.
+     *
+     * `nowMs` decides whether the time-based fee applies, since it is charged
+     * only inside `timeBasedFeeThreshold` of the holder's last deposit.
+     * Defaults to local time, which is close enough except right at the
+     * boundary; pass the chain's clock when that matters.
+     */
+    previewRedeemNet(shareMint: PublicKey | string, shares: bigint, owner: PublicKey | string, nowMs?: bigint): Promise<IWithdrawalFeeBreakdown>;
+    /** The vault's configured withdrawal fees, and whether `owner` is exempt. */
+    getWithdrawalFee(shareMint: PublicKey | string, owner?: PublicKey | string): Promise<{
+        permanentFeePercentage: bigint;
+        timeBasedFeePercentage: bigint;
+        timeBasedFeeThreshold: bigint;
+        feeExempt: PublicKey[];
+        exempt: boolean;
+    }>;
+    /** Shares to give up for `assets`. Ceils, so the quote never understates. */
+    previewWithdraw(shareMint: PublicKey | string, assets: bigint): Promise<bigint>;
+    maxDeposit(shareMint: PublicKey | string, owner: PublicKey | string): Promise<bigint>;
+    maxMint(shareMint: PublicKey | string, owner: PublicKey | string): Promise<bigint>;
+    maxRedeem(shareMint: PublicKey | string, owner: PublicKey | string): Promise<bigint>;
+    /**
+     * Gross, matching the program's `max_withdraw`. Settlement deducts the
+     * withdrawal fees from this; see {@link previewRedeemNet}.
+     */
+    maxWithdraw(shareMint: PublicKey | string, owner: PublicKey | string): Promise<bigint>;
+    /** `quote.rs::can_deposit`. */
+    private canDeposit;
+    /** `quote.rs::can_withdraw`. */
+    private canWithdraw;
+    /** An owner's vault account, or null before their first deposit or redeem. */
+    getAccountState(shareMint: PublicKey | string, owner: PublicKey | string): Promise<ISolanaVaultAccount | null>;
+    /** Queue head and tail. Equal means drained. */
+    getWithdrawalQueue(shareMint: PublicKey | string): Promise<{
+        head: bigint;
+        tail: bigint;
+    }>;
+    /**
+     * Every open request, in queue order.
+     *
+     * Request addresses are keyed by owner and nonce, so the queue cannot be
+     * derived — this enumerates the program's accounts. That is a
+     * `getProgramAccounts` call, which public RPCs throttle hard; prefer
+     * {@link getAccountState} when you only need one owner's requests.
+     */
+    getAllPendingWithdrawals(shareMint: PublicKey | string): Promise<ISolanaWithdrawalRequestAccount[]>;
+    getPendingWithdrawalsCount(shareMint: PublicKey | string): Promise<number>;
+    /**
+     * Everything a UI needs for one holder, in one pass.
+     *
+     * Batched rather than composed from the methods above: each of those
+     * re-reads the vault, which is four extra round trips on an endpoint that
+     * throttles.
+     */
+    getUserPosition(shareMint: PublicKey | string, owner: PublicKey | string): Promise<{
+        shares: bigint;
+        assets: bigint;
+        collateralBalance: bigint;
+        pendingWithdrawalShares: bigint;
+        pendingRequests: number;
+        lastDepositTs: bigint;
+    }>;
+    /** Vault state, supply, TVL and solvency in one pass, for a vault page. */
+    getCompleteVaultInfo(shareMint: PublicKey | string): Promise<{
+        state: ISolanaVaultState;
+        totalSupply: bigint;
+        totalAssets: bigint;
+        custody: bigint;
+        solvent: boolean;
+        pendingWithdrawals: number;
+    }>;
+    /** The rate, with what a single share is worth at it. */
+    getVaultRate(shareMint: PublicKey | string): Promise<{
+        rate: bigint;
+        maxChangePerUpdate: bigint;
+        updateInterval: bigint;
+        lastUpdatedAt: bigint;
+    }>;
+}

package/dist/src/solana-vaults/on-chain-calls/vault-reader.js

@@ -0,0 +1,432 @@
+import { PublicKey } from "@solana/web3.js";
+import { decodeMint, decodeProtocolConfig, decodeVault, decodeVaultAccount, decodeWithdrawalQueue, decodeWithdrawalRequestAccount } from "../utils/borsh.js";
+import { accountDiscriminator, associatedTokenAddress, deriveVaultAccount } from "../utils/pdas.js";
+import { amountFromShares, amountFromSharesFloor, maxDepositAmount, maxMintShares, sharesFromAmount, sharesFromAmountCeil, vaultTvl, withdrawalFee } from "../utils/math.js";
+/**
+ * Reads vault state from the chain.
+ *
+ * The quote methods answer locally from decoded state rather than simulating
+ * the program's `quote.rs` view instructions. A simulation costs a round trip
+ * each and the public RPCs throttle hard, so a page rendering a dozen quotes
+ * would stall; the arithmetic is transcribed in `utils/math.ts`, rounding
+ * included, and pinned against the program's own values in the tests.
+ *
+ * Everything else decodes accounts directly. Solana has no view functions in
+ * the EVM sense, so there is nothing cheaper to call.
+ */
+export class SolanaVaultReader {
+    constructor(connection, parser) {
+        this.connection = connection;
+        this.parser = parser;
+    }
+    /** Swap in a newer deployment without rebuilding the reader. */
+    updateDeployment(parser) {
+        this.parser = parser;
+    }
+    get programId() {
+        return this.parser.programId;
+    }
+    key(value) {
+        return typeof value === "string" ? new PublicKey(value) : value;
+    }
+    // --- raw state ---
+    /** The protocol config, or null when the protocol is not initialised. */
+    async getProtocolConfig() {
+        const account = await this.connection.getAccountInfo(this.parser.getProtocolConfigAddress());
+        return account === null ? null : decodeProtocolConfig(account.data);
+    }
+    async isProtocolPaused() {
+        const config = await this.getProtocolConfig();
+        return config?.pauseNonAdminOperations ?? false;
+    }
+    /** The vault account, by share mint. Throws if it does not exist. */
+    async getVaultState(shareMint) {
+        const { vault } = this.getVaultPdas(shareMint);
+        const account = await this.connection.getAccountInfo(vault);
+        if (account === null) {
+            throw new Error(`no vault at ${vault.toBase58()}`);
+        }
+        return decodeVault(account.data);
+    }
+    /**
+     * Delegated to the parser rather than derived here, so the manifest's
+     * recorded vault address is still checked against what this program id
+     * produces. Deriving directly would skip that and go on to read a
+     * different deployment, surfacing as a confusing missing-vault error.
+     */
+    getVaultPdas(shareMint) {
+        return this.parser.getVaultPdas(this.key(shareMint));
+    }
+    /** Every vault the deployment knows about, keyed by share mint. */
+    getAllVaultAddresses() {
+        return Object.keys(this.parser.getVaults());
+    }
+    async getVaultRoles(shareMint) {
+        const vault = await this.getVaultState(shareMint);
+        return {
+            admin: vault.admin,
+            operator: vault.operator,
+            // The program stores "unset" as the default pubkey; null reads better.
+            rateManager: vault.rateManager.equals(PublicKey.default)
+                ? null
+                : vault.rateManager,
+            subAccounts: vault.subAccounts
+        };
+    }
+    /**
+     * The four pause bits. `vault` is the whole-vault switch and ORs with each
+     * per-operation bit, so a caller checking only the specific one would miss
+     * a globally paused vault.
+     */
+    async getVaultPauseStatus(shareMint) {
+        const v = await this.getVaultState(shareMint);
+        return {
+            vault: v.paused,
+            deposits: v.paused || v.pausedDeposits,
+            withdrawals: v.paused || v.pausedWithdrawals,
+            privileged: v.paused || v.pausedPrivileged
+        };
+    }
+    async isBlacklisted(shareMint, account) {
+        const vault = await this.getVaultState(shareMint);
+        const who = this.key(account);
+        return vault.blacklisted.some(a => a.equals(who));
+    }
+    async isSubAccount(shareMint, account) {
+        const vault = await this.getVaultState(shareMint);
+        const who = this.key(account);
+        return vault.subAccounts.some(a => a.equals(who));
+    }
+    // --- supply and balances ---
+    /** Share supply, read from the mint rather than tracked in the vault. */
+    async getTotalSupply(shareMint) {
+        const account = await this.connection.getAccountInfo(this.key(shareMint));
+        if (account === null)
+            throw new Error("share mint not found");
+        return decodeMint(account.data).supply;
+    }
+    /** `total_assets`: TVL at the current rate. */
+    async getTotalAssets(shareMint) {
+        const [vault, supply] = await Promise.all([
+            this.getVaultState(shareMint),
+            this.getTotalSupply(shareMint)
+        ]);
+        return vaultTvl(supply, vault.rate.value);
+    }
+    /**
+     * What the custody account actually holds, against what the vault believes.
+     *
+     * Solvent means custody covers what the vault owes, not that the two are
+     * equal. Anyone can transfer into the custody account, and an unsolicited
+     * single unit would otherwise make a fully backed vault read as
+     * insolvent. `drift` carries the difference: positive is a donation or a
+     * stuck transfer, negative is a real shortfall.
+     */
+    async getVaultBalances(shareMint) {
+        const pdas = this.getVaultPdas(shareMint);
+        const [vault, custody] = await Promise.all([
+            this.getVaultState(shareMint),
+            this.connection.getTokenAccountBalance(pdas.vaultCollateral)
+        ]);
+        const held = BigInt(custody.value.amount);
+        return {
+            recorded: vault.balance,
+            custody: held,
+            solvent: held >= vault.balance,
+            drift: held - vault.balance
+        };
+    }
+    /**
+     * The token program that owns `mint`.
+     *
+     * Resolved from the mint account itself, not assumed. Associated token
+     * addresses derive differently under SPL Token and Token-2022, and
+     * `create_vault` takes the two token programs separately, so a vault's
+     * collateral and shares need not share one. Guessing wrong derives an
+     * address nothing lives at and reports a holder as owning zero.
+     *
+     * The manifest is consulted first where it has an answer, since that
+     * saves a round trip; it only covers collateral mints, and only those it
+     * happens to list.
+     */
+    async resolveTokenProgram(mint) {
+        const recorded = this.parser.getTokenProgram(mint);
+        if (recorded)
+            return recorded;
+        const account = await this.connection.getAccountInfo(mint);
+        if (account === null)
+            throw new Error(`mint ${mint.toBase58()} not found`);
+        return account.owner;
+    }
+    /** An owner's share balance. Zero when they hold no token account. */
+    async balanceOf(shareMint, owner) {
+        const mint = this.key(shareMint);
+        return this.tokenBalance(mint, this.key(owner), await this.resolveTokenProgram(mint));
+    }
+    /** An owner's collateral balance for this vault's deposit token. */
+    async getUnderlyingTokenBalance(shareMint, owner) {
+        const mint = this.parser.getCollateralMint(shareMint);
+        return this.tokenBalance(mint, this.key(owner), await this.resolveTokenProgram(mint));
+    }
+    async tokenBalance(mint, owner, tokenProgram) {
+        const ata = associatedTokenAddress(owner, mint, tokenProgram);
+        const account = await this.connection.getAccountInfo(ata);
+        // No token account is not an error: it is how a wallet that has never
+        // held this token looks, and the answer is zero.
+        if (account === null)
+            return 0n;
+        return account.data.readBigUInt64LE(64);
+    }
+    // --- quotes, mirroring quote.rs ---
+    async convertToShares(shareMint, assets) {
+        return sharesFromAmount(assets, (await this.getVaultState(shareMint)).rate.value);
+    }
+    async convertToAssets(shareMint, shares) {
+        return amountFromSharesFloor(shares, (await this.getVaultState(shareMint)).rate.value);
+    }
+    /** Shares minted for `assets`. Floors, so a deposit never over-issues. */
+    async previewDeposit(shareMint, assets) {
+        return this.convertToShares(shareMint, assets);
+    }
+    /** Collateral needed to mint `shares`. Ceils, so the vault is never short. */
+    async previewMint(shareMint, shares) {
+        return amountFromShares(shares, (await this.getVaultState(shareMint)).rate.value);
+    }
+    /**
+     * Collateral for `shares` at the current rate, **before withdrawal fees**.
+     *
+     * This matches the program's `preview_redeem`, which is also gross — but
+     * settlement subtracts the permanent and time-based fees before paying
+     * out, so on a fee-bearing vault the holder receives less than this.
+     * {@link previewRedeemNet} is what they actually get.
+     */
+    async previewRedeem(shareMint, shares) {
+        return this.convertToAssets(shareMint, shares);
+    }
+    /**
+     * What a holder actually receives for `shares`, fees deducted.
+     *
+     * `nowMs` decides whether the time-based fee applies, since it is charged
+     * only inside `timeBasedFeeThreshold` of the holder's last deposit.
+     * Defaults to local time, which is close enough except right at the
+     * boundary; pass the chain's clock when that matters.
+     */
+    async previewRedeemNet(shareMint, shares, owner, nowMs = BigInt(Date.now())) {
+        const who = this.key(owner);
+        const [vault, account] = await Promise.all([
+            this.getVaultState(shareMint),
+            this.getAccountState(shareMint, who)
+        ]);
+        return withdrawalFee(amountFromSharesFloor(shares, vault.rate.value), vault.withdrawalFee, {
+            exempt: vault.withdrawalFee.feeExempt.some(a => a.equals(who)),
+            lastDepositTs: account?.lastDepositTs ?? 0n,
+            nowMs
+        });
+    }
+    /** The vault's configured withdrawal fees, and whether `owner` is exempt. */
+    async getWithdrawalFee(shareMint, owner) {
+        const vault = await this.getVaultState(shareMint);
+        const fee = vault.withdrawalFee;
+        const who = owner === undefined ? undefined : this.key(owner);
+        return {
+            ...fee,
+            exempt: who !== undefined && fee.feeExempt.some(a => a.equals(who))
+        };
+    }
+    /** Shares to give up for `assets`. Ceils, so the quote never understates. */
+    async previewWithdraw(shareMint, assets) {
+        return sharesFromAmountCeil(assets, (await this.getVaultState(shareMint)).rate.value);
+    }
+    async maxDeposit(shareMint, owner) {
+        const [vault, config, supply] = await Promise.all([
+            this.getVaultState(shareMint),
+            this.getProtocolConfig(),
+            this.getTotalSupply(shareMint)
+        ]);
+        if (!this.canDeposit(vault, config, this.key(owner)))
+            return 0n;
+        return maxDepositAmount(supply, vault.rate.value, vault.maxTvl);
+    }
+    async maxMint(shareMint, owner) {
+        const [vault, config, supply] = await Promise.all([
+            this.getVaultState(shareMint),
+            this.getProtocolConfig(),
+            this.getTotalSupply(shareMint)
+        ]);
+        if (!this.canDeposit(vault, config, this.key(owner)))
+            return 0n;
+        return maxMintShares(supply, vault.rate.value, vault.maxTvl);
+    }
+    async maxRedeem(shareMint, owner) {
+        const [vault, config, balance] = await Promise.all([
+            this.getVaultState(shareMint),
+            this.getProtocolConfig(),
+            this.balanceOf(shareMint, owner)
+        ]);
+        if (!this.canWithdraw(vault, config, this.key(owner)))
+            return 0n;
+        // Below the minimum the whole balance is unredeemable, not merely capped.
+        return balance < vault.minWithdrawalShares ? 0n : balance;
+    }
+    /**
+     * Gross, matching the program's `max_withdraw`. Settlement deducts the
+     * withdrawal fees from this; see {@link previewRedeemNet}.
+     */
+    async maxWithdraw(shareMint, owner) {
+        const [vault, redeemable] = await Promise.all([
+            this.getVaultState(shareMint),
+            this.maxRedeem(shareMint, owner)
+        ]);
+        return redeemable === 0n
+            ? 0n
+            : amountFromSharesFloor(redeemable, vault.rate.value);
+    }
+    /** `quote.rs::can_deposit`. */
+    canDeposit(vault, config, owner) {
+        if (config?.pauseNonAdminOperations)
+            return false;
+        if (vault.paused || vault.pausedDeposits)
+            return false;
+        if (vault.blacklisted.some(a => a.equals(owner)))
+            return false;
+        if (vault.subAccounts.some(a => a.equals(owner)))
+            return false;
+        // A bound parking lot closes the direct path to everyone not listed;
+        // with no lot, an empty list is open to all.
+        if (!vault.parkingLot.equals(PublicKey.default)) {
+            return vault.depositUserList.some(a => a.equals(owner));
+        }
+        return (vault.depositUserList.length === 0 ||
+            vault.depositUserList.some(a => a.equals(owner)));
+    }
+    /** `quote.rs::can_withdraw`. */
+    canWithdraw(vault, config, owner) {
+        if (config?.pauseNonAdminOperations)
+            return false;
+        if (vault.paused || vault.pausedWithdrawals)
+            return false;
+        if (vault.blacklisted.some(a => a.equals(owner)))
+            return false;
+        return (vault.withdrawalUserList.length === 0 ||
+            vault.withdrawalUserList.some(a => a.equals(owner)));
+    }
+    // --- withdrawals ---
+    /** An owner's vault account, or null before their first deposit or redeem. */
+    async getAccountState(shareMint, owner) {
+        const { vault } = this.getVaultPdas(shareMint);
+        const address = deriveVaultAccount(this.programId, vault, this.key(owner));
+        const account = await this.connection.getAccountInfo(address);
+        return account === null ? null : decodeVaultAccount(account.data);
+    }
+    /** Queue head and tail. Equal means drained. */
+    async getWithdrawalQueue(shareMint) {
+        const { withdrawalQueue } = this.getVaultPdas(shareMint);
+        const account = await this.connection.getAccountInfo(withdrawalQueue);
+        if (account === null)
+            throw new Error("withdrawal queue not found");
+        const q = decodeWithdrawalQueue(account.data);
+        return { head: q.head, tail: q.tail };
+    }
+    /**
+     * Every open request, in queue order.
+     *
+     * Request addresses are keyed by owner and nonce, so the queue cannot be
+     * derived — this enumerates the program's accounts. That is a
+     * `getProgramAccounts` call, which public RPCs throttle hard; prefer
+     * {@link getAccountState} when you only need one owner's requests.
+     */
+    async getAllPendingWithdrawals(shareMint) {
+        const { vault } = this.getVaultPdas(shareMint);
+        const accounts = await this.connection.getProgramAccounts(this.programId, {
+            filters: [
+                {
+                    memcmp: {
+                        offset: 0,
+                        bytes: bs58(accountDiscriminator("WithdrawalRequestAccount"))
+                    }
+                },
+                // discriminator + bump, then the vault the request belongs to.
+                { memcmp: { offset: 9, bytes: vault.toBase58() } }
+            ]
+        });
+        return accounts
+            .map(a => decodeWithdrawalRequestAccount(a.pubkey, a.account.data))
+            .sort((a, b) => a.queueIndex < b.queueIndex ? -1 : a.queueIndex > b.queueIndex ? 1 : 0);
+    }
+    async getPendingWithdrawalsCount(shareMint) {
+        const { head, tail } = await this.getWithdrawalQueue(shareMint);
+        return Number(tail - head);
+    }
+    // --- composed views ---
+    /**
+     * Everything a UI needs for one holder, in one pass.
+     *
+     * Batched rather than composed from the methods above: each of those
+     * re-reads the vault, which is four extra round trips on an endpoint that
+     * throttles.
+     */
+    async getUserPosition(shareMint, owner) {
+        const who = this.key(owner);
+        const [vault, shares, collateralBalance, account] = await Promise.all([
+            this.getVaultState(shareMint),
+            this.balanceOf(shareMint, who),
+            this.getUnderlyingTokenBalance(shareMint, who),
+            this.getAccountState(shareMint, who)
+        ]);
+        return {
+            shares,
+            assets: amountFromSharesFloor(shares, vault.rate.value),
+            collateralBalance,
+            pendingWithdrawalShares: account?.totalPendingWithdrawalShares ?? 0n,
+            pendingRequests: account?.pendingWithdrawalRequests.length ?? 0,
+            lastDepositTs: account?.lastDepositTs ?? 0n
+        };
+    }
+    /** Vault state, supply, TVL and solvency in one pass, for a vault page. */
+    async getCompleteVaultInfo(shareMint) {
+        const pdas = this.getVaultPdas(shareMint);
+        const [state, totalSupply, custody, queue] = await Promise.all([
+            this.getVaultState(shareMint),
+            this.getTotalSupply(shareMint),
+            this.connection.getTokenAccountBalance(pdas.vaultCollateral),
+            this.getWithdrawalQueue(shareMint)
+        ]);
+        const held = BigInt(custody.value.amount);
+        return {
+            state,
+            totalSupply,
+            totalAssets: vaultTvl(totalSupply, state.rate.value),
+            custody: held,
+            solvent: held >= state.balance,
+            pendingWithdrawals: Number(queue.tail - queue.head)
+        };
+    }
+    /** The rate, with what a single share is worth at it. */
+    async getVaultRate(shareMint) {
+        const { rate } = await this.getVaultState(shareMint);
+        return {
+            rate: rate.value,
+            maxChangePerUpdate: rate.maxRateChangePerUpdate,
+            updateInterval: rate.rateUpdateInterval,
+            lastUpdatedAt: rate.lastUpdatedAt
+        };
+    }
+}
+/** base58, for `memcmp` filters: web3.js wants a string, not bytes. */
+function bs58(bytes) {
+    const ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+    let n = 0n;
+    for (const b of bytes)
+        n = n * 256n + BigInt(b);
+    let out = "";
+    while (n > 0n) {
+        out = ALPHABET[Number(n % 58n)] + out;
+        n /= 58n;
+    }
+    for (const b of bytes) {
+        if (b !== 0)
+            break;
+        out = "1" + out;
+    }
+    return out;
+}

package/dist/src/solana-vaults/utils/borsh.d.ts

@@ -0,0 +1,65 @@
+import { PublicKey } from "@solana/web3.js";
+import type { ISolanaProtocolConfigState, ISolanaVaultAccount, ISolanaVaultState, ISolanaWithdrawalQueue, ISolanaWithdrawalRequestAccount } from "../interfaces/index.js";
+/**
+ * Borsh decoding for `ember_vaults` accounts.
+ *
+ * Decoded by hand rather than through Anchor's client. The program's IDL is
+ * not published on chain — `anchor idl init` cannot get an IDL this size past
+ * the public RPCs — so a client cannot fetch it, and pulling in the whole
+ * Anchor runtime to read a few dozen fields is not worth the dependency.
+ *
+ * Field order here must track `state.rs`. The discriminator check catches a
+ * wrong account type; it cannot catch a field reordered within the right one,
+ * so `SolanaAccountDecoding.test.ts` pins the offsets against fixtures taken
+ * from a real deployment.
+ */
+/** A forward-only reader over account data. */
+export declare class Cursor {
+    private readonly data;
+    private offset;
+    constructor(data: Buffer, offset?: number);
+    skip(n: number): this;
+    u8(): number;
+    bool(): boolean;
+    u64(): bigint;
+    u128(): bigint;
+    pubkey(): PublicKey;
+    string(): string;
+    vec<T>(item: (c: Cursor) => T): T[];
+    /** How far in the cursor has read. For the layout tests. */
+    position(): number;
+}
+/**
+ * `state::Vault`, in declaration order.
+ *
+ * Returns the cursor's final position alongside the value, so a caller can
+ * check it against the account's own length. Stopping early still decodes
+ * without error — the withdrawal-fee tail was missed exactly that way — so
+ * "it parsed" is not evidence the layout is right.
+ */
+export declare function decodeVaultWithPosition(data: Buffer): {
+    vault: ISolanaVaultState;
+    position: number;
+};
+/** `state::Vault`, in declaration order. */
+export declare function decodeVault(data: Buffer): ISolanaVaultState;
+/** `state::VaultAccount`. */
+export declare function decodeVaultAccount(data: Buffer): ISolanaVaultAccount;
+/** `state::WithdrawalRequestAccount`. */
+export declare function decodeWithdrawalRequestAccount(address: PublicKey, data: Buffer): ISolanaWithdrawalRequestAccount;
+/** `state::WithdrawalQueue`: head and tail, the entries live in their own accounts. */
+export declare function decodeWithdrawalQueue(data: Buffer): ISolanaWithdrawalQueue;
+/** `state::ProtocolConfig`. */
+export declare function decodeProtocolConfig(data: Buffer): ISolanaProtocolConfigState;
+export interface ISplMint {
+    mintAuthority: PublicKey | null;
+    supply: bigint;
+    decimals: number;
+    isInitialized: boolean;
+    freezeAuthority: PublicKey | null;
+}
+/**
+ * The classic 82-byte SPL mint layout. The first 82 bytes of a Token-2022
+ * mint are identical, so this reads both; it just ignores any extensions.
+ */
+export declare function decodeMint(data: Buffer): ISplMint;