@crewhaus/tool-chaincall 0.7.0

package/dist/lib/batch.d.ts

@@ -0,0 +1,13 @@
+import type { Aggregate3Result, Call3 } from "@crewhaus/tool-onchain";
+import { type ChainRpc } from "./rpc";
+export type { Aggregate3Result, Call3 };
+/**
+ * Send one `aggregate3` and return the per-call rows.
+ *
+ * `block` is a tag or a quantity and is passed through verbatim; pinning it
+ * to a number is the caller's job, because only the caller knows whether it
+ * is sending one batch or five.
+ */
+export declare function runAggregate3(rpc: ChainRpc, chainId: string, calls: ReadonlyArray<Call3>, multicall3Address: string, block: string, signal: AbortSignal, what: string): Promise<ReadonlyArray<Aggregate3Result>>;
+/** Split into runs of at most `size`, preserving order. */
+export declare function chunk<T>(items: ReadonlyArray<T>, size: number): T[][];

package/dist/lib/batch.js

@@ -0,0 +1,55 @@
+/**
+ * Driving a Multicall3 batch: pack, one `eth_call`, unpack.
+ *
+ * The packing and unpacking are `@crewhaus/tool-onchain`'s
+ * `encodeAggregate3` / `decodeAggregate3` — this file adds only the round
+ * trip and the distinction the whole batch idea rests on:
+ *
+ *   - a SUB-CALL that reverted is a row, with `success: false` and its
+ *     revert bytes;
+ *   - the BATCH failing is an exception, because there are then no rows at
+ *     all and the caller's next move is different.
+ *
+ * `decodeAggregate3` already refuses a blob whose result count does not
+ * match the batch that was sent. That refusal is load-bearing: results are
+ * matched by position and nothing in them names the call they answer, so a
+ * short answer zipped against the calls sent attributes every result after
+ * the gap to the wrong contract.
+ */
+import { decodeAggregate3, encodeAggregate3 } from "@crewhaus/tool-onchain";
+import { data as asData } from "./hex";
+import { ChainCallError, isAbort, rpcErrorText, rpcRead } from "./rpc";
+/**
+ * Send one `aggregate3` and return the per-call rows.
+ *
+ * `block` is a tag or a quantity and is passed through verbatim; pinning it
+ * to a number is the caller's job, because only the caller knows whether it
+ * is sending one batch or five.
+ */
+export async function runAggregate3(rpc, chainId, calls, multicall3Address, block, signal, what) {
+    const request = encodeAggregate3(calls, multicall3Address);
+    let raw;
+    try {
+        raw = await rpcRead(rpc, chainId, "eth_call", [{ to: request.to, data: request.data }, block], signal);
+    }
+    catch (err) {
+        // A cancellation passes through unchanged. Dressing it as "the batch
+        // failed" would send a caller looking for a missing Multicall3 deploy
+        // when what actually happened is that their deadline ran out.
+        if (isAbort(err, signal))
+            throw err;
+        // The aggregate call itself failing is not a sub-call reverting. It means
+        // the batch never ran: no Multicall3 at that address on this chain, a
+        // block the node has pruned, a gas cap the batch went past, or a sub-call
+        // with allowFailure:false taking the whole batch down with it.
+        throw new ChainCallError(`${what}: the Multicall3 batch itself failed at ${request.to} — ${rpcErrorText(err)}`, err);
+    }
+    return decodeAggregate3(asData(raw, `${what}: the batch's return data`), request.callCount);
+}
+/** Split into runs of at most `size`, preserving order. */
+export function chunk(items, size) {
+    const out = [];
+    for (let i = 0; i < items.length; i += size)
+        out.push(items.slice(i, i + size));
+    return out;
+}

package/dist/lib/codec.d.ts

