@ironwallet/mcp-server 1.0.3 → 1.2.0

package/dist/api/history/merge.js

@@ -0,0 +1,208 @@
+/**
+ * K-way merge of newest-first sources with a resumable cursor.
+ *
+ * Each source is a paged stream. Per source we remember which page we are on
+ * (`cursor`, the value that fetched it) and how many items of that page were
+ * already emitted (`skip`). Re-fetching a partially consumed page and skipping
+ * is what makes partial consumption exact for cursor-only APIs (TronGrid
+ * fingerprints, Esplora last_seen_txid, Solana `before`), where a mid-page
+ * cursor cannot be synthesized.
+ *
+ * Per call we load at most two pages per source, so a window always holds at
+ * least `limit` items unless the source is exhausted. The merge then emits up
+ * to `limit` items strictly by timestamp. If some source has an empty window
+ * but is not exhausted (an API returned fewer rows than asked), we stop early
+ * rather than emit out-of-order items — unless nothing was emitted yet, in
+ * which case progress beats perfect ordering.
+ *
+ * Offset-paged indexers (Etherscan-compatible, NodeReal, TronScan, TonCenter)
+ * drift when a new transaction lands between two calls: every page shifts by
+ * one and the last row of the previous page shows up again. The cursor
+ * therefore also carries the boundary — the oldest emitted timestamp and the
+ * hashes emitted at it — and later pages drop anything newer than or equal to
+ * that boundary. Newer rows are either duplicates or transactions that arrived
+ * after the first page; both belong to a fresh query, not to page N.
+ */
+const CURSOR_VERSION = 1;
+export function encodeCursor(state) {
+    return Buffer.from(JSON.stringify(state), "utf8").toString("base64url");
+}
+export function decodeCursor(cursor) {
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+    }
+    catch {
+        throw new Error("Invalid cursor: not a cursor issued by get_transaction_history.");
+    }
+    if (!parsed ||
+        typeof parsed !== "object" ||
+        parsed.v !== CURSOR_VERSION ||
+        typeof parsed.p !== "string" ||
+        !parsed.s ||
+        typeof parsed.s !== "object") {
+        throw new Error("Invalid cursor: unsupported format. Call again without cursor.");
+    }
+    const state = parsed;
+    for (const [name, st] of Object.entries(state.s)) {
+        if (!st ||
+            typeof st !== "object" ||
+            (st.cursor !== null && typeof st.cursor !== "string") ||
+            !Number.isInteger(st.skip) ||
+            st.skip < 0 ||
+            typeof st.done !== "boolean") {
+            throw new Error(`Invalid cursor: bad state for source "${name}".`);
+        }
+    }
+    if (state.b !== undefined) {
+        const b = state.b;
+        if (!b ||
+            typeof b !== "object" ||
+            !Number.isFinite(b.ts) ||
+            !Array.isArray(b.h) ||
+            b.h.some((h) => typeof h !== "string")) {
+            throw new Error("Invalid cursor: bad boundary.");
+        }
+    }
+    return state;
+}
+/** True when a row is at or above the boundary, i.e. already emitted or newer than page 1. */
+function beforeBoundary(item, b) {
+    if (!b)
+        return false;
+    return item.ts > b.ts || (item.ts === b.ts && b.h.includes(item.item.hash));
+}
+async function loadWindow(source, state, limit, ctx, boundary) {
+    if (state.done)
+        return { source, entries: [], exhausted: true, state };
+    const entries = [];
+    let pageCursor = state.cursor;
+    let skip = state.skip;
+    let exhausted = false;
+    for (let pages = 0; pages < 2; pages++) {
+        const page = await source.fetchPage(pageCursor, limit, ctx);
+        const items = page.items;
+        for (let i = skip; i < items.length; i++) {
+            const lastOfPage = i === items.length - 1;
+            const after = lastOfPage && page.next === null
+                ? { cursor: pageCursor, skip: i + 1, done: true }
+                : lastOfPage
+                    ? { cursor: page.next, skip: 0, done: false }
+                    : { cursor: pageCursor, skip: i + 1, done: false };
+            // Drifted duplicates and rows newer than page 1 are consumed (state
+            // advances past them) but never emitted.
+            if (beforeBoundary(items[i], boundary)) {
+                if (entries.length === 0)
+                    state = after;
+                continue;
+            }
+            entries.push({ item: items[i], after });
+        }
+        if (page.next === null) {
+            exhausted = true;
+            break;
+        }
+        if (entries.length >= limit)
+            break;
+        pageCursor = page.next;
+        skip = 0;
+    }
+    // A page that ended exactly at its boundary with `skip` covering all rows:
+    // nothing new here, but the stream continues from the next page.
+    if (entries.length === 0 && !exhausted) {
+        return { source, entries, exhausted: false, state: { cursor: pageCursor, skip: 0, done: false } };
+    }
+    if (entries.length === 0 && exhausted) {
+        return { source, entries, exhausted: true, state: { ...state, done: true } };
+    }
+    return { source, entries, exhausted, state };
+}
+const KIND_RANK = {
+    token_transfer: 0,
+    transfer: 1,
+    contract_call: 2,
+    other: 3,
+};
+/**
+ * Newest first. Ties (same millisecond — common for a token transfer and the
+ * call that carried it) go to: the row sharing the last emitted hash, then
+ * the more informative kind, then source order.
+ */
+function pickNext(windows, heads, last) {
+    let best = -1;
+    for (let i = 0; i < windows.length; i++) {
+        if (heads[i] >= windows[i].entries.length)
+            continue;
+        if (best === -1) {
+            best = i;
+            continue;
+        }
+        const a = windows[i].entries[heads[i]].item;
+        const b = windows[best].entries[heads[best]].item;
+        if (a.ts !== b.ts) {
+            if (a.ts > b.ts)
+                best = i;
+            continue;
+        }
+        const aSame = last !== undefined && a.item.hash === last.hash;
+        const bSame = last !== undefined && b.item.hash === last.hash;
+        if (aSame !== bSame) {
+            if (aSame)
+                best = i;
+            continue;
+        }
+        if (KIND_RANK[a.item.kind] < KIND_RANK[b.item.kind])
+            best = i;
+    }
+    return best;
+}
+/**
+ * @param limit    rows to emit
+ * @param pageSize rows to request per source page (defaults to `limit`); a
+ *                 refill round asks for a full page while emitting only the
+ *                 remainder, so it does not crawl in tiny requests
+ */
+export async function mergeSources(sources, limit, previous, ctx, pageSize = limit) {
+    const windows = await Promise.all(sources.map((source) => loadWindow(source, previous?.s[source.name] ?? { cursor: null, skip: 0, done: false }, Math.max(limit, pageSize), ctx, previous?.b)));
+    const heads = windows.map(() => 0);
+    const out = [];
+    let lastTs = 0;
+    for (;;) {
+        const best = pickNext(windows, heads, out[out.length - 1]);
+        if (best === -1)
+            break;
+        const entry = windows[best].entries[heads[best]];
+        // Past the limit we only continue while the next row belongs to the same
+        // transaction as the last one, so a tx is never split across pages.
+        if (out.length >= limit && entry.item.item.hash !== out[out.length - 1]?.hash)
+            break;
+        const starved = windows.some((w, i) => heads[i] >= w.entries.length && !w.exhausted && i !== best);
+        if (starved && out.length > 0)
+            break;
+        heads[best]++;
+        windows[best].state = entry.after;
+        out.push(entry.item.item);
+        lastTs = entry.item.ts;
+    }
+    const state = {};
+    let hasMore = false;
+    windows.forEach((w, i) => {
+        state[w.source.name] = w.state;
+        if (heads[i] < w.entries.length || !w.exhausted)
+            hasMore = true;
+    });
+    let boundary = previous?.b;
+    if (out.length > 0) {
+        const hashes = new Set();
+        windows.forEach((w, i) => {
+            for (let k = 0; k < heads[i]; k++) {
+                const e = w.entries[k];
+                if (e.item.ts === lastTs)
+                    hashes.add(e.item.item.hash);
+            }
+        });
+        boundary = { ts: lastTs, h: [...hashes] };
+    }
+    return { items: out, state, boundary, hasMore };
+}
+//# sourceMappingURL=merge.js.map

