Skip to main content

​
Hello World

The Arcium tooling suite for writing MXEs (MPC eXecution Environments) is built on top of Anchor, so if you’re familiar with Anchor, you should find Arcium to be a familiar experience, except that you’re using the arcium CLI instead of anchor. To initialize a new MXE project, run: 
arcium init <project-name>
This will create a new project with the given name and initialize it with a basic structure. The structure is the same as in an Anchor project with two differences, so it is not repeated here (for an explanation of the Anchor project structure, see the Anchor documentation). The two differences are:
  • The Arcium.toml file, which contains the configuration for the Arcium tooling suite.
  • The encrypted-ixs directory. This is where we write all our code that is meant to operate on encrypted data and therefore runs in MPC. This code is written using our own Rust framework called Arcis. This will already be populated with a simple example called add_together.rs. Let’s take a closer look at it.

​
Our first encrypted instruction

use arcis::*;

#[encrypted]
mod circuits {
    use arcis::*;

    pub struct InputValues {
        v1: u8,
        v2: u8,
    }

    #[instruction]
    pub fn add_together(input_ctxt: Enc<Shared, InputValues>) -> Enc<Shared, u16> {
        let input = input_ctxt.to_arcis();
        let sum = input.v1 as u16 + input.v2 as u16;
        input_ctxt.owner.from_arcis(sum)
    }
}
Let’s go through it line by line. use arcis::*; imports all the necessary types and functions for writing encrypted instructions with Arcis. The #[encrypted] attribute marks a module that contains encrypted instructions. Inside this module, we define a struct InputValues that contains the two values we want to encrypt and pass to the encrypted instruction. The #[instruction] macro marks the function as an entry point for MPC execution. While you can write helper functions without this attribute, only functions marked with #[instruction] will be compiled into individual circuits that can be called onchain. The function add_together takes an encrypted input parameter of type Enc<Shared, InputValues>. Let’s break this down:
  • Enc<Owner, Data> is Arcium’s encrypted data type
  • Shared means the data is encrypted with a shared secret between the client and MXE (both can decrypt it)
  • InputValues is the actual data structure being encrypted (our struct with v1 and v2)
  • The alternative to Shared is Mxe, where only the MXE can decrypt the data
Inside the function:
  1. input_ctxt.to_arcis() converts the input into a form we can operate on within the MPC environment.
  2. We perform the addition operation, casting the u8 values to u16 to prevent overflow.
  3. input_ctxt.owner.from_arcis(sum) converts the encrypted sum into an encrypted format that can be stored onchain, while maintaining encryption with the shared secret between the client and the MXE.

​
Calling it from Solana

Now that we’ve written our first encrypted instruction, let’s see how we can use it from within a Solana program. Our default project already contains a Solana program in the programs/ directory. Let’s take a closer look at it too: 
use anchor_lang::prelude::*;
use arcium_anchor::prelude::*;

// This constant identifies our encrypted instruction for onchain operations
// comp_def_offset() generates a unique identifier from the function name
const COMP_DEF_OFFSET_ADD_TOGETHER: u32 = comp_def_offset("add_together");

declare_id!("YOUR_PROGRAM_ID_HERE");

#[arcium_program]
pub mod hello_world {
    use super::*;

    pub fn init_add_together_comp_def(ctx: Context<InitAddTogetherCompDef>) -> Result<()> {
        init_computation_def(ctx.accounts, None)?;
        Ok(())
    }

