@unlink-xyz/cli 0.1.0

package/dist/commands/withdraw.js

@@ -0,0 +1,47 @@
+import { Option } from "commander";
+import { createContext } from "../lib/context.js";
+import { withErrorHandler } from "../lib/errors.js";
+import { mergeConfigDefaults, requireChainId, requireGatewayUrl, requirePoolAddress, resolveOptions, } from "../lib/options.js";
+import { log, output } from "../lib/output.js";
+import { isRelaySuccess, pollRelayStatus } from "../lib/relay.js";
+export function registerWithdrawCommands(program) {
+    program
+        .command("withdraw")
+        .requiredOption("--to <address>", "Recipient EOA address (0x...)")
+        .requiredOption("--token <address>", "Token contract address")
+        .requiredOption("--amount <value>", "Amount (raw atomic units)")
+        .addOption(new Option("--wait", "Wait for relay confirmation").default(true))
+        .addOption(new Option("--no-wait", "Fire-and-forget (do not wait for confirmation)"))
+        .description("Withdraw tokens from the privacy pool to an EOA")
+        .action(withErrorHandler(async (cmdOpts, cmd) => {
+        const options = mergeConfigDefaults(resolveOptions(cmd.optsWithGlobals()));
+        requireGatewayUrl(options);
+        requireChainId(options);
+        requirePoolAddress(options);
+        const ctx = await createContext(options);
+        const activeIdx = await ctx.wallet.accounts.getActiveIndex();
+        log(`Using account #${activeIdx}`, options);
+        log("Planning and submitting withdrawal...", options);
+        const result = await ctx.wallet.withdraw({
+            withdrawals: [
+                {
+                    token: cmdOpts["token"],
+                    amount: BigInt(cmdOpts["amount"]),
+                    recipient: cmdOpts["to"],
+                },
+            ],
+        });
+        log(`Relay ID: ${result.relayId}`, options);
+        const shouldWait = cmdOpts["wait"];
+        if (shouldWait) {
+            const final = await pollRelayStatus(ctx.wallet, result.relayId, options);
+            if (!isRelaySuccess(final)) {
+                throw new Error(`Withdrawal relay ${final.relayId} ended with status "${final.status}"${final.error ? `: ${final.error}` : ""}`);
+            }
+            output(final, options);
+        }
+        else {
+            output({ relayId: result.relayId, status: "submitted" }, options);
+        }
+    }));
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "dotenv/config";

package/dist/index.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import "dotenv/config";
+import { createProgram } from "./cli.js";
+const program = createProgram();
+await program.parseAsync(process.argv);
+process.exit(0);

package/dist/lib/context.d.ts

@@ -0,0 +1,14 @@
+import { UnlinkWallet } from "@unlink-xyz/core";
+import type { ResolvedOptions } from "./options.js";
+export type CLIContext = {
+    wallet: UnlinkWallet;
+    options: ResolvedOptions;
+    gatewayUrl: string;
+};
+/**
+ * Create a CLI context.
+ * Pass `local: true` for wallet/account commands that don't need network.
+ */
+export declare function createContext(options: ResolvedOptions, opts?: {
+    local?: boolean;
+}): Promise<CLIContext>;

package/dist/lib/context.js

@@ -0,0 +1,42 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import { UnlinkWallet } from "@unlink-xyz/core";
+import { createSqliteStorage } from "../storage/sqlite.js";
+const rng = (n) => new Uint8Array(crypto.randomBytes(n));
+/**
+ * Create a CLI context.
+ * Pass `local: true` for wallet/account commands that don't need network.
+ */
+export async function createContext(options, opts) {
+    const local = opts?.local ?? false;
+    if (!local && !options.gatewayUrl) {
+        throw new Error("--gateway-url or UNLINK_GATEWAY_URL is required");
+    }
+    const gatewayUrl = local
+        ? (options.gatewayUrl ?? "http://localhost:0")
+        : options.gatewayUrl;
+    const dbPath = path.join(options.dataDir, "wallet.db");
+    const storage = createSqliteStorage({ path: dbPath });
+    await storage.open();
+    const prover = options.artifactVersion
+        ? { artifactSource: { version: options.artifactVersion } }
+        : undefined;
+    const wallet = await UnlinkWallet.create({
+        chainId: local ? 0 : options.chainId,
+        poolAddress: local
+            ? "0x0000000000000000000000000000000000000000"
+            : options.poolAddress,
+        gatewayUrl,
+        chainRpcUrl: options.nodeUrl,
+        storage,
+        rng,
+        fetch: globalThis.fetch,
+        autoSync: false,
+        prover,
+    });
+    return {
+        wallet,
+        options,
+        gatewayUrl,
+    };
+}

package/dist/lib/errors.d.ts

@@ -0,0 +1 @@
+export declare function withErrorHandler<T extends unknown[]>(fn: (...args: T) => Promise<void>): (...args: T) => Promise<void>;

package/dist/lib/errors.js

@@ -0,0 +1,24 @@
+export function withErrorHandler(fn) {
+    return async (...args) => {
+        try {
+            await fn(...args);
+        }
+        catch (err) {
+            // Commander always passes the Command object as the last argument
+            const last = args[args.length - 1];
+            const json = last !== null &&
+                typeof last === "object" &&
+                "optsWithGlobals" in last
+                ? Boolean(last.optsWithGlobals()["json"])
+                : false;
+            const message = err instanceof Error ? err.message : String(err);
+            if (json) {
+                process.stderr.write(JSON.stringify({ error: message }) + "\n");
+            }
+            else {
+                process.stderr.write(`Error: ${message}\n`);
+            }
+            process.exit(1);
+        }
+    };
+}

package/dist/lib/multisig-store.d.ts

@@ -0,0 +1,8 @@
+import { type MultisigAccount } from "@unlink-xyz/multisig";
+export type MultisigAccountRef = {
+    groupId: string;
+    participantIndex: number;
+};
+export declare function saveMultisigAccount(dataDir: string, account: MultisigAccount): Promise<void>;
+export declare function loadMultisigAccount(dataDir: string, groupId: string, participantIndex?: number): Promise<MultisigAccount>;
+export declare function listMultisigAccounts(dataDir: string): Promise<MultisigAccountRef[]>;

package/dist/lib/multisig-store.js

@@ -0,0 +1,121 @@
+import { mkdir, readdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { deserializeMultisigAccount, serializeMultisigAccount, } from "@unlink-xyz/multisig";
+const MULTISIG_DIR = "multisig";
+const FILE_SUFFIX = ".json";
+const FILENAME_RE = /^(.*)__p([1-9][0-9]*)\.json$/;
+function multisigDir(dataDir) {
+    return join(dataDir, MULTISIG_DIR);
+}
+function toRef(account) {
+    assertParticipantIndex(account.participantIndex);
+    return {
+        groupId: account.groupId,
+        participantIndex: account.participantIndex,
+    };
+}
+function filename(ref) {
+    const encodedGroupId = encodeURIComponent(ref.groupId);
+    return `${encodedGroupId}__p${ref.participantIndex}${FILE_SUFFIX}`;
+}
+function path(dataDir, ref) {
+    const dir = multisigDir(dataDir);
+    const resolved = resolve(dir, filename(ref));
+    if (!resolved.startsWith(resolve(dir) + "/")) {
+        throw new Error("invalid groupId: path traversal detected");
+    }
+    return resolved;
+}
+function parseFilename(name) {
+    const match = FILENAME_RE.exec(name);
+    if (!match)
+        return null;
+    const encodedGroupId = match[1];
+    const participantIndex = Number(match[2]);
+    if (!encodedGroupId)
+        return null;
+    if (!Number.isInteger(participantIndex) || participantIndex < 1)
+        return null;
+    let groupId;
+    try {
+        groupId = decodeURIComponent(encodedGroupId);
+    }
+    catch {
+        return null;
+    }
+    return {
+        groupId,
+        participantIndex,
+    };
+}
+function assertParticipantIndex(value) {
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error(`Invalid multisig account: participantIndex must be a positive integer (received ${value})`);
+    }
+}
+export async function saveMultisigAccount(dataDir, account) {
+    const dir = multisigDir(dataDir);
+    const ref = toRef(account);
+    const dest = path(dataDir, ref);
+    const tmp = `${dest}.${process.pid}.${Date.now()}.tmp`;
+    await mkdir(dir, { recursive: true });
+    await writeFile(tmp, JSON.stringify(serializeMultisigAccount(account)), "utf-8");
+    await rename(tmp, dest);
+}
+export async function loadMultisigAccount(dataDir, groupId, participantIndex) {
+    if (participantIndex !== undefined) {
+        return loadByRef(dataDir, { groupId, participantIndex });
+    }
+    const matches = (await listMultisigAccounts(dataDir)).filter((ref) => ref.groupId === groupId);
+    if (matches.length === 0) {
+        throw new Error(`Multisig account not found: ${groupId}`);
+    }
+    const accounts = await Promise.all(matches.map(async (ref) => ({
+        ref,
+        account: await loadByRef(dataDir, ref),
+    })));
+    if (accounts.length > 1) {
+        const participants = accounts
+            .map(({ ref }) => ref.participantIndex)
+            .sort((a, b) => a - b)
+            .join(", ");
+        throw new Error(`Multiple multisig accounts found for ${groupId} (participants: ${participants}).`);
+    }
+    const [single] = accounts;
+    if (!single) {
+        throw new Error(`Multisig account not found: ${groupId}`);
+    }
+    return single.account;
+}
+async function loadByRef(dataDir, ref) {
+    try {
+        const raw = await readFile(path(dataDir, ref), "utf-8");
+        const account = deserializeMultisigAccount(JSON.parse(raw));
+        if (account.groupId !== ref.groupId ||
+            account.participantIndex !== ref.participantIndex) {
+            throw new Error(`Invalid multisig account file for ${ref.groupId}: filename and JSON identity mismatch`);
+        }
+        return account;
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            throw new Error(`Multisig account not found: ${ref.groupId}`);
+        }
+        throw err;
+    }
+}
+export async function listMultisigAccounts(dataDir) {
+    try {
+        const files = await readdir(multisigDir(dataDir));
+        return files
+            .filter((f) => f.endsWith(FILE_SUFFIX))
+            .map(parseFilename)
+            .filter((ref) => ref !== null);
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return [];
+        }
+        throw err;
+    }
+}

