@arcium-hq/client 0.9.2 → 0.9.3

package/src/pda.ts

@@ -0,0 +1,203 @@
+import { PublicKey, AddressLookupTableProgram } from '@solana/web3.js';
+import * as anchor from '@coral-xyz/anchor';
+import {
+    ARX_NODE_ACC_SEED,
+    CLOCK_ACC_SEED,
+    CLUSTER_ACC_SEED,
+    COMP_DEF_ACC_SEED,
+    COMPUTATION_ACC_SEED,
+    EXEC_POOL_ACC_SEED,
+    MEMPOOL_ACC_SEED,
+    MXE_ACCOUNT_SEED,
+    MXE_RECOVERY_ACC_SEED,
+    OFFSET_BUFFER_SIZE,
+    POOL_ACC_SEED,
+    RAW_CIRCUIT_ACC_SEED,
+    RECOVERY_CLUSTER_ACC_SEED,
+} from './constants.js';
+import { ARCIUM_ADDR } from './idl/index.js';
+
+/**
+ * Return the public key of the deployed Arcium program on Solana.
+ * @returns Arcium program's public key.
+ */
+export function getArciumProgramId(): PublicKey {
+    return new anchor.web3.PublicKey(ARCIUM_ADDR);
+}
+
+/**
+ * Derive the computation account address for a given cluster and computation offset.
+ * @param clusterOffset - Offset of the cluster this computation will be executed by.
+ * @param computationOffset - Computation offset as an anchor.BN.
+ * @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];
+}
+
+/**
+ * Derive the mempool account address for a given cluster.
+ * @param clusterOffset - Offset of the cluster.
+ * @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];
+}
+
+/**
+ * Derive the executing pool account address for a given cluster.
+ * @param clusterOffset - Offset of the cluster.
+ * @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];
+}
+
+/**
+ * Derive the fee pool account address.
+ * @returns Derived fee pool account public key.
+ */
+export function getFeePoolAccAddress(): PublicKey {
+    const seeds = [Buffer.from(POOL_ACC_SEED)];
+
+    return generateArciumPDAFrom(seeds)[0];
+}
+
+/**
+ * Derive the clock account address.
+ * @returns Derived clock account public key.
+ */
+export function getClockAccAddress(): PublicKey {
+    const seeds = [Buffer.from(CLOCK_ACC_SEED)];
+
+    return generateArciumPDAFrom(seeds)[0];
+}
+
+/**
+ * Derive the cluster account address for a given offset.
+ * @param clusterOffset - Cluster offset as a number.
+ * @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];
+}
+
+/**
+ * Derive the ArxNode account address for a given offset.
+ * @param nodeOffset - ArxNode offset as a number.
+ * @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];
+}
+
+/**
+ * Derive the MXE account address for a given MXE program ID.
+ * @param mxeProgramId - Public key of the MXE program.
+ * @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];
+}
+
+/**
+ * Derive the computation definition account address for a given MXE program ID and offset.
+ * @param mxeProgramId - Public key of the MXE program.
+ * @param compDefOffset - Computation definition offset as a number.
+ * @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];
+}
+
+/**
+ * Derive the recovery cluster account address for a given MXE program ID.
+ * @param mxeProgramId - Public key of the MXE program.
+ * @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];
+}
+
+/**
+ * Derive the MXE recovery account address for a key recovery session.
+ * @param backupMxeProgramId - Public key of the backup MXE program that will take over.
+ * @param originalMxeProgramId - Public key of the original MXE program being recovered.
+ * @returns Derived MXE recovery account public key.
+ */
+export function getMxeRecoveryAccAddress(backupMxeProgramId: PublicKey, originalMxeProgramId: PublicKey): PublicKey {
+    const seeds = [
+        Buffer.from(MXE_RECOVERY_ACC_SEED),
+        backupMxeProgramId.toBuffer(),
+        originalMxeProgramId.toBuffer(),
+    ];
+    return generateArciumPDAFrom(seeds)[0];
+}
+
+/**
+ * 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).
+ * @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];
+}
+
+/**
+ * Derive the address lookup table address for an MXE program.
+ * @param mxeProgramId - Public key of the MXE program.
+ * @param lutOffset - Index of the lookup table, to be fetched from the mxe account.
+ * @returns Derived address lookup table public key.
+ */
+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];
+}
+
+/**
+ * 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);
+}

package/src/utils.ts

@@ -0,0 +1,126 @@
+import * as anchor from '@coral-xyz/anchor';
+import { CURVE25519_BASE_FIELD } from './cryptography/rescueDesc.js';
+import { ctAdd, ctLt, ctSelect, ctSignBit, ctSub, verifyBinSize } from './ctUtils.js';
+import { ArciumIdlType } from './idl/index.js';
+
+/**
+ * Check if code is running in a browser environment.
+ * @returns true if window object exists, false otherwise.
+ */
+export function isBrowser(): boolean {
+    return (
+        // eslint-disable-next-line no-prototype-builtins
+        typeof window !== 'undefined' && !window.process?.hasOwnProperty('type')
+    );
+}
+
+/**
+ * Conditionally logs a message if logging is enabled.
+ * @param log - Whether to output the log.
+ * @param args - Arguments to pass to console.log.
+ */
+export function optionalLog(log: boolean, ...args: Parameters<typeof console.log>) {
+    if (log) {
+        // eslint-disable-next-line no-console
+        console.log(...args);
+    }
+}
+
+/**
+ * Calculate the minimum number of bits needed to represent a value.
+ * Formula: floor(log2(max)) + 1 for unsigned, +1 for signed, +1 for diff of two negatives.
+ * @param max - Bigint value to measure.
+ * @returns Number of bits required.
+ */
+export function getBinSize(max: bigint): bigint {
+    // floor(log2(max)) + 1 to represent unsigned elements, a +1 for signed elements
+    // and another +1 to account for the diff of two negative elements
+    return BigInt(Math.floor(Math.log2(Number(max)))) + 3n;
+}
+
+/**
+ * Number of mantissa bits for double-precision floating point values.
+ */
+export const DOUBLE_PRECISION_MANTISSA = 52;
+
+/**
+ * Encode a value as a bigint suitable for Rescue encryption, handling booleans, bigints, and numbers.
+ * The encoding is performed in constant-time to avoid leaking information through timing side-channels.
+ * Throws if the value is out of the supported range for the field.
+ * @param v - Value to encode (bigint, number, or boolean).
+ * @returns Encoded value as a bigint.
+ */
+export function encodeAsRescueEncryptable(v: bigint | number | boolean): bigint {
+    if (typeof v === 'boolean') {
+        return v ? 1n : 0n;
+    }
+    if (typeof v === 'bigint') {
+        const binSize = getBinSize(CURVE25519_BASE_FIELD.ORDER - 1n);
+        if (!verifyBinSize(v, binSize - 1n) || ctLt(v, -(CURVE25519_BASE_FIELD.ORDER - 1n), binSize) || !ctLt(v, CURVE25519_BASE_FIELD.ORDER, binSize)) {
+            throw Error(`v must be in the range [${CURVE25519_BASE_FIELD.ORDER - 1n}, ${CURVE25519_BASE_FIELD.ORDER - 1n}]`);
+        }
+        return ctSelect(ctSignBit(v, binSize), ctAdd(v, CURVE25519_BASE_FIELD.ORDER, binSize), v, binSize);
+    }
+    if (typeof v === 'number') {
+        if (v < -(2 ** 75) || v >= 2 ** 75) {
+            throw new Error('Inputs only supported in the range [-2**75, 2**75)');
+        }
+        const vBigInt = BigInt(Math.round(v * 2 ** DOUBLE_PRECISION_MANTISSA));
+        const binSize = getBinSize(CURVE25519_BASE_FIELD.ORDER - 1n);
+        return ctSelect(ctSignBit(vBigInt, binSize), ctAdd(vBigInt, CURVE25519_BASE_FIELD.ORDER, binSize), vBigInt, binSize);
+    }
+    throw new Error('Invalid type to convert from number to bigint');
+}
+
+/**
+ * Decode a Rescue-decrypted value back to a signed bigint.
+ * Handle the conversion from field element representation to signed integer.
+ * @param v - Decrypted field element value.
+ * @returns Decoded signed bigint value.
+ */
+export function decodeRescueDecryptedToBigInt(v: bigint): bigint {
+    const twoInv = (CURVE25519_BASE_FIELD.ORDER + 1n) / 2n;
+    const binSize = getBinSize(CURVE25519_BASE_FIELD.ORDER - 1n);
+    const isLtTwoInv = ctLt(v, twoInv, binSize);
+    return ctSelect(isLtTwoInv, v, ctSub(v, CURVE25519_BASE_FIELD.ORDER, binSize), binSize);
+}
+
+/**
+ * Decode a Rescue-decrypted value back to a JavaScript number.
+ * Convert from field element representation to a floating-point number.
+ * @param v - Decrypted field element value.
+ * @returns Decoded number value.
+ */
+export function decodeRescueDecryptedToNumber(v: bigint): number {
+    const vSigned = decodeRescueDecryptedToBigInt(v);
+    return Number(vSigned) * 2 ** -DOUBLE_PRECISION_MANTISSA;
+}
+
+/**
+ * Generate a random integer in the range [min, max] (inclusive).
+ * @param min - Minimum value (inclusive).
+ * @param max - Maximum value (inclusive).
+ * @returns Random integer between min and max.
+ */
+export function randomInt(min: number, max: number): number {
+    return Math.floor(Math.random() * (max + 1 - min)) + min;
+}
+
+/**
+ * Reference to a computation in a mempool or executing pool.
+ * Contains the computation offset and priority fee information.
+ */
+export type ComputationReference = anchor.IdlTypes<ArciumIdlType>['computationReference'];
+
+/**
+ * Check if a computation reference is null (all zeros).
+ * @param ref - Computation reference to check.
+ * @returns true if the reference is null, false otherwise.
+ */
+export function isNullRef(ref: ComputationReference): boolean {
+    const bigZero = new anchor.BN(0);
+    return (
+        ref.computationOffset === bigZero
+        && ref.priorityFee === bigZero
+    );
+}