Deployment
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)
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 filesUpload 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:
1116522165
3458519414
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 1116522165 \
--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 1116522165 \
--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 1116522165 \
--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 1116522165 \
--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 1116522165 \
--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 1116522165 \
--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 = getClusterAcc(cluster_offset); // e.g., getClusterAcc(1116522165)
// 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>
Then run your tests against the deployed program:
arcium test --skip-local-validator --provider.cluster devnet
Note: This will use the RPC endpoint configured for devnet in your Anchor.toml file or environment settings.
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> --url devnet
Need more devnet SOL? Request an airdrop:
solana airdrop 2 <your-keypair-pubkey> --url 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!
Last updated