@arcium-hq/client 0.10.4 → 0.11.1

package/src/pda.ts

@@ -1,22 +1,30 @@
 import { PublicKey, AddressLookupTableProgram } from '@solana/web3.js';
 import * as anchor from '@anchor-lang/core';
 import {
+    ARCIUM_SIGNER_ACC_SEED,
     ARX_NODE_ACC_SEED,
     CLOCK_ACC_SEED,
     CLUSTER_ACC_SEED,
     COMP_DEF_ACC_SEED,
     COMPUTATION_ACC_SEED,
     EXEC_POOL_ACC_SEED,
+    FAILURE_CLAIM_ACC_SEED,
     MEMPOOL_ACC_SEED,
     MXE_ACCOUNT_SEED,
     MXE_RECOVERY_ACC_SEED,
+    OPERATOR_ACC_SEED,
     OFFSET_BUFFER_SIZE,
     POOL_ACC_SEED,
     RAW_CIRCUIT_ACC_SEED,
     RECOVERY_CLUSTER_ACC_SEED,
+    RECOVERY_PEER_ACC_SEED,
 } from './constants.js';
 import { ARCIUM_ADDR } from './idl/index.js';
 
+const U64_SEED_SIZE = 8;
+const MAX_U8 = 0xff;
+const MAX_U32 = 0xffffffff;
+
 /**
  * Return the public key of the deployed Arcium program on Solana.
  * @returns Arcium program's public key.
@@ -32,11 +40,7 @@ export function getArciumProgramId(): PublicKey {
  * @returns Derived computation account public key.
  */
 export function getComputationAccAddress(clusterOffset: number, computationOffset: anchor.BN): PublicKey {
-    const clOffsetBuffer = Buffer.alloc(OFFSET_BUFFER_SIZE);
-    clOffsetBuffer.writeUInt32LE(clusterOffset, 0);
-
-    const seeds = [Buffer.from(COMPUTATION_ACC_SEED), clOffsetBuffer, computationOffset.toArrayLike(Buffer, 'le', 8)];
-    return generateArciumPDAFrom(seeds)[0];
+    return findArciumPda([stringSeed(COMPUTATION_ACC_SEED), u32Seed(clusterOffset), u64Seed(computationOffset)]);
 }
 
 /**
@@ -45,11 +49,7 @@ export function getComputationAccAddress(clusterOffset: number, computationOffse
  * @returns Derived mempool account public key.
  */
 export function getMempoolAccAddress(clusterOffset: number): PublicKey {
-    const clOffsetBuffer = Buffer.alloc(OFFSET_BUFFER_SIZE);
-    clOffsetBuffer.writeUInt32LE(clusterOffset, 0);
-
-    const seeds = [Buffer.from(MEMPOOL_ACC_SEED), clOffsetBuffer];
-    return generateArciumPDAFrom(seeds)[0];
+    return findArciumPda([stringSeed(MEMPOOL_ACC_SEED), u32Seed(clusterOffset)]);
 }
 
 /**
@@ -58,12 +58,7 @@ export function getMempoolAccAddress(clusterOffset: number): PublicKey {
  * @returns Derived executing pool account public key.
  */
 export function getExecutingPoolAccAddress(clusterOffset: number): PublicKey {
-    const clOffsetBuffer = Buffer.alloc(OFFSET_BUFFER_SIZE);
-    clOffsetBuffer.writeUInt32LE(clusterOffset, 0);
-
-    const seeds = [Buffer.from(EXEC_POOL_ACC_SEED), clOffsetBuffer];
-
-    return generateArciumPDAFrom(seeds)[0];
+    return findArciumPda([stringSeed(EXEC_POOL_ACC_SEED), u32Seed(clusterOffset)]);
 }
 
 /**
@@ -71,9 +66,7 @@ export function getExecutingPoolAccAddress(clusterOffset: number): PublicKey {
  * @returns Derived fee pool account public key.
  */
 export function getFeePoolAccAddress(): PublicKey {
-    const seeds = [Buffer.from(POOL_ACC_SEED)];
-
-    return generateArciumPDAFrom(seeds)[0];
+    return findArciumPda([stringSeed(POOL_ACC_SEED)]);
 }
 
 /**
@@ -81,9 +74,7 @@ export function getFeePoolAccAddress(): PublicKey {
  * @returns Derived clock account public key.
  */
 export function getClockAccAddress(): PublicKey {
-    const seeds = [Buffer.from(CLOCK_ACC_SEED)];
-
-    return generateArciumPDAFrom(seeds)[0];
+    return findArciumPda([stringSeed(CLOCK_ACC_SEED)]);
 }
 
 /**
@@ -92,11 +83,7 @@ export function getClockAccAddress(): PublicKey {
  * @returns Derived cluster account public key.
  */
 export function getClusterAccAddress(clusterOffset: number): PublicKey {
-    const offsetBuffer = Buffer.alloc(OFFSET_BUFFER_SIZE);
-    offsetBuffer.writeUInt32LE(clusterOffset, 0);
-    const seeds = [Buffer.from(CLUSTER_ACC_SEED), offsetBuffer];
-
-    return generateArciumPDAFrom(seeds)[0];
+    return findArciumPda([stringSeed(CLUSTER_ACC_SEED), u32Seed(clusterOffset)]);
 }
 
 /**
@@ -105,11 +92,7 @@ export function getClusterAccAddress(clusterOffset: number): PublicKey {
  * @returns Derived ArxNode account public key.
  */
 export function getArxNodeAccAddress(nodeOffset: number): PublicKey {
-    const offsetBuffer = Buffer.alloc(OFFSET_BUFFER_SIZE);
-    offsetBuffer.writeUInt32LE(nodeOffset, 0);
-    const seeds = [Buffer.from(ARX_NODE_ACC_SEED), offsetBuffer];
-
-    return generateArciumPDAFrom(seeds)[0];
+    return findArciumPda([stringSeed(ARX_NODE_ACC_SEED), u32Seed(nodeOffset)]);
 }
 
 /**
@@ -118,9 +101,7 @@ export function getArxNodeAccAddress(nodeOffset: number): PublicKey {
  * @returns Derived MXE account public key.
  */
 export function getMXEAccAddress(mxeProgramId: PublicKey): PublicKey {
-    const seeds = [Buffer.from(MXE_ACCOUNT_SEED), mxeProgramId.toBuffer()];
-
-    return generateArciumPDAFrom(seeds)[0];
+    return findArciumPda([stringSeed(MXE_ACCOUNT_SEED), pubkeySeed(mxeProgramId)]);
 }
 
 /**
@@ -130,11 +111,7 @@ export function getMXEAccAddress(mxeProgramId: PublicKey): PublicKey {
  * @returns Derived computation definition account public key.
  */
 export function getCompDefAccAddress(mxeProgramId: PublicKey, compDefOffset: number): PublicKey {
-    const offsetBuffer = Buffer.alloc(OFFSET_BUFFER_SIZE);
-    offsetBuffer.writeUInt32LE(compDefOffset, 0);
-    const seeds = [Buffer.from(COMP_DEF_ACC_SEED), mxeProgramId.toBuffer(), offsetBuffer];
-
-    return generateArciumPDAFrom(seeds)[0];
+    return findArciumPda([stringSeed(COMP_DEF_ACC_SEED), pubkeySeed(mxeProgramId), u32Seed(compDefOffset)]);
 }
 
 /**
@@ -143,8 +120,7 @@ export function getCompDefAccAddress(mxeProgramId: PublicKey, compDefOffset: num
  * @returns Derived recovery cluster account public key.
  */
 export function getRecoveryClusterAccAddress(mxeProgramId: PublicKey): PublicKey {
-    const seeds = [Buffer.from(RECOVERY_CLUSTER_ACC_SEED), mxeProgramId.toBuffer()];
-    return generateArciumPDAFrom(seeds)[0];
+    return findArciumPda([stringSeed(RECOVERY_CLUSTER_ACC_SEED), pubkeySeed(mxeProgramId)]);
 }
 
 /**
@@ -153,23 +129,57 @@ export function getRecoveryClusterAccAddress(mxeProgramId: PublicKey): PublicKey
  * @returns Derived MXE recovery account public key.
  */
 export function getMxeRecoveryAccAddress(originalMxeProgramId: PublicKey): PublicKey {
-    const seeds = [Buffer.from(MXE_RECOVERY_ACC_SEED), originalMxeProgramId.toBuffer()];
-    return generateArciumPDAFrom(seeds)[0];
+    return findArciumPda([stringSeed(MXE_RECOVERY_ACC_SEED), pubkeySeed(originalMxeProgramId)]);
+}
+
+/**
+ * Derive the recovery peer account address for a given recovery peer offset.
+ * @param peerOffset - Recovery peer offset as a u32 in `[0, 2^32 - 1]`.
+ * @returns Derived recovery peer account public key.
+ */
+export function getRecoveryPeerAccAddress(peerOffset: number): PublicKey {
+    return findArciumPda([stringSeed(RECOVERY_PEER_ACC_SEED), u32Seed(peerOffset)]);
+}
+
+/**
+ * Derive the operator account address for a given operator signer.
+ * @param operatorSigner - Public key of the operator signer.
+ * @returns Derived operator account public key.
+ */
+export function getOperatorAccAddress(operatorSigner: PublicKey): PublicKey {
+    return findArciumPda([stringSeed(OPERATOR_ACC_SEED), pubkeySeed(operatorSigner)]);
+}
+
+/**
+ * Derive the failure claim account address for a given MXE program and computation offset.
+ * @param mxeProgramId - Public key of the MXE program.
+ * @param computationOffset - Computation offset as an anchor.BN in `[0, 2^64 - 1]`.
+ * @returns Derived failure claim account public key.
+ */
+export function getFailureClaimAccAddress(mxeProgramId: PublicKey, computationOffset: anchor.BN): PublicKey {
+    return findArciumPda([stringSeed(FAILURE_CLAIM_ACC_SEED), pubkeySeed(mxeProgramId), u64Seed(computationOffset)]);
+}
+
+/**
+ * Derive the Arcium signer account address used by an MXE program when invoking the Arcium
+ * program. Unlike most other helpers in this module, this PDA is derived under the MXE
+ * program ID (the caller), not the Arcium program ID - Arcium verifies the seed via
+ * `seeds::program = _mxe_program`.
+ * @param mxeProgramId - Public key of the MXE program that owns the signer PDA.
+ * @returns Derived Arcium signer account public key.
+ */
+export function getArciumSignerAccAddress(mxeProgramId: PublicKey): PublicKey {
+    return findPda(mxeProgramId, [stringSeed(ARCIUM_SIGNER_ACC_SEED)]);
 }
 
 /**
  * Derive the raw circuit account address for a given computation definition and index.
  * @param compDefPubkey - Public key of the computation definition account.
- * @param rawCircuitIndex - Index of the raw circuit account (0-based).
+ * @param rawCircuitIndex - Index of the raw circuit account as a u8 in `[0, 255]`.
  * @returns Derived raw circuit account public key.
  */
 export function getRawCircuitAccAddress(compDefPubkey: PublicKey, rawCircuitIndex: number): PublicKey {
-    const seeds = [
-        Buffer.from(RAW_CIRCUIT_ACC_SEED),
-        compDefPubkey.toBuffer(),
-        Buffer.from([rawCircuitIndex]),
-    ];
-    return generateArciumPDAFrom(seeds)[0];
+    return findArciumPda([stringSeed(RAW_CIRCUIT_ACC_SEED), pubkeySeed(compDefPubkey), u8Seed(rawCircuitIndex)]);
 }
 
 /**
@@ -180,19 +190,48 @@ export function getRawCircuitAccAddress(compDefPubkey: PublicKey, rawCircuitInde
  */
 export function getLookupTableAddress(mxeProgramId: PublicKey, lutOffset: anchor.BN): PublicKey {
     const mxeAccount = getMXEAccAddress(mxeProgramId);
-    const lutIndexBuffer = lutOffset.toArrayLike(Buffer, 'le', 8);
-    const seeds = [mxeAccount.toBuffer(), lutIndexBuffer];
-    return PublicKey.findProgramAddressSync(seeds, AddressLookupTableProgram.programId)[0];
+    return findPda(AddressLookupTableProgram.programId, [pubkeySeed(mxeAccount), u64Seed(lutOffset)]);
 }
 
