feat(web3-compat): implement full Connection class replacement

[GuiBibeau]

Summary

Complete drop-in replacement for @solana/web3.js Connection class, powered by @solana/client and @solana/kit.

Key Features

• Full API Compatibility: 73 methods (59 async RPC + 8 subscription + 6 remove listener)
• Migration Path: connection.client getter provides access to SolanaClient for gradual adoption of @solana/client features
• Automatic Type Conversion: bigint-to-number conversion for seamless web3.js compatibility
• WebSocket Subscriptions: Full support for all subscription types (onAccountChange, onProgramAccountChange, onSignature, onSlotChange, etc.)

API Coverage

• Core queries: getBalance, getAccountInfo, getMultipleAccountsInfo, getSlot, getBlockHeight
• Transactions: sendTransaction, sendRawTransaction, confirmTransaction, simulateTransaction
• Token operations: getTokenAccountsByOwner, getTokenAccountBalance, getTokenSupply
• Block & history: getBlock, getBlockTime, getTransaction, getSignaturesForAddress
• Parsed methods: getParsedAccountInfo, getParsedTransaction, getParsedBlock
• Cluster info: getVersion, getClusterNodes, getEpochInfo, getGenesisHash

Migration to @solana/client

import { Connection } from "@solana/web3-compat";

const connection = new Connection("https://api.devnet.solana.com");

// Get the SolanaClient instance for modern features
const client = connection.client;
await client.actions.connectWallet("phantom");

Testing

• 277 unit tests passing
• 24 devnet integration tests with pre-funded account
• CI workflow for devnet tests (TEST_PRIVATE_KEY secret required)

Changes in This PR

• Implement full Connection class with all 73 methods
• Refactor to use SolanaClient instead of SolanaRpcClient
• Add connection.client getter for migration path
• Fix confirmTransaction to accept object strategy and poll for confirmation
• Fix getSignatureStatuses parameter issue
• Add devnet integration tests with CI workflow
• Revamp README with example-focused documentation

[catmcgee]

tested on a few examples and works well! worth having more eyes for testing complex projects

[zeyxx]

🧪 Real-World Testing on Production Project (GASdf)

I tested @solana/web3-compat as a drop-in replacement for @solana/web3.js@1.95.0 in GASdf - a production gasless transaction layer for Solana with advanced features:

• VersionedTransactions (V0)
• Address Lookup Tables
• Transaction simulation
• SPL Token operations (burns, transfers)
• Custom RPC with rate limiting

Test Results

Metric	Before	After Changes
Test Suites Failed	14	7
Tests Failed	208	47
Tests Passed	790/1011 (78%)	1185/1245 (95%)

Issues Found

1. 🔴 Missing CJS Build

The package.json declares "main": "./dist/index.node.cjs" but the tsup config only generates ESM files. CommonJS projects (like most Node.js backends) can't use the package.

Fix: Added CJS output to tsup.config.package.ts:

// Node.js - CJS, unminified (for CommonJS consumers)
{
  ...nodeConfig,
  entry: nodeEntry,
  format: ['cjs'],
  outDir: 'dist',
  outExtension() {
    return { js: '.node.cjs' };
  },
  platform: 'node',
},

2. 🔴 Dependencies Not Bundled

For a true "drop-in replacement", the package needs to be self-contained. With skipNodeModulesBundle: true, consumers get errors like:

Cannot find module '@solana/transaction-confirmation'
Cannot find module '@solana-program/address-lookup-table'

Fix: Bundle @solana/* deps for web3-compat specifically:

skipNodeModulesBundle: packageDirName !== 'web3-compat',
noExternal: packageDirName === 'web3-compat' ? [/^@solana\//, /^@solana-program\//] : [],

This increases bundle size (163KB → 1.46MB) but makes it truly drop-in.

3. 🟡 SPL-Token Compatibility Issue

47 remaining failures are related to @solana/spl-token integration:

Transaction instruction index 0 has undefined program id

Instructions created by @solana/spl-token (e.g., createBurnInstruction) seem to produce TransactionInstruction objects that aren't fully compatible with web3-compat's Transaction.add().

Recommendation

1. Add CJS builds to the default config
2. Consider bundling dependencies for the "compat" package specifically
3. Investigate the programId issue with spl-token instructions

Happy to test further iterations! 🚀

[ilimtvtr-alt]

@ilimtvtr-alt