package/dist/api/history/merge.js.map

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

package/dist/api/history/normalize.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Helpers shared by history providers: untrusted-string hygiene, amount
+ * formatting, direction detection. Indexer payloads are attacker-influenced
+ * (anyone can deploy a token called "IGNORE PREVIOUS INSTRUCTIONS"), so token
+ * symbols are reduced to a short printable string before they reach the agent.
+ */
+import type { HistoryAmount, HistoryAsset, HistoryDirection, HistoryFee } from "./types.js";
+/**
+ * Keep only printable, non-whitespace-control characters, collapse spaces,
+ * cap the length. Falls back when nothing usable remains. `₮` (Tether's
+ * jetton ticker) is folded to `T` like the balance reader does.
+ */
+export declare function sanitizeSymbol(value: unknown, fallback: string): string;
+/** Heuristic spam flag for token symbols copied from an indexer. */
+export declare function symbolWarning(symbol: string): string | undefined;
+/** Sanitized token asset with a spam warning when the symbol looks off. */
+export declare function tokenAsset(rawSymbol: unknown, fallback: string, contractAddress: string | null, decimals: number): HistoryAsset;
+/** Token decimals from an indexer field; anything absurd becomes `fallback`. */
+export declare function clampDecimals(value: unknown, fallback: number): number;
+/** Parse a decimal or 0x-hex integer string/number into a bigint; NaN-ish → 0n. */
+export declare function toBigInt(value: unknown): bigint;
+export declare function amountOf(raw: bigint, decimals: number): HistoryAmount;
+export declare function feeOf(raw: bigint, decimals: number, symbol: string): HistoryFee | null;
+/** Seconds or milliseconds since epoch → { ts (ms), iso }. Null when unusable. */
+export declare function timeFrom(value: unknown): {
+    ts: number;
+    iso: string;
+} | null;
+/** Pending items sort to the top of the newest-first list. */
+export declare function pendingTs(): number;
+export declare function directionOf(from: string | null | undefined, to: string | null | undefined, isSelf: (candidate: string | null | undefined) => boolean): HistoryDirection;
+/** Case-insensitive comparator for hex (EVM) addresses. */
+export declare function evmAddressMatcher(self: string): (candidate: string | null | undefined) => boolean;
+/** Exact comparator for base58 / bech32 style addresses. */
+export declare function exactAddressMatcher(self: string): (candidate: string | null | undefined) => boolean;
+export declare function toBlockNumber(value: unknown): number | null;
+export declare function asString(value: unknown): string | null;

