@arcium-hq/client 0.10.3 → 0.11.0

package/src/idlAccounts.ts

@@ -0,0 +1,79 @@
+import { BorshCoder, convertIdlToCamelCase } from '@anchor-lang/core';
+import { DISCRIMINATOR_SIZE } from './constants.js';
+import { ARCIUM_IDL } from './idl/index.js';
+import type { ArciumIdlType } from './idl/index.js';
+
+type IdlAccountName = ArciumIdlType['accounts'][number]['name'];
+
+// Names are validated against the IDL account-name union at compile time, so a
+// typo or stale tier fails `tsc` rather than only throwing at load.
+const MEMPOOL_DECODER_ACCOUNT_NAMES = [
+    'tinyMempool',
+    'smallMempool',
+    'mediumMempool',
+    'largeMempool',
+] as const satisfies readonly IdlAccountName[];
+const EXECUTING_POOL_DECODER_ACCOUNT_NAMES = [
+    'tinyExecPool',
+    'smallExecPool',
+    'mediumExecPool',
+    'largeExecPool',
+] as const satisfies readonly IdlAccountName[];
+
+/** @internal */
+export type MempoolDecoderAccountName = typeof MEMPOOL_DECODER_ACCOUNT_NAMES[number];
+/** @internal */
+export type ExecutingPoolDecoderAccountName = typeof EXECUTING_POOL_DECODER_ACCOUNT_NAMES[number];
+/** @internal */
+export type PoolDecoderAccountName = MempoolDecoderAccountName | ExecutingPoolDecoderAccountName;
+
+type PoolAccountKind = 'mempool' | 'executing pool';
+
+function discriminatorKey(discriminator: ArrayLike<number>): string {
+    return Buffer.from(discriminator).toString('hex');
+}
+
+// Discriminator bytes are read from the IDL at load time rather than pinned, so the
+// decoder tracks the program's account layout as the single source of truth; a
+// missing or renamed tier throws here instead of silently misrouting at runtime.
+const accountDiscriminatorCoder = new BorshCoder(convertIdlToCamelCase(ARCIUM_IDL)).accounts;
+
+function buildPoolAccountMap<const AccountNames extends readonly IdlAccountName[]>(
+    accountNames: AccountNames,
+): ReadonlyMap<string, AccountNames[number]> {
+    return new Map<string, AccountNames[number]>(accountNames.map((name): [string, AccountNames[number]] => [
+        discriminatorKey(accountDiscriminatorCoder.accountDiscriminator(name)),
+        name,
+    ]));
+}
+
+const MEMPOOL_ACCOUNT_BY_DISCRIMINATOR = buildPoolAccountMap(MEMPOOL_DECODER_ACCOUNT_NAMES);
+const EXECUTING_POOL_ACCOUNT_BY_DISCRIMINATOR = buildPoolAccountMap(EXECUTING_POOL_DECODER_ACCOUNT_NAMES);
+
+function getPoolAccountNameByDiscriminator<AccountName extends PoolDecoderAccountName>(
+    accountData: Uint8Array,
+    accountsByDiscriminator: ReadonlyMap<string, AccountName>,
+    kind: PoolAccountKind,
+): AccountName {
+    if (accountData.length < DISCRIMINATOR_SIZE) {
+        throw new Error(`${kind} account data is shorter than discriminator size`);
+    }
+
+    const key = discriminatorKey(accountData.subarray(0, DISCRIMINATOR_SIZE));
+    const accountName = accountsByDiscriminator.get(key);
+    if (accountName === undefined) {
+        throw new Error(`Unknown ${kind} account discriminator: ${key}`);
+    }
+
+    return accountName;
+}
+
+/** @internal */
+export function getMempoolAccountNameByDiscriminator(accountData: Uint8Array): MempoolDecoderAccountName {
+    return getPoolAccountNameByDiscriminator(accountData, MEMPOOL_ACCOUNT_BY_DISCRIMINATOR, 'mempool');
+}
+
+/** @internal */
+export function getExecutingPoolAccountNameByDiscriminator(accountData: Uint8Array): ExecutingPoolDecoderAccountName {
+    return getPoolAccountNameByDiscriminator(accountData, EXECUTING_POOL_ACCOUNT_BY_DISCRIMINATOR, 'executing pool');
+}

