Arcium

Encrypted computation on Solana via MPC. Data stays encrypted during computation. The

arcium

MCP Tools:

search_arcium_docs

query_docs_filesystem_arcium_docs

cat <path>.mdx

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:

.reveal()

.x25519_pubkey()

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.

#[encrypted]

#[instruction]

Core Pattern: Three Functions

Every computation needs three functions in your Solana program:

init_<name>_comp_def

<name>

<name>_callback

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

Encryption Context

Enc<Shared, T>

Enc<Mxe, T>

Enc<Mxe, T>

.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