@@ -0,0 +1,49 @@
+/** Encode a call from a signature and its arguments. Throws on a bad type. */
+export declare function encodeCallData(signature: string, args: ReadonlyArray<unknown>, what: string): Promise<string>;
+/** Decode return data against a list of ABI types. */
+export declare function decodeValues(types: ReadonlyArray<string>, hex: string, what: string): Promise<unknown[]>;
+export type CheckedAddress = {
+    /** EIP-55 mixed case, which is what goes into any output. */
+    readonly address: string;
+    readonly lowercase: string;
+    /**
+     * Whether the input CARRIED a checksum this verified. An all-lowercase
+     * address is well-formed and unverifiable, and the difference matters
+     * enough that it travels with the answer rather than collapsing into
+     * "valid".
+     */
+    readonly checksumVerified: boolean;
+    readonly isZero: boolean;
+};
+/** Validate an address through `tool-onchain`'s EIP-55 implementation. */
+export declare function checkAddress(raw: string, what: string): Promise<CheckedAddress>;
+/**
+ * Selectors this package builds calldata from, with the signature each one
+ * is the hash of. `lib.test.ts` recomputes all of them.
+ */
+export declare const SELECTORS: Readonly<{
+    /** Multicall3, self-called inside a batch to learn the block it ran at. */
+    readonly getBlockNumber: "0x42cbb15c";
+    /** Multicall3, so a native balance can be read inside a batch. */
+    readonly getEthBalance: "0x4d2301cc";
+    /** ERC-20. */
+    readonly balanceOf: "0x70a08231";
+    /** ERC-165. */
+    readonly supportsInterface: "0x01ffc9a7";
+    /** What a transparent or UUPS proxy tends to expose as a view. */
+    readonly implementation: "0x5c60da1b";
+    /** EIP-1822's marker method; also what EIP-1967 UUPS proxies implement. */
+    readonly proxiableUUID: "0x52d1902d";
+}>;
+/** The signature each selector above is the Keccak prefix of. */
+export declare const SELECTOR_SIGNATURES: Readonly<Record<keyof typeof SELECTORS, string>>;
+/** Left-pad an address into a 32-byte argument word. */
+export declare function addressArg(address: string): string;
+/** Right-pad a `bytes4` into its 32-byte argument word. */
+export declare function bytes4Arg(id: string): string;
+/** `supportsInterface(interfaceId)` calldata. */
+export declare function supportsInterfaceData(interfaceId: string): string;
+/** `getEthBalance(account)` calldata, for Multicall3. */
+export declare function getEthBalanceData(account: string): string;
+/** `balanceOf(account)` calldata, for an ERC-20. */
+export declare function balanceOfData(account: string): string;

package/dist/lib/codec.js

