@ember-finance/sdk 2.39.0 → 2.42.0

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

@@ -0,0 +1,380 @@
+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, payer = owner) {
+        const ata = associatedTokenAddress(owner, ctx.shareMint, ctx.shareProgram);
+        const existing = await this.connection.getAccountInfo(ata);
+        if (existing !== null)
+            return [];
+        return [
+            SolanaTxBuilder.createAtaIdempotent(payer, owner, ctx.shareMint, ctx.shareProgram)
+        ];
+    }
+    // --- parking lot ---
+    /**
+     * Parks a deposit: escrows collateral and queues a request for the
+     * operator to forward into the vault later. No shares are minted here.
+     *
+     * THIS CALL IS RACY BY CONSTRUCTION. The request's account address is
+     * seeded with the lot's `sequence_number + 1`, and the program increments
+     * before it writes, so two parks landing in the same slot collide and the
+     * loser fails its address check. The lot is read immediately before
+     * building to keep the window small, but it cannot be closed from here —
+     * on `ParkingLotSequenceTaken` the caller should simply call again, which
+     * re-reads and takes the next slot.
+     *
+     * No automatic retry: a resend after a failed SEND (rather than a failed
+     * simulation) could double-park if the first transaction actually landed.
+     *
+     * `receiver` takes the minted shares when the request is forwarded. The
+     * depositor keeps the refund and the account's rent either way.
+     */
+    async parkDeposit(shareMint, assets, options) {
+        const assetsValue = toBigInt(assets, "assets");
+        const signer = this.resolveSigner(options?.signer);
+        const ctx = await this.vaultContext(shareMint);
+        const lot = await this.reader.getParkingLot(ctx.shareMint);
+        if (lot === null) {
+            throw new Error(`vault ${ctx.shareMint.toBase58()} has no parking lot; deposit directly instead`);
+        }
+        if (lot.depositsPaused) {
+            throw new Error("the parking lot is not accepting deposits");
+        }
+        // +1: the slot this park will take, because the program increments
+        // before it writes.
+        const sequenceNumber = lot.sequenceNumber + 1n;
+        const receiver = options?.receiver
+            ? this.key(options.receiver)
+            : signer.publicKey;
+        // The program only checks the receiver's share account when the request
+        // is FORWARDED, and a missing one makes it skip and refund instead
+        // (`parking_lot.rs` can_receive_mint / should_skip). A first-time
+        // receiver's park would otherwise succeed here and silently become a
+        // refund later, long after the caller stopped watching. Idempotent, so
+        // it is a no-op when the account already exists, and the signer pays
+        // because the receiver may never have signed anything.
+        const response = await this.send([
+            ...(await this.ensureShareAccount(ctx, receiver, signer.publicKey)),
+            SolanaTxBuilder.parkingLotDeposit(ctx, signer.publicKey, assetsValue, sequenceNumber, receiver)
+        ], signer, options);
+        return { ...response, sequenceNumber };
+    }
+    /**
+     * Cancels a parked deposit before it settles, returning the escrowed
+     * collateral and the account's rent.
+     *
+     * Takes the request's own sequence number — from `getParkedDeposits` —
+     * not the lot's next one.
+     */
+    async cancelParkedDeposit(shareMint, sequenceNumber, options) {
+        rejectReceiver(options, "cancelParkedDeposit");
+        const sequenceValue = toBigInt(sequenceNumber, "sequenceNumber");
+        const signer = this.resolveSigner(options?.signer);
+        const ctx = await this.vaultContext(shareMint);
+        return this.send([
+            SolanaTxBuilder.parkingLotCancelDeposit(ctx, signer.publicKey, sequenceValue)
+        ], signer, options);
+    }
+    /**
+     * Claims a refund that settlement could not deliver.
+     *
+     * Only for a request whose `claimable` flag is set — the request settled
+     * but the collateral could not be returned, so it waits in escrow under
+     * the lot's `totalClaimableAssets`. `getParkedDeposits` separates these
+     * from the ones still pending.
+     */
+    async claimParkedRefund(shareMint, sequenceNumber, options) {
+        rejectReceiver(options, "claimParkedRefund");
+        const sequenceValue = toBigInt(sequenceNumber, "sequenceNumber");
+        const signer = this.resolveSigner(options?.signer);
+        const ctx = await this.vaultContext(shareMint);
+        return this.send([SolanaTxBuilder.parkingLotClaimRefund(ctx, signer.publicKey, sequenceValue)], signer, options);
+    }
+    /**
+     * This depositor's parked deposits, split into those still queued and
+     * those whose refund is waiting to be claimed.
+     *
+     * Found by filtering on the request accounts themselves rather than by
+     * walking the queue: a claimable request has already settled, so it sits
+     * BELOW the lot's head and no scan of the pending window would see it.
+     */
+    async getParkedDeposits(shareMint, owner) {
+        const address = owner ? this.key(owner) : this.resolveSigner().publicKey;
+        return this.reader.getDepositsFor(shareMint, address);
+    }
+    // --- 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

