/arcium

name: arcium
description: >
  Build and debug encrypted Solana applications with Arcium — data stays
  private during computation, no single party sees it. Use when writing Arcis
  circuits (#[encrypted], #[instruction]), wiring Anchor programs with
  init/queue_computation/callback flows, choosing Shared vs Mxe encrypted
  state, encrypting inputs with @arcium-hq/client (RescueCipher, x25519),
  or debugging ArgBuilder ordering, nonce, callback, or computation
  finalization failures. Covers dark pools, sealed-bid auctions, encrypted
  voting, hidden game state, confidential DeFi, secure randomness, and
  threshold signing. Also use for getting started with your first
  Arcium app.
license: MIT
compatibility: Bundled mcp.json configures the Arcium MCP server automatically.
metadata:
  author: arcium-hq
  version: "2.1"

Arcium

Encrypted computation on Solana via MPC. Data stays encrypted during computation. The `arcium` CLI (wraps Anchor) handles init, build, test, and deploy — use MCP for current flags and options.

**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`).

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
• 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)
• All data must be fixed-size — no `Vec`, `String`, `HashMap`; use `[T; N]`

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](examples/minimal-circuit.md) | "hello world tutorial" | | Choose a pattern (stateless, stateful, multi-party) | [patterns.md](examples/patterns.md) | "arcium examples" | | Circuit syntax (`#[encrypted]`, `#[instruction]`) | [patterns.md](examples/patterns.md) | "arcis encrypted instruction" | | Shared vs Mxe encryption | See [Encryption Context](#encryption-context) below | "Shared vs Mxe encryption" | | ArgBuilder ordering / ciphertext errors | [troubleshooting.md -- ArgBuilder Ordering Errors](references/troubleshooting.md#argbuilder-ordering-errors) | "ArgBuilder encrypted plaintext" | | Callback not firing / computation stuck | [troubleshooting.md -- Computation Never Finalizes](references/troubleshooting.md#computation-never-finalizes) | "arcium_callback queue_computation" | | Nonce / decryption errors | [troubleshooting.md -- Nonce Errors](references/troubleshooting.md#nonce-errors) | "RescueCipher encrypt nonce" | | Client-side encryption (RescueCipher, x25519) | [minimal-circuit.md](examples/minimal-circuit.md) -- Test section | "RescueCipher encrypt nonce" | | Threshold signing / secure randomness | — | "MXESigningKey sign" or "ArcisRNG" | | Deployment (devnet/mainnet) | — | "arcium deploy cluster-offset" | | Version / installation requirements | — | "arcium installation anchor solana" |

Core Pattern: Three Functions

Every computation needs three functions in your Solana program:

| Function | Purpose | When Called | |----------|---------|-------------| | `init_<name>_comp_def` | Initialize computation definition | Once per instruction | | `<name>` | Build args + queue computation | Each request | | `<name>_callback` | Handle result from Arx nodes | After MPC completes |

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...
}

**Encryption size**: RescueCipher encrypts any scalar to 32 bytes regardless of type. Formula: `ciphertext_size = 32 * number_of_scalar_values`. See [troubleshooting.md](references/troubleshooting.md) for the full size table.

Encryption Context

| Scenario | Use | |----------|-----| | User inputs, results returned to user | `Enc<Shared, T>` | | Internal state users shouldn't acces