    pub fn add_together(
        ctx: Context<AddTogether>,
        computation_offset: u64,
        ciphertext_0: [u8; 32],
        ciphertext_1: [u8; 32],
        pub_key: [u8; 32],
        nonce: u128,
    ) -> Result<()> {
        let args = ArgBuilder::new()
            .x25519_pubkey(pub_key)
            .plaintext_u128(nonce)
            .encrypted_u8(ciphertext_0)
            .encrypted_u8(ciphertext_1)
            .build();

        ctx.accounts.sign_pda_account.bump = ctx.bumps.sign_pda_account;

        queue_computation(
            ctx.accounts,
            computation_offset,
            args,
            vec![AddTogetherCallback::callback_ix(
                computation_offset,
                &ctx.accounts.mxe_account,
                &[]
            )?],
            1,
            0,  // cu_price_micro: priority fee in microlamports
            0,  // callback_cu_limit: compute unit limit for the callback (0 = default)
        )?;
        Ok(())
    }

    #[arcium_callback(encrypted_ix = "add_together")]
    pub fn add_together_callback(
        ctx: Context<AddTogetherCallback>,
        output: SignedComputationOutputs<AddTogetherOutput>,
    ) -> Result<()> {
        let o = match output.verify_output(
            &ctx.accounts.cluster_account,
            &ctx.accounts.computation_account
        ) {
            Ok(AddTogetherOutput { field_0 }) => field_0,
            Err(e) => {
                msg!("Error: {}", e);
                return Err(ErrorCode::AbortedComputation.into())
            },
        };

        emit!(SumEvent {
            sum: o.ciphertexts[0],
            nonce: o.nonce.to_le_bytes(),
        });
        Ok(())
    }
}
For brevity, the InitAddTogetherCompDef, AddTogether, and AddTogetherCallback account structs are not included here, but they are automatically generated when you run arcium init. Here’s a simplified version of what AddTogether looks like: 
#[derive(Accounts)]
#[instruction(computation_offset: u64)]
pub struct AddTogether<'info> {
    #[account(mut)]
    pub payer: Signer<'info>,
    // ... other required Arcium accounts (see program/ section for full details)
}
For the full Solana program flow, see Invoking computations from your Solana program. The key things to note here are that every MXE program is identified by the #[arcium_program] macro (which replaces Anchor’s #[program] macro) and that for every encrypted instruction, we generally have three instructions in the Solana program:
  • init_add_together_comp_def: Initializes the computation definition. This runs once before the first invocation of the encrypted instruction. See Computation definition accounts.
  • add_together: Invokes the encrypted instruction, builds the arguments, and queues the computation through the Arcium program. See Invoking computations.
  • add_together_callback: Runs after the MPC cluster finishes the encrypted instruction and returns the result. See Invoking computations.
These three instructions mirror the standard computation lifecycle.

​
Building and testing

