@gibs/common 1.13.0 → 1.17.0

package/dist/cjs/multicall.d.ts

@@ -0,0 +1,56 @@
+import { type Abi, type Chain, type Hex, type PublicClient } from 'viem';
+import type { Call } from './types.js';
+/** The size limits, exported so tests assert against the real values. */
+export declare const multicallLimits: {
+    readonly endpointBodyLimitBytes: number;
+    readonly httpBodyTargetBytes: number;
+    readonly callDataBudgetBytes: number;
+    readonly chunkConcurrency: 1;
+    readonly perCallOverheadBytes: 400;
+};
+/** An `aggregate3` tuple, already encoded and ready to send. */
+type EncodedCall = {
+    callData: Hex;
+    allowFailure: boolean;
+    target: Hex;
+};
+/**
+ * Splits encoded calls into groups whose combined request body stays under
+ * {@link CALLDATA_BUDGET_BYTES}.
+ *
+ * Grouped by measured size rather than by a fixed count on purpose: callers
+ * differ by more than an order of magnitude in how large one call encodes to — a
+ * bare `balanceOf` against a router quote carrying a swap path — so any single
+ * call limit would be far too cautious for one caller and useless for another.
+ *
+ * A call that exceeds the budget on its own still gets its own group; splitting
+ * it further is not possible, and refusing to send it would turn an oversized
+ * request into a missing result.
+ *
+ * @param encoded - the calls to group, in order
+ * @returns groups preserving the original order
+ */
+export declare const chunkBySize: (encoded: EncodedCall[]) => EncodedCall[][];
+/**
+ * Reads many contract calls through Multicall3, splitting the work across as
+ * many requests as the size budget needs and reassembling the results in order.
+ *
+ * Chunking is invisible to callers: the returned array lines up with `calls`
+ * one-for-one exactly as it did when every call went out together, and a chunk
+ * that rejects still rejects the whole read rather than returning a short array
+ * that a caller would silently misread as "these tokens have no balance".
+ *
+ * @param options.chain - the chain, used for its Multicall3 deployment
+ * @param options.client - the public client to read through
+ * @param options.abi - the default ABI, when a call does not carry its own
+ * @param options.calls - the calls to make, in the order results are wanted
+ * @param options.target - the default contract, when a call does not name one
+ */
+export declare const multicallRead: <T>({ chain, client, abi, calls, target, }: {
+    chain: Chain;
+    client: PublicClient;
+    abi: Abi;
+    calls: Call[];
+    target?: Hex;
+}) => Promise<T>;
+export {};

package/dist/cjs/multicall.js

