arcium

Arcium

MPC による Solana 上の暗号化計算です。計算中もデータは暗号化されたままです。arcium CLI（Anchor をラップ）は初期化、ビルド、テスト、デプロイを処理します。最新のフラグやオプションについては MCP を使用してください。

MCP ツール：search_arcium_docs で検索（ページパスを返します）し、その後 cat <path>.mdx を指定して query_docs_filesystem_arcium_docs を使い、ページ全体を読み取ります（例：cat /developers/arcis/mental-model.mdx）。

使用する場面

次の場合に使用します：

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

制約：

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

基本モデル

Arcium アプリには、相互に関連する3つの領域があります。バグの多くは、それぞれの境界での不整合に起因します。

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

MPC の制約（秘密分散の仕組みに由来）：

• コンパイル時定数でない限り、if/else の両方の分岐が実行されます。コストは両方の分岐の合計であり、大きい方ではありません
• ループの境界は固定する必要があります。while、break、continue は使用できません
• 比較は高コストですが、算術演算（加算／乗算）はほぼ無料です
• .reveal() と .from_arcis() は条件分岐内で呼び出せません（例外：コンパイル時定数の条件）
• すべてのデータは固定サイズである必要があります。Vec、String、HashMap は使用できません。[T; N] を使用してください

意図別ガイド

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

意図	読む資料	MCP クエリ
初めての Arcium アプリ	minimal-circuit.md	"hello world tutorial"
パターンを選ぶ（ステートレス、ステートフル、マルチパーティ）	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"
しきい値署名／セキュアな乱数	—	"MXESigningKey sign" または "ArcisRNG"
デプロイ（devnet/mainnet）	—	"arcium deploy cluster-offset"
バージョン／インストール要件	—	"arcium installation anchor solana"

基本パターン：3 つの関数

Solana プログラムで計算を行うには、次の 3 つの関数が必要です。

関数	目的	呼び出されるタイミング
init_<name>_comp_def	計算定義を初期化する	命令ごとに 1 回
<name>	引数を構築して計算をキューに追加する	リクエストごと
<name>_callback	Arx ノードからの結果を処理する	MPC 完了後

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

// 1. INIT (once per instruction type)
pub fn init_flip_comp_def(ctx: Context<InitFlipCompDef>) -> Result<()> {
    init_comp_def(ctx.accounts, None, 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,
    )?;
    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<Shared, T>
ユーザーがアクセスすべきでない内部状態	Enc<Mxe, T>
計算をまたいで保持される状態	Enc<Mxe, T>
すべての当事者への最終公開	.reveal()

注意事項

よくある間違いを避けるため、開発中に参照してください。

絶対に行わないでください：

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

重大（サイレント失敗）

• マクロ文字列の一致：すべてのマクロ文字列は、#[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 — 安全な除算を参照してください。
• 結合された暗号文配列：暗号化された各スカラーには、個別の [u8; 32] ArgBuilder 呼び出しが必要です。2 スカラーの型に対して [u8; 64] を渡してはいけません。troubleshooting.md — 暗号文サイズの不一致を参照してください。

警告（誤った結果）

• 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 を一度呼び出す必要があります
3. ArgBuilder のパラメーター順 — 呼び出しは、回路関数のパラメーターと左から右へ同じ順序である必要があります
4. 共有パラメーターに公開鍵が含まれている — .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 を呼び出している（命令タイプごとに一度）
• すべての回路関数に 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 ではない）

リソース

• MCP ツール（API の詳細、CLI フラグ、デプロイ、バージョンを確認する際の主な手段）: search_arcium_docs + query_docs_filesystem_arcium_docs — docs.arcium.com/mcp
• ドキュメント: docs.arcium.com/developers
• サンプル: github.com/arcium-hq/examples
• TypeScript SDK: ts.arcium.com/api
• パターン: patterns.md — 厳選された 15 種類の回路パターン
• トラブルシューティング: troubleshooting.md — デバッグが難しいエラー
• 最小構成の動作するアプリ: minimal-circuit.md — 回路、プログラム、テスト