@@ -0,0 +1,113 @@
+/**
+ * The ABI codec this package uses, which is somebody else's.
+ *
+ * `@crewhaus/tool-onchain` owns the encoder, the decoder, the EIP-55
+ * checksum and the Multicall3 packing. It publishes the first three as
+ * TOOLS rather than as functions — its module surface is `RegisteredTool`s
+ * plus the multicall helpers — so this file calls those tools' `execute`
+ * directly and parses the JSON they return.
+ *
+ * That indirection is deliberate and cheap. The alternative is a second ABI
+ * encoder living here, and a second encoder is a second set of tail offsets
+ * to get wrong: calldata with a misplaced offset is accepted by every node
+ * and misread by the contract, which is a wrong answer rather than an error.
+ * One encoder, one place it can be wrong, one place it gets fixed.
+ *
+ * The four-byte selectors below are constants because computing them needs
+ * Keccak, which this package does not depend on. They are not trusted on
+ * sight: `lib.test.ts` recomputes every one of them with `tool-onchain`'s
+ * own `FunctionSelector` and fails if a digit is off.
+ */
+import { abiDecode, abiEncodeCall, addressCheck } from "@crewhaus/tool-onchain";
+import { ChainCallError } from "./rpc";
+/** Read a tool result that is known to be a JSON string. */
+async function toolJson(tool, input, what) {
+    const result = await tool.execute(input);
+    if (typeof result !== "string") {
+        throw new ChainCallError(`${what}: ${tool.name} returned non-text content`);
+    }
+    return JSON.parse(result);
+}
+/** Encode a call from a signature and its arguments. Throws on a bad type. */
+export async function encodeCallData(signature, args, what) {
+    const out = await toolJson(abiEncodeCall, { signature, args }, what);
+    const encoded = out["data"];
+    if (typeof encoded !== "string")
+        throw new ChainCallError(`${what}: could not encode the call`);
+    return encoded;
+}
+/** Decode return data against a list of ABI types. */
+export async function decodeValues(types, hex, what) {
+    const out = await toolJson(abiDecode, { data: hex, types }, what);
+    const values = out["values"];
+    if (!Array.isArray(values))
+        throw new ChainCallError(`${what}: could not decode the result`);
+    return values;
+}
+/** Validate an address through `tool-onchain`'s EIP-55 implementation. */
+export async function checkAddress(raw, what) {
+    const out = await toolJson(addressCheck, { address: raw }, what);
+    if (out["valid"] !== true) {
+        throw new ChainCallError(`${what}: ${String(out["reason"] ?? "not a valid address")}`);
+    }
+    return {
+        address: String(out["checksummed"]),
+        lowercase: String(out["lowercase"]),
+        checksumVerified: out["hadChecksum"] === true,
+        isZero: out["isZero"] === true,
+    };
+}
+// ---------------------------------------------------------------------------
+// selectors
+// ---------------------------------------------------------------------------
+/**
+ * Selectors this package builds calldata from, with the signature each one
+ * is the hash of. `lib.test.ts` recomputes all of them.
+ */
+export const SELECTORS = Object.freeze({
+    /** Multicall3, self-called inside a batch to learn the block it ran at. */
+    getBlockNumber: "0x42cbb15c",
+    /** Multicall3, so a native balance can be read inside a batch. */
+    getEthBalance: "0x4d2301cc",
+    /** ERC-20. */
+    balanceOf: "0x70a08231",
+    /** ERC-165. */
+    supportsInterface: "0x01ffc9a7",
+    /** What a transparent or UUPS proxy tends to expose as a view. */
+    implementation: "0x5c60da1b",
+    /** EIP-1822's marker method; also what EIP-1967 UUPS proxies implement. */
+    proxiableUUID: "0x52d1902d",
+});
+/** The signature each selector above is the Keccak prefix of. */
+export const SELECTOR_SIGNATURES = Object.freeze({
+    getBlockNumber: "getBlockNumber()",
+    getEthBalance: "getEthBalance(address)",
+    balanceOf: "balanceOf(address)",
+    supportsInterface: "supportsInterface(bytes4)",
+    implementation: "implementation()",
+    proxiableUUID: "proxiableUUID()",
+});
+/** Left-pad an address into a 32-byte argument word. */
+export function addressArg(address) {
+    return address.replace(/^0x/, "").toLowerCase().padStart(64, "0");
+}
+/** Right-pad a `bytes4` into its 32-byte argument word. */
+export function bytes4Arg(id) {
+    const body = id.replace(/^0x/, "").toLowerCase();
+    if (!/^[0-9a-f]{8}$/.test(body)) {
+        throw new ChainCallError(`an interface id is 0x followed by 8 hex digits, got "${id}"`);
+    }
+    return body.padEnd(64, "0");
+}
+/** `supportsInterface(interfaceId)` calldata. */
+export function supportsInterfaceData(interfaceId) {
+    return `${SELECTORS.supportsInterface}${bytes4Arg(interfaceId)}`;
+}
+/** `getEthBalance(account)` calldata, for Multicall3. */
+export function getEthBalanceData(account) {
+    return `${SELECTORS.getEthBalance}${addressArg(account)}`;
+}
+/** `balanceOf(account)` calldata, for an ERC-20. */
+export function balanceOfData(account) {
+    return `${SELECTORS.balanceOf}${addressArg(account)}`;
+}

package/dist/lib/fees.d.ts

