@gibs/common 1.10.1 → 1.13.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Gibs Finance
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/dist/assert.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Asserts that a value is defined (not null, undefined, or falsy)
+ * Throws a descriptive error if the value is falsy
+ *
+ * @param value - The value to check
+ * @param context - Context description for the error message
+ * @returns The value if defined
+ * @throws Error if value is falsy
+ */
+export declare function ensureResult<T>(value: T | null | undefined | false | 0, context: string): T;
+/**
+ * Type guard that asserts a value is defined
+ * Similar to ensureResult but uses TypeScript's asserts syntax
+ *
+ * @param value - The value to check
+ * @param message - Error message if assertion fails
+ */
+export declare function assertDefined<T>(value: T | null | undefined, message: string): asserts value is T;

package/dist/assert.js

@@ -0,0 +1,27 @@
+/**
+ * Asserts that a value is defined (not null, undefined, or falsy)
+ * Throws a descriptive error if the value is falsy
+ *
+ * @param value - The value to check
+ * @param context - Context description for the error message
+ * @returns The value if defined
+ * @throws Error if value is falsy
+ */
+export function ensureResult(value, context) {
+    if (!value) {
+        throw new Error(`${context}: Expected result but got ${value}`);
+    }
+    return value;
+}
+/**
+ * Type guard that asserts a value is defined
+ * Similar to ensureResult but uses TypeScript's asserts syntax
+ *
+ * @param value - The value to check
+ * @param message - Error message if assertion fails
+ */
+export function assertDefined(value, message) {
+    if (value === null || value === undefined) {
+        throw new Error(message);
+    }
+}

package/dist/{src/cache.js → cache.js}

@@ -1,4 +1,4 @@
-import { jsonAnyStringify } from "./serialize.js";
+import { jsonAnyStringify } from './serialize.js';
 /**
  * Memoize a function result and return a single value
  * @param fn the function to memoize

package/dist/client.d.ts

@@ -0,0 +1,48 @@
+import { type Chain, type HttpTransportConfig, type PublicClient } from 'viem';
+export { MAX_SAME_METHOD_CALLS_PER_SECOND } from './rpcPacer.js';
+/**
+ * JSON-RPC request batching config. When enabled, viem coalesces requests made
+ * within `wait` milliseconds (up to `batchSize`) into ONE HTTP POST carrying a
+ * JSON-RPC array body. This is the default because it sharply cuts request
+ * volume on nodes that support it.
+ *
+ * Note: some public nodes (notably some Binance Smart Chain endpoints) reject the
+ * array-wrapped body — even for a single request — which makes every call fail
+ * and get retried, BURNING through requests. Such chains must construct their
+ * client with `batch: false` (see {@link clientFromChain}'s `batch` option) so
+ * requests are sent as plain JSON-RPC objects the node accepts.
+ */
+export declare const defaultRpcBatch: {
+    readonly wait: 10;
+    readonly batchSize: 32;
+};
+/** The default batch config for the client */
+export declare const defaultBatchConfig: {
+    batch: {
+        readonly wait: 10;
+        readonly batchSize: 32;
+    };
+};
+/**
+ * Returns the chain key for the given chain id and urls
+ * @param chainId - the chain id
+ * @param urls - the urls
+ * @returns the chain key
+ */
+export declare const chainKey: (chainId: number, urls: string[]) => string;
+/** The client cache for the given chain id */
+export declare const clientCache: Map<number, {
+    key: string;
+    client: PublicClient;
+}>;
+export declare const clientFromChain: ({ chain, urls, batch, }: {
+    chain: Chain;
+    urls: string[];
+    /**
+     * JSON-RPC request batching for this client's transport. Defaults to
+     * {@link defaultRpcBatch}. Pass `false` for chains whose RPC nodes reject the
+     * array-wrapped batch body (some Binance Smart Chain endpoints), so requests
+     * are sent as plain JSON-RPC objects and are not failed-and-retried.
+     */
+    batch?: HttpTransportConfig["batch"];
+}) => PublicClient;

package/dist/client.js

