@gibs/common 1.12.0 → 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/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/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/{src/types.ts → dist/types.d.ts}

@@ -1,13 +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[])[];
+    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/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,36 +1,101 @@
 {
   "name": "@gibs/common",
-  "version": "1.12.0",
-  "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": {
+    "prepublishOnly": "npx tsc",
     "build": "npx tsc",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "description": "",
+  "dependencies": {
+    "lodash-es": "^4.17.21"
+  },
+  "peerDependencies": {
+    "viem": ">=2.37.0 <3"
+  },
   "devDependencies": {
     "@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.46.3"
+  "publishConfig": {
+    "access": "public"
   }
 }

package/src/assert.test.ts

@@ -1,141 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { assertDefined, ensureResult } from './assert';
-
-describe('assert', () => {
-  describe('ensureResult', () => {
-    it('should return value when truthy', () => {
-      expect(ensureResult('hello', 'test')).toBe('hello');
-      expect(ensureResult(123, 'test')).toBe(123);
-      expect(ensureResult(true, 'test')).toBe(true);
-      expect(ensureResult({ foo: 'bar' }, 'test')).toEqual({ foo: 'bar' });
-      expect(ensureResult([1, 2, 3], 'test')).toEqual([1, 2, 3]);
-    });
-
-    it('should throw Error when value is null', () => {
-      expect(() => ensureResult(null, 'TestContext')).toThrow(
-        'TestContext: Expected result but got null',
-      );
-    });
-
-    it('should throw Error when value is undefined', () => {
-      expect(() => ensureResult(undefined, 'TestContext')).toThrow(
-        'TestContext: Expected result but got undefined',
-      );
-    });
-
-    it('should throw Error when value is false', () => {
-      expect(() => ensureResult(false, 'TestContext')).toThrow(
-        'TestContext: Expected result but got false',
-      );
-    });
-
-    it('should throw Error when value is 0', () => {
-      expect(() => ensureResult(0, 'TestContext')).toThrow(
-        'TestContext: Expected result but got 0',
-      );
-    });
-
-    it('should include context in error message', () => {
-      expect(() => ensureResult(null, 'Multicall aggregate3')).toThrow(
-        'Multicall aggregate3: Expected result but got null',
-      );
-
-      expect(() => ensureResult(undefined, 'Database query')).toThrow(
-        'Database query: Expected result but got undefined',
-      );
-    });
-
-    it('should handle BigInt values', () => {
-      expect(ensureResult(123n, 'test')).toBe(123n);
-      // 0n is falsy just like 0, so it should throw
-      expect(() => ensureResult(0n, 'test')).toThrow('test: Expected result but got 0');
-    });
-
-    it('should handle empty string as falsy', () => {
-      expect(() => ensureResult('', 'TestContext')).toThrow(
-        'TestContext: Expected result but got ',
-      );
-    });
-
-    it('should handle empty array as truthy', () => {
-      expect(ensureResult([], 'test')).toEqual([]);
-    });
-
-    it('should throw Error, not the value itself', () => {
-      try {
-        ensureResult(null, 'test');
-        expect.fail('Should have thrown');
-      } catch (err) {
-        expect(err).toBeInstanceOf(Error);
-        expect(err).not.toBe(null);
-      }
-    });
-  });
-
-  describe('assertDefined', () => {
-    it('should not throw when value is defined', () => {
-      expect(() => assertDefined('hello', 'test')).not.toThrow();
-      expect(() => assertDefined(123, 'test')).not.toThrow();
-      expect(() => assertDefined(true, 'test')).not.toThrow();
-      expect(() => assertDefined(false, 'test')).not.toThrow();
-      expect(() => assertDefined(0, 'test')).not.toThrow();
-      expect(() => assertDefined({}, 'test')).not.toThrow();
-      expect(() => assertDefined([], 'test')).not.toThrow();
-    });
-
-    it('should throw when value is null', () => {
-      expect(() => assertDefined(null, 'Value cannot be null')).toThrow('Value cannot be null');
-    });
-
-    it('should throw when value is undefined', () => {
-      expect(() => assertDefined(undefined, 'Value cannot be undefined')).toThrow(
-        'Value cannot be undefined',
-      );
-    });
-
-    it('should not throw for falsy but defined values', () => {
-      expect(() => assertDefined(false, 'test')).not.toThrow();
-      expect(() => assertDefined(0, 'test')).not.toThrow();
-      expect(() => assertDefined('', 'test')).not.toThrow();
-      expect(() => assertDefined(0n, 'test')).not.toThrow();
-    });
-
-    it('should include message in error', () => {
-      expect(() => assertDefined(null, 'Custom error message')).toThrow('Custom error message');
-    });
-
-    it('should throw Error object', () => {
-      try {
-        assertDefined(null, 'test');
-        expect.fail('Should have thrown');
-      } catch (err) {
-        expect(err).toBeInstanceOf(Error);
-      }
-    });
-
-    it('should work with type narrowing', () => {
-      const value: string | null = 'hello';
-      assertDefined(value, 'test');
-      // TypeScript should now know value is string
-      const uppercased: string = value.toUpperCase();
-      expect(uppercased).toBe('HELLO');
-    });
-  });
-
-  describe('integration', () => {
-    it('should allow chaining ensureResult', () => {
-      const obj = { nested: { value: 42 } };
-      const result = ensureResult(ensureResult(obj, 'obj').nested, 'nested').value;
-      expect(result).toBe(42);
-    });
-
-    it('should provide clear error messages in real-world scenarios', async () => {
-      const mockApiCall = async (): Promise<any[] | null> => null;
-
-      await expect(async () => {
-        const result = await mockApiCall();
-        ensureResult(result, 'API call');
-      }).rejects.toThrow('API call: Expected result but got null');
-    });
-  });
-});