@upshiftfinance/sdk 0.0.0-stage → 0.1.0

package/lib/adapters/solana/utils.js

@@ -0,0 +1,773 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SolanaUtils = exports.isSolanaAddress = void 0;
+exports.assertSolanaProgramType = assertSolanaProgramType;
+exports.undeployedProgramMessage = undeployedProgramMessage;
+exports.selectRichestTokenAccount = selectRichestTokenAccount;
+exports.uiAmountToRawBn = uiAmountToRawBn;
+const anchor_1 = require("@coral-xyz/anchor");
+const web3_js_1 = require("@solana/web3.js");
+const ethers_1 = require("ethers");
+const constants_1 = require("./constants");
+const confirm_1 = require("./confirm");
+const core_1 = require("../../core");
+const cache_1 = require("../../core/cache");
+// ============================================================================
+// SOLANA UTILITIES
+// ============================================================================
+function getExplorerLink({ signature, type = 'tx', network = constants_1.fallbackNetwork, }) {
+    const baseUrl = 'https://solscan.io';
+    return `${baseUrl}/${type}/${signature}?cluster=${network}`;
+}
+// Re-exported from the core leaf so consumers in the core layer can import it
+// without taking a dependency on the Solana adapter.
+const chain_address_1 = require("../../core/helpers/chain-address");
+Object.defineProperty(exports, "isSolanaAddress", { enumerable: true, get: function () { return chain_address_1.isSolanaAddress; } });
+function isSolana(signature) {
+    if (!signature || typeof signature !== 'string')
+        return false;
+    // Check if it's an Ethereum address first
+    if ((0, ethers_1.isAddress)(signature))
+        return false;
+    // Check if it's a valid Solana address (including PDAs) — addresses are not signatures
+    if ((0, chain_address_1.isSolanaAddress)(signature))
+        return false;
+    // Check if it's a valid base58 string with correct length for Solana signatures
+    // Solana signatures are base58 encoded and typically 88 characters long
+    const base58Chars = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+    const isValidBase58 = signature
+        .split('')
+        .every((char) => base58Chars.includes(char));
+    if (!isValidBase58)
+        return false;
+    // Check length - Solana signatures are typically 88 characters
+    return (signature.length >= 80 && signature.length <= 100);
+}
+/** On-chain name (IDL `metadata.name`) of each program type. */
+const programNames = {
+    vault: 'august_vault',
+    withdrawalQueue: 'august_withdrawal_queue',
+};
+/**
+ * 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
+ */
+function assertSolanaProgramType(type) {
+    if (typeof type !== 'string' || !Object.hasOwn(programNames, type)) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', `Unknown Solana program type '${String(type)}'. Expected one of: ${Object.keys(programNames).join(', ')}.`);
+    }
+}
+/**
+ * Error text for `program` having no canonical deployment on `network`, naming
+ * the networks it is deployed on.
+ * @internal
+ */
+function undeployedProgramMessage(program, network) {
+    const deployed = Object.entries(constants_1.programIds)
+        .filter(([, ids]) => ids[program])
+        .map(([name]) => name);
+    return (`No canonical ${programNames[program]} deployment for Solana network '${network}'. ` +
+        `Deployed networks: ${deployed.join(', ')}.`);
+}
+function getProgram({ provider, idl, programId, network, }) {
+    const baseIdl = idl ?? constants_1.vaultIdl;
+    // The withdrawal queue IDL resolves through `programIds.withdrawalQueue`;
+    // anything else is treated as the vault. Recognised by name, so the queue IDL
+    // never has to be imported here (and pulled into every bundle).
+    const program = baseIdl?.metadata?.name === programNames.withdrawalQueue
+        ? 'withdrawalQueue'
+        : 'vault';
+    // Precedence: explicit `programId` → a custom IDL's `address` → the network
+    // default → the bundled IDL's embedded `address`.
+    //
+    // The custom-address check compares by VALUE, not reference. Keying off
+    // `idl === vaultIdl` broke for a structurally-identical-but-not-reference-equal
+    // copy (second bundle instance, or JSON round-tripped), silently retargeting
+    // devnet callers at mainnet. Every copy carries the same build stamp, so it
+    // still defers to the network default — but a genuinely custom IDL is honoured.
+    // A build stamp is the program's canonical id, which some network maps.
+    const isBuildStamp = Object.values(constants_1.programIds).some((ids) => ids[program] === baseIdl?.address);
+    const suppliedAddress = typeof baseIdl?.address === 'string' && !isBuildStamp
+        ? baseIdl.address
+        : undefined;
+    const explicitId = programId ?? suppliedAddress;
+    if (explicitId) {
+        return new anchor_1.Program({ ...baseIdl, address: explicitId }, provider);
+    }
+    if (network) {
+        const networkDefault = (0, constants_1.getDeployedProgramIds)(network)?.[program];
+        if (!networkDefault) {
+            throw new core_1.UpshiftValidationError('INVALID_INPUT', `${undeployedProgramMessage(program, network)} ` +
+                `Pass an explicit \`programId\` (or an IDL carrying the target \`address\`) to target a program on this network.`);
+        }
+        return new anchor_1.Program({ ...baseIdl, address: networkDefault }, provider);
+    }
+    return new anchor_1.Program(baseIdl, provider);
+}
+// ============================================================================
+// SOLANA PROVIDERS
+// ============================================================================
+async function testRpcEndpoint({ connection }) {
+    try {
+        const blockHeight = await connection.getBlockHeight();
+        return { success: true, blockHeight };
+    }
+    catch (error) {
+        return { success: false, error };
+    }
+}
+// Function to get the best available RPC endpoint
+async function getBestRpcEndpoint({ endpoint, network = constants_1.fallbackNetwork, connection, }) {
+    const primaryEndpoint = endpoint;
+    const fallbackEndpoint = constants_1.fallbackRpcEndpoints[network];
+    // Test primary endpoint first
+    const primaryTest = await testRpcEndpoint({ connection });
+    if (primaryTest.success) {
+        return primaryEndpoint;
+    }
+    // Fall back to public endpoint
+    core_1.Logger.log.warn('getBestRpcEndpoint', '⚠️ Primary RPC endpoint failed, using fallback:', fallbackEndpoint);
+    return fallbackEndpoint;
+}
+function getProvider({ connection, publicKey, signTransaction, }) {
+    if (!publicKey || !signTransaction) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', 'Wallet not connected: publicKey and signTransaction are required for write operations');
+    }
+    // Anchor's own confirmation misreports landed txs as timed out; see confirm.ts.
+    return new confirm_1.BlockhashConfirmingProvider(connection, {
+        publicKey,
+        signTransaction,
+        signAllTransactions: async (txs) => {
+            // Use Promise.all instead of await in loop
+            const signedTransactions = await Promise.all(txs.map(async (tx) => signTransaction(tx)));
+            return signedTransactions;
+        },
+    }, 
+    // Inherited from the connection, not hard-coded: a caller who configured
+    // the adapter for 'finalized' must not have writes issued through
+    // `getProgram(...).methods…rpc()` confirm at something weaker.
+    { commitment: connection.commitment ?? 'finalized' });
+}
+// Read-only provider for data fetching without wallet connection
+function getReadOnlyProvider({ connection }) {
+    // Create a dummy wallet object for read-only operations
+    const dummyWallet = {
+        publicKey: web3_js_1.PublicKey.default, // Use default public key
+        signTransaction: async (_tx) => {
+            throw new core_1.UpshiftValidationError('INVALID_INPUT', 'Cannot sign transactions with read-only provider');
+        },
+        signAllTransactions: async (_txs) => {
+            throw new core_1.UpshiftValidationError('INVALID_INPUT', 'Cannot sign transactions with read-only provider');
+        },
+    };
+    // See `getProvider` — the connection is the single source of truth for
+    // commitment, so reads through this provider match reads made directly.
+    return new anchor_1.AnchorProvider(connection, dummyWallet, {
+        commitment: connection.commitment ?? 'finalized',
+    });
+}
+// ============================================================================
+// SOLANA DERIVATIONS
+// ============================================================================
+function deriveVaultStatePda(vaultProgramId) {
+    if (!vaultProgramId)
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', 'Vault program ID missing');
+    const _vaultProgramId = new web3_js_1.PublicKey(vaultProgramId);
+    const [pda] = web3_js_1.PublicKey.findProgramAddressSync([new TextEncoder().encode('VAULT_STATE')], _vaultProgramId);
+    return pda;
+}
+function deriveShareMintPda(vaultProgramId) {
+    if (!vaultProgramId)
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', 'Vault program ID missing');
+    const _vaultProgramId = new web3_js_1.PublicKey(vaultProgramId);
+    const [pda] = web3_js_1.PublicKey.findProgramAddressSync([new TextEncoder().encode('mint')], _vaultProgramId);
+    return pda;
+}
+function deriveVaultTokenAtaPda(vaultProgramId, depositMint, vaultVersion) {
+    if (!(vaultProgramId && depositMint))
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', 'Vault program ID or deposit mint missing');
+    const _vaultProgramId = new web3_js_1.PublicKey(vaultProgramId);
+    const seeds = [
+        Buffer.from('token_vault'),
+        depositMint.toBuffer(),
+    ];
+    if (vaultVersion !== undefined) {
+        if (!Number.isInteger(vaultVersion) ||
+            vaultVersion < 0 ||
+            vaultVersion > 255) {
+            throw new core_1.UpshiftValidationError('INVALID_INPUT', `Invalid vault version ${vaultVersion}: must be an integer between 0 and 255`);
+        }
+        seeds.push(Buffer.from([vaultVersion]));
+    }
+    const [pda] = web3_js_1.PublicKey.findProgramAddressSync(seeds, _vaultProgramId);
+    return pda;
+}
+// ============================================================================
+// SOLANA VAULTS
+// ============================================================================
+/**
+ * How long a decoded vault state stays in the process cache, in milliseconds.
+ *
+ * `vaultState-*` entries carry live balances (`localAum`, `deployedAum`, fee
+ * settings), so they must expire quickly: the shared `CACHE` defaults to 24 h,
+ * which froze TVL and share price for the life of the process. 60 s bounds
+ * the staleness to one block of polling while still collapsing the burst of
+ * reads a single page render makes. Mint addresses (`vaultMints-*`) are
+ * immutable and keep the default TTL.
+ */
+const VAULT_STATE_CACHE_TTL_MS = 60_000;
+/**
+ * Cache a decoded vault state under `cacheKey` with the short
+ * {@link VAULT_STATE_CACHE_TTL_MS} TTL. Only called after a successful decode:
+ * a failed read is never cached, so the next caller retries the RPC instead
+ * of inheriting a `null` state for the TTL.
+ */
+function cacheVaultState(cacheKey, value) {
+    cache_1.CACHE.set(cacheKey, value, { ttl: VAULT_STATE_CACHE_TTL_MS });
+}
+async function getVaultState({ provider, connection, vaultProgramId, vaultAddress, idl, }) {
+    const returnObj = {
+        vaultState: null,
+        depositMintDecimals: null,
+    };
+    try {
+        const cacheKey = `vaultState-${vaultAddress || vaultProgramId}`;
+        const cachedData = await (0, core_1.getSafeCache)(cacheKey);
+        if (cachedData)
+            return cachedData;
+        if (!vaultProgramId) {
+            throw new core_1.UpshiftValidationError('INVALID_INPUT', 'Please enter a vault program ID');
+        }
+        const vaultStatePda = vaultAddress
+            ? new web3_js_1.PublicKey(vaultAddress)
+            : deriveVaultStatePda(vaultProgramId);
+        const _vaultProgramId = new web3_js_1.PublicKey(vaultProgramId);
+        const program = getProgram({
+            provider,
+            idl,
+            programId: _vaultProgramId.toBase58(),
+        });
+        const state = await program.account.vaultState.fetch(vaultStatePda);
+        returnObj.vaultState = state;
+        if (state.depositMint) {
+            try {
+                const mintInfo = await connection.getParsedAccountInfo(state.depositMint);
+                if (mintInfo.value) {
+                    const parsedData = mintInfo.value.data;
+                    returnObj.depositMintDecimals = parsedData.parsed.info.decimals;
+                }
+            }
+            catch (mintError) {
+                core_1.Logger.log.error('getVaultState', mintError, {
+                    message: 'Error fetching deposit mint decimals',
+                });
+            }
+        }
+        cacheVaultState(cacheKey, returnObj);
+        return returnObj;
+    }
+    catch (e) {
+        const error = e;
+        core_1.Logger.log.error('getVaultState', error, {
+            message: 'Error reading vault state',
+        });
+        return returnObj;
+    }
+}
+/**
+ * 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.
+ */
+async function getVaultStateReadOnly({ vaultProgramId, vaultAddress, connection, idl, fresh = false, }) {
+    const returnObj = {
+        vaultState: null,
+        depositMintDecimals: null,
+    };
+    try {
+        const cacheKey = `vaultState-${vaultAddress || vaultProgramId}`;
+        const cachedData = fresh ? undefined : await (0, core_1.getSafeCache)(cacheKey);
+        if (cachedData)
+            return cachedData;
+        if (!vaultProgramId) {
+            throw new core_1.UpshiftValidationError('INVALID_INPUT', 'Please enter a vault program ID');
+        }
+        const _vaultProgramId = new web3_js_1.PublicKey(vaultProgramId);
+        const vaultStatePda = vaultAddress
+            ? new web3_js_1.PublicKey(vaultAddress)
+            : deriveVaultStatePda(_vaultProgramId);
+        // One account read; the bytes are decoded locally below rather than
+        // re-fetched through `program.account.vaultState.fetch`.
+        const accountInfo = await connection.getAccountInfo(vaultStatePda);
+        if (!accountInfo) {
+            core_1.Logger.log.warn('getVaultStateReadOnly', 'Vault state account not found');
+            return returnObj;
+        }
+        // Decode with the program's account coder (same pattern as
+        // `readPricingSnapshot`); the read-only provider never signs.
+        try {
+            const readOnlyProvider = getReadOnlyProvider({ connection });
+            const program = getProgram({
+                provider: readOnlyProvider,
+                idl,
+                programId: _vaultProgramId.toBase58(),
+            });
+            const state = program.coder.accounts.decode('vaultState', accountInfo.data);
+            returnObj.vaultState = state;
+            if (state.depositMint) {
+                try {
+                    const mintInfo = await connection.getParsedAccountInfo(state.depositMint);
+                    if (mintInfo.value) {
+                        const parsedData = mintInfo.value.data;
+                        returnObj.depositMintDecimals = parsedData.parsed.info.decimals;
+                    }
+                }
+                catch (mintError) {
+                    core_1.Logger.log.error('getVaultStateReadOnly', mintError, {
+                        message: 'Error fetching deposit mint decimals',
+                    });
+                }
+            }
+        }
+        catch (programError) {
+            core_1.Logger.log.error('getVaultStateReadOnly', programError, {
+                message: 'Error decoding vault state with read-only provider',
+            });
+            // Decode failed: the state is unavailable and must not be cached, or
+            // every caller for the next TTL would inherit the failure.
+            returnObj.vaultState = null;
+            return returnObj;
+        }
+        cacheVaultState(cacheKey, returnObj);
+        return returnObj;
+    }
+    catch (e) {
+        const error = e;
+        core_1.Logger.log.error('getVaultStateReadOnly', error, {
+            message: 'Error reading vault state',
+        });
+        return returnObj;
+    }
+}
+// Fetch deposit and share mint addresses from on-chain vault state (read-only, no wallet required)
+async function getVaultMints({ vaultProgramId, vaultAddress, connection, idl, }) {
+    try {
+        const cacheKey = `vaultMints-${vaultAddress || vaultProgramId}`;
+        const cachedData = await (0, core_1.getSafeCache)(cacheKey);
+        if (cachedData)
+            return cachedData;
+        if (!vaultProgramId) {
+            throw new core_1.UpshiftValidationError('INVALID_INPUT', 'Please enter a vault program ID');
+        }
+        const _vaultProgramId = new web3_js_1.PublicKey(vaultProgramId);
+        const vaultStatePda = vaultAddress
+            ? new web3_js_1.PublicKey(vaultAddress)
+            : deriveVaultStatePda(_vaultProgramId);
+        const readOnlyProvider = getReadOnlyProvider({ connection });
+        const program = getProgram({
+            provider: readOnlyProvider,
+            idl,
+            programId: _vaultProgramId.toBase58(),
+        });
+        const state = await program.account.vaultState.fetch(vaultStatePda);
+        const returnObj = {
+            depositMint: state.depositMint.toString(),
+            shareMint: state.shareMint.toString(),
+            // Empty arrays yield undefined, falling back to legacy PDA seeds (no version byte)
+            vaultVersion: Array.isArray(state.vaultVersion)
+                ? state.vaultVersion[0]
+                : undefined,
+        };
+        await (0, core_1.setSafeCache)(cacheKey, returnObj);
+        return returnObj;
+    }
+    catch (e) {
+        const error = e;
+        const cause = error?.message || String(error);
+        core_1.Logger.log.error('getVaultMints', error, {
+            message: 'Error reading vault mints',
+            vaultProgramId: String(vaultProgramId),
+            vaultAddress: vaultAddress ? String(vaultAddress) : undefined,
+        });
+        throw new core_1.UpshiftSDKError('UNKNOWN', `Failed to read vault mints from on-chain state: ${cause}`, {
+            cause: error,
+            context: {
+                vaultProgramId: String(vaultProgramId),
+                vaultAddress: vaultAddress ? String(vaultAddress) : undefined,
+            },
+        });
+    }
+}
+async function getToken({ mintAddress, endpoint, connection, }) {
+    // `endpoint` is optional on ISolanaConnectionOptions, so a caller with no
+    // Solana RPC configured reaches `fetch(undefined, ...)`, which throws
+    // "Cannot read properties of undefined (reading 'toString')" from inside the
+    // runtime's fetch wrapper — an unactionable error masquerading as a token
+    // failure. Bail before the request instead.
+    if (!endpoint) {
+        core_1.Logger.log.warn('getToken', 'No Solana RPC endpoint configured', {
+            mintAddress: String(mintAddress),
+        });
+        return null;
+    }
+    try {
+        const cacheKey = `solana_token-${mintAddress}`;
+        const cachedData = await (0, core_1.getSafeCache)(cacheKey);
+        if (cachedData)
+            return cachedData;
+        // First, try to get token metadata via Metaplex DAS API
+        const response = await fetch(endpoint, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                jsonrpc: '2.0',
+                id: 'text',
+                method: 'getAsset',
+                params: { id: mintAddress.toString() },
+            }),
+        });
+        const data = (await response.json()); // @todo: add interface
+        // If we got valid token metadata, return it
+        if (data.result?.token_info?.decimals !== undefined) {
+            return {
+                address: data?.result?.id,
+                symbol: data.result?.content?.metadata?.symbol || 'N/A',
+                decimals: data.result?.token_info?.decimals,
+                name: data.result?.content?.metadata?.name || 'Unknown',
+                image: data.result?.content.metadata?.image,
+                program: data.result?.token_info?.token_program,
+                mintAuthority: data.result?.token_info?.mint_authority,
+                freezeAuthority: data.result?.token_info?.freeze_authority,
+                supply: data.result?.token_info?.supply,
+            };
+        }
+        // If Metaplex metadata didn't work, check if this is a vault program address
+        // In that case, we should query the share mint PDA instead
+        if (connection) {
+            try {
+                const vaultProgramId = new web3_js_1.PublicKey(mintAddress);
+                // Try to get vault state to see if this is a vault
+                const vaultState = await getVaultStateReadOnly({
+                    vaultProgramId,
+                    connection,
+                    idl: constants_1.vaultIdl,
+                });
+                // If we successfully got vault state, derive the share mint and query that
+                if (vaultState.vaultState) {
+                    const shareMintPda = deriveShareMintPda(vaultProgramId);
+                    // Get share mint metadata from blockchain
+                    const shareMintInfo = await connection.getParsedAccountInfo(shareMintPda);
+                    if (shareMintInfo.value) {
+                        const parsedData = shareMintInfo.value.data;
+                        // Try to get Metaplex metadata for the share mint
+                        const shareMintMetadata = await fetch(endpoint, {
+                            method: 'POST',
+                            headers: {
+                                'Content-Type': 'application/json',
+                            },
+                            body: JSON.stringify({
+                                jsonrpc: '2.0',
+                                id: 'text',
+                                method: 'getAsset',
+                                params: { id: shareMintPda.toString() },
+                            }),
+                        });
+                        const shareMintData = (await shareMintMetadata.json());
+                        const returnObj = {
+                            address: mintAddress.toString(), // Return original vault address
+                            symbol: shareMintData.result?.content?.metadata?.symbol || 'N/A',
+                            decimals: parsedData.parsed.info.decimals,
+                            name: shareMintData.result?.content?.metadata?.name ||
+                                'Vault Share Token',
+                            image: shareMintData.result?.content?.metadata?.image,
+                            program: shareMintData.result?.token_info?.token_program,
+                            mintAuthority: shareMintData.result?.token_info?.mint_authority,
+                            freezeAuthority: shareMintData.result?.token_info?.freeze_authority,
+                            supply: parsedData.parsed.info.supply,
+                            shareMintAddress: shareMintPda.toString(), // Include share mint address
+                        };
+                        await (0, core_1.setSafeCache)(cacheKey, returnObj);
+                        return returnObj;
+                    }
+                }
+            }
+            catch (vaultError) {
+                // Not a vault or error checking vault state, continue to return null
+                core_1.Logger.log.info('getToken', 'Not a vault program or error querying vault:', vaultError);
+            }
+        }
+        // If all attempts failed, return null
+        return null;
+    }
+    catch (error) {
+        // Callers fall back to backend metadata when this returns null, so a failed
+        // lookup is degraded-but-handled — warn, don't raise it as an error.
+        core_1.Logger.log.warn('getToken', 'Error fetching token metadata', {
+            mintAddress: String(mintAddress),
+            error,
+        });
+        return null;
+    }
+}
+// Helper function to get just the token symbol
+async function getTokenSymbol({ endpoint, mintAddress, }) {
+    try {
+        const tokenMetadata = await getToken({ endpoint, mintAddress });
+        if (tokenMetadata) {
+            return tokenMetadata.symbol;
+        }
+        return null;
+    }
+    catch (error) {
+        core_1.Logger.log.error('getTokenSymbol', error, {
+            message: 'Error fetching token symbol',
+        });
+        return 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.
+ */
+function selectRichestTokenAccount(accounts) {
+    const parsed = accounts.map((entry) => {
+        const info = entry.account.data?.parsed?.info;
+        const tokenAmount = info?.tokenAmount;
+        const raw = tokenAmount?.amount;
+        // A u64 string is the only shape the RPC promises here. Anything else
+        // (a base64 `data` the node could not jsonParse, a reshaping proxy) means
+        // we do not know this balance.
+        if (typeof raw !== 'string' || !/^\d+$/.test(raw)) {
+            throw new core_1.UpshiftSDKError('UNKNOWN', `Could not read the balance of token account ${entry.pubkey.toBase58()}. ` +
+                'The RPC returned an unrecognized response; please retry or switch RPC.', {
+                context: {
+                    account: entry.pubkey.toBase58(),
+                    rawAmount: String(raw),
+                },
+            });
+        }
+        return {
+            pubkey: entry.pubkey,
+            amount: BigInt(raw),
+            decimals: typeof tokenAmount?.decimals === 'number' ? tokenAmount.decimals : null,
+            // Passed through from the RPC rather than recomputed from `amount`, so
+            // the lossy float these legacy readers return is not made lossier.
+            uiAmount: typeof tokenAmount?.uiAmount === 'number' ? tokenAmount.uiAmount : null,
+            frozen: info?.state === 'frozen',
+        };
+    });
+    const richest = (candidates) => candidates.reduce((best, candidate) => {
+        if (!best)
+            return candidate;
+        if (candidate.amount !== best.amount)
+            return candidate.amount > best.amount ? candidate : best;
+        // Equal balances: break the tie on the address. Falling back to "whichever
+        // the RPC listed first" would leave exactly the ordering dependence this
+        // function exists to remove — harmless while the balances match, but it
+        // means two calls can name different accounts for the same wallet.
+        return candidate.pubkey.toBase58() < best.pubkey.toBase58()
+            ? candidate
+            : best;
+    }, undefined);
+    return richest(parsed.filter((a) => !a.frozen)) ?? richest(parsed);
+}
+async function fetchUserTokenBalance({ connection, publicKey, depositMint, }) {
+    if (!publicKey || !depositMint)
+        return '0';
+    try {
+        const _publicKey = new web3_js_1.PublicKey(publicKey);
+        const _depositMint = new web3_js_1.PublicKey(depositMint);
+        const tokenAccounts = await connection.getParsedTokenAccountsByOwner(_publicKey, {
+            mint: _depositMint,
+        });
+        // Same rule the write path uses — see `selectRichestTokenAccount`.
+        const richest = selectRichestTokenAccount(tokenAccounts.value);
+        return richest?.uiAmount?.toString() || '0';
+    }
+    catch (e) {
+        const error = e;
+        core_1.Logger.log.error('fetchUserTokenBalance', error, {
+            message: 'Error fetching user token balance',
+        });
+        return '0';
+    }
+}
+async function fetchUserShareBalance({ connection, publicKey, shareMint, }) {
+    if (!publicKey || !shareMint)
+        return 0;
+    try {
+        const _publicKey = new web3_js_1.PublicKey(publicKey);
+        const _shareMint = new web3_js_1.PublicKey(shareMint);
+        const shareAccounts = await connection.getParsedTokenAccountsByOwner(_publicKey, {
+            mint: _shareMint,
+        });
+        // Same rule the write path uses — see `selectRichestTokenAccount`.
+        const richest = selectRichestTokenAccount(shareAccounts.value);
+        return richest?.uiAmount ?? 0;
+    }
+    catch (e) {
+        const error = e;
+        core_1.Logger.log.error('fetchUserShareBalance', error, {
+            message: 'Error fetching user share balance',
+        });
+        return 0;
+    }
+}
+/**
+ * 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).
+ */
+async function fetchUserShareBalanceRaw({ connection, publicKey, shareMint, }) {
+    if (!publicKey || !shareMint)
+        return { amount: '0', decimals: null };
+    try {
+        const _publicKey = new web3_js_1.PublicKey(publicKey);
+        const _shareMint = new web3_js_1.PublicKey(shareMint);
+        const shareAccounts = await connection.getParsedTokenAccountsByOwner(_publicKey, {
+            mint: _shareMint,
+        });
+        // Same rule the write path uses — see `selectRichestTokenAccount`.
+        const richest = selectRichestTokenAccount(shareAccounts?.value ?? []);
+        if (!richest)
+            return { amount: '0', decimals: null };
+        return {
+            amount: richest.amount.toString(),
+            decimals: richest.decimals,
+        };
+    }
+    catch (e) {
+        const error = e;
+        core_1.Logger.log.error('fetchUserShareBalanceRaw', error, {
+            message: 'Error fetching raw user share balance',
+        });
+        return { amount: '0', decimals: 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).
+ */
+function resolveProgramId(vaultAddress, solanaMetadata) {
+    return solanaMetadata?.program_id || vaultAddress;
+}
+// String-arithmetic UI→raw conversion. Truncates past `decimals` like
+// ethers.parseUnits; safe past Number.MAX_SAFE_INTEGER.
+/** @internal */
+function uiAmountToRawBn(uiAmount, decimals) {
+    if (!Number.isFinite(uiAmount)) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', `uiAmountToRawBn: amount must be finite, got ${uiAmount}`);
+    }
+    if (uiAmount < 0) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', `uiAmountToRawBn: amount must be non-negative, got ${uiAmount}`);
+    }
+    if (!Number.isInteger(decimals) || decimals < 0) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', `uiAmountToRawBn: decimals must be a non-negative integer, got ${decimals}`);
+    }
+    // Build the fixed-decimal string manually — `.toFixed(decimals)` rounds
+    // the last digit, but parseUnits semantics require truncation.
+    const uiStr = uiAmount.toString();
+    const expansion = uiStr.includes('e') || uiStr.includes('E')
+        ? uiAmount.toFixed(Math.max(decimals, 20)).replace(/\.?0+$/, '')
+        : uiStr;
+    const [whole, fraction = ''] = expansion.split('.');
+    const truncated = fraction.slice(0, decimals);
+    const paddedFraction = truncated.padEnd(decimals, '0');
+    const raw = (whole + paddedFraction).replace(/^0+/, '') || '0';
+    return new anchor_1.BN(raw);
+}
+exports.SolanaUtils = {
+    getExplorerLink,
+    isSolanaAddress: chain_address_1.isSolanaAddress,
+    isSolana,
+    getProgram,
+    getProvider,
+    getReadOnlyProvider,
+    deriveShareMintPda,
+    deriveVaultStatePda,
+    deriveVaultTokenAtaPda,
+    getVaultState,
+    getVaultStateReadOnly,
+    getToken,
+    getTokenSymbol,
+    fetchUserTokenBalance,
+    fetchUserShareBalance,
+    fetchUserShareBalanceRaw,
+    getBestRpcEndpoint,
+    fallbackDecimals: constants_1.fallbackDecimals,
+    fallbackNetwork: constants_1.fallbackNetwork,
+    programIds: constants_1.programIds,
+    getVaultMints,
+    resolveProgramId,
+};
+//# sourceMappingURL=utils.js.map