@@ -0,0 +1,217 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.multicallRead = exports.chunkBySize = exports.multicallLimits = void 0;
+const viem_1 = require("viem");
+const assert_js_1 = require("./assert.js");
+/**
+ * The largest request body the leading endpoint accepts, in bytes. MEASURED,
+ * not assumed.
+ *
+ * `one.valve.city` answers a 102,400 byte body with 200 and a 102,656 byte body
+ * with 413, bisected on 2026-09-12. That is the 100 kibibyte default of
+ * `express.json`, and the proxy leads every chain list this application ships,
+ * so it is the number every other budget here has to clear.
+ *
+ * THE PREVIOUS VALUE WAS A GUESS AND IT WAS FIVE TIMES TOO LARGE. It said "the
+ * one-megabyte body limit that is the default in the reverse proxies these
+ * endpoints sit behind", which is Nginx's default, not Express's — and the
+ * endpoint in front is Express. Nobody had asked the endpoint.
+ */
+const ENDPOINT_BODY_LIMIT_BYTES = 100 * 1024;
+/**
+ * How large a single HTTP request body to the node may get, in bytes.
+ *
+ * Nothing bounded this before, so the whole call list went out at once and the
+ * size followed whatever the caller happened to be reading. The token picker
+ * reads a balance per token, and PulseChain's list runs to about eleven and a
+ * half thousand of them: a single 8.5 MB `eth_call`, repeated on every open,
+ * which `rpc.pulsechain.com` answered with HTTP 413. The caller catches that and
+ * falls back to an empty map, so the visible result was not an error — it was
+ * every balance quietly missing.
+ *
+ * Four kibibytes under {@link ENDPOINT_BODY_LIMIT_BYTES}, because the budget
+ * below counts only the calls: `aggregate3` adds a fixed header of its own and
+ * the JSON-RPC envelope wraps the lot, and neither is charged to a call.
+ */
+const HTTP_BODY_TARGET_BYTES = ENDPOINT_BODY_LIMIT_BYTES - 4 * 1024;
+/**
+ * How many chunks may be in flight at once.
+ *
+ * Splitting a request is only an improvement if the pieces do not arrive as a
+ * burst; an endpoint that rejected one large body will just as happily rate-limit
+ * two dozen small ones.
+ *
+ * ONE, AND RUNNING MORE BUYS NOTHING. The transport coalesces calls made in the
+ * same tick into one post, so four chunks at a quarter of the budget each arrive
+ * as ONE post of the same total size as a single full-budget chunk — the same
+ * bytes, in the same round trip, at four times the call count. The proxy's
+ * budget counts CALLS, not posts and not bytes, so the wider setting spent four
+ * times the rate limit for identical throughput.
+ *
+ * Measured on one token-picker open, 2026-09-12: at a concurrency of four the
+ * peak was eleven calls of one method in a second against a ceiling of eight,
+ * and one post was refused; at one the peak was seven and every post was
+ * answered. Request bytes fell from 737,057 to 638,890 in the same comparison,
+ * because nothing had to be resent to a fallback endpoint.
+ */
+const CHUNK_CONCURRENCY = 1;
+/**
+ * How much encoded call data one `aggregate3` may carry.
+ *
+ * Divided by the concurrency rather than set directly, because the transport
+ * COALESCES calls made in the same tick into one HTTP body. Chunking to a
+ * quarter-megabyte budget and running four at a time was measured arriving as a
+ * single 1.37 MB request — the split was real, and then undone at the layer
+ * below. What the node sees is this budget multiplied by the concurrency, so
+ * that is the relationship worth writing down; changing either constant alone
+ * cannot silently blow the target.
+ *
+ * STILL TRUE AT A CONCURRENCY OF ONE, and that is why the division stays rather
+ * than being folded away: raising the concurrency again without cutting this
+ * budget would put the target back over the endpoint's limit, and the division
+ * is what stops that being silent.
+ */
+const CALLDATA_BUDGET_BYTES = Math.floor(HTTP_BODY_TARGET_BYTES / CHUNK_CONCURRENCY);
+/**
+ * Bytes of request body a single call costs beyond its own encoded data.
+ * MEASURED against a real `aggregate3` encoding, not estimated.
+ *
+ * `aggregate3` spends five thirty-two byte words per call — the head offset, the
+ * target, the failure flag, the data offset and the data length — which is 320
+ * hexadecimal characters, plus up to 63 more padding the call data out to a word
+ * boundary. A `balanceOf` whose own call data is 74 characters was measured
+ * costing 448.6 bytes of body, so the real overhead is about 375 and the old
+ * value of 200 UNDERSTATED IT BY NEARLY A HALF.
+ *
+ * That is how a chunk budgeted at 128 kibibytes went out as a 214 kilobyte body.
+ * Four hundred keeps a small margin over the measurement.
+ */
+const PER_CALL_OVERHEAD_BYTES = 400;
+/** The size limits, exported so tests assert against the real values. */
+exports.multicallLimits = {
+    endpointBodyLimitBytes: ENDPOINT_BODY_LIMIT_BYTES,
+    httpBodyTargetBytes: HTTP_BODY_TARGET_BYTES,
+    callDataBudgetBytes: CALLDATA_BUDGET_BYTES,
+    chunkConcurrency: CHUNK_CONCURRENCY,
+    perCallOverheadBytes: PER_CALL_OVERHEAD_BYTES,
+};
+/**
+ * Splits encoded calls into groups whose combined request body stays under
+ * {@link CALLDATA_BUDGET_BYTES}.
+ *
+ * Grouped by measured size rather than by a fixed count on purpose: callers
+ * differ by more than an order of magnitude in how large one call encodes to — a
+ * bare `balanceOf` against a router quote carrying a swap path — so any single
+ * call limit would be far too cautious for one caller and useless for another.
+ *
+ * A call that exceeds the budget on its own still gets its own group; splitting
+ * it further is not possible, and refusing to send it would turn an oversized
+ * request into a missing result.
+ *
+ * @param encoded - the calls to group, in order
+ * @returns groups preserving the original order
+ */
+const chunkBySize = (encoded) => {
+    const chunks = [];
+    let current = [];
+    let currentBytes = 0;
+    for (const call of encoded) {
+        const bytes = call.callData.length + PER_CALL_OVERHEAD_BYTES;
+        if (current.length > 0 && currentBytes + bytes > CALLDATA_BUDGET_BYTES) {
+            chunks.push(current);
+            current = [];
+            currentBytes = 0;
+        }
+        current.push(call);
+        currentBytes += bytes;
+    }
+    if (current.length > 0)
+        chunks.push(current);
+    return chunks;
+};
+exports.chunkBySize = chunkBySize;
+/**
+ * Runs `task` over every item with at most `concurrency` in flight, preserving
+ * input order in the result.
+ *
+ * @param items - the work items
+ * @param concurrency - how many may run at once
+ * @param task - what to do with one item
+ */
+const mapWithConcurrency = async (items, concurrency, task) => {
+    const results = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const index = next;
+            next += 1;
+            results[index] = await task(items[index]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, worker));
+    return results;
+};
+/**
+ * Reads many contract calls through Multicall3, splitting the work across as
+ * many requests as the size budget needs and reassembling the results in order.
+ *
+ * Chunking is invisible to callers: the returned array lines up with `calls`
+ * one-for-one exactly as it did when every call went out together, and a chunk
+ * that rejects still rejects the whole read rather than returning a short array
+ * that a caller would silently misread as "these tokens have no balance".
+ *
+ * @param options.chain - the chain, used for its Multicall3 deployment
+ * @param options.client - the public client to read through
+ * @param options.abi - the default ABI, when a call does not carry its own
+ * @param options.calls - the calls to make, in the order results are wanted
+ * @param options.target - the default contract, when a call does not name one
+ */
+const multicallRead = async ({ chain, client, abi, calls, target, }) => {
+    const multicall = (0, viem_1.getContract)({
+        abi: viem_1.multicall3Abi,
+        address: chain.contracts.multicall3.address,
+        // this seems like a bug in viem, it should be able to infer the type of the client
+        client: client,
+    });
+    const arg = calls.map((call) => ({
+        callData: (0, viem_1.encodeFunctionData)({
+            abi: call.abi || abi,
+            functionName: call.functionName,
+            // this seems like a bug in viem, it should be able to infer the type of the args
+            args: (call.args || []),
+        }),
+        allowFailure: call.allowFailure || false,
+        target: (call.target || target),
+    }));
+    try {
+        const chunks = (0, exports.chunkBySize)(arg);
+        const chunkResults = await mapWithConcurrency(chunks, CHUNK_CONCURRENCY, async (chunk) => (0, assert_js_1.ensureResult)(await multicall.read.aggregate3([chunk]), 'Multicall aggregate3'));
+        const r = chunkResults.flat();
+        return calls.map((call, i) => call.allowFailure
+            ? r[i].success
+                ? (0, viem_1.decodeFunctionResult)({
+                    abi: call.abi || abi,
+                    functionName: call.functionName,
+                    data: r[i].returnData,
+                })
+                : r[i].returnData
+            : (0, viem_1.decodeFunctionResult)({
+                abi: call.abi || abi,
+                functionName: call.functionName,
+                data: r[i].returnData,
+            }));
+    }
+    catch (err) {
+        // Deliberately a summary rather than the calls themselves: a failing read can
+        // hold tens of thousands of them, and dumping the array cost more than the
+        // failure did.
+        console.error('Multicall aggregate3 failed', {
+            chainId: client.chain?.id,
+            target,
+            callCount: calls.length,
+            functionNames: [...new Set(calls.map((call) => call.functionName))],
+        });
+        throw err;
+    }
+};
+exports.multicallRead = multicallRead;

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/cjs/rpcPacer.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Holds outgoing JSON-RPC requests back so no method crosses the endpoint's
+ * per-second ceiling.
+ *
+ * WHY BATCH SIZE WAS NOT ENOUGH, WHICH IS THE WHOLE POINT OF THIS FILE. The
+ * transport already caps a single post at the ceiling, and that stops one post
+ * being refused for being too big. It says nothing about how many posts leave
+ * per second. Measured on one page load: nine `eth_call` inside a single rolling
+ * second, spread across four posts of which none was individually too large, and
+ * the fourth came back `429`.
+ *
+ * A ROLLING WINDOW, NOT A BUCKET. The first measurement of this counted calls
+ * into whole seconds aligned to the page load and reported nothing over the
+ * ceiling while a refusal sat in the same run — six calls at 1.9 seconds and
+ * seven at 2.1 fall in different buckets and land 200 milliseconds apart. A rate
+ * limiter does not know when our page started, so neither does this.
+ *
+ * ONE LIMITER FOR THE WHOLE APPLICATION, not one per client — but keyed on the
+ * HOST as well as the method.
+ *
+ * The budget is the host's, and it is shared across chains: six
+ * `eth_blockNumber` on PulseChain plus six on Ethereum were answered exactly
+ * eight times, the same as twelve on one chain. So a limiter per client would
+ * let two chains spend one budget twice and neither would know.
+ *
+ * But two DIFFERENT hosts have two different budgets, and counting them
+ * together would throttle a spare endpoint for traffic it never received —
+ * which is exactly backwards once requests are spread across hosts on purpose.
+ */
+/**
+ * The most calls of ONE method the proxy answers in one second. MEASURED.
+ *
+ * `one.valve.city` refuses past this with HTTP 429 and the body
+ * `Rate limit exceeded (per method, per second)`. Probed 2026-09-12 at
+ * concurrency 1, 2, 3, 4, 6, 8, 12, 16 and 24: every request up to eight was
+ * answered and everything past eight was refused, with no variance across
+ * twenty rounds. The budget is shared across CHAINS — six calls on chain 369
+ * plus six on chain 1 were answered exactly eight times, the same as twelve on
+ * one chain — so it is keyed on the method, not the chain.
+ *
+ * A BATCH THAT CROSSES THE CEILING IS REFUSED WHOLE, which is why this bounds
+ * the batch size. One post carrying sixteen `eth_blockNumber` calls came back
+ * with all sixteen refused; the same sixteen sent as separate posts had eight
+ * answered. Coalescing past the ceiling therefore converts a partial refusal
+ * into a total one, and viem's default of thirty-two calls per post is four
+ * times over it.
+ */
+export declare const MAX_SAME_METHOD_CALLS_PER_SECOND = 8;
+/** How the pacer reads the clock and waits, so a test can supply its own. */
+export interface PacerClock {
+    /** Milliseconds, monotonic enough for a one-second window. */
+    now: () => number;
+    /** Resolves after roughly `ms`. */
+    sleep: (ms: number) => Promise<void>;
+}
+/** A paced sender. */
+export interface RpcPacer {
+    /**
+     * Waits until `counts` can be spent without crossing the ceiling, then
+     * records them as spent.
+     *
+     * @param counts - how many calls of each method this request carries.
+     */
+    reserve: (host: string, counts: ReadonlyMap<string, number>) => Promise<void>;
+    /** How many calls of a method are inside the window for a host. Testing aid. */
+    spent: (host: string, method: string) => number;
+}
+/**
+ * Builds a pacer.
+ *
+ * @param options - the ceiling, and optionally a clock to drive it.
+ * @returns a pacer.
+ */
+export declare const createRpcPacer: ({ ceiling, clock, }: {
+    ceiling: number;
+    clock?: PacerClock;
+}) => RpcPacer;
+/**
+ * Counts the calls per method in a JSON-RPC body.
+ *
+ * A batch is an ARRAY and a single call is an object; both arrive here, and a
+ * body that cannot be read at all counts as nothing rather than throwing —
+ * pacing is an optimisation and must never be the reason a request fails.
+ *
+ * @param body - the request body, as text.
+ * @returns method to how many calls of it the body carries.
+ */
+export declare const countMethods: (body: string | null | undefined) => Map<string, number>;

