Arcium Frontend SDK (universal)

TypeScript SDK for building encrypted Solana apps with Arcium: derive Arcium PDAs, encrypt user inputs, encode encrypted instructions, add compute/priority-fee helpers, and verify SignedComputationOutputs. Focused on crypto + transport helpers you can drop into any frontend.

Compatible with @arcium-hq/client v0.8.x (Arcium protocol v0.8.0).

Features

• PDAs: mxe, mempool, executing pool, computation, cluster, comp_def.
• deriveCompDefAccounts — async helper that fetches lutOffsetSlot and returns the Address Lookup Table address required for initCompDef instructions (v0.7.0+).
• Encryption helpers (X25519 + RescueCipher), nonce/computation offset generation.
• Encrypted instruction builder + compute-budget helpers (cu_price_micro, cuLimit).
• Output verification helpers for SignedComputationOutputs (verify_output).
• Environment-driven config: cluster offset/program ID provided by the consumer.

Quick Start

Scaffold a new terminal-styled Arcium app with built-in Solana wallet support:

npx crucible init <project-name>
# or
crucible init <project-name>

Install

Published package (with required peers):

npm install arcium-frontend-sdk @coral-xyz/anchor @solana/web3.js @arcium-hq/client

Local workspace build (current repo):

cd arcium-sdk
npm install
npm run build

Requires Node 20.18+.

Environment

• ARCIUM_CLUSTER_OFFSET — required; keep per environment (dev/stage/prod) in .env.
• NEXT_PUBLIC_RPC_URL/RPC_URL — optional RPC (defaults to devnet).
• NEXT_PUBLIC_MXE_PROGRAM_ID — your program ID; the SDK never hardcodes it.
• POOL_ACCOUNT_PUBKEY / CLOCK_ACCOUNT_PUBKEY — shared game accounts used across the sample frontends (defaults shown below; override via env if yours differ).

.env.example:

ARCIUM_CLUSTER_OFFSET=768109697
NEXT_PUBLIC_RPC_URL=https://api.devnet.solana.com
NEXT_PUBLIC_MXE_PROGRAM_ID=ReplaceWithProgramId
POOL_ACCOUNT_PUBKEY=FsWbPQcJQ2cCyr9ndse13fDqds4F2Ezx2WgTL25Dke4M
CLOCK_ACCOUNT_PUBKEY=AxygBawEvVwZPetj3yPJb9sGdZvaJYsVguET1zFUQkV

Usage walkthrough

1. Initialize a computation definition (required once, v0.7.0+)

Every comp def must be initialized before encrypted instructions can be queued. Since v0.7.0, the initCompDef instruction requires an Address Lookup Table account derived from mxeAcc.lutOffsetSlot. Use deriveCompDefAccounts to get all the pieces:

import { deriveCompDefAccounts } from 'arcium-frontend-sdk';

const { compDefAccount, mxeAccount, addressLookupTable } = await deriveCompDefAccounts(provider, {
  programId: program.programId,
  compDefName: 'my_computation', // snake_case name matching your circuit
});

await program.methods.initMyComputationCompDef()
  .accounts({ compDefAccount, payer: wallet.publicKey, mxeAccount, addressLookupTable })
  .signers([wallet])
  .rpc({ preflightCommitment: 'confirmed', commitment: 'confirmed' });

2. Build and send an encrypted instruction

import { PublicKey } from '@solana/web3.js';
import * as anchor from '@coral-xyz/anchor';
import {
  ensureEnvConfig,
  deriveCoreAccounts,
  prepareEncryptionPayload,
  encodeEncryptedCall,
  buildInstruction,
  buildComputeBudgetIxs,
  randomComputationOffset,
} from 'arcium-frontend-sdk';
import { getMXEPublicKey } from '@arcium-hq/client';

// 0) Env (cluster offset may differ per env)
const env = ensureEnvConfig(); // reads ARCIUM_CLUSTER_OFFSET
const programId = new PublicKey(process.env.NEXT_PUBLIC_MXE_PROGRAM_ID!);