Similar to Anchor, encrypted instructions and Solana programs are built with arcium build. Tests use the @arcium-hq/client TypeScript library by default and run with arcium test. Install npm dependencies first with yarn or npm install in your project directory. By default, tests run against a local cluster. To test against devnet or mainnet, use arcium test --cluster devnet after adding the cluster offset to Arcium.toml, for example [clusters.devnet] offset = 456. For faster local loops, use arcium test --test-name <name> to run tests/<name>.ts. After a full localnet keygen, arcium test --skip-keygen or arcium localnet --skip-keygen reuses cached MXE keys; for detached runs, call arcium snapshot-mxe-keygen --rpc-url l before shutting down the validator. Let’s take a quick look at the default test file. Some helper functions and imports are excluded for brevity, but you can find the complete examples in your generated project: 
describe("Hello World", () => {
  // Configure the client to use the local cluster.
  anchor.setProvider(anchor.AnchorProvider.env());
  const program = anchor.workspace.HelloWorld as Program<HelloWorld>;
  const provider = anchor.getProvider();

  const arciumEnv = getArciumEnv();

  it("Is initialized!", async () => {
    const owner = readKpJson(`${os.homedir()}/.config/solana/id.json`);

    console.log("Initializing add together computation definition");
    const initATSig = await initAddTogetherCompDef(program, owner);
    console.log(
      "Add together computation definition initialized with signature",
      initATSig
    );

    const privateKey = x25519.utils.randomSecretKey();
    const publicKey = x25519.getPublicKey(privateKey);
    const mxePublicKey = await getMXEPublicKeyWithRetry(
      provider as anchor.AnchorProvider,
      program.programId
    );

    console.log("MXE x25519 pubkey is", mxePublicKey);
    const sharedSecret = x25519.getSharedSecret(privateKey, mxePublicKey);
    const cipher = new RescueCipher(sharedSecret);

    const val1 = BigInt(1);
    const val2 = BigInt(2);
    const plaintext = [val1, val2];

    const nonce = randomBytes(16);
    const ciphertext = cipher.encrypt(plaintext, nonce);

    const sumEventPromise = awaitEvent("sumEvent");
    const computationOffset = new anchor.BN(randomBytes(8), "hex");

    const queueSig = await program.methods
      .addTogether(
        computationOffset,
        Array.from(ciphertext[0]),
        Array.from(ciphertext[1]),
        Array.from(publicKey),
        new anchor.BN(deserializeLE(nonce).toString())
      )
      .accountsPartial({
        computationAccount: getComputationAccAddress(
          arciumEnv.arciumClusterOffset,
          computationOffset
        ),
        clusterAccount: getClusterAccAddress(arciumEnv.arciumClusterOffset),
        mxeAccount: getMXEAccAddress(program.programId),
        mempoolAccount: getMempoolAccAddress(arciumEnv.arciumClusterOffset),
        executingPool: getExecutingPoolAccAddress(arciumEnv.arciumClusterOffset),
        compDefAccount: getCompDefAccAddress(
          program.programId,
          Buffer.from(getCompDefAccOffset("add_together")).readUInt32LE()
        ),
      })
      .rpc({ commitment: "confirmed" });
    console.log("Queue sig is ", queueSig);

    const finalizeSig = await awaitComputationFinalization(
      provider as anchor.AnchorProvider,
      computationOffset,
      program.programId,
      "confirmed"
    );
    console.log("Finalize sig is ", finalizeSig);

    const sumEvent = await sumEventPromise;
    const decrypted = cipher.decrypt([sumEvent.sum], new Uint8Array(sumEvent.nonce))[0];
    expect(decrypted).to.equal(val1 + val2);
  });
});
This test demonstrates the complete flow of encrypted computations in Arcium. Here’s what each key step does:
  • initAddTogetherCompDef: Call the init_add_together_comp_def instruction to initialize the encrypted instruction definition. (only need to be called once after the program is deployed)
  • getMXEPublicKeyWithRetry: Fetch the MXE’s x25519 public key.
  • x25519.utils.randomSecretKey: Generate a random private key for the x25519 key exchange.
  • x25519.getPublicKey: Generate the public key corresponding to the private key we generated above.
  • x25519.getSharedSecret: Generate the shared secret with the MXE cluster using a x25519 key exchange.
  • cipher = new RescueCipher(sharedSecret): Initialize the Rescue cipher. The constructor derives a key from the Rescue-Prime hash function; see Encryption overview.
  • cipher.encrypt: Encrypt the inputs for the encrypted instruction.
  • awaitEvent: Wait for the sumEvent event to be emitted by the program on finalization of the computation (in the callback instruction).
  • addTogether: Call the add_together instruction to invoke the encrypted instruction.
  • awaitComputationFinalization: Since waiting for an Arcium computation is not the same as waiting for one Solana transaction (because the MPC cluster must finish the computation and invoke the callback), this function is used, which is provided by the Arcium TypeScript library.

​
Ready to Deploy?

Now that you have built and tested your MXE locally, you are probably eager to see it running live! Head over to our deployment guide where we’ll walk you through getting your MXE deployed on Solana. We’ll cover everything from choosing the right RPC endpoint to initializing your computation definitions.

​
What’s next?

Core concepts

Understand MXEs, Clusters, and encrypted instructions.

Learn Arcis

Understand MPC constraints and build more complex circuits.