@crewhaus/tool-token 0.7.0

package/dist/lib/erc.js

@@ -0,0 +1,238 @@
+/**
+ * The token-standard call surface: the selectors, the interface ids, and the
+ * reading of what comes back.
+ *
+ * This is a narrow codec, not a second copy of `tool-onchain`'s general ABI
+ * coder, and the reason is the whole point of this file. A general decoder is
+ * told what type to expect and fails when the bytes are not that type. The
+ * tokens that break harnesses are exactly the ones whose bytes are not that
+ * type: `symbol()` on MKR returns a `bytes32`, not a `string`; `decimals()`
+ * on some very old tokens reverts or is simply absent; an EOA answers every
+ * call with `0x`. Reading those needs the raw words and a documented
+ * fallback, which is a different job from "decode this as a string".
+ *
+ * Every selector and interface id below is a literal, and every one of them
+ * is derived from its signature in `lib.test.ts` through `tool-onchain`'s
+ * `FunctionSelector`. A literal that drifts fails a test rather than
+ * producing calldata a node accepts and a contract misreads.
+ */
+/** Four-byte selectors for the calls this package makes. */
+export const SELECTOR = Object.freeze({
+    /** ERC-20 `balanceOf(address)`. */
+    balanceOf: "0x70a08231",
+    /** ERC-20 `allowance(address,address)`. */
+    allowance: "0xdd62ed3e",
+    decimals: "0x313ce567",
+    symbol: "0x95d89b41",
+    name: "0x06fdde03",
+    totalSupply: "0x18160ddd",
+    ownerOf: "0x6352211e",
+    tokenURI: "0xc87b56dd",
+    /** ERC-1155 `uri(uint256)`. */
+    uri: "0x0e89341c",
+    /** ERC-1155 `balanceOf(address,uint256)` — a different selector from ERC-20's. */
+    balanceOf1155: "0x00fdd58e",
+    supportsInterface: "0x01ffc9a7",
+    /** Multicall3's own helpers, callable inside the same batch. */
+    getEthBalance: "0x4d2301cc",
+    getBlockNumber: "0x42cbb15c",
+});
+/**
+ * ERC-165 interface ids. Each is the XOR of the selectors of the functions in
+ * its interface, and `lib.test.ts` recomputes each one from that function
+ * list rather than trusting the literal.
+ */
+export const INTERFACE_ID = Object.freeze({
+    erc165: "0x01ffc9a7",
+    erc721: "0x80ac58cd",
+    erc721Metadata: "0x5b5e139f",
+    erc721Enumerable: "0x780e9d63",
+    erc1155: "0xd9b67a26",
+    erc1155MetadataUri: "0x0e89341c",
+    /**
+     * Not an interface. ERC-165 requires `supportsInterface(0xffffffff)` to
+     * answer FALSE, so a contract that says true here answers true to
+     * everything and its other answers mean nothing.
+     */
+    invalid: "0xffffffff",
+});
+/** A decoded string longer than this is not a symbol or a name. */
+export const MAX_STRING_BYTES = 4096;
+const HEX_BODY = /^[0-9a-fA-F]*$/;
+export function hexToBytes(hex, what = "data") {
+    const body = hex.startsWith("0x") || hex.startsWith("0X") ? hex.slice(2) : hex;
+    if (body.length % 2 !== 0)
+        throw new Error(`${what}: an odd number of hex digits`);
+    if (!HEX_BODY.test(body))
+        throw new Error(`${what}: not hex`);
+    const out = new Uint8Array(body.length / 2);
+    for (let i = 0; i < out.length; i++)
+        out[i] = Number.parseInt(body.slice(i * 2, i * 2 + 2), 16);
+    return out;
+}
+export function bytesToHex(bytes) {
+    let out = "";
+    for (const b of bytes)
+        out += b.toString(16).padStart(2, "0");
+    return out;
+}
+/** A 32-byte word holding a right-aligned address. */
+export function addressWord(address) {
+    const body = address.replace(/^0x/i, "").toLowerCase();
+    if (body.length !== 40)
+        throw new Error(`an address is 20 bytes, got ${body.length / 2}`);
+    return body.padStart(64, "0");
+}
+/** A 32-byte word holding a right-aligned unsigned integer. */
+export function uintWord(value) {
+    if (value < 0n)
+        throw new Error(`${value} is negative, and the type is unsigned`);
+    if (value >= 1n << 256n)
+        throw new Error(`${value} does not fit in a uint256`);
+    return value.toString(16).padStart(64, "0");
+}
+/**
+ * A 32-byte word holding a LEFT-aligned `bytes4`.
+ *
+ * Fixed bytes are left-aligned and integers right-aligned. Getting this
+ * backwards makes every `supportsInterface` answer false, which reads as "not
+ * an NFT" rather than as a bug.
+ */
+export function bytes4Word(id) {
+    const body = id.replace(/^0x/i, "").toLowerCase();
+    if (body.length !== 8)
+        throw new Error(`an interface id is 4 bytes, got "${id}"`);
+    return body.padEnd(64, "0");
+}
+/** Assemble calldata from a selector and pre-padded words. */
+export function callData(selector, ...words) {
+    return `${selector}${words.join("")}`;
+}
+// ---------------------------------------------------------------------------
+// reading the answer
+// ---------------------------------------------------------------------------
+const WORD = 32;
+/** Read one 32-byte word as an unsigned integer, or null when it is not there. */
+export function decodeUint(data) {
+    const bytes = hexToBytes(data, "return data");
+    if (bytes.length < WORD)
+        return null;
+    let value = 0n;
+    for (const b of bytes.subarray(0, WORD))
+        value = (value << 8n) | BigInt(b);
+    return value;
+}
+/**
+ * Read one word as an address.
+ *
+ * The top 12 bytes must be zero. A word with anything up there is not an
+ * address the caller can use, and masking it off would turn a contract's
+ * garbage into a plausible destination.
+ */
+export function decodeAddressValue(data) {
+    const bytes = hexToBytes(data, "return data");
+    if (bytes.length < WORD)
+        return null;
+    for (let i = 0; i < 12; i++)
+        if (bytes[i] !== 0)
+            return null;
+    return `0x${bytesToHex(bytes.subarray(12, WORD))}`;
+}
+/** Read one word as a bool. Anything other than 0 or 1 is not a bool. */
+export function decodeBool(data) {
+    const value = decodeUint(data);
+    if (value === null || value > 1n)
+        return null;
+    return value === 1n;
+}
+/** UTF-8, strictly. A symbol that is not text must not come back as U+FFFD replacement characters. */
+const strictUtf8 = new TextDecoder("utf-8", { fatal: true });
+function decodeBytes32Text(word, raw, note) {
+    let end = word.length;
+    while (end > 0 && word[end - 1] === 0)
+        end--;
+    const body = word.subarray(0, end);
+    if (body.some((b) => b === 0)) {
+        // Interior NULs mean this is not a NUL-padded string, whatever the
+        // trailing zeros suggested.
+        return { value: null, encoding: "undecodable", note: `${note}interior NUL bytes`, raw };
+    }
+    try {
+        return { value: strictUtf8.decode(body), encoding: "bytes32", note, raw };
+    }
+    catch {
+        return { value: null, encoding: "undecodable", note: `${note}not valid UTF-8`, raw };
+    }
+}
+/**
+ * Read `symbol()` or `name()` from whatever the token actually returned.
+ *
+ * Three shapes are real and all three are in production:
+ *
+ *   - a normal dynamic `string` (offset, length, bytes);
+ *   - exactly one word, which is the `bytes32` form MKR and several other
+ *     2017-era tokens use — the ABI was not settled when they deployed;
+ *   - nothing at all, because the function is absent or reverted.
+ *
+ * The third is reported as `absent`, never as an empty name. "" and "we could
+ * not read it" are different facts and a caller displaying the first as the
+ * second shows a blank where a warning belongs.
+ */
+export function decodeStringish(data) {
+    const raw = data.startsWith("0x") ? data : `0x${data}`;
+    const bytes = hexToBytes(data, "return data");
+    if (bytes.length === 0) {
+        return { value: null, encoding: "absent", note: "the call returned no data", raw };
+    }
+    if (bytes.length === WORD) {
+        return decodeBytes32Text(bytes, raw, "returned bytes32 rather than string; ");
+    }
+    if (bytes.length >= WORD * 2) {
+        const offset = decodeUint(data);
+        const length = decodeUint(`0x${bytesToHex(bytes.subarray(WORD, WORD * 2))}`);
+        const wellFormed = offset === 32n &&
+            length <= BigInt(bytes.length - WORD * 2) &&
+            length <= BigInt(MAX_STRING_BYTES);
+        if (wellFormed) {
+            const body = bytes.subarray(WORD * 2, WORD * 2 + Number(length));
+            try {
+                return { value: strictUtf8.decode(body), encoding: "string", note: "", raw };
+            }
+            catch {
+                return { value: null, encoding: "undecodable", note: "not valid UTF-8", raw };
+            }
+        }
+        if (length > BigInt(MAX_STRING_BYTES)) {
+            return {
+                value: null,
+                encoding: "undecodable",
+                note: `declares ${length} bytes, past the ${MAX_STRING_BYTES}-byte cap for a symbol or a name`,
+                raw,
+            };
+        }
+        // A blob that is neither a well-formed string nor one word. The first word
+        // is still the most likely place a bytes32 symbol is sitting.
+        return decodeBytes32Text(bytes.subarray(0, WORD), raw, "not a well-formed dynamic string; read the first word as bytes32; ");
+    }
+    return {
+        value: null,
+        encoding: "undecodable",
+        note: `${bytes.length} bytes is neither a word nor a dynamic string`,
+        raw,
+    };
+}
+/**
+ * The 64-hex-digit, zero-padded, LOWERCASE form of a token id, for the `{id}`
+ * placeholder in an ERC-1155 URI.
+ *
+ * The spec is explicit and almost everyone gets it wrong: it is not the
+ * decimal id and not `0x`-prefixed. A gateway handed `{id}` replaced with "1"
+ * returns a 404, or worse, somebody else's metadata.
+ */
+export function padTokenIdHex(tokenId) {
+    if (tokenId < 0n)
+        throw new Error(`a token id cannot be negative, got ${tokenId}`);
+    if (tokenId >= 1n << 256n)
+        throw new Error(`${tokenId} does not fit in a uint256`);
+    return tokenId.toString(16).padStart(64, "0");
+}

