SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsarcium

arcium

Data & analytics

View repository

Updated 10-15 19:57

About this skill

Arcium

Encrypted computation on Solana via MPC. Data stays encrypted during computation. Your confidential app — a Solana program + Arcis circuits (the Rust circuit framework) + an on-chain metadata account — is an MXE (MPC eXecution Environment). The arcium CLI (wraps Anchor) handles init, build, test, and deploy — use MCP for current flags and options.

Targets Arcium v0.11.x (Anchor 1.0.2, Solana 3.1.10 — unchanged from v0.10.x). Upgrading from v0.10.x? See the v0.10 → v0.11 migration guide — the one app-facing breaking change is queue_computation's new 7th arg callback_cu_limit: u32 (pass 0 for default). v0.11 also adds Arcis enums and Option<T> (additive; not usable as circuit input/output). Coming from v0.9.x? Do the v0.9 → v0.10 migration first (init_comp_def → init_computation_def, @coral-xyz/anchor → @anchor-lang/core, Box<…> on queue-side accounts).

MCP Tools: search_arcium_docs for discovery (returns page path), then query_docs_filesystem_arcium_docs with cat <path>.mdx for full-page reads (e.g., cat /developers/arcis/mental-model.mdx).

No MCP? Use the docs directly: docs.arcium.com/llms.txt for the page index, or llms-full.txt for all docs in one file.

When to Use

Use when:

  • You need trustless computation -- cryptographically guaranteed, no single party sees the data
  • Multiple parties compute on combined data without revealing inputs
  • On-chain state must remain encrypted but computable
  • Privacy: sealed-bid auctions, voting, hidden game state, dark pools, confidential DeFi

Constraints:

  • Fixed loop bounds required (no variable-length iteration)

Mental Model

Arcium apps have three coupled surfaces. Most bugs are mismatches across their boundaries:

Surface Responsibility Common Boundary Bugs
Circuit (Arcis/Rust) Pure fixed-shape MPC logic Variable loops, dynamic collections, .reveal() inside conditionals
Program (Anchor/Rust) Orchestration: init + queue + callback Macro name mismatch, callback accounts not writable, wrong ArgBuilder order
Client (TypeScript) Key exchange, encryption, submission, decryption Nonce reuse, missing .x25519_pubkey() for Shared, param order ≠ circuit order

MPC constraints (from how secret sharing works):

  • Both branches of if/else execute unless the condition is a compile-time constant — cost = sum of both branches, not max. Same rule applies to non-constant match arms and if let — all reachable arms execute.
  • Loops must have fixed bounds — no while, break, continue
  • Comparisons are expensive; arithmetic (add/multiply) is nearly free
  • .reveal() and .from_arcis() cannot be called inside conditionals (exception: compile-time constant conditions; also forbidden inside non-constant match arms and guards)
  • All data must be fixed-size — no Vec, String, HashMap; use [T; N]
  • Pattern matching (match, if let, matches!) is supported in v0.10+. Last match arms cannot have guards. Let chains require edition = "2024" in encrypted-ixs/Cargo.toml.
  • Enums and Option<T> are supported in v0.11+ (full Option combinator surface — .unwrap_or, .map, .and_then, etc.). Two constraints: neither can be a circuit input or output, and enum discriminants cannot be set explicitly.

Intent Router

Identify what you're building, then read the linked reference before coding. For API details, CLI flags, deployment, and versions, use MCP directly.

