solana-kit-migration

Solana Kit 移行アシスタント

このスキルでは、@solana/web3.js（v1.x）と@solana/kit（旧称 web3.js 2.0）間の移行について、各ライブラリを使い分けるタイミングや移行方法をご案内します。

概要

Solana JavaScript エコシステムには、主に2つの SDK があります。

ライブラリ	状態	用途
@solana/web3.js (1.x)	メンテナンスモード	レガシープロジェクト、Anchor に依存するアプリ
@solana/kit	開発が活発	新規プロジェクト、パフォーマンスが重要なアプリ

重要な判断ポイント：@solana/kitが今後の主流ですが、移行が必ずしも簡単とは限りません。

各ライブラリを使うタイミング

@solana/kit を使う場合：

1. Anchor 依存なしで新規プロジェクトを始める
2. バンドルサイズが重要な場合 — Kit はツリーシェイキングに対応しています（バンドルサイズを26％削減）
3. パフォーマンスが重要な場合 — 確定までのレイテンシーが約200ms短縮され、暗号処理が10倍高速です
4. 標準プログラム（System、Token、Associated Token）を使う場合
5. バンドルサイズが読み込み時間に影響するブラウザーアプリケーションを構築する
6. 型安全性が重要な場合 — TypeScript のサポートが向上し、コンパイル時にエラーを検出できます
7. モダンな JavaScript を使う場合 — ネイティブの BigInt、WebCrypto、AsyncIterators に対応しています

@solana/web3.js (v1.x) を使う場合：

1. Anchor を使う場合 — Anchor はまだ Kit を標準ではサポートしていません
2. 既存の大規模なコードベースがある場合 — 移行コストがメリットを上回ります
3. 依存関係が v1 を必要とする場合 — 使用している SDK が Kit をサポートしているか確認してください
4. 迅速なプロトタイピングを行う場合 — v1 の OOP スタイルの方がなじみやすい可能性があります
5. ドキュメントやサンプルを重視する場合 — v1 向けのコミュニティリソースの方が豊富です

両方を使う（ハイブリッド方式）場合：

1. 段階的に移行する場合 — 相互運用には@solana/compatを使います
2. 依存関係が混在している場合 — v1 を必要とするライブラリと Kit をサポートするライブラリがあります
3. 機能単位で移行する場合 — まず頻繁に実行される処理を変換します

簡単な判断フローチャート

START
  │
  ├─ New project? ─────────────────────────────────────────┐
  │     │                                                   │
  │     ├─ Using Anchor? ──► YES ──► Use @solana/web3.js   │
  │     │                                                   │
  │     └─ No Anchor? ──► Use @solana/kit                  │
  │                                                         │
  └─ Existing project? ────────────────────────────────────┤
        │                                                   │
        ├─ Performance issues? ──► Consider migration      │
        │                                                   │
        ├─ Bundle size issues? ──► Consider migration      │
        │                                                   │
        └─ Working fine? ──► Stay with current SDK         │

移行分析の手順

ユーザーから移行について質問された場合は、次の手順に従ってください。

ステップ 1：現在のコードベースを分析する

移行分析スクリプトを実行し、次の項目を検出します。

• 現在使われている SDK のバージョン
• Anchor の依存関係
• サードパーティ SDK の依存関係
• 移行が必要な使用パターン

# Use the analyze-migration.sh script in scripts/
./scripts/analyze-migration.sh /path/to/project

ステップ 2：依存関係を確認する

移行の妨げになる次の依存関係を探します。

• @coral-xyz/anchor または@project-serum/anchor — Anchor の Kit サポートを待ちます
• まだ移行していない SDK（package.json を確認してください）

ステップ 3：移行の複雑さを評価する

変更が必要な次のパターンの出現回数を数えます。

• new Connection(...) → createSolanaRpc(...)
• Keypair.fromSecretKey(...) → createKeyPairSignerFromBytes(...)
• new PublicKey(...) → address(...)
• new Transaction() → createTransactionMessage(...)
• クラスベースのパターン → pipe()を使った関数合成

ステップ 4：移行方針を提案する

調査結果に基づいて、次の方針を提案します。

• 全面的な移行：妨げとなる要因がなく、移行箇所が50未満の場合
• 段階的な移行：移行箇所が50～200の場合。@solana/compatを使います
• 待機：Anchor に依存している場合、または重要な SDK が Kit をサポートしていない場合
• ハイブリッド：特定のモジュールだけで Kit のパフォーマンスが必要な場合

