@crewhaus/tool-defi 0.7.0

package/dist/lib/abi.d.ts

@@ -0,0 +1,147 @@
+/**
+ * The handful of ABI shapes this package reads, and nothing more.
+ *
+ * `@crewhaus/tool-onchain` owns the general ABI coder for this monorepo, but
+ * its entrypoint exports the coder as TOOLS (`AbiEncodeCall`, `AbiDecode`,
+ * `FunctionSelector`) rather than as functions, and this package does not
+ * reach past another package's entrypoint or widen it while sibling packages
+ * are being written into the same checkout. What is left is small and fixed:
+ * every call here is a view function with at most two static arguments, and
+ * every answer is a run of 32-byte words plus, in one case, a string.
+ *
+ * The selectors below are CONSTANTS, not computed — there is no Keccak in this
+ * package's dependency set. That is only safe because it is checked: `lib.test.ts`
+ * puts every one of them through tool-onchain's `FunctionSelector` tool, and
+ * puts every decoder in this file through its `AbiDecode`, so a wrong constant
+ * or a mis-sliced word fails the suite rather than reading the wrong storage
+ * slot in production.
+ */
+export declare class AbiError extends Error {
+    readonly name = "AbiError";
+}
+/**
+ * Four-byte selectors, each with the canonical signature it was hashed over.
+ *
+ * Canonical matters: `balanceOf(address)` and `balanceOf(address owner)` hash
+ * the same because parameter names are not part of the signature, but `uint`
+ * and `uint256` do NOT — the first is not canonical and hashes differently.
+ */
+export declare const SELECTORS: Readonly<{
+    /** `decimals()` — ERC-20, and a Chainlink aggregator's answer scale. */
+    readonly decimals: "0x313ce567";
+    /** `description()` — a Chainlink feed's own label, e.g. "ETH / USD". */
+    readonly description: "0x7284e416";
+    /** `latestRoundData()` — (uint80,int256,uint256,uint256,uint80). */
+    readonly latestRoundData: "0xfeaf968c";
+    /** `balanceOf(address)` — ERC-20, and an ERC-4626 share balance. */
+    readonly balanceOf: "0x70a08231";
+    /** `getPriceUnsafe(bytes32)` — Pyth: (int64,uint64,int32,uint256). */
+    readonly getPriceUnsafe: "0x96834ad3";
+    /** `getUserAccountData(address)` — Aave v3 Pool: six uint256. */
+    readonly getUserAccountData: "0xbf92857c";
+    /** `convertToAssets(uint256)` — ERC-4626. */
+    readonly convertToAssets: "0x07a2d13a";
+    /** `asset()` — ERC-4626's underlying token. */
+    readonly asset: "0x38d52e0f";
+    /** `borrowBalanceOf(address)` — Compound v3 Comet, in base-token units. */
+    readonly borrowBalanceOf: "0x374c49b4";
+    /** `baseToken()` — Compound v3 Comet's single borrowable asset. */
+    readonly baseToken: "0xc55dae63";
+    /** `collateralBalanceOf(address,address)` — Compound v3 Comet. */
+    readonly collateralBalanceOf: "0x5c2549ee";
+    /** `isLiquidatable(address)` — Compound v3 Comet's own verdict, not a derived one. */
+    readonly isLiquidatable: "0x042e02cf";
+}>;
+/**
+ * Shape-check an address and lowercase it.
+ *
+ * Shape only: verifying an EIP-55 checksum needs Keccak, which this package
+ * does not have. `AddressCheck` in `@crewhaus/tool-onchain` is the tool that
+ * catches a typo in a mixed-case address, and every tool description here
+ * points a caller at it — reading the wrong contract is not an error this can
+ * detect for itself, it is a wrong answer.
+ */
+export declare function normalizeAddress(raw: string, what: string): string;
+export declare function normalizeBytes32(raw: string, what: string): string;
+/** Calldata for a view function that takes no arguments. */
+export declare function callNoArgs(selector: string): string;
+/** Calldata for one `address` argument: left-padded into a 32-byte word. */
+export declare function callWithAddress(selector: string, address: string, what: string): string;
+/** Calldata for two `address` arguments, in declaration order. */
+export declare function callWithAddresses(selector: string, first: string, second: string, what: string): string;
+/** Calldata for one `uint256` argument. */
+export declare function callWithUint256(selector: string, value: bigint, what: string): string;
+/** Calldata for one `bytes32` argument. */
+export declare function callWithBytes32(selector: string, value: string, what: string): string;
+/**
+ * Split return data into exactly `count` unsigned 32-byte words.
+ *
+ * Exactly, not at least: a contract that answered with fewer words than its
+ * signature promises did not answer the question, and an address with no code
+ * answers `0x` — which zero-pads into a perfectly plausible price of zero if
+ * anyone lets it. `@crewhaus/tool-onchain`'s decoder takes the same line.
+ */
+export declare function decodeWords(data: string, count: number, what: string): bigint[];
+/**
+ * Reinterpret an unsigned word as a signed integer of `bits` width.
+ *
+ * A Chainlink `answer` is an int256 and a Pyth `expo` is an int32, and both
+ * are genuinely negative in the wild: `expo` is almost always negative, and a
+ * feed reporting a negative answer is the signal that something is wrong with
+ * it. Read unsigned, that same feed reports about 1.15e77 and the position
+ * built on it looks spectacularly solvent.
+ */
+export declare function asSigned(word: bigint, bits: number): bigint;
+/**
+ * Read a 32-byte word as an `address`.
+ *
+ * The low 20 bytes are the address; the upper 12 are padding that the ABI says
+ * is zero and that nothing on the receiving end enforces. `@crewhaus/tool-onchain`'s
+ * decoder takes the low 20 bytes and ignores the rest, so this does too —
+ * formatting the WHOLE word instead produces a 66-character string that is not
+ * an address, which every downstream address check then rejects, so one
+ * non-conforming contract takes out the read rather than the padding it
+ * violated. The dirty padding is reported rather than swallowed: it is also
+ * what calling the wrong function on the right contract looks like.
+ */
+export declare function addressFromWord(word: bigint): {
+    address: string;
+    paddingDirty: boolean;
+};
+/** A contract-supplied label longer than this is not a label. "ETH / USD" is nine. */
+export declare const MAX_CONTRACT_TEXT_CHARS = 128;
+/**
+ * Make a contract-supplied string safe to put in a result.
+ *
+ * Every string in this package's output that did not come from the caller came
+ * from a contract, and a contract's bytes are written by whoever deployed it —
+ * which, for a feed address a caller was handed, is not the caller. A real
+ * aggregator's `description()` is nine characters; a long one is not a label,
+ * it is somebody using the one free-text field here as a way into the reader's
+ * context. Control characters go the same way: a newline in returned bytes
+ * lets them impersonate the lines printed around them.
+ *
+ * Truncation is REPORTED, never silent — a label quietly cut at 128 characters
+ * is a different label, and "this address is the pair you meant" is exactly the
+ * check a shortened one would pass by accident.
+ */
+export declare function sanitizeContractText(raw: string, maxChars?: number): {
+    text: string;
+    truncated: boolean;
+    hadControlCharacters: boolean;
+};
+/**
+ * Decode return data holding one dynamic `string`.
+ *
+ * Head word is a byte OFFSET from the start of the data, not an index; the
+ * word at that offset is the byte length, and the bytes follow it padded up to
+ * a word boundary. Treating the offset as a length is the classic misread, and
+ * it produces a plausible short string rather than an error.
+ *
+ * `maxBytes` is a refusal, not a truncation: a node may return up to
+ * MAX_RESPONSE_BYTES, so without it a contract can hand back a megabyte of
+ * text that this would decode in full and carry into somebody's context window.
+ */
+export declare function decodeString(data: string, what: string, maxBytes?: number): string;
+/** The largest uint256, which several protocols use to mean "unbounded". */
+export declare const UINT256_MAX: bigint;