@@ -0,0 +1,164 @@
+import { createPublicClient, createTransport, http, webSocket, } from 'viem';
+import { countMethods, createRpcPacer, MAX_SAME_METHOD_CALLS_PER_SECOND, } from './rpcPacer.js';
+export { MAX_SAME_METHOD_CALLS_PER_SECOND } from './rpcPacer.js';
+/**
+ * JSON-RPC request batching config. When enabled, viem coalesces requests made
+ * within `wait` milliseconds (up to `batchSize`) into ONE HTTP POST carrying a
+ * JSON-RPC array body. This is the default because it sharply cuts request
+ * volume on nodes that support it.
+ *
+ * Note: some public nodes (notably some Binance Smart Chain endpoints) reject the
+ * array-wrapped body — even for a single request — which makes every call fail
+ * and get retried, BURNING through requests. Such chains must construct their
+ * client with `batch: false` (see {@link clientFromChain}'s `batch` option) so
+ * requests are sent as plain JSON-RPC objects the node accepts.
+ */
+export const defaultRpcBatch = {
+    wait: 10,
+    batchSize: 32,
+};
+/** The default batch config for the client */
+export const defaultBatchConfig = {
+    batch: defaultRpcBatch,
+};
+/**
+ * Returns the chain key for the given chain id and urls
+ * @param chainId - the chain id
+ * @param urls - the urls
+ * @returns the chain key
+ */
+export const chainKey = (chainId, urls) => {
+    return `${chainId},${urls.join(',')}`.toLowerCase();
+};
+/** The client cache for the given chain id */
+export const clientCache = new Map();
+/**
+ * Returns the client for the given chain and urls
+ * @param chain - the chain
+ * @param urls - the urls
+ * @returns the client
+ */
+/**
+ * The one pacer for the whole application.
+ *
+ * MODULE LEVEL, DELIBERATELY. The endpoint keys its budget on the METHOD, not
+ * the chain — six `eth_blockNumber` on PulseChain plus six on Ethereum were
+ * answered exactly eight times, the same as twelve on one chain. A pacer per
+ * client would let two chains spend one budget twice and neither would know it
+ * had.
+ *
+ * It is built with the same ceiling the batch size uses, so the two can never
+ * describe different limits.
+ */
+const pacer = createRpcPacer({ ceiling: MAX_SAME_METHOD_CALLS_PER_SECOND });
+/**
+ * Holds a request until its methods fit under the ceiling.
+ *
+ * WIRED HERE RATHER THAN AROUND THE CALLERS because this is the only place that
+ * sees the FINAL body: viem coalesces separate reads into one post, so a limiter
+ * upstream of the transport would count intentions and this counts what is
+ * actually sent.
+ *
+ * Returning nothing leaves the request untouched — the hook exists to delay, not
+ * to rewrite.
+ */
+const paceRequest = async (request) => {
+    // The HOST, not the full url: one proxy serves every chain from one budget,
+    // so `/evm/1` and `/evm/369` must count against the same tally.
+    const host = new URL(request.url).host;
+    await pacer.reserve(host, countMethods(await request.clone().text().catch(() => null)));
+};
+/**
+ * Spreads requests across a chain's endpoints instead of resting on the first.
+ *
+ * WHAT `fallback` ACTUALLY DOES, and why it is not this. With `rank: false` it
+ * sends every request to entry zero and moves on only when that entry ERRORS. So
+ * the spares behind a chain carry no load at all: on Ethereum, `valve.city` took
+ * one hundred percent of every read while two perfectly good nodes sat idle, and
+ * the only way traffic ever reached them was a refusal — a wasted round trip
+ * spent discovering a spare we could have used on purpose.
+ *
+ * That matters because the first entry is a SHARED proxy. Its key is published
+ * on chainlist.org, so its per-second budget is not ours alone: measured at a
+ * refusal, our own calls in the preceding second were seven against a ceiling of
+ * eight. We were not over the limit. Somebody else was using the rest of it, and
+ * no amount of pacing on our side fixes that — only using less of that host
+ * does.
+ *
+ * ROUND ROBIN, AND FALLBACK STILL INTACT. Each request starts at the next
+ * endpoint in rotation and walks the rest on failure, so a dead host costs one
+ * attempt exactly as it did before while a healthy one now carries its share.
+ *
+ * NOT `rank: true`, which is viem's own answer to this and is the wrong one
+ * here: ranking pings EVERY url on EVERY chain every few seconds forever, which
+ * on an idle page was once the entire outbound traffic and is what spent the
+ * shared budget in the first place. It also reorders a list this project curates
+ * deliberately.
+ */
+const balanced = (transports) => {
+    if (transports.length === 1)
+        return transports[0];
+    return (config) => {
+        const instances = transports.map((transport) => transport(config));
+        // Module-level rotation per client, not per call site: every reader on the
+        // page shares one cursor, which is what makes the split even rather than
+        // each caller starting at zero and piling onto the same host.
+        let cursor = 0;
+        return createTransport({
+            key: 'balanced',
+            name: 'Balanced',
+            type: 'balanced',
+            // CAST AT THE BOUNDARY, deliberately. `EIP1193RequestFn` is generic over
+            // the method being called and resolves its own return type; a rotation
+            // cannot preserve that relationship because it does not know which
+            // transport will answer until it has tried one. The delegates below are
+            // fully typed and the shape passing through is unchanged — only the
+            // compiler's ability to follow it across the loop is lost.
+            request: (async (args) => {
+                const start = cursor;
+                cursor = (cursor + 1) % instances.length;
+                let lastError;
+                for (let offset = 0; offset < instances.length; offset += 1) {
+                    try {
+                        return await instances[(start + offset) % instances.length].request(args);
+                    }
+                    catch (error) {
+                        // KEPT AND RETHROWN AT THE END, not swallowed. If every endpoint
+                        // refuses, the caller must see a real error — a rotation that
+                        // returns undefined when all its hosts are down turns an outage
+                        // into a silently empty read.
+                        lastError = error;
+                    }
+                }
+                throw lastError;
+            }),
+        });
+    };
+};
+export const clientFromChain = ({ chain, urls, batch = defaultRpcBatch, }) => {
+    const key = chainKey(chain.id, urls);
+    const existing = clientCache.get(chain.id);
+    if (existing && existing.key === key) {
+        return existing.client;
+    }
+    const transport = !urls?.length
+        ? http()
+        : balanced(urls.map((rpc) => rpc.startsWith('http')
+            ? http(rpc, { batch, onFetchRequest: paceRequest })
+            : webSocket(rpc, {
+                keepAlive: true,
+                reconnect: true,
+                retryDelay: 250,
+                retryCount: 10,
+                timeout: 4_000,
+            })));
+    const client = createPublicClient({
+        chain,
+        transport,
+    });
+    clientCache.set(chain.id, {
+        key,
+        client,
+    });
+    return client;
+};

