@ironwallet/mcp-server 1.1.0 → 1.2.0

package/dist/api/history/providers/esplora.js

@@ -0,0 +1,100 @@
+/**
+ * Esplora REST API (blockstream.info, mempool.space, litecoinspace.org).
+ * `/address/{a}/txs` returns mempool + the newest 25 confirmed transactions;
+ * `/address/{a}/txs/chain/{last_seen_txid}` pages further. One source; the
+ * page cursor is the last confirmed txid we saw. Direction and amount are
+ * derived from the wallet's share of inputs and outputs.
+ */
+import { NATIVE_SYMBOL } from "../../balances.js";
+import { httpJson } from "../../http.js";
+import { amountOf, asString, feeOf, pendingTs, timeFrom, toBigInt } from "../normalize.js";
+/**
+ * Wallet-relative view of a UTXO transaction. `sent` = value of our inputs,
+ * `received` = value of our outputs. Out: amount = what left to others
+ * (inputs − change − fee). In: amount = what we received.
+ */
+export function utxoSummary(inputs, outputs, address) {
+    const ours = (io) => io.address === address;
+    const sent = inputs.filter(ours).reduce((s, io) => s + io.value, 0n);
+    const received = outputs.filter(ours).reduce((s, io) => s + io.value, 0n);
+    const otherOutputs = outputs.filter((io) => !ours(io) && io.address);
+    const otherInputs = inputs.filter((io) => !ours(io) && io.address);
+    if (sent > 0n) {
+        const toOthers = otherOutputs.reduce((s, io) => s + io.value, 0n);
+        if (toOthers === 0n) {
+            return { direction: "self", amount: amountOf(received, 8), from: address, to: address };
+        }
+        return {
+            direction: "out",
+            amount: amountOf(toOthers, 8),
+            from: address,
+            to: otherOutputs[0]?.address ?? null,
+        };
+    }
+    return {
+        direction: "in",
+        amount: amountOf(received, 8),
+        from: otherInputs[0]?.address ?? null,
+        to: address,
+    };
+}
+export function mapEsploraTx(tx, address, network) {
+    const hash = asString(tx.txid);
+    if (!hash)
+        return null;
+    const confirmed = tx.status?.confirmed === true;
+    const time = confirmed ? timeFrom(tx.status?.block_time) : null;
+    const inputs = (tx.vin ?? []).map((v) => ({
+        address: asString(v.prevout?.scriptpubkey_address),
+        value: toBigInt(v.prevout?.value ?? 0),
+    }));
+    const outputs = (tx.vout ?? []).map((v) => ({
+        address: asString(v.scriptpubkey_address),
+        value: toBigInt(v.value ?? 0),
+    }));
+    const feeRaw = toBigInt(tx.fee ?? 0);
+    const summary = utxoSummary(inputs, outputs, address);
+    const symbol = NATIVE_SYMBOL[network];
+    const item = {
+        hash,
+        timestamp: time?.iso ?? null,
+        block: confirmed && typeof tx.status?.block_height === "number" ? tx.status.block_height : null,
+        kind: "transfer",
+        direction: summary.direction,
+        status: confirmed ? "confirmed" : "pending",
+        from: summary.from,
+        to: summary.to,
+        asset: { symbol, contractAddress: null, decimals: 8 },
+        amount: summary.amount,
+        fee: summary.direction === "in" ? null : feeOf(feeRaw, 8, symbol),
+    };
+    return { ts: time?.ts ?? pendingTs(), item };
+}
+export function esploraProvider(baseUrl, address, network) {
+    const label = /mempool\.space/i.test(baseUrl)
+        ? "mempool.space"
+        : /blockstream/i.test(baseUrl)
+            ? "blockstream"
+            : /litecoinspace/i.test(baseUrl)
+                ? "litecoinspace"
+                : "esplora";
+    const source = {
+        name: "utxo",
+        async fetchPage(cursor, _pageSize, ctx) {
+            const url = cursor === null
+                ? `${baseUrl}/address/${encodeURIComponent(address)}/txs`
+                : `${baseUrl}/address/${encodeURIComponent(address)}/txs/chain/${encodeURIComponent(cursor)}`;
+            const rows = await httpJson(url, { method: "GET" }, { ...ctx.http, label: "history.esplora" });
+            if (!Array.isArray(rows))
+                throw new Error("esplora: unexpected response");
+            const items = rows.map((tx) => mapEsploraTx(tx, address, network)).filter((x) => x !== null);
+            // Esplora pages hold 25 confirmed txs; fewer means we reached the end.
+            const confirmed = rows.filter((tx) => tx.status?.confirmed === true);
+            const last = confirmed[confirmed.length - 1]?.txid;
+            const next = confirmed.length < 25 || !last ? null : last;
+            return { items, next };
+        },
+    };
+    return { label, sources: [source] };
+}
+//# sourceMappingURL=esplora.js.map

