magicblock

MagicBlock 開発スキル

solana-dev スキルと併用する

ER/PER、委任、オラクル、Session Keys、クランク、VRF、Magic Actions、eSPL、プライベート決済など、MagicBlock 固有の事項にはこのスキルを使用してください。スキャフォールディング、PDA、アカウントレイアウト、SPL トークン、クライアント、ウォレット、LiteSVM/Mollusk テストなど、一般的な Solana または Anchor の作業では、solana-dev も読み込んでください。

主な概念

エフェメラルロールアップは、ベースレイヤー上で委任されたアカウントをロックし、そのアカウントの元のプログラム所有者のもとで ER のクローンが実行を続けることで、高性能かつ低レイテンシーなトランザクションを実現します。ゲーム、リアルタイムアプリ、高速なトランザクション処理に役立ちます。

エフェメラルアカウントは、ER 内でのみ作成、使用、クローズされます。一時的で高頻度に更新される状態に役立ちますが、Solana にコミットされないため、永続的な所有権、残高、報酬、精算結果の唯一のコピーとして使用することはできません。

委任では、ベースレイヤーのアカウントを一時的に Delegation Program に割り当て、元のプログラム所有者のもとで ER にクローンします。通常のプログラム所有権、署名者、権限、アカウントの制約は ER 上でも引き続き適用されます。委任ステータスはルーティングとライフサイクルに関するものであり、新たなアプリケーション認可ルールではありません。

委任後のアクションでは、delegate_account_with_actions を使用して、ベースレイヤーの委任に命令を付加します。Delegation Program はそれらを委任レコードに保存し、バリデーターはクローンの作成後に ER 上で実行します。ベースレイヤーでの委任が成功しても、アクションの実行が保証されるわけではありません。公開または暗号化されたペイロード、署名者の処理、復旧については、delegation-actions.md を参照してください。これらはベースレイヤーで実行される委任後の Magic Actions とは異なります。

委任のデバッグに関する不変条件：適切に委任されたアカウントは、ベースレイヤーでは delegation program に所有されているように見え、ルーターの getDelegationStatus が返す ER エンドポイントでは元のプログラムに所有されているように見え、delegated=true の状態で ER にクローンされます。

検証済み SDK v0.16.2 のスナップショットでは、コミットおよびコミットと委任解除のインテントをスケジュールするために、MagicIntentBundleBuilder を使用してください。非推奨のフリー関数 commit_accounts および commit_and_undelegate_accounts は使用しないでください。

**プライベートエフェメラルロールアップ（PER）**では、ER ローカルの EphemeralPermission を使い、TEE 対応バリデーター内で委任されたアカウントへのアクセスを制御します。ベースレイヤーではデータアカウントのみを委任し、ER 上で CreateEphemeralPermissionCpi、UpdateEphemeralPermissionCpi、CloseEphemeralPermissionCpi を使って、その権限を作成、更新、クローズしてください。ベースレイヤーに別の権限アカウントを作成したり、委任したりしないでください。

Magic Actionsは、MagicIntentBundleBuilder.add_post_commit_actions(...) を介して ER トランザクション内でスケジュールされる、ベースレイヤーの命令です。試行された各ベースレイヤーのトランザクションでは、コミットとアクションがアトミックに適用されます。いずれかの BaseAction が失敗すると、committor は、影響を受ける TransactionStrategy 内のすべての BaseAction を削除してから、残りのコミット戦略を再試行します。ほかのトランザクション戦略または finalize 戦略のアクションは、この削除の対象外です。最初にスケジュールしたすべてのアクションを監視し、結果を照合してください。スケジュールまたは最終的なコミットが成功しただけでは、いずれかのアクションが実行されたことの証明にはなりません。

コミット手数料と上限は、Delegation Program とバリデーターにまたがります。手数料ボールトの経路を使わない場合、アカウントの現在の nonce が 10 に達すると、通常のコミットは失敗します。受け入れられたコミットでも、委任解除時に委任 PDA の手数料予算を消費することがあります。委任された支払者と、バリデーターのスコープに設定された magic_fee_vault を使う場合、コミット 26 から、コミットされるアカウントごとに 100_000 lamports の引き落としが始まります。手数料、返金、スポンサーシップ、コスト見積もり、手数料支払者への資金補充に関する質問については、まず fees-and-commit-economics.md を参照してください。 Lamports の補充：委任されたアカウント（例：委任された手数料支払者）が ER 側でさらに lamports を必要とする場合は、SDK の lamportsDelegatedTransferIx を使用します。トランザクションはベースレイヤーで送信されます。Ephemeral SPL Token プログラムが使い捨ての lamports PDA を作成して資金を供給し、委任することで、ER が宛先にクレジットします。

