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	"hello world tutorial"
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	—	"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 for the full size table.

Encryption Context

Scenario	Use
User inputs, results returned to user	Enc<Shared, T>
Internal state users shouldn't access	Enc<Mxe, T>
State persisted across computations	Enc<Mxe, T>
Final reveal to all parties	.reveal()

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)

• 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)

Resources

• MCP tools (primary for API details, CLI flags, deployment, versions): search_arcium_docs + query_docs_filesystem_arcium_docs — docs.arcium.com/mcp
• Docs: docs.arcium.com/developers
• Examples: github.com/arcium-hq/examples
• TypeScript SDK: ts.arcium.com/api
• Patterns: patterns.md — 15 curated circuit patterns
• Troubleshooting: troubleshooting.md — hard-to-debug errors
• Minimal working app: minimal-circuit.md — circuit + program + test