@upshiftfinance/sdk 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,229 @@
+import { AnchorProvider, BN, Program, type web3 } from '@coral-xyz/anchor';
+import { PublicKey, type ParsedAccountData, type Transaction } from '@solana/web3.js';
+import type { ISolanaConnectionOptions, ISolanaVaultState } from './types';
+import { BlockhashConfirmingProvider } from './confirm';
+import type { ISolanaProgramIds } from './constants';
+declare function getExplorerLink({ signature, type, network, }: {
+    signature: string;
+    type: 'tx' | 'address' | 'token';
+} & ISolanaConnectionOptions): string;
+import { isSolanaAddress } from '../../core/helpers/chain-address';
+export { isSolanaAddress };
+declare function isSolana(signature: string): boolean;
+/**
+ * Throws unless `type` is a program type `programNames` maps. Checked at
+ * runtime for untyped callers: a typo would otherwise read as an undeployed
+ * program, and a prototype key like `toString` as a program id.
+ * @internal
+ */
+export declare function assertSolanaProgramType(type: unknown): asserts type is keyof ISolanaProgramIds;
+/**
+ * Error text for `program` having no canonical deployment on `network`, naming
+ * the networks it is deployed on.
+ * @internal
+ */
+export declare function undeployedProgramMessage(program: keyof ISolanaProgramIds, network: string): string;
+declare function getProgram({ provider, idl, programId, network, }: {
+    idl?: any;
+    programId?: string;
+} & ISolanaConnectionOptions): Program<any>;
+declare function getBestRpcEndpoint({ endpoint, network, connection, }: ISolanaConnectionOptions): Promise<"http://127.0.0.1:8899" | `https://${string}`>;
+declare function getProvider({ connection, publicKey, signTransaction, }: {
+    publicKey: PublicKey;
+    signTransaction: (<T extends Transaction | web3.VersionedTransaction>(transaction: T) => Promise<T>) | undefined;
+} & ISolanaConnectionOptions): BlockhashConfirmingProvider;
+declare function getReadOnlyProvider({ connection }: ISolanaConnectionOptions): AnchorProvider;
+declare function deriveVaultStatePda(vaultProgramId: PublicKey | string): web3.PublicKey;
+declare function deriveShareMintPda(vaultProgramId: PublicKey | string): web3.PublicKey;
+declare function deriveVaultTokenAtaPda(vaultProgramId: PublicKey | string, depositMint: PublicKey, vaultVersion?: number): web3.PublicKey;
+declare function getVaultState({ provider, connection, vaultProgramId, vaultAddress, idl, }: {
+    vaultProgramId: PublicKey | string;
+    vaultAddress?: PublicKey | string;
+    idl: any;
+} & ISolanaConnectionOptions): Promise<{
+    vaultState: unknown | null;
+    depositMintDecimals: number | null;
+}>;
+/**
+ * Read-only version of `getVaultState` that works without a wallet connection.
+ *
+ * Makes one `getAccountInfo` for the vault state PDA and decodes the bytes
+ * with the program's account coder (no second fetch through
+ * `program.account.vaultState.fetch`), plus one `getParsedAccountInfo` for the
+ * deposit mint's decimals. Worst case: 2 RPC calls per cache miss; a hit costs
+ * none. The decoded state is cached for {@link VAULT_STATE_CACHE_TTL_MS}.
+ *
+ * Resolves `{ vaultState: null, depositMintDecimals: null }` — and caches
+ * nothing — when the account is missing, the RPC fails, or the bytes do not
+ * decode. Callers (`getSolanaVault`) treat a `null` state as "on-chain data
+ * unavailable" and fall back to backend data.
+ *
+ * Served from the cache unless `fresh` is set. A fresh read skips the cached
+ * value and refreshes it, for callers comparing the vault's AUM with live data
+ * such as an operator's current portfolio.
+ */
+declare function getVaultStateReadOnly({ vaultProgramId, vaultAddress, connection, idl, fresh, }: {
+    vaultProgramId: PublicKey | string;
+    vaultAddress?: PublicKey | string;
+    idl: any;
+    fresh?: boolean;
+} & ISolanaConnectionOptions): Promise<{
+    vaultState: ISolanaVaultState | null;
+    depositMintDecimals: number | null;
+}>;
+declare function getVaultMints({ vaultProgramId, vaultAddress, connection, idl, }: {
+    vaultProgramId: PublicKey | string;
+    vaultAddress?: PublicKey | string;
+    idl: any;
+} & ISolanaConnectionOptions): Promise<{
+    depositMint: string;
+    shareMint: string;
+    vaultVersion: number | undefined;
+}>;
+declare function getToken({ mintAddress, endpoint, connection, }: {
+    mintAddress: string | PublicKey;
+} & ISolanaConnectionOptions): Promise<{
+    address: string;
+    symbol: string;
+    decimals: number;
+    name: string;
+    image: string;
+} | null>;
+declare function getTokenSymbol({ endpoint, mintAddress, }: {
+    mintAddress: string | PublicKey;
+} & ISolanaConnectionOptions): Promise<string | null>;
+/**
+ * A wallet's token account of record for one mint: the account holding the
+ * largest balance.
+ *
+ * **This is the single selection rule for the whole Solana adapter.** Reads
+ * (balances shown in a UI) and writes (the account a transfer actually names)
+ * must agree on which account represents the user, or the two describe
+ * different money: a balance read from account A while a deposit mints into
+ * account B looks, to the user, like a successful transaction that never
+ * arrived. Every reader in this file and both vault handlers call this, so the
+ * rule cannot drift.
+ *
+ * Largest-balance rather than "the first account the RPC returned":
+ * `getParsedTokenAccountsByOwner` guarantees no ordering, so taking `[0]` can
+ * select an empty leftover while the user's funds sit in a sibling account —
+ * which fails on-chain as an insufficient-funds revert *after* they sign.
+ *
+ * **Spendable accounts win over frozen ones**, regardless of balance: a token
+ * issuer can freeze an account, and neither a transfer out of nor a transfer
+ * into a frozen account can succeed. Picking the richest account outright would
+ * hand a frozen one to the program and revert with SPL `0x11` after the user
+ * signs, while a perfectly usable sibling sat next to it. When *every* account
+ * is frozen the richest frozen one is still returned, flagged — a reader should
+ * show that balance, because the user does own it, and a writer should refuse
+ * before asking for a signature.
+ *
+ * Internal to the adapter: exported for `vault.actions.ts`, deliberately not
+ * re-exported on `SolanaUtils`. It takes a raw RPC response shape, which is not
+ * a contract worth freezing on the public surface.
+ *
+ * @param accounts - The `.value` array from `getParsedTokenAccountsByOwner`.
+ * @returns The selected account with its raw balance, decimals, the RPC's own
+ *   `uiAmount`, and whether it is frozen — or `undefined` when the wallet owns
+ *   no account for the mint.
+ * @throws UpshiftSDKError when an account's balance cannot be read. An
+ *   unreadable balance is *unknown*, not zero — scoring it zero would silently
+ *   demote a funded account below a dust one and reinstate the `[0]` behaviour
+ *   this function exists to prevent.
+ */
+export declare function selectRichestTokenAccount(accounts: {
+    pubkey: PublicKey;
+    account: {
+        data: ParsedAccountData | Buffer;
+    };
+}[]): {
+    pubkey: PublicKey;
+    amount: bigint;
+    decimals: number | null;
+    uiAmount: number | null;
+    frozen: boolean;
+} | undefined;
+declare function fetchUserTokenBalance({ connection, publicKey, depositMint, }: {
+    publicKey: PublicKey | string;
+    depositMint?: PublicKey | string;
+} & ISolanaConnectionOptions): Promise<string>;
+declare function fetchUserShareBalance({ connection, publicKey, shareMint, }: {
+    publicKey: PublicKey | string;
+    shareMint?: PublicKey | string;
+} & ISolanaConnectionOptions): Promise<number>;
+/**
+ * Same on-chain lookup as `fetchUserShareBalance`, but returns the raw u64
+ * `amount` string and the mint's `decimals` — or `null` when the scale can't
+ * be determined (see Return shape) — instead of the floating-point `uiAmount`.
+ * Callers that feed the result into BigInt math (positions, redemptions,
+ * allowances) must use this — `uiAmount` is lossy and silently encodes with
+ * the wrong scale when passed back through `toNormalizedBn` without an
+ * explicit decimals argument.
+ *
+ * Return shape:
+ *   `{ amount: '<u64>', decimals: number }` — token account exists.
+ *   `{ amount: '0',     decimals: null   }` — no token account, missing
+ *      tokenAmount in the parsed response, missing args, or the RPC threw.
+ *
+ * `decimals === null` is the "scale unknown" signal — callers that need a
+ * normalized `INormalizedNumber` must substitute a known decimals value
+ * (typically the deposit mint's decimals from backend metadata) before
+ * normalizing. Never throws.
+ *
+ * RPC cost: 1 × `getParsedTokenAccountsByOwner`. Independent of how many
+ * other accounts the wallet owns (filter is mint-scoped).
+ */
+declare function fetchUserShareBalanceRaw({ connection, publicKey, shareMint, }: {
+    publicKey: PublicKey | string;
+    shareMint?: PublicKey | string;
+} & ISolanaConnectionOptions): Promise<{
+    amount: string;
+    decimals: number | null;
+}>;
+/**
+ * Resolve the on-chain program ID for a Solana vault.
+ * Prefers the explicit `program_id` from metadata; falls back to the vault address
+ * (for legacy vaults where address == program ID).
+ */
+declare function resolveProgramId(vaultAddress: string, solanaMetadata?: {
+    program_id?: string;
+} | null): string;
+/** @internal */
+export declare function uiAmountToRawBn(uiAmount: number, decimals: number): BN;
+export declare const SolanaUtils: {
+    getExplorerLink: typeof getExplorerLink;
+    isSolanaAddress: typeof isSolanaAddress;
+    isSolana: typeof isSolana;
+    getProgram: typeof getProgram;
+    getProvider: typeof getProvider;
+    getReadOnlyProvider: typeof getReadOnlyProvider;
+    deriveShareMintPda: typeof deriveShareMintPda;
+    deriveVaultStatePda: typeof deriveVaultStatePda;
+    deriveVaultTokenAtaPda: typeof deriveVaultTokenAtaPda;
+    getVaultState: typeof getVaultState;
+    getVaultStateReadOnly: typeof getVaultStateReadOnly;
+    getToken: typeof getToken;
+    getTokenSymbol: typeof getTokenSymbol;
+    fetchUserTokenBalance: typeof fetchUserTokenBalance;
+    fetchUserShareBalance: typeof fetchUserShareBalance;
+    fetchUserShareBalanceRaw: typeof fetchUserShareBalanceRaw;
+    getBestRpcEndpoint: typeof getBestRpcEndpoint;
+    fallbackDecimals: number;
+    fallbackNetwork: import("../..").ISolanaNetwork;
+    programIds: {
+        devnet: {
+            vault: string;
+            withdrawalQueue: string;
+        };
+        "mainnet-beta": {
+            vault: string;
+            withdrawalQueue: string;
+        };
+        localnet: {
+            vault: string;
+            withdrawalQueue: string;
+        };
+    };
+    getVaultMints: typeof getVaultMints;
+    resolveProgramId: typeof resolveProgramId;
+};