package/dist/lib/abi.js

@@ -0,0 +1,245 @@
+/**
+ * The handful of ABI shapes this package reads, and nothing more.
+ *
+ * `@crewhaus/tool-onchain` owns the general ABI coder for this monorepo, but
+ * its entrypoint exports the coder as TOOLS (`AbiEncodeCall`, `AbiDecode`,
+ * `FunctionSelector`) rather than as functions, and this package does not
+ * reach past another package's entrypoint or widen it while sibling packages
+ * are being written into the same checkout. What is left is small and fixed:
+ * every call here is a view function with at most two static arguments, and
+ * every answer is a run of 32-byte words plus, in one case, a string.
+ *
+ * The selectors below are CONSTANTS, not computed — there is no Keccak in this
+ * package's dependency set. That is only safe because it is checked: `lib.test.ts`
+ * puts every one of them through tool-onchain's `FunctionSelector` tool, and
+ * puts every decoder in this file through its `AbiDecode`, so a wrong constant
+ * or a mis-sliced word fails the suite rather than reading the wrong storage
+ * slot in production.
+ */
+export class AbiError extends Error {
+    name = "AbiError";
+}
+/**
+ * Four-byte selectors, each with the canonical signature it was hashed over.
+ *
+ * Canonical matters: `balanceOf(address)` and `balanceOf(address owner)` hash
+ * the same because parameter names are not part of the signature, but `uint`
+ * and `uint256` do NOT — the first is not canonical and hashes differently.
+ */
+export const SELECTORS = Object.freeze({
+    /** `decimals()` — ERC-20, and a Chainlink aggregator's answer scale. */
+    decimals: "0x313ce567",
+    /** `description()` — a Chainlink feed's own label, e.g. "ETH / USD". */
+    description: "0x7284e416",
+    /** `latestRoundData()` — (uint80,int256,uint256,uint256,uint80). */
+    latestRoundData: "0xfeaf968c",
+    /** `balanceOf(address)` — ERC-20, and an ERC-4626 share balance. */
+    balanceOf: "0x70a08231",
+    /** `getPriceUnsafe(bytes32)` — Pyth: (int64,uint64,int32,uint256). */
+    getPriceUnsafe: "0x96834ad3",
+    /** `getUserAccountData(address)` — Aave v3 Pool: six uint256. */
+    getUserAccountData: "0xbf92857c",
+    /** `convertToAssets(uint256)` — ERC-4626. */
+    convertToAssets: "0x07a2d13a",
+    /** `asset()` — ERC-4626's underlying token. */
+    asset: "0x38d52e0f",
+    /** `borrowBalanceOf(address)` — Compound v3 Comet, in base-token units. */
+    borrowBalanceOf: "0x374c49b4",
+    /** `baseToken()` — Compound v3 Comet's single borrowable asset. */
+    baseToken: "0xc55dae63",
+    /** `collateralBalanceOf(address,address)` — Compound v3 Comet. */
+    collateralBalanceOf: "0x5c2549ee",
+    /** `isLiquidatable(address)` — Compound v3 Comet's own verdict, not a derived one. */
+    isLiquidatable: "0x042e02cf",
+});
+const HEX_ADDRESS = /^0x[0-9a-fA-F]{40}$/;
+const HEX_BYTES32 = /^0x[0-9a-fA-F]{64}$/;
+const HEX_DATA = /^0x([0-9a-fA-F]{2})*$/;
+/**
+ * Shape-check an address and lowercase it.
+ *
+ * Shape only: verifying an EIP-55 checksum needs Keccak, which this package
+ * does not have. `AddressCheck` in `@crewhaus/tool-onchain` is the tool that
+ * catches a typo in a mixed-case address, and every tool description here
+ * points a caller at it — reading the wrong contract is not an error this can
+ * detect for itself, it is a wrong answer.
+ */
+export function normalizeAddress(raw, what) {
+    const text = raw.trim();
+    if (!HEX_ADDRESS.test(text)) {
+        throw new AbiError(`${what}: "${raw}" is not an address (0x followed by 40 hex characters) — run AddressCheck on it first`);
+    }
+    return text.toLowerCase();
+}
+export function normalizeBytes32(raw, what) {
+    const text = raw.trim();
+    if (!HEX_BYTES32.test(text)) {
+        throw new AbiError(`${what}: "${raw}" is not 0x followed by 64 hex characters`);
+    }
+    return text.toLowerCase();
+}
+/** Calldata for a view function that takes no arguments. */
+export function callNoArgs(selector) {
+    return selector;
+}
+/** Calldata for one `address` argument: left-padded into a 32-byte word. */
+export function callWithAddress(selector, address, what) {
+    return selector + normalizeAddress(address, what).slice(2).padStart(64, "0");
+}
+/** Calldata for two `address` arguments, in declaration order. */
+export function callWithAddresses(selector, first, second, what) {
+    return (selector +
+        normalizeAddress(first, `${what} (first argument)`).slice(2).padStart(64, "0") +
+        normalizeAddress(second, `${what} (second argument)`).slice(2).padStart(64, "0"));
+}
+/** Calldata for one `uint256` argument. */
+export function callWithUint256(selector, value, what) {
+    if (value < 0n)
+        throw new AbiError(`${what}: a uint256 argument must not be negative`);
+    const hex = value.toString(16);
+    if (hex.length > 64)
+        throw new AbiError(`${what}: ${value} does not fit in a uint256`);
+    return selector + hex.padStart(64, "0");
+}
+/** Calldata for one `bytes32` argument. */
+export function callWithBytes32(selector, value, what) {
+    return selector + normalizeBytes32(value, what).slice(2);
+}
+function hexBody(data, what) {
+    const text = data.trim();
+    if (!HEX_DATA.test(text)) {
+        throw new AbiError(`${what}: expected 0x followed by an even number of hex characters`);
+    }
+    return text.slice(2);
+}
+/**
+ * Split return data into exactly `count` unsigned 32-byte words.
+ *
+ * Exactly, not at least: a contract that answered with fewer words than its
+ * signature promises did not answer the question, and an address with no code
+ * answers `0x` — which zero-pads into a perfectly plausible price of zero if
+ * anyone lets it. `@crewhaus/tool-onchain`'s decoder takes the same line.
+ */
+export function decodeWords(data, count, what) {
+    const body = hexBody(data, what);
+    if (body.length === 0) {
+        throw new AbiError(`${what}: the call returned no data — the address has no code, or the function does not exist on it`);
+    }
+    if (body.length !== count * 64) {
+        throw new AbiError(`${what}: expected ${count} 32-byte word(s) (${count * 32} bytes), got ${body.length / 2}`);
+    }
+    const words = [];
+    for (let i = 0; i < count; i++) {
+        words.push(BigInt(`0x${body.slice(i * 64, (i + 1) * 64)}`));
+    }
+    return words;
+}
+/**
+ * Reinterpret an unsigned word as a signed integer of `bits` width.
+ *
+ * A Chainlink `answer` is an int256 and a Pyth `expo` is an int32, and both
+ * are genuinely negative in the wild: `expo` is almost always negative, and a
+ * feed reporting a negative answer is the signal that something is wrong with
+ * it. Read unsigned, that same feed reports about 1.15e77 and the position
+ * built on it looks spectacularly solvent.
+ */
+export function asSigned(word, bits) {
+    if (!Number.isInteger(bits) || bits <= 0 || bits > 256) {
+        throw new AbiError(`asSigned: ${bits} is not a supported integer width`);
+    }
+    const modulus = 1n << BigInt(bits);
+    const masked = word & (modulus - 1n);
+    return masked >= modulus >> 1n ? masked - modulus : masked;
+}
+/**
+ * Read a 32-byte word as an `address`.
+ *
+ * The low 20 bytes are the address; the upper 12 are padding that the ABI says
+ * is zero and that nothing on the receiving end enforces. `@crewhaus/tool-onchain`'s
+ * decoder takes the low 20 bytes and ignores the rest, so this does too —
+ * formatting the WHOLE word instead produces a 66-character string that is not
+ * an address, which every downstream address check then rejects, so one
+ * non-conforming contract takes out the read rather than the padding it
+ * violated. The dirty padding is reported rather than swallowed: it is also
+ * what calling the wrong function on the right contract looks like.
+ */
+export function addressFromWord(word) {
+    const low = word & ((1n << 160n) - 1n);
+    return {
+        address: `0x${low.toString(16).padStart(40, "0")}`,
+        paddingDirty: word !== low,
+    };
+}
+/** A contract-supplied label longer than this is not a label. "ETH / USD" is nine. */
+export const MAX_CONTRACT_TEXT_CHARS = 128;
+/**
+ * Make a contract-supplied string safe to put in a result.
+ *
+ * Every string in this package's output that did not come from the caller came
+ * from a contract, and a contract's bytes are written by whoever deployed it —
+ * which, for a feed address a caller was handed, is not the caller. A real
+ * aggregator's `description()` is nine characters; a long one is not a label,
+ * it is somebody using the one free-text field here as a way into the reader's
+ * context. Control characters go the same way: a newline in returned bytes
+ * lets them impersonate the lines printed around them.
+ *
+ * Truncation is REPORTED, never silent — a label quietly cut at 128 characters
+ * is a different label, and "this address is the pair you meant" is exactly the
+ * check a shortened one would pass by accident.
+ */
+export function sanitizeContractText(raw, maxChars = MAX_CONTRACT_TEXT_CHARS) {
+    let hadControlCharacters = false;
+    let out = "";
+    for (const character of raw) {
+        const code = character.codePointAt(0) ?? 0;
+        if (code < 0x20 || (code >= 0x7f && code <= 0x9f)) {
+            hadControlCharacters = true;
+            out += "\uFFFD";
+            continue;
+        }
+        out += character;
+    }
+    const truncated = [...out].length > maxChars;
+    return {
+        text: truncated ? `${[...out].slice(0, maxChars).join("")}\u2026` : out,
+        truncated,
+        hadControlCharacters,
+    };
+}
+/**
+ * Decode return data holding one dynamic `string`.
+ *
+ * Head word is a byte OFFSET from the start of the data, not an index; the
+ * word at that offset is the byte length, and the bytes follow it padded up to
+ * a word boundary. Treating the offset as a length is the classic misread, and
+ * it produces a plausible short string rather than an error.
+ *
+ * `maxBytes` is a refusal, not a truncation: a node may return up to
+ * MAX_RESPONSE_BYTES, so without it a contract can hand back a megabyte of
+ * text that this would decode in full and carry into somebody's context window.
+ */
+export function decodeString(data, what, maxBytes = 1024) {
+    const body = hexBody(data, what);
+    if (body.length < 128) {
+        throw new AbiError(`${what}: a returned string needs at least two words, got ${body.length / 2} bytes`);
+    }
+    const offset = Number(BigInt(`0x${body.slice(0, 64)}`));
+    if (!Number.isSafeInteger(offset) || offset % 32 !== 0 || offset * 2 + 64 > body.length) {
+        throw new AbiError(`${what}: the string's offset word (${offset}) does not point inside the data`);
+    }
+    const lengthAt = offset * 2;
+    const length = Number(BigInt(`0x${body.slice(lengthAt, lengthAt + 64)}`));
+    if (!Number.isSafeInteger(length) || lengthAt + 64 + length * 2 > body.length) {
+        throw new AbiError(`${what}: the string claims ${length} bytes, past the end of the data`);
+    }
+    if (length > maxBytes) {
+        throw new AbiError(`${what}: the string is ${length} bytes, past the ${maxBytes} this reads from a contract — a label that long is not a label`);
+    }
+    const bytes = body.slice(lengthAt + 64, lengthAt + 64 + length * 2);
+    const out = new Uint8Array(length);
+    for (let i = 0; i < length; i++)
+        out[i] = Number.parseInt(bytes.slice(i * 2, i * 2 + 2), 16);
+    return new TextDecoder("utf-8", { fatal: false }).decode(out);
+}
+/** The largest uint256, which several protocols use to mean "unbounded". */
+export const UINT256_MAX = (1n << 256n) - 1n;

