arcium

Arcium

通过 MPC 在 Solana 上进行加密计算。计算过程中数据始终保持加密状态。arcium CLI（封装了 Anchor）负责处理初始化、构建、测试和部署——如需了解当前标志和选项，请使用 MCP。

MCP 工具：使用 search_arcium_docs 搜索内容（返回页面路径），然后使用 query_docs_filesystem_arcium_docs 和 cat <path>.mdx 读取完整页面（例如，cat /developers/arcis/mental-model.mdx）。

适用场景

适用于：

• 需要无须信任的计算——由密码学保证，没有任何一方能看到数据
• 多方基于组合后的数据进行计算，但不泄露各自的输入
• 链上状态必须保持加密，同时仍可参与计算
• 隐私场景：密封投标拍卖、投票、隐藏游戏状态、暗池、机密 DeFi

限制：

• 必须使用固定循环边界（不能进行可变长度迭代）

心智模型

Arcium 应用有三个相互耦合的层面。大多数 Bug 都是由它们的边界不匹配导致的：

层面	职责	常见边界 Bug
电路（Arcis/Rust）	纯粹的固定形状 MPC 逻辑	可变循环、动态集合、在条件语句中调用 .reveal()
程序（Anchor/Rust）	编排：初始化 + 排队 + 回调	宏名称不匹配、回调账户不可写、ArgBuilder 顺序错误
客户端（TypeScript）	密钥交换、加密、提交、解密	重用 nonce、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"
Nonce / 解密错误	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"

核心模式：三个函数

Solana 程序中的每项计算都需要三个函数：

函数	用途	调用时机
init_<name>_comp_def	初始化计算定义	每条指令执行一次
<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)
• 切勿在一次 ArgBuilder 调用中组合多个密文——每个加密标量都需要单独调用 [u8; 32]
• 对于 Enc<Shared, T>，切勿省略 .x25519_pubkey()（会静默失败）；Enc<Mxe, T> 无需调用

严重问题（会静默失败）

• 宏字符串匹配：所有宏字符串都必须与 #[instruction] fn NAME 完全匹配，包括 #[arcium_callback]、comp_def_offset()、#[init_computation_definition_accounts]、#[queue_computation_accounts]、#[callback_accounts]
• ArgBuilder 顺序：调用必须从左到右与电路参数顺序一致。对于 Enc<Shared, T>：先调用 .x25519_pubkey()，再调用 .plaintext_u128(nonce)，然后传入密文。对于 Enc<Mxe, T>：先调用 .plaintext_u128(nonce)，然后传入密文。对于 Shared，省略 .x25519_pubkey() 会导致静默失败。
• 除以秘密零值：使用安全除数模式保护除数——MPC 中两个分支都会执行，因此除法始终会运行。请参阅 patterns.md — 安全除法。
• 组合密文数组：每个加密标量都需要单独调用一次 [u8; 32] ArgBuilder——两个标量的类型切勿传入 [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 成本更低）
• 使用较窄的类型（u64 相比 u128）时，比较和除法成本更低；存储成本相同

调试排查顺序

计算失败或返回错误结果时，从这里开始。

计算失败、返回错误结果或始终无法完成时，请按以下顺序检查：

1. 名称完全匹配 — #[instruction] fn NAME 必须与 #[arcium_callback(encrypted_ix = "NAME")]、comp_def_offset("NAME") 以及所有账户宏中的名称一致
2. 已初始化计算定义 — 每次计算前必须调用一次 init_*_comp_def
3. ArgBuilder 参数顺序 — 调用顺序必须与电路 fn 参数从左到右的顺序一致
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] fn 名称一致

程序：

• 首次计算前调用 init_*_comp_def（每种指令类型调用一次）
• 每个电路 fn 都有 init、invoke 和 callback 指令
• #[arcium_callback(encrypted_ix = "...")] 与电路 fn 名称完全一致
• 额外的回调账户同时通过 CallbackAccount { pubkey, is_writable: true } 传入，并在回调结构体中使用 #[account(mut)]

客户端：

• 每次加密使用唯一 nonce（调用之间不重复使用）
• ArgBuilder 调用顺序与电路 fn 参数从左到右的顺序一致
• 每个 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 — 电路 + 程序 + 测试