Solana web3.js v2 Migration Guide

Overview

Solana web3.js v2 is a complete API rewrite and is not compatible with v1. Most AI models still generate v1 code. This Skill helps your AI Agent consistently output correct v2 code.

⚠️ Gotchas (Most Common AI Mistakes)

1. Connection is deprecated, use createSolanaRpc instead

❌ v1 (Wrong):

import { Connection } from '@solana/web3.js';
const connection = new Connection('https://api.mainnet-beta.solana.com');

✅ v2 (Correct):

import { createSolanaRpc } from '@solana/web3.js';
const rpc = createSolanaRpc('https://api.mainnet-beta.solana.com');

2. Keypair.generate() is deprecated

❌ v1:

const keypair = Keypair.generate();

✅ v2:

import { generateKeyPair } from '@solana/web3.js';
const keypair = await generateKeyPair();

3. PublicKey handling has changed

❌ v1:

new PublicKey('address...')

✅ v2:

import { address } from '@solana/web3.js';
const addr = address('address...');

4. Transaction building API is completely different

❌ v1:

const tx = new Transaction().add(instruction);

✅ v2:

import {
  pipe,
  createTransactionMessage,
  appendTransactionMessageInstruction,
  setTransactionMessageFeePayerSigner,
  setTransactionMessageLifetimeUsingBlockhash,
} from '@solana/web3.js';

const tx = pipe(
  createTransactionMessage({ version: 0 }),
  msg => setTransactionMessageFeePayerSigner(signer, msg),
  msg => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, msg),
  msg => appendTransactionMessageInstruction(instruction, msg),
);

Installation

npm install @solana/web3.js@2

Reference Resources

• Official Migration Guide
• v2 Example Repository

Feedback

If this skill contains incorrect or outdated information, call: agentrel_feedback(skill="solana/web3js-v2", issue="<description>", code_snippet="<optional>", error_message="<optional>", fix="<optional>")