package/dist/lib/lists.d.ts

@@ -0,0 +1,78 @@
+/** One token as a list carries it. This is the Uniswap token-list shape. */
+export type TokenListEntry = {
+    readonly chainId: number;
+    readonly address: string;
+    readonly symbol: string;
+    readonly name: string;
+    readonly decimals: number;
+    readonly tags?: ReadonlyArray<string>;
+};
+export type TokenList = {
+    /** How the answer refers to this list. Two lists may not share an id. */
+    readonly id: string;
+    readonly name?: string;
+    readonly tokens: ReadonlyArray<TokenListEntry>;
+};
+/** One list's claim about one address. */
+export type ListClaim = {
+    readonly listId: string;
+    readonly symbol: string;
+    readonly name: string;
+    readonly decimals: number;
+    readonly tags: ReadonlyArray<string>;
+};
+export type MatchKind = "address" | "symbol" | "name" | "symbol-confusable" | "name-confusable";
+/** One address a query could mean, with every list that carries it. */
+export type Candidate = {
+    /** Lowercase. Addresses are compared lowercased; the checksummed form is for display. */
+    readonly address: string;
+    readonly claims: ReadonlyArray<ListClaim>;
+    readonly matchedBy: ReadonlyArray<MatchKind>;
+};
+/** The text with every zero-width and formatting character removed. */
+export declare function stripInvisible(text: string): string;
+/** Which invisible code points are present, in order, so a report can name them. */
+export declare function invisibleCodePoints(text: string): ReadonlyArray<number>;
+/**
+ * Fold a symbol or a name towards a comparison key.
+ *
+ * Only ever used to ADD candidates. Never used to decide which address a
+ * query resolves to.
+ */
+export declare function confusableSkeleton(text: string): string;
+/** What is odd about a piece of text a contract or a list supplied. */
+export type TextConcern = {
+    readonly code: "invisible-characters" | "non-ascii" | "confusable" | "whitespace" | "over-long";
+    readonly detail: string;
+};
+/**
+ * Everything worth saying about a symbol or a name before a human reads it.
+ *
+ * These are reported, not acted on. A legitimate token can have a non-ASCII
+ * name; none of them need a zero-width space in the ticker.
+ */
+export declare function textConcerns(text: string): ReadonlyArray<TextConcern>;
+export declare const ADDRESS_SHAPE: RegExp;
+/**
+ * A stable digest of the lists a resolution was made against.
+ *
+ * Reproducibility evidence, not a security control: the same query against
+ * the same fingerprint gives the same candidates, and a fingerprint that
+ * moved explains why yesterday's answer differs from today's. Only the fields
+ * that affect the outcome go in, sorted, so a list that reordered its tokens
+ * or gained a logo URL still fingerprints the same.
+ */
+export declare function fingerprintLists(lists: ReadonlyArray<TokenList>, chainId: number): string;
+/**
+ * Every address on the given lists that the query could mean, for one chain.
+ *
+ * Matching is by exact symbol, exact name, and by confusable skeleton of
+ * both. The four are reported separately in `matchedBy` so the caller can see
+ * WHY an address is in the set — a candidate that only matched by skeleton is
+ * the impostor the literal match would have missed.
+ */
+export declare function findCandidates(lists: ReadonlyArray<TokenList>, chainId: number, query: string): ReadonlyArray<Candidate>;
+/** The distinct decimals the lists claim for one address, in order found. */
+export declare function claimedDecimals(candidate: Candidate): ReadonlyArray<number>;
+/** The distinct symbols the lists claim for one address. */
+export declare function claimedSymbols(candidate: Candidate): ReadonlyArray<string>;