API 移行リファレンス

完全な対応表はresources/api-mappings.mdを参照してください。主な変換例：

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);

トランザクションの構築

// 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
  ),
);

エッジケースと注意点

1. BigInt への変換

Kit ではすべての箇所でネイティブの BigInt を使います。次の点に注意してください。

// WRONG - will fail
const amount = 1000000000;

// CORRECT
const amount = 1_000_000_000n;
// or
const amount = BigInt(1000000000);
// or use helper
const amount = lamports(1_000_000_000n);

2. Base58 エンコードエラー

Kit ではエンコーディングの指定が明示的に必要な場合があります。

// If you see: "Encoded binary (base 58) data should be less than 128 bytes"
// Add encoding parameter:
await rpc.getAccountInfo(address, { encoding: 'base64' }).send();

3. 非同期の Keypair 生成

Kit での Keypair 作成は非同期です（WebCrypto を使用します）。

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

// Kit - MUST await
const keypair = await generateKeyPairSigner();

4. RPC メソッドのチェーン

Kit の RPC 呼び出しには.send()が必要です。

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

// Kit - don't forget .send()!
const { value: balance } = await rpc.getBalance(address).send();

5. PublicKey と Address

これらは異なる型で、互換性はありません。

// Use @solana/compat for conversion
import { fromLegacyPublicKey, toLegacyPublicKey } from '@solana/compat';

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

6. トランザクションへの署名

署名の流れが異なります。

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

// Kit - use signer pattern
const signedTx = await signTransactionMessageWithSigners(txMessage);
const signature = await sendAndConfirmTransaction(signedTx);

7. Anchor との非互換性

Anchor は v1 の型を生成します。Anchor を使っている場合：

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

// Use Kit for non-Anchor parts if needed
// Bridge with @solana/compat

8. サブスクリプションの処理

Kit では AsyncIterators を使います。

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

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

for await (const notification of notifications) {
  // handle notification
}
// To unsubscribe:
abortController.abort();

9. VersionedTransaction の移行

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

// Kit - transactions are versioned by default
const tx = createTransactionMessage({ version: 0 });

10. ルックアップテーブル

アドレスルックアップテーブルの動作は異なります。

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

// Kit
// Lookup tables are handled in transaction compilation
// See resources/lookup-tables-example.md

代替案：Gill を検討する

Kit が低レベルすぎると感じる場合は、Gillを検討してください。

• Kit のプリミティブを基盤としています
• より高水準の抽象化を提供します
• 一般的なタスク向けの、よりシンプルな API を備えています
• Kit と完全な互換性があります

import { createSolanaClient, sendSol } from 'gill';

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

ガイドライン

• Kit への移行を推奨する前に、必ず Anchor との互換性を確認してください
• 段階的な移行には@solana/compatを推奨してください
• バンドルサイズのメリットが最も重要なのは、ブラウザーアプリケーションです
• パフォーマンスのメリットが最も重要なのは、高スループットのバックエンドです
• 明確なメリットがない場合、安定して動作しているコードを移行しないでください
• 十分にテストしてください。Kit ではエラーの種類や動作が異なります

このスキルのファイル

solana-kit-migration/
├── SKILL.md                          # This file
├── scripts/
│   ├── analyze-migration.sh          # Codebase analysis script
│   └── detect-patterns.js            # Pattern detection utility
├── resources/
│   ├── api-mappings.md               # Complete API reference
│   ├── compatibility-matrix.md       # SDK compatibility info
│   └── package-comparison.md         # Feature comparison
├── examples/
│   ├── v1-to-kit/                    # Migration examples
│   │   ├── basic-transfer.md
│   │   ├── token-operations.md
│   │   └── subscription-handling.md
│   └── mixed-codebase/               # Hybrid approach examples
│       └── anchor-with-kit.md
└── docs/
    └── edge-cases.md                 # Detailed edge cases

注記

• Kit は 2024 年 12 月 16 日に @solana/[email protected] としてリリースされました
• その後、混同を避けるために @solana/kit に改称されました
• 1.x 系列はメンテナンスモードですが、現在も広く使用されています
• 移行ツールは進化しています。定期的に更新を確認してください