Deployment - Arcium Docs

Getting Started with Deployment

So you’ve built and tested your MXE locally, and now you’re ready to deploy it to Solana devnet. This guide will walk you through the deployment process and share some tips to make it go smoothly.

This guide walks you through deploying to devnet first. Once you’ve validated your MXE on devnet, see Deploying to Mainnet for mainnet-specific configuration.

What You’ll Need

Before we dive into deployment, let’s make sure you have everything ready:

Your MXE built successfully with arcium build
Tests passing locally with arcium test
A Solana keypair with around 2-5 SOL for deployment costs (program deployment and account initialization)
Access to a reliable RPC endpoint

RPC reliability is critical for deployment. Default Solana RPC endpoints can be unreliable and drop transactions, causing deployment failures. Get an API key from Helius, Triton, or QuickNode before attempting deployment.

Preparing Your Program

Before you deploy, there are a couple of important things to consider about how your program handles computation definitions.

Handling Large Circuits with Offchain Storage

Here’s something important to know: right now, Arcis compiled circuits are not optimally efficient with their encoding, which means your circuit files can easily be several MBs in size. That makes initializing computation definitions onchain pretty expensive - and will require a lot of transactions to fully upload. The good news is you can store your circuits offchain instead. Just upload them to IPFS, a public S3 bucket, or even Supabase object storage - wherever works for you. Here’s how to update your program to use offchain storage: Standard approach (works for small circuits):

pub fn init_add_together_comp_def(ctx: Context<InitAddTogetherCompDef>) -> Result<()> {
    // This initializes the computation definition account
    init_comp_def(ctx.accounts, None, None)?;
    Ok(())
}

Offchain approach (recommended for larger circuits):

// First, import the types you'll need
use arcium_client::idl::arcium::types::{CircuitSource, OffChainCircuitSource};
use arcium_macros::circuit_hash;

pub fn init_add_together_comp_def(ctx: Context<InitAddTogetherCompDef>) -> Result<()> {
    // Point to your uploaded circuit file
    init_comp_def(
        ctx.accounts,
        Some(CircuitSource::OffChain(OffChainCircuitSource {
            source: "https://your-storage.com/path/to/add_together.arcis".to_string(),
            hash: circuit_hash!("add_together"),
        })),
        None,
    )?;
    Ok(())
}

The circuit_hash! macro embeds the SHA-256 hash of your compiled circuit at compile time. The hash is read from build/{circuit_name}.hash, which is generated automatically during arcium build. Arx nodes verify this hash when fetching your circuit to ensure the circuit hasn’t been tampered with.Important: Always use circuit_hash! for offchain circuits. Don’t use a placeholder like [0u8; 32] - this will cause verification to fail on Arx nodes.

With the offchain approach, you’ll:

Build your project with arcium build to generate the circuit files and hashes
Upload the .arcis files from build/ folder to your preferred storage service
Update your init functions with the public URLs and circuit_hash! macro calls

Note: Your circuit files must be publicly accessible without authentication. Make sure your storage service allows public read access. This saves a ton on transaction costs and lets you work with much larger circuits!

Note on Cluster Configuration

When testing locally, you’ve been using arciumEnv.arciumClusterOffset with getClusterAccAddress() in your test code. For devnet deployment, you’ll use the same pattern with your chosen cluster offset - we’ll show you exactly how in the post-deployment section.

Basic Deployment

The arcium deploy command handles both deploying your program and initializing the MXE account. Here’s the basic command structure:

arcium deploy --cluster-offset <cluster-offset> --recovery-set-size <size> --keypair-path <path-to-your-keypair> --rpc-url <your-rpc-url>

Let’s break down what each parameter does:

Understanding Cluster Offsets

The --cluster-offset tells your MXE which Arcium cluster it should connect to. Think of clusters as groups of nodes that will perform your encrypted computations. Available offsets: Devnet cluster:

456 - v0.8.3

Mainnet cluster:

2026

Recovery Set Size

The --recovery-set-size parameter specifies the number of nodes required for threshold cryptography recovery operations. This is a required parameter. The minimum value is 4.