package/dist/api/history/providers/esplora.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"esplora.js","sourceRoot":"","sources":["../../../../src/api/history/providers/esplora.ts"],"names":[],"mappings":"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"}

package/dist/api/history/providers/etherscan.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Etherscan-compatible `module=account` API (Blockscout, Routescan/Snowtrace).
+ * Two newest-first sources: `txlist` (native transfers + contract calls made or
+ * received by the address) and `tokentx` (ERC-20 transfers). Page-based
+ * (`page` / `offset`), so a page cursor is just the page number.
+ */
+import type { NetworkId } from "../../../networks.js";
+import { type HistoryProvider, type SourceItem } from "../types.js";
+interface EtherscanEnvelope {
+    status?: string;
+    message?: string;
+    result?: unknown;
+}
+export interface EtherscanTx {
+    blockNumber?: string;
+    timeStamp?: string;
+    hash?: string;
+    from?: string;
+    to?: string;
+    value?: string;
+    gasPrice?: string;
+    gasUsed?: string;
+    isError?: string;
+    txreceipt_status?: string;
+    input?: string;
+    contractAddress?: string;
+    /** tokentx only */
+    tokenSymbol?: string;
+    tokenDecimal?: string;
+}
+/** Empty result sets come back as status "0" with a "No … found" message; treat as []. */
+export declare function unwrapEtherscanResult(res: EtherscanEnvelope, label: string): EtherscanTx[];
+export declare function mapNativeTx(tx: EtherscanTx, address: string, network: NetworkId): SourceItem | null;
+export declare function mapTokenTx(tx: EtherscanTx, address: string, network: NetworkId): SourceItem | null;
+export declare function etherscanProvider(baseUrl: string, address: string, network: NetworkId): HistoryProvider;
+export {};

package/dist/api/history/providers/etherscan.js

