arcium

Arcium

MPC による Solana 上の暗号化計算です。計算中もデータは暗号化されたままです。機密性の高いアプリは、Solana プログラム、Arcis 回路（Rust の回路フレームワーク）、オンチェーンメタデータアカウントで構成され、MXE（MPC 実行環境）となります。arcium CLI（Anchor をラップしたもの）が初期化、ビルド、テスト、デプロイを処理します。最新のフラグやオプションは MCP で確認してください。

Arcium v0.11.x が対象です（Anchor 1.0.2、Solana 3.1.10 — v0.10.x から変更はありません）。v0.10.x からアップグレードしますか？v0.10 → v0.11 移行ガイドをご覧ください。アプリに影響する唯一の破壊的変更は、queue_computation の7番目の引数 callback_cu_limit: u32 が新設されたことです（デフォルト値を使用するには 0 を渡します）。v0.11 では Arcis の列挙型と Option<T> も追加されています（後方互換性のある追加機能ですが、回路の入力／出力には使用できません）。v0.9.x から移行しますか？先に v0.9 → v0.10 移行を行ってください（init_comp_def → init_computation_def、@coral-xyz/anchor → @anchor-lang/core、キュー側アカウントでの Box<…>）。

MCP ツール：探索には search_arcium_docs を使用します（ページパスが返されます）。ページ全体を読むには、続けて query_docs_filesystem_arcium_docs に cat <path>.mdx を指定します（例：cat /developers/arcis/mental-model.mdx）。

MCP がない場合：ドキュメントを直接参照してください。ページのインデックスは docs.arcium.com/llms.txt、すべてのドキュメントをまとめたファイルは llms-full.txt です。

使用する場面

次の場合に使用します：

• 信頼不要の計算が必要な場合 — 暗号学的に保証され、単独の当事者がデータを見ることはありません
• 複数の当事者が、入力を明かさずにデータを組み合わせて計算する場合
• オンチェーン状態を暗号化したまま計算可能にする必要がある場合
• プライバシーが必要な用途：封印入札オークション、投票、非公開のゲーム状態、ダークプール、機密性の高い DeFi

制約：

• ループの境界は固定する必要があります（可変長の反復は不可）

メンタルモデル

Arcium アプリには、相互に連携する3つの層があります。ほとんどのバグは、層の境界における不整合が原因です。

層	責務	よくある境界のバグ
回路（Arcis/Rust）	固定形状の純粋な MPC ロジック	可変ループ、動的コレクション、条件分岐内の .reveal()
プログラム（Anchor/Rust）	オーケストレーション：初期化 + キューへの追加 + コールバック	マクロ名の不一致、書き込み可能でないコールバックアカウント、ArgBuilder の順序違い
クライアント（TypeScript）	鍵交換、暗号化、送信、復号	ノンスの再利用、Shared での .x25519_pubkey() の指定漏れ、パラメーターの順序と回路の順序の不一致

MPC の制約（秘密分散の仕組みによるもの）：

• 条件がコンパイル時定数でない限り、if/else の両方の分岐が実行されます。コストは大きいほうではなく、両方の分岐の合計です。同じ規則は、定数でない match の各アームと if let にも適用されます — 到達可能なアームはすべて実行されます。
• ループの境界は固定する必要があります — while、break、continue は使用できません
• 比較は高コストですが、算術演算（加算／乗算）はほぼ無料です
• .reveal() と .from_arcis() は条件分岐内で呼び出せません（コンパイル時定数の条件を除く。また、定数でない match のアームとガード内でも禁止されています）
• すべてのデータは固定サイズである必要があります — Vec、String、HashMap は使用できません。[T; N] を使用してください
• パターンマッチング（match、if let、matches!）は v0.10 以降でサポートされています。最後の match アームにはガードを指定できません。let チェーンを使用するには、encrypted-ixs/Cargo.toml で edition = "2024" を設定する必要があります。
• 列挙型と Option<T> は v0.11 以降でサポートされています（.unwrap_or、.map、.and_then など、Option のコンビネーター全般を使用できます）。制約は2つあります。どちらも回路の入力や出力にはできず、列挙型の判別値を明示的に設定できません。