package/dist/erc20.d.ts

@@ -0,0 +1,20 @@
+import { type Chain, type Hex, type PublicClient } from 'viem';
+import type { Erc20Metadata } from './types.js';
+/** The erc20 metadata calls */
+export declare const erc20MetadataCalls: {
+    functionName: string;
+}[];
+/**
+ * The multicall for the erc20 metadata.
+ *
+ * The explicit annotation is required rather than stylistic: `@types/lodash-es`
+ * re-exports its `MemoizedFunction` type from a nested `@types/lodash` that a
+ * generated declaration file cannot name (TS2742). Spelling out the plain call
+ * signature also keeps the memoization an implementation detail — no caller
+ * touches the `.cache` property it would otherwise publish.
+ */
+export declare const multicallErc20: (inputs: {
+    client: PublicClient;
+    target: Hex;
+    chain: Chain;
+}) => Promise<Erc20Metadata>;

package/dist/{src/erc20.js → erc20.js}

@@ -1,5 +1,5 @@
+import * as _ from 'lodash-es';
 import { erc20Abi, erc20Abi_bytes32, getAddress, } from 'viem';
-import _ from 'lodash';
 import { multicallRead } from './multicall.js';
 /** The erc20 metadata calls */
 export const erc20MetadataCalls = [
@@ -7,7 +7,15 @@ export const erc20MetadataCalls = [
     { functionName: 'symbol' },
     { functionName: 'decimals' },
 ];
-/** The multicall for the erc20 metadata */
+/**
+ * The multicall for the erc20 metadata.
+ *
+ * The explicit annotation is required rather than stylistic: `@types/lodash-es`
+ * re-exports its `MemoizedFunction` type from a nested `@types/lodash` that a
+ * generated declaration file cannot name (TS2742). Spelling out the plain call
+ * signature also keeps the memoization an implementation detail — no caller
+ * touches the `.cache` property it would otherwise publish.
+ */
 export const multicallErc20 = _.memoize(async ({ client, target, chain }) => {
     const options = {
         chain: chain,

package/dist/{src/index.d.ts → index.d.ts}

@@ -1,6 +1,7 @@
-export * from './types.js';
-export * from './serialize.js';
+export * from './assert.js';
 export * from './cache.js';
-export * from './multicall.js';
-export * from './erc20.js';
 export * from './client.js';
+export * from './erc20.js';
+export * from './multicall.js';
+export * from './serialize.js';
+export * from './types.js';

package/dist/{src/index.js → index.js}

@@ -1,6 +1,7 @@
-export * from './types.js';
-export * from './serialize.js';
+export * from './assert.js';
 export * from './cache.js';
-export * from './multicall.js';
-export * from './erc20.js';
 export * from './client.js';
+export * from './erc20.js';
+export * from './multicall.js';
+export * from './serialize.js';
+export * from './types.js';

package/dist/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/multicall.js

@@ -0,0 +1,213 @@
+import * as _ from 'lodash-es';
+import { decodeFunctionResult, encodeFunctionData, getContract, multicall3Abi, } from 'viem';
+import { ensureResult } from './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. */
+export const 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
+ */
+export 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;
+};
+/**
+ * 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
+ */
+export const multicallRead = async ({ chain, client, abi, calls, target, }) => {
+    const multicall = getContract({
+        abi: 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: 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 = chunkBySize(arg);
+        const chunkResults = await mapWithConcurrency(chunks, CHUNK_CONCURRENCY, async (chunk) => ensureResult(await multicall.read.aggregate3([chunk]), 'Multicall aggregate3'));
+        const r = chunkResults.flat();
+        return calls.map((call, i) => call.allowFailure
+            ? r[i].success
+                ? decodeFunctionResult({
+                    abi: call.abi || abi,
+                    functionName: call.functionName,
+                    data: r[i].returnData,
+                })
+                : r[i].returnData
+            : 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: _.uniq(calls.map((call) => call.functionName)),
+        });
+        throw err;
+    }
+};