@@ -0,0 +1,118 @@
+/**
+ * Etherscan-compatible `module=account` API (Blockscout, Routescan/Snowtrace).
+ * Two newest-first sources: `txlist` (native transfers + contract calls made or
+ * received by the address) and `tokentx` (ERC-20 transfers). Page-based
+ * (`page` / `offset`), so a page cursor is just the page number.
+ */
+import { NATIVE_SYMBOL } from "../../balances.js";
+import { httpJson } from "../../http.js";
+import { amountOf, asString, clampDecimals, directionOf, evmAddressMatcher, feeOf, timeFrom, tokenAsset, toBigInt, toBlockNumber, } from "../normalize.js";
+import { HISTORY_MAX_LIMIT, } from "../types.js";
+/** Empty result sets come back as status "0" with a "No … found" message; treat as []. */
+export function unwrapEtherscanResult(res, label) {
+    if (Array.isArray(res.result))
+        return res.result;
+    const message = `${res.message ?? ""} ${typeof res.result === "string" ? res.result : ""}`;
+    if (/no (transactions|token transfers|records) found/i.test(message))
+        return [];
+    throw new Error(`${label}: ${message.trim() || "unexpected response"}`);
+}
+export function mapNativeTx(tx, address, network) {
+    const hash = asString(tx.hash);
+    if (!hash)
+        return null;
+    const time = timeFrom(tx.timeStamp);
+    const isSelf = evmAddressMatcher(address);
+    const from = asString(tx.from);
+    const to = asString(tx.to) ?? asString(tx.contractAddress);
+    const value = toBigInt(tx.value);
+    const input = tx.input ?? "0x";
+    const failed = tx.isError === "1" || tx.txreceipt_status === "0";
+    const direction = directionOf(from, to, isSelf);
+    const feeRaw = toBigInt(tx.gasUsed) * toBigInt(tx.gasPrice);
+    const symbol = NATIVE_SYMBOL[network];
+    const item = {
+        hash,
+        timestamp: time?.iso ?? null,
+        block: toBlockNumber(tx.blockNumber),
+        kind: value > 0n ? "transfer" : input.length > 2 ? "contract_call" : "other",
+        direction,
+        status: failed ? "failed" : "confirmed",
+        from,
+        to,
+        asset: { symbol, contractAddress: null, decimals: 18 },
+        amount: amountOf(value, 18),
+        fee: direction === "in" ? null : feeOf(feeRaw, 18, symbol),
+    };
+    return { ts: time?.ts ?? 0, item };
+}
+export function mapTokenTx(tx, address, network) {
+    const hash = asString(tx.hash);
+    const contract = asString(tx.contractAddress);
+    if (!hash || !contract)
+        return null;
+    const time = timeFrom(tx.timeStamp);
+    const isSelf = evmAddressMatcher(address);
+    const from = asString(tx.from);
+    const to = asString(tx.to);
+    const decimals = clampDecimals(tx.tokenDecimal, 18);
+    const direction = directionOf(from, to, isSelf);
+    const feeRaw = toBigInt(tx.gasUsed) * toBigInt(tx.gasPrice);
+    const item = {
+        hash,
+        timestamp: time?.iso ?? null,
+        block: toBlockNumber(tx.blockNumber),
+        kind: "token_transfer",
+        direction,
+        status: "confirmed",
+        from,
+        to,
+        asset: tokenAsset(tx.tokenSymbol, "TOKEN", contract, decimals),
+        amount: amountOf(toBigInt(tx.value), decimals),
+        fee: direction === "in" ? null : feeOf(feeRaw, 18, NATIVE_SYMBOL[network]),
+    };
+    return { ts: time?.ts ?? 0, item };
+}
+function pageNumber(cursor) {
+    if (cursor === null)
+        return 1;
+    const n = Number.parseInt(cursor, 10);
+    if (!Number.isInteger(n) || n < 1)
+        throw new Error("Invalid cursor for etherscan source.");
+    return n;
+}
+/**
+ * `page` only means something for a fixed `offset` (page size), and the
+ * cursor must survive a different `limit` on the next call — so the size
+ * requested by the merge is ignored and every page is PAGE_SIZE rows.
+ */
+const PAGE_SIZE = HISTORY_MAX_LIMIT;
+function makeSource(name, action, baseUrl, address, network, map) {
+    return {
+        name,
+        async fetchPage(cursor, _pageSize, ctx) {
+            const page = pageNumber(cursor);
+            const url = `${baseUrl}?module=account&action=${action}&address=${encodeURIComponent(address)}` +
+                `&page=${page}&offset=${PAGE_SIZE}&sort=desc`;
+            const res = await httpJson(url, { method: "GET" }, { ...ctx.http, label: `history.etherscan.${action}` });
+            const rows = unwrapEtherscanResult(res, `etherscan ${action}`);
+            const items = rows.map((tx) => map(tx, address, network)).filter((x) => x !== null);
+            return { items, next: rows.length < PAGE_SIZE ? null : String(page + 1) };
+        },
+    };
+}
+export function etherscanProvider(baseUrl, address, network) {
+    const label = /blockscout\.com/i.test(baseUrl)
+        ? "blockscout"
+        : /routescan\.io|snowtrace/i.test(baseUrl)
+            ? "routescan"
+            : "etherscan-compatible";
+    return {
+        label,
+        sources: [
+            makeSource("native", "txlist", baseUrl, address, network, mapNativeTx),
+            makeSource("erc20", "tokentx", baseUrl, address, network, mapTokenTx),
+        ],
+    };
+}
+//# sourceMappingURL=etherscan.js.map

