Assistant de Migration Solana Kit

Cette compétence vous aide à naviguer la transition entre @solana/web3.js (v1.x) et @solana/kit (anciennement web3.js 2.0), en fournissant des conseils sur quand utiliser chaque bibliothèque et comment migrer entre elles.

Vue d'ensemble

L'écosystème JavaScript Solana propose deux options SDK majeures :

Bibliothèque	Statut	Cas d'usage
`@solana/web3.js` (1.x)	Mode maintenance	Projets existants, applications dépendantes d'Anchor
`@solana/kit`	Développement actif	Nouveaux projets, applications critiques en performance

Décision clé : @solana/kit est l'avenir, mais la migration n'est pas toujours simple.

Quand utiliser chaque bibliothèque

Utiliser @solana/kit quand :

Démarrer un nouveau projet sans dépendances Anchor
La taille du bundle compte - Kit est modulaire (26 % de bundles plus petits)
La performance est critique - ~200 ms de latence de confirmation plus rapide, crypto 10x plus rapide
Utiliser des programmes standards (System, Token, Associated Token)
Construire des applications navigateur où la taille du bundle impacte le temps de chargement
La sécurité des types est importante - Meilleur support TypeScript détecte les erreurs à la compilation
Utiliser du JavaScript moderne - BigInt natif, WebCrypto, AsyncIterators

Utiliser @solana/web3.js (v1.x) quand :

Utiliser Anchor - Anchor ne supporte pas Kit nativement pour l'instant
Base de code existante importante - Le coût de migration dépasse les bénéfices
Les dépendances nécessitent v1 - Vérifiez si vos SDKs supportent Kit
Prototypage rapide - Le style OOP de v1 peut être plus familier
Documentation/exemples - Plus de ressources communautaires pour v1

Utiliser les deux (approche hybride) quand :

Migration progressive - Utilisez @solana/compat pour l'interopérabilité
Dépendances mixtes - Certaines libs nécessitent v1, d'autres supportent Kit
Migration feature par feature - Convertissez d'abord les chemins critiques

Organigramme de décision rapide

DÉMARRAGE
  │
  ├─ Nouveau projet? ─────────────────────────────────────────┐
  │     │                                                   │
  │     ├─ Utiliser Anchor? ──► OUI ──► Utiliser @solana/web3.js   │
  │     │                                                   │
  │     └─ Pas Anchor? ──► Utiliser @solana/kit                  │
  │                                                         │
  └─ Projet existant? ────────────────────────────────────┤
        │                                                   │
        ├─ Problèmes de performance? ──► Envisager la migration      │
        │                                                   │
        ├─ Problèmes de taille du bundle? ──► Envisager la migration      │
        │                                                   │
        └─ Fonctionne bien? ──► Rester avec le SDK actuel         │

Instructions pour l'analyse de migration

Lorsqu'un utilisateur demande une migration, suivez ces étapes :

Étape 1 : Analyser la base de code actuelle

Exécutez le script d'analyse de migration pour détecter :

Quelle version du SDK est actuellement utilisée
Les dépendances Anchor
Les dépendances SDK tierces
Les modèles d'utilisation qui nécessitent une migration

# Utilisez le script analyze-migration.sh dans scripts/
./scripts/analyze-migration.sh /path/to/project

Étape 2 : Vérifier les dépendances

Recherchez ces dépendances bloquantes :

@coral-xyz/anchor ou @project-serum/anchor - Attendez le support Anchor Kit
Les SDKs qui n'ont pas migré (vérifiez leur package.json)

Étape 3 : Évaluer la complexité de migration

Comptez les occurrences de ces modèles qui nécessitent des modifications :

new Connection(...) → createSolanaRpc(...)
Keypair.fromSecretKey(...) → createKeyPairSignerFromBytes(...)
new PublicKey(...) → address(...)
new Transaction() → createTransactionMessage(...)
Modèles basés sur les classes → Composition fonctionnelle avec pipe()

Étape 4 : Recommander une stratégie