Ephemeral SPL Token には 2 つの利用形態があります。SDK のライフサイクルモデルでは、クライアントは delegateSpl/transferSpl/undelegateIx/withdrawSpl を使用します。ER の残高は所有者の正規 ATA アドレスにある通常の SPL トークン アカウントとして表示されるため、Anchor プログラムは通常の SPL Token CPI を使用できます。直接プログラムモデルでは、コントラクトは ephemeral-spl-api を使用し、eATA／グローバルボールトの PDA を明示的に扱います。この直接利用の形態には、正規 ATA モデルを適用しないでください。

Pricing Oracle は、Solana／ER の利用者向けにサポート対象の市場フィードを再公開します。安全に統合するには、期待されるフィード ID、上流の公開時刻の鮮度、値の範囲、指数、算術演算の検査、およびユーザーの価格上限・下限を検証します。デシリアライズに成功しただけでは、価格の検証にはなりません。

Session Keys は、制約されたアプリケーションアクション用の一時的な署名者を認可します。セッションの有効性は SPL トークンの権限とは別です。トークンを使用するには、明示的に設定された上限付きのトークンデリゲート許容量も必要です。

アーキテクチャ：

┌─────────────────┐     delegate      ┌─────────────────────┐
│   Base Layer    │ ───────────────►  │  Ephemeral Rollup   │
│    (Solana)     │                   │    (MagicBlock)     │
│                 │  ◄───────────────  │                     │
└─────────────────┘    undelegate     └─────────────────────┘
     ~400ms                                  ~10-50ms

デフォルトのスタック

プログラム

ephemeral-rollups-sdk と Anchor を使用します。ネイティブおよび Pinocchio もサポートされています。

• 明示的なアップグレードがタスクでない限り、対象リポジトリに既存の ephemeral-rollups-sdk／Anchor のバージョンを使用します
• SDK の機能フラグで Anchor のバージョン範囲が選択されます。Anchor 1.x のプログラムには anchor、Anchor >=0.28,<1.0 のプログラムには anchor-compat を使用します

必須マクロ：

• プログラムモジュールに #[ephemeral] を、#[program] より前に指定します。これにより process_undelegation コールバック（委任プログラムがアカウントを返すためにこのコールバックを CPI で呼び出します）と、コミット／委任解除のインテントビルダーが挿入されます。コミットと委任解除には必須ですが、委任自体には不要です。アカウントを後で委任解除できるよう、委任を行うすべてのプログラムに指定してください。
• 対応する委任／コミットのアカウントコンテキストに #[delegate] と #[commit] を指定します。
• VRF のリクエストコンテキストに #[vrf] を、さらに VRF のコールバックコンテキストに #[vrf_callback] を指定します。コールバックマクロが結果の受け取りを認証します。ephemeral-rollups-sdk の vrf 機能を有効にしてください。 SDK v0.16.2 では VRF が再エクスポートされるため、新しい Anchor コードで ephemeral-vrf-sdk を直接依存関係に追加する必要はありません。vrf.md を参照してください。

Anchor 以外のプログラム： ephemeral-rollups-pinocchio クレートを使用します（委任、コミット、VRF には Pinocchio 版があります）。engine examples リポジトリには roll-dice の Anchor 版と Pinocchio 版があります。対象プログラムが Anchor ではなくネイティブの場合は、Pinocchio を使用してください。

このスキルに記載されているバージョンは、動作確認済みのスナップショットまたは互換性を示す目印です。依存関係を変更する前に、対象リポジトリのマニフェスト、ツールチェーンファイル、ロックファイル、および関連する上流ソースを確認してください。日付付きスナップショットとソースへのリンクについては、resources.md を参照してください。

接続

• 初期化と委任にはベースレイヤー接続を使用します： https://rpc.magicblock.app/devnet または https://rpc.magicblock.app/mainnet
• 委任状態の確認にはルーター接続を使用します： https://devnet-router.magicblock.app/ または https://router.magicblock.app/
• 委任されたアカウントの操作にはエフェメラルロールアップ接続を使用します： ルーターの getDelegationStatus が返す fqdn を使用してください