package/dist/api/history/providers/etherscan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"etherscan.js","sourceRoot":"","sources":["../../../../src/api/history/providers/etherscan.ts"],"names":[],"mappings":"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"}

package/dist/api/history/providers/nodereal.d.ts

@@ -0,0 +1,27 @@
+/**
+ * NodeReal BSC explorer backend (the API behind bsctrace.com). Undocumented and
+ * keyless; the only keyless address-scoped BSC history we found. Two sources:
+ * `external` (top-level transactions) and `20` (BEP-20 transfers). Page-based.
+ * Any non-2xx (including its odd HTTP 566) fails the source so the tool can
+ * report "unavailable" instead of an empty history.
+ */
+import type { NetworkId } from "../../../networks.js";
+import { type HistoryProvider, type SourceItem } from "../types.js";
+export interface NodeRealTransfer {
+    category?: string;
+    blockNum?: string;
+    from?: string;
+    to?: string;
+    value?: string;
+    asset?: string;
+    hash?: string;
+    contractAddress?: string;
+    decimal?: string;
+    blockTimeStamp?: number;
+    gasPrice?: number;
+    gasUsed?: number;
+    receiptsStatus?: number;
+    input?: string;
+}
+export declare function mapNodeRealTransfer(row: NodeRealTransfer, address: string, network: NetworkId): SourceItem | null;
+export declare function noderealProvider(baseUrl: string, address: string, network: NetworkId): HistoryProvider;

package/dist/api/history/providers/nodereal.js

@@ -0,0 +1,93 @@
+/**
+ * NodeReal BSC explorer backend (the API behind bsctrace.com). Undocumented and
+ * keyless; the only keyless address-scoped BSC history we found. Two sources:
+ * `external` (top-level transactions) and `20` (BEP-20 transfers). Page-based.
+ * Any non-2xx (including its odd HTTP 566) fails the source so the tool can
+ * report "unavailable" instead of an empty history.
+ */
+import { NATIVE_SYMBOL } from "../../balances.js";
+import { httpJson } from "../../http.js";
+import { amountOf, asString, clampDecimals, directionOf, evmAddressMatcher, feeOf, timeFrom, tokenAsset, toBigInt, toBlockNumber, } from "../normalize.js";
+import { HISTORY_MAX_LIMIT, } from "../types.js";
+const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+export function mapNodeRealTransfer(row, address, network) {
+    const hash = asString(row.hash);
+    if (!hash)
+        return null;
+    const time = timeFrom(row.blockTimeStamp);
+    const isSelf = evmAddressMatcher(address);
+    const from = asString(row.from);
+    const to = asString(row.to);
+    const direction = directionOf(from, to, isSelf);
+    const value = toBigInt(row.value);
+    const failed = row.receiptsStatus === 0;
+    const feeRaw = toBigInt(row.gasUsed) * toBigInt(row.gasPrice);
+    const nativeSymbol = NATIVE_SYMBOL[network];
+    const isToken = row.category === "20";
+    const contract = asString(row.contractAddress);
+    const item = {
+        hash,
+        timestamp: time?.iso ?? null,
+        block: toBlockNumber(row.blockNum),
+        kind: isToken
+            ? "token_transfer"
+            : value > 0n
+                ? "transfer"
+                : (row.input ?? "0x").length > 2
+                    ? "contract_call"
+                    : "other",
+        direction,
+        status: failed ? "failed" : "confirmed",
+        from,
+        to,
+        asset: isToken
+            ? tokenAsset(row.asset, "TOKEN", contract && contract !== ZERO_ADDRESS ? contract : null, clampDecimals(row.decimal, 18))
+            : { symbol: nativeSymbol, contractAddress: null, decimals: 18 },
+        amount: amountOf(value, isToken ? clampDecimals(row.decimal, 18) : 18),
+        fee: direction === "in" ? null : feeOf(feeRaw, 18, nativeSymbol),
+    };
+    return { ts: time?.ts ?? 0, item };
+}
+function pageNumber(cursor) {
+    if (cursor === null)
+        return 1;
+    const n = Number.parseInt(cursor, 10);
+    if (!Number.isInteger(n) || n < 1)
+        throw new Error("Invalid cursor for nodereal source.");
+    return n;
+}
+/**
+ * Page numbers only mean something for a fixed page size, and the cursor
+ * must survive a different `limit` on the next call — so the size requested
+ * by the merge is ignored and every page is PAGE_SIZE rows.
+ */
+const PAGE_SIZE = HISTORY_MAX_LIMIT;
+function makeSource(name, type, baseUrl, address, network) {
+    return {
+        name,
+        async fetchPage(cursor, _pageSize, ctx) {
+            const page = pageNumber(cursor);
+            const url = `${baseUrl}/tx/getAssetTransferByAddress?address=${encodeURIComponent(address)}` +
+                `&type=${type}&pageSize=${PAGE_SIZE}&page=${page}&order=desc`;
+            const res = await httpJson(url, { method: "GET" }, { ...ctx.http, label: `history.nodereal.${type}` });
+            if (res.code !== 0 || !res.data) {
+                throw new Error(`nodereal ${type}: ${res.msg ?? "unexpected response"}`);
+            }
+            const rows = res.data.list ?? [];
+            const items = rows
+                .map((row) => mapNodeRealTransfer(row, address, network))
+                .filter((x) => x !== null);
+            return { items, next: rows.length < PAGE_SIZE ? null : String(page + 1) };
+        },
+    };
+}
+export function noderealProvider(baseUrl, address, network) {
+    return {
+        label: "nodereal",
+        sources: [
+            makeSource("native", "external", baseUrl, address, network),
+            makeSource("bep20", "20", baseUrl, address, network),
+        ],
+    };
+}
+//# sourceMappingURL=nodereal.js.map