インテントルーター

何を構築するのかを特定し、コーディングを始める前にリンク先のリファレンスを読んでください。API の詳細、CLI フラグ、デプロイ、バージョンについては、MCP を直接使用してください。

インテント	読むもの	MCP クエリ
初めての Arcium アプリ	minimal-circuit.md	"hello world tutorial"
コアコンセプト／用語（MXE、Arx、comp def）	core-concepts	"arcium core concepts"
パターンの選択（ステートレス、ステートフル、マルチパーティ）	patterns.md	"arcium examples"
回路構文（#[encrypted]、#[instruction]）	patterns.md	"arcis encrypted instruction"
Shared と Mxe の暗号化	以下の暗号化コンテキストを参照	"Shared vs Mxe encryption"
ArgBuilder の順序／暗号文エラー	troubleshooting.md -- ArgBuilder Ordering Errors	"ArgBuilder encrypted plaintext"
コールバックが実行されない／計算が停止する	troubleshooting.md -- Computation Never Finalizes	"arcium_callback queue_computation"
ノンス／復号エラー	troubleshooting.md -- Nonce Errors	"RescueCipher encrypt nonce"
クライアント側の暗号化（RescueCipher、x25519）	minimal-circuit.md -- テストセクション	"RescueCipher encrypt nonce"
しきい値署名／安全な乱数	patterns.md	"MXESigningKey sign" または "ArcisRNG"
再暗号化／シーリング	patterns.md	"arcium sealing re-encryption"
デプロイ（devnet/mainnet）	—	"arcium deploy cluster-offset"
CI／GitHub Actions	setup-arcium	"arcium github actions ci"
バージョン／インストール要件	インストールのドキュメント	"arcium installation anchor solana"
v0.11.x へのアップグレード（callback_cu_limit、列挙型／Option）	移行ガイド	"v0.11 migration"
MXE／comp def を閉じてレントを回収する	—	"deactivate close computation definition"

コアパターン：3 つの関数

すべての計算で、Solana プログラムに次の 3 つの関数が必要です。

関数	目的	呼び出されるタイミング
init_<name>_comp_def	計算定義を初期化します — 回路のコンパイル済みバイトコードを保持するオンチェーンアカウントです	命令ごとに 1 回
<name>	引数を構築し、計算をキューに追加します	リクエストごと
<name>_callback	Arx ノード（クラスターの MPC 計算ノード）からの結果を処理します	MPC の完了後

const COMP_DEF_OFFSET_FLIP: u32 = comp_def_offset("flip");

// 1. INIT (once per instruction type) — v0.10+ helper is `init_computation_def` (2 args)
pub fn init_flip_comp_def(ctx: Context<InitFlipCompDef>) -> Result<()> {
    init_computation_def(ctx.accounts, None)
}

// 2. QUEUE (each computation)
pub fn flip(ctx: Context<Flip>, offset: u64, ...) -> Result<()> {
    let args = ArgBuilder::new()...build();
    queue_computation(ctx.accounts, offset, args,
        vec![FlipCallback::callback_ix(offset, &ctx.accounts.mxe_account, &[])?],
        1, 0, 0, // num_callback_txs, cu_price_micro, callback_cu_limit (v0.11: 7th arg, 0 = default)
    )?;
    Ok(())
}

// 3. CALLBACK (after MPC completes)
#[arcium_callback(encrypted_ix = "flip")]
pub fn flip_callback(ctx: Context<FlipCallback>,
    output: SignedComputationOutputs<FlipOutput>) -> Result<()> {
    let result = output.verify_output(...)?;
    // Use result...
}

暗号化サイズ：RescueCipher は型にかかわらず、任意のスカラーを 32 バイトに暗号化します。 式：ciphertext_size = 32 * number_of_scalar_values。サイズの一覧はtroubleshooting.mdを参照してください。

暗号化コンテキスト

Enc<Owner, T> — Owner は復号できるユーザーです。回路を書く前に選択してください。

シナリオ	使用するもの
ユーザーが入力を送信する／結果を同じユーザーにシールして返す	Enc<Shared, T>
ユーザーがアクセスすべきでない内部状態	Enc<Mxe, T>
計算をまたいで永続化される状態（任意の当事者が再読み込みする）	Enc<Mxe, T>
結果を全員に公開する	.reveal()

