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:
- Names match exactly —
#[instruction] fn NAME must match across #[arcium_callback(encrypted_ix = "NAME")], comp_def_offset("NAME"), and all account macros
- Comp def initialized —
init_*_comp_def must be called once before any computation
- ArgBuilder param order — calls must match circuit fn parameters left-to-right
- Shared params include pubkey —
.x25519_pubkey() before .plaintext_u128(nonce) before ciphertexts (missing = silent failure)
- Nonce is unique — fresh
randomBytes(16) per encryption, same nonce passed to program
- 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
- 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:
Program:
Client:
Deploy:
Resources
1---2name: arcium3description: >4 Build and debug encrypted Solana applications with Arcium — data stays5 private during computation, no single party sees it. Use when writing Arcis6 circuits (#[encrypted], #[instruction]), wiring Anchor programs with7 init/queue_computation/callback flows, choosing Shared vs Mxe encrypted8 state, encrypting inputs with @arcium-hq/client (RescueCipher, x25519),9 or debugging ArgBuilder ordering, nonce, callback, or computation10 finalization failures. Covers dark pools, sealed-bid auctions, encrypted11 voting, hidden game state, confidential DeFi, secure randomness, and12 threshold signing. Also use for getting started with your first13 Arcium app.14license: MIT15compatibility: Bundled mcp.json configures the Arcium MCP server automatically.16metadata:17 source: https://skillmd.com/skills/sendaifun/arcium18 author: arcium-hq19 version: "2.1"20---2122# Arcium2324Encrypted 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.2526**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`).2728## When to Use2930**Use when:**31- You need trustless computation -- cryptographically guaranteed, no single party sees the data32- Multiple parties compute on combined data without revealing inputs33- On-chain state must remain encrypted but computable34- Privacy: sealed-bid auctions, voting, hidden game state, dark pools, confidential DeFi3536**Constraints:**37- Fixed loop bounds required (no variable-length iteration)3839## Mental Model4041Arcium apps have three coupled surfaces. Most bugs are mismatches across their boundaries:4243| Surface | Responsibility | Common Boundary Bugs |44|---------|---------------|----------------------|45| **Circuit** (Arcis/Rust) | Pure fixed-shape MPC logic | Variable loops, dynamic collections, `.reveal()` inside conditionals |46| **Program** (Anchor/Rust) | Orchestration: init + queue + callback | Macro name mismatch, callback accounts not writable, wrong ArgBuilder order |47| **Client** (TypeScript) | Key exchange, encryption, submission, decryption | Nonce reuse, missing `.x25519_pubkey()` for Shared, param order ≠ circuit order |4849**MPC constraints** (from how secret sharing works):50- Both branches of `if/else` execute unless the condition is a compile-time constant — cost = sum of both branches, not max51- Loops must have fixed bounds — no `while`, `break`, `continue`52- Comparisons are expensive; arithmetic (add/multiply) is nearly free53- `.reveal()` and `.from_arcis()` cannot be called inside conditionals (exception: compile-time constant conditions)54- All data must be fixed-size — no `Vec`, `String`, `HashMap`; use `[T; N]`5556## Intent Router5758Identify what you're building, then read the linked reference before coding. For API details, CLI flags, deployment, and versions, use MCP directly.5960| Intent | Read | MCP Query |61|--------|------|-----------|62| First Arcium app | [minimal-circuit.md](examples/minimal-circuit.md) | "hello world tutorial" |63| Choose a pattern (stateless, stateful, multi-party) | [patterns.md](examples/patterns.md) | "arcium examples" |64| Circuit syntax (`#[encrypted]`, `#[instruction]`) | [patterns.md](examples/patterns.md) | "arcis encrypted instruction" |65| Shared vs Mxe encryption | See [Encryption Context](#encryption-context) below | "Shared vs Mxe encryption" |66| ArgBuilder ordering / ciphertext errors | [troubleshooting.md -- ArgBuilder Ordering Errors](references/troubleshooting.md#argbuilder-ordering-errors) | "ArgBuilder encrypted plaintext" |67| Callback not firing / computation stuck | [troubleshooting.md -- Computation Never Finalizes](references/troubleshooting.md#computation-never-finalizes) | "arcium_callback queue_computation" |68| Nonce / decryption errors | [troubleshooting.md -- Nonce Errors](references/troubleshooting.md#nonce-errors) | "RescueCipher encrypt nonce" |69| Client-side encryption (RescueCipher, x25519) | [minimal-circuit.md](examples/minimal-circuit.md) -- Test section | "RescueCipher encrypt nonce" |70| Threshold signing / secure randomness | — | "MXESigningKey sign" or "ArcisRNG" |71| Deployment (devnet/mainnet) | — | "arcium deploy cluster-offset" |72| Version / installation requirements | — | "arcium installation anchor solana" |7374## Core Pattern: Three Functions7576Every computation needs three functions in your Solana program:7778| Function | Purpose | When Called |79|----------|---------|-------------|80| `init_<name>_comp_def` | Initialize computation definition | Once per instruction |81| `<name>` | Build args + queue computation | Each request |82| `<name>_callback` | Handle result from Arx nodes | After MPC completes |8384```rust85const COMP_DEF_OFFSET_FLIP: u32 = comp_def_offset("flip");8687// 1. INIT (once per instruction type)88pub fn init_flip_comp_def(ctx: Context<InitFlipCompDef>) -> Result<()> {89 init_comp_def(ctx.accounts, None, None)90}9192// 2. QUEUE (each computation)93pub fn flip(ctx: Context<Flip>, offset: u64, ...) -> Result<()> {94 let args = ArgBuilder::new()...build();95 queue_computation(ctx.accounts, offset, args,96 vec![FlipCallback::callback_ix(offset, &ctx.accounts.mxe_account, &[])?],97 1, 0,98 )?;99 Ok(())100}101102// 3. CALLBACK (after MPC completes)103#[arcium_callback(encrypted_ix = "flip")]104pub fn flip_callback(ctx: Context<FlipCallback>,105 output: SignedComputationOutputs<FlipOutput>) -> Result<()> {106 let result = output.verify_output(...)?;107 // Use result...108}109```110111**Encryption size**: RescueCipher encrypts any scalar to 32 bytes regardless of type.112Formula: `ciphertext_size = 32 * number_of_scalar_values`. See [troubleshooting.md](references/troubleshooting.md) for the full size table.113114## Encryption Context115116| Scenario | Use |117|----------|-----|118| User inputs, results returned to user | `Enc<Shared, T>` |119| Internal state users shouldn't access | `Enc<Mxe, T>` |120| State persisted across computations | `Enc<Mxe, T>` |121| Final reveal to all parties | `.reveal()` |122123## Gotchas124125> Reference during development to avoid common mistakes.126127**NEVER:**128- NEVER reuse a nonce — every `cipher.encrypt()` call needs a fresh `randomBytes(16)`129- NEVER combine multiple ciphertexts into one ArgBuilder call — each encrypted scalar is its own `[u8; 32]` call130- NEVER omit `.x25519_pubkey()` for `Enc<Shared, T>` (silent failure); `Enc<Mxe, T>` skips it131132### Critical (silent failures)133- **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]`134- **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.135- **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](examples/patterns.md).136- **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](references/troubleshooting.md#ciphertext-size-mismatch).137138### Warning (wrong results)139- **Nonce reuse**: Same nonce for multiple encryptions = garbled output. Use unique `randomBytes(16)` per encryption.140- **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.141- **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.142143### Tips144- Prefer arithmetic over comparisons (cheaper in MPC)145- Comparisons/divisions are cheaper with narrower types (`u64` vs `u128`); storage cost is identical146147## Debug Triage Order148149> Start here when a computation fails or returns wrong results.150151When a computation fails, returns wrong results, or never finalizes — check in this order:1521531. **Names match exactly** — `#[instruction] fn NAME` must match across `#[arcium_callback(encrypted_ix = "NAME")]`, `comp_def_offset("NAME")`, and all account macros1542. **Comp def initialized** — `init_*_comp_def` must be called once before any computation1553. **ArgBuilder param order** — calls must match circuit fn parameters left-to-right1564. **Shared params include pubkey** — `.x25519_pubkey()` before `.plaintext_u128(nonce)` before ciphertexts (missing = silent failure)1575. **Nonce is unique** — fresh `randomBytes(16)` per encryption, same nonce passed to program1586. **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 struct1597. **Environment correct** — cluster offset matches network, MXE public key available (retry with backoff), RPC endpoint reliable160161For detailed error solutions: [troubleshooting.md](references/troubleshooting.md)162163## Verification Checklist164165> Pre-deploy gate. Run through before deploying or submitting a PR.166167**Circuit:**168- [ ] `arcium build` compiles without errors169- [ ] No `break`/`continue`/`return`/variable-length loops170- [ ] `#[instruction]` fn names are consistent across all macros171172**Program:**173- [ ] `init_*_comp_def` called before first computation (once per instruction type)174- [ ] Every circuit fn has init + invoke + callback instructions175- [ ] `#[arcium_callback(encrypted_ix = "...")]` matches circuit fn name exactly176- [ ] Extra callback accounts passed via `CallbackAccount { pubkey, is_writable: true }` AND `#[account(mut)]` in callback struct177178**Client:**179- [ ] Unique nonce per encryption (no reuse across calls)180- [ ] ArgBuilder call order matches circuit fn parameter order left-to-right181- [ ] `.x25519_pubkey()` included for every `Enc<Shared, T>` parameter182- [ ] Cluster offset matches deployment environment183184**Deploy:**185- [ ] `arcium test` passes locally before deploy186- [ ] RPC endpoint is reliable (not default Solana RPC)187188## Resources189190- **MCP tools** (primary for API details, CLI flags, deployment, versions): `search_arcium_docs` + `query_docs_filesystem_arcium_docs` — [docs.arcium.com/mcp](https://docs.arcium.com/mcp)191- **Docs**: [docs.arcium.com/developers](https://docs.arcium.com/developers/)192- **Examples**: [github.com/arcium-hq/examples](https://github.com/arcium-hq/examples)193- **TypeScript SDK**: [ts.arcium.com/api](https://ts.arcium.com/api)194- **Patterns**: [patterns.md](examples/patterns.md) — 15 curated circuit patterns195- **Troubleshooting**: [troubleshooting.md](references/troubleshooting.md) — hard-to-debug errors196- **Minimal working app**: [minimal-circuit.md](examples/minimal-circuit.md) — circuit + program + test