package/src/onchain.ts

@@ -1,137 +1,35 @@
-import { Program, AnchorProvider } from '@anchor-lang/core';
+import anchorPkg, { Program, AnchorProvider } from '@anchor-lang/core';
 import * as anchor from '@anchor-lang/core';
-import { ConfirmOptions, PublicKey } from '@solana/web3.js';
+import type { AccountInfo, ConfirmOptions, PublicKey } from '@solana/web3.js';
 import { ARCIUM_IDL, ArciumIdlType } from './idl/index.js';
 import { sha256 } from './cryptography/cryptography.js';
 import { Arcium } from './idl/arcium.js';
 import {
-    COMP_DEF_ACC_SEED,
     COMP_DEF_OFFSET_SIZE,
-    DISCRIMINATOR_SIZE,
-    MAX_ACCOUNT_SIZE,
+    DEFAULT_UPLOAD_TX_BATCH_SIZE,
     MAX_EMBIGGEN_IX_PER_TX,
+    MAX_RAW_CIRCUIT_BYTES_PER_ACC,
     MAX_REALLOC_PER_IX,
     MAX_UPLOAD_PER_TX_BYTES,
-    OFFSET_BUFFER_SIZE,
+    RAW_CIRCUIT_ACCOUNT_HEADER_SIZE,
 } from './constants.js';
 import {
-    getArciumProgramId,
     getMXEAccAddress,
     getComputationAccAddress,
+    getCompDefAccAddress,
     getFeePoolAccAddress,
     getRawCircuitAccAddress,
     getLookupTableAddress,
 } from './pda.js';
 import { ComputationReference, isNullRef, optionalLog } from './utils.js';
+import {
+    getExecutingPoolAccountNameByDiscriminator,
+    getMempoolAccountNameByDiscriminator,
+} from './idlAccounts.js';
+import { normalizeRecoveryPeers } from './recoveryPeers.js';
+import { assertRawCircuitUploadLength, getRawCircuitAccountCount } from './rawCircuit.js';
 
