solana-survivor

Automate your @solana/web3.js → @solana/kit migration

npx solana-survivor migrate

Solana replaced their entire core SDK. Every project on @solana/web3.js needs to migrate — and there's no official automated path.

Solana Survivor is a production-grade migration engine. It combines deterministic AST codemods with an AI agent to automate up to 90% of the work, then generates a full report so you know exactly what happened.

What it does

┌──────────────────────────────────────────────────────────┐
│                 npx solana-survivor migrate               │
├───────────┬──────────────────────────────────────────────┤
│  Stage 1  │  Scanner   — finds every web3.js usage       │
│  Stage 2  │  Codemods  — deterministic AST transforms    │
│  Stage 3  │  AI Agent  — resolves edge cases             │
│  Stage 4  │  Verify    — runs tsc + your test suite      │
│  Stage 5  │  Report    — coverage %, flags, next steps   │
└───────────┴──────────────────────────────────────────────┘

Commands

migrate — Run the full pipeline

npx solana-survivor migrate [path]
npx solana-survivor migrate ./my-project --dry-run
npx solana-survivor migrate ./my-project --verbose --skip-agent

Options:

• --dry-run — Preview transforms without writing files
• --skip-agent — Skip the AI agent step
• --skip-verify — Skip TypeScript verification
• --verbose — Show detailed output

scan — Analyse without transforming

npx solana-survivor scan [path]

Outputs a manifest of every @solana/web3.js call site found. Writes .solana-survivor/manifest.json.

report — Display the last migration report

npx solana-survivor report [path]

Reads .solana-survivor/migration-report.json and prints a formatted summary.

verify — Run post-migration checks

npx solana-survivor verify [path]

Runs tsc --noEmit and your project's test suite, reports zero-error status.

Coverage

| Pattern | Automation level | How | |---|---|---| | from '@solana/web3.js' imports | Automated | Rewrites to tree-shaken @solana/kit imports | | new Connection(url) | Automated | → createSolanaRpcClient(url) | | new PublicKey(str) | Automated | → address(str) | | .toBase58() | Automated | Removed — Address is a branded string | | Keypair.generate() | Automated | → await generateKeyPair() | | Keypair.fromSecretKey() | Automated | → await importKeyPair({...}) | | LAMPORTS_PER_SOL arithmetic | Automated | → solToLamports() / lamportsToSol() | | SystemProgram.transfer({...}) | Automated | → getTransferSolInstruction({...}) | | new Transaction().add(...) | Automated | → pipe-based createTransaction builder | | sendAndConfirmTransaction(...) | Automated | → sendAndConfirmTransactionFactory pattern | | WebSocket subscriptions | Todo-flagged | Manual — async iterator pattern required | | Custom wallet adapters | AI Agent | Claude reads your adapter and proposes a diff | | Dynamic transaction builders | AI Agent | Claude resolves runtime-shape ambiguity |

Migration report

Every run produces .solana-survivor/migration-report.json and prints:

Solana Survivor — Migration Report
───────────────────────────────────
Files scanned:          47
Codemod coverage:       78%   (37 files fully transformed)
AI agent coverage:      12%   (6 files — proposals in agent-diffs/)
Manual review needed:   10%   (4 files — see flags below)
TypeScript errors:      0     (was 143 before migration)
Time taken:             12s

Flags
└─ send-flow    ×3   src/tx/send.ts ...
└─ async-pattern ×2  src/subscriptions.ts ...

Todo markers

When the codemod can't automatically transform a pattern, it inserts a comment:

// solana-survivor-todo: [send-flow] sendAndConfirmTransaction — requires factory pattern setup.
// Add to module top: const sendAndConfirm = sendAndConfirmTransactionFactory({ rpc, rpcSubscriptions }).

Categories: send-flow · async-pattern · wallet-adapter · transaction-builder · unknown

Search your codebase for solana-survivor-todo to find everything that needs attention.

Requirements

• Node.js 18+
• TypeScript project (JavaScript also supported)

License

MIT