Intent Read MCP Query
First Arcium app minimal-circuit.md "hello world tutorial"
Core concepts / terminology (MXE, Arx, comp def) core-concepts "arcium core concepts"
Choose a pattern (stateless, stateful, multi-party) patterns.md "arcium examples"
Circuit syntax (#[encrypted], #[instruction]) patterns.md "arcis encrypted instruction"
Shared vs Mxe encryption See Encryption Context below "Shared vs Mxe encryption"
ArgBuilder ordering / ciphertext errors troubleshooting.md -- ArgBuilder Ordering Errors "ArgBuilder encrypted plaintext"
Callback not firing / computation stuck troubleshooting.md -- Computation Never Finalizes "arcium_callback queue_computation"
Nonce / decryption errors troubleshooting.md -- Nonce Errors "RescueCipher encrypt nonce"
Client-side encryption (RescueCipher, x25519) minimal-circuit.md -- Test section "RescueCipher encrypt nonce"
Threshold signing / secure randomness patterns.md "MXESigningKey sign" or "ArcisRNG"
Re-encryption / sealing patterns.md "arcium sealing re-encryption"
Deployment (devnet/mainnet) — "arcium deploy cluster-offset"
CI / GitHub Actions setup-arcium "arcium github actions ci"
Version / installation requirements installation docs "arcium installation anchor solana"
Upgrading to v0.11.x (callback_cu_limit, enums/Option) migration guide "v0.11 migration"
Closing MXE / comp def to reclaim rent — "deactivate close computation definition"

Core Pattern: Three Functions

Every computation needs three functions in your Solana program:

Function Purpose When Called
init_<name>_comp_def Init computation definition — on-chain account holding the circuit's compiled bytecode Once per instruction
<name> Build args + queue computation Each request
<name>_callback Handle result from Arx nodes (the cluster's MPC compute nodes) After MPC completes 
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...
}

Encryption size: RescueCipher encrypts any scalar to 32 bytes regardless of type. Formula: ciphertext_size = 32 * number_of_scalar_values. See troubleshooting.md for the full size table.

Encryption Context

Enc<Owner, T> — Owner is who can decrypt. Choose before writing the circuit.

Scenario Use
User submits input / result sealed back to that same user Enc<Shared, T>
Internal state users shouldn't access Enc<Mxe, T>
State persisted across computations (re-read by any party) Enc<Mxe, T>
Result revealed to everyone .reveal()

Wrong owner fails quietly: persisted/multi-party state must be Mxe — Shared grants reveal capability to one client's x25519 key, leaking aggregate state to that recipient. If a different client key/nonce is used later, decryption yields garbage (MPC cannot raise a decrypt error without leaking). Shared also seals to one recipient; for a public result use .reveal(), not Shared. (Omitting .x25519_pubkey() on a Shared input is the same silent-failure class — see Gotchas.)

Gotchas

Reference during development to avoid common mistakes.

NEVER:

  • NEVER reuse a nonce — every cipher.encrypt() call needs a fresh randomBytes(16)
  • NEVER combine multiple ciphertexts into one ArgBuilder call — each encrypted scalar is its own [u8; 32] call
  • NEVER omit .x25519_pubkey() for Enc<Shared, T> (silent failure); Enc<Mxe, T> skips it

Critical (silent failures)

  • Box-wrap queue-side Arcium accounts (v0.10+): In #[queue_computation_accounts], follow generated templates and wrap heavy accounts: Box<Account<'info, MXEAccount>>, Box<Account<'info, Cluster>>, Box<Account<'info, ComputationDefinitionAccount>>. Unboxed queue accounts can exceed Anchor/Solana stack limits. Callback-side (#[callback_accounts]) can stay unboxed.
  • Macro string matching: All macro strings must exactly match #[instruction] fn NAME across #[arcium_callback], comp_def_offset(), #[init_computation_definition_accounts], #[queue_computation_accounts], #[callback_accounts]
  • ArgBuilder ordering: Calls must match circuit parameter order left-to-right. For Enc<Shared, T>: .x25519_pubkey() then .plaintext_u128(nonce) then ciphertexts. For Enc<Mxe, T>: .plaintext_u128(nonce) then ciphertexts. Missing .x25519_pubkey() for Shared = silent failure.
  • Division by secret zero: Guard divisors with the safe divisor pattern -- both branches execute in MPC, so the division always runs. See patterns.md — Safe Division.
  • Combined ciphertext arrays: Each encrypted scalar needs a separate [u8; 32] ArgBuilder call — do NOT pass [u8; 64] for a two-scalar type. See troubleshooting.md — Ciphertext Size Mismatch.

Warning (wrong results)

  • Nonce reuse: Same nonce for multiple encryptions = garbled output. Use unique randomBytes(16) per encryption.
  • Callback account writability: Pass extra accounts via CallbackAccount { pubkey, is_writable: true } in callback_ix(..., &[...]). Also mark #[account(mut)] in callback struct. Accounts cannot be created or resized during callbacks.
  • Output struct naming: Circuit fn add_together generates AddTogetherOutput. Single returns use field_0 (a SharedEncryptedStruct<1> or MXEEncryptedStruct<1> with .ciphertexts and .nonce). Tuple returns nest field_0, field_1, etc.

Tips

  • Prefer arithmetic over comparisons (cheaper in MPC)
  • Comparisons/divisions are cheaper with narrower types (u64 vs u128); storage cost is identical

Debug Triage Order

Start here when a computation fails or returns wrong results.

When a computation fails, returns wrong results, or never finalizes — check in this order:

  1. Names match exactly — #[instruction] fn NAME must match across #[arcium_callback(encrypted_ix = "NAME")], comp_def_offset("NAME"), and all account macros
  2. Comp def initialized — init_*_comp_def must be called once before any computation
  3. ArgBuilder param order — calls must match circuit fn parameters left-to-right
  4. Shared params include pubkey — .x25519_pubkey() before .plaintext_u128(nonce) before ciphertexts (missing = silent failure)
  5. Nonce is unique — fresh randomBytes(16) per encryption, same nonce passed to program
  6. Callback registered and writable — callback_ix(...) passed in queue_computation call, accounts set in BOTH CallbackAccount { pubkey, is_writable: true } AND #[account(mut)] in callback struct
  7. Environment correct — cluster offset matches network, MXE public key available (retry with backoff), RPC endpoint reliable

For detailed error solutions: troubleshooting.md

Verification Checklist

Pre-deploy gate. Run through before deploying or submitting a PR.

Circuit:

  • arcium build compiles without errors
  • No break/continue/return/variable-length loops
  • #[instruction] fn names are consistent across all macros

Program:

  • init_*_comp_def called before first computation (once per instruction type)
  • Every circuit fn has init + invoke + callback instructions
  • #[arcium_callback(encrypted_ix = "...")] matches circuit fn name exactly
  • Extra callback accounts passed via CallbackAccount { pubkey, is_writable: true } AND #[account(mut)] in callback struct

Client:

  • Unique nonce per encryption (no reuse across calls)
  • ArgBuilder call order matches circuit fn parameter order left-to-right
  • .x25519_pubkey() included for every Enc<Shared, T> parameter
  • Cluster offset matches deployment environment

Deploy:

  • arcium test passes locally before deploy
  • RPC endpoint is reliable (not default Solana RPC)
  • CI pins setup-arcium and explicit Arcium/Anchor/Solana versions for reproducible toolchain installs

Resources