@getomnichain/omnichain 0.2.0

package/dist/solana/solana_chain.js

@@ -0,0 +1,704 @@
+import { ComputeBudgetProgram, Connection, MessageV0, PublicKey, SystemProgram, VersionedTransaction, } from '@solana/web3.js';
+import { TOKEN_2022_PROGRAM_ID, TOKEN_PROGRAM_ID, createAssociatedTokenAccountIdempotentInstruction, createAssociatedTokenAccountInstruction, createTransferCheckedInstruction, getAccount, getAssociatedTokenAddressSync, getMint, } from '@solana/spl-token';
+import { Chain, resolveTransferAmount } from "../chain.base.js";
+import { ChainError, ChainErrorKinds, sanitizeCause, sanitizeMessage } from "../errors.js";
+import { NetworkType, registerNonEvmChain } from "../network_type.js";
+import { Priority } from "../priority.js";
+import { AssetBalanceChange, } from "../transaction_status.js";
+import { SolanaTransactionFees, SolanaTransactionStatus, } from "./solana_transaction_status.js";
+import { SolanaAddress } from "./solana_address.js";
+import { SolanaToken } from "./solana_token.js";
+import { UnsignedSolanaTransaction } from "./unsigned_solana_transaction.js";
+const DEFAULT_COMPUTE_UNIT_LIMIT = 200_000;
+/** Percentile (0..1) of recent prioritization fees picked per Priority. */
+const SOL_PRIORITY_PERCENTILE = {
+    [Priority.SLOW]: 0.25,
+    [Priority.NORMAL]: 0.5,
+    [Priority.FAST]: 0.9,
+};
+/**
+ * Solana is account-based but very different from EVM (see docs/solana.md). Key choices made
+ * for depositron:
+ *   - Transfers always build a `VersionedTransaction` (MessageV0) — legacy transactions are
+ *     deprecated and can't address account-lookup tables for fee reduction.
+ *   - The fee payer is always the sender (no relayer pattern here).
+ *   - SPL transfers use `transferChecked` (which asserts the recipient mint matches the
+ *     declared mint, defeating the entire class of "wrong-token-decimals" attacks).
+ *   - When the recipient doesn't have an ATA for the mint, we *prepend* a create-ATA
+ *     instruction paid by the sender. This costs ~2039 lamports of rent-exempt deposit.
+ *   - We do NOT consult a curated registry to determine SPL vs Token-2022 —
+ *     instead we read the mint account owner at build time. That's one RPC per transfer but
+ *     it's authoritative.
+ */
+export class SolanaChain extends Chain {
+    defaultRpcUrl;
+    rpcUrl;
+    legacyRpcEnvNames;
+    explorerClusterSuffix;
+    chainAgnosticGenesisHash;
+    _nativeToken;
+    _connection = null;
+    constructor(init) {
+        super(init.chainId, init.name, NetworkType.SOLANA, init.blockTimeSeconds, init.nativeSymbol, init.explorerBaseUrl);
+        this.defaultRpcUrl = init.defaultRpcUrl;
+        this.rpcUrl = init.rpcUrl;
+        this.legacyRpcEnvNames = init.legacyRpcEnvNames ?? [];
+        this.explorerClusterSuffix = init.explorerClusterSuffix ?? '';
+        this.chainAgnosticGenesisHash = init.chainAgnosticGenesisHash;
+        this._nativeToken = SolanaToken.native(init.chainId, init.nativeSymbol, init.nativeDecimals ?? 9);
+        registerNonEvmChain(init.chainId, NetworkType.SOLANA);
+    }
+    get nativeToken() {
+        return this._nativeToken;
+    }
+    getConnection() {
+        if (this._connection)
+            return this._connection;
+        const rpcUrl = this.readRpcUrl();
+        this._connection = new Connection(rpcUrl, { commitment: 'confirmed' });
+        return this._connection;
+    }
+    /**
+     * Network-aware priority fee suggestion in microlamports per compute unit.
+     * Samples `getRecentPrioritizationFees({ lockedWritableAccounts: [] })` (cluster-wide, ~150 most recent slots) and
+     * picks a percentile per priority:
+     *   - SLOW   = p25
+     *   - NORMAL = p50
+     *   - FAST   = p90
+     * Returns 0 if the cluster has been so quiet that the chosen percentile is 0 (legitimate
+     * outcome on devnet / off-peak mainnet). Caller plugs this into
+     * `ComputeBudgetProgram.setComputeUnitPrice({ microLamports })`.
+     */
+    async suggestPriorityFeeMicroLamports(priority) {
+        const samples = await this.getConnection().getRecentPrioritizationFees({
+            lockedWritableAccounts: [],
+        });
+        const fees = samples
+            .map((s) => s.prioritizationFee)
+            .filter((f) => Number.isFinite(f) && f >= 0)
+            .sort((a, b) => a - b);
+        if (fees.length === 0)
+            return 0;
+        const percentile = SOL_PRIORITY_PERCENTILE[priority];
+        const idx = Math.min(fees.length - 1, Math.floor((fees.length - 1) * percentile));
+        return fees[idx];
+    }
+    /**
+     * Env var name for a Solana chain by chain id — mirrors Python's
+     * `SolanaChain.rpc_url_env_for_chain_id` (impl/solana/base.py:421-423)
+     * exactly, including the signed chainId. Shell operators must set via
+     * dotenv / docker / k8s since `SOLANA_-2000_RPC_URL` is not a settable
+     * name in sh/bash/zsh.
+     */
+    static rpcUrlEnvForChainId(chainId) {
+        return `SOLANA_${chainId}_RPC_URL`;
+    }
+    /**
+     * Resolution precedence, mirrors omnichain-py/impl/solana/base.py:424-434
+     * plus a TS-side legacy fallback for consumers with pre-v0 env-var names:
+     *   1. constructor `rpcUrl`
+     *   2. env `<NAME_UPPERCASE_UNDERSCORED>_RPC_URL`
+     *   3. env `SOLANA_<chainId>_RPC_URL` (Python parity — signed)
+     *   4. env from `legacyRpcEnvNames` (if configured — e.g. mainnet checks
+     *      the pre-rename `SOLANA_RPC_URL` here)
+     *   5. `defaultRpcUrl`  (never throws — public cluster)
+     */
+    readRpcUrl() {
+        if (this.rpcUrl && this.rpcUrl.trim().length > 0)
+            return this.rpcUrl.trim();
+        const env = globalThis.process?.env;
+        const candidates = [
+            this.name.replace(/ /g, '_').toUpperCase() + '_RPC_URL',
+            SolanaChain.rpcUrlEnvForChainId(this.chainId),
+            ...this.legacyRpcEnvNames,
+        ];
+        for (const key of candidates) {
+            const v = env?.[key];
+            if (v && v.trim().length > 0)
+                return v.trim();
+        }
+        return this.defaultRpcUrl;
+    }
+    getWalletExplorerUrl(address) {
+        return `${this.explorerBaseUrl}/account/${address}${this.explorerClusterSuffix}`;
+    }
+    getTokenExplorerUrl(tokenIdentifier) {
+        if (!tokenIdentifier) {
+            return this.explorerBaseUrl + this.explorerClusterSuffix;
+        }
+        return `${this.explorerBaseUrl}/token/${tokenIdentifier}${this.explorerClusterSuffix}`;
+    }
+    getTransactionExplorerUrl(txHash) {
+        return `${this.explorerBaseUrl}/tx/${txHash}${this.explorerClusterSuffix}`;
+    }
+    validateAddress(raw) {
+        try {
+            new SolanaAddress(raw);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    validateTokenIdentifier(raw) {
+        if (raw === undefined)
+            return true; // native SOL
+        return this.validateAddress(raw);
+    }
+    async getBalance(owner, tokenIdentifier) {
+        if (!this.validateAddress(owner)) {
+            throw new ChainError(ChainErrorKinds.InvalidAddress, `Invalid Solana address: ${owner}`, {
+                chainId: this.chainId,
+                address: owner,
+            });
+        }
+        const connection = this.getConnection();
+        const ownerPk = new PublicKey(owner);
+        try {
+            if (tokenIdentifier === undefined) {
+                return BigInt(await connection.getBalance(ownerPk));
+            }
+            if (!this.validateAddress(tokenIdentifier)) {
+                throw new ChainError(ChainErrorKinds.InvalidTokenIdentifier, `Invalid Solana mint: ${tokenIdentifier}`, { chainId: this.chainId, identifier: tokenIdentifier });
+            }
+            const mintPk = new PublicKey(tokenIdentifier);
+            const programId = await this.resolveTokenProgramId(mintPk);
+            const ata = getAssociatedTokenAddressSync(mintPk, ownerPk, false, programId);
+            try {
+                const acct = await getAccount(connection, ata, undefined, programId);
+                return acct.amount;
+            }
+            catch {
+                // No ATA → balance 0.
+                return 0n;
+            }
+        }
+        catch (err) {
+            if (err instanceof ChainError)
+                throw err;
+            throw new ChainError(ChainErrorKinds.RpcError, `Failed to read Solana balance for ${owner}/${tokenIdentifier ?? 'NATIVE'}: ${err.message}`, { chainId: this.chainId, address: owner, identifier: tokenIdentifier }, err);
+        }
+    }
+    async createTransferUnsignedTransaction(req) {
+        if (!req.from) {
+            throw new ChainError(ChainErrorKinds.InvalidArgument, 'Solana transfers require an explicit `from` (no implicit signer)', { chainId: this.chainId });
+        }
+        if (!this.validateAddress(req.from)) {
+            throw new ChainError(ChainErrorKinds.InvalidAddress, `Invalid sender: ${req.from}`, {
+                chainId: this.chainId,
+                address: req.from,
+            });
+        }
+        if (!this.validateAddress(req.to)) {
+            throw new ChainError(ChainErrorKinds.InvalidAddress, `Invalid recipient: ${req.to}`, {
+                chainId: this.chainId,
+                address: req.to,
+            });
+        }
+        if (!this.validateTokenIdentifier(req.tokenIdentifier)) {
+            throw new ChainError(ChainErrorKinds.InvalidTokenIdentifier, `Invalid token identifier: ${req.tokenIdentifier}`, { chainId: this.chainId, identifier: req.tokenIdentifier });
+        }
+        // gasPricing not yet consumed by Solana builder (Phase 2 follow-up);
+        // reject rather than silently ignore.
+        if (req.gasPricing !== undefined) {
+            throw new ChainError(ChainErrorKinds.InvalidArgument, 'CreateTransferRequest.gasPricing is not yet consumed by SolanaChain (Phase 2 follow-up). Use `priorityFeeMicroLamportsPerCu` / `computeUnitLimit` on SolanaTransferOptions for now.', { chainId: this.chainId });
+        }
+        // isFullBalance requires a base-fee + rent-exempt reserve before
+        // it can be safely wired — sending all lamports leaves 0 for the
+        // 5000-lamport base fee (and ATA rent when feePayer === from on
+        // the SPL path). Deferred to a follow-up card.
+        if (req.isFullBalance === true) {
+            throw new ChainError(ChainErrorKinds.InvalidArgument, 'CreateTransferRequest.isFullBalance is not yet supported on SolanaChain — pass `amount` or `amountHr` explicitly.', { chainId: this.chainId });
+        }
+        // Only fetch decimals when amountHr is the input form — avoids the
+        // extra getMint RPC on every bigint-amount transfer. Native path
+        // uses SDK-declared decimals; SPL path uses resolveMintDecimals
+        // (which already throws on RPC failure — no defensive fallback).
+        const tokenDecimals = req.amountHr !== undefined
+            ? req.tokenIdentifier === undefined
+                ? this._nativeToken.decimals
+                : await this.resolveMintDecimals(new PublicKey(req.tokenIdentifier))
+            : 0;
+        const resolvedAmount = resolveTransferAmount(req, tokenDecimals);
+        const amountMr = resolvedAmount.kind === 'exact' ? resolvedAmount.amountMr : 0n;
+        if (amountMr <= 0n) {
+            throw new ChainError(ChainErrorKinds.InvalidArgument, `Transfer amount must be positive (got ${amountMr})`, { chainId: this.chainId });
+        }
+        if (req.feePayer !== undefined && !this.validateAddress(req.feePayer)) {
+            throw new ChainError(ChainErrorKinds.InvalidAddress, `Invalid feePayer: ${req.feePayer}`, {
+                chainId: this.chainId,
+                address: req.feePayer,
+            });
+        }
+        const connection = this.getConnection();
+        const fromPk = new PublicKey(req.from);
+        const toPk = new PublicKey(req.to);
+        const feePayerAddress = req.feePayer ?? req.from;
+        const feePayerPk = new PublicKey(feePayerAddress);
+        const instructions = [];
+        if (req.computeUnitLimit !== undefined || req.priorityFeeMicroLamportsPerCu !== undefined) {
+            instructions.push(ComputeBudgetProgram.setComputeUnitLimit({
+                units: req.computeUnitLimit ?? DEFAULT_COMPUTE_UNIT_LIMIT,
+            }));
+            if (req.priorityFeeMicroLamportsPerCu !== undefined) {
+                instructions.push(ComputeBudgetProgram.setComputeUnitPrice({
+                    microLamports: req.priorityFeeMicroLamportsPerCu,
+                }));
+            }
+        }
+        if (req.tokenIdentifier === undefined) {
+            instructions.push(SystemProgram.transfer({
+                fromPubkey: fromPk,
+                toPubkey: toPk,
+                lamports: amountMr,
+            }));
+        }
+        else {
+            const mintPk = new PublicKey(req.tokenIdentifier);
+            const programId = await this.resolveTokenProgramId(mintPk);
+            // If amountHr wasn't the input form, tokenDecimals is still 0 and
+            // we haven't fetched the mint yet — do it now for the transfer-
+            // checked instruction (which requires the real decimals).
+            const decimals = tokenDecimals > 0 ? tokenDecimals : await this.resolveMintDecimals(mintPk);
+            const sourceAta = getAssociatedTokenAddressSync(mintPk, fromPk, false, programId);
+            const destAta = getAssociatedTokenAddressSync(mintPk, toPk, false, programId);
+            // Create the destination ATA when missing — the fee payer pays rent.
+            const destInfo = await connection.getAccountInfo(destAta);
+            if (!destInfo) {
+                instructions.push(createAssociatedTokenAccountInstruction(feePayerPk, destAta, toPk, mintPk, programId));
+            }
+            instructions.push(createTransferCheckedInstruction(sourceAta, mintPk, destAta, fromPk, amountMr, decimals, [], programId));
+        }
+        const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash('finalized');
+        const message = MessageV0.compile({
+            payerKey: feePayerPk,
+            instructions,
+            recentBlockhash: blockhash,
+        });
+        return new UnsignedSolanaTransaction({
+            chainId: this.chainId,
+            transaction: new VersionedTransaction(message),
+            feePayer: feePayerAddress,
+            recentBlockhash: blockhash,
+            lastValidBlockHeight,
+            instructions,
+        });
+    }
+    /**
+     * Wraps a caller-supplied list of program instructions into a fully-formed
+     * UnsignedSolanaTransaction. Used by depositron's SOL_INSTRUCTIONS action type to support
+     * arbitrary program calls (staking, swaps, custom programs) without the SDK having to
+     * understand the instruction semantics. The SDK still owns the envelope: CU limit + price,
+     * MessageV0 compilation, fresh blockhash, VersionedTransaction wrapping.
+     *
+     * Caller is responsible for: instruction correctness, signer-account constraints (only the
+     * single key the caller will sign with — typically the vault key — can be flagged as signer),
+     * ATA creation (if any instruction touches an ATA that doesn't exist yet), and decimals
+     * validation (no automatic `transferChecked` fallback here).
+     */
+    async createInstructionsUnsignedTransaction(req) {
+        if (!req.from || !this.validateAddress(req.from)) {
+            throw new ChainError(ChainErrorKinds.InvalidAddress, `Invalid sender: ${req.from}`, {
+                chainId: this.chainId,
+                address: req.from,
+            });
+        }
+        if (req.feePayer !== undefined && !this.validateAddress(req.feePayer)) {
+            throw new ChainError(ChainErrorKinds.InvalidAddress, `Invalid feePayer: ${req.feePayer}`, {
+                chainId: this.chainId,
+                address: req.feePayer,
+            });
+        }
+        if (!Array.isArray(req.instructions) || req.instructions.length === 0) {
+            throw new ChainError(ChainErrorKinds.InvalidArgument, 'SolanaChain.createInstructionsUnsignedTransaction requires at least one instruction', { chainId: this.chainId });
+        }
+        const feePayerAddress = req.feePayer ?? req.from;
+        const feePayerPk = new PublicKey(feePayerAddress);
+        const allIxs = [];
+        if (req.computeUnitLimit !== undefined || req.priorityFeeMicroLamportsPerCu !== undefined) {
+            allIxs.push(ComputeBudgetProgram.setComputeUnitLimit({
+                units: req.computeUnitLimit ?? DEFAULT_COMPUTE_UNIT_LIMIT,
+            }));
+            if (req.priorityFeeMicroLamportsPerCu !== undefined) {
+                allIxs.push(ComputeBudgetProgram.setComputeUnitPrice({
+                    microLamports: req.priorityFeeMicroLamportsPerCu,
+                }));
+            }
+        }
+        for (const ix of req.instructions)
+            allIxs.push(ix);
+        const connection = this.getConnection();
+        const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash('finalized');
+        const message = MessageV0.compile({
+            payerKey: feePayerPk,
+            instructions: allIxs,
+            recentBlockhash: blockhash,
+        });
+        return new UnsignedSolanaTransaction({
+            chainId: this.chainId,
+            transaction: new VersionedTransaction(message),
+            feePayer: feePayerAddress,
+            recentBlockhash: blockhash,
+            lastValidBlockHeight,
+            instructions: allIxs,
+        });
+    }
+    /**
+     * Returns a fresh UnsignedSolanaTransaction with the same instructions but a newly-fetched
+     * blockhash. Use when a previously-built tx couldn't broadcast inside its blockhash window
+     * (~60s on mainnet) — Solana drops txs whose blockhash has expired. Caller must re-sign:
+     * the new signed message has a different recent_blockhash byte sequence, so any existing
+     * signature is invalid.
+     */
+    async refreshBlockhash(unsigned) {
+        const connection = this.getConnection();
+        const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash('finalized');
+        if (blockhash === unsigned.recentBlockhash)
+            return unsigned;
+        const message = MessageV0.compile({
+            payerKey: unsigned.feePayerPubkey,
+            instructions: unsigned.instructions,
+            recentBlockhash: blockhash,
+        });
+        return new UnsignedSolanaTransaction({
+            chainId: unsigned.chainId,
+            transaction: new VersionedTransaction(message),
+            feePayer: unsigned.feePayer,
+            recentBlockhash: blockhash,
+            lastValidBlockHeight,
+            instructions: unsigned.instructions,
+        });
+    }
+    /**
+     * Simulates the tx and right-sizes its setComputeUnitLimit instruction (10% headroom).
+     * Lowers priority-fee cost because the fee = CU price × CU limit; oversized limits pay for
+     * unused compute. Returns the unsigned untouched if it has no CU-limit ix or simulation didn't
+     * report unitsConsumed. Throws ChainError(SimulationFailed) when the sim returns `err`.
+     */
+    async estimateAndApplyCu(unsigned) {
+        const connection = this.getConnection();
+        const sim = await connection.simulateTransaction(unsigned.transaction, {
+            sigVerify: false,
+            replaceRecentBlockhash: true,
+            commitment: 'confirmed',
+        });
+        if (sim.value.err) {
+            throw new ChainError(ChainErrorKinds.InvalidArgument, `Solana simulation rejected the tx: ${JSON.stringify(sim.value.err)}`, { chainId: this.chainId });
+        }
+        const consumed = sim.value.unitsConsumed;
+        if (!consumed)
+            return unsigned;
+        const newLimit = Math.ceil(consumed * 1.1);
+        const setLimitIxIndex = unsigned.instructions.findIndex((ix) => ix.programId.equals(ComputeBudgetProgram.programId) &&
+            // setComputeUnitLimit ix discriminator is 0x02 in the first data byte.
+            ix.data.length >= 1 &&
+            ix.data[0] === 0x02);
+        if (setLimitIxIndex === -1)
+            return unsigned;
+        const newInstructions = [...unsigned.instructions];
+        newInstructions[setLimitIxIndex] = ComputeBudgetProgram.setComputeUnitLimit({
+            units: newLimit,
+        });
+        const message = MessageV0.compile({
+            payerKey: unsigned.feePayerPubkey,
+            instructions: newInstructions,
+            recentBlockhash: unsigned.recentBlockhash,
+        });
+        return new UnsignedSolanaTransaction({
+            chainId: unsigned.chainId,
+            transaction: new VersionedTransaction(message),
+            feePayer: unsigned.feePayer,
+            recentBlockhash: unsigned.recentBlockhash,
+            lastValidBlockHeight: unsigned.lastValidBlockHeight,
+            instructions: newInstructions,
+        });
+    }
+    /** Whether the given error came from a preflight simulation rejection (vs network/transport). */
+    static isSimulationError(err) {
+        if (err instanceof ChainError && err.kind === ChainErrorKinds.InvalidArgument)
+            return true;
+        const msg = err?.message ?? '';
+        return /simulation failed|transaction simulation failed/i.test(msg);
+    }
+    /** Whether the given error indicates the tx's blockhash has expired and a refresh is needed. */
+    static isBlockhashExpiredError(err) {
+        const msg = err?.message ?? '';
+        return /blockhash not found|expired blockhash|blockhash.*expired/i.test(msg);
+    }
+    async getTransactionStatus(txHash) {
+        const connection = this.getConnection();
+        // Best-effort read of the current rpc URL for message/cause scrubbing.
+        // readRpcUrl throws when nothing is configured; there'd be no
+        // network call in that case, but defensive null keeps the sanitizer
+        // total.
+        let scrubUrl = null;
+        try {
+            scrubUrl = this.readRpcUrl();
+        }
+        catch {
+            scrubUrl = null;
+        }
+        let tx;
+        try {
+            tx = await connection.getTransaction(txHash, {
+                commitment: 'confirmed',
+                maxSupportedTransactionVersion: 0,
+            });
+        }
+        catch (err) {
+            const rawMsg = err instanceof Error ? err.message : String(err);
+            throw new ChainError(ChainErrorKinds.RpcError, sanitizeMessage(`Failed to read Solana tx ${txHash}: ${rawMsg}`, scrubUrl), { chainId: this.chainId, txHash }, sanitizeCause(err, scrubUrl));
+        }
+        if (!tx) {
+            // Full tx not fetchable; fall back to signature status. Consume BOTH
+            // fields (`confirmationStatus` + `err`) — the previous fix that
+            // always returned Pending on settled-but-unfetchable let a settled-
+            // FAILED tx poll indefinitely.
+            let sig;
+            try {
+                sig = await connection.getSignatureStatus(txHash, { searchTransactionHistory: true });
+            }
+            catch (err) {
+                const rawMsg = err instanceof Error ? err.message : String(err);
+                throw new ChainError(ChainErrorKinds.RpcError, sanitizeMessage(`Failed to read Solana signature status ${txHash}: ${rawMsg}`, scrubUrl), { chainId: this.chainId, txHash }, sanitizeCause(err, scrubUrl));
+            }
+            if (!sig || !sig.value)
+                return SolanaTransactionStatus.notFound(this.chainId);
+            const settled = sig.value.confirmationStatus === 'finalized' ||
+                sig.value.confirmationStatus === 'confirmed';
+            if (settled && sig.value.err) {
+                // Fees are not reconstructable from a sig-status only — factory
+                // now accepts fees: null for exactly this case.
+                return SolanaTransactionStatus.failed({
+                    chainId: this.chainId,
+                    inclusionAt: null,
+                    error: { code: 'REVERTED', reason: JSON.stringify(sig.value.err) },
+                    fees: null,
+                });
+            }
+            // settled-Success without a fetchable body OR still propagating —
+            // keep polling. NotFound here would misreport a settled deposit.
+            return SolanaTransactionStatus.pending(this.chainId);
+        }
+        if (!tx.meta) {
+            // A returned tx without meta is a valid RPC response shape (some
+            // very old txs or unusual nodes). Report Pending so consumers keep
+            // polling rather than throwing from a status read; matches the
+            // _decodeBalanceChanges guard at the same file.
+            return SolanaTransactionStatus.pending(this.chainId);
+        }
+        const accounts = tx.transaction.message.staticAccountKeys.map((k) => k.toBase58());
+        const feePayer = accounts[0] ?? '';
+        if (feePayer.length === 0) {
+            throw new ChainError(ChainErrorKinds.TransactionDecodeFailed, `Solana tx ${txHash} has no fee_payer account`, { chainId: this.chainId, txHash });
+        }
+        const feeLamports = BigInt(tx.meta.fee);
+        const rawCu = tx.meta.computeUnitsConsumed;
+        const computeUnitsConsumed = rawCu === undefined || rawCu === null ? null : BigInt(rawCu);
+        const preLamports = BigInt(tx.meta.preBalances?.[0] ?? 0);
+        const postLamports = BigInt(tx.meta.postBalances?.[0] ?? 0);
+        const fees = new SolanaTransactionFees({
+            feePayer,
+            feeLamports,
+            computeUnitsConsumed,
+            netLamportsChangeByFeePayer: postLamports - preLamports,
+        });
+        const inclusionAt = tx.blockTime ? new Date(tx.blockTime * 1000) : null;
+        if (tx.meta.err) {
+            return SolanaTransactionStatus.failed({
+                chainId: this.chainId,
+                inclusionAt,
+                error: { code: 'REVERTED', reason: JSON.stringify(tx.meta.err) },
+                fees,
+            });
+        }
+        // Wrap the decoder so a malformed uiTokenAmount.amount / pre/postBalance
+        // (BigInt(...) throws SyntaxError on non-numeric strings) surfaces as
+        // ChainError(TransactionDecodeFailed) rather than a raw SyntaxError.
+        // Mirrors evm_chain.ts:decodeBalanceChanges catch.
+        let balanceChanges;
+        try {
+            balanceChanges = this._decodeBalanceChanges(tx);
+        }
+        catch (err) {
+            if (err instanceof ChainError)
+                throw err;
+            throw new ChainError(ChainErrorKinds.TransactionDecodeFailed, `Failed to decode Solana tx ${txHash}: ${err instanceof Error ? err.message : String(err)}`, { chainId: this.chainId, txHash }, err instanceof Error ? err : undefined);
+        }
+        return SolanaTransactionStatus.successful({
+            chainId: this.chainId,
+            inclusionAt,
+            balanceChanges,
+            fees,
+        });
+    }
+    async getChainTipHeight() {
+        return this.getConnection().getSlot('confirmed');
+    }
+    /**
+     * Resolves the token program owner for a given mint. Token-2022 mints are owned by
+     * TOKEN_2022_PROGRAM_ID; classic SPL by TOKEN_PROGRAM_ID. Required for `transferChecked`
+     * and ATA derivation.
+     */
+    async resolveTokenProgramId(mint) {
+        const connection = this.getConnection();
+        const info = await connection.getAccountInfo(mint);
+        if (!info) {
+            throw new ChainError(ChainErrorKinds.InvalidTokenIdentifier, `Mint ${mint.toBase58()} not found on chain`, { chainId: this.chainId, identifier: mint.toBase58() });
+        }
+        const owner = info.owner.toBase58();
+        if (owner === TOKEN_PROGRAM_ID.toBase58())
+            return TOKEN_PROGRAM_ID;
+        if (owner === TOKEN_2022_PROGRAM_ID.toBase58())
+            return TOKEN_2022_PROGRAM_ID;
+        throw new ChainError(ChainErrorKinds.InvalidTokenIdentifier, `Mint ${mint.toBase58()} is owned by ${owner}, not an SPL Token program`, { chainId: this.chainId, identifier: mint.toBase58() });
+    }
+    async resolveMintDecimals(mint) {
+        const programId = await this.resolveTokenProgramId(mint);
+        const mintInfo = await getMint(this.getConnection(), mint, undefined, programId);
+        return mintInfo.decimals;
+    }
+    /**
+     * Raw-instruction helper for callers that will compile the transaction downstream
+     * (e.g. depositron's SOL_INSTRUCTIONS action type) instead of using
+     * createTransferUnsignedTransaction's compiled-tx surface.
+     *
+     * Synchronous — no RPC.
+     */
+    buildNativeTransferInstruction(from, to, lamports) {
+        if (lamports <= 0n) {
+            throw new ChainError(ChainErrorKinds.InvalidArgument, `Native transfer lamports must be positive (got ${lamports})`, { chainId: this.chainId });
+        }
+        return SystemProgram.transfer({
+            fromPubkey: from,
+            toPubkey: to,
+            lamports,
+        });
+    }
+    /**
+     * Raw-instruction helper for SPL / Token-2022 transfers where the caller will compile
+     * the transaction downstream. Returns [createATA-idempotent?, transferChecked].
+     *
+     * Idempotent ATA (vs the probe-then-create pattern in createTransferUnsignedTransaction)
+     * is deliberate: when a downstream compiler runs the emitted instructions blindly,
+     * a probe done here can race with execution — the idempotent form is a no-op when the
+     * ATA exists and a create when it doesn't, without needing a probe RPC.
+     *
+     * `allowOwnerOffCurve: true` applies to BOTH source and destination ATA derivation —
+     * needed for PDA-owned vaults / program-owned recipients. Defaults to false to match
+     * createTransferUnsignedTransaction.
+     */
+    async buildSplTransferInstructions(req) {
+        if (req.amount <= 0n) {
+            throw new ChainError(ChainErrorKinds.InvalidArgument, `SPL transfer amount must be positive (got ${req.amount})`, { chainId: this.chainId, identifier: req.mint.toBase58() });
+        }
+        const includeCreateAta = req.includeCreateAta ?? true;
+        const allowOwnerOffCurve = req.allowOwnerOffCurve ?? false;
+        const programId = await this.resolveTokenProgramId(req.mint);
+        const decimals = await this.resolveMintDecimals(req.mint);
+        const deriveAta = (owner, role) => {
+            try {
+                return getAssociatedTokenAddressSync(req.mint, owner, allowOwnerOffCurve, programId);
+            }
+            catch (err) {
+                // spl-token's TokenOwnerOffCurveError ships with an empty message. Rethrow as
+                // ChainError so consumers see the SDK's declared error surface, and so the
+                // reason is discoverable (pass `allowOwnerOffCurve: true` for PDA-owned wallets).
+                throw new ChainError(ChainErrorKinds.InvalidAddress, `${role} owner is off-curve; pass allowOwnerOffCurve:true for PDA-owned wallets`, { chainId: this.chainId, address: owner.toBase58() });
+            }
+        };
+        const sourceAta = deriveAta(req.from, 'source');
+        const destAta = deriveAta(req.to, 'destination');
+        const instructions = [];
+        if (includeCreateAta) {
+            instructions.push(createAssociatedTokenAccountIdempotentInstruction(req.from, destAta, req.to, req.mint, programId));
+        }
+        instructions.push(createTransferCheckedInstruction(sourceAta, req.mint, destAta, req.from, req.amount, decimals, [], programId));
+        return instructions;
+    }
+    /**
+     * Decodes per-account lamport deltas + SPL pre/post token-balance diffs into
+     * a `NestedBalanceChanges` map. Marked internal via naming rather than TS
+     * `private` so chain-agnostic unit tests can exercise it directly without
+     * spinning up a Connection.
+     */
+    _decodeBalanceChanges(tx) {
+        const result = new Map();
+        if (!tx.meta)
+            return result;
+        // For v0 messages, meta.preBalances/postBalances are indexed over
+        // staticAccountKeys ++ loadedAddresses.writable ++ loadedAddresses.readonly.
+        // Iterating only staticAccountKeys silently drops lamport deltas for
+        // any LUT-resolved account — a SOL deposit to a wallet that only
+        // appears via a lookup table produces no balanceChanges row at all.
+        // getTransaction() is called with maxSupportedTransactionVersion: 0
+        // so we always see the resolved addresses.
+        const staticKeys = tx.transaction.message.staticAccountKeys.map((k) => k.toBase58());
+        const loaded = tx.meta.loadedAddresses;
+        const loadedWritable = (loaded?.writable ?? []).map((k) => k.toBase58());
+        const loadedReadonly = (loaded?.readonly ?? []).map((k) => k.toBase58());
+        const accounts = [...staticKeys, ...loadedWritable, ...loadedReadonly];
+        const pre = tx.meta.preBalances ?? [];
+        const post = tx.meta.postBalances ?? [];
+        for (let i = 0; i < accounts.length; i++) {
+            const delta = BigInt(post[i] ?? 0) - BigInt(pre[i] ?? 0);
+            if (delta === 0n)
+                continue;
+            AssetBalanceChange.upsert(result, accounts[i], this._nativeToken, AssetBalanceChange.fromMr(delta, this._nativeToken.decimals));
+        }
+        const preTok = tx.meta.preTokenBalances ?? [];
+        const postTok = tx.meta.postTokenBalances ?? [];
+        const tokenKey = (b) => `${b.accountIndex}|${b.mint}`;
+        // Track the token account's owner (a wallet) and the mint's decimals,
+        // both surfaced verbatim by getTransaction's parsed token-balance meta.
+        const byKey = new Map();
+        for (const b of preTok) {
+            byKey.set(tokenKey(b), {
+                pre: BigInt(b.uiTokenAmount.amount),
+                post: 0n,
+                mint: b.mint,
+                owner: b.owner ?? null,
+                decimals: b.uiTokenAmount.decimals,
+            });
+        }
+        for (const b of postTok) {
+            const k = tokenKey(b);
+            const cur = byKey.get(k);
+            if (cur) {
+                cur.post = BigInt(b.uiTokenAmount.amount);
+                // Prefer the post-owner if the pre entry lacked one (account
+                // freshly initialized inside the tx).
+                if (cur.owner === null && b.owner)
+                    cur.owner = b.owner;
+            }
+            else {
+                byKey.set(k, {
+                    pre: 0n,
+                    post: BigInt(b.uiTokenAmount.amount),
+                    mint: b.mint,
+                    owner: b.owner ?? null,
+                    decimals: b.uiTokenAmount.decimals,
+                });
+            }
+        }
+        for (const { pre: p, post: q, mint, owner, decimals } of byKey.values()) {
+            const delta = q - p;
+            if (delta === 0n)
+                continue;
+            // Skip entries where the token-account owner is unknown — filling in
+            // the mint as if it were a wallet address would be actively wrong.
+            // Matches Python's behavior in impl/solana/base.py:704-706.
+            if (owner === null)
+                continue;
+            // Symbol is not surfaced by getTransaction; use an UNKNOWN placeholder
+            // built from the first four mint characters. Mirrors the EVM decoder's
+            // UNKNOWN_<hex-slice> shape (evm_chain.ts:480) so consumers can spot
+            // unresolved tokens uniformly.
+            const symbol = `UNKNOWN_${mint.slice(0, 4)}`;
+            const splToken = new SolanaToken(this.chainId, symbol, mint, decimals);
+            AssetBalanceChange.upsert(result, owner, splToken, AssetBalanceChange.fromMr(delta, decimals));
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=solana_chain.js.map