-/**
- * Generate a program-derived address (PDA) from the provided seeds and the Arcium program ID.
- * @param seeds - Array of Buffer seeds used for PDA derivation.
- * @returns Tuple containing the derived public key and the bump seed.
- */
-function generateArciumPDAFrom(
-    seeds: Buffer[],
-): [PublicKey, number] {
-    const programId = getArciumProgramId();
-    return PublicKey.findProgramAddressSync(seeds, programId);
+function stringSeed(value: string): Buffer {
+    return Buffer.from(value);
+}
+
+function u8Seed(value: number): Buffer {
+    assertIntegerInRange(value, 0, MAX_U8, 'u8 seed');
+    return Buffer.from([value]);
+}
+
+function u32Seed(value: number): Buffer {
+    assertIntegerInRange(value, 0, MAX_U32, 'u32 seed');
+    const buffer = Buffer.alloc(OFFSET_BUFFER_SIZE);
+    buffer.writeUInt32LE(value, 0);
+    return buffer;
+}
+
+function u64Seed(value: anchor.BN): Buffer {
+    if (value.isNeg() || value.byteLength() > U64_SEED_SIZE) {
+        throw new RangeError(
+            `u64 seed must be between 0 and 18446744073709551615 (got ${value.toString()})`,
+        );
+    }
+    return value.toArrayLike(Buffer, 'le', U64_SEED_SIZE);
+}
+
+function pubkeySeed(value: PublicKey): Buffer {
+    return value.toBuffer();
+}
+
+function findArciumPda(seeds: Buffer[]): PublicKey {
+    return findPda(getArciumProgramId(), seeds);
+}
+
+function findPda(programId: PublicKey, seeds: Buffer[]): PublicKey {
+    return PublicKey.findProgramAddressSync(seeds, programId)[0];
+}
+
+function assertIntegerInRange(value: number, min: number, max: number, label: string): void {
+    if (!Number.isInteger(value) || value < min || value > max) {
+        throw new RangeError(`${label} must be an integer between ${min} and ${max} (got ${value})`);
+    }
 }

package/src/rawCircuit.ts

@@ -0,0 +1,41 @@
+import {
+    MAX_RAW_CIRCUIT_ACCOUNTS,
+    MAX_RAW_CIRCUIT_BYTES_PER_ACC,
+} from './constants.js';
+
+/** @internal */
+export function getRawCircuitAccountCount(rawCircuitByteLength: number): number {
+    if (!Number.isInteger(rawCircuitByteLength) || rawCircuitByteLength < 0) {
+        throw new RangeError(`rawCircuit byte length must be a non-negative integer (got ${rawCircuitByteLength})`);
+    }
+
+    const accountCount = Math.ceil(rawCircuitByteLength / MAX_RAW_CIRCUIT_BYTES_PER_ACC);
+    if (accountCount > MAX_RAW_CIRCUIT_ACCOUNTS) {
+        throw new RangeError(
+            `Raw circuit is too large for on-chain upload: requires ${accountCount} raw circuit accounts, maximum is ${MAX_RAW_CIRCUIT_ACCOUNTS}`,
+        );
+    }
+
+    return accountCount;
+}
+
+/** @internal */
+export function assertRawCircuitUploadLength(
+    rawCircuitByteLength: number,
+    declaredCircuitByteLength: number,
+    circuitName: string,
+): void {
+    if (!Number.isInteger(rawCircuitByteLength) || rawCircuitByteLength < 0) {
+        throw new RangeError(`rawCircuit byte length must be a non-negative integer (got ${rawCircuitByteLength})`);
+    }
+    if (!Number.isInteger(declaredCircuitByteLength) || declaredCircuitByteLength <= 0) {
+        throw new RangeError(
+            `Declared circuit byte length for ${circuitName} must be a positive integer (got ${declaredCircuitByteLength})`,
+        );
+    }
+    if (rawCircuitByteLength !== declaredCircuitByteLength) {
+        throw new RangeError(
+            `Raw circuit byte length for ${circuitName} must match the computation definition: got ${rawCircuitByteLength}, expected ${declaredCircuitByteLength}`,
+        );
+    }
+}

package/src/recoveryPeers.ts

@@ -0,0 +1,46 @@
+import { MAX_RECOVERY_PEERS, MIN_RECOVERY_PEERS } from './constants.js';
+
+const MAX_U32 = 0xffffffff;
+
+/**
+ * Mirrors the on-chain `init_mxe_part2` recovery-peer bounds before building the instruction.
+ * @internal
+ */
+export function assertValidRecoveryPeers(recoveryPeers: readonly number[]): void {
+    if (recoveryPeers.length > MAX_RECOVERY_PEERS) {
+        throw new Error(
+            `recoveryPeers must have at most ${MAX_RECOVERY_PEERS} elements (got ${recoveryPeers.length})`,
+        );
+    }
+
+    let nonZeroPeers = 0;
+    for (let index = 0; index < recoveryPeers.length; index += 1) {
+        const peer = recoveryPeers[index];
+        if (!Number.isInteger(peer) || peer < 0 || peer > MAX_U32) {
+            throw new RangeError(
+                `recoveryPeers[${index}] must be an integer in [0, ${MAX_U32}] (got ${peer})`,
+            );
+        }
+        if (peer !== 0) {
+            nonZeroPeers += 1;
+        }
+    }
+
+    if (nonZeroPeers > 0 && nonZeroPeers < MIN_RECOVERY_PEERS) {
+        throw new Error(
+            `recoveryPeers must have 0 or at least ${MIN_RECOVERY_PEERS} non-zero offsets (found ${nonZeroPeers})`,
+        );
+    }
+}
+
+/** @internal */
+export function normalizeRecoveryPeers(recoveryPeers: readonly number[]): number[] {
+    assertValidRecoveryPeers(recoveryPeers);
+
+    const paddedRecoveryPeers = [...recoveryPeers];
+    while (paddedRecoveryPeers.length < MAX_RECOVERY_PEERS) {
+        paddedRecoveryPeers.push(0);
+    }
+
+    return paddedRecoveryPeers;
+}