package/dist/lib/options.d.ts

@@ -0,0 +1,40 @@
+export type ResolvedOptions = {
+    gatewayUrl: string | undefined;
+    nodeUrl: string | undefined;
+    chainId: number | undefined;
+    poolAddress: string | undefined;
+    dataDir: string;
+    json: boolean;
+    privateKey: string | undefined;
+    artifactVersion: string | undefined;
+};
+export type ConfigFile = {
+    gatewayUrl?: string;
+    chainId?: number;
+    poolAddress?: string;
+    nodeUrl?: string;
+    artifactVersion?: string;
+};
+/** Read config.json from the data directory. Returns empty object if missing or invalid. */
+export declare function loadConfigFile(dataDir: string): ConfigFile;
+/** Write config.json to the data directory. */
+export declare function saveConfigFile(dataDir: string, config: ConfigFile): void;
+export declare function resolveOptions(opts: Record<string, unknown>): ResolvedOptions;
+/** Merge config file defaults into resolved options. CLI flags/env vars take priority. */
+export declare function mergeConfigDefaults(options: ResolvedOptions): ResolvedOptions;
+export declare function requireChainId(opts: ResolvedOptions): asserts opts is ResolvedOptions & {
+    chainId: number;
+};
+export declare function requirePoolAddress(opts: ResolvedOptions): asserts opts is ResolvedOptions & {
+    poolAddress: string;
+};
+export declare function requireGatewayUrl(opts: ResolvedOptions): asserts opts is ResolvedOptions & {
+    gatewayUrl: string;
+};
+export declare function requirePrivateKey(opts: ResolvedOptions): asserts opts is ResolvedOptions & {
+    privateKey: string;
+};
+export declare function requireNodeUrl(opts: ResolvedOptions): asserts opts is ResolvedOptions & {
+    nodeUrl: string;
+};
+export declare function parseIndex(arg: string): number;