package/dist/cjs/rpcPacer.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.countMethods = exports.createRpcPacer = exports.MAX_SAME_METHOD_CALLS_PER_SECOND = void 0;
+/**
+ * Holds outgoing JSON-RPC requests back so no method crosses the endpoint's
+ * per-second ceiling.
+ *
+ * WHY BATCH SIZE WAS NOT ENOUGH, WHICH IS THE WHOLE POINT OF THIS FILE. The
+ * transport already caps a single post at the ceiling, and that stops one post
+ * being refused for being too big. It says nothing about how many posts leave
+ * per second. Measured on one page load: nine `eth_call` inside a single rolling
+ * second, spread across four posts of which none was individually too large, and
+ * the fourth came back `429`.
+ *
+ * A ROLLING WINDOW, NOT A BUCKET. The first measurement of this counted calls
+ * into whole seconds aligned to the page load and reported nothing over the
+ * ceiling while a refusal sat in the same run — six calls at 1.9 seconds and
+ * seven at 2.1 fall in different buckets and land 200 milliseconds apart. A rate
+ * limiter does not know when our page started, so neither does this.
+ *
+ * ONE LIMITER FOR THE WHOLE APPLICATION, not one per client — but keyed on the
+ * HOST as well as the method.
+ *
+ * The budget is the host's, and it is shared across chains: six
+ * `eth_blockNumber` on PulseChain plus six on Ethereum were answered exactly
+ * eight times, the same as twelve on one chain. So a limiter per client would
+ * let two chains spend one budget twice and neither would know.
+ *
+ * But two DIFFERENT hosts have two different budgets, and counting them
+ * together would throttle a spare endpoint for traffic it never received —
+ * which is exactly backwards once requests are spread across hosts on purpose.
+ */
+/**
+ * The most calls of ONE method the proxy answers in one second. MEASURED.
+ *
+ * `one.valve.city` refuses past this with HTTP 429 and the body
+ * `Rate limit exceeded (per method, per second)`. Probed 2026-09-12 at
+ * concurrency 1, 2, 3, 4, 6, 8, 12, 16 and 24: every request up to eight was
+ * answered and everything past eight was refused, with no variance across
+ * twenty rounds. The budget is shared across CHAINS — six calls on chain 369
+ * plus six on chain 1 were answered exactly eight times, the same as twelve on
+ * one chain — so it is keyed on the method, not the chain.
+ *
+ * A BATCH THAT CROSSES THE CEILING IS REFUSED WHOLE, which is why this bounds
+ * the batch size. One post carrying sixteen `eth_blockNumber` calls came back
+ * with all sixteen refused; the same sixteen sent as separate posts had eight
+ * answered. Coalescing past the ceiling therefore converts a partial refusal
+ * into a total one, and viem's default of thirty-two calls per post is four
+ * times over it.
+ */
+exports.MAX_SAME_METHOD_CALLS_PER_SECOND = 8;
+const systemClock = {
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
+/** The window the ceiling is counted over. */
+const WINDOW_MS = 1_000;
+/**
+ * Builds a pacer.
+ *
+ * @param options - the ceiling, and optionally a clock to drive it.
+ * @returns a pacer.
+ */
+const createRpcPacer = ({ ceiling, clock = systemClock, }) => {
+    /** When each still-counting call was sent, per host-and-method, oldest first. */
+    const sent = new Map();
+    /**
+     * Reservations run ONE AT A TIME, chained. Two callers checking the window
+     * concurrently both see room and both take it — the classic check-then-act
+     * race, and the reason a limiter that looks right can still emit bursts. The
+     * chain makes "is there room" and "take it" a single step.
+     */
+    let queue = Promise.resolve();
+    const forget = (method, now) => {
+        const times = sent.get(method);
+        if (!times)
+            return [];
+        // Times are appended in order, so everything expired is a prefix.
+        let keep = 0;
+        while (keep < times.length && now - times[keep] >= WINDOW_MS)
+            keep += 1;
+        const live = keep === 0 ? times : times.slice(keep);
+        sent.set(method, live);
+        return live;
+    };
+    const reserveOne = async (key, count) => {
+        // A request carrying MORE than the ceiling of one method cannot ever fit,
+        // and waiting for room that will never exist would hang the page forever.
+        // The transport caps a post at the ceiling, so this is a guard against a
+        // caller that bypassed it rather than an expected path: spend what there is
+        // and let the endpoint answer for the rest.
+        const want = Math.min(count, ceiling);
+        for (;;) {
+            const now = clock.now();
+            const live = forget(key, now);
+            if (live.length + want <= ceiling) {
+                for (let i = 0; i < count; i += 1)
+                    live.push(now);
+                sent.set(key, live);
+                return;
+            }
+            // Wait exactly until the oldest call leaves the window — not a fixed
+            // retry interval, which would either spin or overshoot. The `+ 1` is so
+            // the comparison above is past the boundary rather than on it.
+            const oldest = live[0];
+            await clock.sleep(Math.max(1, oldest + WINDOW_MS - now + 1));
+        }
+    };
+    return {
+        reserve: (host, counts) => {
+            const run = queue.then(async () => {
+                // Ordered so the same body always reserves its methods in the same
+                // sequence; two bodies reserving the same pair in opposite orders is
+                // how a queue deadlocks itself.
+                for (const method of [...counts.keys()].sort()) {
+                    await reserveOne(`${host}|${method}`, counts.get(method) ?? 0);
+                }
+            });
+            // The queue must continue even when a reservation throws, or one failure
+            // stops every later request on the page.
+            queue = run.catch(() => undefined);
+            return run;
+        },
+        spent: (host, method) => forget(`${host}|${method}`, clock.now()).length,
+    };
+};
+exports.createRpcPacer = createRpcPacer;
+/**
+ * Counts the calls per method in a JSON-RPC body.
+ *
+ * A batch is an ARRAY and a single call is an object; both arrive here, and a
+ * body that cannot be read at all counts as nothing rather than throwing —
+ * pacing is an optimisation and must never be the reason a request fails.
+ *
+ * @param body - the request body, as text.
+ * @returns method to how many calls of it the body carries.
+ */
+const countMethods = (body) => {
+    const counts = new Map();
+    if (!body)
+        return counts;
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return counts;
+    }
+    const entries = Array.isArray(parsed) ? parsed : [parsed];
+    for (const entry of entries) {
+        const method = entry?.method;
+        if (typeof method !== 'string')
+            continue;
+        counts.set(method, (counts.get(method) ?? 0) + 1);
+    }
+    return counts;
+};
+exports.countMethods = countMethods;