package/dist/lib/batch.d.ts

@@ -0,0 +1,21 @@
+import { type RpcOptions } from "./rpc";
+/** One read to issue. */
+export type BatchCall = {
+    readonly to: string;
+    readonly data: string;
+    /** What this read is, for the failure message. */
+    readonly label: string;
+};
+/** One read's answer, at the position of the call that asked for it. */
+export type CallOutcome = {
+    readonly ok: true;
+    readonly data: string;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+export type BatchOptions = RpcOptions & {
+    /** The chain's Multicall3 deployment, when the operator has pinned one. */
+    readonly multicall3?: string;
+};
+export declare function batchCalls(endpoint: string, calls: ReadonlyArray<BatchCall>, blockTag: string, options?: BatchOptions): Promise<ReadonlyArray<CallOutcome>>;

package/dist/lib/batch.js

@@ -0,0 +1,83 @@
+/**
+ * Reading several contracts as one answer.
+ *
+ * Every read in a valuation has to come from ONE block height. A balance from
+ * block N and a price from block N+1 is a number that never existed, and it
+ * looks exactly like a number that did. Two things enforce that here:
+ *
+ *   1. The block is PINNED first — `eth_blockNumber`, then every read at that
+ *      hex tag — so a batch is consistent whether it goes out as one
+ *      Multicall3 call or as several plain `eth_call`s.
+ *   2. Multicall3 is an OPTIMISATION, not the mechanism. It is used when the
+ *      operator has pinned its address for the chain, because one round trip
+ *      beats forty; a chain without a pinned deployment reads the same forty
+ *      values at the same pinned block, one call at a time. A tool that
+ *      required Multicall3 would be wrong on every chain that predates it.
+ *
+ * The packing and unpacking is `@crewhaus/tool-onchain`'s `encodeAggregate3` /
+ * `decodeAggregate3`, not a local copy: the argument is an array of dynamic
+ * tuples and the offsets are the part that goes wrong silently.
+ *
+ * One shape difference the two paths must not leak: under Multicall3 a
+ * sub-call that reverts comes back as `success: false` with its revert bytes,
+ * while a plain `eth_call` that reverts comes back as a JSON-RPC error. Both
+ * land here as the same `CallOutcome` row, so nothing downstream has to know
+ * which path it took.
+ */
+import { decodeAggregate3, encodeAggregate3 } from "@crewhaus/tool-onchain";
+import { sanitizeContractText } from "./abi";
+import { ethCall, mapPool } from "./rpc";
+/** How many plain `eth_call`s are in flight at once when there is no Multicall3. */
+const CALL_CONCURRENCY = 6;
+export async function batchCalls(endpoint, calls, blockTag, options = {}) {
+    if (calls.length === 0)
+        return [];
+    if (options.multicall3 !== undefined && calls.length > 1) {
+        return batchThroughMulticall(endpoint, calls, blockTag, options.multicall3, options);
+    }
+    return mapPool(calls, CALL_CONCURRENCY, async (call) => {
+        const outcome = await ethCall(endpoint, call.to, call.data, blockTag, options);
+        return outcome.ok
+            ? { ok: true, data: outcome.value }
+            : { ok: false, reason: `${call.label}: ${outcome.message}` };
+    });
+}
+async function batchThroughMulticall(endpoint, calls, blockTag, multicall3, options) {
+    const request = encodeAggregate3(calls.map((call) => ({ target: call.to, callData: call.data, allowFailure: true })), multicall3);
+    const outcome = await ethCall(endpoint, request.to, request.data, blockTag, options);
+    if (!outcome.ok) {
+        // The batch itself failed, so there is no per-call answer to hand back.
+        // Every row carries the same reason rather than one row failing and the
+        // rest reading as empty.
+        return calls.map((call) => ({
+            ok: false,
+            reason: `${call.label}: the Multicall3 batch failed — ${outcome.message}`,
+        }));
+    }
+    let rows;
+    try {
+        rows = decodeAggregate3(outcome.value, calls.length);
+    }
+    catch (err) {
+        return calls.map((call) => ({
+            ok: false,
+            reason: `${call.label}: the Multicall3 answer could not be read — ${err.message}`,
+        }));
+    }
+    return rows.map((row, index) => {
+        const call = calls[index];
+        if (row.success)
+            return { ok: true, data: row.returnData };
+        // A revert string is written by the contract, and this one ends up in a
+        // tool result and then in a model's context. It is capped and scrubbed for
+        // the same reason `description()` is: a `revert(...)` is a free-text field
+        // an attacker controls, and a newline in it lets it impersonate the lines
+        // around it.
+        const reason = row.revert?.reason;
+        const safe = reason === null || reason === undefined ? null : sanitizeContractText(reason).text;
+        return {
+            ok: false,
+            reason: `${call.label}: the call reverted${safe === null ? "" : ` — ${safe}`}`,
+        };
+    });
+}

package/dist/lib/decimal.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Exact decimal arithmetic on `{ unscaled, scale }` pairs.
+ *
+ * Everything this package values is ALREADY a scaled integer: a token balance
+ * is a uint256 with the token's decimals, a Chainlink answer is an int256 with
+ * the feed's `decimals()`, a Pyth price is an int64 with its own exponent. So
+ * `{ unscaled: balance, scale: 18 }` IS the balance, exactly, and no parsing
+ * step is needed to get there. `Number(balance)` would keep fifteen of its
+ * digits and quietly drop the rest, which for 18 decimals is the difference
+ * between a wei and a thousand of them.
+ *
+ * WHY THIS IS NOT IMPORTED FROM `@crewhaus/tool-math`: that package owns this
+ * monorepo's decimal kernel and this file mirrors it, but its entrypoint
+ * exports only its tools, `statsKernel` and the currency table — the kernel
+ * itself is module-private. Reaching past another package's entrypoint is the
+ * thing `@crewhaus/tool-table` names as the wrong move, and widening
+ * tool-math's surface mid-wave, while sibling packages are being written into
+ * the same checkout, is how one agent's edit lands on top of another's. So the
+ * arithmetic lives here and `lib.test.ts` pins every rounding case in it
+ * against tool-math's `Round` tool, through that public surface, on the ties
+ * and modes where two implementations diverge if they ever will.
+ */
+/** A rounding mode, named at every call site that can lose a digit. */
+export type RoundingMode = "halfEven" | "halfUp" | "down";
+/**
+ * An exact decimal: `unscaled / 10^scale`. `scale` is non-negative — a value
+ * that would need a negative scale is normalised by multiplying the integer
+ * instead, so there is one representation of "this many, at this precision".
+ */
+export type Fixed = {
+    readonly unscaled: bigint;
+    readonly scale: number;
+};
+export declare class DecimalError extends Error {
+    readonly name = "DecimalError";
+}
+/** Scales past this are a bug, not a price. 18 decimals plus a cross is ~40. */
+export declare const MAX_SCALE = 80;
+export declare function pow10(n: number): bigint;
+/** Build a Fixed, normalising a negative scale into the integer part. */
+export declare function fixed(unscaled: bigint, scale: number): Fixed;
+export declare const ZERO: Fixed;
+/** An integer as a Fixed. */
+export declare function fromInteger(value: bigint): Fixed;
+/**
+ * Parse a plain decimal string exactly.
+ *
+ * Exponent notation is refused rather than accepted: every literal this
+ * package reads comes from a price provider or a caller writing an amount, and
+ * `1e-7` in either place is far more likely to be a float that has already
+ * been through a double than a deliberate exponent.
+ */
+export declare function parseFixed(text: string, what: string): Fixed;
+/**
+ * Read a number that arrived inside a JSON document.
+ *
+ * `JSON.parse` turns a bare numeric literal into a double before anything here
+ * sees it, so a provider that publishes its rate as `0.85431` hands us the
+ * nearest double to that, not the digits. `String(value)` gives the shortest
+ * decimal that round-trips to the same double, which is exact for anything up
+ * to seventeen significant digits — an ECB reference rate has five. A provider
+ * that published a twenty-digit price as a bare number would lose the tail, so
+ * the caller is told which kind of literal a price came from rather than left
+ * to assume; see `PriceLiteralKind` below and the `literal` field on a quote.
+ */
+export declare function fixedFromJson(value: unknown, what: string): {
+    value: Fixed;
+    kind: PriceLiteralKind;
+};
+/** Whether a price arrived as a JSON string (exact) or a JSON number (through a double). */
+export type PriceLiteralKind = "string" | "number";
+export declare function isZero(value: Fixed): boolean;
+export declare function isPositive(value: Fixed): boolean;
+export declare function negate(value: Fixed): Fixed;
+export declare function absolute(value: Fixed): Fixed;
+export declare function add(a: Fixed, b: Fixed): Fixed;
+export declare function subtract(a: Fixed, b: Fixed): Fixed;
+/** -1, 0 or 1. */
+export declare function compare(a: Fixed, b: Fixed): number;
+/**
+ * The exact product. Scales add, so nothing is rounded here — a balance at 18
+ * decimals times a price at 8 is a value at 26, and the rounding happens once,
+ * at the end, where a mode can be named for it.
+ */
+export declare function multiply(a: Fixed, b: Fixed): Fixed;
+/** Integer division with the named mode. Shared by `divide` and `roundToPlaces`. */
+export declare function divideRound(numerator: bigint, denominator: bigint, mode: RoundingMode): bigint;
+/** `a / b`, carried to `scale` decimal places with the named mode. */
+export declare function divide(a: Fixed, b: Fixed, scale: number, mode: RoundingMode): Fixed;
+/** Round to a fixed number of decimal places. */
+export declare function roundToPlaces(value: Fixed, places: number, mode: RoundingMode): Fixed;
+/** Drop trailing zeros without changing the value: 1.500 -> 1.5, 100 stays 100. */
+export declare function trim(value: Fixed): Fixed;
+/** Plain decimal notation, always. Never `1e-7`, never a float. */
+export declare function toDecimalString(value: Fixed): string;
+/**
+ * A ratio in basis points, rounded down.
+ *
+ * Down, deliberately: every caller of this is reporting a share or a spread,
+ * and a share rounded up can make a set of weights sum past 10000, which reads
+ * as an arithmetic bug in the output rather than as the rounding it is.
+ */
+export declare function ratioBps(part: Fixed, whole: Fixed): number;