@upshiftfinance/sdk 0.0.0-stage → 0.1.0

package/lib/adapters/solana/token-reads.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readPricingSnapshot = readPricingSnapshot;
+exports.resolveUserTokenAccount = resolveUserTokenAccount;
+/**
+ * Account reads shared by the Solana write handlers (`vault.actions.ts`,
+ * `queue.actions.ts`) and the withdrawal-queue readers.
+ *
+ * Internal: kept out of `vault.actions.ts` because `Solana.actions` is that
+ * whole module, so anything exported from it becomes public API.
+ */
+const spl_token_1 = require("@solana/spl-token");
+const core_1 = require("../../core");
+const utils_1 = require("./utils");
+/**
+ * The vault state and share-mint supply as of a **single slot**.
+ *
+ * Both figures price the quote, so they have to come from one snapshot. Read
+ * independently — even concurrently, as two RPC requests — a deposit or
+ * redemption landing in between combines a supply and an asset total that
+ * never coexisted, and the quote is wrong in whichever direction the
+ * interleaving fell. Seeing a 10% deposit's new assets against the old supply
+ * quotes ~10% high, and the floor then rejects a redemption whose share price
+ * never moved; the opposite ordering quotes low and silently weakens the
+ * protection. `getMultipleAccountsInfo` is served from one slot, so the pair
+ * is always coherent — and it costs one round trip instead of two.
+ *
+ * @param program - Anchor program, used only for its account coder; the
+ *   provider it was built with is irrelevant, so no read-only program is needed.
+ * @param vaultStatePda - Vault state account to decode.
+ * @param shareMintAddr - Share mint whose supply and decimals are read.
+ * @param extraAccounts - Further accounts to read in the same call and slot,
+ *   returned raw and in order (`null` for an absent one). Lets a caller that
+ *   also needs, say, token accounts avoid a second round trip.
+ * @returns The decoded `VaultState`, the share mint's raw `supply`, its
+ *   `decimals`, and `extraAccountInfos` — all from the same slot.
+ * @throws {@link UpshiftSDKError} when either account is absent, or is not the
+ *   account type it should be.
+ */
+async function readPricingSnapshot({ connection, program, vaultStatePda, shareMintAddr, extraAccounts = [], }) {
+    const [vaultStateInfo, shareMintInfo, ...extraAccountInfos] = await connection.getMultipleAccountsInfo([
+        vaultStatePda,
+        shareMintAddr,
+        ...extraAccounts,
+    ]);
+    if (!vaultStateInfo) {
+        throw new core_1.UpshiftSDKError('UNKNOWN', `Vault state account ${vaultStatePda.toBase58()} does not exist; it cannot be priced.`);
+    }
+    if (!shareMintInfo) {
+        throw new core_1.UpshiftSDKError('UNKNOWN', `Share mint ${shareMintAddr.toBase58()} does not exist; it cannot be priced.`);
+    }
+    // `vaultState`, not the IDL's own `VaultState`: `Program` runs the IDL
+    // through `convertIdlToCamelCase`, so its coder only answers to the
+    // camelCase name and the IDL spelling throws `Account not found`. (A coder
+    // built directly from the raw IDL behaves the opposite way — which is why
+    // this has to be checked against a real `Program`, as its test does.)
+    //
+    // Decoded by name rather than `decodeAny`, so a `vaultAddress` pointing at
+    // some other account of this program fails here instead of being decoded as
+    // whatever it happens to be.
+    let vaultStateData;
+    try {
+        vaultStateData = program.coder.accounts.decode('vaultState', vaultStateInfo.data);
+    }
+    catch (e) {
+        throw new core_1.UpshiftSDKError('UNKNOWN', `Account ${vaultStatePda.toBase58()} is not a vault state account for this program.`, { cause: e });
+    }
+    let mint;
+    try {
+        mint = (0, spl_token_1.unpackMint)(shareMintAddr, shareMintInfo, spl_token_1.TOKEN_PROGRAM_ID);
+    }
+    catch (e) {
+        throw new core_1.UpshiftSDKError('UNKNOWN', `Account ${shareMintAddr.toBase58()} is not an SPL Token mint.`, { cause: e });
+    }
+    return {
+        vaultStateData,
+        supply: mint.supply,
+        shareDecimals: mint.decimals,
+        extraAccountInfos,
+    };
+}
+/**
+ * Pick which token account to hand the vault program for a given mint, and
+ * describe how to create it when the user has none.
+ *
+ * The vault program constrains these accounts by `token::mint` +
+ * `token::authority` (not `associated_token::…`), so any account the signer
+ * owns qualifies. We therefore keep an existing account when there is one —
+ * that is where the user's balance already lives — and fall back to the
+ * associated token account otherwise.
+ *
+ * Two deliberate choices:
+ *
+ * - **The create is returned, not sent.** Prepended to the deposit/redeem via
+ *   `.preInstructions()` it is atomic with the transfer, so there is no window
+ *   in which the vault instruction can reference an account that has not
+ *   landed. Sent as its own transaction — as this module used to — it raced
+ *   its own confirmation. Observed in production (2026-08-11):
+ *   a deposit failed with `Simulation failed … Logs: []` while the share-ATA
+ *   create was still in flight, then succeeded 17s later on retry. The empty
+ *   log array means the transaction never reached program execution, so there
+ *   was nothing on-chain to debug from.
+ * - **Idempotent.** `createAssociatedTokenAccountIdempotentInstruction` is a
+ *   no-op when the account already exists, so a concurrent create — another
+ *   tab, a wallet's auto-provisioning — cannot turn into an
+ *   `SystemError::AccountAlreadyInUse` ("already in use") failure between our
+ *   read and our submit.
+ *
+ * Which account wins when several exist is decided by
+ * {@link selectRichestTokenAccount} — the same rule every balance *read* in
+ * this adapter uses, so the account a UI reports and the account a transfer
+ * names are never different accounts.
+ *
+ * Classic SPL Token only: the ATA is derived under `TOKEN_PROGRAM_ID`, matching
+ * the `tokenProgram` both handlers pass, even though the program's
+ * `TokenInterface` would also accept Token-2022.
+ *
+ * @param owner - Wallet that owns the account and pays rent for any creation.
+ * @throws UpshiftSDKError when a candidate account's balance cannot be read
+ *   (propagated from the shared selector).
+ */
+async function resolveUserTokenAccount({ connection, owner, mint, }) {
+    const existing = await connection.getParsedTokenAccountsByOwner(owner, {
+        mint,
+    });
+    const richest = (0, utils_1.selectRichestTokenAccount)(existing.value);
+    if (richest)
+        return {
+            address: richest.pubkey,
+            balance: richest.amount,
+            frozen: richest.frozen,
+        };
+    // Off-curve allowed: a multisig vault holds and signs as a PDA.
+    const ata = await (0, spl_token_1.getAssociatedTokenAddress)(mint, owner, true);
+    return {
+        address: ata,
+        balance: BigInt(0),
+        frozen: false,
+        createIx: (0, spl_token_1.createAssociatedTokenAccountIdempotentInstruction)(owner, // payer
+        ata, // associated token account
+        owner, // owner
+        mint),
+    };
+}
+//# sourceMappingURL=token-reads.js.map