トランザクションのルーティング

• 委任トランザクション → ベースレイヤー
• 委任されたアカウントの操作 → エフェメラルロールアップ
• 委任解除／コミットトランザクション → エフェメラルロールアップ

運用手順

0. 設計が決まっていない場合はアーキテクチャを計画する

新しいアプリケーション、インテグレーション設計、移行、または実装計画では、コードを書く前に architecture-planning.md を読んでください。MagicBlock が必要かどうかを判断し、必要最小限の製品セットを選択して、アカウントとトランザクションのルーティングを整理し、決済と復旧を定義して、検証環境を選択します。各ラウンドで重要な質問は最大 3 つまでにし、それ以外の場合は明示的な前提を置いて進めます。

1. 操作の種類を分類する

• アカウントの初期化（ベースレイヤー）
• 委任（ベースレイヤー）
• 委任後のアクション（ベースレイヤーでスケジュールされ、クローン作成後に ER で実行）
• 委任されたアカウントに対する操作（エフェメラルロールアップ）
• 状態のコミット（エフェメラルロールアップ）
• 委任解除（エフェメラルロールアップ）
• ER 専用のエフェメラルアカウントのライフサイクル（エフェメラルロールアップ。コミットは行いません）
• 非同期サービスの処理（VRF コールバック、クランク、キューに登録された送金、または Magic Action）
• クライアントによる署名・送信に続く、ホストされた API でのトランザクション構築

2. 適切な接続先を選ぶ

• ベースレイヤー：https://rpc.magicblock.app/devnet または https://rpc.magicblock.app/mainnet
• ルーター：https://devnet-router.magicblock.app/ または https://router.magicblock.app/
• エフェメラルロールアップ：アカウントのルーター getDelegationStatus が返す fqdn

3. MagicBlock 固有の正確性を確保して実装する

各実装について、以下を記録します。

• 各トランザクションで使用する接続先
• 操作前のルーター getDelegationStatus の確認
• delegate 呼び出しとアカウント定義の間で一致する PDA シード
• 対応するベーストランザクションでは事前シミュレーションを維持し、既知のシミュレーション非互換性がある ER パスに限り skipPreflight: true を使用すること（理由を文書化し、実行ログを確認すること）
• delegate／undelegate 後の状態伝播を待つこと
• Ephemeral SPL Token のフローでは、入金と出金のビルダーを個別に選択すること：デフォルトの shuttle 出金を使用するか、明示的に undelegateIx を実行してベースへのコミットを待ち、レガシーの withdrawSpl(..., { idempotent: false }) を呼び出します。直接 CPI には、コピーしたバイト列や推測したシードではなく ephemeral-spl-api のエクスポートを使用します。
• オラクルのフローでは、ID、最大経過時間、数値変換、ユーザー制限、古いフィードの動作を扱うこと
• Session Keys では、スコープ、有効期限、任意のワンタイム署名者への lamports 補充、失効、アプリケーション側で適用する支出制限、および別個の SPL デリゲート許容量を扱うこと
• 非同期フローでは、受理／スケジュールと完了の違いに加えて、監視、冪等性、タイムアウト、再試行、返金、照合を扱うこと

セキュリティ上重要な設計、レビュー、実装では、security.md を読んでください。プロトコルの保証と、必要なインテグレーション検証、アプリケーションポリシー、一般的な Solana セキュリティを区別します。アプリケーション上の推奨事項を MagicBlock プロトコルの保証として示さないでください。

4. 稼働中の委任／ルーティングの障害をデバッグする

InvalidWritableAccount、プライベート残高の欠落、バリデーターの不一致、または「アカウントは委任済みだが ER に拒否される」という報告については、以下を実施します。

• 正確な署名またはアカウントの公開鍵から調査を開始します。
• ルーター getDelegationStatus を照会し、ER の読み取り／トランザクションにはその fqdn を使用します。
• ベースの所有者、ルーターのステータス、ER の所有者、および最近の ER トランザクションログを比較します。
• 委任されたアカウントがベース上で委任プログラムに所有されている状態は想定どおりとして扱います。
• 詳細な手順については、debugging.md を参照してください。

5. サービス側で発生した可能性のある障害を診断する

サービス側で発生した可能性のある予期しない RPC、ルーティング、オラクル、またはトランザクションのエラーについては、次のようにします。