@@ -0,0 +1,61 @@
+/** `gasLimit / elasticity` is the gas target a block is measured against. */
+export declare const DEFAULT_ELASTICITY = 2n;
+/** The 1/8 the base fee may move by in one block. */
+export declare const BASE_FEE_MAX_CHANGE_DENOMINATOR = 8n;
+export type BaseFeeProjection = {
+    readonly next: bigint;
+    readonly target: bigint;
+    readonly direction: "up" | "down" | "flat";
+};
+/**
+ * The next block's base fee, by the EIP-1559 rule.
+ *
+ * Three cases and one floor. At exactly the target the fee is unchanged;
+ * above it the fee rises by `parent * excess / target / 8` with a minimum of
+ * one wei (the spec's `max(1, …)`, which is what stops a chain with a
+ * one-wei base fee from being stuck there through full blocks); below it the
+ * fee falls by the same expression with no such floor.
+ *
+ * A zero `gasLimit` — which only a malformed block has — returns the parent
+ * fee rather than dividing by zero.
+ */
+export declare function nextBaseFee(parentBaseFee: bigint, gasUsed: bigint, gasLimit: bigint, elasticity?: bigint, denominator?: bigint): BaseFeeProjection;
+/**
+ * The median of a list of bigints, with the low middle chosen for an even
+ * count rather than an average.
+ *
+ * Averaging two adjacent samples invents a wei value that no block ever
+ * charged. For a fee percentile, "a tip this size was enough in half the
+ * sampled blocks" is a statement about an observed sample, and the lower of
+ * the two middles is still one of the observations.
+ */
+export declare function medianOf(values: ReadonlyArray<bigint>): bigint | undefined;
+export type PercentileSummary = {
+    readonly percentile: number;
+    readonly medianWei: string;
+    readonly minWei: string;
+    readonly maxWei: string;
+    /** How many sampled blocks contributed a reward at this percentile. */
+    readonly samples: number;
+};
+/**
+ * Summarise one column of `feeHistory.reward`.
+ *
+ * The node computes each percentile per block; this reduces the column
+ * across the window. Blocks with no reward entry — an empty block has no
+ * transactions to take a percentile of — are counted out rather than read as
+ * a zero tip, because "nobody paid anything" and "nobody paid" are different
+ * claims and only one of them is true.
+ */
+export declare function summarisePercentile(percentile: number, column: ReadonlyArray<bigint>): PercentileSummary | undefined;
+/**
+ * How far the base fee moved across the window, in basis points of where it
+ * started. Reported instead of a "rising"/"falling" word because the word
+ * needs a threshold nobody agreed on, and one 1559 step is already 1250 bps.
+ *
+ * A decimal STRING, like every other figure derived from a wei value here. A
+ * chain whose base fee sits at a one-wei floor and then spikes produces a
+ * ratio past 2^53, and `Number()` turns that into `1e+34` — a value that is
+ * neither an integer nor the one that was computed.
+ */
+export declare function changeBps(first: bigint, last: bigint): string | undefined;

package/dist/lib/fees.js