-const TINY_MEMPOOL_ACC_NAME: Arcium['accounts']['21']['name'] = 'tinyMempool';
-const TINY_MEMPOOL_DISCRIMINATOR: Arcium['accounts']['21']['discriminator'] = [
-    176,
-    33,
-    67,
-    108,
-    73,
-    135,
-    110,
-    166,
-];
-
-const TINY_EXECPOOL_ACC_NAME: Arcium['accounts']['20']['name'] = 'tinyExecPool';
-const TINY_EXECPOOL_DISCRIMINATOR: Arcium['accounts']['20']['discriminator'] = [
-    80,
-    245,
-    5,
-    90,
-    154,
-    189,
-    190,
-    172,
-];
-
-const SMALL_MEMPOOL_ACC_NAME: Arcium['accounts']['19']['name'] = 'smallMempool';
-const SMALL_MEMPOOL_DISCRIMINATOR: Arcium['accounts']['19']['discriminator'] = [
-    123,
-    153,
-    151,
-    118,
-    126,
-    71,
-    73,
-    92,
-];
-
-const SMALL_EXECPOOL_ACC_NAME: Arcium['accounts']['18']['name'] = 'smallExecPool';
-const SMALL_EXECPOOL_DISCRIMINATOR: Arcium['accounts']['18']['discriminator'] = [
-    37,
-    147,
-    249,
-    253,
-    217,
-    136,
-    3,
-    87,
-];
-const MEDIUM_MEMPOOL_ACC_NAME: Arcium['accounts']['12']['name'] = 'mediumMempool';
-const MEDIUM_MEMPOOL_DISCRIMINATOR: Arcium['accounts']['12']['discriminator'] = [
-    10,
-    249,
-    58,
-    39,
-    255,
-    231,
-    199,
-    168,
-];
-
-const MEDIUM_EXECPOOL_ACC_NAME: Arcium['accounts']['11']['name'] = 'mediumExecPool';
-const MEDIUM_EXECPOOL_DISCRIMINATOR: Arcium['accounts']['11']['discriminator'] = [
-    97,
-    117,
-    128,
-    202,
-    213,
-    76,
-    5,
-    163,
-];
-
-const LARGE_MEMPOOL_ACC_NAME: Arcium['accounts']['9']['name'] = 'largeMempool';
-const LARGE_MEMPOOL_DISCRIMINATOR: Arcium['accounts']['9']['discriminator'] = [
-    16,
-    168,
-    90,
-    235,
-    249,
-    207,
-    73,
-    223,
-];
-
-const LARGE_EXECPOOL_ACC_NAME: Arcium['accounts']['8']['name'] = 'largeExecPool';
-const LARGE_EXECPOOL_DISCRIMINATOR: Arcium['accounts']['8']['discriminator'] = [
-    147,
-    145,
-    148,
-    170,
-    30,
-    13,
-    43,
-    216,
-];
-
-const MEMPOOL_DISCRIMINATOR_MAP = {
-    [TINY_MEMPOOL_DISCRIMINATOR.toString()]: TINY_MEMPOOL_ACC_NAME,
-    [SMALL_MEMPOOL_DISCRIMINATOR.toString()]: SMALL_MEMPOOL_ACC_NAME,
-    [MEDIUM_MEMPOOL_DISCRIMINATOR.toString()]: MEDIUM_MEMPOOL_ACC_NAME,
-    [LARGE_MEMPOOL_DISCRIMINATOR.toString()]: LARGE_MEMPOOL_ACC_NAME,
-} as const;
-
-const EXECPOOL_DISCRIMINATOR_MAP = {
-    [TINY_EXECPOOL_DISCRIMINATOR.toString()]: TINY_EXECPOOL_ACC_NAME,
-    [SMALL_EXECPOOL_DISCRIMINATOR.toString()]: SMALL_EXECPOOL_ACC_NAME,
-    [MEDIUM_EXECPOOL_DISCRIMINATOR.toString()]: MEDIUM_EXECPOOL_ACC_NAME,
-    [LARGE_EXECPOOL_DISCRIMINATOR.toString()]: LARGE_EXECPOOL_ACC_NAME,
-} as const;
+const { BN } = anchorPkg;
 
 /**
  * Represents a mempool account of any size (tiny, small, medium, or large).
@@ -169,17 +67,8 @@ export type CircuitSource = anchor.IdlTypes<ArciumIdlType>['circuitSource'];
  * @throws Error if the account cannot be fetched or the discriminator is unknown.
  */
 export async function getMempoolAccInfo(provider: AnchorProvider, mempoolAccPubkey: anchor.web3.PublicKey): Promise<MempoolAccount> {
-    const accData = await provider.connection.getAccountInfo(mempoolAccPubkey);
-    if (accData === null) {
-        throw new Error(`Failed to fetch mempool account ${mempoolAccPubkey.toBase58()}`);
-    }
-
-    const discriminator = Array.from(accData.data.subarray(0, DISCRIMINATOR_SIZE)).toString();
-    const accName = MEMPOOL_DISCRIMINATOR_MAP[discriminator];
-
-    if (accName === undefined) {
-        throw new Error(`Unknown mempool account discriminator: ${discriminator}`);
-    }
+    const accData = requireAccountInfo(await provider.connection.getAccountInfo(mempoolAccPubkey), mempoolAccPubkey, 'mempool');
+    const accName = getMempoolAccountNameByDiscriminator(accData.data);
     const program = getArciumProgram(provider);
     return program.coder.accounts.decode(accName, accData.data);
 }
