@gibs/common 1.10.1 → 1.13.0

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

@@ -0,0 +1,153 @@
+/**
+ * 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 const 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.
+ */
+export 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,
+    };
+};
+/**
+ * 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 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;
+};

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

@@ -4,9 +4,16 @@ type SerializedBigInt = {
     value: string;
 };
 /** The json any stringify for the given key and value */
-export declare const jsonAnyStringify: (key: string, value: unknown) => unknown;
+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 */
+/**
+ * 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/serialize.js

@@ -0,0 +1,42 @@
+const BIGINT_TYPE = 'bigint';
+/** The json any stringify for the given key and value */
+export const jsonAnyStringify = (_key, value) => {
+    if (typeof value === BIGINT_TYPE) {
+        return {
+            __type__: BIGINT_TYPE,
+            value: value.toString(),
+        };
+    }
+    return value;
+};
+/** The is serialized big int for the given value */
+export const isSerializedBigInt = (value) => {
+    return (!!value && typeof value === 'object' && value.__type__ === BIGINT_TYPE);
+};
+/**
+ * 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.
+ */
+export const jsonAnyParse = (_key, value) => {
+    if (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;
+};

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

@@ -1,4 +1,4 @@
-import type { Abi, Hex } from "viem";
+import type { Abi, Hex } from 'viem';
 /** The inputs for a multicall read */
 export type Call = {
     allowFailure?: boolean;

package/package.json

@@ -1,31 +1,101 @@
 {
   "name": "@gibs/common",
-  "version": "1.10.1",
-  "main": "index.js",
-  "access": "public",
+  "version": "1.13.0",
+  "description": "Low-level blockchain helpers shared across the Gibs Finance packages: caching, multicall, and serialization.",
+  "keywords": [
+    "ethereum",
+    "pulsechain",
+    "viem",
+    "multicall",
+    "cache"
+  ],
+  "license": "ISC",
+  "author": "Gibs Finance",
+  "homepage": "https://gibs.finance",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gibsfinance/bridge.git",
+    "directory": "packages/common"
+  },
+  "bugs": {
+    "url": "https://github.com/gibsfinance/bridge/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
   "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts",
-    "./erc20": "./src/erc20.ts",
-    "./cache": "./src/cache.ts",
-    "./serialize": "./src/serialize.ts",
-    "./types": "./src/types.ts",
-    "./multicall": "./src/multicall.ts",
-    "./client": "./src/client.ts"
+    ".": {
+      "gibs-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./erc20": {
+      "gibs-source": "./src/erc20.ts",
+      "types": "./dist/erc20.d.ts",
+      "default": "./dist/erc20.js"
+    },
+    "./cache": {
+      "gibs-source": "./src/cache.ts",
+      "types": "./dist/cache.d.ts",
+      "default": "./dist/cache.js"
+    },
+    "./serialize": {
+      "gibs-source": "./src/serialize.ts",
+      "types": "./dist/serialize.d.ts",
+      "default": "./dist/serialize.js"
+    },
+    "./types": {
+      "gibs-source": "./src/types.ts",
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
+    },
+    "./multicall": {
+      "gibs-source": "./src/multicall.ts",
+      "types": "./dist/multicall.d.ts",
+      "default": "./dist/multicall.js"
+    },
+    "./client": {
+      "gibs-source": "./src/client.ts",
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./test-utils/fuzz": {
+      "gibs-source": "./src/test-utils/fuzz.ts",
+      "default": "./src/test-utils/fuzz.ts"
+    }
   },
+  "files": [
+    "dist",
+    "!dist/tsconfig.tsbuildinfo",
+    "!dist/**/*.test-d.*",
+    "!dist/test-utils",
+    "LICENSE"
+  ],
   "scripts": {
-    "build": "npx tsc"
+    "prepublishOnly": "npx tsc",
+    "build": "npx tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "lodash-es": "^4.17.21"
+  },
+  "peerDependencies": {
+    "viem": ">=2.37.0 <3"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "description": "",
   "devDependencies": {
-    "@types/node": "^22.12.0",
-    "typescript": "~5.7.2"
+    "@types/node": "^24",
+    "@vitest/coverage-v8": "^3.1.1",
+    "typescript": "~5.7.2",
+    "viem": "^2.46.3",
+    "vitest": "^3.1.1"
   },
-  "dependencies": {
-    "lodash": "^4.17.21",
-    "viem": "^2.37.8"
+  "publishConfig": {
+    "access": "public"
   }
 }

package/dist/src/client.d.ts

@@ -1,30 +0,0 @@
-import { type Chain, type PublicClient } from "viem";
-/** The default batch config for the client */
-export declare const defaultBatchConfig: {
-    batch: {
-        wait: number;
-        batchSize: number;
-    };
-};
-/**
- * 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;
-}>;
-/**
- * Returns the client for the given chain and urls
- * @param chain - the chain
- * @param urls - the urls
- * @returns the client
- */
-export declare const clientFromChain: ({ chain, urls, }: {
-    chain: Chain;
-    urls: string[];
-}) => PublicClient;

package/dist/src/client.js

@@ -1,55 +0,0 @@
-import { createPublicClient, fallback, http, webSocket } from "viem";
-/** The default batch config for the client */
-export const defaultBatchConfig = {
-    batch: {
-        wait: 10,
-        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 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
- */
-export const clientFromChain = ({ chain, urls, }) => {
-    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()
-        : fallback(urls.map((rpc) => rpc.startsWith('http')
-            ? http(rpc, {
-                ...defaultBatchConfig,
-            })
-            : webSocket(rpc, {
-                keepAlive: true,
-                reconnect: true,
-                retryDelay: 250,
-                retryCount: 10,
-                timeout: 4_000,
-                ...defaultBatchConfig,
-            })), { rank: true });
-    const client = createPublicClient({
-        chain,
-        transport,
-    });
-    clientCache.set(chain.id, {
-        key,
-        client,
-    });
-    return client;
-};

package/dist/src/erc20.d.ts

@@ -1,13 +0,0 @@
-import { type Chain, type PublicClient, type Hex } from 'viem';
-import _ from 'lodash';
-import type { Erc20Metadata } from './types.js';
-/** The erc20 metadata calls */
-export declare const erc20MetadataCalls: {
-    functionName: string;
-}[];
-/** The multicall for the erc20 metadata */
-export declare const multicallErc20: (({ client, target, chain }: {
-    client: PublicClient;
-    target: Hex;
-    chain: Chain;
-}) => Promise<Erc20Metadata>) & _.MemoizedFunction;

package/dist/src/multicall.d.ts

@@ -1,10 +0,0 @@
-import { type Chain, type PublicClient, type Hex, type Abi } from 'viem';
-import type { Call } from './types.js';
-/** The multicall for the given chain, client, abi, calls, and target */
-export declare const multicallRead: <T>({ chain, client, abi, calls, target, }: {
-    chain: Chain;
-    client: PublicClient;
-    abi: Abi;
-    calls: Call[];
-    target?: Hex;
-}) => Promise<T>;

package/dist/src/multicall.js

@@ -1,44 +0,0 @@
-import { getContract, encodeFunctionData, decodeFunctionResult, multicall3Abi, } from 'viem';
-/** The multicall for the given chain, client, abi, calls, and target */
-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),
-    }));
-    let reads = null;
-    try {
-        reads = await multicall.read.aggregate3([arg]);
-        if (!reads)
-            throw reads;
-        const r = reads;
-        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) {
-        console.error(client.chain?.id, target, calls, reads);
-        throw err;
-    }
-};

package/dist/src/serialize.js

@@ -1,22 +0,0 @@
-const BIGINT_TYPE = 'bigint';
-/** The json any stringify for the given key and value */
-export const jsonAnyStringify = (key, value) => {
-    if (typeof value === BIGINT_TYPE) {
-        return {
-            __type__: BIGINT_TYPE,
-            value: value.toString(),
-        };
-    }
-    return value;
-};
-/** The is serialized big int for the given value */
-export const isSerializedBigInt = (value) => {
-    return (!!value && typeof value === 'object' && value.__type__ === BIGINT_TYPE);
-};
-/** The json any parse for the given key and value */
-export const jsonAnyParse = (_key, value) => {
-    if (isSerializedBigInt(value)) {
-        return BigInt(value.value);
-    }
-    return value;
-};