@@ -0,0 +1,113 @@
+/**
+ * The EIP-1559 base-fee rule, and the statistics over a fee-history window.
+ *
+ * All of it is integer arithmetic on `bigint`. That is not fastidiousness:
+ * `eth_feeHistory` returns `gasUsedRatio` as a JSON FLOAT, and computing the
+ * next base fee from that float is the obvious shortcut and the wrong answer
+ * — the ratio has already lost the low bits of `gasUsed`, and the rule
+ * multiplies a wei value by it. So the projection reads `gasUsed` and
+ * `gasLimit` off the block as integers and never touches the ratio.
+ *
+ * The other thing this file refuses to do is assume. Not every chain runs a
+ * 1559 market, and several that look like one do not follow the vanilla rule
+ * — a different elasticity, a different denominator, or a constant floor
+ * that never moves. So the projection is COMPARED against the value the node
+ * itself put at the end of `feeHistory.baseFeePerGas`, and a disagreement is
+ * reported rather than hidden behind whichever number came first.
+ */
+import { ChainCallError } from "./rpc";
+/** `gasLimit / elasticity` is the gas target a block is measured against. */
+export const DEFAULT_ELASTICITY = 2n;
+/** The 1/8 the base fee may move by in one block. */
+export const BASE_FEE_MAX_CHANGE_DENOMINATOR = 8n;
+/**
+ * The next block's base fee, by the EIP-1559 rule.
+ *
+ * Three cases and one floor. At exactly the target the fee is unchanged;
+ * above it the fee rises by `parent * excess / target / 8` with a minimum of
+ * one wei (the spec's `max(1, …)`, which is what stops a chain with a
+ * one-wei base fee from being stuck there through full blocks); below it the
+ * fee falls by the same expression with no such floor.
+ *
+ * A zero `gasLimit` — which only a malformed block has — returns the parent
+ * fee rather than dividing by zero.
+ */
+export function nextBaseFee(parentBaseFee, gasUsed, gasLimit, elasticity = DEFAULT_ELASTICITY, denominator = BASE_FEE_MAX_CHANGE_DENOMINATOR) {
+    if (elasticity <= 0n || denominator <= 0n) {
+        throw new ChainCallError("the 1559 elasticity and denominator must both be positive");
+    }
+    const target = gasLimit / elasticity;
+    if (target === 0n)
+        return { next: parentBaseFee, target, direction: "flat" };
+    if (gasUsed === target)
+        return { next: parentBaseFee, target, direction: "flat" };
+    if (gasUsed > target) {
+        const raw = (parentBaseFee * (gasUsed - target)) / target / denominator;
+        const delta = raw > 0n ? raw : 1n;
+        return { next: parentBaseFee + delta, target, direction: "up" };
+    }
+    const delta = (parentBaseFee * (target - gasUsed)) / target / denominator;
+    const next = parentBaseFee - delta;
+    return { next: next > 0n ? next : 0n, target, direction: "down" };
+}
+/**
+ * The median of a list of bigints, with the low middle chosen for an even
+ * count rather than an average.
+ *
+ * Averaging two adjacent samples invents a wei value that no block ever
+ * charged. For a fee percentile, "a tip this size was enough in half the
+ * sampled blocks" is a statement about an observed sample, and the lower of
+ * the two middles is still one of the observations.
+ */
+export function medianOf(values) {
+    if (values.length === 0)
+        return undefined;
+    const sorted = [...values].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    return sorted[(sorted.length - 1) >> 1];
+}
+/**
+ * Summarise one column of `feeHistory.reward`.
+ *
+ * The node computes each percentile per block; this reduces the column
+ * across the window. Blocks with no reward entry — an empty block has no
+ * transactions to take a percentile of — are counted out rather than read as
+ * a zero tip, because "nobody paid anything" and "nobody paid" are different
+ * claims and only one of them is true.
+ */
+export function summarisePercentile(percentile, column) {
+    if (column.length === 0)
+        return undefined;
+    const median = medianOf(column);
+    if (median === undefined)
+        return undefined;
+    let min = column[0];
+    let max = column[0];
+    for (const value of column) {
+        if (value < min)
+            min = value;
+        if (value > max)
+            max = value;
+    }
+    return {
+        percentile,
+        medianWei: median.toString(),
+        minWei: min.toString(),
+        maxWei: max.toString(),
+        samples: column.length,
+    };
+}
+/**
+ * How far the base fee moved across the window, in basis points of where it
+ * started. Reported instead of a "rising"/"falling" word because the word
+ * needs a threshold nobody agreed on, and one 1559 step is already 1250 bps.
+ *
+ * A decimal STRING, like every other figure derived from a wei value here. A
+ * chain whose base fee sits at a one-wei floor and then spikes produces a
+ * ratio past 2^53, and `Number()` turns that into `1e+34` — a value that is
+ * neither an integer nor the one that was computed.
+ */
+export function changeBps(first, last) {
+    if (first === 0n)
+        return undefined;
+    return (((last - first) * 10000n) / first).toString();
+}

