@ember-finance/sdk 2.38.0 → 2.40.0

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

@@ -0,0 +1,288 @@
+import { PublicKey, Transaction } from "@solana/web3.js";
+import { normaliseSigner } from "../signers/solana-signer.js";
+import { associatedTokenAddress } from "../utils/pdas.js";
+import { SolanaTxBuilder } from "./tx-builder.js";
+import { SolanaVaultReader } from "./vault-reader.js";
+/**
+ * Normalises an amount to a bigint, rejecting what `BigInt()` would quietly
+ * accept.
+ *
+ * `BigInt()` is far looser than it looks: `BigInt("")` and `BigInt("  ")` are
+ * `0n`, `BigInt("0x10")` is `16n` and `BigInt("-5")` is `-5n`. An empty form
+ * field would therefore become a zero-amount deposit rather than an error, and
+ * a negative would travel as far as `u64le` before failing with a RangeError
+ * that names no field. Strings must be plain decimal digits, and every amount
+ * here is unsigned on chain.
+ */
+function toBigInt(value, field) {
+    let result;
+    if (typeof value === "bigint") {
+        result = value;
+    }
+    else if (typeof value === "number") {
+        if (!Number.isInteger(value)) {
+            throw new TypeError(`${field} must be a whole number, got ${value}`);
+        }
+        // Past 2^53 a number has already lost the precision an exact token
+        // amount needs, so the value here would not be the one the caller meant.
+        if (!Number.isSafeInteger(value)) {
+            throw new TypeError(`${field} is too large to be exact as a number (${value}); pass a bigint or a string`);
+        }
+        result = BigInt(value);
+    }
+    else {
+        const digits = value.trim();
+        if (!/^\d+$/.test(digits)) {
+            throw new TypeError(`${field} must be a decimal integer string, got ${JSON.stringify(value)}`);
+        }
+        result = BigInt(digits);
+    }
+    if (result < 0n) {
+        throw new TypeError(`${field} must not be negative, got ${result}`);
+    }
+    return result;
+}
+/**
+ * Rejects a `receiver` on the instructions that have none.
+ *
+ * The options types already keep it off deposit and mint, but excess-property
+ * checking only applies to object LITERALS: a variable typed
+ * ISolanaRedeemOptions satisfies ISolanaWriteOptions and passes straight
+ * through, where the field would be silently dropped.
+ */
+function rejectReceiver(options, call) {
+    if (options && "receiver" in options) {
+        throw new TypeError(`${call} mints into the depositor's own token account and takes no receiver; ` +
+            `the program's instruction has no such argument`);
+    }
+}
+/**
+ * The user-facing writes: deposit, mint, redeem and cancel.
+ *
+ * Each method reads only what it needs to build a correct instruction — the
+ * mints' token programs and, for a redeem, the owner's request nonce — then
+ * signs and sends. The instruction building itself lives in SolanaTxBuilder,
+ * so a caller who wants to batch or route differently can use that directly.
+ */
+export class SolanaUserCalls {
+    constructor(connection, parser, 
+    /**
+     * Optional so one instance can serve a page that has not connected a
+     * wallet yet; every write then takes its own signer.
+     */
+    signer) {
+        this.connection = connection;
+        this.signer = signer;
+        this.parser = parser;
+        this.reader = new SolanaVaultReader(connection, parser);
+    }
+    /** Swap in a newer deployment without rebuilding the caller. */
+    updateDeployment(parser) {
+        this.parser = parser;
+        this.reader.updateDeployment(parser);
+    }
+    key(value) {
+        return typeof value === "string" ? new PublicKey(value) : value;
+    }
+    resolveSigner(override) {
+        const signer = override ?? this.signer;
+        if (!signer) {
+            throw new Error("no signer: pass one to the constructor or to this call");
+        }
+        return normaliseSigner(signer);
+    }
+    /**
+     * The mints and their owning token programs.
+     *
+     * The programs come from the deployment manifest when it records them and
+     * from the mint accounts otherwise. They are not assumed equal: a vault's
+     * collateral and share mints may sit under SPL Token and Token-2022
+     * respectively, and the ATA addresses differ between the two.
+     */
+    async vaultContext(shareMint) {
+        const mint = this.key(shareMint);
+        const collateralMint = this.parser.getCollateralMint(mint);
+        const [shareProgram, collateralProgram] = await Promise.all([
+            this.tokenProgram(mint),
+            this.tokenProgram(collateralMint)
+        ]);
+        return {
+            programId: this.parser.programId,
+            shareMint: mint,
+            collateralMint,
+            shareProgram,
+            collateralProgram
+        };
+    }
+    async tokenProgram(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;
+    }
+    /**
+     * Signs, sends and confirms. Simulation runs first unless turned off, and
+     * its error is surfaced in place of the send's: the program's own message
+     * is in the simulation logs, while a failed send gives only a code.
+     */
+    async send(instructions, signer, options) {
+        const tx = new Transaction();
+        if (options?.preInstructions?.length)
+            tx.add(...options.preInstructions);
+        tx.add(...instructions);
+        const { blockhash, lastValidBlockHeight } = await this.connection.getLatestBlockhash();
+        tx.recentBlockhash = blockhash;
+        tx.feePayer = signer.publicKey;
+        let unitsConsumed;
+        if (options?.simulate !== false) {
+            const sim = await this.connection.simulateTransaction(tx);
+            if (sim.value.err) {
+                const logs = sim.value.logs?.join("\n") ?? "";
+                throw new Error(`simulation failed: ${JSON.stringify(sim.value.err)}\n${logs}`);
+            }
+            unitsConsumed = sim.value.unitsConsumed ?? undefined;
+        }
+        const signed = await signer.signTransaction(tx);
+        const signature = await this.connection.sendRawTransaction(signed.serialize());
+        // Confirm at the commitment this Connection READS at, not a hardcoded
+        // one. Confirming at "confirmed" under a "finalized" connection returns
+        // before the following reads can see the write - two awaited
+        // redeemShares calls would then read the same nonce and derive a
+        // request account that already exists.
+        const confirmation = await this.connection.confirmTransaction({ signature, blockhash, lastValidBlockHeight }, this.connection.commitment ?? "confirmed");
+        if (confirmation.value.err) {
+            throw new Error(`transaction ${signature} failed: ${JSON.stringify(confirmation.value.err)}`);
+        }
+        return { signature, unitsConsumed };
+    }
+    // --- deposits ---
+    /**
+     * Deposits collateral and mints shares at the vault's live rate.
+     *
+     * `minShares` is the on-chain slippage floor; it bites only if the rate
+     * manager moves the rate between quoting and landing. Quote it with
+     * `SolanaVaultReader.previewDeposit`.
+     *
+     * The depositor's share account is created here when missing, so a first
+     * deposit is still a single transaction.
+     */
+    async depositAsset(shareMint, amount, minShares, options) {
+        // Validated before any round trip: a bad amount should not cost two
+        // account reads first, and the error should name the field rather than
+        // surface as a failed mint lookup.
+        rejectReceiver(options, "depositAsset");
+        const amountValue = toBigInt(amount, "amount");
+        const minSharesValue = toBigInt(minShares, "minShares");
+        const signer = this.resolveSigner(options?.signer);
+        const ctx = await this.vaultContext(shareMint);
+        const instructions = [
+            ...(await this.ensureShareAccount(ctx, signer.publicKey)),
+            SolanaTxBuilder.depositAsset(ctx, signer.publicKey, amountValue, minSharesValue)
+        ];
+        return this.send(instructions, signer, options);
+    }
+    /**
+     * Mints an exact share count, spending at most `maxAmount` of collateral.
+     * The mirror of depositAsset, for a caller who wants a round share figure.
+     */
+    async mintShares(shareMint, shares, maxAmount, options) {
+        rejectReceiver(options, "mintShares");
+        const sharesValue = toBigInt(shares, "shares");
+        const maxAmountValue = toBigInt(maxAmount, "maxAmount");
+        const signer = this.resolveSigner(options?.signer);
+        const ctx = await this.vaultContext(shareMint);
+        const instructions = [
+            ...(await this.ensureShareAccount(ctx, signer.publicKey)),
+            SolanaTxBuilder.mintShares(ctx, signer.publicKey, sharesValue, maxAmountValue)
+        ];
+        return this.send(instructions, signer, options);
+    }
+    /**
+     * The idempotent ATA instruction, but only when the account is actually
+     * missing: including it unconditionally costs a few hundred compute units
+     * on every repeat deposit for nothing.
+     */
+    async ensureShareAccount(ctx, owner) {
+        const ata = associatedTokenAddress(owner, ctx.shareMint, ctx.shareProgram);
+        const existing = await this.connection.getAccountInfo(ata);
+        if (existing !== null)
+            return [];
+        return [
+            SolanaTxBuilder.createAtaIdempotent(owner, owner, ctx.shareMint, ctx.shareProgram)
+        ];
+    }
+    // --- withdrawals ---
+    /**
+     * Queues a withdrawal. This does NOT return collateral: the shares are
+     * escrowed and a request is appended to the vault's queue, which the
+     * operator settles later. Watch it with `getPendingWithdrawals`.
+     *
+     * The request's account is seeded by the owner's next nonce, which is read
+     * here — a caller passing a stale one would collide with their own earlier
+     * request.
+     */
+    async redeemShares(shareMint, shares, options) {
+        const sharesValue = toBigInt(shares, "shares");
+        const signer = this.resolveSigner(options?.signer);
+        const ctx = await this.vaultContext(shareMint);
+        const account = await this.reader.getAccountState(ctx.shareMint, signer.publicKey);
+        // Null before the owner's first deposit or redeem, where the program
+        // creates the account and starts the nonce at 0.
+        const nonce = account?.nextRequestNonce ?? 0n;
+        const receiver = options?.receiver
+            ? this.key(options.receiver)
+            : signer.publicKey;
+        return this.send([
+            SolanaTxBuilder.redeemShares(ctx, signer.publicKey, sharesValue, nonce, receiver)
+        ], signer, options);
+    }
+    /**
+     * Cancels a queued withdrawal by its queue `sequenceNumber` — not the
+     * request nonce that seeds the request account. Take it from
+     * `getPendingWithdrawals`.
+     */
+    async cancelPendingWithdrawalRequest(shareMint, sequenceNumber, options) {
+        const sequenceValue = toBigInt(sequenceNumber, "sequenceNumber");
+        const signer = this.resolveSigner(options?.signer);
+        const ctx = await this.vaultContext(shareMint);
+        return this.send([
+            SolanaTxBuilder.cancelPendingWithdrawalRequest(ctx, signer.publicKey, sequenceValue)
+        ], signer, options);
+    }
+    /**
+     * An owner's live queued withdrawals, each carrying the `sequenceNumber`
+     * that `cancelPendingWithdrawalRequest` takes.
+     *
+     * CANCELLED REQUESTS ARE EXCLUDED, and that filter is not cosmetic.
+     * `cancel_pending_withdrawal_request` does not remove the entry: it pushes
+     * the sequence number onto the account's `cancel_withdraw_request` list and
+     * leaves the request in place, for the operator to skip when it settles
+     * (see withdraw.rs). Returning the raw list would therefore show a
+     * withdrawal the user already cancelled as still pending, indefinitely.
+     */
+    async getPendingWithdrawals(shareMint, owner) {
+        const account = await this.accountState(shareMint, owner);
+        if (!account)
+            return [];
+        const cancelled = new Set(account.cancelWithdrawRequest.map(String));
+        return account.pendingWithdrawalRequests.filter(request => !cancelled.has(String(request.sequenceNumber)));
+    }
+    /**
+     * The requests this owner has cancelled that the operator has not yet
+     * settled. They still occupy a slot on the account until it does.
+     */
+    async getCancelledWithdrawals(shareMint, owner) {
+        const account = await this.accountState(shareMint, owner);
+        if (!account)
+            return [];
+        const cancelled = new Set(account.cancelWithdrawRequest.map(String));
+        return account.pendingWithdrawalRequests.filter(request => cancelled.has(String(request.sequenceNumber)));
+    }
+    async accountState(shareMint, owner) {
+        const address = owner ? this.key(owner) : this.resolveSigner().publicKey;
+        return this.reader.getAccountState(shareMint, address);
+    }
+}

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;
+    }>;
+}