@elizaos/agent 2.0.0-beta.1 → 2.0.11-beta.5

package/api/wallet.js

@@ -0,0 +1,786 @@
+/**
+ * Wallet key generation, address derivation, and balance/NFT fetching.
+ * Uses Node crypto primitives + Noble curves/hashes for key derivation.
+ * Balance data from Alchemy/Ankr (EVM), NodeReal/QuickNode (BSC RPC),
+ * and Helius (Solana) REST APIs.
+ *
+ * DEX price oracle logic lives in ./wallet-dex-prices.ts.
+ * EVM balance + NFT fetching lives in ./wallet-evm-balance.ts
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import { logger } from "@elizaos/core";
+import { secp256k1 } from "@noble/curves/secp256k1.js";
+import { keccak_256 } from "@noble/hashes/sha3.js";
+import { resolveStewardCredentialsPath } from "../config/paths.js";
+import { computeValueUsd } from "./wallet-dex-prices.js";
+// ── Re-exports from extracted modules ─────────────────────────────────
+export { computeValueUsd, DEX_PRICE_TIMEOUT_MS, DEXPAPRIKA_CHAIN_MAP, DEXSCREENER_CHAIN_MAP, fetchDexPaprikaPrices, fetchDexPrices, fetchDexScreenerPrices, WRAPPED_NATIVE, } from "./wallet-dex-prices.js";
+export { DEFAULT_EVM_CHAINS, fetchEvmBalances, resolveEvmProviderKeys, } from "./wallet-evm-balance.js";
+// ── Constants ─────────────────────────────────────────────────────────
+const FETCH_TIMEOUT_MS = 15_000;
+export const MANAGED_EVM_ADDRESS_ENV_KEY = "ELIZA_MANAGED_EVM_ADDRESS";
+export const MANAGED_SOLANA_ADDRESS_ENV_KEY = "ELIZA_MANAGED_SOLANA_ADDRESS";
+export const CLOUD_EVM_ADDRESS_ENV_KEY = "ELIZA_CLOUD_EVM_ADDRESS";
+export const CLOUD_SOLANA_ADDRESS_ENV_KEY = "ELIZA_CLOUD_SOLANA_ADDRESS";
+export const WALLET_SOURCE_EVM_ENV_KEY = "WALLET_SOURCE_EVM";
+export const WALLET_SOURCE_SOLANA_ENV_KEY = "WALLET_SOURCE_SOLANA";
+const SOLANA_WRAPPED_NATIVE_MINT = "So11111111111111111111111111111111111111112";
+const SOLANA_SPL_TOKEN_PROGRAM_ID = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
+/** Module-level cache for steward wallet addresses (avoids process.env mutation). */
+let stewardAddressCache = null;
+function normalizeWalletSource(value) {
+    if (value === "local" || value === "cloud") {
+        return value;
+    }
+    return null;
+}
+function readValidatedEvmAddress(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return null;
+    if (!/^0x[0-9a-fA-F]{40}$/.test(trimmed)) {
+        return null;
+    }
+    return trimmed;
+}
+function readValidatedSolanaAddress(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return null;
+    try {
+        const decoded = base58Decode(trimmed);
+        return decoded.length === 32 ? trimmed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function deriveLocalEvmAddress() {
+    const evmKey = process.env.EVM_PRIVATE_KEY;
+    if (!evmKey || PLACEHOLDER_RE.test(evmKey))
+        return null;
+    try {
+        return deriveEvmAddress(evmKey);
+    }
+    catch (e) {
+        logger.warn(`Bad EVM key: ${e}`);
+        return null;
+    }
+}
+function deriveLocalSolanaAddress() {
+    const solKey = process.env.SOLANA_PRIVATE_KEY;
+    if (!solKey || PLACEHOLDER_RE.test(solKey))
+        return null;
+    try {
+        return deriveSolanaAddress(solKey);
+    }
+    catch (e) {
+        logger.warn(`Bad SOL key: ${e}`);
+        return null;
+    }
+}
+function readStewardEvmAddress() {
+    const stewardEvm = stewardAddressCache?.evm?.trim() ??
+        process.env[STEWARD_EVM_ADDRESS_ENV_KEY]?.trim();
+    return readValidatedEvmAddress(stewardEvm);
+}
+function readStewardSolanaAddress() {
+    const stewardSolana = stewardAddressCache?.solana?.trim() ??
+        process.env[STEWARD_SOLANA_ADDRESS_ENV_KEY]?.trim();
+    return readValidatedSolanaAddress(stewardSolana);
+}
+function readManagedEvmAddress() {
+    const managed = readValidatedEvmAddress(process.env[MANAGED_EVM_ADDRESS_ENV_KEY]);
+    if (!managed && process.env[MANAGED_EVM_ADDRESS_ENV_KEY]?.trim()) {
+        logger.warn("Bad managed EVM address in env");
+    }
+    return managed;
+}
+function readManagedSolanaAddress() {
+    const managed = readValidatedSolanaAddress(process.env[MANAGED_SOLANA_ADDRESS_ENV_KEY]);
+    if (!managed && process.env[MANAGED_SOLANA_ADDRESS_ENV_KEY]?.trim()) {
+        logger.warn("Bad managed Solana address in env");
+    }
+    return managed;
+}
+function resolveEvmAddressForConfiguredSource(source) {
+    if (source === "local") {
+        return deriveLocalEvmAddress();
+    }
+    if (source === "cloud") {
+        return (readValidatedEvmAddress(process.env[CLOUD_EVM_ADDRESS_ENV_KEY]) ??
+            readManagedEvmAddress());
+    }
+    return null;
+}
+function resolveSolanaAddressForConfiguredSource(source) {
+    if (source === "local") {
+        return deriveLocalSolanaAddress();
+    }
+    if (source === "cloud") {
+        return (readValidatedSolanaAddress(process.env[CLOUD_SOLANA_ADDRESS_ENV_KEY]) ??
+            readManagedSolanaAddress());
+    }
+    return null;
+}
+// ── EVM key derivation (secp256k1 via @noble/curves + keccak-256) ─────
+function generateEvmPrivateKey() {
+    return `0x${crypto.randomBytes(32).toString("hex")}`;
+}
+export function deriveEvmAddress(privateKeyHex) {
+    const cleaned = privateKeyHex.startsWith("0x")
+        ? privateKeyHex.slice(2)
+        : privateKeyHex;
+    // Use @noble/curves — works in Node, Bun, and browsers.
+    // (Node's crypto.createECDH("secp256k1") fails in Bun due to BoringSSL.)
+    const pubKey = secp256k1.getPublicKey(Buffer.from(cleaned, "hex"), false); // uncompressed (65 bytes)
+    const pubNoPrefix = pubKey.subarray(1); // drop the 04 prefix
+    // Ethereum address = last 20 bytes of keccak-256(pubkey).
+    const hash = Buffer.from(keccak_256(pubNoPrefix)).toString("hex");
+    const raw = hash.slice(-40);
+    return toChecksumEvmAddress(raw);
+}
+function toChecksumEvmAddress(addressHex) {
+    const lower = addressHex.toLowerCase().replace(/^0x/, "");
+    const hash = Buffer.from(keccak_256(Buffer.from(lower, "ascii"))).toString("hex");
+    let out = "0x";
+    for (let i = 0; i < lower.length; i += 1) {
+        const char = lower[i];
+        out += Number.parseInt(hash[i], 16) >= 8 ? char.toUpperCase() : char;
+    }
+    return out;
+}
+// ── Solana key derivation (Ed25519 via Node crypto) ───────────────────
+function generateSolanaKeypair() {
+    const { privateKey, publicKey } = crypto.generateKeyPairSync("ed25519");
+    const privBytes = privateKey.export({ type: "pkcs8", format: "der" });
+    const pubBytes = publicKey.export({ type: "spki", format: "der" });
+    // Ed25519 PKCS8 DER: raw 32-byte seed at offset 16; SPKI DER: raw 32-byte pubkey at offset 12
+    const seed = privBytes.subarray(16, 48);
+    const pubRaw = pubBytes.subarray(12, 44);
+    // Solana secret key = seed(32) + pubkey(32)
+    return {
+        privateKey: base58Encode(Buffer.concat([seed, pubRaw])),
+        publicKey: base58Encode(pubRaw),
+    };
+}
+export function deriveSolanaAddress(privateKeyString) {
+    const secretBytes = decodeSolanaPrivateKey(privateKeyString);
+    if (secretBytes.length === 64)
+        return base58Encode(secretBytes.subarray(32));
+    if (secretBytes.length === 32) {
+        // Derive pubkey from 32-byte seed
+        const keyObj = crypto.createPrivateKey({
+            key: Buffer.concat([
+                Buffer.from("302e020100300506032b657004220420", "hex"),
+                secretBytes,
+            ]),
+            format: "der",
+            type: "pkcs8",
+        });
+        const pubDer = crypto
+            .createPublicKey(keyObj)
+            .export({ type: "spki", format: "der" });
+        return base58Encode(pubDer.subarray(12, 44));
+    }
+    throw new Error(`Invalid Solana secret key length: ${secretBytes.length}`);
+}
+// ── Base58 (Bitcoin alphabet) ─────────────────────────────────────────
+const B58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+function base58Encode(data) {
+    let num = BigInt(`0x${Buffer.from(data).toString("hex")}`);
+    const chars = [];
+    while (num > 0n) {
+        chars.unshift(B58[Number(num % 58n)]);
+        num /= 58n;
+    }
+    for (const byte of data) {
+        if (byte === 0)
+            chars.unshift("1");
+        else
+            break;
+    }
+    return chars.join("") || "1";
+}
+function base58Decode(str) {
+    if (str.length === 0)
+        return Buffer.alloc(0);
+    let num = 0n;
+    for (const c of str) {
+        const i = B58.indexOf(c);
+        if (i === -1)
+            throw new Error(`Invalid base58: ${c}`);
+        num = num * 58n + BigInt(i);
+    }
+    const hex = num.toString(16).padStart(2, "0");
+    const bytes = Buffer.from(hex.length % 2 ? `0${hex}` : hex, "hex");
+    let zeros = 0;
+    for (const c of str) {
+        if (c === "1")
+            zeros++;
+        else
+            break;
+    }
+    return zeros > 0 ? Buffer.concat([Buffer.alloc(zeros), bytes]) : bytes;
+}
+/** Sentinel values that appear as env placeholders – skip without error. */
+const PLACEHOLDER_RE = /^\[?\s*(REDACTED|PLACEHOLDER|T(?:O)D(?:O)|CHANGEME|EMPTY)\s*]?$/i;
+function decodeSolanaPrivateKey(key) {
+    if (PLACEHOLDER_RE.test(key)) {
+        throw new Error("placeholder value");
+    }
+    // Only attempt JSON array parse when the content looks like a numeric array
+    // e.g. [1,2,3,...] — not [REDACTED] or other bracket-wrapped strings
+    if (key.startsWith("[") && key.endsWith("]") && /^\[\s*\d/.test(key)) {
+        try {
+            const parsed = JSON.parse(key);
+            if (!Array.isArray(parsed) ||
+                !parsed.every((v) => typeof v === "number")) {
+                throw new Error("not a numeric array");
+            }
+            return Buffer.from(parsed);
+        }
+        catch {
+            throw new Error("Invalid JSON byte-array format");
+        }
+    }
+    return base58Decode(key);
+}
+// ── Key validation ────────────────────────────────────────────────────
+const HEX_RE = /^[0-9a-fA-F]+$/;
+export function validateEvmPrivateKey(key) {
+    const cleaned = key.startsWith("0x") ? key.slice(2) : key;
+    if (cleaned.length !== 64)
+        return {
+            valid: false,
+            chain: "evm",
+            address: null,
+            error: "Must be 64 hex characters",
+        };
+    if (!HEX_RE.test(cleaned))
+        return {
+            valid: false,
+            chain: "evm",
+            address: null,
+            error: "Invalid hex characters",
+        };
+    try {
+        return {
+            valid: true,
+            chain: "evm",
+            address: deriveEvmAddress(key),
+            error: null,
+        };
+    }
+    catch (err) {
+        return {
+            valid: false,
+            chain: "evm",
+            address: null,
+            error: `Derivation failed: ${String(err)}`,
+        };
+    }
+}
+export function validateSolanaPrivateKey(key) {
+    try {
+        const bytes = decodeSolanaPrivateKey(key);
+        if (bytes.length !== 64 && bytes.length !== 32) {
+            return {
+                valid: false,
+                chain: "solana",
+                address: null,
+                error: `Must be 32 or 64 bytes, got ${bytes.length}`,
+            };
+        }
+        return {
+            valid: true,
+            chain: "solana",
+            address: deriveSolanaAddress(key),
+            error: null,
+        };
+    }
+    catch (err) {
+        return {
+            valid: false,
+            chain: "solana",
+            address: null,
+            error: `Invalid key: ${String(err)}`,
+        };
+    }
+}
+/** Auto-detect chain from key format and validate. */
+export function validatePrivateKey(key) {
+    const trimmed = key.trim();
+    if (trimmed.startsWith("0x") ||
+        (trimmed.length === 64 && HEX_RE.test(trimmed)))
+        return validateEvmPrivateKey(trimmed);
+    return validateSolanaPrivateKey(trimmed);
+}
+/** Mask a secret string for safe display (e.g. logs, UI). */
+export function maskSecret(value) {
+    if (!value || value.length <= 8)
+        return "****";
+    return `${value.slice(0, 4)}...${value.slice(-4)}`;
+}
+// ── Key generation ────────────────────────────────────────────────────
+export function generateWalletKeys() {
+    const evmPrivateKey = generateEvmPrivateKey();
+    const solana = generateSolanaKeypair();
+    return {
+        evmPrivateKey,
+        evmAddress: deriveEvmAddress(evmPrivateKey),
+        solanaPrivateKey: solana.privateKey,
+        solanaAddress: solana.publicKey,
+    };
+}
+export function generateWalletForChain(chain) {
+    if (chain === "evm") {
+        const pk = generateEvmPrivateKey();
+        return { chain, address: deriveEvmAddress(pk), privateKey: pk };
+    }
+    const sol = generateSolanaKeypair();
+    return {
+        chain: "solana",
+        address: sol.publicKey,
+        privateKey: sol.privateKey,
+    };
+}
+// Extracted to wallet-env-sync.ts to break circular dependency with config/config.ts.
+// Local import for internal use (setSolanaWalletEnv below), plus re-export for
+// backward compatibility so existing consumers of wallet.js keep working.
+import { syncSolanaPublicKeyEnv } from "./wallet-env-sync.js";
+export { syncSolanaPublicKeyEnv } from "./wallet-env-sync.js";
+export function setSolanaWalletEnv(privateKey) {
+    const trimmed = privateKey.trim();
+    process.env.SOLANA_PRIVATE_KEY = trimmed;
+    return syncSolanaPublicKeyEnv(trimmed);
+}
+/** Validate key, store in process.env. Caller persists to config if needed. */
+export function importWallet(chain, privateKey) {
+    const trimmed = privateKey.trim();
+    if (chain === "evm") {
+        const v = validateEvmPrivateKey(trimmed);
+        if (!v.valid)
+            return { success: false, chain, address: null, error: v.error };
+        process.env.EVM_PRIVATE_KEY = trimmed.startsWith("0x")
+            ? trimmed
+            : `0x${trimmed}`;
+        logger.info(`[wallet] Imported EVM wallet: ${v.address}`);
+        return { success: true, chain, address: v.address, error: null };
+    }
+    const v = validateSolanaPrivateKey(trimmed);
+    if (!v.valid)
+        return { success: false, chain, address: null, error: v.error };
+    setSolanaWalletEnv(trimmed);
+    logger.info(`[wallet] Imported Solana wallet: ${v.address}`);
+    return { success: true, chain, address: v.address, error: null };
+}
+// ── Steward wallet cache env keys ─────────────────────────────────────
+export const STEWARD_EVM_ADDRESS_ENV_KEY = "STEWARD_EVM_ADDRESS";
+export const STEWARD_SOLANA_ADDRESS_ENV_KEY = "STEWARD_SOLANA_ADDRESS";
+function normalizeOptionalString(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function readPersistedStewardCredentials() {
+    const credentialsPath = resolveStewardCredentialsPath();
+    try {
+        if (!fs.existsSync(credentialsPath)) {
+            return null;
+        }
+        const parsed = JSON.parse(fs.readFileSync(credentialsPath, "utf8"));
+        return {
+            apiUrl: normalizeOptionalString(parsed.apiUrl),
+            tenantId: normalizeOptionalString(parsed.tenantId),
+            agentId: normalizeOptionalString(parsed.agentId),
+            apiKey: normalizeOptionalString(parsed.apiKey),
+            agentToken: normalizeOptionalString(parsed.agentToken),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Initialise the steward wallet address cache.
+ *
+ * Call once during server startup.  Fetches addresses from the steward API
+ * and writes them to `process.env.STEWARD_EVM_ADDRESS` /
+ * `process.env.STEWARD_SOLANA_ADDRESS` so the synchronous
+ * `getWalletAddresses()` can use them without hitting the network.
+ */
+export async function initStewardWalletCache() {
+    const persisted = readPersistedStewardCredentials();
+    const stewardApiUrl = normalizeOptionalString(process.env.STEWARD_API_URL) ?? persisted?.apiUrl;
+    if (!stewardApiUrl)
+        return;
+    const agentId = normalizeOptionalString(process.env.STEWARD_AGENT_ID) ||
+        normalizeOptionalString(process.env.ELIZA_STEWARD_AGENT_ID) ||
+        persisted?.agentId ||
+        null;
+    if (!agentId)
+        return;
+    try {
+        const headers = { Accept: "application/json" };
+        const bearerToken = normalizeOptionalString(process.env.STEWARD_AGENT_TOKEN) ??
+            persisted?.agentToken;
+        const apiKey = normalizeOptionalString(process.env.STEWARD_API_KEY) ?? persisted?.apiKey;
+        const tenantId = normalizeOptionalString(process.env.STEWARD_TENANT_ID) ??
+            persisted?.tenantId;
+        if (bearerToken) {
+            headers.Authorization = `Bearer ${bearerToken}`;
+        }
+        else if (apiKey) {
+            headers["X-Steward-Key"] = apiKey;
+        }
+        if (tenantId) {
+            headers["X-Steward-Tenant"] = tenantId;
+        }
+        const res = await fetch(`${stewardApiUrl}/agents/${encodeURIComponent(agentId)}`, { headers, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+        if (!res.ok) {
+            logger.warn(`[wallet] Steward wallet cache init: agent lookup returned ${res.status}`);
+            return;
+        }
+        const body = (await res.json());
+        const agent = body.data ?? body;
+        const stewardEvm = agent.walletAddresses?.evm?.trim() || agent.walletAddress?.trim() || null;
+        const stewardSolana = agent.walletAddresses?.solana?.trim() || null;
+        stewardAddressCache = { evm: stewardEvm, solana: stewardSolana };
+        if (stewardEvm) {
+            process.env[STEWARD_EVM_ADDRESS_ENV_KEY] = stewardEvm;
+        }
+        else {
+            delete process.env[STEWARD_EVM_ADDRESS_ENV_KEY];
+        }
+        if (stewardSolana) {
+            process.env[STEWARD_SOLANA_ADDRESS_ENV_KEY] = stewardSolana;
+            if (!process.env.SOLANA_PUBLIC_KEY?.trim()) {
+                process.env.SOLANA_PUBLIC_KEY = stewardSolana;
+            }
+            if (!process.env.WALLET_PUBLIC_KEY?.trim()) {
+                process.env.WALLET_PUBLIC_KEY = stewardSolana;
+            }
+        }
+        else {
+            delete process.env[STEWARD_SOLANA_ADDRESS_ENV_KEY];
+        }
+        if (stewardEvm) {
+            logger.info(`[wallet] Steward EVM address cached: ${stewardEvm}`);
+        }
+        if (stewardSolana) {
+            logger.info(`[wallet] Steward Solana address cached: ${stewardSolana}`);
+        }
+    }
+    catch (err) {
+        logger.debug(`[wallet] Steward wallet cache init unavailable: ${err}`);
+    }
+}
+/**
+ * Derive addresses from env keys.  Works without a running runtime.
+ *
+ * Resolution order (steward-first):
+ *   1. Steward cached addresses  (`STEWARD_EVM_ADDRESS` / `STEWARD_SOLANA_ADDRESS`)
+ *   2. Local private key derivation  (`EVM_PRIVATE_KEY` / `SOLANA_PRIVATE_KEY`)
+ *   3. Managed address env vars  (`ELIZA_MANAGED_EVM_ADDRESS` / `ELIZA_MANAGED_SOLANA_ADDRESS`)
+ */
+export function getWalletAddresses() {
+    const configuredEvmSource = normalizeWalletSource(process.env[WALLET_SOURCE_EVM_ENV_KEY]);
+    const configuredSolanaSource = normalizeWalletSource(process.env[WALLET_SOURCE_SOLANA_ENV_KEY]);
+    let evmAddress = resolveEvmAddressForConfiguredSource(configuredEvmSource);
+    let solanaAddress = resolveSolanaAddressForConfiguredSource(configuredSolanaSource);
+    // Legacy fallback order when no explicit source selection exists yet.
+    if (!evmAddress && !configuredEvmSource) {
+        evmAddress =
+            readStewardEvmAddress() ??
+                deriveLocalEvmAddress() ??
+                readManagedEvmAddress();
+    }
+    if (!solanaAddress && !configuredSolanaSource) {
+        solanaAddress =
+            readStewardSolanaAddress() ??
+                deriveLocalSolanaAddress() ??
+                readManagedSolanaAddress();
+    }
+    return { evmAddress, solanaAddress };
+}
+/**
+ * Extended wallet addresses including steward-managed wallets.
+ * Calls steward API (async) to discover additional addresses.
+ * Key-derived addresses are always preferred; steward addresses fill gaps.
+ */
+export async function getWalletAddressesWithSteward() {
+    const base = getWalletAddresses();
+    // Only augment when steward is configured
+    const stewardApiUrl = process.env.STEWARD_API_URL?.trim();
+    if (!stewardApiUrl) {
+        return base;
+    }
+    const agentId = process.env.STEWARD_AGENT_ID?.trim() ||
+        process.env.ELIZA_STEWARD_AGENT_ID?.trim() ||
+        base.evmAddress?.trim() ||
+        null;
+    if (!agentId) {
+        return base;
+    }
+    try {
+        const headers = {
+            Accept: "application/json",
+        };
+        const bearerToken = process.env.STEWARD_AGENT_TOKEN?.trim();
+        const apiKey = process.env.STEWARD_API_KEY?.trim();
+        const tenantId = process.env.STEWARD_TENANT_ID?.trim();
+        if (bearerToken) {
+            headers.Authorization = `Bearer ${bearerToken}`;
+        }
+        else if (apiKey) {
+            headers["X-Steward-Key"] = apiKey;
+        }
+        if (tenantId) {
+            headers["X-Steward-Tenant"] = tenantId;
+        }
+        const res = await fetch(`${stewardApiUrl}/agents/${encodeURIComponent(agentId)}`, { headers, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+        if (!res.ok) {
+            logger.warn(`Steward agent lookup returned ${res.status}`);
+            return base;
+        }
+        const body = (await res.json());
+        const agent = body.data ?? body;
+        const stewardEvm = agent.walletAddresses?.evm?.trim() || agent.walletAddress?.trim() || null;
+        const stewardSolana = agent.walletAddresses?.solana?.trim() || null;
+        return {
+            evmAddress: base.evmAddress ?? stewardEvm,
+            solanaAddress: base.solanaAddress ?? stewardSolana,
+            stewardEvmAddress: stewardEvm,
+            stewardSolanaAddress: stewardSolana,
+        };
+    }
+    catch (err) {
+        logger.warn(`Steward wallet address lookup failed: ${err}`);
+        return base;
+    }
+}
+function shortenMint(mint) {
+    if (mint.length <= 10)
+        return mint;
+    return `${mint.slice(0, 4)}...${mint.slice(-4)}`;
+}
+async function fetchSolanaDexMeta(addresses) {
+    const uniqueAddresses = [
+        ...new Set(addresses.map((address) => address.trim())),
+    ].filter(Boolean);
+    const results = new Map();
+    if (uniqueAddresses.length === 0)
+        return results;
+    for (let index = 0; index < uniqueAddresses.length; index += 30) {
+        const batch = uniqueAddresses.slice(index, index + 30);
+        try {
+            const res = await fetch(`https://api.dexscreener.com/tokens/v1/solana/${batch.join(",")}`, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+            if (!res.ok)
+                continue;
+            const pairs = (await res.json());
+            if (!Array.isArray(pairs))
+                continue;
+            const bestPairByMint = new Map();
+            for (const pair of pairs) {
+                const mint = pair.baseToken?.address?.trim();
+                if (!mint)
+                    continue;
+                const existing = bestPairByMint.get(mint);
+                if (!existing ||
+                    (pair.liquidity?.usd ?? 0) > (existing.liquidity?.usd ?? 0)) {
+                    bestPairByMint.set(mint, pair);
+                }
+            }
+            for (const [mint, pair] of bestPairByMint) {
+                results.set(mint, {
+                    priceUsd: pair.priceUsd ?? null,
+                    imageUrl: pair.info?.imageUrl?.trim() || undefined,
+                    name: pair.baseToken?.name?.trim() || undefined,
+                    symbol: pair.baseToken?.symbol?.trim() || undefined,
+                });
+            }
+        }
+        catch (err) {
+            logger.warn(`[wallet] Solana DexScreener fetch failed: ${String(err)}`);
+        }
+    }
+    return results;
+}
+function buildSolanaTokenBalance(token, dexMeta) {
+    const meta = dexMeta.get(token.mint);
+    const computedValueUsd = meta?.priceUsd && meta.priceUsd.length > 0
+        ? computeValueUsd(token.balance, meta.priceUsd)
+        : "0";
+    return {
+        mint: token.mint,
+        symbol: token.symbol?.trim() ||
+            meta?.symbol?.trim() ||
+            shortenMint(token.mint).toUpperCase(),
+        name: token.name?.trim() || meta?.name?.trim() || token.mint,
+        balance: token.balance,
+        decimals: token.decimals,
+        valueUsd: token.valueUsd && Number.parseFloat(token.valueUsd) > 0
+            ? token.valueUsd
+            : computedValueUsd,
+        logoUrl: token.logoUrl?.trim() || meta?.imageUrl || "",
+    };
+}
+function rpcJsonRequest(body) {
+    return {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        body,
+    };
+}
+function describeRpcEndpoint(url) {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return "rpc";
+    }
+}
+/** Parse JSON from a fetch response. If the body isn't JSON, throw with the raw text. */
+async function jsonOrThrow(res) {
+    const text = await res.text();
+    if (!res.ok)
+        throw new Error(text.slice(0, 200) || `HTTP ${res.status}`);
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error(text.slice(0, 200) || "Invalid JSON");
+    }
+}
+export async function fetchSolanaBalances(address, heliusKey) {
+    const url = `https://mainnet.helius-rpc.com/?api-key=${heliusKey}`;
+    const rpc = (body) => ({
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        body,
+    });
+    let solBalance = "0";
+    const balanceData = await jsonOrThrow(await fetch(url, rpc(JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "getBalance",
+        params: [address],
+    }))));
+    if (balanceData.error?.message)
+        throw new Error(balanceData.error.message);
+    solBalance = ((balanceData.result?.value ?? 0) / 1e9).toFixed(9);
+    const tokenData = await jsonOrThrow(await fetch(url, rpc(JSON.stringify({
+        jsonrpc: "2.0",
+        id: 2,
+        method: "getAssetsByOwner",
+        params: {
+            ownerAddress: address,
+            displayOptions: { showFungible: true, showNativeBalance: true },
+            page: 1,
+            limit: 100,
+        },
+    }))));
+    if (tokenData.error?.message)
+        throw new Error(tokenData.error.message);
+    const fungibleAssets = (tokenData.result?.items ?? []).filter((item) => item.interface === "FungibleToken" || item.interface === "FungibleAsset");
+    const dexMeta = await fetchSolanaDexMeta([
+        SOLANA_WRAPPED_NATIVE_MINT,
+        ...fungibleAssets.map((item) => item.id),
+    ]);
+    const tokens = [];
+    for (const item of tokenData.result?.items ?? []) {
+        if (item.interface !== "FungibleToken" &&
+            item.interface !== "FungibleAsset")
+            continue;
+        const decimals = item.token_info?.decimals ?? 0;
+        const rawBalance = item.token_info?.balance ?? 0;
+        const balance = decimals > 0
+            ? (rawBalance / 10 ** decimals).toString()
+            : rawBalance.toString();
+        tokens.push(buildSolanaTokenBalance({
+            mint: item.id,
+            symbol: item.token_info?.symbol ?? item.content?.metadata?.symbol,
+            name: item.content?.metadata?.name ?? null,
+            balance,
+            decimals,
+            valueUsd: item.token_info?.price_info?.total_price?.toFixed(2) ?? null,
+            logoUrl: item.content?.links?.image ?? null,
+        }, dexMeta));
+    }
+    const solPriceUsd = dexMeta.get(SOLANA_WRAPPED_NATIVE_MINT)?.priceUsd ?? "0";
+    return {
+        solBalance,
+        solValueUsd: computeValueUsd(solBalance, solPriceUsd),
+        tokens,
+    };
+}
+export async function fetchSolanaNativeBalanceViaRpc(address, rpcUrls) {
+    const urls = [...new Set(rpcUrls)].filter((u) => Boolean(u.trim()));
+    const errors = [];
+    for (const rpcUrl of urls) {
+        try {
+            const balanceData = await jsonOrThrow(await fetch(rpcUrl, rpcJsonRequest(JSON.stringify({
+                jsonrpc: "2.0",
+                id: 1,
+                method: "getBalance",
+                params: [address],
+            }))));
+            if (balanceData.error?.message)
+                throw new Error(balanceData.error.message);
+            const tokenAccounts = await jsonOrThrow(await fetch(rpcUrl, rpcJsonRequest(JSON.stringify({
+                jsonrpc: "2.0",
+                id: 2,
+                method: "getTokenAccountsByOwner",
+                params: [
+                    address,
+                    { programId: SOLANA_SPL_TOKEN_PROGRAM_ID },
+                    { encoding: "jsonParsed" },
+                ],
+            }))));
+            if (tokenAccounts.error?.message) {
+                throw new Error(tokenAccounts.error.message);
+            }
+            const rawTokens = (tokenAccounts.result?.value ?? [])
+                .map((item) => {
+                const info = item.account?.data?.parsed?.info;
+                const mint = info?.mint?.trim();
+                const tokenAmount = info?.tokenAmount;
+                const balance = tokenAmount?.uiAmountString?.trim() ||
+                    tokenAmount?.amount?.trim() ||
+                    "0";
+                const decimals = tokenAmount?.decimals ?? 0;
+                if (!mint || Number.parseFloat(balance) <= 0)
+                    return null;
+                return {
+                    mint,
+                    balance,
+                    decimals,
+                };
+            })
+                .filter((token) => token !== null);
+            const dexMeta = await fetchSolanaDexMeta([
+                SOLANA_WRAPPED_NATIVE_MINT,
+                ...rawTokens.map((token) => token.mint),
+            ]);
+            const tokens = rawTokens.map((token) => buildSolanaTokenBalance(token, dexMeta));
+            const solBalance = ((balanceData.result?.value ?? 0) / 1e9).toFixed(9);
+            const solPriceUsd = dexMeta.get(SOLANA_WRAPPED_NATIVE_MINT)?.priceUsd ?? "0";
+            return {
+                solBalance,
+                solValueUsd: computeValueUsd(solBalance, solPriceUsd),
+                tokens,
+            };
+        }
+        catch (err) {
+            const msg = String(err);
+            errors.push(`${describeRpcEndpoint(rpcUrl)}: ${msg}`);
+        }
+    }
+    throw new Error(errors.join(" | ").slice(0, 400) || "Solana RPC unavailable");
+}