Choosing Your RPC Provider

The --rpc-url parameter is particularly important. While you could use Solana’s default RPC endpoints with the shorthand notation (-u d for devnet), the default RPC can be unreliable and cause deployment failures due to dropped transactions. Recommended approach with a reliable RPC:

arcium deploy --cluster-offset 456 \
  --recovery-set-size 4 \
  --keypair-path ~/.config/solana/id.json \
  --rpc-url <your-devnet-rpc-url>

If you must use the default RPC:

arcium deploy --cluster-offset 456 \
  --recovery-set-size 4 \
  --keypair-path ~/.config/solana/id.json \
  -u d  # 'd' for devnet, 'm' for mainnet, 'l' for localnet

Just be prepared for potential transaction failures with the default RPC.

Advanced Deployment Options

Once you’re comfortable with basic deployment, you might want to customize things further.

Adjusting Mempool Size

The mempool determines how many computations your MXE can queue up. The default “Tiny” size works fine for testing, but you might want more capacity for production:

arcium deploy --cluster-offset 456 \
  --recovery-set-size 4 \
  --keypair-path ~/.config/solana/id.json \
  --rpc-url <your-rpc-url> \
  --mempool-size Medium

Available sizes are: Tiny, Small, Medium, Large. Start small and increase if you need more capacity.

Using a Custom Program Address

If you need your program at a specific address (maybe for consistency across deployments), you can provide a program keypair:

arcium deploy --cluster-offset 456 \
  --recovery-set-size 4 \
  --keypair-path ~/.config/solana/id.json \
  --rpc-url <your-rpc-url> \
  --program-keypair ./program-keypair.json

Partial Deployments

Sometimes you might need to run just part of the deployment process. For instance, if you’ve already deployed the program but need to reinitialize the MXE account:

# Skip program deployment, only initialize MXE account
arcium deploy --cluster-offset 456 \
  --recovery-set-size 4 \
  --keypair-path ~/.config/solana/id.json \
  --rpc-url <your-rpc-url> \
  --skip-deploy

Or if you only want to deploy the program without initialization:

# Deploy program only, skip MXE initialization
arcium deploy --cluster-offset 456 \
  --recovery-set-size 4 \
  --keypair-path ~/.config/solana/id.json \
  --rpc-url <your-rpc-url> \
  --skip-init

After Deployment

Initialize Your Computation Definitions

Your MXE is deployed, but you still need to initialize the computation definitions. This tells the Arcium network what encrypted operations your MXE can perform. Computation definitions only need to be initialized once - they persist onchain and don’t need to be re-initialized unless you’re deploying to a new program address. You can initialize them anytime after deployment completes successfully. Remember how we mentioned you’d need to update your cluster configuration? Now’s the time! You’ll need to update your test or client code to derive the cluster account (and the related PDAs) from the cluster offset you selected during deployment. Local testing pattern:

const arciumEnv = getArciumEnv();

// In your transaction...
.accountsPartial({
    computationAccount: getComputationAccAddress(
        arciumEnv.arciumClusterOffset,
        computationOffset
    ),
    clusterAccount: getClusterAccAddress(arciumEnv.arciumClusterOffset),
    mxeAccount: getMXEAccAddress(program.programId),
    mempoolAccount: getMempoolAccAddress(arciumEnv.arciumClusterOffset),
    executingPool: getExecutingPoolAccAddress(arciumEnv.arciumClusterOffset),
    // ... other accounts
})

For devnet deployment:

// Use the cluster offset from your deployment (e.g., 456)
const clusterOffset = 456;

// In your transaction...
.accountsPartial({
    computationAccount: getComputationAccAddress(clusterOffset, computationOffset),
    clusterAccount: getClusterAccAddress(clusterOffset),
    mxeAccount: getMXEAccAddress(program.programId),
    mempoolAccount: getMempoolAccAddress(clusterOffset),
    executingPool: getExecutingPoolAccAddress(clusterOffset),
    // ... other accounts
})