package/lib/adapters/solana/types.d.ts

@@ -0,0 +1,325 @@
+import type { AnchorProvider, BN } from '@coral-xyz/anchor';
+import type { Connection, PublicKey } from '@solana/web3.js';
+export type ISolanaRpcEndpoint = `https://${string}`;
+export type ISolanaNetwork = 'devnet' | 'mainnet-beta' | 'testnet' | 'localnet';
+export interface ISolanaConnectionOptions {
+    endpoint?: ISolanaRpcEndpoint;
+    connection?: Connection;
+    provider?: AnchorProvider;
+    network?: ISolanaNetwork;
+}
+export interface ISolanaVaultState {
+    operator: PublicKey | null;
+    admin: PublicKey | null;
+    shareMint: PublicKey | null;
+    depositMint: PublicKey | null;
+    feeRecipient: PublicKey | null;
+    withdrawalFee: number | null;
+    /**
+     * On-vault reserve (raw u64 base units). Sum with `deployedAum` for total
+     * assets. Anchor decodes u64 as `BN`, never `number` — convert with
+     * `BigInt(localAum.toString())`, not `Number(...)`, to avoid precision loss.
+     */
+    localAum: BN | null;
+    /** Operator-deployed AUM (raw u64 base units, decoded by Anchor as `BN`). */
+    deployedAum: BN | null;
+    /**
+     * Virtual-share offset the program prices with (a power of ten). Absent on
+     * builds that predate it, and `0` on vaults created before it; read it
+     * through `resolveShareOffset`, which maps both to the default.
+     */
+    shareOffset?: BN | null;
+    aumIncreaseLimit: number | null;
+    aumDecreaseLimit: number | null;
+    pdaBump: number[] | null;
+    vaultVersion: number[] | null;
+    paused: boolean | null;
+    /**
+     * The only key the vault accepts a redeem from, or the default (all-zero)
+     * public key when no withdrawal queue is attached. When set it is this
+     * vault's withdrawal-queue PDA: a direct holder redeem is refused with
+     * `WithdrawalQueueRequired` (6021), and holders exit through the queue
+     * instead. Vaults created before the queue existed read the default key.
+     */
+    withdrawalQueueAuthority: PublicKey | null;
+    /**
+     * Number of registered operator subaccounts. Non-zero means operator
+     * transfers must go to a registered subaccount; `0` on vaults created before
+     * subaccounts existed, and on every mainnet vault today.
+     */
+    subaccountCount: BN | null;
+    /**
+     * Raw deposit-mint units taken out to subaccounts and not yet returned,
+     * across all of them. Distinct from `deployedAum`, which the operator marks
+     * without moving tokens. Informational: nothing on-chain trusts it.
+     */
+    deployedPrincipal: BN | null;
+}
+/**
+ * A vault's withdrawal queue account (`WithdrawalQueue` in the
+ * august_withdrawal_queue program), as Anchor decodes it.
+ *
+ * One per vault, at the PDA `["withdrawal_queue", vault_state]`. Integer fields
+ * are `BN`s in raw on-chain units; times are in seconds.
+ */
+export interface ISolanaWithdrawalQueueState {
+    /** The vault this queue serves. */
+    vaultState: PublicKey;
+    /** The vault's deposit mint, copied at initialization. */
+    depositMint: PublicKey;
+    /** The vault's share mint, copied at initialization. */
+    shareMint: PublicKey;
+    /** The queue's share escrow: holds every pending request's shares. */
+    escrowShares: PublicKey;
+    /**
+     * The queue's deposit-mint escrow. Transit only: a payout passes through it
+     * within the finalizing transaction, so it normally holds nothing.
+     */
+    escrowAssets: PublicKey;
+    /**
+     * Seconds between a request and its eligibility. Stamped on each request when
+     * it is created, so a change applies to later requests only.
+     */
+    cooldownSeconds: BN;
+    /**
+     * Seconds after scheduled eligibility that a request may still be finalized,
+     * or `0` for no expiry. Stamped on each request when it is created.
+     */
+    fulfillmentWindowSeconds: BN;
+    /** Queue-wide counter; the last value stamped on a request (the first is 1). */
+    sequence: BN;
+    /** Number of live (unfinalized, uncancelled) requests. */
+    pendingRequests: BN;
+    /** Raw shares escrowed across all live requests. */
+    pendingShares: BN;
+    /** Canonical bump of the queue PDA. */
+    bump: number;
+}
+/**
+ * One withdrawal request (`WithdrawalRequest` in the august_withdrawal_queue
+ * program), as Anchor decodes it.
+ *
+ * At the PDA `["withdrawal_request", queue, owner, request_id as u64 LE]`. The
+ * account exists while the request is pending and is closed when it is
+ * finalized or cancelled. Integer fields are `BN`s; times are Unix seconds.
+ */
+export interface ISolanaWithdrawalRequestState {
+    /** The queue holding this request's shares. */
+    queue: PublicKey;
+    /** Who requested; may cancel, and may always finalize. */
+    owner: PublicKey;
+    /** Deposit-mint token account the payout goes to. */
+    recipientTokenAccount: PublicKey;
+    /**
+     * Who may finalize besides the owner, or the default (all-zero) public key
+     * for anyone.
+     */
+    finalizer: PublicKey;
+    /** Raw shares escrowed for this request. */
+    shares: BN;
+    /** Owner-chosen id, unique per owner while the request exists. */
+    requestId: BN;
+    /**
+     * Queue-wide stamp given at creation. Instructions that target the request
+     * pass it as `expected_sequence`, so a delayed call cannot land on a
+     * recreated request with the same id.
+     */
+    sequence: BN;
+    /** When the request was created. */
+    requestedAt: BN;
+    /** `requestedAt + cooldown` at creation. Never changes. */
+    scheduledEligibleAt: BN;
+    /**
+     * When finalization may begin. Equals `scheduledEligibleAt` unless an admin
+     * or operator expedited the request, which only ever moves it earlier.
+     */
+    eligibleAt: BN;
+    /**
+     * When the request stops being finalizable (the instant itself counts as
+     * expired), or `0` for never. An expired request can only be cancelled.
+     */
+    expiresAt: BN;
+    /** Bump of the request PDA. */
+    bump: number;
+    /**
+     * The owner's floor on the net payout, in raw deposit-mint units; `0` for
+     * none. A claim that would pay less is refused with `PayoutBelowFloor`.
+     */
+    minAssetsOut: BN;
+}
+export interface ISolanaToken {
+    address: string;
+    symbol: any;
+    decimals: number;
+    name: any;
+    image: any;
+    program: any;
+    mintAuthority: any;
+    freezeAuthority: any;
+    supply: string;
+    shareMintAddress: string;
+}
+export interface ISolanaVaultConfig {
+    programId: string;
+    vaultState: string;
+    shareMint: string;
+    vaultTokenAta: string;
+    depositMint: string;
+    network: ISolanaNetwork;
+}
+export interface ISolanaDepositResult {
+    success: boolean;
+    signature?: string;
+    sharesMinted?: number;
+    error?: string;
+}
+export interface ISolanaWithdrawResult {
+    success: boolean;
+    signature?: string;
+    tokensWithdrawn?: number;
+    error?: string;
+}
+export interface ISolanaVaultStats {
+    totalAssets: number;
+    totalShares: number;
+    isPaused: boolean;
+    withdrawalFee: number;
+    admin: string;
+    operator: string;
+    feeRecipient: string;
+    lastUpdated: Date;
+}
+/**
+ * Slippage protection for {@link SolanaAdapter.vaultDeposit}.
+ *
+ * The SDK quotes the shares a deposit should mint from the vault's current
+ * state and passes a floor to the program's `deposit_checked` instruction,
+ * which reverts with `SlippageExceeded` if the share price moves past it
+ * before execution.
+ */
+export interface ISolanaDepositOptions {
+    /**
+     * Tolerance below the quoted shares, in basis points (`0` to `10000`).
+     * `0` demands the quote exactly. Ignored when `minSharesOut` is given.
+     * @defaultValue 50 (0.5%)
+     */
+    slippageBps?: number;
+    /**
+     * Explicit floor in raw share units, passed to `deposit_checked` as is.
+     * Skips the quote and the single snapshot read it needs. `0n` restores the
+     * unguarded behaviour of the plain `deposit` instruction.
+     *
+     * When the handler's `idl` predates `deposit_checked`, a non-zero floor or
+     * any `slippageBps` throws {@link UpshiftValidationError} instead of being
+     * silently dropped; with neither, the plain `deposit` is sent.
+     *
+     * Must be a `bigint` in `0 .. 2^64-1`; anything else throws
+     * {@link UpshiftValidationError} before the transaction is built.
+     */
+    minSharesOut?: bigint;
+}
+/**
+ * Slippage protection for {@link SolanaAdapter.vaultRedeem}.
+ *
+ * The floor is measured **net of the withdrawal fee**, i.e. on what the wallet
+ * actually receives, matching the program's `redeem_checked`.
+ */
+export interface ISolanaRedeemOptions {
+    /**
+     * Tolerance below the quoted net payout, in basis points (`0` to `10000`).
+     * `0` demands the quote exactly. Ignored when `minAssetsOut` is given.
+     * @defaultValue 50 (0.5%)
+     */
+    slippageBps?: number;
+    /**
+     * Explicit floor in raw deposit-mint units, net of the withdrawal fee,
+     * passed to `redeem_checked` as is. Skips the quote. `0n` restores the
+     * unguarded behaviour of the plain `redeem` instruction.
+     *
+     * When the handler's `idl` predates `redeem_checked`, a non-zero floor or
+     * any `slippageBps` throws {@link UpshiftValidationError} instead of being
+     * silently dropped; with neither, the plain `redeem` is sent.
+     */
+    minAssetsOut?: bigint;
+    /**
+     * Claim this withdrawal request instead of redeeming instantly: the request
+     * account's address, as `id` on the entries `getVaultAvailableRedemptions`
+     * returns. Its shares, recipient and vault come from the request, so the
+     * `redeemShares` and `vaultAddress` arguments are ignored. The queue pays
+     * at the share price of the moment it settles, held to the floor the request
+     * was made with, so `slippageBps` and `minAssetsOut` must not be set
+     * alongside it.
+     *
+     * Required on a vault with a withdrawal queue attached, which refuses a
+     * direct redeem. See {@link SolanaAdapter.vaultRequestRedeem}.
+     */
+    request?: PublicKey | string;
+}
+/**
+ * Input to {@link SolanaAdapter.vaultRequestRedeem}.
+ */
+export interface ISolanaRequestRedeemParams {
+    /** The vault's `VaultState` account address. */
+    vault: PublicKey | string;
+    /** The holder, who signs, escrows the shares and pays rent for the request. */
+    wallet: PublicKey | string;
+    /** Shares to escrow: `bigint` in raw share units, or `number` as a UI amount. */
+    amount: number | bigint;
+    /**
+     * Wallet to pay when the request is claimed; its deposit-token account is
+     * created in the same transaction if it has none, at the holder's expense.
+     * Defaults to the holder.
+     */
+    recipient?: PublicKey | string;
+    /**
+     * The one key besides the holder that may claim the request, e.g. a keeper.
+     * Defaults to anyone, which is what lets a keeper settle requests for
+     * holders who do not come back.
+     */
+    finalizer?: PublicKey | string;
+    /**
+     * The request's id, unique per holder while it is pending. Defaults to a
+     * random `u64`; pass one only to choose it yourself.
+     */
+    requestId?: bigint;
+    /**
+     * Tolerance below the quoted net payout, in basis points (`0` to `10000`).
+     * The floor is fixed now and checked when the request is claimed, so it
+     * guards against a fee rise or an AUM mark-down in between; yield earned in
+     * the meantime only raises the payout. Ignored when `minAssetsOut` is given.
+     * @defaultValue 50 (0.5%)
+     */
+    slippageBps?: number;
+    /**
+     * Explicit floor on the net payout, in raw deposit-mint units, stored on the
+     * request as is. Skips the quote. `0n` means no floor: the claim pays
+     * whatever the shares are worth when it lands.
+     *
+     * Must be a `bigint` in `0 .. 2^64-1`; anything else throws
+     * {@link UpshiftValidationError} before the transaction is built.
+     */
+    minAssetsOut?: bigint;
+}
+/**
+ * What {@link SolanaAdapter.vaultRequestRedeem} returns.
+ */
+export interface ISolanaRequestRedeemResult {
+    /** The confirmed transaction's signature. */
+    signature: string;
+    /**
+     * The new request account's address: pass it as `request` to claim or
+     * cancel. `getVaultAvailableRedemptions` lists it as `id`.
+     */
+    request: string;
+    /** The request id, as a decimal string (a `u64`). */
+    requestId: string;
+}
+/**
+ * Input to {@link SolanaAdapter.vaultCancelRedeemRequest}.
+ */
+export interface ISolanaCancelRedeemRequestParams {
+    /** The holder who made the request; only they may cancel it. */
+    wallet: PublicKey | string;
+    /** The request account's address, as returned by `vaultRequestRedeem`. */
+    request: PublicKey | string;
+}

package/lib/adapters/solana/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map