Invoking a Computation from your Solana program
Last updated
Last updated
Before reading this, we recommend having read the Computation Lifecycle section and the Arcis inputs/outputs section.
Let's say we have the following encrypted instruction and want to invoke it from our MXE.
#[encrypted]
mod circuits {
use arcis_imports::*;
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)
}
}
To do this, we first need to receive the encrypted parameter of type InputValues
which contains two encrypted u8
s, then encode them into the Argument
format, and finally queue the computation for execution. Additionally, we need to define a callback instruction that will be invoked when the computation is complete. Callback instructions have a few requirements:
They must be defined with the #[arcium_callback(encrypted_ix = "encrypted_ix_name")]
macro.
They must have exactly two arguments: ctx: Context<...>
and output: ComputationOutputs<T>
where T
is named as {encrypted_ix_name}Output
.
For passing encrypted arguments, if the corresponding argument is Enc<Shared, T>
, then we need to pass the Argument::ArcisPubkey(pub_key)
and Argument::PlaintextU128(nonce)
, before the ciphertext. If the corresponding argument is Enc<Mxe, T>
, then we only need to pass the nonce as Argument::PlaintextU128(nonce)
and the ciphertext. Ciphertexts are passed as Argument::EncryptedXYZ(ciphertext)
where XYZ
is the type of the ciphertext, with the possibilities being EncryptedU8
, EncryptedU16
, EncryptedU32
, EncryptedU64
, EncryptedU128
, EncryptedBool
.
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<()> {
// Build the args the confidential instruction expects (Ciphertext, Ciphertext, u8)
let args = vec![
Argument::ArcisPubkey(pub_key),
Argument::PlaintextU128(nonce),
Argument::EncryptedU8(ciphertext_0),
Argument::EncryptedU8(ciphertext_1),
];
// Build & queue our computation (via CPI to the Arcium program)
queue_computation(
ctx.accounts,
// Random offset for the computation
computation_offset,
// The one-time inputs our confidential instruction expects
args,
// Accounts needed for the callback instruction
vec![],
// Callback server address
// None here because the output of the confidential instruction can fit into a solana transaction
// as its just 1 Ciphertext which is 32 bytes
None
)?;
Ok(())
}
// Macro provided by the Arcium SDK to define a callback instruction.
#[arcium_callback(encrypted_ix = "add_together")]
pub fn add_together_callback(
ctx: Context<AddTogetherCallback>,
output: ComputationOutputs<AddTogetherOutput>,
) -> Result<()> {
let o = match output {
ComputationOutputs::Success(AddTogetherOutput { field_0 }) => field_0,
_ => return Err(ErrorCode::AbortedComputation.into()),
};
emit!(SumEvent {
sum: o.ciphertexts[0],
nonce: o.nonce.to_le_bytes(),
});
Ok(())
}
Let's also have a look at the Accounts
structs for each of these instructions:
/// Accounts required to invoke the `add_together` encrypted instruction.
/// `add_together` must be the name of the encrypted instruction we're invoking.
#[queue_computation_accounts("add_together", payer)]
#[derive(Accounts)]
#[instruction(computation_offset: u64)]
pub struct AddTogether<'info> {
#[account(mut)]
pub payer: Signer<'info>,
#[account(
address = derive_mxe_pda!()
)]
pub mxe_account: Account<'info, MXEAccount>,
#[account(
mut,
address = derive_mempool_pda!()
)]
/// CHECK: mempool_account, checked by the arcium program.
pub mempool_account: UncheckedAccount<'info>,
#[account(
mut,
address = derive_execpool_pda!()
)]
/// CHECK: executing_pool, checked by the arcium program.
pub executing_pool: UncheckedAccount<'info>,
#[account(
mut,
address = derive_comp_pda!(computation_offset)
)]
/// CHECK: computation_account, checked by the arcium program.
pub computation_account: UncheckedAccount<'info>,
#[account(
address = derive_comp_def_pda!(COMP_DEF_OFFSET_ADD_TOGETHER)
)]
pub comp_def_account: Account<'info, ComputationDefinitionAccount>,
#[account(
mut,
address = derive_cluster_pda!(mxe_account)
)]
pub cluster_account: Account<'info, Cluster>,
#[account(
mut,
address = ARCIUM_FEE_POOL_ACCOUNT_ADDRESS,
)]
pub pool_account: Account<'info, FeePool>,
#[account(
address = ARCIUM_CLOCK_ACCOUNT_ADDRESS
)]
pub clock_account: Account<'info, ClockAccount>,
pub system_program: Program<'info, System>,
pub arcium_program: Program<'info, Arcium>,
}
That's a lot of accounts to remember! Here's what each one does:
Core MXE Accounts:
mxe_account
: Your MXE's metadata and configuration
mempool_account
: Queue where computations wait to be processed
executing_pool
: Tracks computations currently being executed
computation_account
: Stores individual computation data and results
comp_def_account
: Definition of your encrypted instruction (circuit)
Arcium Network Accounts:
cluster_account
: The MPC cluster that will process your computation
pool_account
: Arcium's fee collection account
clock_account
: Network timing information
System Accounts:
payer
: Pays transaction fees and rent
system_program
: Solana's system program for account creation
arcium_program
: Arcium's core program that orchestrates MPC
The good news is these can be copy-pasted for any confidential instruction. You only need to change:
COMP_DEF_OFFSET_ADD_TOGETHER
to match your instruction name
The instruction name in the queue_computation_accounts
macro
How about the accounts for the callback instruction?
#[callback_accounts("add_together", payer)]
#[derive(Accounts)]
pub struct AddTogetherCallback<'info> {
#[account(mut)]
pub payer: Signer<'info>,
pub arcium_program: Program<'info, Arcium>,
/// Like above, COMP_DEF_PDA_SEED is a constant defined in the Arcium SDK.
/// COMP_DEF_OFFSET_ADD_TOGETHER is an encrypted instruction specific u32
/// offset which can be calculated with `comp_def_offset("add_together")`, where
/// comp_def_offset is a function provided by the Arcium SDK and `add_together`
/// is the name of the encrypted instruction we're invoking.
#[account(
address = derive_comp_def_pda!(COMP_DEF_OFFSET_ADD_TOGETHER)
)]
pub comp_def_account: Account<'info, ComputationDefinitionAccount>,
#[account(address = ::anchor_lang::solana_program::sysvar::instructions::ID)]
/// CHECK: instructions_sysvar, checked by the account constraint
pub instructions_sysvar: AccountInfo<'info>,
}
Here it's a lot fewer accounts to fortunately! Like with the AddTogether
struct, we need to change the parameter for the derive_comp_def_pda
macro and in the callback_accounts
macro depending on the encrypted instruction we're invoking. But what if we don't just want to return a raw value and need some additional accounts? Check out input/outputs for how to handle encrypted data and callback accounts for returning additional accounts in the callback.