package/dist/lib/lists.js

@@ -0,0 +1,290 @@
+/**
+ * Token lists, and the reason a symbol is not an identifier.
+ *
+ * A symbol is a string a deployer chose. Nothing enforces uniqueness, nothing
+ * stops a second contract from calling itself USDC with six decimals and a
+ * convincing name, and two reputable lists routinely carry different
+ * addresses for the same ticker on the same chain. So the matching here never
+ * picks: it gathers every entry a query could plausibly mean and hands the
+ * whole set back. Choosing between two addresses that both say "USDC" is a
+ * decision with a wrong answer that costs money, and it is not a decision a
+ * string match is entitled to make.
+ *
+ * ## The skeleton, and why folding is safe HERE
+ *
+ * `confusableSkeleton` folds a symbol towards ASCII so that "USDC" and
+ * "USDС" — the second with a Cyrillic С — land on the same key. It is a
+ * deliberately small table: the common Latin/Cyrillic/Greek homoglyphs,
+ * invisible formatting characters, and two digit shapes. It is NOT UTS-39,
+ * and a symbol that survives it is not thereby proven safe.
+ *
+ * That looseness is affordable because of the DIRECTION the fold is used in.
+ * It only ever WIDENS the candidate set, and a wider set can only move the
+ * answer towards a refusal — it can never resolve a query to a different
+ * address. This is exactly the property ENS normalisation does not have,
+ * which is why `EnsResolve` is not in this package: there, a fold that is
+ * wrong by one codepoint resolves a name to the wrong address and sends funds
+ * there, so it needs the real UTS-46 table and a real dependency.
+ */
+import { createHash } from "node:crypto";
+// ---------------------------------------------------------------------------
+// the skeleton
+// ---------------------------------------------------------------------------
+/**
+ * Code points that occupy no width, as explicit ranges.
+ *
+ * A table rather than a character class on purpose: a regex whose source
+ * contains the very characters it matches is unreadable, unreviewable, and one
+ * careless paste away from silently losing an entry. Every code point below is
+ * written as a number and named.
+ *
+ * A symbol padded with these is a different string from the one a human reads,
+ * which is the entire trick: "USD" + U+200B + "C" displays as USDC in every
+ * wallet and matches nothing a caller typed.
+ */
+const INVISIBLE_RANGES = Object.freeze([
+    [0x00ad, 0x00ad], // soft hyphen
+    [0x034f, 0x034f], // combining grapheme joiner
+    [0x061c, 0x061c], // arabic letter mark
+    [0x115f, 0x1160], // hangul choseong and jungseong fillers
+    [0x17b4, 0x17b5], // khmer inherent vowels, which render as nothing
+    [0x180b, 0x180e], // mongolian variation selectors and vowel separator
+    [0x200b, 0x200f], // zero-width space and joiners, LTR and RTL marks
+    [0x202a, 0x202e], // bidi embeddings and overrides - the Trojan Source shape
+    [0x2060, 0x2064], // word joiner and the invisible operators
+    [0x2066, 0x206f], // bidi isolates and deprecated format characters
+    [0x3164, 0x3164], // hangul filler
+    [0xfe00, 0xfe0f], // variation selectors
+    [0xfeff, 0xfeff], // byte order mark, also known as zero-width no-break space
+    [0xffa0, 0xffa0], // halfwidth hangul filler
+    [0xe0000, 0xe007f], // tag characters
+]);
+function isInvisible(codePoint) {
+    return INVISIBLE_RANGES.some(([from, to]) => codePoint >= from && codePoint <= to);
+}
+/** The text with every zero-width and formatting character removed. */
+export function stripInvisible(text) {
+    let out = "";
+    for (const ch of text)
+        if (!isInvisible(ch.codePointAt(0)))
+            out += ch;
+    return out;
+}
+/** Which invisible code points are present, in order, so a report can name them. */
+export function invisibleCodePoints(text) {
+    const out = [];
+    for (const ch of text) {
+        const point = ch.codePointAt(0);
+        if (isInvisible(point))
+            out.push(point);
+    }
+    return out;
+}
+/** Combining marks, which NFKD leaves behind after decomposing an accent. */
+const COMBINING = /\p{M}/gu;
+/**
+ * The homoglyph table, lowercase, applied after case folding. Small on
+ * purpose — see the note at the top of this file about which direction a
+ * wrong fold can move the answer.
+ */
+const CONFUSABLE = Object.freeze({
+    // Cyrillic
+    а: "a",
+    б: "b",
+    в: "b",
+    е: "e",
+    ё: "e",
+    ѕ: "s",
+    і: "i",
+    ј: "j",
+    к: "k",
+    м: "m",
+    н: "h",
+    о: "o",
+    р: "p",
+    с: "c",
+    т: "t",
+    у: "y",
+    х: "x",
+    ԁ: "d",
+    ԛ: "q",
+    ԝ: "w",
+    // Greek
+    α: "a",
+    β: "b",
+    ε: "e",
+    ζ: "z",
+    η: "n",
+    ι: "i",
+    κ: "k",
+    μ: "u",
+    ν: "v",
+    ο: "o",
+    ρ: "p",
+    σ: "o",
+    τ: "t",
+    υ: "u",
+    χ: "x",
+    ϲ: "c",
+    // Latin letters NFKD does not decompose
+    ł: "l",
+    ø: "o",
+    đ: "d",
+    ħ: "h",
+    ı: "i",
+    ȷ: "j",
+    ſ: "s",
+});
+/** Digit shapes that read as letters in an all-caps ticker. */
+const DIGIT_SHAPE = Object.freeze({
+    "0": "o",
+    "1": "l",
+    "|": "l",
+    "!": "l",
+    "5": "s",
+});
+/**
+ * Fold a symbol or a name towards a comparison key.
+ *
+ * Only ever used to ADD candidates. Never used to decide which address a
+ * query resolves to.
+ */
+export function confusableSkeleton(text) {
+    const stripped = stripInvisible(text).normalize("NFKD").replace(COMBINING, "");
+    let out = "";
+    for (const ch of stripped.toLowerCase()) {
+        out += CONFUSABLE[ch] ?? DIGIT_SHAPE[ch] ?? ch;
+    }
+    return out.trim();
+}
+const ASCII_PRINTABLE = /^[\x20-\x7E]*$/;
+/**
+ * Everything worth saying about a symbol or a name before a human reads it.
+ *
+ * These are reported, not acted on. A legitimate token can have a non-ASCII
+ * name; none of them need a zero-width space in the ticker.
+ */
+export function textConcerns(text) {
+    const out = [];
+    const invisible = invisibleCodePoints(text);
+    if (invisible.length > 0) {
+        const points = [...new Set(invisible)]
+            .map((point) => `U+${point.toString(16).toUpperCase().padStart(4, "0")}`)
+            .join(", ");
+        out.push({
+            code: "invisible-characters",
+            detail: `contains ${invisible.length} zero-width or formatting character(s): ${points}`,
+        });
+    }
+    if (!ASCII_PRINTABLE.test(stripInvisible(text))) {
+        out.push({ code: "non-ascii", detail: "contains characters outside printable ASCII" });
+        const skeleton = confusableSkeleton(text);
+        if (skeleton !== text.toLowerCase().trim()) {
+            out.push({
+                code: "confusable",
+                detail: `folds to "${skeleton}", so it displays like a different ticker than it is`,
+            });
+        }
+    }
+    if (/^\s|\s$|[\r\n\t]/.test(text)) {
+        out.push({ code: "whitespace", detail: "has leading, trailing or embedded whitespace" });
+    }
+    if (text.length > 64) {
+        out.push({ code: "over-long", detail: `${text.length} characters is not a symbol or a name` });
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// matching
+// ---------------------------------------------------------------------------
+export const ADDRESS_SHAPE = /^0x[0-9a-fA-F]{40}$/;
+/**
+ * A stable digest of the lists a resolution was made against.
+ *
+ * Reproducibility evidence, not a security control: the same query against
+ * the same fingerprint gives the same candidates, and a fingerprint that
+ * moved explains why yesterday's answer differs from today's. Only the fields
+ * that affect the outcome go in, sorted, so a list that reordered its tokens
+ * or gained a logo URL still fingerprints the same.
+ */
+export function fingerprintLists(lists, chainId) {
+    const rows = [];
+    for (const list of lists) {
+        for (const token of list.tokens) {
+            if (token.chainId !== chainId)
+                continue;
+            rows.push(`${list.id}\u0000${token.address.toLowerCase()}\u0000${token.symbol}\u0000${token.name}\u0000${token.decimals}`);
+        }
+    }
+    rows.sort();
+    return `sha256:${createHash("sha256").update(rows.join("\n")).digest("hex")}`;
+}
+function claimOf(list, token) {
+    return {
+        listId: list.id,
+        symbol: token.symbol,
+        name: token.name,
+        decimals: token.decimals,
+        tags: token.tags ?? [],
+    };
+}
+/**
+ * Every address on the given lists that the query could mean, for one chain.
+ *
+ * Matching is by exact symbol, exact name, and by confusable skeleton of
+ * both. The four are reported separately in `matchedBy` so the caller can see
+ * WHY an address is in the set — a candidate that only matched by skeleton is
+ * the impostor the literal match would have missed.
+ */
+export function findCandidates(lists, chainId, query) {
+    const wanted = query.trim();
+    const byAddress = ADDRESS_SHAPE.test(wanted) ? wanted.toLowerCase() : null;
+    const folded = wanted.toLowerCase();
+    const skeleton = confusableSkeleton(wanted);
+    const found = new Map();
+    const note = (address, claim, kind) => {
+        const key = address.toLowerCase();
+        const entry = found.get(key) ?? { claims: [], matchedBy: new Set() };
+        if (!entry.claims.some((c) => c.listId === claim.listId))
+            entry.claims.push(claim);
+        entry.matchedBy.add(kind);
+        found.set(key, entry);
+    };
+    for (const list of lists) {
+        for (const token of list.tokens) {
+            if (token.chainId !== chainId)
+                continue;
+            const claim = claimOf(list, token);
+            if (byAddress !== null) {
+                if (token.address.toLowerCase() === byAddress)
+                    note(token.address, claim, "address");
+                continue;
+            }
+            const symbol = token.symbol ?? "";
+            const name = token.name ?? "";
+            if (symbol.toLowerCase() === folded)
+                note(token.address, claim, "symbol");
+            else if (confusableSkeleton(symbol) === skeleton)
+                note(token.address, claim, "symbol-confusable");
+            if (name.toLowerCase() === folded)
+                note(token.address, claim, "name");
+            else if (confusableSkeleton(name) === skeleton)
+                note(token.address, claim, "name-confusable");
+        }
+    }
+    return [...found.entries()]
+        .map(([address, entry]) => ({
+        address,
+        claims: entry.claims,
+        matchedBy: [...entry.matchedBy].sort(),
+    }))
+        .sort((a, b) => (a.address < b.address ? -1 : a.address > b.address ? 1 : 0));
+}
+/** The distinct decimals the lists claim for one address, in order found. */
+export function claimedDecimals(candidate) {
+    return [...new Set(candidate.claims.map((c) => c.decimals))];
+}
+/** The distinct symbols the lists claim for one address. */
+export function claimedSymbols(candidate) {
+    return [...new Set(candidate.claims.map((c) => c.symbol))];
+}

package/dist/lib/onchain.d.ts

@@ -0,0 +1,26 @@
+/** What `AddressCheck` says about one address. */
+export type AddressVerdict = {
+    readonly valid: boolean;
+    /** The EIP-55 mixed-case form; "" when the input is not a well-formed address. */
+    readonly checksummed: string;
+    /** The comparison key. Addresses are compared lowercased, never checksummed. */
+    readonly lowercase: string;
+    /** True when the input carried a checksum that was verified, not merely a shape. */
+    readonly hadChecksum: boolean;
+    readonly isZero: boolean;
+    readonly reason: string;
+};
+export declare function checkAddress(raw: string): Promise<AddressVerdict>;
+/**
+ * Render base units as an exact decimal string.
+ *
+ * `decimals` is the token's own answer, never a default. There is no path
+ * through this file that supplies 18 for a token that did not say 18.
+ */
+export declare function formatUnits(baseUnits: bigint, decimals: number): Promise<string>;
+/**
+ * The widest decimals `TokenUnits` will convert. A token reporting more than
+ * this is reported with its raw balance and no decimal form: uint8 decimals
+ * goes to 255, and nothing legitimate is out there at 200.
+ */
+export declare const MAX_FORMATTABLE_DECIMALS = 77;

package/dist/lib/onchain.js

@@ -0,0 +1,48 @@
+/**
+ * The bridge to `@crewhaus/tool-onchain`, which owns the arithmetic.
+ *
+ * EIP-55 checksumming and decimal↔base-unit conversion are NOT re-implemented
+ * here. Both are short enough to look trivial and both have a failure mode
+ * that is silent: a checksum derived from a keccak that is really SHA3-256
+ * validates nothing, and a `formatUnits` that rounds loses the low digits of
+ * a balance without saying so. The repository already has one of each,
+ * checked against the EIP's own vectors, so this package calls those rather
+ * than becoming the second copy that disagrees.
+ *
+ * They arrive as tools rather than as functions because `tool-onchain`
+ * publishes only its tool surface. That makes these wrappers `async` for work
+ * that is pure — a real cost, paid a handful of times per call, and cheaper
+ * than a second EIP-55.
+ */
+import { addressCheck, tokenUnits } from "@crewhaus/tool-onchain";
+/**
+ * `ToolExecuteResult` is a union of a string and a structured content block.
+ * Both of these tools return the string arm; anything else means the tool
+ * changed shape underneath us, and saying so beats a cast that decodes
+ * garbage.
+ */
+async function textResult(result, tool) {
+    const value = await result;
+    if (typeof value !== "string")
+        throw new Error(`${tool} did not return a string result`);
+    return value;
+}
+export async function checkAddress(raw) {
+    return JSON.parse(await textResult(addressCheck.execute({ address: raw }), "AddressCheck"));
+}
+/**
+ * Render base units as an exact decimal string.
+ *
+ * `decimals` is the token's own answer, never a default. There is no path
+ * through this file that supplies 18 for a token that did not say 18.
+ */
+export async function formatUnits(baseUnits, decimals) {
+    const out = JSON.parse(await textResult(tokenUnits.execute({ amount: baseUnits.toString(), decimals, toDecimal: true }), "TokenUnits"));
+    return out.decimal;
+}
+/**
+ * The widest decimals `TokenUnits` will convert. A token reporting more than
+ * this is reported with its raw balance and no decimal form: uint8 decimals
+ * goes to 255, and nothing legitimate is out there at 200.
+ */
+export const MAX_FORMATTABLE_DECIMALS = 77;