En fonction des résultats, recommandez :

Migration complète : Si aucun blocage et < 50 points de migration
Migration progressive : Si 50-200 points de migration, utilisez @solana/compat
Attendre : Si dépendant d'Anchor ou les SDKs critiques ne supportent pas Kit
Hybride : Si seulement certains modules ont besoin de la performance de Kit

Référence de migration API

Voir resources/api-mappings.md pour les mappages complets. Conversions clés :

Connection → RPC

// v1
const connection = new Connection(url, 'confirmed');
const balance = await connection.getBalance(pubkey);

// Kit
const rpc = createSolanaRpc(url);
const { value: balance } = await rpc.getBalance(address).send();

Keypair → KeyPairSigner

// v1
const keypair = Keypair.fromSecretKey(secretKey);
console.log(keypair.publicKey.toBase58());

// Kit
const signer = await createKeyPairSignerFromBytes(secretKey);
console.log(signer.address);

Construction de transaction

// v1
const tx = new Transaction().add(
  SystemProgram.transfer({
    fromPubkey: sender.publicKey,
    toPubkey: recipient,
    lamports: amount,
  })
);
tx.recentBlockhash = blockhash;
tx.feePayer = sender.publicKey;

// Kit
const tx = pipe(
  createTransactionMessage({ version: 0 }),
  tx => setTransactionMessageFeePayer(sender.address, tx),
  tx => setTransactionMessageLifetimeUsingBlockhash(blockhash, tx),
  tx => appendTransactionMessageInstruction(
    getTransferSolInstruction({
      source: sender,
      destination: address(recipient),
      amount: lamports(BigInt(amount)),
    }),
    tx
  ),
);

Cas limites et pièges

1. Conversion BigInt

Kit utilise BigInt natif partout. Attention à :

// INCORRECT - échouera
const amount = 1000000000;

// CORRECT
const amount = 1_000_000_000n;
// ou
const amount = BigInt(1000000000);
// ou utiliser helper
const amount = lamports(1_000_000_000n);

2. Erreurs d'encodage Base58

Kit peut nécessiter un encodage explicite :

// Si vous voyez : "Encoded binary (base 58) data should be less than 128 bytes"
// Ajoutez le paramètre encoding :
await rpc.getAccountInfo(address, { encoding: 'base64' }).send();

3. Génération de Keypair asynchrone

La création de keypair dans Kit est asynchrone (utilise WebCrypto) :

// v1 - synchrone
const keypair = Keypair.generate();

// Kit - DOIT utiliser await
const keypair = await generateKeyPairSigner();

4. Chaînage des appels RPC

Les appels RPC de Kit nécessitent .send() :

// v1
const balance = await connection.getBalance(pubkey);

// Kit - n'oubliez pas .send()!
const { value: balance } = await rpc.getBalance(address).send();

5. PublicKey vs Address

Ce sont des types différents et non interchangeables :

// Utilisez @solana/compat pour la conversion
import { fromLegacyPublicKey, toLegacyPublicKey } from '@solana/compat';

const kitAddress = fromLegacyPublicKey(legacyPublicKey);
const legacyPubkey = toLegacyPublicKey(kitAddress);

6. Signature de transaction

Le flux de signature est différent :

// v1
transaction.sign(keypair);
// ou
const signed = await connection.sendTransaction(tx, [keypair]);

// Kit - utiliser le modèle signer
const signedTx = await signTransactionMessageWithSigners(txMessage);
const signature = await sendAndConfirmTransaction(signedTx);

7. Incompatibilité Anchor

Anchor génère des types v1. Si vous utilisez Anchor :

// Gardez @solana/web3.js pour les interactions Anchor
import { Connection, PublicKey } from '@solana/web3.js';
import { Program } from '@coral-xyz/anchor';

// Utilisez Kit pour les parties non-Anchor si nécessaire
// Faire le pont avec @solana/compat

8. Gestion des abonnements

Kit utilise AsyncIterators :

