@ember-finance/sdk 2.38.0 → 2.40.0

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

@@ -0,0 +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

@@ -0,0 +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;
+}