@upshiftfinance/sdk 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,372 @@
+/**
+ * Solana Adapter for Upshift SDK
+ *
+ * @module SolanaAdapter
+ */
+import * as SolanaConstants from './constants';
+import * as SolanaGetters from './getters';
+import * as SolanaActions from './vault.actions';
+import type { AnchorProvider, web3 } from '@coral-xyz/anchor';
+import { type Commitment, Connection, PublicKey, type Transaction } from '@solana/web3.js';
+import type { ISolanaCancelRedeemRequestParams, ISolanaDepositOptions, ISolanaNetwork, ISolanaRedeemOptions, ISolanaRequestRedeemParams, ISolanaRpcEndpoint } from './types';
+import type { SendTransactionOptions } from '@solana/wallet-adapter-base';
+export declare const Solana: {
+    utils: {
+        getExplorerLink: ({ signature, type, network, }: {
+            signature: string;
+            type: "tx" | "address" | "token";
+        } & import("./types").ISolanaConnectionOptions) => string;
+        isSolanaAddress: typeof import("./utils").isSolanaAddress;
+        isSolana: (signature: string) => boolean;
+        getProgram: ({ provider, idl, programId, network, }: {
+            idl?: any;
+            programId?: string;
+        } & import("./types").ISolanaConnectionOptions) => import("@coral-xyz/anchor").Program<any>;
+        getProvider: ({ connection, publicKey, signTransaction, }: {
+            publicKey: PublicKey;
+            signTransaction: (<T extends Transaction | web3.VersionedTransaction>(transaction: T) => Promise<T>) | undefined;
+        } & import("./types").ISolanaConnectionOptions) => import("./confirm").BlockhashConfirmingProvider;
+        getReadOnlyProvider: ({ connection }: import("./types").ISolanaConnectionOptions) => AnchorProvider;
+        deriveShareMintPda: (vaultProgramId: PublicKey | string) => web3.PublicKey;
+        deriveVaultStatePda: (vaultProgramId: PublicKey | string) => web3.PublicKey;
+        deriveVaultTokenAtaPda: (vaultProgramId: PublicKey | string, depositMint: PublicKey, vaultVersion?: number) => web3.PublicKey;
+        getVaultState: ({ provider, connection, vaultProgramId, vaultAddress, idl, }: {
+            vaultProgramId: PublicKey | string;
+            vaultAddress?: PublicKey | string;
+            idl: any;
+        } & import("./types").ISolanaConnectionOptions) => Promise<{
+            vaultState: unknown | null;
+            depositMintDecimals: number | null;
+        }>;
+        getVaultStateReadOnly: ({ vaultProgramId, vaultAddress, connection, idl, fresh, }: {
+            vaultProgramId: PublicKey | string;
+            vaultAddress?: PublicKey | string;
+            idl: any;
+            fresh?: boolean;
+        } & import("./types").ISolanaConnectionOptions) => Promise<{
+            vaultState: import("./types").ISolanaVaultState | null;
+            depositMintDecimals: number | null;
+        }>;
+        getToken: ({ mintAddress, endpoint, connection, }: {
+            mintAddress: string | PublicKey;
+        } & import("./types").ISolanaConnectionOptions) => Promise<{
+            address: string;
+            symbol: string;
+            decimals: number;
+            name: string;
+            image: string;
+        } | null>;
+        getTokenSymbol: ({ endpoint, mintAddress, }: {
+            mintAddress: string | PublicKey;
+        } & import("./types").ISolanaConnectionOptions) => Promise<string | null>;
+        fetchUserTokenBalance: ({ connection, publicKey, depositMint, }: {
+            publicKey: PublicKey | string;
+            depositMint?: PublicKey | string;
+        } & import("./types").ISolanaConnectionOptions) => Promise<string>;
+        fetchUserShareBalance: ({ connection, publicKey, shareMint, }: {
+            publicKey: PublicKey | string;
+            shareMint?: PublicKey | string;
+        } & import("./types").ISolanaConnectionOptions) => Promise<number>;
+        fetchUserShareBalanceRaw: ({ connection, publicKey, shareMint, }: {
+            publicKey: PublicKey | string;
+            shareMint?: PublicKey | string;
+        } & import("./types").ISolanaConnectionOptions) => Promise<{
+            amount: string;
+            decimals: number | null;
+        }>;
+        getBestRpcEndpoint: ({ endpoint, network, connection, }: import("./types").ISolanaConnectionOptions) => Promise<"http://127.0.0.1:8899" | `https://${string}`>;
+        fallbackDecimals: number;
+        fallbackNetwork: import("../..").ISolanaNetwork;
+        programIds: {
+            devnet: {
+                vault: string;
+                withdrawalQueue: string;
+            };
+            "mainnet-beta": {
+                vault: string;
+                withdrawalQueue: string;
+            };
+            localnet: {
+                vault: string;
+                withdrawalQueue: string;
+            };
+        };
+        getVaultMints: ({ vaultProgramId, vaultAddress, connection, idl, }: {
+            vaultProgramId: PublicKey | string;
+            vaultAddress?: PublicKey | string;
+            idl: any;
+        } & import("./types").ISolanaConnectionOptions) => Promise<{
+            depositMint: string;
+            shareMint: string;
+            vaultVersion: number | undefined;
+        }>;
+        resolveProgramId: (vaultAddress: string, solanaMetadata?: {
+            program_id?: string;
+        } | null) => string;
+    };
+    constants: typeof SolanaConstants;
+    actions: typeof SolanaActions;
+    getters: typeof SolanaGetters;
+};
+/**
+ * Solana Adapter for Upshift SDK
+ *
+ * @example
+ * To access the Solana adapter instance
+ * ```
+ * const sdk = new UpshiftSDK()
+ * sdk.solana.getVaultState()
+ * ```
+ */
+declare class SolanaAdapter {
+    private _endpoint;
+    private _network;
+    private _connection;
+    private _provider;
+    /**
+     * @param commitment - Commitment for every read this adapter makes *and* for
+     *   the confirmation of every write, so the two always describe the same
+     *   chain state — the vault handlers take it from this same `Connection`.
+     *
+     *   Defaults to `'finalized'`, which is what this adapter has always used in
+     *   practice: it previously passed no commitment at all, so both reads and
+     *   confirmations fell through to the RPC's own `'finalized'` default. The
+     *   default is stated explicitly now rather than inherited, but it is
+     *   unchanged.
+     *
+     *   Pass `'confirmed'` for a markedly faster round trip — seconds rather
+     *   than tens of seconds — accepting that the state you act on can still, in
+     *   principle, be rolled back. Also settable as the `commitment` field of
+     *   the `solana` config passed to `UpshiftSDK`.
+     */
+    constructor(endpoint: ISolanaRpcEndpoint, network?: ISolanaNetwork, commitment?: Commitment);
+    get endpoint(): `https://${string}`;
+    get network(): ISolanaNetwork;
+    get connection(): web3.Connection;
+    get provider(): AnchorProvider;
+    setWalletProvider(_publicKey: PublicKey | string, signTransaction: (<T extends Transaction | web3.VersionedTransaction>(transaction: T) => Promise<T>) | undefined): void;
+    /**
+     * Build an Anchor `Program` bound to this adapter's provider and network.
+     *
+     * The program id is resolved as: explicit `programId` → the `address` carried
+     * by a custom `programIdl` → the canonical deployment for this adapter's
+     * network. A copy of the SDK's bundled `vaultIdl` defers to the network
+     * default (its embedded `address` is a build stamp, not network-aware), so
+     * forwarding it on devnet never silently targets the mainnet program.
+     *
+     * An IDL whose `metadata.name` is `august_withdrawal_queue` resolves against
+     * the withdrawal queue program's network default instead of the vault's.
+     *
+     * @param programIdl - Anchor IDL to bind. Defaults to the SDK's bundled
+     *   `august_vault` IDL. A custom IDL's `address` is honoured when it differs
+     *   from the program's canonical id (the build stamp every bundled copy of
+     *   the vault or queue IDL carries).
+     * @param programId - Base58 program id that overrides both the IDL's address
+     *   and the network default. Use this to target a non-canonical deployment.
+     * @returns An Anchor `Program` for the resolved program id. No RPC is made —
+     *   construction is offline.
+     * @throws {@link UpshiftValidationError} if no program id can be resolved
+     *   because the program has no canonical deployment on this adapter's network
+     *   (neither program on `testnet`) and neither `programId` nor a custom IDL
+     *   address was supplied.
+     *
+     * @example
+     * ```ts
+     * // canonical program on the adapter's network
+     * const program = sdk.solana.getProgram();
+     *
+     * // a different deployment, same interface
+     * const legacy = sdk.solana.getProgram(vaultIdl, '7B8n9vL51b6ibqRAd1adZsi3x3kxtq5NZaondh22Vkyq');
+     * ```
+     */
+    getProgram(programIdl?: any, programId?: string): import("@coral-xyz/anchor").Program<any>;
+    getVaultState(vaultProgramId: PublicKey | string, idl: any, vaultAddress?: PublicKey | string): Promise<{
+        vaultState: unknown | null;
+        depositMintDecimals: number | null;
+    }>;
+    getVaultStateReadOnly(vaultProgramId: PublicKey | string, idl: any, vaultAddress?: PublicKey | string): Promise<{
+        vaultState: import("./types").ISolanaVaultState | null;
+        depositMintDecimals: number | null;
+    }>;
+    getToken(mintAddress: string | PublicKey): Promise<{
+        address: string;
+        symbol: string;
+        decimals: number;
+        name: string;
+        image: string;
+    }>;
+    getTokenSymbol(mintAddress: string | PublicKey): Promise<string>;
+    fetchUserTokenBalance(publicKey: PublicKey | string, depositMint: PublicKey | string): Promise<string>;
+    fetchUserShareBalance(publicKey: PublicKey | string, shareMint: PublicKey | string): Promise<number>;
+    /**
+     * BigInt-safe variant of {@link fetchUserShareBalance}. Returns the raw u64
+     * `amount` (as a base-units string) plus the mint's `decimals` (or `null`
+     * when the scale can't be determined — see Returns), so the caller can
+     * produce a correct `INormalizedNumber` without losing precision.
+     *
+     * Prefer this anywhere the result feeds BigInt math — positions, max-
+     * actions, redemption sizing, allowance checks. `fetchUserShareBalance`
+     * returns a JS-number `uiAmount` which silently encodes against 18 decimals
+     * when passed through `toNormalizedBn(value)` without an explicit decimals
+     * argument; that's exactly how the jitoSOL "missing position" regression
+     * manifested.
+     *
+     * RPC cost: 1 `getParsedTokenAccountsByOwner` call. Worst case ~150ms on a
+     * healthy mainnet endpoint.
+     *
+     * @param publicKey   Wallet owner (PublicKey or base58 string).
+     * @param shareMint   The vault's share-token mint (PublicKey or base58).
+     * @returns
+     *   `{ amount, decimals }`. Three observable shapes:
+     *   - `{ amount: '<u64>', decimals: <number> }` — token account exists.
+     *   - `{ amount: '0', decimals: null }` — no token account for this mint
+     *     under this wallet, OR `tokenAmount` was missing from the response,
+     *     OR `publicKey`/`shareMint` was not supplied. Distinguishable from a
+     *     genuine zero-balance account (`decimals` would be set there).
+     *   - `{ amount: '0', decimals: null }` — RPC threw (error is logged).
+     *
+     *   `decimals === null` means "we could not determine the scale" — callers
+     *   that need an `INormalizedNumber` must fall back to a known decimals
+     *   value (typically the deposit mint's decimals from backend metadata)
+     *   before normalizing. Never throws.
+     */
+    fetchUserShareBalanceRaw(publicKey: PublicKey | string, shareMint: PublicKey | string): Promise<{
+        amount: string;
+        decimals: number | null;
+    }>;
+    /**
+     * Deposit funds into a Solana Upshift vault.
+     * @param depositAmount  `bigint` (raw on-chain units) or `number` (UI amount).
+     * @param sendTransaction - **Ignored; scheduled for removal in the next major release.**
+     *   Share-account creation is now prepended to the deposit instruction, so
+     *   the SDK sends no second transaction and never invokes this callback —
+     *   signing goes through the provider's wallet.
+     *
+     *   **Pass `undefined` here; do not delete the argument.** It sits *before*
+     *   `vaultAddress`, so removing it shifts your vault address into this slot
+     *   and leaves `vaultAddress` undefined — which silently falls back to the
+     *   legacy single-vault PDA derivation and targets a different vault.
+     * @param options - Slippage protection. By default the SDK quotes the shares this deposit should mint
+     *   from the vault's current state and passes that quote, lowered by 50 bps,
+     *   as the floor to the program's checked instruction. See {@link ISolanaDepositOptions}.
+     */
+    vaultDeposit(vaultProgramId: PublicKey | string, idl: any, publicKey: PublicKey | string, depositAmount: number | bigint, sendTransaction?: (transaction: Transaction | web3.VersionedTransaction, connection: Connection, options?: SendTransactionOptions) => Promise<web3.TransactionSignature>, vaultAddress?: PublicKey | string, options?: ISolanaDepositOptions): Promise<any>;
+    /**
+     * Redeem vault shares from a Solana Upshift vault.
+     * @param redeemShares  `bigint` (raw share units) or `number` (UI amount).
+     * @param sendTransaction - **Ignored; scheduled for removal in the next major release.**
+     *   Payout- and fee-recipient-account creation is now prepended to the redeem
+     *   instruction, so the SDK sends no second transaction and never invokes
+     *   this callback — signing goes through the provider's wallet.
+     *
+     *   **Pass `undefined` here; do not delete the argument.** It sits *before*
+     *   `vaultAddress`, so removing it shifts your vault address into this slot
+     *   and leaves `vaultAddress` undefined — which silently falls back to the
+     *   legacy single-vault PDA derivation and targets a different vault.
+     * @param options - Slippage protection. By default the SDK quotes the net payout these shares should return
+     *   from the vault's current state and passes that quote, lowered by 50 bps,
+     *   as the floor to the program's checked instruction. See {@link ISolanaRedeemOptions}.
+     *
+     *   **On a vault with a withdrawal queue**, holders cannot redeem directly:
+     *   request with {@link SolanaAdapter.vaultRequestRedeem}, then claim here with
+     *   `options.request` once the cooldown has run. The claim settles at the share
+     *   price of that moment, net of the withdrawal fee, held to the floor set at
+     *   request time, and pays the request's recipient; `redeemShares` and
+     *   `vaultAddress` are then ignored, and `slippageBps` / `minAssetsOut` must
+     *   be left unset. Without `request`, a
+     *   queued vault is refused before signing.
+     * @returns The confirmed transaction's signature.
+     * @throws {@link UpshiftValidationError} for bad input, for a queued vault
+     *   without `options.request`, or for a request the wallet cannot claim yet.
+     * @example
+     * ```ts
+     * // A vault with a withdrawal queue: claim a ready request.
+     * const { pendingRedemptions } = await sdk.getVaultAvailableRedemptions({ vault, wallet });
+     * await sdk.solana.vaultRedeem(programId, vaultIdl, wallet, 0n, undefined, undefined, {
+     *   request: pendingRedemptions[0].id,
+     * });
+     * ```
+     */
+    vaultRedeem(vaultProgramId: PublicKey | string, idl: any, publicKey: PublicKey | string, redeemShares: number | bigint, sendTransaction?: (transaction: Transaction | web3.VersionedTransaction, connection: Connection, options?: SendTransactionOptions) => Promise<web3.TransactionSignature>, vaultAddress?: PublicKey | string, options?: ISolanaRedeemOptions): Promise<any>;
+    /**
+     * Request a withdrawal from a Solana vault that has a withdrawal queue.
+     *
+     * With a queue attached, a vault's shares cannot be redeemed directly: the
+     * holder escrows them in a request, waits out the queue's cooldown, then
+     * claims with {@link SolanaAdapter.vaultRedeem} and `options.request`, or
+     * anyone the request permits (a keeper, by default) claims for them. The
+     * payout is priced when the request is claimed, not now, but never below the
+     * floor set here: by default the current net quote lowered by 50 bps, so a
+     * fee rise or mark-down in between makes the claim fail rather than pay
+     * less. A pending request
+     * can be cancelled at any time with
+     * {@link SolanaAdapter.vaultCancelRedeemRequest}, which returns the shares.
+     *
+     * Signs through the provider's wallet and submits one transaction, which
+     * also creates the recipient's deposit-token account when it has none. The
+     * holder pays the request account's rent, refunded when it is claimed or
+     * cancelled, plus rent for any account created. Use
+     * `getVaultAvailableRedemptions` to list requests and see when they can be
+     * claimed.
+     *
+     * RPC: three to four reads, then the send.
+     *
+     * @param params - Vault, wallet, shares, and optional recipient, finalizer,
+     *   request id and floor. See {@link ISolanaRequestRedeemParams}.
+     * @returns The signature, the request's address (pass it as `request` to
+     *   claim or cancel) and its id.
+     * @throws {@link UpshiftValidationError} for bad input, a vault without an
+     *   attached queue, a frozen account or too few shares, before signing.
+     * @throws {@link UpshiftSDKError} when the transaction fails.
+     * @example
+     * ```ts
+     * const { request } = await sdk.solana.vaultRequestRedeem({
+     *   vault: vaultStateAddress,
+     *   wallet: wallet.publicKey,
+     *   amount: 10, // shares, UI units
+     * });
+     * // ...once the cooldown has run:
+     * await sdk.solana.vaultRedeem(programId, vaultIdl, wallet.publicKey, 0n, undefined, undefined, { request });
+     * ```
+     */
+    vaultRequestRedeem(params: ISolanaRequestRedeemParams): Promise<import("./types").ISolanaRequestRedeemResult>;
+    /**
+     * Cancel a pending withdrawal request, returning its shares to the holder.
+     *
+     * Allowed at any time while the request exists: during the cooldown, after
+     * it, past the fulfillment window, and while the vault is paused. Only the
+     * holder who made the request may cancel it. Signs through the provider's
+     * wallet; the request's rent is refunded to the holder.
+     *
+     * RPC: three reads, then the send.
+     *
+     * @param params - The holder and the request address. See
+     *   {@link ISolanaCancelRedeemRequestParams}.
+     * @returns The confirmed transaction's signature.
+     * @throws {@link UpshiftValidationError} for a missing request, or one this
+     *   wallet did not make, before signing.
+     * @throws {@link UpshiftSDKError} when the transaction fails.
+     * @example
+     * ```ts
+     * await sdk.solana.vaultCancelRedeemRequest({ wallet: wallet.publicKey, request });
+     * ```
+     */
+    vaultCancelRedeemRequest(params: ISolanaCancelRedeemRequestParams): Promise<string>;
+    /**
+     * Canonical program id for a program type on this adapter's network.
+     *
+     * @param type - Program to look up: `'vault'` (august_vault) or
+     *   `'withdrawalQueue'` (august_withdrawal_queue).
+     * @returns The base58 program id.
+     * @throws {@link UpshiftValidationError} if `type` is not one of the two
+     *   program types, or the program is not deployed on this adapter's network
+     *   (neither program on `testnet`).
+     * @example
+     * ```ts
+     * const queueProgram = adapter.getProgramId('withdrawalQueue');
+     * ```
+     */
+    getProgramId(type: 'vault' | 'withdrawalQueue'): string;
+}
+export type { ISolanaCancelRedeemRequestParams, ISolanaDepositOptions, ISolanaRedeemOptions, ISolanaRequestRedeemParams, ISolanaRequestRedeemResult, } from './types';
+export default SolanaAdapter;