package/dist/lib/options.js

@@ -0,0 +1,109 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+function asNonEmptyString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function asChainId(value) {
+    if (typeof value !== "number")
+        return undefined;
+    if (!Number.isInteger(value) || !Number.isFinite(value) || value < 0) {
+        return undefined;
+    }
+    return value;
+}
+/** Read config.json from the data directory. Returns empty object if missing or invalid. */
+export function loadConfigFile(dataDir) {
+    const filePath = path.join(dataDir, "config.json");
+    try {
+        const raw = fs.readFileSync(filePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        const result = {};
+        const gatewayUrl = asNonEmptyString(parsed.gatewayUrl);
+        const chainId = asChainId(parsed.chainId);
+        const poolAddress = asNonEmptyString(parsed.poolAddress);
+        const nodeUrl = asNonEmptyString(parsed.nodeUrl);
+        const artifactVersion = asNonEmptyString(parsed.artifactVersion);
+        if (gatewayUrl !== undefined)
+            result.gatewayUrl = gatewayUrl;
+        if (chainId !== undefined)
+            result.chainId = chainId;
+        if (poolAddress !== undefined)
+            result.poolAddress = poolAddress;
+        if (nodeUrl !== undefined)
+            result.nodeUrl = nodeUrl;
+        if (artifactVersion !== undefined)
+            result.artifactVersion = artifactVersion;
+        return result;
+    }
+    catch {
+        return {};
+    }
+}
+/** Write config.json to the data directory. */
+export function saveConfigFile(dataDir, config) {
+    const filePath = path.join(dataDir, "config.json");
+    fs.mkdirSync(dataDir, { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(config, null, 2) + "\n");
+}
+export function resolveOptions(opts) {
+    return {
+        gatewayUrl: opts["gatewayUrl"] || undefined,
+        nodeUrl: opts["nodeUrl"] || undefined,
+        chainId: opts["chainId"] ? Number(opts["chainId"]) : undefined,
+        poolAddress: opts["poolAddress"] || undefined,
+        dataDir: opts["dataDir"] || path.join(os.homedir(), ".unlink"),
+        json: Boolean(opts["json"]),
+        privateKey: opts["privateKey"] || undefined,
+        artifactVersion: opts["artifactVersion"] || undefined,
+    };
+}
+/** Merge config file defaults into resolved options. CLI flags/env vars take priority. */
+export function mergeConfigDefaults(options) {
+    const config = loadConfigFile(options.dataDir);
+    return {
+        ...options,
+        gatewayUrl: options.gatewayUrl ?? config.gatewayUrl,
+        nodeUrl: options.nodeUrl ?? config.nodeUrl,
+        chainId: options.chainId ?? config.chainId,
+        poolAddress: options.poolAddress ?? config.poolAddress,
+        artifactVersion: options.artifactVersion ?? config.artifactVersion,
+    };
+}
+export function requireChainId(opts) {
+    if (opts.chainId === undefined ||
+        !Number.isInteger(opts.chainId) ||
+        opts.chainId < 0) {
+        throw new Error("--chain-id or UNLINK_CHAIN_ID must be a valid number");
+    }
+}
+export function requirePoolAddress(opts) {
+    if (!opts.poolAddress) {
+        throw new Error("--pool-address or UNLINK_POOL_ADDRESS is required for this command");
+    }
+}
+export function requireGatewayUrl(opts) {
+    if (!opts.gatewayUrl) {
+        throw new Error("--gateway-url or UNLINK_GATEWAY_URL is required for this command");
+    }
+}
+export function requirePrivateKey(opts) {
+    if (!opts.privateKey) {
+        throw new Error("--private-key or UNLINK_PRIVATE_KEY is required for this command");
+    }
+}
+export function requireNodeUrl(opts) {
+    if (!opts.nodeUrl) {
+        throw new Error("--node-url or UNLINK_RPC_HTTP_URL is required for this command");
+    }
+}
+export function parseIndex(arg) {
+    const index = Number(arg);
+    if (!Number.isInteger(index) || index < 0) {
+        throw new Error("Index must be a non-negative integer");
+    }
+    return index;
+}

package/dist/lib/output.d.ts

@@ -0,0 +1,6 @@
+export type OutputOptions = {
+    json: boolean;
+};
+export declare function output(data: unknown, opts: OutputOptions): void;
+/** Write progress/status to stderr. Suppressed in JSON mode. */
+export declare function log(message: string, opts: OutputOptions): void;

package/dist/lib/output.js

@@ -0,0 +1,34 @@
+function bigintReplacer(_key, value) {
+    return typeof value === "bigint" ? value.toString() : value;
+}
+export function output(data, opts) {
+    if (opts.json) {
+        process.stdout.write(JSON.stringify(data, bigintReplacer, 2) + "\n");
+    }
+    else if (typeof data === "string") {
+        process.stdout.write(data + "\n");
+    }
+    else {
+        process.stdout.write(formatHuman(data) + "\n");
+    }
+}
+function formatHuman(data) {
+    if (data === null || data === undefined)
+        return "null";
+    if (typeof data === "bigint")
+        return data.toString();
+    if (typeof data !== "object")
+        return String(data);
+    if (Array.isArray(data)) {
+        return data.length === 0 ? "(empty)" : data.map(formatHuman).join("\n");
+    }
+    return Object.entries(data)
+        .map(([k, v]) => `${k}: ${formatHuman(v)}`)
+        .join("\n");
+}
+/** Write progress/status to stderr. Suppressed in JSON mode. */
+export function log(message, opts) {
+    if (!opts.json) {
+        process.stderr.write(message + "\n");
+    }
+}

package/dist/lib/relay.d.ts

@@ -0,0 +1,18 @@
+import type { UnlinkWallet } from "@unlink-xyz/core";
+import { type OutputOptions } from "./output.js";
+export type RelayPollResult = {
+    relayId: string;
+    status: string;
+    txHash?: string;
+    block?: number;
+    error?: string;
+};
+export declare function isRelaySuccess(result: RelayPollResult): boolean;
+/**
+ * Poll relay status until terminal state.
+ * Logs progress to stderr in human-readable mode.
+ */
+export declare function pollRelayStatus(wallet: UnlinkWallet, relayId: string, outputOpts: OutputOptions, opts?: {
+    timeout?: number;
+    interval?: number;
+}): Promise<RelayPollResult>;

package/dist/lib/relay.js

@@ -0,0 +1,35 @@
+import { log } from "./output.js";
+const TERMINAL_STATES = new Set(["succeeded", "reverted", "failed", "dead"]);
+const DEFAULT_POLL_INTERVAL_MS = 3_000;
+const DEFAULT_TIMEOUT_MS = 120_000;
+export function isRelaySuccess(result) {
+    return result.status === "succeeded";
+}
+/**
+ * Poll relay status until terminal state.
+ * Logs progress to stderr in human-readable mode.
+ */
+export async function pollRelayStatus(wallet, relayId, outputOpts, opts) {
+    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_MS;
+    const interval = opts?.interval ?? DEFAULT_POLL_INTERVAL_MS;
+    const deadline = Date.now() + timeout;
+    let lastState = "";
+    while (Date.now() < deadline) {
+        const status = await wallet.getTxStatus(relayId);
+        if (status.state !== lastState) {
+            lastState = status.state;
+            log(`Status: ${status.state}`, outputOpts);
+        }
+        if (TERMINAL_STATES.has(status.state)) {
+            return {
+                relayId,
+                status: status.state,
+                txHash: status.txHash ?? undefined,
+                block: status.receipt?.blockNumber ?? undefined,
+                error: status.error ?? undefined,
+            };
+        }
+        await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+    throw new Error(`Timed out waiting for relay ${relayId} after ${timeout / 1000}s (last state: ${lastState || "unknown"})`);
+}

package/dist/lib/tokens.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Resolve ERC-20 token symbol via eth_call. Caches results.
+ * Falls back to truncated address on failure.
+ */
+export declare function resolveTokenSymbol(nodeUrl: string, address: string): Promise<string>;
+/**
+ * Resolve ERC-20 decimals via eth_call. Returns undefined if unavailable.
+ * Caches both successful and failed lookups.
+ */
+export declare function resolveTokenDecimals(nodeUrl: string, address: string): Promise<number | undefined>;
+/** Format raw token amount as human-readable when decimals are known. */
+export declare function formatTokenAmount(amount: bigint, decimals?: number): string;
+/** Clear token metadata cache (for testing). */
+export declare function clearSymbolCache(): void;

package/dist/lib/tokens.js

@@ -0,0 +1,142 @@
+const symbolCache = new Map();
+const decimalsCache = new Map();
+// ERC-20 symbol() selector
+const SYMBOL_SELECTOR = "0x95d89b41";
+// ERC-20 decimals() selector
+const DECIMALS_SELECTOR = "0x313ce567";
+/**
+ * Resolve ERC-20 token symbol via eth_call. Caches results.
+ * Falls back to truncated address on failure.
+ */
+export async function resolveTokenSymbol(nodeUrl, address) {
+    const key = `${nodeUrl}:${address.toLowerCase()}`;
+    const cached = symbolCache.get(key);
+    if (cached)
+        return cached;
+    try {
+        const result = await callContract(nodeUrl, address, SYMBOL_SELECTOR);
+        if (result && result !== "0x" && result.length > 2) {
+            const symbol = decodeStringResult(result);
+            if (symbol) {
+                symbolCache.set(key, symbol);
+                return symbol;
+            }
+        }
+    }
+    catch {
+        // Fall through to truncated address
+    }
+    const fallback = truncateAddress(address);
+    symbolCache.set(key, fallback);
+    return fallback;
+}
+/**
+ * Resolve ERC-20 decimals via eth_call. Returns undefined if unavailable.
+ * Caches both successful and failed lookups.
+ */
+export async function resolveTokenDecimals(nodeUrl, address) {
+    const key = `${nodeUrl}:${address.toLowerCase()}`;
+    if (decimalsCache.has(key)) {
+        return decimalsCache.get(key);
+    }
+    let decimals;
+    try {
+        const result = await callContract(nodeUrl, address, DECIMALS_SELECTOR);
+        if (result && result !== "0x" && result.length >= 4) {
+            decimals = decodeUint8Result(result);
+        }
+    }
+    catch {
+        // Leave undefined on failure.
+    }
+    decimalsCache.set(key, decimals);
+    return decimals;
+}
+async function callContract(nodeUrl, address, data) {
+    const resp = await fetch(nodeUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            method: "eth_call",
+            params: [{ to: address, data }, "latest"],
+            id: 1,
+        }),
+    });
+    const json = (await resp.json());
+    return json.result;
+}
+/** Decode ABI-encoded string return value. */
+function decodeStringResult(hex) {
+    try {
+        // Remove 0x prefix.
+        const data = hex.slice(2);
+        // bytes32 encoding (some tokens like MKR): no offset, just raw bytes.
+        if (data.length === 64) {
+            const bytes = Buffer.from(data, "hex");
+            const end = bytes.indexOf(0);
+            const str = bytes.subarray(0, end === -1 ? 32 : end).toString("utf-8");
+            if (str.length > 0 && /^[\x20-\x7E]+$/.test(str)) {
+                return str;
+            }
+        }
+        // Standard ABI string encoding: offset (32 bytes) + length (32 bytes) + data.
+        if (data.length >= 128) {
+            const length = Number.parseInt(data.slice(64, 128), 16);
+            if (length > 0 && length <= 32) {
+                const str = Buffer.from(data.slice(128, 128 + length * 2), "hex")
+                    .toString("utf-8")
+                    .trim();
+                if (str.length > 0)
+                    return str;
+            }
+        }
+    }
+    catch {
+        // Fall through.
+    }
+    return null;
+}
+function decodeUint8Result(hex) {
+    try {
+        const data = hex.startsWith("0x") ? hex.slice(2) : hex;
+        if (data.length < 2)
+            return undefined;
+        const val = Number.parseInt(data.slice(-2), 16);
+        if (Number.isNaN(val))
+            return undefined;
+        return val;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Format raw token amount as human-readable when decimals are known. */
+export function formatTokenAmount(amount, decimals) {
+    if (decimals === undefined ||
+        !Number.isInteger(decimals) ||
+        decimals < 0 ||
+        decimals > 36) {
+        return amount.toString();
+    }
+    if (decimals === 0)
+        return amount.toString();
+    const base = 10n ** BigInt(decimals);
+    const whole = amount / base;
+    const frac = amount % base;
+    if (frac === 0n)
+        return whole.toString();
+    // Pad to decimals digits, strip trailing zeros.
+    const fracStr = frac.toString().padStart(decimals, "0").replace(/0+$/, "");
+    return `${whole}.${fracStr}`;
+}
+function truncateAddress(address) {
+    if (address.length <= 12)
+        return address;
+    return `${address.slice(0, 6)}...${address.slice(-4)}`;
+}
+/** Clear token metadata cache (for testing). */
+export function clearSymbolCache() {
+    symbolCache.clear();
+    decimalsCache.clear();
+}