// v1
const subscriptionId = connection.onAccountChange(pubkey, callback);
connection.removeAccountChangeListener(subscriptionId);

// Kit - utiliser AbortController
const abortController = new AbortController();
const notifications = await rpcSubscriptions
  .accountNotifications(address)
  .subscribe({ abortSignal: abortController.signal });

for await (const notification of notifications) {
  // gérer notification
}
// Pour se désabonner :
abortController.abort();

9. Migration VersionedTransaction

// v1
const versionedTx = new VersionedTransaction(messageV0);

// Kit - les transactions sont versionnées par défaut
const tx = createTransactionMessage({ version: 0 });

10. Lookup Tables

Les Address Lookup Tables fonctionnent différemment :

// v1
const lookupTable = await connection.getAddressLookupTable(tableAddress);
const messageV0 = new TransactionMessage({...}).compileToV0Message([lookupTable.value]);

// Kit
// Les lookup tables sont gérées dans la compilation de transaction
// Voir resources/lookup-tables-example.md

Alternative : Envisager Gill

Si Kit semble trop bas niveau, envisagez Gill :

Construit sur les primitives de Kit
Abstractions de plus haut niveau
API plus simple pour les tâches courantes
Compatibilité complète avec Kit

import { createSolanaClient, sendSol } from 'gill';

const client = createSolanaClient({ rpcUrl });
await sendSol(client, { from: signer, to: recipient, amount: lamports(1n) });

Directives

Toujours vérifier la compatibilité Anchor avant de recommander une migration Kit
Recommander @solana/compat pour les migrations progressives
Les bénéfices de taille de bundle comptent surtout pour les applications navigateur
Les bénéfices de performance comptent surtout pour les backends à haut débit
Ne pas migrer du code stable et fonctionnel sans bénéfices clairs
Tester en détail - Kit a des types d'erreur et des comportements différents

Fichiers dans cette compétence

solana-kit-migration/
├── SKILL.md                          # Ce fichier
├── scripts/
│   ├── analyze-migration.sh          # Script d'analyse de base de code
│   └── detect-patterns.js            # Utilitaire de détection de modèles
├── resources/
│   ├── api-mappings.md               # Référence API complète
│   ├── compatibility-matrix.md       # Info de compatibilité SDK
│   └── package-comparison.md         # Comparaison des fonctionnalités
├── examples/
│   ├── v1-to-kit/                    # Exemples de migration
│   │   ├── basic-transfer.md
│   │   ├── token-operations.md
│   │   └── subscription-handling.md
│   └── mixed-codebase/               # Exemples d'approche hybride
│       └── anchor-with-kit.md
└── docs/
    └── edge-cases.md                 # Cas limites détaillés

Vérifier

Un appel RPC/SDK réel a été émis (mainnet, devnet, ou validateur local) et la charge de réponse est capturée dans le transcript, pas seulement paraphrasée
Chaque transaction a été simulée (simulateTransaction ou équivalent) avant toute étape de signature/envoi ; les journaux de simulation sont joints
Pour toute transaction signée/envoyée, la signature résultante est enregistrée et confirmée on-chain (statut renvoyé par getSignatureStatuses ou une URL d'explorateur)
Le slippage, la priority-fee, et les limites de compute-unit ont été définis explicitement avec des valeurs numériques concrètes, pas laissés aux défauts de la bibliothèque
Les adresses de compte, mints, et IDs de programme utilisés dans l'exécution correspondent aux adresses solana-kit-migration documentées pour le cluster ciblé (pas de mélange mainnet/devnet)
Le chemin d'échec a été exercé au moins une fois (solde insuffisant, oracle obsolète, blockhash expiré, etc.) et la gestion des erreurs de l'agent a produit un message lisible

Notes

Kit a été publié en tant que @solana/web3.js@2.0.0 le 16 décembre 2024
Il a été renommé ultérieurement en @solana/kit pour éviter la confusion
La ligne 1.x est en mode maintenance mais toujours largement utilisée
Les outils de migration évoluent - vérifiez les mises à jour régulièrement