// 1) Fetch MXE public key from chain
const mxePubkey = await getMXEPublicKey(provider, programId);

// 2) Encrypt inputs (numbers/bigints)
const computationOffset = randomComputationOffset();
const encrypted = prepareEncryptionPayload({
  values: [1n, 2n, 3n, 4n],
  mxePublicKey: mxePubkey,
});

// 3) Derive PDAs
const derived = deriveCoreAccounts({
  programId,
  clusterOffset: env.clusterOffset,
  computationOffset,
  compDefOffset: 'my_comp_def', // string -> getCompDefAccOffset
});

// 4) Build ix data (use your 8-byte discriminator from IDL)
const discriminator = Buffer.alloc(8);
const data = encodeEncryptedCall({
  discriminator,
  computationOffset,
  encryptionPubkey: encrypted.encryptionPubkey,
  nonce: encrypted.nonce,
  ciphertexts: encrypted.ciphertexts,
});

// 5) Account metas in your IDL order, then build the instruction
const keys = [
  { pubkey: wallet.publicKey, isSigner: true, isWritable: true },
  { pubkey: derived.mxeAccount, isSigner: false, isWritable: false },
  { pubkey: derived.mempoolAccount, isSigner: false, isWritable: true },
  { pubkey: derived.executingPool, isSigner: false, isWritable: true },
  { pubkey: derived.computationAccount, isSigner: false, isWritable: true },
  { pubkey: derived.compDefAccount, isSigner: false, isWritable: false },
  { pubkey: derived.clusterAccount, isSigner: false, isWritable: true },
  // ... your program-specific accounts ...
  { pubkey: derived.arciumProgramId, isSigner: false, isWritable: false },
];
const { ix } = buildInstruction({ programId, accounts: keys, data });

// 6) Optional compute budget
const budgetIxs = buildComputeBudgetIxs({ cuPriceMicro: 1000, cuLimit: 1_400_000 });

Full runnable example: examples/battle-frontend.ts.

Callback + verify_output example

import { verifySignedOutputs, assertVerified } from 'arcium-frontend-sdk';

function handleCallback(signedOutputs: { verify_output: () => boolean; payload: unknown }) {
  assertVerified(signedOutputs); // throws if invalid
  return signedOutputs.payload;
}

See examples/callback-verify.ts.

API surface

Module	Exports
config	ensureEnvConfig, loadEnvConfig, createConnection, createAnchorProvider, toArciumEnv
accounts	deriveCoreAccounts, deriveCompDefAccounts, toBuffer
encryption	prepareEncryptionPayload, randomComputationOffset, randomNonce, generateKeypair, deriveSharedSecret, encryptBigints, buildEncryptedArgs
transactions/compute	encodeEncryptedCall, buildInstruction, buildComputeBudgetIxs, buildTransaction
results	verifySignedOutputs, assertVerified

Changelog

v0.2.0

• Updated @arcium-hq/client dependency to ^0.8.4 (supports Arcium protocol v0.8.0).
• New: deriveCompDefAccounts(provider, { programId, compDefName }) — async helper for initCompDef instructions. Fetches mxeAcc.lutOffsetSlot and returns { compDefAccount, mxeAccount, addressLookupTable, compDefAccAddress, compDefOffset }.
• New type: DerivedCompDefAccounts.
• generateKeypair() updated: x25519.utils.randomPrivateKey() → x25519.utils.randomSecretKey() (renamed in @noble/curves).

v0.1.4

• Initial public release with @arcium-hq/client@0.5.x support.

LLM usage guide

If you ask an AI assistant (Cursor, Claude Code, Copilot Workspace, etc.) to wire this SDK into your app, hand it LLM_GUIDE.md. That file gives the model exact steps, required env vars, and the canonical flow to encrypt inputs, derive Arcium PDAs, build encrypted instructions, and verify results using the published npm package.

License

MIT © 2025 sicmundus