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.

test(solana-attestations): cover the pruned-cursor recovery that unwedges a stalled attestation crawl

nirholas9ed49dc7f49f
diff --git a/prompts/swarm-100/cron-batch-06.md b/prompts/swarm-100/cron-batch-06.md
deleted file mode 100644
index 8e216a66a..000000000
--- a/prompts/swarm-100/cron-batch-06.md
+++ /dev/null
@@ -1,106 +0,0 @@
-# Cron audit batch 06: /api/llm/health and 7 more
-
-How to run: paste this file's repo path into a fresh Claude Code chat in this
-repository and say "run this work order". This file is fully self-contained:
-it depends on no other prompt file anywhere. If neighboring files in
-prompts/swarm-100/ are gone, that work is done; if present, ignore them.
-Every claim below rots; step 0 re-measures, and what you measure wins.
-
-## Operating clause (binding)
-
-- Read CLAUDE.md first. Its rules override everything, including this file.
-- Finish 100% in this session. Never end the turn with a question, an option
- list, or an unexecuted plan. A judgment call goes in one line of the final
- report; it never becomes a question that halts work.
-- The only permitted stops are the CLAUDE.md stop-and-ask gates: spending real
- funds or any irreversible on-chain write, git push or a production deploy,
- committing content that references a crypto project other than $THREE, and
- destroying unrecoverable data.
-- No mocks, no fake data, no placeholder stubs, no unfinished-work markers, no
- commented-out code. Real APIs and real integrations only.
-- The em-dash and en-dash characters are banned in everything you write.
-- Concurrent agents share this worktree: stage explicit paths only (never a
- bare add-everything), and commit finished work promptly.
-- Before committing, run: npm run check:rules -- --paths <files you touched>.
- It must exit 0.
-
-## Step 0: re-derive the current state
-
-1. Confirm each cron below still exists in vercel.json crons; removed ones are
- out of scope.
-2. Scheduler truth (crons run on Cloud Scheduler, never in-process):
-
- export PATH="$HOME/google-cloud-sdk/bin:$PATH"
- gcloud scheduler jobs list --project aerial-vehicle-466722-p5 --location us-central1 | grep -E 'health|cleanup-csrf-tokens|treasury-autopilot|process-withdrawals|erc8004-crawl|solana-autodeploy|solana-attestations-crawl|trader-score-attest'
-
-3. Production behavior, last 72h, per cron:
-
- gcloud logging read 'resource.type="cloud_run_revision" resource.labels.service_name="three-ws-api" textPayload:"<cron name>"' --freshness=72h --limit 50 --project aerial-vehicle-466722-p5
-
-## Task: verify and fix these scheduled jobs
-
-Crons in this batch:
-
-- /api/llm/health
-- /api/cron/cleanup-csrf-tokens
-- /api/cron/treasury-autopilot
-- /api/cron/process-withdrawals
-- /api/cron/erc8004-crawl
-- /api/cron/solana-autodeploy
-- /api/cron/solana-attestations-crawl
-- /api/cron/trader-score-attest
-
-For each cron:
-
-1. Read the handler and its auth guard (crons authenticate; find the shared
- pattern in api/_lib before invoking anything).
-2. Invoke it once against a locally started server with the proper cron auth
- from .env. It must complete without an unhandled error and be safe to run
- twice (idempotent); if a local run would move real funds or write on-chain,
- audit its dry-run or validation path instead and say so in the report.
-3. Production logs from step 0: zero unhandled errors and evidence it actually
- fires on schedule. A cron that exists in vercel.json but has no scheduler
- job, or vice versa, is drift: fix it (npm run check:cron-drift helps).
-4. Fix every failure at root: the handler, the schedule, or the env it needs.
-
-## Definition of done
-
-- [ ] Every cron in the batch has a scheduler job, a clean local invocation
- (or an audited dry-run path for money-moving crons), and 72h of
- production logs free of unhandled errors.
-- [ ] npm run check:cron-drift and npm run check:cron-syntax pass.
-- [ ] npm run check:rules -- --paths <touched files> exits 0; vitest passes if
- code changed.
-
-## Never blocked
-
-| Blocker | Resolution (act, do not ask) |
-|---|---|
-| Missing env var or credential | Check .env and .env.local, then the Cloud Run service env, then Secret Manager (the CLAUDE.md self-unblock playbook has the exact commands). If it truly exists nowhere, wire the code fully behind the env var, prove the wiring with a dry run, and name the single missing var in the report. |
-| gcloud not on PATH | Run: export PATH="$HOME/google-cloud-sdk/bin:$PATH" |
-| Dev server port 3000 busy | Another agent may be serving this repo; probe it and reuse if so. Otherwise start your own on a free port: npx vite --port 3101 |
-| Playwright browser missing | npx playwright install chromium |
-| A surface needs a signed-in user | Register a fresh account through the real /register flow against the real API and use it. Never mock the session. |
-| A defect sits in code you did not touch | Fix it if it blocks a Definition of done line (root cause it, never mask it). Otherwise note it in the report and continue. |
-| An unrelated test is red | Same rule. Never pipe npm test through tail; it masks exit codes. |
-
-## Close out (required)
-
-1. Verify every Definition of done line with the actual command output in
- front of you. Never claim a line you did not verify.
-2. Commit with explicit paths and a subject that describes the diff (house
- style: type(scope): what changed and why a reader cares).
-3. Delete this prompt file in that same commit:
-
- git rm prompts/swarm-100/cron-batch-06.md
-
- The shrinking directory is this campaign's only progress ledger; there is
- no progress log to update.
-4. Final report: what step 0 measured, what changed (file list), evidence per
- Definition of done line, and any one-line judgment calls. No trailing
- questions, no unexecuted plans.
-
-If a line genuinely cannot pass inside this session (an external party must
-respond, or an owner-gated action is the final step), finish everything else,
-leave this file in place, and state exactly which line remains and who owns
-it. Never delete this file on a partial.
diff --git a/tests/solana-attestations-cursor-recovery.test.js b/tests/solana-attestations-cursor-recovery.test.js
new file mode 100644
index 000000000..5aae2a688
--- /dev/null
+++ b/tests/solana-attestations-cursor-recovery.test.js
@@ -0,0 +1,82 @@
+// A pruned attestation cursor used to wedge one agent's crawl forever: the cron
+// stores only the newest signature it saw, presents it back as
+// getSignaturesForAddress({ until }), and the RPC fails the WHOLE call with
+// "Transaction <sig> not found" once that signature leaves its ledger. Every
+// later tick replayed the same dead signature, so the agent stopped indexing
+// permanently while the cron kept reporting 200 (the handler catches per agent).
+// These cover the recovery: detect that class of error, re-scan from the head.
+
+import { describe, it, expect } from 'vitest';
+import { isPrunedCursorError, signaturesSinceCursor } from '../api/_lib/solana-attestations.js';
+
+// The message shape a Solana RPC actually returns for a pruned `until`.
+const PRUNED = new Error(
+ 'failed to get signatures for address: Transaction 4q3xLaQ6U76xRPQfXBK9FebjS26tEWzvT7pUonQcDFubovFy6dAohpZWpwHGg6hfJc6EoXVKUL4U9NfMo6vCKU2g not found',
+);
+
+describe('isPrunedCursorError', () => {
+ it('matches the RPC message for a cursor the node no longer has', () => {
+ expect(isPrunedCursorError(PRUNED)).toBe(true);
+ expect(isPrunedCursorError(new Error('Transaction abc123 not found'))).toBe(true);
+ });
+
+ it('does not swallow unrelated RPC failures', () => {
+ expect(isPrunedCursorError(new Error('429 Too Many Requests'))).toBe(false);
+ expect(isPrunedCursorError(new Error('fetch failed'))).toBe(false);
+ expect(isPrunedCursorError(null)).toBe(false);
+ });
+});
+
+describe('signaturesSinceCursor', () => {
+ const KEY = 'AgentAsset1111111111111111111111111111111111';
+ const SIGS = [{ signature: 'newest' }, { signature: 'older' }];
+
+ it('passes the cursor through on the happy path and reports no reset', async () => {
+ const calls = [];
+ const conn = {
+ async getSignaturesForAddress(key, opts) {
+ calls.push(opts);
+ return SIGS;
+ },
+ };
+ const out = await signaturesSinceCursor(conn, KEY, 200, 'cursor-sig');
+ expect(out).toEqual({ sigs: SIGS, cursorReset: false });
+ expect(calls).toEqual([{ limit: 200, until: 'cursor-sig' }]);
+ });
+
+ it('re-scans from the head when the cursor has been pruned', async () => {
+ const calls = [];
+ const conn = {
+ async getSignaturesForAddress(key, opts) {
+ calls.push(opts);
+ if (opts.until) throw PRUNED;
+ return SIGS;
+ },
+ };
+ const out = await signaturesSinceCursor(conn, KEY, 200, 'pruned-sig');
+ expect(out).toEqual({ sigs: SIGS, cursorReset: true });
+ // The second attempt drops `until` entirely. That is what breaks the stall.
+ expect(calls).toEqual([{ limit: 200, until: 'pruned-sig' }, { limit: 200 }]);
+ });
+
+ it('rethrows an unrelated failure instead of masking it as a reset', async () => {
+ const conn = {
+ async getSignaturesForAddress() {
+ throw new Error('429 Too Many Requests');
+ },
+ };
+ await expect(signaturesSinceCursor(conn, KEY, 200, 'cursor-sig')).rejects.toThrow('429');
+ });
+
+ it('does not retry when there was no cursor to begin with', async () => {
+ let calls = 0;
+ const conn = {
+ async getSignaturesForAddress() {
+ calls += 1;
+ throw PRUNED;
+ },
+ };
+ await expect(signaturesSinceCursor(conn, KEY, 200, undefined)).rejects.toThrow('not found');
+ expect(calls).toBe(1);
+ });
+});