package/dist/api/history/providers/nodereal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodereal.js","sourceRoot":"","sources":["../../../../src/api/history/providers/nodereal.ts"],"names":[],"mappings":"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"}

package/dist/api/history/providers/solana.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Solana JSON-RPC: getSignaturesForAddress → one batched getTransaction call
+ * (jsonParsed). Amounts are the wallet's lamport / token balance deltas from
+ * the transaction meta, so swaps and program interactions show what actually
+ * left or arrived. Cursor = last signature (`before`). Memos are deliberately
+ * not surfaced: they are free-form text from strangers.
+ */
+import type { HistoryProvider, SourceItem } from "../types.js";
+interface SignatureInfo {
+    signature?: string;
+    slot?: number;
+    blockTime?: number | null;
+    err?: unknown;
+}
+interface TokenBalance {
+    accountIndex?: number;
+    mint?: string;
+    owner?: string;
+    uiTokenAmount?: {
+        amount?: string;
+        decimals?: number;
+    };
+}
+export interface SolanaTx {
+    slot?: number;
+    blockTime?: number | null;
+    meta?: {
+        err?: unknown;
+        fee?: number;
+        preBalances?: number[];
+        postBalances?: number[];
+        preTokenBalances?: TokenBalance[];
+        postTokenBalances?: TokenBalance[];
+    } | null;
+    transaction?: {
+        message?: {
+            accountKeys?: Array<{
+                pubkey?: string;
+                signer?: boolean;
+            } | string>;
+        };
+    };
+}
+/** Wallet-relative items for one transaction (one per asset that moved). */
+export declare function mapSolanaTx(signature: string, tx: SolanaTx | null, info: SignatureInfo, address: string): SourceItem[];
+export declare function solanaProvider(rpcUrl: string, address: string): HistoryProvider;
+export {};

package/dist/api/history/providers/solana.js