package/dist/api/history/normalize.js

@@ -0,0 +1,149 @@
+/**
+ * Helpers shared by history providers: untrusted-string hygiene, amount
+ * formatting, direction detection. Indexer payloads are attacker-influenced
+ * (anyone can deploy a token called "IGNORE PREVIOUS INSTRUCTIONS"), so token
+ * symbols are reduced to a short printable string before they reach the agent.
+ */
+import { formatUnits } from "ethers";
+const MAX_SYMBOL_LENGTH = 24;
+/**
+ * Keep only printable, non-whitespace-control characters, collapse spaces,
+ * cap the length. Falls back when nothing usable remains. `₮` (Tether's
+ * jetton ticker) is folded to `T` like the balance reader does.
+ */
+export function sanitizeSymbol(value, fallback) {
+    if (typeof value !== "string")
+        return fallback;
+    const cleaned = value
+        .replaceAll("₮", "T")
+        .replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, "")
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, MAX_SYMBOL_LENGTH)
+        .trim();
+    return cleaned.length > 0 ? cleaned : fallback;
+}
+const LINK_IN_SYMBOL = /https?:|www\.|t\.me|\.(com|net|org|io|club|xyz|me|app|site|top|info|pro|cc|link|live|online|vip|fun|finance|gift|claim)\b/i;
+/** Heuristic spam flag for token symbols copied from an indexer. */
+export function symbolWarning(symbol) {
+    if (LINK_IN_SYMBOL.test(symbol)) {
+        return "Symbol contains a link. Unsolicited tokens like this are usually scams; do not interact with the contract.";
+    }
+    // eslint-disable-next-line no-control-regex
+    if (/[^\x20-\x7E]/.test(symbol)) {
+        return "Symbol uses non-ASCII characters, possibly imitating another ticker. Verify the contract address before trusting it.";
+    }
+    if (/[|\\/<>{}[\]]/.test(symbol) || symbol.length > 12) {
+        return "Unusual symbol for a token. Verify the contract address before trusting it.";
+    }
+    return undefined;
+}
+/** Sanitized token asset with a spam warning when the symbol looks off. */
+export function tokenAsset(rawSymbol, fallback, contractAddress, decimals) {
+    const symbol = sanitizeSymbol(rawSymbol, fallback);
+    const warning = symbol === fallback ? undefined : symbolWarning(symbol);
+    return { symbol, contractAddress, decimals, ...(warning ? { warning } : {}) };
+}
+/** Token decimals from an indexer field; anything absurd becomes `fallback`. */
+export function clampDecimals(value, fallback) {
+    const n = typeof value === "number" ? value : Number.parseInt(String(value ?? ""), 10);
+    if (!Number.isInteger(n) || n < 0 || n > 36)
+        return fallback;
+    return n;
+}
+/** Parse a decimal or 0x-hex integer string/number into a bigint; NaN-ish → 0n. */
+export function toBigInt(value) {
+    if (typeof value === "bigint")
+        return value;
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? BigInt(Math.trunc(value)) : 0n;
+    }
+    if (typeof value !== "string")
+        return 0n;
+    const s = value.trim();
+    if (s.length === 0)
+        return 0n;
+    try {
+        if (/^-?0x[0-9a-f]+$/i.test(s)) {
+            return s.startsWith("-") ? -BigInt(s.slice(1)) : BigInt(s);
+        }
+        if (/^-?\d+$/.test(s))
+            return BigInt(s);
+        // "123.0" style from some indexers.
+        const m = /^(-?\d+)\.0*$/.exec(s);
+        if (m)
+            return BigInt(m[1]);
+    }
+    catch {
+        return 0n;
+    }
+    return 0n;
+}
+export function amountOf(raw, decimals) {
+    const abs = raw < 0n ? -raw : raw;
+    return { raw: abs.toString(), formatted: formatUnits(abs, decimals) };
+}
+export function feeOf(raw, decimals, symbol) {
+    if (raw <= 0n)
+        return null;
+    return { ...amountOf(raw, decimals), symbol };
+}
+/** Seconds or milliseconds since epoch → { ts (ms), iso }. Null when unusable. */
+export function timeFrom(value) {
+    let n;
+    if (typeof value === "number")
+        n = value;
+    else if (typeof value === "string" && /^\d+$/.test(value.trim()))
+        n = Number(value.trim());
+    else if (typeof value === "string" && value.trim().length > 0) {
+        const parsed = Date.parse(value);
+        if (Number.isNaN(parsed))
+            return null;
+        return { ts: parsed, iso: new Date(parsed).toISOString() };
+    }
+    else
+        return null;
+    if (!Number.isFinite(n) || n <= 0)
+        return null;
+    // Anything below ~1e11 is seconds (that is year 5138 in seconds, 1973 in ms).
+    const ms = n < 1e11 ? n * 1000 : n;
+    return { ts: ms, iso: new Date(ms).toISOString() };
+}
+/** Pending items sort to the top of the newest-first list. */
+export function pendingTs() {
+    return Date.now();
+}
+export function directionOf(from, to, isSelf) {
+    const fromSelf = isSelf(from);
+    const toSelf = isSelf(to);
+    if (fromSelf && toSelf)
+        return "self";
+    if (fromSelf)
+        return "out";
+    return "in";
+}
+/** Case-insensitive comparator for hex (EVM) addresses. */
+export function evmAddressMatcher(self) {
+    const target = self.toLowerCase();
+    return (candidate) => typeof candidate === "string" && candidate.toLowerCase() === target;
+}
+/** Exact comparator for base58 / bech32 style addresses. */
+export function exactAddressMatcher(self) {
+    return (candidate) => candidate === self;
+}
+export function toBlockNumber(value) {
+    if (typeof value === "number")
+        return Number.isFinite(value) && value >= 0 ? Math.trunc(value) : null;
+    if (typeof value !== "string")
+        return null;
+    const s = value.trim();
+    if (/^0x[0-9a-f]+$/i.test(s))
+        return Number.parseInt(s, 16);
+    if (/^\d+$/.test(s))
+        return Number.parseInt(s, 10);
+    return null;
+}
+export function asString(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+//# sourceMappingURL=normalize.js.map

package/dist/api/history/normalize.js.map

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

package/dist/api/history/pace.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Process-wide request gates for keyless public indexers with per-IP rate
+ * limits (TonCenter ≈ 1 rps, TronGrid 3 rps). A provider's sources run in
+ * parallel and may load two pages each, so without a gate a single tool call
+ * bursts past the limit and the indexer suspends the IP for several seconds.
+ */
+/** Run `fn` no sooner than `gapMs` after the previous call through the same gate. */
+export declare function paced<T>(gate: string, gapMs: number, fn: () => Promise<T>): Promise<T>;

package/dist/api/history/pace.js

@@ -0,0 +1,17 @@
+/**
+ * Process-wide request gates for keyless public indexers with per-IP rate
+ * limits (TonCenter ≈ 1 rps, TronGrid 3 rps). A provider's sources run in
+ * parallel and may load two pages each, so without a gate a single tool call
+ * bursts past the limit and the indexer suspends the IP for several seconds.
+ */
+const gates = new Map();
+/** Run `fn` no sooner than `gapMs` after the previous call through the same gate. */
+export async function paced(gate, gapMs, fn) {
+    const now = Date.now();
+    const startAt = Math.max(now, gates.get(gate) ?? 0);
+    gates.set(gate, startAt + gapMs);
+    if (startAt > now)
+        await new Promise((resolve) => setTimeout(resolve, startAt - now));
+    return fn();
+}
+//# sourceMappingURL=pace.js.map

package/dist/api/history/pace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pace.js","sourceRoot":"","sources":["../../../src/api/history/pace.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;AAExC,qFAAqF;AACrF,MAAM,CAAC,KAAK,UAAU,KAAK,CAAI,IAAY,EAAE,KAAa,EAAE,EAAoB;IAC9E,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACpD,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,GAAG,KAAK,CAAC,CAAC;IACjC,IAAI,OAAO,GAAG,GAAG;QAAE,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC;IACtF,OAAO,EAAE,EAAE,CAAC;AACd,CAAC"}

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

@@ -0,0 +1,24 @@
+/**
+ * BlockCypher `/addrs/{a}/full` for Dogecoin. Newest first, `limit` ≤ 50,
+ * paged with `before=<block height>` (exclusive). Keyless quota is small
+ * (~100 req/h), which is fine for a wallet's occasional history check.
+ */
+import type { NetworkId } from "../../../networks.js";
+import type { HistoryProvider, SourceItem } from "../types.js";
+export interface BlockCypherTx {
+    hash?: string;
+    block_height?: number;
+    confirmed?: string;
+    received?: string;
+    fees?: number;
+    inputs?: Array<{
+        addresses?: string[];
+        output_value?: number;
+    }>;
+    outputs?: Array<{
+        addresses?: string[];
+        value?: number;
+    }>;
+}
+export declare function mapBlockCypherTx(tx: BlockCypherTx, address: string, network: NetworkId): SourceItem | null;
+export declare function blockcypherProvider(baseUrl: string, address: string, network: NetworkId): HistoryProvider;

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

@@ -0,0 +1,70 @@
+/**
+ * BlockCypher `/addrs/{a}/full` for Dogecoin. Newest first, `limit` ≤ 50,
+ * paged with `before=<block height>` (exclusive). Keyless quota is small
+ * (~100 req/h), which is fine for a wallet's occasional history check.
+ */
+import { NATIVE_SYMBOL } from "../../balances.js";
+import { httpJson } from "../../http.js";
+import { asString, feeOf, pendingTs, timeFrom, toBigInt } from "../normalize.js";
+import { utxoSummary } from "./esplora.js";
+export function mapBlockCypherTx(tx, address, network) {
+    const hash = asString(tx.hash);
+    if (!hash)
+        return null;
+    const confirmed = typeof tx.block_height === "number" && tx.block_height > 0;
+    const time = confirmed ? timeFrom(tx.confirmed) : null;
+    const inputs = (tx.inputs ?? []).map((i) => ({
+        address: i.addresses?.[0] ?? null,
+        value: toBigInt(i.output_value ?? 0),
+    }));
+    const outputs = (tx.outputs ?? []).map((o) => ({
+        address: o.addresses?.[0] ?? null,
+        value: toBigInt(o.value ?? 0),
+    }));
+    const feeRaw = toBigInt(tx.fees ?? 0);
+    const summary = utxoSummary(inputs, outputs, address);
+    const symbol = NATIVE_SYMBOL[network];
+    const item = {
+        hash,
+        timestamp: time?.iso ?? null,
+        block: confirmed ? tx.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 blockcypherProvider(baseUrl, address, network) {
+    const source = {
+        name: "utxo",
+        async fetchPage(cursor, pageSize, ctx) {
+            if (cursor !== null && !/^\d+$/.test(cursor))
+                throw new Error("Invalid cursor for blockcypher source.");
+            const url = `${baseUrl}/addrs/${encodeURIComponent(address)}/full?limit=${pageSize}` +
+                (cursor !== null ? `&before=${cursor}` : "");
+            const res = await httpJson(url, { method: "GET" }, { ...ctx.http, label: "history.blockcypher" });
+            if (res.error)
+                throw new Error(`blockcypher: ${res.error}`);
+            const rows = res.txs ?? [];
+            const items = rows.map((tx) => mapBlockCypherTx(tx, address, network)).filter((x) => x !== null);
+            const heights = rows
+                .map((tx) => tx.block_height)
+                .filter((h) => typeof h === "number" && h > 0);
+            // `before` is exclusive, so a page cut in the middle of a block would
+            // skip the rest of that block. Re-include the oldest block instead; the
+            // merge boundary drops the rows already emitted. When the whole page is
+            // one block that would loop forever, so step past it in that case.
+            const oldest = heights.length > 0 ? Math.min(...heights) : null;
+            const newest = heights.length > 0 ? Math.max(...heights) : null;
+            const next = res.hasMore && oldest !== null ? String(oldest === newest ? oldest : oldest + 1) : null;
+            return { items, next };
+        },
+    };
+    return { label: "blockcypher", sources: [source] };
+}
+//# sourceMappingURL=blockcypher.js.map

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

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

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

@@ -0,0 +1,41 @@
+/**
+ * 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 type { NetworkId } from "../../../networks.js";
+import type { HistoryItem, HistoryProvider, SourceItem } from "../types.js";
+export interface EsploraTx {
+    txid?: string;
+    fee?: number;
+    status?: {
+        confirmed?: boolean;
+        block_height?: number;
+        block_time?: number;
+    };
+    vin?: Array<{
+        prevout?: {
+            scriptpubkey_address?: string;
+            value?: number;
+        } | null;
+        is_coinbase?: boolean;
+    }>;
+    vout?: Array<{
+        scriptpubkey_address?: string;
+        value?: number;
+    }>;
+}
+export interface UtxoIo {
+    address: string | null;
+    value: bigint;
+}
+/**
+ * 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 declare function utxoSummary(inputs: UtxoIo[], outputs: UtxoIo[], address: string): Pick<HistoryItem, "direction" | "amount" | "from" | "to">;
+export declare function mapEsploraTx(tx: EsploraTx, address: string, network: NetworkId): SourceItem | null;
+export declare function esploraProvider(baseUrl: string, address: string, network: NetworkId): HistoryProvider;