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-rpc): fail over when a short-ledger node answers -32020 for a signature cursor it does not hold

nirholasbb1f40c1bbe5
diff --git a/api/_lib/solana/connection.js b/api/_lib/solana/connection.js
index 31e45ef22..89ea6af20 100644
--- a/api/_lib/solana/connection.js
+++ b/api/_lib/solana/connection.js
@@ -1056,6 +1056,19 @@ const PROVIDER_CAPACITY_CODES = new Set([
// demotion, never a lane bench: the lane is healthy for every other shape.
const JSONRPC_INTERNAL_ERROR = -32603;
+// -32020 "Transaction <sig> not found" is how a node with a short ledger answers a
+// getSignaturesForAddress whose `until`/`before` cursor is older than its own
+// history. It is a statement about THAT node's storage, not about the chain:
+// measured 2026-10-09, PublicNode and Solana Vibe Station both answer -32020 for a
+// finalized 2026-10-03 signature while mainnet-beta answers the same call
+// normally. Unclassified, the envelope reached the caller as the chain's verdict,
+// so both leak scanners, whose cursors age past PublicNode's window, stopped
+// reading every controlled wallet for six days. Disposition: fail this request
+// over and charge the lane NOTHING, because the same lane serves the same method
+// for any cursor it does hold. A signature no node holds still fails, just after
+// the whole chain has been asked.
+const JSONRPC_HISTORY_NOT_ON_NODE = -32020;
+
// A provider that refuses one call shape: by paid-tier gate, by policy, or by
// switching the method off: answers with a method-shaped JSON-RPC error, and the
// dangerous variant answers HTTP 200 so no status-driven rotation fires. Measured
@@ -1178,6 +1191,19 @@ export function classifyRpcBody(body) {
methodBlock: true,
};
}
+ // History this node does not hold (see JSONRPC_HISTORY_NOT_ON_NODE). Another
+ // lane may hold it, and this lane is healthy, so `noPenalty` rotates without
+ // cooling or demoting anything.
+ if (hasError && item.error?.code === JSONRPC_HISTORY_NOT_ON_NODE) {
+ const msg = String(item.error?.message || '');
+ return {
+ status: 502,
+ reason: 'history not on node',
+ log: `200 + history not on node -32020 ${msg.slice(0, 48)}`.trim(),
+ bodyText: msg,
+ noPenalty: true,
+ };
+ }
}
return null;
}
@@ -1599,7 +1625,7 @@ export function makeRotatingFetch(endpoints) {
}
const bad = classifyRpcBody(okBody);
if (bad) {
- penalise(url, bad.status, bad.bodyText || '', bad.methodBlock === true, bad.log);
+ if (!bad.noPenalty) penalise(url, bad.status, bad.bodyText || '', bad.methodBlock === true, bad.log);
return { error: new Error(`solana rpc ${bad.reason} @ ${maskUrl(url)}`) };
}
// Body already consumed above; hand the caller a fresh Response carrying
diff --git a/docs/ops/solana-rpc-lanes.md b/docs/ops/solana-rpc-lanes.md
index 023eb0705..11b552326 100644
--- a/docs/ops/solana-rpc-lanes.md
+++ b/docs/ops/solana-rpc-lanes.md
@@ -145,6 +145,15 @@ to 8/8 on a warmed instance:
mainnet-beta). Its throttle answers `-32005`, which the capacity classifier already
parks correctly, so it is depth rather than a primary.
+**`-32020` (2026-10-09) is a free failover too.** PublicNode and Solana Vibe Station
+keep a short ledger, so a `getSignaturesForAddress` whose `until` or `before` cursor is
+older than their history answers `-32020 Transaction <sig> not found` while
+mainnet-beta answers the same call normally. Handed back as the chain's verdict, it left
+both leak scanners unable to read any controlled wallet for six days once their cursors
+aged past PublicNode's window. `classifyRpcBody` now rotates on it with `noPenalty`:
+nothing is cooled or demoted, because the same lane serves the method for every cursor
+it does hold.
+
The standing cost is unchanged and is a billing decision, not a code one: while both
metered lanes sit at their monthly ceiling, this shape is served only by throttled
free nodes, so it stays the first read to degrade.
diff --git a/tests/solana-rpc-method-capability.test.js b/tests/solana-rpc-method-capability.test.js
index 4d89a43de..e7ed91e97 100644
--- a/tests/solana-rpc-method-capability.test.js
+++ b/tests/solana-rpc-method-capability.test.js
@@ -392,6 +392,49 @@ describe('classifyRpcBody: a node internal error is a per-shape failover, not an
});
});
+// PublicNode and Solana Vibe Station keep a short ledger. Asked for signatures
+// `until` a cursor older than that window they answer -32020 "Transaction <sig>
+// not found", while mainnet-beta answers the same call (measured live
+// 2026-10-09). Handed back as the chain's answer, that error blinded both leak
+// scanners for six days once their cursors aged past PublicNode's history.
+const SHORT_LEDGER_NOT_FOUND = {
+ jsonrpc: '2.0',
+ id: 1,
+ error: { code: -32020, message: 'Transaction 5UUzsXbGUSoimU1qzfmnbYUXhGyURDN3KjQcZ5ENtoqXuBXt3JKkKVqeHSkgLtuU3pm2dqP1VNud7Bt8ytpAwc5H not found' },
+};
+
+describe('classifyRpcBody: history a node does not hold is a free failover', () => {
+ it('fails a -32020 envelope over without demoting or cooling anything', () => {
+ const bad = classifyRpcBody(JSON.stringify(SHORT_LEDGER_NOT_FOUND));
+ expect(bad).toBeTruthy();
+ expect(bad.reason).toBe('history not on node');
+ expect(bad.noPenalty).toBe(true);
+ expect(bad.methodBlock).toBeFalsy();
+ });
+
+ it('rotates onto a lane that holds the cursor and leaves the short-ledger lane primary', async () => {
+ const shortLedger = 'https://cap-h1.test/';
+ const archive = 'https://cap-h2.test/';
+ const page = { jsonrpc: '2.0', id: 1, result: [] };
+ global.fetch = vi.fn(async (url, init) => {
+ const { method, params } = JSON.parse(init.body);
+ if (url === shortLedger && method === 'getSignaturesForAddress' && params?.[1]?.until) return resp(SHORT_LEDGER_NOT_FOUND);
+ return resp(method === 'getSignaturesForAddress' ? page : OK);
+ });
+ const rf = makeRotatingFetch([shortLedger, archive]);
+
+ const r = await rf(null, rpc('getSignaturesForAddress', ['WalletPlaceholder111111111111111111111111111', { limit: 100, until: 'OldCursor' }]));
+ await expect(r.json()).resolves.toEqual(page);
+ expect(global.fetch.mock.calls.at(-1)[0]).toBe(archive);
+ expect(isEndpointCooling(shortLedger)).toBe(false);
+ expect(isMethodDemoted(shortLedger, 'getSignaturesForAddress')).toBe(false);
+
+ // A cursor the short-ledger lane does hold still goes to it first.
+ await rf(null, rpc('getSignaturesForAddress', ['WalletPlaceholder111111111111111111111111111', { limit: 100 }]));
+ expect(global.fetch.mock.calls.at(-1)[0]).toBe(shortLedger);
+ });
+});
+
// PublicNode accepts a getTokenLargestAccounts and then never answers it: no
// response at 35 s, while getAccountInfo comes back in milliseconds. Charging
// that hang to the LANE parked the free chain's primary for every method, on one