@@ -1,5 +1,5 @@
 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 ISolanaDepositRequest, type ISolanaParkingLotState, 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";
 /**
@@ -22,6 +22,18 @@ export declare class SolanaVaultReader {
     updateDeployment(parser: SolanaDeploymentParser): void;
     get programId(): PublicKey;
     private key;
+    /**
+     * Whether an account is on one of the unbounded allow lists.
+     *
+     * The program's own test is `UserListEntry::exists`: owned by the program
+     * AND non-empty. A bare "the account exists" is weaker and wrong here -
+     * these addresses are public and derivable, so anyone can make
+     * `getAccountInfo` return non-null for one by sending it lamports. That
+     * system-owned, dataless account would read as listed and then be rejected
+     * on chain, which is a confusing false positive on a path users hit
+     * directly.
+     */
+    private isListed;
     /** The protocol config, or null when the protocol is not initialised. */
     getProtocolConfig(): Promise<ISolanaProtocolConfigState | null>;
     isProtocolPaused(): Promise<boolean>;
@@ -139,6 +151,73 @@ export declare class SolanaVaultReader {
     private canDeposit;
     /** `quote.rs::can_withdraw`. */
     private canWithdraw;
+    /** The lot's address for a vault, whether or not one exists. */
+    parkingLotAddress(shareMint: PublicKey | string): PublicKey;
+    /**
+     * A vault's parking lot, or null when it has none.
+     *
+     * Null is the ordinary case: a lot is opt-in per vault, so most vaults have
+     * no account at this address at all.
+     */
+    getParkingLot(shareMint: PublicKey | string): Promise<ISolanaParkingLotState | null>;
+    /** The lot's escrow token account. */
+    parkingLotEscrowAddress(shareMint: PublicKey | string): PublicKey;
+    /** One parked deposit by its sequence number, or null if it is gone. */
+    getDepositRequest(shareMint: PublicKey | string, sequenceNumber: bigint): Promise<ISolanaDepositRequest | null>;
+    /**
+     * A page of the lot's queue, oldest first, with an explicit cursor.
+     *
+     * `limit` counts SLOTS SCANNED, not requests returned, because a slot may
+     * be empty: a cancelled request's account is closed while its number stays
+     * in the range. `scannedTo` is therefore returned separately and is always
+     * advanced — a page of zero requests still tells the caller where to
+     * resume, which an empty array alone could not.
+     *
+     * Reads are batched at `MAX_MULTIPLE_ACCOUNTS`: `getMultipleAccounts`
+     * refuses more than 100 pubkeys per call, so a larger window is split
+     * rather than failing.
+     *
+     * This window is `(queueStartIndex, sequenceNumber]` — the UNSETTLED part
+     * of the queue. Requests whose refund is waiting to be claimed sit BELOW
+     * the head and are not here; use `getRequestsByDepositor` for those.
+     */
+    getPendingDeposits(shareMint: PublicKey | string, options?: {
+        limit?: number;
+        after?: bigint;
+    }): Promise<{
+        requests: ISolanaDepositRequest[];
+        /** The last slot examined. Pass back as `after` to continue. */
+        scannedTo: bigint;
+        hasMore: boolean;
+    }>;
+    /**
+     * Every surviving request belonging to one depositor, wherever it sits in
+     * the queue.
+     *
+     * Position-independent on purpose. A CLAIMABLE request — one that settled
+     * but whose refund could not be delivered — lives BELOW `queueStartIndex`
+     * (see parking_lot.rs: "below the head only claimable requests remain"),
+     * so no scan of the pending window can ever find one. Walking downwards
+     * instead is unbounded and mostly hits closed accounts.
+     *
+     * So this filters on chain by the account's own bytes: the request's size,
+     * its parking lot at offset 9 and its depositor at offset 57. Those
+     * offsets track `DepositRequest` in state.rs and are pinned by test.
+     *
+     * `getProgramAccounts` is an indexed scan and some public RPCs restrict
+     * it; a provider endpoint is the right place to run this.
+     */
+    getRequestsByDepositor(shareMint: PublicKey | string, depositor: PublicKey | string): Promise<ISolanaDepositRequest[]>;
+    /**
+     * A depositor's requests, split by what they can do with them.
+     *
+     * `pending` is still queued and can be cancelled; `claimable` has settled
+     * with an undeliverable refund and is collected with `claim_refund`.
+     */
+    getDepositsFor(shareMint: PublicKey | string, depositor: PublicKey | string): Promise<{
+        pending: ISolanaDepositRequest[];
+        claimable: ISolanaDepositRequest[];
+    }>;
     /** 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. */