**所有者を誤ると、エラーが通知されずに失敗します：**永続化される状態やマルチパーティ状態には Mxe が必要です。Shared は 1 つのクライアントの x25519 キーに公開能力を与え、集約された状態をその受信者に漏えいさせます。後で別のクライアントキー／ノンスを使うと、復号結果は意味のないデータになります（情報漏えいを避けるため、MPC は復号エラーを通知できません）。また、Shared は1 人の受信者にのみシールします。公開結果には Shared ではなく .reveal() を使用してください。（Shared 入力で .x25519_pubkey() を省略した場合も、同じくエラーが通知されずに失敗します — 「注意事項」を参照してください。）

注意点

開発中に参照して、よくあるミスを避けてください。

絶対にしないでください：

• nonce を再利用しないでください。cipher.encrypt() を呼び出すたびに、新しい randomBytes(16) が必要です。
• 複数の暗号文を1回の ArgBuilder 呼び出しにまとめないでください。暗号化された各スカラーは、それぞれ個別の [u8; 32] 呼び出しにします。
• Enc<Shared, T> では .x25519_pubkey() を省略しないでください（無言で失敗します）。Enc<Mxe, T> では不要です。

重大（無言で失敗）

• キュー側の Arcium アカウントを Box でラップする（v0.10 以降）：#[queue_computation_accounts] では、生成されたテンプレートに従い、サイズの大きいアカウントをラップしてください：Box<Account<'info, MXEAccount>>、Box<Account<'info, Cluster>>、Box<Account<'info, ComputationDefinitionAccount>>。キューアカウントを Box でラップしないと、Anchor/Solana のスタック制限を超える可能性があります。コールバック側（#[callback_accounts]）は Box でラップしなくてもかまいません。
• マクロ文字列の一致：すべてのマクロ文字列は、#[arcium_callback]、comp_def_offset()、#[init_computation_definition_accounts]、#[queue_computation_accounts]、#[callback_accounts] にある #[instruction] fn NAME と完全に一致させてください。
• ArgBuilder の順序：呼び出し順は、回路のパラメーター順に左から一致させてください。Enc<Shared, T> の場合は、.x25519_pubkey()、次に .plaintext_u128(nonce)、その後に暗号文です。Enc<Mxe, T> の場合は、.plaintext_u128(nonce)、その後に暗号文です。Shared で .x25519_pubkey() を省略すると、無言で失敗します。
• 秘密の値がゼロの場合の除算：安全な除数のパターンを使って除数をチェックしてください。MPC では両方の分岐が実行されるため、除算は必ず実行されます。patterns.md — Safe Division を参照してください。
• 暗号文配列の結合：暗号化された各スカラーには、個別の [u8; 32] ArgBuilder 呼び出しが必要です。2つのスカラーを持つ型に [u8; 64] を渡さないでください。troubleshooting.md — Ciphertext Size Mismatch を参照してください。

警告（誤った結果）

• nonce の再利用：複数の暗号化に同じ nonce を使うと、出力が乱れます。暗号化ごとに固有の randomBytes(16) を使ってください。
• コールバックアカウントの書き込み可能設定：追加のアカウントは、callback_ix(..., &[...]) 内で CallbackAccount { pubkey, is_writable: true } を使って渡してください。また、コールバック構造体で #[account(mut)] を指定してください。コールバック中にアカウントを作成したり、サイズを変更したりすることはできません。
• 出力構造体の命名：回路の fn add_together は AddTogetherOutput を生成します。単一の戻り値では field_0 が使われます（.ciphertexts と .nonce を持つ SharedEncryptedStruct<1> または MXEEncryptedStruct<1>）。タプルの戻り値では field_0、field_1 などがネストされます。

ヒント

• MPC では、比較より算術演算を優先してください（より低コストです）。
• 比較や除算は、型が狭いほど低コストです（u128 より u64）。ストレージコストは同じです。

デバッグの切り分け順

計算が失敗したり、誤った結果を返したりした場合は、ここから確認してください。