Make sure to use the same cluster_offset value that you used during deployment! This ensures your program talks to the right cluster. Once you’ve updated the cluster configuration, you can run the initialization:

// Now with the correct cluster configured
await initAddTogetherCompDef(program, owner);

Verify Everything’s Working

Let’s make sure your deployment succeeded:

solana program show <your-program-id> --url <your-rpc-url>

To run your tests against the deployed program, configure the cluster offset in your Arcium.toml:

[clusters.devnet]
offset = <your-cluster-offset>

Then run:

arcium test --cluster devnet

The CLI reads the cluster offset from Arcium.toml and configures the test environment automatically. For RPC configuration, set the cluster and wallet in your Anchor.toml:

[provider]
cluster = "devnet"
wallet = "~/.config/solana/id.json"

Deploying to Mainnet

Once you’ve validated your MXE on devnet, you can deploy to Arcium mainnet-alpha. The deployment process is the same, with a few key differences:

Mainnet Cluster Offset

Use the mainnet cluster offset from the Understanding Cluster Offsets section:

arcium deploy --cluster-offset <mainnet-cluster-offset> \
  --recovery-set-size 4 \
  --keypair-path ~/.config/solana/id.json \
  --rpc-url <your-mainnet-rpc-url>

Mainnet Configuration

Configure the mainnet cluster offset in your Arcium.toml (see Understanding Cluster Offsets for the current value):

[clusters.mainnet]
offset = <your-cluster-offset>

To test against your mainnet deployment:

arcium test --cluster mainnet

Mainnet deployments require real SOL — there are no airdrops. Ensure your wallet is funded before deploying.

Common Issues and Solutions

The examples below use devnet. For mainnet, replace -u d with -u m and use a mainnet RPC URL.

Dealing with Dropped Transactions

If your deployment fails with transaction errors, it’s almost always the RPC. Switch to a dedicated provider:

# Instead of this (unreliable):
arcium deploy ... -u d

# Use this (reliable):
arcium deploy ... --rpc-url <your-devnet-rpc-url>

Running Out of SOL

Check your balance before deploying:

solana balance <your-keypair-pubkey> -u devnet

If you need more SOL on devnet, request it via airdrop:

solana airdrop 2 <your-keypair-pubkey> -u devnet

Deployment Partially Failed?

No worries, you can complete the missing steps. If the program deployed but initialization failed, just run with --skip-deploy. If initialization succeeded but deployment failed, use --skip-init.

What’s Next?

With your MXE deployed, you’re ready to:

Update your client code to connect to the deployed program
Initialize all your computation definitions
Test with real encrypted computations
Monitor performance and adjust mempool size if needed

If you run into any issues or have questions, don’t hesitate to reach out on Discord!

​Getting Started with Deployment

​What You’ll Need

​Preparing Your Program

​Handling Large Circuits with Offchain Storage

​Note on Cluster Configuration

​Basic Deployment

​Understanding Cluster Offsets

​Recovery Set Size

​Choosing Your RPC Provider

​Advanced Deployment Options

​Adjusting Mempool Size

​Using a Custom Program Address

​Partial Deployments

​After Deployment

​Initialize Your Computation Definitions

​Verify Everything’s Working

​Deploying to Mainnet

​Mainnet Cluster Offset

​Mainnet Configuration

​Common Issues and Solutions

​Dealing with Dropped Transactions

​Running Out of SOL

​Deployment Partially Failed?

​What’s Next?

Getting Started with Deployment

What You’ll Need

Preparing Your Program

Handling Large Circuits with Offchain Storage

Note on Cluster Configuration

Basic Deployment

Understanding Cluster Offsets

Recovery Set Size

Choosing Your RPC Provider

Advanced Deployment Options

Adjusting Mempool Size

Using a Custom Program Address

Partial Deployments

After Deployment

Initialize Your Computation Definitions

Verify Everything’s Working

Deploying to Mainnet

Mainnet Cluster Offset

Mainnet Configuration

Common Issues and Solutions

Dealing with Dropped Transactions

Running Out of SOL

Deployment Partially Failed?

What’s Next?