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.

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 - we strongly recommend getting a free API key from Helius, or QuickNode

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 aren’t super efficient with their encoding, which means your circuit files can easily be several MBs in size. That makes initializing computation definitions on-chain 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, true, 0, None, None)?;
    Ok(())
}

Offchain approach (recommended for larger circuits):

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

pub fn init_add_together_comp_def(ctx: Context<InitAddTogetherCompDef>) -> Result<()> {
    // Point to your uploaded circuit file
    init_comp_def(
        ctx.accounts,
        true,
        0,
        Some(CircuitSource::OffChain(OffChainCircuitSource {
            source: "https://your-storage.com/path/to/add_together_testnet.arcis".to_string(),
            hash: [0; 32], // Just use zeros for now - hash verification isn't enforced yet
        })),
        None,
    )?;
    Ok(())
}

With the offchain approach, you’ll:

Build your project with arcium build to generate the circuit files
Upload the files from build/ folder to your preferred storage service (files include network suffix, e.g., add_together_testnet.arcis for testnet)
Update your init functions in the Solana program with the public URLs
Run arcium build again to rebuild the Solana program with your changes

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.arciumClusterPubkey in your test code. After deployment to devnet, you’ll need to update this to use the actual cluster pubkey - 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> --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. For devnet, you can choose from these offsets:

1078779259
3726127828
768109697

Each represents a different cluster on devnet. They all work the same way, so just pick one for your deployment.

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 1078779259 \
  --keypair-path ~/.config/solana/id.json \
  --rpc-url https://devnet.helius-rpc.com/?api-key=<your-api-key>

If you must use the default RPC:

arcium deploy --cluster-offset 1078779259 \
  --keypair-path ~/.config/solana/id.json \
  -u d  # 'd' for devnet, 't' for testnet, '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 1078779259 \
  --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 1078779259 \
  --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 1078779259 \
  --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 1078779259 \
  --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 on-chain 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 use the actual cluster pubkey instead of the local testing environment. Replace this (local testing):

const arciumEnv = getArciumEnv();

// Later in your transaction...
.accountsPartial({
    clusterAccount: arciumEnv.arciumClusterPubkey,
    // ... other accounts
})

With this (for devnet):

// Use the cluster offset from your deployment
const clusterAccount = getClusterAccAddress(cluster_offset); // e.g., getClusterAccAddress(1078779259)

// In your transaction...
.accountsPartial({
    clusterAccount: clusterAccount,
    // ... 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, false);

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 on devnet, you’ll need to update your test setup code to use devnet configuration instead of the local testing environment:

// Update your test setup to use devnet when needed
const useDevnet = true; // Set to false for local testing

if (useDevnet) {
  // Devnet configuration
  const connection = new anchor.web3.Connection(
    "https://api.devnet.solana.com", // or your preferred RPC
    "confirmed"
  );
  const wallet = new anchor.Wallet(owner);
  const provider = new anchor.AnchorProvider(connection, wallet, {
    commitment: "confirmed",
  });
  const program = new anchor.Program<YourProgram>(IDL as anchor.Idl, provider);
  const clusterAccount = getClusterAccAddress(1078779259); // Use your cluster offset
} else {
  // Local configuration
  anchor.setProvider(anchor.AnchorProvider.env());
  const provider = anchor.getProvider() as anchor.AnchorProvider;
  const program = anchor.workspace.YourProgram as Program<YourProgram>;
  const arciumEnv = getArciumEnv();
  const clusterAccount = arciumEnv.arciumClusterPubkey;
}

Then run your tests with:

arcium test

Common Issues and Solutions

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 https://devnet.helius-rpc.com/?api-key=<your-key>

Running Out of SOL

Check your balance before deploying:

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

Need more devnet SOL? Request an 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
Run end-to-end tests 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

​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

​Common Issues and Solutions

​Dealing with Dropped Transactions

​Running Out of SOL

​Deployment Partially Failed?

​What’s Next?