計算が失敗する、誤った結果を返す、または完了しない場合は、次の順序で確認してください。

1. 名前が完全に一致している — #[instruction] fn NAME は、#[arcium_callback(encrypted_ix = "NAME")]、comp_def_offset("NAME")、およびすべてのアカウントマクロで一致している必要があります。
2. Comp def が初期化されている — どの計算よりも前に、init_*_comp_def を1回呼び出す必要があります。
3. ArgBuilder のパラメーター順 — 呼び出し順は、回路関数のパラメーター順に左から一致している必要があります。
4. Shared パラメーターに公開鍵が含まれている — 暗号文の前に .x25519_pubkey()、次に .plaintext_u128(nonce) を指定します（省略すると無言で失敗します）。
5. nonce が一意である — 暗号化ごとに新しい randomBytes(16) を使い、同じ nonce をプログラムに渡してください。
6. コールバックが登録され、書き込み可能である — queue_computation 呼び出しに callback_ix(...) が渡されていることを確認し、アカウントが CallbackAccount { pubkey, is_writable: true } とコールバック構造体の #[account(mut)] の両方で設定されていることを確認してください。
7. 環境が正しい — クラスターオフセットがネットワークと一致していること、MXE 公開鍵が利用可能であること（バックオフして再試行）、RPC エンドポイントが安定していることを確認してください。

エラーの詳しい解決方法については、troubleshooting.md を参照してください。

検証チェックリスト

デプロイ前の確認事項です。デプロイまたは PR の提出前に確認してください。

回路：

• arcium build がエラーなしでコンパイルできる
• break／continue／return／可変長ループがない
• #[instruction] の関数名がすべてのマクロ間で一致している

プログラム：

• 最初の計算の前に init_*_comp_def が呼び出されている（命令の種類ごとに1回）
• すべての回路関数に init、invoke、callback の命令がある
• #[arcium_callback(encrypted_ix = "...")] が回路関数名と完全に一致している
• 追加のコールバックアカウントが CallbackAccount { pubkey, is_writable: true } で渡され、コールバック構造体で #[account(mut)] が指定されている

クライアント：

• 暗号化ごとに一意の nonce を使用している（呼び出し間で再利用しない）
• ArgBuilder の呼び出し順序が、回路関数の左から右へのパラメーター順と一致している
• すべての Enc<Shared, T> パラメーターに .x25519_pubkey() が含まれている
• クラスターオフセットがデプロイ環境と一致している

デプロイ：

• デプロイ前にローカルで arcium test が成功する
• RPC エンドポイントが安定している（デフォルトの Solana RPC ではない）
• 再現可能なツールチェーンのインストールのため、CI で setup-arcium と Arcium／Anchor／Solana のバージョンを明示的に固定している

リソース

• MCP ツール（API の詳細、CLI フラグ、デプロイ、バージョンの確認に最適）：search_arcium_docs + query_docs_filesystem_arcium_docs — docs.arcium.com/mcp
• ドキュメント：docs.arcium.com/developers — MCP を利用できない場合：llms.txt（インデックス）、llms-full.txt（全文）
• v0.10 → v0.11 の移行：移行ガイド — queue_computation の第7引数 callback_cu_limit、Arcis の列挙型と Option<T>
• アカウントのライフサイクル／クローズ：account-lifecycle — deactivate-computation-definition → TTL（180スロット）→ close-computation-definition／close-mxe
• サンプル：github.com/arcium-hq/examples
• CI／GitHub Actions：github.com/arcium-hq/setup-arcium — CI のツールチェーンをインストールする GitHub Action。デフォルトに依存せず、v0.11.x 用の Arcium／Anchor／Solana のバージョンを明示的に設定してください
• TypeScript SDK：@arcium-hq/client + @arcium-hq/reader（計算イベントを購読） — ts.arcium.com/api
• パターン：patterns.md — 回路パターン集（ステートレス、ステートフル、マルチパーティ、乱数、パッキング、しきい値署名、シーリング）
• トラブルシューティング：troubleshooting.md — 原因を特定しにくいエラー
• 最小構成の動作するアプリ：minimal-circuit.md — 回路 + プログラム + テスト