@ember-finance/sdk 2.39.0 → 2.40.0

package/dist/src/ember-vaults.d.ts

@@ -22,6 +22,8 @@ import type { Connection as SolanaConnection } from "@solana/web3.js";
 import type { ISolanaDeployment } from "./solana-vaults/interfaces/index.js";
 import { SolanaDeploymentParser } from "./solana-vaults/utils/deployment-parser.js";
 import { SolanaVaultReader } from "./solana-vaults/on-chain-calls/vault-reader.js";
+import { SolanaUserCalls } from "./solana-vaults/on-chain-calls/user.js";
+import type { SolanaSigner } from "./solana-vaults/signers/solana-signer.js";
 import { ChainType, PlatformEnv } from "./common/constants.js";
 /**
  * SUI-specific initialization options
@@ -54,13 +56,16 @@ export interface EvmInitOptions {
  * Solana-specific initialization options.
  *
  * `connection` rather than a provider: web3.js has no provider abstraction,
- * and every read below goes through it. No signer yet - this slice is
- * read-only, and the signer shape (wallet adapter vs Keypair) is settled when
- * the write builders land.
+ * and every read goes through it.
+ *
+ * `signer` takes either shape - a raw Keypair for scripts and ops tooling, or
+ * a connected browser wallet - and is optional so a page can read before
+ * anyone connects. A write with no signer anywhere throws.
  */
 export interface SolanaInitOptions {
     chainType: "solana";
     connection: SolanaConnection;
+    signer?: SolanaSigner;
     /**
      * Unused on Solana and accepted only so the constructor can read it
      * uniformly. The chain identifier is "solana" on every cluster; which
@@ -76,8 +81,8 @@ export type EmberVaultsInitOptions = SuiInitOptions | EvmInitOptions | SolanaIni
 /**
  * Solana-specific EmberVaults instance type.
  *
- * Narrower than its Sui and EVM counterparts on purpose: reads only. The
- * admin, operator, vaultAdmin, user and txBuilder surfaces follow, and the
+ * Narrower than its Sui and EVM counterparts: reads plus the user writes.
+ * The admin, operator, vaultAdmin and txBuilder surfaces follow, and the
  * getters for them throw rather than returning undefined until they do.
  */
 export interface SolanaEmberVaults {
@@ -86,6 +91,7 @@ export interface SolanaEmberVaults {
     parser: SolanaDeploymentParser;
     walletAddress?: string;
     reader: SolanaVaultReader;
+    user: SolanaUserCalls;
     deployment: ISolanaDeployment;
 }
 /**
@@ -178,6 +184,8 @@ export declare class EmberVaults {
     private _solanaParser?;
     private _solanaDeployment?;
     private _solanaVaultReader?;
+    private _solanaUser?;
+    private _solanaSigner?;
     private _walletAddress?;
     private _chainIdentifier?;
     constructor(options: EmberVaultsInitOptions);
@@ -221,7 +229,7 @@ export declare class EmberVaults {
     get admin(): SuiAdminCalls | EVMAdminCalls;
     get operator(): SuiOperatorCalls | EVMOperatorCalls;
     get vaultAdmin(): SuiVaultAdminCalls | EVMVaultAdminCalls;
-    get user(): SuiUserCalls | EVMUserCalls;
+    get user(): SuiUserCalls | EVMUserCalls | SolanaUserCalls;
     get deployment(): ISuiDeployment | EvmProtocolInfo | ISolanaDeployment;
     /**
      * Check if this is a SUI instance

package/dist/src/ember-vaults.js

@@ -16,6 +16,7 @@ import { AccountsApi, Configuration, VaultsApi } from "./api/index.js";
 import { AccountsApi as AccountsV2Api, Configuration as ConfigurationV2, VaultsApi as VaultsV2Api } from "./api/v2/index.js";
 import { SolanaDeploymentParser } from "./solana-vaults/utils/deployment-parser.js";
 import { SolanaVaultReader } from "./solana-vaults/on-chain-calls/vault-reader.js";
+import { SolanaUserCalls } from "./solana-vaults/on-chain-calls/user.js";
 import { environmentConfig } from "./common/constants.js";
 /**
  * EmberVaults - Unified interface for both SUI and EVM chains
@@ -73,10 +74,12 @@ export class EmberVaults {
     _initSolana(options) {
         this._solanaConnection = options.connection;
         this._walletAddress = options.walletAddress;
+        this._solanaSigner = options.signer;
         if (options.deployment) {
             this._solanaDeployment = options.deployment;
             this._solanaParser = new SolanaDeploymentParser(options.deployment);
             this._solanaVaultReader = new SolanaVaultReader(options.connection, this._solanaParser);
+            this._solanaUser = new SolanaUserCalls(options.connection, this._solanaParser, options.signer);
         }
     }
     _initSui(options) {
@@ -157,6 +160,12 @@ export class EmberVaults {
             // so it is rebuilt rather than mutated - a deployment pointing at a
             // different program is a different parser.
             this._solanaParser = new SolanaDeploymentParser(solanaDeployment);
+            if (this._solanaUser) {
+                this._solanaUser.updateDeployment(this._solanaParser);
+            }
+            else {
+                this._solanaUser = new SolanaUserCalls(this._solanaConnection, this._solanaParser, this._solanaSigner);
+            }
             if (this._solanaVaultReader) {
                 this._solanaVaultReader.updateDeployment(this._solanaParser);
             }
@@ -234,7 +243,8 @@ export class EmberVaults {
      */
     notOnSolana(surface) {
         throw new Error(`${surface} is not available for Solana yet. ` +
-            `The Solana module currently exposes reads only: use .reader, .parser or .deployment.`);
+            `The Solana module exposes reads and the user writes: ` +
+            `use .reader, .user, .parser or .deployment.`);
     }
     // ============================================
     // Solana Getters
@@ -276,8 +286,11 @@ export class EmberVaults {
         return this.chainType === "sui" ? this._suiVaultAdmin : this._evmVaultAdmin;
     }
     get user() {
-        if (this.chainType === "solana")
-            this.notOnSolana("user");
+        if (this.chainType === "solana") {
+            if (!this._solanaUser)
+                throw new Error("No Solana deployment loaded. Pass one, or call init().");
+            return this._solanaUser;
+        }
         return this.chainType === "sui" ? this._suiUser : this._evmUser;
     }
     get deployment() {
@@ -360,12 +373,16 @@ export class EmberVaults {
         if (!this._solanaParser || !this._solanaVaultReader || !this._solanaDeployment) {
             throw new Error("No Solana deployment loaded. Pass one, or call init().");
         }
+        if (!this._solanaUser) {
+            throw new Error("No Solana deployment loaded. Pass one, or call init().");
+        }
         return {
             chainType: "solana",
             connection: this._solanaConnection,
             parser: this._solanaParser,
             walletAddress: this._walletAddress,
             reader: this._solanaVaultReader,
+            user: this._solanaUser,
             deployment: this._solanaDeployment
         };
     }

package/dist/src/solana-vaults/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./interfaces/index.js";
 export * from "./on-chain-calls/index.js";
+export * from "./signers/index.js";
 export * from "./utils/index.js";

package/dist/src/solana-vaults/index.js

@@ -1,3 +1,4 @@
 export * from "./interfaces/index.js";
 export * from "./on-chain-calls/index.js";
+export * from "./signers/index.js";
 export * from "./utils/index.js";

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

@@ -1 +1,3 @@
+export * from "./tx-builder.js";
+export * from "./user.js";
 export * from "./vault-reader.js";

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

@@ -1 +1,3 @@
+export * from "./tx-builder.js";
+export * from "./user.js";
 export * from "./vault-reader.js";

package/dist/src/solana-vaults/on-chain-calls/tx-builder.d.ts

@@ -0,0 +1,62 @@
+import { PublicKey, TransactionInstruction } from "@solana/web3.js";
+/** Everything an instruction needs that cannot be derived from the share mint. */
+export interface ISolanaVaultContext {
+    programId: PublicKey;
+    shareMint: PublicKey;
+    collateralMint: PublicKey;
+    /** The owning program of each mint; they need not be the same one. */
+    shareProgram: PublicKey;
+    collateralProgram: PublicKey;
+}
+/**
+ * Builds the program's user instructions. Pure: it derives addresses and
+ * encodes data, and never touches the network or signs.
+ *
+ * Kept separate from SolanaUserCalls so a caller can batch several of these
+ * into one transaction, add their own instructions around them, or hand the
+ * result to a different sender — the same split the EVM side has.
+ */
+export declare class SolanaTxBuilder {
+    /**
+     * Creates an associated token account only if it is missing.
+     *
+     * `tokenProgram` is a parameter rather than a constant: an ATA's address
+     * derives from it, so a Token-2022 mint resolves somewhere else entirely
+     * and passing the SPL Token default would create an account at an address
+     * the program will not accept.
+     */
+    static createAtaIdempotent(payer: PublicKey, owner: PublicKey, mint: PublicKey, tokenProgram?: PublicKey): TransactionInstruction;
+    /**
+     * `deposit_asset`: moves collateral in and mints shares at the live rate.
+     *
+     * `minShares` is the slippage floor and is enforced on chain. It matters
+     * only if the rate manager moves the rate between quoting and landing.
+     */
+    static depositAsset(ctx: ISolanaVaultContext, depositor: PublicKey, amount: bigint, minShares: bigint): TransactionInstruction;
+    /**
+     * `mint_shares`: the same movement expressed the other way round — an exact
+     * share count out, with `maxAmount` capping the collateral it may consume.
+     */
+    static mintShares(ctx: ISolanaVaultContext, depositor: PublicKey, shares: bigint, maxAmount: bigint): TransactionInstruction;
+    /**
+     * `redeem_shares`: burns nothing yet — it escrows the shares into the
+     * vault's pending account and appends a request to the withdrawal queue.
+     * The operator settles it later, so this returns no collateral.
+     *
+     * `requestIndex` identifies the request account and must be the owner's
+     * next index; SolanaUserCalls reads it so callers do not have to.
+     */
+    static redeemShares(ctx: ISolanaVaultContext, owner: PublicKey, shares: bigint, requestNonce: bigint, receiver: PublicKey): TransactionInstruction;
+    /**
+     * `cancel_pending_withdrawal_request`: withdraws the request from the
+     * queue, identified by its `sequenceNumber`.
+     *
+     * Only four accounts, none of them token accounts. The escrowed shares are
+     * not moved here — the request is marked cancelled on the owner's
+     * VaultAccount and the operator returns the shares when it next settles —
+     * so neither the share mint, the pending-shares escrow nor the request's
+     * own account appear. Matches CancelWithdrawalRequest in withdraw.rs: note
+     * that `vault` and `owner` are both read-only.
+     */
+    static cancelPendingWithdrawalRequest(ctx: ISolanaVaultContext, owner: PublicKey, sequenceNumber: bigint): TransactionInstruction;
+}

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

@@ -0,0 +1,190 @@
+import { SystemProgram, TransactionInstruction } from "@solana/web3.js";
+import { ASSOCIATED_TOKEN_PROGRAM_ID, TOKEN_PROGRAM_ID, associatedTokenAddress, deriveProtocolConfig, deriveVaultAccount, deriveVaultPdas, deriveWithdrawalRequest, eventCpiAccounts, instructionDiscriminator, u128le, u64le } from "../utils/pdas.js";
+/**
+ * Builds the program's user instructions. Pure: it derives addresses and
+ * encodes data, and never touches the network or signs.
+ *
+ * Kept separate from SolanaUserCalls so a caller can batch several of these
+ * into one transaction, add their own instructions around them, or hand the
+ * result to a different sender — the same split the EVM side has.
+ */
+export class SolanaTxBuilder {
+    /**
+     * Creates an associated token account only if it is missing.
+     *
+     * `tokenProgram` is a parameter rather than a constant: an ATA's address
+     * derives from it, so a Token-2022 mint resolves somewhere else entirely
+     * and passing the SPL Token default would create an account at an address
+     * the program will not accept.
+     */
+    static createAtaIdempotent(payer, owner, mint, tokenProgram = TOKEN_PROGRAM_ID) {
+        return new TransactionInstruction({
+            programId: ASSOCIATED_TOKEN_PROGRAM_ID,
+            keys: [
+                { pubkey: payer, isSigner: true, isWritable: true },
+                {
+                    pubkey: associatedTokenAddress(owner, mint, tokenProgram),
+                    isSigner: false,
+                    isWritable: true
+                },
+                { pubkey: owner, isSigner: false, isWritable: false },
+                { pubkey: mint, isSigner: false, isWritable: false },
+                { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+                { pubkey: tokenProgram, isSigner: false, isWritable: false }
+            ],
+            // 1 = CreateIdempotent. Unlike 0 (Create), this succeeds when the
+            // account already exists, so a repeat deposit needs no pre-check.
+            data: Buffer.from([1])
+        });
+    }
+    /**
+     * `deposit_asset`: moves collateral in and mints shares at the live rate.
+     *
+     * `minShares` is the slippage floor and is enforced on chain. It matters
+     * only if the rate manager moves the rate between quoting and landing.
+     */
+    static depositAsset(ctx, depositor, amount, minShares) {
+        const pdas = deriveVaultPdas(ctx.programId, ctx.shareMint);
+        return new TransactionInstruction({
+            programId: ctx.programId,
+            keys: [
+                {
+                    pubkey: deriveProtocolConfig(ctx.programId),
+                    isSigner: false,
+                    isWritable: false
+                },
+                { pubkey: pdas.vault, isSigner: false, isWritable: true },
+                { pubkey: ctx.collateralMint, isSigner: false, isWritable: false },
+                { pubkey: ctx.shareMint, isSigner: false, isWritable: true },
+                { pubkey: pdas.vaultCollateral, isSigner: false, isWritable: true },
+                { pubkey: depositor, isSigner: true, isWritable: true },
+                {
+                    pubkey: deriveVaultAccount(ctx.programId, pdas.vault, depositor),
+                    isSigner: false,
+                    isWritable: true
+                },
+                {
+                    pubkey: associatedTokenAddress(depositor, ctx.collateralMint, ctx.collateralProgram),
+                    isSigner: false,
+                    isWritable: true
+                },
+                {
+                    pubkey: associatedTokenAddress(depositor, ctx.shareMint, ctx.shareProgram),
+                    isSigner: false,
+                    isWritable: true
+                },
+                { pubkey: ctx.collateralProgram, isSigner: false, isWritable: false },
+                { pubkey: ctx.shareProgram, isSigner: false, isWritable: false },
+                { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+                ...eventCpiAccounts(ctx.programId)
+            ],
+            data: Buffer.concat([
+                instructionDiscriminator("deposit_asset"),
+                u64le(amount),
+                u64le(minShares)
+            ])
+        });
+    }
+    /**
+     * `mint_shares`: the same movement expressed the other way round — an exact
+     * share count out, with `maxAmount` capping the collateral it may consume.
+     */
+    static mintShares(ctx, depositor, shares, maxAmount) {
+        const deposit = SolanaTxBuilder.depositAsset(ctx, depositor, shares, maxAmount);
+        return new TransactionInstruction({
+            programId: deposit.programId,
+            keys: deposit.keys,
+            data: Buffer.concat([
+                instructionDiscriminator("mint_shares"),
+                u64le(shares),
+                u64le(maxAmount)
+            ])
+        });
+    }
+    /**
+     * `redeem_shares`: burns nothing yet — it escrows the shares into the
+     * vault's pending account and appends a request to the withdrawal queue.
+     * The operator settles it later, so this returns no collateral.
+     *
+     * `requestIndex` identifies the request account and must be the owner's
+     * next index; SolanaUserCalls reads it so callers do not have to.
+     */
+    static redeemShares(ctx, owner, shares, requestNonce, receiver) {
+        const pdas = deriveVaultPdas(ctx.programId, ctx.shareMint);
+        const vaultAccount = deriveVaultAccount(ctx.programId, pdas.vault, owner);
+        return new TransactionInstruction({
+            programId: ctx.programId,
+            keys: [
+                {
+                    pubkey: deriveProtocolConfig(ctx.programId),
+                    isSigner: false,
+                    isWritable: false
+                },
+                { pubkey: pdas.vault, isSigner: false, isWritable: true },
+                { pubkey: ctx.shareMint, isSigner: false, isWritable: false },
+                { pubkey: pdas.vaultPendingShares, isSigner: false, isWritable: true },
+                { pubkey: pdas.withdrawalQueue, isSigner: false, isWritable: true },
+                { pubkey: vaultAccount, isSigner: false, isWritable: true },
+                { pubkey: owner, isSigner: true, isWritable: true },
+                {
+                    pubkey: deriveWithdrawalRequest(ctx.programId, pdas.vault, owner, requestNonce),
+                    isSigner: false,
+                    isWritable: true
+                },
+                {
+                    pubkey: associatedTokenAddress(owner, ctx.shareMint, ctx.shareProgram),
+                    isSigner: false,
+                    isWritable: true
+                },
+                { pubkey: ctx.shareProgram, isSigner: false, isWritable: false },
+                { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+                ...eventCpiAccounts(ctx.programId)
+            ],
+            // `receiver` is an argument, not an account: the collateral is paid
+            // out later by the operator, so there is nothing to write to now.
+            data: Buffer.concat([
+                instructionDiscriminator("redeem_shares"),
+                u64le(shares),
+                receiver.toBuffer()
+            ])
+        });
+    }
+    /**
+     * `cancel_pending_withdrawal_request`: withdraws the request from the
+     * queue, identified by its `sequenceNumber`.
+     *
+     * Only four accounts, none of them token accounts. The escrowed shares are
+     * not moved here — the request is marked cancelled on the owner's
+     * VaultAccount and the operator returns the shares when it next settles —
+     * so neither the share mint, the pending-shares escrow nor the request's
+     * own account appear. Matches CancelWithdrawalRequest in withdraw.rs: note
+     * that `vault` and `owner` are both read-only.
+     */
+    static cancelPendingWithdrawalRequest(ctx, owner, sequenceNumber) {
+        const pdas = deriveVaultPdas(ctx.programId, ctx.shareMint);
+        return new TransactionInstruction({
+            programId: ctx.programId,
+            keys: [
+                {
+                    pubkey: deriveProtocolConfig(ctx.programId),
+                    isSigner: false,
+                    isWritable: false
+                },
+                { pubkey: pdas.vault, isSigner: false, isWritable: false },
+                {
+                    pubkey: deriveVaultAccount(ctx.programId, pdas.vault, owner),
+                    isSigner: false,
+                    isWritable: true
+                },
+                { pubkey: owner, isSigner: true, isWritable: false },
+                ...eventCpiAccounts(ctx.programId)
+            ],
+            // u128, not u64: a queue sequence number, not the request nonce
+            // that seeds the request PDA.
+            data: Buffer.concat([
+                instructionDiscriminator("cancel_pending_withdrawal_request"),
+                u128le(sequenceNumber)
+            ])
+        });
+    }
+}

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

@@ -0,0 +1,150 @@
+import { type Connection, PublicKey, type TransactionInstruction } from "@solana/web3.js";
+import { type ISolanaWithdrawalRequest } from "../interfaces/index.js";
+import { type SolanaSigner } from "../signers/solana-signer.js";
+import { SolanaDeploymentParser } from "../utils/deployment-parser.js";
+/** What a write returns. */
+export interface ISolanaTxResponse {
+    /** The transaction signature, base58. Also its explorer id. */
+    signature: string;
+    /** Compute units the simulation reported, when one ran. */
+    unitsConsumed?: number;
+}
+export interface ISolanaWriteOptions {
+    /**
+     * Simulate before sending. On by default: a failed simulation costs one
+     * round trip and reports the program's error, where a failed send costs a
+     * fee and reports a bare "custom program error".
+     */
+    simulate?: boolean;
+    /** Extra instructions to run before the vault call, e.g. a compute budget. */
+    preInstructions?: TransactionInstruction[];
+    /** Overrides the signer supplied to the constructor, for this call only. */
+    signer?: SolanaSigner;
+}
+/**
+ * Redemptions, and only redemptions, take a receiver.
+ *
+ * `deposit_asset` and `mint_shares` have no receiver argument and mint into the
+ * depositor's own associated token account, so a `receiver` on those options
+ * would be accepted and silently ignored. It is kept off their type rather than
+ * rejected at runtime, so the mistake does not compile.
+ */
+export interface ISolanaRedeemOptions extends ISolanaWriteOptions {
+    /** Who receives the collateral at settlement. Defaults to the signer. */
+    receiver?: PublicKey | string;
+}
+/**
+ * Amounts accept the shapes the Sui and EVM surfaces accept, not just bigint.
+ *
+ * `EmberVaults.user` is a union of the three chains' call classes, so a shared
+ * call site resolves each parameter to the INTERSECTION of their types. Sui's
+ * `NumStr` is `number | string` and EVM's is `string | number | bigint`;
+ * intersected with a bigint-only Solana that is `never`, so before this type
+ * existed `ember.user.redeemShares(vault, x)` failed to compile for every x —
+ * `100`, `"100"` and `100n` alike.
+ *
+ * `100n` through `ember.user` is still rejected, because Sui's `NumStr` has no
+ * bigint. That is pre-existing and unrelated to Solana; a bigint works on a
+ * narrowed instance (`asSolana().user`, or a `SolanaUserCalls` directly).
+ */
+export type SolanaAmount = bigint | number | string;
+/**
+ * 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 declare class SolanaUserCalls {
+    private readonly connection;
+    /**
+     * Optional so one instance can serve a page that has not connected a
+     * wallet yet; every write then takes its own signer.
+     */
+    private readonly signer?;
+    private parser;
+    private readonly reader;
+    constructor(connection: Connection, parser: SolanaDeploymentParser, 
+    /**
+     * Optional so one instance can serve a page that has not connected a
+     * wallet yet; every write then takes its own signer.
+     */
+    signer?: SolanaSigner);
+    /** Swap in a newer deployment without rebuilding the caller. */
+    updateDeployment(parser: SolanaDeploymentParser): void;
+    private key;
+    private resolveSigner;
+    /**
+     * 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.
+     */
+    private vaultContext;
+    private tokenProgram;
+    /**
+     * 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.
+     */
+    private send;
+    /**
+     * 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.
+     */
+    depositAsset(shareMint: PublicKey | string, amount: SolanaAmount, minShares: SolanaAmount, options?: ISolanaWriteOptions): Promise<ISolanaTxResponse>;
+    /**
+     * Mints an exact share count, spending at most `maxAmount` of collateral.
+     * The mirror of depositAsset, for a caller who wants a round share figure.
+     */
+    mintShares(shareMint: PublicKey | string, shares: SolanaAmount, maxAmount: SolanaAmount, options?: ISolanaWriteOptions): Promise<ISolanaTxResponse>;
+    /**
+     * 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.
+     */
+    private ensureShareAccount;
+    /**
+     * 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.
+     */
+    redeemShares(shareMint: PublicKey | string, shares: SolanaAmount, options?: ISolanaRedeemOptions): Promise<ISolanaTxResponse>;
+    /**
+     * Cancels a queued withdrawal by its queue `sequenceNumber` — not the
+     * request nonce that seeds the request account. Take it from
+     * `getPendingWithdrawals`.
+     */
+    cancelPendingWithdrawalRequest(shareMint: PublicKey | string, sequenceNumber: SolanaAmount, options?: ISolanaWriteOptions): Promise<ISolanaTxResponse>;
+    /**
+     * 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.
+     */
+    getPendingWithdrawals(shareMint: PublicKey | string, owner?: PublicKey | string): Promise<ISolanaWithdrawalRequest[]>;
+    /**
+     * The requests this owner has cancelled that the operator has not yet
+     * settled. They still occupy a slot on the account until it does.
+     */
+    getCancelledWithdrawals(shareMint: PublicKey | string, owner?: PublicKey | string): Promise<ISolanaWithdrawalRequest[]>;
+    private accountState;
+}

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/signers/index.d.ts

@@ -0,0 +1 @@
+export * from "./solana-signer.js";

package/dist/src/solana-vaults/signers/index.js

@@ -0,0 +1 @@
+export * from "./solana-signer.js";

package/dist/src/solana-vaults/signers/solana-signer.d.ts

@@ -0,0 +1,44 @@
+import { Keypair, PublicKey, type Transaction } from "@solana/web3.js";
+/**
+ * The browser-wallet shape: Phantom, Solflare, Backpack and the
+ * `@solana/wallet-adapter` wallets all satisfy this.
+ *
+ * Deliberately structural rather than an import of the wallet-adapter types:
+ * taking that dependency would pull a React-oriented package into a library
+ * that otherwise needs only web3.js, and every adapter already matches this.
+ */
+export interface ISolanaWalletAdapter {
+    /** Null while the wallet is disconnected. */
+    publicKey: PublicKey | null;
+    signTransaction(tx: Transaction): Promise<Transaction>;
+    /** Present on most adapters; unused here, declared so they still match. */
+    signAllTransactions?(txs: Transaction[]): Promise<Transaction[]>;
+}
+/**
+ * Either shape works wherever the SDK signs: a raw `Keypair` for scripts, ops
+ * tooling and tests, or a connected wallet for a browser app.
+ */
+export type SolanaSigner = Keypair | ISolanaWalletAdapter;
+/** What the call layer actually uses, once the two shapes are collapsed. */
+export interface INormalisedSolanaSigner {
+    publicKey: PublicKey;
+    signTransaction(tx: Transaction): Promise<Transaction>;
+}
+/**
+ * Duck-typed, NOT `instanceof Keypair`.
+ *
+ * A dApp frequently ends up with two copies of @solana/web3.js in its tree —
+ * its own and the SDK's, or two versions hoisted side by side — and a `Keypair`
+ * built against one copy fails `instanceof` against the other. That failure
+ * mode is silent and maddening to debug, so the check is on shape instead:
+ * only an adapter has `signTransaction`.
+ */
+export declare function isWalletAdapter(signer: SolanaSigner): signer is ISolanaWalletAdapter;
+/**
+ * Collapses either shape into one signer.
+ *
+ * A disconnected wallet is rejected here rather than later: its `publicKey` is
+ * null, which would otherwise surface as a confusing failure deep inside
+ * instruction building, after the caller has already paid for account reads.
+ */
+export declare function normaliseSigner(signer: SolanaSigner): INormalisedSolanaSigner;

package/dist/src/solana-vaults/signers/solana-signer.js

@@ -0,0 +1,61 @@
+/**
+ * Duck-typed, NOT `instanceof Keypair`.
+ *
+ * A dApp frequently ends up with two copies of @solana/web3.js in its tree —
+ * its own and the SDK's, or two versions hoisted side by side — and a `Keypair`
+ * built against one copy fails `instanceof` against the other. That failure
+ * mode is silent and maddening to debug, so the check is on shape instead:
+ * only an adapter has `signTransaction`.
+ */
+export function isWalletAdapter(signer) {
+    return typeof signer.signTransaction === "function";
+}
+/**
+ * The inverse check, structural throughout.
+ *
+ * `publicKey instanceof PublicKey` would defeat the whole point of the check
+ * above: a Keypair from another copy of web3.js carries THAT copy's PublicKey,
+ * so the duplicate-package hazard would simply move here and reject a perfectly
+ * good signer. It is checked by the methods this SDK actually calls on it.
+ */
+function isKeypairLike(signer) {
+    const candidate = signer;
+    const key = candidate.publicKey;
+    return (candidate.secretKey instanceof Uint8Array &&
+        key !== null &&
+        key !== undefined &&
+        typeof key.toBase58 === "function" &&
+        typeof key.toBuffer === "function");
+}
+/**
+ * Collapses either shape into one signer.
+ *
+ * A disconnected wallet is rejected here rather than later: its `publicKey` is
+ * null, which would otherwise surface as a confusing failure deep inside
+ * instruction building, after the caller has already paid for account reads.
+ */
+export function normaliseSigner(signer) {
+    if (isWalletAdapter(signer)) {
+        const { publicKey } = signer;
+        if (publicKey === null || publicKey === undefined) {
+            throw new Error("wallet is not connected: its publicKey is null. Connect it before signing.");
+        }
+        return {
+            publicKey,
+            signTransaction: (tx) => signer.signTransaction(tx)
+        };
+    }
+    if (isKeypairLike(signer)) {
+        return {
+            publicKey: signer.publicKey,
+            // partialSign rather than sign: a transaction may legitimately need
+            // other signatures too (a fresh mint keypair, a fee payer), and
+            // `sign` would discard any already collected.
+            signTransaction: async (tx) => {
+                tx.partialSign(signer);
+                return tx;
+            }
+        };
+    }
+    throw new Error("unsupported signer: pass a Keypair, or a wallet exposing publicKey and signTransaction");
+}

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

@@ -2,6 +2,15 @@ import { PublicKey } from "@solana/web3.js";
 import { type ISolanaVaultPdas } from "../interfaces/index.js";
 /** Little-endian u64, for the nonce and sequence-number seeds. */
 export declare function u64le(v: bigint | number): Buffer;
+/**
+ * A u128 as 16 little-endian bytes: the program's sequence numbers.
+ *
+ * Range-checked, because the masking loop truncates silently otherwise:
+ * `(1n << 128n) + 6n` and `6n` encode to identical bytes, so an out-of-range
+ * sequence number would cancel request 6 rather than fail. `u64le` gets this
+ * for free from `writeBigUInt64LE`, which throws.
+ */
+export declare function u128le(v: bigint | number): Buffer;
 /** The protocol-wide config. One per program id, and it can never be closed. */
 export declare const deriveProtocolConfig: (programId: PublicKey) => PublicKey;
 /**

package/dist/src/solana-vaults/utils/pdas.js

@@ -20,6 +20,27 @@ export function u64le(v) {
     b.writeBigUInt64LE(BigInt(v));
     return b;
 }
+const U128_MAX = (1n << 128n) - 1n;
+/**
+ * A u128 as 16 little-endian bytes: the program's sequence numbers.
+ *
+ * Range-checked, because the masking loop truncates silently otherwise:
+ * `(1n << 128n) + 6n` and `6n` encode to identical bytes, so an out-of-range
+ * sequence number would cancel request 6 rather than fail. `u64le` gets this
+ * for free from `writeBigUInt64LE`, which throws.
+ */
+export function u128le(v) {
+    let value = BigInt(v);
+    if (value < 0n || value > U128_MAX) {
+        throw new RangeError(`value ${value} is out of range for a u128`);
+    }
+    const buf = Buffer.alloc(16);
+    for (let i = 0; i < 16; i++) {
+        buf[i] = Number(value & 0xffn);
+        value >>= 8n;
+    }
+    return buf;
+}
 /** The protocol-wide config. One per program id, and it can never be closed. */
 export const deriveProtocolConfig = (programId) => PublicKey.findProgramAddressSync([seed(SOLANA_SEEDS.protocolConfig)], programId)[0];
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@ember-finance/sdk",
     "description": "Ember Protocol SDK",
-    "version": "2.39.0",
+    "version": "2.40.0",
     "type": "module",
     "module": "./dist/index.js",
     "main": "./dist/index.js",