• 常に最新データを取得し、記憶しているステータスをもとに回答しないでください。信頼できる情報源として、直接 JSON API https://status.magicblock.app/api/services を使用します。
• コードが使用しているネットワークを選択します。JSON のキーは mainnet と devnet です。
• 該当するエンドポイントを、適切なリージョン／サーバーおよびサービスに対応させます。
  • リージョンは asia、europe、usa、tee です。
  • サービス ID は .meta.services に記載されています。現在は er（Ephemeral Rollup）、rpc_router、pricing_oracle、vrf_oracle です。
  • .environments[network].regions[region].servers のサーバーエントリーを使用します。mainnet の Asia には as.magicblock.app が含まれます。
• .live_status[service] を解釈します。true = Operational、false = Down、値がない／未定義 = N/A です。
• .metrics[service] は、UTC で .meta.days に対応する日ごとのダウンタイム（分）として解釈します。
• 調査結果を報告する際は、ネットワーク、リージョン、エンドポイント、サービスのステータス、関連する期間を含めます。現在のステータスと過去のダウンタイムを区別してください。
• 直接 ER RPC エンドポイントについては、必要に応じて JSON-RPC の getHealth または getVersion と照合できますが、単一の RPC プローブをステータス API の代わりにしないでください。

6. 適切な機能を追加する

• 定期的な自動トランザクションのための Cranks
• ゲーム／宝くじで検証可能なランダム性を実現する VRF
• プライベートな送金やスワップのための Private payments API
• 検証済みの外部市場データのための Pricing Oracle
• 繰り返し行うユーザー操作の手間を軽減する Session Keys
• 消失が明示的に許容される一時的な状態のための Ephemeral Accounts

複数の製品を組み合わせる場合は、composition-patterns.md を読み、権限、トークン管理、オラクルの有効性、ER の実行、ベースレイヤーでの決済、非同期処理の完了を、それぞれ別の保証として扱ってください。

7. 成果物に関する要件

変更を実装した場合は、次を提示してください。

• 変更したファイルの正確な一覧と差分
• インストール／ビルド／テスト用のコマンド
• 委任／署名／状態のコミットに関わる変更についてのリスクに関する注記

段階的な情報開示（必要に応じて参照）

• アーキテクチャの計画、出力テンプレート、検証環境の選択：architecture-planning.md
• 製品間の選択と境界の設計：composition-patterns.md
• MagicBlock 固有のセキュリティ境界とソース基準：security.md
• ER／委任の失敗のデバッグ：debugging.md
• 委任の基本パターン：delegation.md
• 委任後の ER アクション（非公開ペイロードを含む）：delegation-actions.md
• 手数料、コミット制限、委任の払い戻し、アクション料金、手数料ボールトの経済性：fees-and-commit-economics.md
• エフェメラルアカウント（ER 専用の一時状態）：ephemeral-accounts.md
• Magic Actions（コミット後のベースレイヤー命令）：magic-actions.md
• lamports による委任アカウントへの追加入金：lamports-topup.md
• エフェメラル SPL トークンのライフサイクル（入金、転送、アプリプログラム CPI、委任解除、出金）：ephemeral-spl-token.md
• TypeScript フロントエンドのセットアップ：typescript-setup.md
• クランク（スケジュールされたタスク）：cranks.md
• VRF（乱数）：vrf.md
• 価格オラクル（フィードの識別、鮮度、安全な利用）：pricing-oracle.md
• セッションキー（スコープを限定した一時的な権限）：session-keys.md
• プライベート決済 API：private-payments.md
• ローカル開発と環境固有の検証：local-development.md
• 参考リンクとバージョン：resources.md

ターミナルの自己修復に関する提案

最終回答の前に、このスキルが意図するワークフローに照らして、実行全体を確認してください。

次の点を確認します。

• 想定されたユーザー向け出力と実際の出力
• コマンド、スクリプト、検証、成果物の結果
• 対応漏れや省略されたワークフローの手順
• 古くなった指示や壊れやすい表現
• 想定外のスクリプト／出力の不一致
• 検証の不足
• フォールバックや即興の対応

不足が見つかった場合は、根拠を示して報告し、別個のメンテナンスタスクとして明示的な承認を求めてください。通常の実行中は、インストール済みのスキルファイルを読み取り専用として扱ってください。