solana-program-upgrade は何をしますか？
ライブな Solana プログラムをアップグレードし、そのオンチェーンアカウントデータを安全に移行するためのスキルです -
バージョニング、遅延 realloc マイグレーション、フォークシミュレーション、アップグレード権限の整理、ロールバック。これはSolana開発において最も壊滅的なライフサイクルステップであり、これを生存可能にします。
拡張機能:
solana-dev-skillそのスキルは新規の Anchor/Pinocchio/テストの基本を担当します。このスキルはアップグレード + マイグレーションライフサイクルのみを担当します。プログラムが既にデプロイされていて変更が必要な場合にこれを使用してください。
黄金律（安全の背骨）
- バージョンタグと移行パスなしに、ライブなアカウントレイアウトを決して変更しないでください。
古いアカウントは生のバイト列です。変更された構造体でそれらを読み取る新しいコードは、
AccountDidNotDeserializeや無言のデータ破損を引き起こします。8バイトのディスクリミネータは型を制限しますが、バージョンは制限しません。 - メインネットに適用する前に、実際のクローンされたメインネットステートに対してシミュレーションを行ってください。 フォーク上で正確なアップグレードとマイグレーションを常に実行し、アカウントのバイトを比較してください。例外はありません。
- アップグレード権限をマルチシグ化してください。 すべてのプログラムロジックを置き換えられる単一のホットキーは、詐取/侵害のベクトルです。Squads v4 に移行してください。
- オンチェーンデータのマイグレーションは通常、前方互換のみです。 追加的で再開可能なように設計し、データを元に戻せることを前提にしないでください。
- 以前の
.soファイルを保持してください。 データを元に戻せなくても、コードはいつでも素早くロールバックできます。 - デフォルトで devnet/localnet/fork を使用してください。 どの例でもメインネットを自動ターゲットにしないでください。
アップグレードワークフロー
順番に従ってください。各ステップは詳細なファイルにルーティングされます。
- スキーマの差分を確認する - 古い
#[account]構造体と新しいものを比較します。追加的変更と破壊的変更（並び替え/削除/型変更 = 破壊的）を特定します。 - 戦略を選択する - 即時クランク vs 遅延アクセス時マイグレーション vs 新しいアカウントへのコピー ->
migration-strategies.md - バージョン管理された構造体を記述する - バージョンタグを追加し、保存されたバージョンで分岐します ->
account-versioning.md - マイグレーションを実装する - 手動
realloc（移植可能なベースライン）->realloc-migration.md、または AnchorMigration型（利用可能なバージョンの場合）->anchor-migration-type.md - フォーク上でシミュレーションする - 実際のアカウントをクローンし、アップグレードを実行し、バイトを比較し、冪等性を確認します ->
fork-simulation.md - 権限を保護する - メインネットに触れる前に、Squads マルチシグを確認/移行します ->
upgrade-authority.md - バイナリをデプロイする - バッファフロー、サイズが大きい場合は
extend、IDL、--final->program-deploy-upgrade.md - 確認し、ロールバック計画を保持する - アカウントがデシリアライズ可能であることを確認します。以前の
.soと中途半端なマイグレーションからの回復パスを保持します ->rollback-recovery.md
ルーティングテーブル
状況に合った行を見つけて、そのファイルを読んでください。
| 症状 / タスク | 読むファイル |
|---|---|
AccountDidNotDeserialize / サイズ不一致 / アップグレード後の値の誤り | account-versioning.md、次に realloc-migration.md |
#[account] 構造体のフィールドを追加/削除/並び替え/型変更した | account-versioning.md |
| 「後で変更できるようにアカウントをバージョン管理するには？」 | account-versioning.md |
| 既存のアカウントをその場で拡張/縮小する必要がある | realloc-migration.md |
| 遅延「アクセス時マイグレーション」 vs 即時一括マイグレーション | realloc-migration.md、migration-strategies.md |
realloc::zero 古いバイトの落とし穴 / レント補充の方向 | realloc-migration.md |
| 命令ごとの 10KB realloc 成長制限、大きな成長 | realloc-migration.md |
新しい Anchor Migration<'info, From, To> 型を使用したい | anchor-migration-type.md |
AccountAlreadyMigrated / AccountNotMigrated エラー | anchor-migration-type.md |
| 即時 vs 遅延 vs 新しいアカウントへのコピーの選択 | migration-strategies.md |
| 多数のアカウントセット（例：数万）を低コストで移行する | migration-strategies.md |
| バッチ/クランク/キーパーによるマイグレーション、ページネーション、進捗追跡 | migration-strategies.md |
| その場での realloc が不可能（データの縮小、型変更） | migration-strategies.md |
| プログラムバイナリの再デプロイ / アップグレード | program-deploy-upgrade.md |
solana program write-buffer / deploy --buffer フロー | program-deploy-upgrade.md |
新しい .so がデプロイ済みのものより大きい場合（solana program extend） | program-deploy-upgrade.md |
IDL のアップグレード（anchor idl upgrade） | program-deploy-upgrade.md |
| その場でのデプロイ vs 新しいプログラムID（PDA/アカウントへの影響） | program-deploy-upgrade.md |
| プログラムを誰が制御するか？単一キー vs マルチシグ | upgrade-authority.md |
| アップグレード権限を Squads v4 マルチシグに移行する | upgrade-authority.md |
set-upgrade-authority、タイムロック、キー管理 | upgrade-authority.md |
プログラムを不変にする（--final）とそのコスト | upgrade-authority.md |
| メインネット前にアップグレードをテストする / 実際の状態をクローンする | fork-simulation.md |
| Surfpool メインネットフォーク；アップグレード前後のアカウントバイトを比較する | fork-simulation.md |
| マイグレーション命令の LiteSVM / Mollusk ユニットテスト | fork-simulation.md |
| マイグレーションが冪等であることの証明（2回実行 = 副作用なし） | fork-simulation.md |
| アップグレードに失敗した - 古いコードを素早く戻す | rollback-recovery.md |
| 中途半端に移行されたアカウントセット；安全に再開する | rollback-recovery.md |
| 一時停止 / マイグレーションガード / 緊急フィーチャーフラグ | rollback-recovery.md |
| Native / Pinocchio プログラム（Anchor の糖衣構文なし） | realloc-migration.md、account-versioning.md |
| 信頼できるリンクとドキュメント（最新版を確認） | resources.md |
コンパニオンツール
- コマンド:
/plan-upgrade（スキーマ差分 -> 移行計画 + リスクレポート）、/simulate-upgrade（フォーク、クローン、実行、比較）、/check-upgrade-authority（単一キー vs マルチシグの監査）。 - エージェント:
program-migration-architect（スキーマ差分からマイグレーションを設計）、migration-qa-engineer（フォーク/LiteSVM テストを作成し、データ破損がないことを確認）。 - ルール:
account-layout-guardは#[account]構造体 /state.rsの編集時に自動的に発動し、バージョンアップと移行パスを要求します。
正確性の契約
ルーティングされたファイル内のすべての CLI フラグ、Anchor 制約、クレート、アカウント型は、実際に存在し検証可能でなければなりません。不確かな場合は、インストール済みのバージョン（anchor --version、solana --version、Anchor の変更履歴）に対して検証してください。決して invent（独自に創作）しないでください。Migration 型は未リリースの可能性があるものとして扱ってください。手動の realloc パターンが移植可能なデフォルトです。