arcium-frontend

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Arcium Frontend Development

Arcium前端开发

Guide for building encrypted Solana applications using Arcium.

本指南介绍如何使用Arcium构建加密的Solana应用。

When to Use This Skill

适用场景

Use this skill when:

Building a new Arcium-powered frontend
Adding encrypted computations to existing apps
Integrating Solana wallet adapters
Deriving Arcium PDAs
Encrypting user inputs
Building and sending encrypted instructions
Troubleshooting Arcium-related errors

在以下场景中可使用本技能：

构建全新的Arcium驱动前端
为现有应用添加加密计算功能
集成Solana钱包适配器
派生Arcium PDA
加密用户输入
构建并发送加密指令
排查Arcium相关错误

Required Dependencies

所需依赖

bash

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

bash

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

Environment Variables

环境变量

Variable	Required	Default
`ARCIUM_CLUSTER_OFFSET`	Yes	—
`NEXT_PUBLIC_MXE_PROGRAM_ID`	Yes	—
`NEXT_PUBLIC_RPC_URL`	No	devnet

变量名	是否必填	默认值
`ARCIUM_CLUSTER_OFFSET`	是	—
`NEXT_PUBLIC_MXE_PROGRAM_ID`	是	—
`NEXT_PUBLIC_RPC_URL`	否	devnet

Core Flow

核心流程

Setup provider → Create Anchor provider from wallet
Fetch MXE key →
```
getMXEPublicKey(provider, programId)
```
Generate offset → Random 8-byte computation offset
Encrypt values → X25519 key exchange + RescueCipher
Derive PDAs → MXE, cluster, computation, comp def accounts
Build instruction → Encode discriminator + encrypted data
Send transaction → Sign and submit with compute budget

设置Provider → 从钱包创建Anchor Provider
获取MXE公钥 →
```
getMXEPublicKey(provider, programId)
```
生成偏移量 → 随机8字节计算偏移量
加密数值 → X25519密钥交换 + RescueCipher
派生PDA → MXE、集群、计算、计算定义账户
构建指令 → 编码鉴别器 + 加密数据
发送交易 → 签名并提交，附带计算预算

Key Imports

关键导入

typescript

import * as anchor from '@coral-xyz/anchor';
import { PublicKey, SystemProgram } from '@solana/web3.js';
import {
  getMXEPublicKey,
  getClusterAccAddress,
  getMXEAccAddress,
  getMempoolAccAddress,
  getExecutingPoolAccAddress,
  getComputationAccAddress,
  getCompDefAccAddress,
  getArciumAccountBaseSeed,
  getCompDefAccOffset,
  getArciumProgramId,
  x25519,
  RescueCipher,
  deserializeLE,
} from '@arcium-hq/client';

typescript

import * as anchor from '@coral-xyz/anchor';
import { PublicKey, SystemProgram } from '@solana/web3.js';
import {
  getMXEPublicKey,
  getClusterAccAddress,
  getMXEAccAddress,
  getMempoolAccAddress,
  getExecutingPoolAccAddress,
  getComputationAccAddress,
  getCompDefAccAddress,
  getArciumAccountBaseSeed,
  getCompDefAccOffset,
  getArciumProgramId,
  x25519,
  RescueCipher,
  deserializeLE,
} from '@arcium-hq/client';

Encryption Pattern

加密模式

typescript

// 1. Fetch MXE public key
const mxePublicKey = await getMXEPublicKey(provider, programId);

// 2. Generate ephemeral keypair
const privateKey = x25519.utils.randomPrivateKey();
const publicKey = x25519.getPublicKey(privateKey);

// 3. Derive shared secret
const sharedSecret = x25519.getSharedSecret(privateKey, mxePublicKey);

// 4. Encrypt values
const cipher = new RescueCipher(sharedSecret);
const nonce = nacl.randomBytes(16);
const values = [BigInt(10), BigInt(7), BigInt(5)];
const ciphertexts = cipher.encrypt(values, nonce);

typescript

// 1. 获取MXE公钥
const mxePublicKey = await getMXEPublicKey(provider, programId);

// 2. 生成临时密钥对
const privateKey = x25519.utils.randomPrivateKey();
const publicKey = x25519.getPublicKey(privateKey);

// 3. 派生共享密钥
const sharedSecret = x25519.getSharedSecret(privateKey, mxePublicKey);

