Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

fix(solana): split a JSON-RPC batch a lane caps instead of failing the whole call

nirholasad300c5446bd
diff --git a/api/_lib/solana/connection.js b/api/_lib/solana/connection.js
index cdcaf893a..a18dded81 100644
--- a/api/_lib/solana/connection.js
+++ b/api/_lib/solana/connection.js
@@ -1074,6 +1074,106 @@ export function throwDisposition({ callerAborted, attemptTimedOut, hasMethods })
return 'cool-lane';
}
+// ---------------------------------------------------------------------------
+// Per-lane JSON-RPC batch caps
+// ---------------------------------------------------------------------------
+// web3.js batches: getTransactions/getParsedTransactions send ONE JSON-RPC array
+// carrying N getTransaction calls, and getMultipleAccounts does the same for
+// account reads. Some free lanes cap how many calls of a shape they will serve
+// per batch and reject the whole array. Measured 2026-08-15 on
+// solana-rpc.publicnode.com: HTTP 400 + `{code:-32600,"Maximum number of
+// 'getTransaction' calls in a batch request is 1. To increase limits, get a
+// personal token here: https://www.allnodes.com/publicnode"}`.
+//
+// That answer is neither a lane fault nor a method refusal, and misreading it as
+// either loses data we can trivially fetch: the node is healthy, the credential
+// is fine, and it serves the very same call happily one at a time. A plain 400
+// also does not rotate (see shouldRotate: other 4xx are caller errors identical
+// on every lane), so left unclassified it surfaced raw and hard-failed the
+// caller — which is exactly how the pump.fun MCP `get_token_trades` tool died
+// with "400 Bad Request: Maximum number of 'getTransaction' calls in a batch
+// request is 1" on every attempt, while every other tool on the same lane worked.
+//
+// So the disposition is: re-send this batch to the SAME lane as single requests
+// and merge the envelopes back into the array the caller expects. The (lane,
+// method) pair is remembered for a while so the next batch skips the wasted
+// probe and goes straight to unbatched.
+const BATCH_LIMIT_REFUSAL =
+ /maximum number of .{0,64}(?:calls|requests) in a batch|batch (?:request )?(?:size|limit)[^.]{0,48}(?:exceed|too (?:large|big|many)|is \d+)|too many (?:calls|requests) in (?:a |one )?batch|batch too large/i;
+
+// How many single requests a split is allowed to become. A batch wider than this
+// costs more in round-trips than it is worth against a lane that caps at 1, so
+// the request rotates to a lane that takes the batch whole instead.
+const MAX_BATCH_SPLIT = 64;
+// Concurrent single requests during a split. Enough to keep a chunked read fast,
+// low enough that splitting one batch never looks like a burst to the lane that
+// just told us it wants them one at a time.
+const BATCH_SPLIT_CONCURRENCY = 4;
+const BATCH_CAP_TTL_MS = 30 * 60_000;
+
+/** @type {Map<string, number>} `${url}\0${method}` → expiry ms */
+const _batchCapped = new Map();
+
+/**
+ * True when `text` is a provider refusing a batch because of its OWN per-batch
+ * limit, rather than because the request is malformed. PURE, so the policy is
+ * unit-testable without a node.
+ *
+ * @param {string} text
+ */
+export function isBatchLimitRefusal(text) {
+ return BATCH_LIMIT_REFUSAL.test(String(text || ''));
+}
+
+/**
+ * The elements of a JSON-RPC batch body, or null when `body` is not a batch of
+ * more than one call. Splitting is only ever worth it for a real batch.
+ *
+ * @param {unknown} body
+ * @returns {object[]|null}
+ */
+export function batchElements(body) {
+ if (typeof body !== 'string') return null;
+ if (body.trimStart()[0] !== '[') return null;
+ try {
+ const parsed = JSON.parse(body);
+ if (!Array.isArray(parsed) || parsed.length < 2) return null;
+ return parsed.every((el) => el && typeof el === 'object') ? parsed : null;
+ } catch {
+ return null;
+ }
+}
+
+/** True when this lane is known to cap batches for every shape in `methods`. */
+function isBatchCapped(url, methods) {
+ if (!methods.length) return false;
+ const now = Date.now();
+ return methods.every((m) => {
+ const until = _batchCapped.get(methodKey(url, m)) || 0;
+ if (until && until <= now) {
+ _batchCapped.delete(methodKey(url, m));
+ return false;
+ }
+ return until > now;
+ });
+}
+
+function markBatchCapped(url, methods) {
+ const until = Date.now() + BATCH_CAP_TTL_MS;
+ for (const m of methods) _batchCapped.set(methodKey(url, m), until);
+}
+
+/** Read-only view of the lanes known to cap batches, for the ops/health surface. */
+export function rpcBatchCaps(now = Date.now()) {
+ const out = [];
+ for (const [key, until] of _batchCapped) {
+ if (until <= now) continue;
+ const [url, method] = key.split(METHOD_KEY_SEP);
+ out.push({ host: maskUrl(url), method, expiresInMs: until - now });
+ }
+ return out;
+}
+
// Rotating fetch backing a Connection. It NEVER surfaces a rotate-worthy status
// (401/403/429/5xx) to @solana/web3.js — it either returns a healthy response or
// throws — so web3.js's internal 429 backoff loop ("Server responded with 429 …
@@ -1133,6 +1233,37 @@ export function makeRotatingFetch(endpoints) {
// error is treated as a failure — web3.js would otherwise choke on it with a
// `StructError`, and the /api/solana-rpc proxy would forward the garbage (an
// empty `[]`) straight to the browser.
+ // The batch this request carries, if it is one. Null for a single call, which
+ // makes every batch-cap check below a no-op.
+ const batch = batchElements(typeof init?.body === 'string' ? init.body : '');
+
+ // Re-send `batch` to `url` as single JSON-RPC requests and merge the envelopes
+ // back into the array the caller is waiting for. Order is preserved (web3.js
+ // matches on id, but a caller reading positionally must not be surprised).
+ // Throws on the first sub-request that fails validation, so the caller rotates
+ // exactly as it would for any other lane failure — never a partial array.
+ const sendUnbatched = async (url, signal) => {
+ const envelopes = new Array(batch.length);
+ let cursor = 0;
+ const worker = async () => {
+ for (let i = cursor++; i < batch.length; i = cursor++) {
+ const resp = await fetch(url, { ...init, signal, body: JSON.stringify(batch[i]) });
+ if (!resp.ok) throw new Error(`solana rpc ${resp.status} @ ${maskUrl(url)} (unbatched)`);
+ const text = await resp.text();
+ const bad = classifyRpcBody(text);
+ if (bad) throw new Error(`solana rpc ${bad.reason} @ ${maskUrl(url)} (unbatched)`);
+ envelopes[i] = JSON.parse(text);
+ }
+ };
+ await Promise.all(
+ Array.from({ length: Math.min(BATCH_SPLIT_CONCURRENCY, batch.length) }, worker),
+ );
+ return new Response(JSON.stringify(envelopes), {
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ });
+ };
+
const tryEndpoint = async (url) => {
// Bound every attempt so one hanging provider can never absorb the whole
// request budget (undici's default timeouts run to minutes): the attempt
@@ -1143,11 +1274,33 @@ export function makeRotatingFetch(endpoints) {
// ReferenceError instead of rotating and killed the whole failover chain
// (the play-gate 502 of 2026-08-13).
const attemptSignal = AbortSignal.timeout(ATTEMPT_TIMEOUT_MS);
+ const signal = init?.signal
+ ? AbortSignal.any([init.signal, attemptSignal])
+ : attemptSignal;
+ // A batch splits into at most MAX_BATCH_SPLIT single requests; a wider one
+ // is cheaper to rotate than to unroll against a lane that caps at 1.
+ const splittable = !!batch && batch.length <= MAX_BATCH_SPLIT;
try {
- const resp = await fetch(url, {
- ...init,
- signal: init?.signal ? AbortSignal.any([init.signal, attemptSignal]) : attemptSignal,
- });
+ // This lane already told us it caps batches for these shapes — skip the
+ // probe request that only re-learns it and go straight to singles.
+ if (splittable && isBatchCapped(url, methods)) return { response: await sendUnbatched(url, signal) };
+
+ const resp = await fetch(url, { ...init, signal });
+ // A per-batch cap is the lane's own policy, not a caller error and not a
+ // lane fault, so it neither rotates nor cools: unroll and re-send here.
+ if (splittable && !resp.ok) {
+ const bodyText = await resp
+ .clone()
+ .text()
+ .catch(() => '');
+ if (isBatchLimitRefusal(bodyText)) {
+ markBatchCapped(url, methods);
+ console.log(
+ `[solana-rpc] ${maskUrl(url)} caps batches for ${methods.join(',') || 'this shape'}, re-sending ${batch.length} calls unbatched`,
+ );
+ return { response: await sendUnbatched(url, signal) };
+ }
+ }
if (shouldRotate(resp.status)) {
// Read the body only on the failure path (we never return it) so a
// quota signal can pick the long cooldown, and so a 401/403 can be told
@@ -1167,6 +1320,15 @@ export function makeRotatingFetch(endpoints) {
return { error: new Error(`solana rpc ${resp.status} @ ${maskUrl(url)}`) };
}
const okBody = await resp.text();
+ // Same cap, stated politely: some nodes answer a too-wide batch with a
+ // 200 carrying one error envelope instead of an HTTP 400.
+ if (splittable && isBatchLimitRefusal(okBody)) {
+ markBatchCapped(url, methods);
+ console.log(
+ `[solana-rpc] ${maskUrl(url)} caps batches for ${methods.join(',') || 'this shape'}, re-sending ${batch.length} calls unbatched`,
+ );
+ return { response: await sendUnbatched(url, signal) };
+ }
const bad = classifyRpcBody(okBody);
if (bad) {
penalise(url, bad.status, bad.bodyText || '', bad.methodBlock === true, bad.log);
diff --git a/tests/solana-rpc-rotating-fetch.test.js b/tests/solana-rpc-rotating-fetch.test.js
index eb6865560..9dc32a31e 100644
--- a/tests/solana-rpc-rotating-fetch.test.js
+++ b/tests/solana-rpc-rotating-fetch.test.js
@@ -3,6 +3,8 @@ import {
makeRotatingFetch,
classifyRpcBody,
markEndpointCooldown,
+ isBatchLimitRefusal,
+ batchElements,
} from '../api/_lib/solana/connection.js';
// A Response carrying either a raw string body or a JSON-encoded object, the way a
@@ -175,3 +177,127 @@ describe('provider daily-limit (-32003 / "request limit reached")', () => {
}
});
});
+
+// web3.js sends getTransactions/getParsedTransactions as ONE JSON-RPC array of N
+// getTransaction calls. PublicNode caps that at 1 per batch and rejects the whole
+// array with HTTP 400 + -32600 "Maximum number of 'getTransaction' calls in a
+// batch request is 1" — a plain 4xx, which shouldRotate deliberately treats as a
+// caller error and surfaces as-is. Left unclassified it hard-failed every batched
+// read on that lane while single calls to the same lane worked: the pump.fun MCP
+// `get_token_trades` tool returned nothing but that 400 (measured 2026-08-15).
+// The lane is healthy, so the fix is to unroll the batch onto the SAME lane.
+describe('per-lane JSON-RPC batch caps', () => {
+ const PUBLICNODE_CAP =
+ "Maximum number of 'getTransaction' calls in a batch request is 1. To increase limits, get a personal token here: https://www.allnodes.com/publicnode";
+
+ const batchBody = (n) =>
+ JSON.stringify(
+ Array.from({ length: n }, (_, i) => ({
+ jsonrpc: '2.0',
+ id: i + 1,
+ method: 'getTransaction',
+ params: [`sig${i}`, { maxSupportedTransactionVersion: 0 }],
+ })),
+ );
+
+ let origFetch;
+ beforeEach(() => {
+ origFetch = global.fetch;
+ });
+ afterEach(() => {
+ global.fetch = origFetch;
+ });
+
+ it('recognises the measured refusal, and not a genuine invalid-params error', () => {
+ expect(isBatchLimitRefusal(PUBLICNODE_CAP)).toBe(true);
+ expect(isBatchLimitRefusal('batch request size exceeds the limit of 10')).toBe(true);
+ expect(isBatchLimitRefusal('Invalid params: unrecognized signature')).toBe(false);
+ expect(isBatchLimitRefusal('')).toBe(false);
+ });
+
+ it('reads batch elements only from a real multi-call batch', () => {
+ expect(batchElements(batchBody(3))).toHaveLength(3);
+ expect(batchElements(batchBody(1))).toBeNull(); // a one-element array is not worth splitting
+ expect(batchElements('{"jsonrpc":"2.0","id":1,"method":"getBalance"}')).toBeNull();
+ expect(batchElements('not json')).toBeNull();
+ expect(batchElements(undefined)).toBeNull();
+ });
+
+ it('re-sends a capped batch as single calls on the same lane, preserving order', async () => {
+ const eps = ['https://batchcap-a.test/'];
+ const seen = [];
+ global.fetch = vi.fn(async (url, init) => {
+ const parsed = JSON.parse(init.body);
+ if (Array.isArray(parsed)) {
+ return resp({ jsonrpc: '2.0', id: null, error: { code: -32600, message: PUBLICNODE_CAP } }, 400);
+ }
+ seen.push(parsed.params[0]);
+ return resp({ jsonrpc: '2.0', id: parsed.id, result: { sig: parsed.params[0] } });
+ });
+
+ const out = await makeRotatingFetch(eps)(null, { method: 'POST', body: batchBody(4) });
+ const merged = await out.json();
+ expect(out.status).toBe(200);
+ expect(merged).toHaveLength(4);
+ expect(merged.map((e) => e.result.sig)).toEqual(['sig0', 'sig1', 'sig2', 'sig3']);
+ expect(merged.map((e) => e.id)).toEqual([1, 2, 3, 4]);
+ expect(seen.sort()).toEqual(['sig0', 'sig1', 'sig2', 'sig3']);
+ });
+
+ it('remembers the cap so the next batch skips the rejected probe request', async () => {
+ const eps = ['https://batchcap-b.test/'];
+ let batchAttempts = 0;
+ global.fetch = vi.fn(async (url, init) => {
+ const parsed = JSON.parse(init.body);
+ if (Array.isArray(parsed)) {
+ batchAttempts++;
+ return resp({ jsonrpc: '2.0', id: null, error: { code: -32600, message: PUBLICNODE_CAP } }, 400);
+ }
+ return resp({ jsonrpc: '2.0', id: parsed.id, result: 'ok' });
+ });
+ const rf = makeRotatingFetch(eps);
+ await rf(null, { method: 'POST', body: batchBody(3) });
+ await rf(null, { method: 'POST', body: batchBody(3) });
+ // Only the FIRST request pays for discovering the cap.
+ expect(batchAttempts).toBe(1);
+ });
+
+ it('splits on a 200-status refusal too, not only an HTTP 400', async () => {
+ const eps = ['https://batchcap-c.test/'];
+ global.fetch = vi.fn(async (url, init) => {
+ const parsed = JSON.parse(init.body);
+ if (Array.isArray(parsed)) {
+ return resp({ jsonrpc: '2.0', id: null, error: { code: -32600, message: PUBLICNODE_CAP } });
+ }
+ return resp({ jsonrpc: '2.0', id: parsed.id, result: 'ok' });
+ });
+ const merged = await (await makeRotatingFetch(eps)(null, { method: 'POST', body: batchBody(2) })).json();
+ expect(merged.map((e) => e.result)).toEqual(['ok', 'ok']);
+ });
+
+ it('rotates to the next lane when an unrolled single call also fails', async () => {
+ const eps = ['https://batchcap-d1.test/', 'https://batchcap-d2.test/'];
+ global.fetch = vi.fn(async (url, init) => {
+ const parsed = JSON.parse(init.body);
+ if (String(url) === eps[0]) {
+ return Array.isArray(parsed)
+ ? resp({ jsonrpc: '2.0', id: null, error: { code: -32600, message: PUBLICNODE_CAP } }, 400)
+ : resp('server error', 503);
+ }
+ return resp(Array.isArray(parsed) ? parsed.map((el) => ({ jsonrpc: '2.0', id: el.id, result: 'lane2' })) : VALID);
+ });
+ const merged = await (await makeRotatingFetch(eps)(null, { method: 'POST', body: batchBody(2) })).json();
+ expect(merged.map((e) => e.result)).toEqual(['lane2', 'lane2']);
+ });
+
+ it('leaves a lane that serves the batch whole completely alone', async () => {
+ const eps = ['https://batchcap-e.test/'];
+ const fetchSpy = vi.fn(async (url, init) =>
+ resp(JSON.parse(init.body).map((el) => ({ jsonrpc: '2.0', id: el.id, result: 'whole' }))),
+ );
+ global.fetch = fetchSpy;
+ const merged = await (await makeRotatingFetch(eps)(null, { method: 'POST', body: batchBody(5) })).json();
+ expect(merged).toHaveLength(5);
+ expect(fetchSpy).toHaveBeenCalledTimes(1);
+ });
+});