package/dist/lib/hex.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Read a JSON-RPC QUANTITY as a bigint.
+ *
+ * Leading zeros are tolerated rather than refused: several providers emit
+ * `0x0000…` for a zero field, and rejecting a node's own formatting habit
+ * would fail a read that is perfectly well-defined. What is refused is
+ * anything that is not hex at all, a decimal string that a caller mistook
+ * for a quantity, and `0x` with no digits.
+ */
+export declare function quantity(value: unknown, what: string): bigint;
+/** Same, but a missing or null field is an absent value rather than an error. */
+export declare function optionalQuantity(value: unknown, what: string): bigint | undefined;
+/** Render a bigint as a minimal QUANTITY, the form the wire wants. */
+export declare function toQuantity(value: bigint): string;
+/**
+ * Validate a 0x DATA string and lowercase it. `0x` passes: an empty return
+ * is the single most important value in this package, because it is what an
+ * address with no code answers, and treating it as an error loses the fact.
+ */
+export declare function data(value: unknown, what: string): string;
+/** Byte count of a 0x DATA string. */
+export declare function byteLength(hex: string): number;
+/**
+ * The 32-byte word at `index`, or undefined when the data is shorter.
+ *
+ * Returning undefined rather than a zero word is the point: a short answer
+ * that gets padded reads as a real zero, and "the balance is 0" is exactly
+ * the wrong thing to say about a call that did not return one.
+ */
+export declare function wordAt(hex: string, index: number): string | undefined;
+/** A 32-byte word as an unsigned integer. */
+export declare function wordToBigint(word: string): bigint;
+/**
+ * The address in the low 20 bytes of a word, lowercased.
+ *
+ * The high 12 bytes must be zero. A storage slot whose top bytes are dirty
+ * is not an address that happens to have junk above it — it is a slot that
+ * holds something else, and silently masking it off would report a proxy's
+ * implementation as whatever the low bytes of a packed struct happen to be.
+ */
+export declare function wordToAddress(word: string, what: string): string;
+/** True when a 32-byte word is all zeros: an unset slot. */
+export declare function isZeroWord(word: string): boolean;
+/** A bool return value: 32 bytes, zero for false, anything else for true. */
+export declare function wordToBool(word: string): boolean;
+/** The zero address, which is what an unset slot decodes to. */
+export declare const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+/**
+ * A block tag or number, as the wire wants it.
+ *
+ * A number arrives as a decimal STRING and leaves as a quantity: a block
+ * number past 2^53 is not a today problem, but the rule that no chain
+ * quantity passes through a JS number has no exceptions in this package,
+ * because the exceptions are what get copied.
+ */
+export declare function blockParam(blockNumber: string | undefined, blockTag: string | undefined): string;

package/dist/lib/hex.js