// 4. 加密数值
const cipher = new RescueCipher(sharedSecret);
const nonce = nacl.randomBytes(16);
const values = [BigInt(10), BigInt(7), BigInt(5)];
const ciphertexts = cipher.encrypt(values, nonce);

PDA Derivation Pattern

PDA派生模式

typescript

// Cluster-based PDAs
const clusterOffset = 768109697; // from ARCIUM_CLUSTER_OFFSET
const clusterAccount = getClusterAccAddress(clusterOffset);
const mempoolAccount = getMempoolAccAddress(clusterOffset);
const executingPool = getExecutingPoolAccAddress(clusterOffset);

// Program-based PDAs
const mxeAccount = getMXEAccAddress(programId);
const computationOffset = new anchor.BN(nacl.randomBytes(8), 'le');
const computationAccount = getComputationAccAddress(clusterOffset, computationOffset);

// Comp def account
const baseSeed = getArciumAccountBaseSeed('ComputationDefinitionAccount');
const offsetBytes = getCompDefAccOffset('my_computation');
const [compDefAccount] = PublicKey.findProgramAddressSync(
  [baseSeed, programId.toBuffer(), offsetBytes],
  getArciumProgramId()
);

typescript

// 基于集群的PDA
const clusterOffset = 768109697; // 来自ARCIUM_CLUSTER_OFFSET
const clusterAccount = getClusterAccAddress(clusterOffset);
const mempoolAccount = getMempoolAccAddress(clusterOffset);
const executingPool = getExecutingPoolAccAddress(clusterOffset);

// 基于程序的PDA
const mxeAccount = getMXEAccAddress(programId);
const computationOffset = new anchor.BN(nacl.randomBytes(8), 'le');
const computationAccount = getComputationAccAddress(clusterOffset, computationOffset);

// 计算定义账户
const baseSeed = getArciumAccountBaseSeed('ComputationDefinitionAccount');
const offsetBytes = getCompDefAccOffset('my_computation');
const [compDefAccount] = PublicKey.findProgramAddressSync(
  [baseSeed, programId.toBuffer(), offsetBytes],
  getArciumProgramId()
);

Account Ordering

账户顺序

Standard order for encrypted instructions:

```
payer
```
(signer, writable)
```
mxeAccount
```
(not signer, not writable)
```
mempoolAccount
```
(not signer, writable)
```
executingPool
```
(not signer, writable)
```
computationAccount
```
(not signer, writable)
```
compDefAccount
```
(not signer, not writable)
```
clusterAccount
```
(not signer, writable)
Game-specific accounts
```
SystemProgram.programId
```
```
arciumProgramId
```

加密指令的标准顺序：

```
payer
```
（签名者，可写）
```
mxeAccount
```
（非签名者，不可写）
```
mempoolAccount
```
（非签名者，可写）
```
executingPool
```
（非签名者，可写）
```
computationAccount
```
（非签名者，可写）
```
compDefAccount
```
（非签名者，不可写）
```
clusterAccount
```
（非签名者，可写）
游戏专属账户
```
SystemProgram.programId
```
```
arciumProgramId
```

Common Errors

常见错误

Error	Cause	Solution
`ARCIUM_CLUSTER_OFFSET is missing`	Missing env var	Add to `.env.local`
`MXE Public Key not found`	MXE not initialized	Initialize MXE account first
`Account not found`	Wrong PDA derivation	Check cluster offset matches network

错误信息	原因	解决方案
`ARCIUM_CLUSTER_OFFSET is missing`	缺少环境变量	添加至 `.env.local`
`MXE Public Key not found`	MXE未初始化	先初始化MXE账户
`Account not found`	PDA派生错误	检查集群偏移量是否与网络匹配

Detailed References

详细参考资料

For in-depth explanations, see:

references/encryption-flow.md — X25519 + RescueCipher details
references/pda-derivation.md — Account derivation patterns
references/wallet-integration.md — Wallet adapter setup
references/nextjs-patterns.md — Next.js App Router integration
references/env-configuration.md — Environment setup
references/troubleshooting.md — Common errors and fixes

如需深入了解，请查看：

references/encryption-flow.md — X25519 + RescueCipher 细节说明
references/pda-derivation.md — 账户派生模式
references/wallet-integration.md — 钱包适配器设置
references/nextjs-patterns.md — Next.js App Router 集成
references/env-configuration.md — 环境设置
references/troubleshooting.md — 常见错误与修复方案