@@ -192,21 +81,24 @@ export async function getMempoolAccInfo(provider: AnchorProvider, mempoolAccPubk
  * @throws Error if the account cannot be fetched or the discriminator is unknown.
  */
 export async function getExecutingPoolAccInfo(provider: AnchorProvider, executingPoolAccPubkey: anchor.web3.PublicKey): Promise<ExecutingPoolAccount> {
-    const accData = await provider.connection.getAccountInfo(executingPoolAccPubkey);
-    if (accData === null) {
-        throw new Error(`Failed to fetch executing pool account ${executingPoolAccPubkey.toBase58()}`);
-    }
-
-    const discriminator = Array.from(accData.data.subarray(0, DISCRIMINATOR_SIZE)).toString();
-    const accName = EXECPOOL_DISCRIMINATOR_MAP[discriminator];
-
-    if (accName === undefined) {
-        throw new Error(`Unknown executing pool account discriminator: ${discriminator}`);
-    }
+    const accData = requireAccountInfo(await provider.connection.getAccountInfo(executingPoolAccPubkey), executingPoolAccPubkey, 'executing pool');
+    const accName = getExecutingPoolAccountNameByDiscriminator(accData.data);
     const program = getArciumProgram(provider);
     return program.coder.accounts.decode(accName, accData.data);
 }
 
+function requireAccountInfo(
+    accountInfo: AccountInfo<Buffer> | null,
+    pubkey: PublicKey,
+    label: 'mempool' | 'executing pool',
+): AccountInfo<Buffer> {
+    if (accountInfo === null) {
+        throw new Error(`Failed to fetch ${label} account ${pubkey.toBase58()}`);
+    }
+
+    return accountInfo;
+}
+
 /**
  * Return all computation references in the mempool for a given account.
  * Only non-stake computations are included.
@@ -286,18 +178,18 @@ export async function getMempoolPriorityFeeStats(
     const refs = await getComputationsInMempool(arciumProgram, mempoolAddress);
 
     if (refs.length === 0) {
-        const zero = new anchor.BN(0);
+        const zero = new BN(0);
         return { mean: zero, median: zero, min: zero, max: zero, count: 0 };
     }
 
     const fees = refs.map(ref => ref.priorityFee).sort((a, b) => a.cmp(b));
 
-    const sum = fees.reduce((acc, fee) => acc.add(fee), new anchor.BN(0));
-    const mean = sum.div(new anchor.BN(fees.length));
+    const sum = fees.reduce((acc, fee) => acc.add(fee), new BN(0));
+    const mean = sum.div(new BN(fees.length));
 
     const mid = Math.floor(fees.length / 2);
     const median = fees.length % 2 === 0
-        ? fees[mid - 1].add(fees[mid]).div(new anchor.BN(2))
+        ? fees[mid - 1].add(fees[mid]).div(new BN(2))
         : fees[mid];
 
     return {
@@ -408,7 +300,8 @@ export function getCircuitState(circuitSource: CircuitSource): CircuitState {
  * @param mxeProgramId - Public key of the MXE program.
  * @param rawCircuit - Raw circuit data as a Uint8Array.
  * @param logging - Whether to log progress (default: true).
- * @param chunkSize - Number of upload transactions to send in parallel (default: 500).
+ * @param chunkSize - Number of upload transactions to send in parallel. Defaults to
+ *                    {@link DEFAULT_UPLOAD_TX_BATCH_SIZE}.
  * @param confirmOptions - Transaction confirmation options.
  * @returns Array of transaction signatures for all upload and finalize transactions.
  */
@@ -418,7 +311,7 @@ export async function uploadCircuit(
     mxeProgramId: anchor.web3.PublicKey,
     rawCircuit: Uint8Array,
     logging: boolean = true,
-    chunkSize: number = 500,
+    chunkSize: number = DEFAULT_UPLOAD_TX_BATCH_SIZE,
     confirmOptions?: ConfirmOptions,
 ): Promise<string[]> {
     const compDefAccInfo = getCompDefAccInfo(circuitName, mxeProgramId);
@@ -432,8 +325,8 @@ export async function uploadCircuit(
         return [];
     }
 
-    // 9 = 8-byte discriminator + 1-byte bump for ComputationDefinitionRaw account
-    const numAccs = Math.ceil(rawCircuit.length / (MAX_ACCOUNT_SIZE - 9));
+    assertRawCircuitUploadLength(rawCircuit.length, compDefAcc.definition.circuitLen, circuitName);
+    const numAccs = getRawCircuitAccountCount(rawCircuit.length);
     const sigs: string[] = [];
     const uploadPromises = [];
     for (let i = 0; i < numAccs; i++) {
@@ -442,8 +335,8 @@ export async function uploadCircuit(
                 provider,
                 program,
                 rawCircuit.subarray(
-                    i * (MAX_ACCOUNT_SIZE - 9),
-                    (i + 1) * (MAX_ACCOUNT_SIZE - 9),
+                    i * MAX_RAW_CIRCUIT_BYTES_PER_ACC,
+                    (i + 1) * MAX_RAW_CIRCUIT_BYTES_PER_ACC,
                 ),
                 i,
                 compDefAccInfo,
@@ -476,8 +369,6 @@ export async function buildFinalizeCompDefTx(
     mxeProgramId: anchor.web3.PublicKey,
 ): Promise<anchor.web3.Transaction> {
     const program = getArciumProgram(provider);
-    const compDefOffsetBuffer = Buffer.alloc(OFFSET_BUFFER_SIZE);
-    compDefOffsetBuffer.writeUInt32LE(compDefOffset, 0);
     return program.methods
         .finalizeComputationDefinition(compDefOffset, mxeProgramId)
         .accounts({
@@ -494,15 +385,14 @@ async function uploadToCircuitAcc(
     compDefAccInfo: { pubkey: anchor.web3.PublicKey; offset: number },
     mxeProgramId: anchor.web3.PublicKey,
     shouldLog: boolean = true,
-    chunkSize: number = 500,
+    chunkSize: number = DEFAULT_UPLOAD_TX_BATCH_SIZE,
     confirmOptions?: ConfirmOptions,
 ): Promise<string[]> {
     const rawCircuitPda = getRawCircuitAccAddress(compDefAccInfo.pubkey, rawCircuitIndex);
     const existingAcc = await provider.connection.getAccountInfo(rawCircuitPda);
 
     // Skip entirely if account exists with correct size (pre-seeded at genesis or already uploaded)
-    // Account layout: 8-byte discriminator + 1-byte bump + circuit data
-    const requiredAccountSize = rawCircuitPart.length + 9;
+    const requiredAccountSize = rawCircuitPart.length + RAW_CIRCUIT_ACCOUNT_HEADER_SIZE;
     if (existingAcc !== null && existingAcc.data.length >= requiredAccountSize) {
         optionalLog(
             shouldLog,
@@ -725,19 +615,8 @@ export function getArciumProgram(provider: AnchorProvider): Program<Arcium> {
  */
 function getCompDefAccInfo(circuitName: string, mxeProgramId: anchor.web3.PublicKey): { pubkey: anchor.web3.PublicKey; offset: number } {
     const offset = getCompDefAccOffset(circuitName);
-    const pda = getCompDefAccPDA(getArciumProgramId(), mxeProgramId, offset);
-    return { pubkey: pda, offset: Buffer.from(offset).readUInt32LE(0) };
-}
-
-/**
- * Return the PDA for a computation definition account, given the program ID, MXE program ID, and offset.
- * @param arciumProgramId - Public key of the Arcium program.
- * @param mxeProgramId - Public key of the MXE program.
- * @param offset - Offset as a Uint8Array.
- * @returns PDA for the computation definition account.
- */
-function getCompDefAccPDA(arciumProgramId: anchor.web3.PublicKey, mxeProgramId: anchor.web3.PublicKey, offset: Uint8Array): anchor.web3.PublicKey {
-    return anchor.web3.PublicKey.findProgramAddressSync([Buffer.from(COMP_DEF_ACC_SEED, 'utf-8'), mxeProgramId.toBuffer(), offset], arciumProgramId)[0];
+    const offsetNumber = Buffer.from(offset).readUInt32LE(0);
+    return { pubkey: getCompDefAccAddress(mxeProgramId, offsetNumber), offset: offsetNumber };
 }
 
 /**
@@ -746,17 +625,22 @@ function getCompDefAccPDA(arciumProgramId: anchor.web3.PublicKey, mxeProgramId:
  * Call initMxePart2 afterwards to finish allocation and add keygen to mempool.
  * @param provider - Anchor provider to use for transactions.
  * @param mxeProgramId - Public key to use as the MXE program ID.
+ * @param recoveryPeers - Array of 100 node offsets for recovery peers (0 for unused slots).
  * @param confirmOptions - Transaction confirmation options.
  * @returns Transaction signature.
  */
 export async function initMxePart1(
     provider: AnchorProvider,
     mxeProgramId: anchor.web3.PublicKey,
+    recoveryPeers: number[],
     confirmOptions?: ConfirmOptions,
 ): Promise<string> {
     const program = getArciumProgram(provider);
+    const paddedRecoveryPeers = normalizeRecoveryPeers(recoveryPeers);
     const tx = await program.methods
-        .initMxePart1()
+        .initMxePart1(
+            paddedRecoveryPeers
+        )
         .accountsPartial({
             signer: provider.publicKey,
             mxeProgram: mxeProgramId,
@@ -772,9 +656,12 @@ export async function initMxePart1(
  * @param provider - Anchor provider to use for transactions.
  * @param clusterOffset - Cluster offset to associate with the MXE.
  * @param mxeProgramId - Public key to use as the MXE program ID.
- * @param recoveryPeers - Array of 100 node offsets for recovery peers (0 for unused slots).
  * @param keygenOffset - Computation offset for the keygen computation.
  * @param keyRecoveryInitOffset - Computation offset for the key_recovery_init computation.
+ * @param recoveryPeers - Recovery peer node offsets. Slots set to 0 are treated as unused.
+ *                        The non-zero count must be either 0 (recovery disabled) or at least
+ *                        `MIN_RECOVERY_PEERS` (4). The array is padded with zeros up to
+ *                        `MAX_RECOVERY_PEERS` (100); passing more than that throws.
  * @param lutOffset - Lookup table offset for the MXE's address lookup table.
  * @param mxeAuthority - Optional authority for the MXE (defaults to provider.publicKey).
  * @param confirmOptions - Transaction confirmation options.
@@ -792,20 +679,10 @@ export async function initMxePart2(
     confirmOptions?: ConfirmOptions,
 ): Promise<string> {
     const program = getArciumProgram(provider);
-    // Ensure recoveryPeers has exactly 100 elements
-    const paddedRecoveryPeers = [...recoveryPeers];
-    while (paddedRecoveryPeers.length < 100) {
-        paddedRecoveryPeers.push(0);
-    }
-    if (paddedRecoveryPeers.length > 100) {
-        throw new Error('recoveryPeers must have at most 100 elements');
-    }
 
     const tx = await program.methods
         .initMxePart2(
             clusterOffset,
-            mxeProgramId,
-            paddedRecoveryPeers,
             keygenOffset,
             keyRecoveryInitOffset,
             lutOffset,
@@ -821,6 +698,14 @@ export async function initMxePart2(
     return signAndSendWithBlockhash(provider, tx, await provider.connection.getLatestBlockhash({ commitment: confirmOptions?.commitment || 'confirmed' }), confirmOptions);
 }
 
+/**
+ * Reclaim the rent locked in a finished computation account.
+ * @param provider - Anchor provider to use for transactions.
+ * @param clusterOffset - Offset of the cluster that ran the computation.
+ * @param computationOffset - Offset of the computation whose rent is being claimed.
+ * @param confirmOptions - Transaction confirmation options.
+ * @returns Transaction signature.
+ */
 export async function claimComputationRent(
     provider: AnchorProvider,
     clusterOffset: number,