@@ -0,0 +1,118 @@
+/**
+ * Hex on the wire, integers in memory, decimal strings on the way out.
+ *
+ * JSON-RPC speaks two hex dialects and conflating them is a real bug class:
+ * a QUANTITY is minimal-length with no leading zeros (`0x1`), and DATA is a
+ * byte string with an even number of digits (`0x01`). `0x` is a legal empty
+ * DATA — it is what an `eth_call` to an address with no code returns — and
+ * is NOT a legal quantity.
+ *
+ * Nothing here ever produces a JS `number` for a chain value. A uint256 is
+ * 78 decimal digits and a double carries about 15, so a balance read into a
+ * number is wrong in its low bits while still printing plausibly. Quantities
+ * come back as `bigint` and leave this package as decimal strings.
+ */
+import { ChainCallError } from "./rpc";
+const LOOSE_QUANTITY = /^0x[0-9a-fA-F]+$/;
+const DATA = /^0x([0-9a-fA-F]{2})*$/;
+/**
+ * Read a JSON-RPC QUANTITY as a bigint.
+ *
+ * Leading zeros are tolerated rather than refused: several providers emit
+ * `0x0000…` for a zero field, and rejecting a node's own formatting habit
+ * would fail a read that is perfectly well-defined. What is refused is
+ * anything that is not hex at all, a decimal string that a caller mistook
+ * for a quantity, and `0x` with no digits.
+ */
+export function quantity(value, what) {
+    if (typeof value === "bigint")
+        return value;
+    if (typeof value !== "string" || !LOOSE_QUANTITY.test(value)) {
+        throw new ChainCallError(`${what}: expected a 0x-prefixed hex quantity, got ${JSON.stringify(value)}`);
+    }
+    return BigInt(value);
+}
+/** Same, but a missing or null field is an absent value rather than an error. */
+export function optionalQuantity(value, what) {
+    return value === undefined || value === null ? undefined : quantity(value, what);
+}
+/** Render a bigint as a minimal QUANTITY, the form the wire wants. */
+export function toQuantity(value) {
+    if (value < 0n)
+        throw new ChainCallError(`a JSON-RPC quantity cannot be negative, got ${value}`);
+    return `0x${value.toString(16)}`;
+}
+/**
+ * Validate a 0x DATA string and lowercase it. `0x` passes: an empty return
+ * is the single most important value in this package, because it is what an
+ * address with no code answers, and treating it as an error loses the fact.
+ */
+export function data(value, what) {
+    if (typeof value !== "string" || !DATA.test(value.trim())) {
+        throw new ChainCallError(`${what}: expected 0x followed by an even number of hex digits, got ${JSON.stringify(value)}`);
+    }
+    return value.trim().toLowerCase();
+}
+/** Byte count of a 0x DATA string. */
+export function byteLength(hex) {
+    return (hex.length - 2) / 2;
+}
+/**
+ * The 32-byte word at `index`, or undefined when the data is shorter.
+ *
+ * Returning undefined rather than a zero word is the point: a short answer
+ * that gets padded reads as a real zero, and "the balance is 0" is exactly
+ * the wrong thing to say about a call that did not return one.
+ */
+export function wordAt(hex, index) {
+    const start = 2 + index * 64;
+    return hex.length >= start + 64 ? `0x${hex.slice(start, start + 64)}` : undefined;
+}
+/** A 32-byte word as an unsigned integer. */
+export function wordToBigint(word) {
+    return BigInt(word);
+}
+/**
+ * The address in the low 20 bytes of a word, lowercased.
+ *
+ * The high 12 bytes must be zero. A storage slot whose top bytes are dirty
+ * is not an address that happens to have junk above it — it is a slot that
+ * holds something else, and silently masking it off would report a proxy's
+ * implementation as whatever the low bytes of a packed struct happen to be.
+ */
+export function wordToAddress(word, what) {
+    const body = word.replace(/^0x/, "").toLowerCase();
+    if (body.length !== 64)
+        throw new ChainCallError(`${what}: expected a 32-byte word`);
+    if (!/^0{24}/.test(body)) {
+        throw new ChainCallError(`${what}: the top 12 bytes of ${word} are not zero, so this slot does not hold an address`);
+    }
+    return `0x${body.slice(24)}`;
+}
+/** True when a 32-byte word is all zeros: an unset slot. */
+export function isZeroWord(word) {
+    return /^0x0{64}$/.test(word.toLowerCase());
+}
+/** A bool return value: 32 bytes, zero for false, anything else for true. */
+export function wordToBool(word) {
+    return !isZeroWord(word);
+}
+/** The zero address, which is what an unset slot decodes to. */
+export const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+/**
+ * A block tag or number, as the wire wants it.
+ *
+ * A number arrives as a decimal STRING and leaves as a quantity: a block
+ * number past 2^53 is not a today problem, but the rule that no chain
+ * quantity passes through a JS number has no exceptions in this package,
+ * because the exceptions are what get copied.
+ */
+export function blockParam(blockNumber, blockTag) {
+    if (blockNumber !== undefined) {
+        if (!/^\d+$/.test(blockNumber.trim())) {
+            throw new ChainCallError(`blockNumber must be a decimal integer string, got ${JSON.stringify(blockNumber)}`);
+        }
+        return toQuantity(BigInt(blockNumber.trim()));
+    }
+    return blockTag ?? "latest";
+}