@@ -0,0 +1,211 @@
+/**
+ * Solana JSON-RPC: getSignaturesForAddress → one batched getTransaction call
+ * (jsonParsed). Amounts are the wallet's lamport / token balance deltas from
+ * the transaction meta, so swaps and program interactions show what actually
+ * left or arrived. Cursor = last signature (`before`). Memos are deliberately
+ * not surfaced: they are free-form text from strangers.
+ */
+import { httpJson } from "../../http.js";
+import { amountOf, asString, feeOf, pendingTs, sanitizeSymbol, timeFrom, toBigInt } from "../normalize.js";
+function keyOf(entry) {
+    if (typeof entry === "string")
+        return entry;
+    return asString(entry?.pubkey);
+}
+/** Wallet-relative items for one transaction (one per asset that moved). */
+export function mapSolanaTx(signature, tx, info, address) {
+    const time = timeFrom(tx?.blockTime ?? info.blockTime ?? undefined);
+    const ts = time?.ts ?? pendingTs();
+    const failed = (tx?.meta?.err ?? info.err) != null;
+    const base = {
+        hash: signature,
+        timestamp: time?.iso ?? null,
+        block: typeof (tx?.slot ?? info.slot) === "number" ? (tx?.slot ?? info.slot) : null,
+        status: failed ? "failed" : "confirmed",
+    };
+    const meta = tx?.meta;
+    const keys = (tx?.transaction?.message?.accountKeys ?? []).map(keyOf);
+    const selfIndex = keys.indexOf(address);
+    if (!meta || selfIndex === -1) {
+        return [
+            {
+                ts,
+                item: {
+                    ...base,
+                    kind: "other",
+                    direction: "in",
+                    from: null,
+                    to: address,
+                    asset: { symbol: "SOL", contractAddress: null, decimals: 9 },
+                    amount: amountOf(0n, 9),
+                    fee: null,
+                },
+            },
+        ];
+    }
+    const feePayer = keys[0] === address;
+    const fee = toBigInt(meta.fee ?? 0);
+    const feeInfo = feePayer ? feeOf(fee, 9, "SOL") : null;
+    const items = [];
+    // SPL deltas for token accounts owned by this wallet, per mint.
+    const tokenDelta = new Map();
+    const addTokens = (balances, sign) => {
+        for (const b of balances ?? []) {
+            if (b.owner !== address || !b.mint)
+                continue;
+            const amount = toBigInt(b.uiTokenAmount?.amount ?? "0") * sign;
+            const prev = tokenDelta.get(b.mint) ?? { delta: 0n, decimals: b.uiTokenAmount?.decimals ?? 0 };
+            tokenDelta.set(b.mint, { delta: prev.delta + amount, decimals: prev.decimals });
+        }
+    };
+    addTokens(meta.preTokenBalances, -1n);
+    addTokens(meta.postTokenBalances, 1n);
+    // Counterparty owners for the same mint (opposite sign).
+    const ownerDeltaByMint = new Map();
+    const addOwners = (balances, sign) => {
+        for (const b of balances ?? []) {
+            if (!b.mint || !b.owner || b.owner === address)
+                continue;
+            const byOwner = ownerDeltaByMint.get(b.mint) ?? new Map();
+            byOwner.set(b.owner, (byOwner.get(b.owner) ?? 0n) + toBigInt(b.uiTokenAmount?.amount ?? "0") * sign);
+            ownerDeltaByMint.set(b.mint, byOwner);
+        }
+    };
+    addOwners(meta.preTokenBalances, -1n);
+    addOwners(meta.postTokenBalances, 1n);
+    for (const [mint, { delta, decimals }] of tokenDelta) {
+        if (delta === 0n)
+            continue;
+        const direction = delta < 0n ? "out" : "in";
+        let counterparty = null;
+        let best = 0n;
+        for (const [owner, d] of ownerDeltaByMint.get(mint) ?? []) {
+            if (direction === "out" ? d > best : d < best) {
+                best = d;
+                counterparty = owner;
+            }
+        }
+        items.push({
+            ts,
+            item: {
+                ...base,
+                kind: "token_transfer",
+                direction,
+                from: direction === "out" ? address : counterparty,
+                to: direction === "out" ? counterparty : address,
+                asset: { symbol: sanitizeSymbol(null, "SPL"), contractAddress: mint, decimals },
+                amount: amountOf(delta, decimals),
+                fee: items.length === 0 && direction === "out" ? feeInfo : null,
+            },
+        });
+    }
+    const pre = toBigInt(meta.preBalances?.[selfIndex] ?? 0);
+    const post = toBigInt(meta.postBalances?.[selfIndex] ?? 0);
+    const solDelta = post - pre + (feePayer ? fee : 0n);
+    if (solDelta !== 0n) {
+        const direction = solDelta < 0n ? "out" : "in";
+        let counterparty = null;
+        let best = 0n;
+        keys.forEach((key, i) => {
+            if (!key || i === selfIndex)
+                return;
+            const d = toBigInt(meta.postBalances?.[i] ?? 0) - toBigInt(meta.preBalances?.[i] ?? 0);
+            if (direction === "out" ? d > best : d < best) {
+                best = d;
+                counterparty = key;
+            }
+        });
+        items.push({
+            ts,
+            item: {
+                ...base,
+                kind: "transfer",
+                direction,
+                from: direction === "out" ? address : counterparty,
+                to: direction === "out" ? counterparty : address,
+                asset: { symbol: "SOL", contractAddress: null, decimals: 9 },
+                amount: amountOf(solDelta, 9),
+                fee: items.length === 0 && direction === "out" ? feeInfo : null,
+            },
+        });
+    }
+    if (items.length === 0) {
+        items.push({
+            ts,
+            item: {
+                ...base,
+                kind: "contract_call",
+                direction: feePayer ? "out" : "in",
+                from: feePayer ? address : keys[0] ?? null,
+                to: feePayer ? null : address,
+                asset: { symbol: "SOL", contractAddress: null, decimals: 9 },
+                amount: amountOf(0n, 9),
+                fee: feeInfo,
+            },
+        });
+    }
+    return items;
+}
+const TX_CONCURRENCY = 5;
+export function solanaProvider(rpcUrl, address) {
+    const label = /publicnode/i.test(rpcUrl) ? "solana-publicnode" : "solana-rpc";
+    const source = {
+        name: "sol",
+        async fetchPage(cursor, pageSize, ctx) {
+            const opts = { ...ctx.http, retry: true };
+            const sigRes = await httpJson(rpcUrl, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    jsonrpc: "2.0",
+                    id: 1,
+                    method: "getSignaturesForAddress",
+                    params: [address, { limit: pageSize, ...(cursor ? { before: cursor } : {}) }],
+                }),
+            }, { ...opts, label: "history.solana.signatures" });
+            if (sigRes.error)
+                throw new Error(`solana getSignaturesForAddress: ${sigRes.error.message}`);
+            const infos = (sigRes.result ?? []).filter((s) => typeof s.signature === "string");
+            if (infos.length === 0)
+                return { items: [], next: null };
+            // One getTransaction per request with bounded concurrency: publicnode
+            // rejects batches with more than one getTransaction, and mainnet-beta
+            // answers big batches with per-item 429s. Any failed detail fails the
+            // page (→ next RPC in the chain) instead of degrading rows to "other".
+            const details = new Array(infos.length).fill(null);
+            let nextIndex = 0;
+            const worker = async () => {
+                for (;;) {
+                    const i = nextIndex++;
+                    if (i >= infos.length)
+                        return;
+                    const res = await httpJson(rpcUrl, {
+                        method: "POST",
+                        headers: { "Content-Type": "application/json" },
+                        body: JSON.stringify({
+                            jsonrpc: "2.0",
+                            id: i,
+                            method: "getTransaction",
+                            params: [
+                                infos[i].signature,
+                                { encoding: "jsonParsed", maxSupportedTransactionVersion: 0, commitment: "confirmed" },
+                            ],
+                        }),
+                    }, { ...opts, retries: 0, label: "history.solana.transaction" });
+                    if (res.error)
+                        throw new Error(`solana getTransaction: ${res.error.message}`);
+                    details[i] = res.result ?? null;
+                }
+            };
+            await Promise.all(Array.from({ length: Math.min(TX_CONCURRENCY, infos.length) }, worker));
+            const items = [];
+            infos.forEach((info, i) => {
+                items.push(...mapSolanaTx(info.signature, details[i], info, address));
+            });
+            const last = infos[infos.length - 1].signature;
+            return { items, next: infos.length < pageSize ? null : last };
+        },
+    };
+    return { label, sources: [source] };
+}
+//# sourceMappingURL=solana.js.map