package/dist/cjs/serialize.d.ts

@@ -0,0 +1,19 @@
+declare const BIGINT_TYPE: "bigint";
+type SerializedBigInt = {
+    __type__: typeof BIGINT_TYPE;
+    value: string;
+};
+/** The json any stringify for the given key and value */
+export declare const jsonAnyStringify: (_key: string, value: unknown) => unknown;
+/** The is serialized big int for the given value */
+export declare const isSerializedBigInt: (value: unknown) => value is SerializedBigInt;
+/**
+ * The json any parse for the given key and value.
+ *
+ * Throws on a corrupt encoded value rather than returning a number for it. Every
+ * caller reads from local storage inside a try/catch and falls back to a
+ * default, so a throw discards one unusable record; a silent zero would survive
+ * into the arithmetic.
+ */
+export declare const jsonAnyParse: (_key: string, value: unknown) => unknown;
+export {};

package/dist/cjs/serialize.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jsonAnyParse = exports.isSerializedBigInt = exports.jsonAnyStringify = void 0;
+const BIGINT_TYPE = 'bigint';
+/** The json any stringify for the given key and value */
+const jsonAnyStringify = (_key, value) => {
+    if (typeof value === BIGINT_TYPE) {
+        return {
+            __type__: BIGINT_TYPE,
+            value: value.toString(),
+        };
+    }
+    return value;
+};
+exports.jsonAnyStringify = jsonAnyStringify;
+/** The is serialized big int for the given value */
+const isSerializedBigInt = (value) => {
+    return (!!value && typeof value === 'object' && value.__type__ === BIGINT_TYPE);
+};
+exports.isSerializedBigInt = isSerializedBigInt;
+/**
+ * The only strings `jsonAnyStringify` ever writes: what `bigint.toString()`
+ * produces, which is an optional minus sign followed by decimal digits.
+ *
+ * Anything else in the `value` field means the record is corrupt, and `BigInt`
+ * is too permissive to notice. `BigInt('')` is 0n and `BigInt('0x10')` is 16n,
+ * so a truncated or garbled record parses into a plausible-looking balance
+ * instead of an error — and a wrong balance is spent, displayed and believed.
+ */
+const DECIMAL_BIG_INT = /^-?\d+$/;
+/**
+ * The json any parse for the given key and value.
+ *
+ * Throws on a corrupt encoded value rather than returning a number for it. Every
+ * caller reads from local storage inside a try/catch and falls back to a
+ * default, so a throw discards one unusable record; a silent zero would survive
+ * into the arithmetic.
+ */
+const jsonAnyParse = (_key, value) => {
+    if ((0, exports.isSerializedBigInt)(value)) {
+        if (typeof value.value !== 'string' || !DECIMAL_BIG_INT.test(value.value)) {
+            throw new TypeError(`corrupt stored big integer: ${JSON.stringify(value.value)} is not a decimal integer`);
+        }
+        return BigInt(value.value);
+    }
+    return value;
+};
+exports.jsonAnyParse = jsonAnyParse;

package/dist/cjs/types.d.ts

@@ -0,0 +1,11 @@
+import type { Abi, Hex } from 'viem';
+/** The inputs for a multicall read */
+export type Call = {
+    allowFailure?: boolean;
+    functionName: string;
+    target?: Hex;
+    abi?: Abi;
+    args?: (bigint | Hex | Hex[] | bigint[] | string | string[])[];
+};
+/** The erc20 metadata */
+export type Erc20Metadata = [string, string, number];

package/dist/cjs/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });