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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
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.jsindex 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 carryingdiff --git a/docs/ops/solana-rpc-lanes.md b/docs/ops/solana-rpc-lanes.mdindex 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 alreadyparks 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 bothmetered lanes sit at their monthly ceiling, this shape is served only by throttledfree 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.jsindex 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