@arcium-hq/client 0.9.2 → 0.9.4

package/src/idl/index.ts

@@ -0,0 +1,20 @@
+import { Arcium } from './arcium.js';
+import * as ARCIUM_IDL_MODULE from './arcium.json' with { type: 'json' };
+
+// Handle both ESM (ts-node wraps as {default: ...}) and bundled (direct) imports
+const ARCIUM_IDL = ((ARCIUM_IDL_MODULE as { default?: Arcium }).default ?? ARCIUM_IDL_MODULE) as unknown as Arcium;
+
+/**
+ * The deployed address of the Arcium program, as specified in the IDL.
+ */
+export const ARCIUM_ADDR = ARCIUM_IDL.address;
+
+/**
+ * The Anchor-generated IDL type for the Arcium program.
+ */
+export type { Arcium as ArciumIdlType };
+
+/**
+ * The Anchor-generated IDL JSON object for the Arcium program.
+ */
+export { ARCIUM_IDL };

package/src/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Client SDK for encrypted Solana programs using Arcium MPC.
+ *
+ * Key exports:
+ * - {@link createPacker} - Pack/unpack circuit inputs and outputs
+ * - {@link awaitComputationFinalization} - Wait for computation results
+ * - Cryptography: AES, Rescue ciphers, HMAC, HKDF
+ * - PDAs: Address derivation utilities
+ *
+ * @packageDocumentation
+ */
+export * from './cryptography/cryptography.js';
+export * from './cryptography/rescueCipher.js';
+export * from './cryptography/cSplRescueCipher.js';
+export * from './cryptography/rescuePrimeHash.js';
+export * from './cryptography/rescueDesc.js';
+export * from './cryptography/arcisEd25519.js';
+export * from './cryptography/aes128Cipher.js';
+export * from './cryptography/aes192Cipher.js';
+export * from './cryptography/aes256Cipher.js';
+export * from './arcis/arcisModule.js';
+export * from './arcis/arcisType.js';
+export { createPacker, type Packer } from './arcis/packer.js';
+export * from './matrix.js';
+export * from './onchain.js';
+export type { MempoolPriorityFeeStats } from './onchain.js';
+export * from './localEnv.js';
+export * from './callback.js';
+export * from './idl/index.js';
+export * from './pda.js';
+export { isNullRef, type ComputationReference } from './utils.js';
+export { x25519 } from '@noble/curves/ed25519';

package/src/localEnv.ts

@@ -0,0 +1,39 @@
+import { isBrowser } from './utils.js';
+
+/**
+ * Structure representing the local Arcium environment variables required for local development or testing.
+ */
+export type ArciumLocalEnv = {
+    arciumClusterOffset: number,
+    arciumBackupClusterOffset: number,
+}
+
+/**
+ * Read local Arcium environment information from environment variables.
+ * Only available in Node.js and when testing locally.
+ * @returns Local Arcium environment configuration.
+ * @throws Error if called in a browser or if required environment variables are missing or invalid.
+ */
+export function getArciumEnv(): ArciumLocalEnv {
+    if (isBrowser()) {
+        throw new Error('Arcium local env is not available in browser.');
+    }
+    try {
+        const arciumClusterOffset = Number(process.env.ARCIUM_CLUSTER_OFFSET);
+        if (isNaN(arciumClusterOffset)) {
+            throw new Error('ARCIUM_CLUSTER_OFFSET environment variable is not set or is invalid (NaN).');
+        }
+        const arciumBackupClusterOffset = process.env.ARCIUM_BACKUP_CLUSTER_OFFSET;
+        const arciumBackupClusterOffsetNumber = Number(arciumBackupClusterOffset);
+        if (typeof arciumBackupClusterOffset !== 'undefined' && isNaN(arciumBackupClusterOffsetNumber)) {
+            throw new Error('ARCIUM_BACKUP_CLUSTER_OFFSET environment variable is invalid (NaN).');
+        }
+        return {
+            arciumClusterOffset,
+            arciumBackupClusterOffset: arciumBackupClusterOffsetNumber,
+        };
+    }
+    catch (e) {
+        throw new Error(`Encountered error while trying to parse env vars: ${e}`);
+    }
+}

package/src/matrix.ts

@@ -0,0 +1,215 @@
+import { FpField } from './cryptography/rescueDesc.js';
+import { generateRandomFieldElem } from './cryptography/cryptography.js';
+import { getBinSize } from './utils.js';
+import {
+    ctLt,
+    ctAdd,
+    ctSelect,
+    ctSub,
+    ctSignBit,
+} from './ctUtils.js';
+
+/**
+ * Matrix operations for MPC field arithmetic.
+ * Used internally by Rescue cipher. Not part of public API.
+ * @internal
+ */
+export class Matrix {
+    field: FpField;
+
+    data: readonly bigint[][];
+
+    constructor(field: FpField, data: readonly bigint[][]) {
+        this.field = field;
+        const nrows = data.length;
+        const ncols = data[0].length;
+        for (let i = 1; i < nrows; ++i) {
+            if (data[i].length !== ncols) {
+                throw Error('All rows must have same number of columns.');
+            }
+        }
+        this.data = data.map((row) => row.map((c) => field.create(c)));
+    }
+
+    /**
+     * Matrix multiplication between `this` and `rhs`.
+     */
+    matMul(rhs: Matrix): Matrix {
+        const thisNrows = this.data.length;
+        const thisNcols = this.data[0].length;
+        const rhsNrows = rhs.data.length;
+        const rhsNcols = rhs.data[0].length;
+        if (thisNcols !== rhsNrows) {
+            throw Error(`this.ncols must be equal to rhs.nrows (found ${thisNcols} and ${rhsNrows})`);
+        }
+        const data = [];
+        for (let i = 0; i < thisNrows; ++i) {
+            const row = [];
+            for (let j = 0; j < rhsNcols; ++j) {
+                let c = this.field.ZERO;
+                for (let k = 0; k < thisNcols; ++k) {
+                    c = this.field.add(c, this.field.mul(this.data[i][k], rhs.data[k][j]));
+                }
+                row.push(c);
+            }
+            data.push(row);
+        }
+        return new Matrix(this.field, data);
+    }
+
+    /**
+     * Element-wise addition between `this` and `rhs`.
+     */
+    add(rhs: Matrix, ct: boolean = false): Matrix {
+        const thisNrows = this.data.length;
+        const thisNcols = this.data[0].length;
+        const rhsNrows = rhs.data.length;
+        const rhsNcols = rhs.data[0].length;
+        if (thisNrows !== rhsNrows) {
+            throw Error(`this.nrows must be equal to rhs.nrows (found ${thisNrows} and ${rhsNrows})`);
+        }
+        if (thisNcols !== rhsNcols) {
+            throw Error(`this.ncols must be equal to rhs.ncols (found ${thisNcols} and ${rhsNcols})`);
+        }
+        const binSize = getBinSize(this.field.ORDER - 1n);
+        const data = [];
+        for (let i = 0; i < thisNrows; ++i) {
+            const row = [];
+            for (let j = 0; j < thisNcols; ++j) {
+                if (ct) {
+                    const sum = ctAdd(this.data[i][j], rhs.data[i][j], binSize);
+                    row.push(ctSelect(ctLt(sum, this.field.ORDER, binSize), sum, ctSub(sum, this.field.ORDER, binSize), binSize));
+                }
+                else {
+                    row.push(this.field.add(this.data[i][j], rhs.data[i][j]));
+                }
+            }
+            data.push(row);
+        }
+        return new Matrix(this.field, data);
+    }
+
+    /**
+     * Element-wise subtraction between `this` and `rhs`.
+     */
+    sub(rhs: Matrix, ct: boolean = false): Matrix {
+        const thisNrows = this.data.length;
+        const thisNcols = this.data[0].length;
+        const rhsNrows = rhs.data.length;
+        const rhsNcols = rhs.data[0].length;
+        if (thisNrows !== rhsNrows) {
+            throw Error(`this.nrows must be equal to rhs.nrows (found ${thisNrows} and ${rhsNrows})`);
+        }
+        if (thisNcols !== rhsNcols) {
+            throw Error(`this.ncols must be equal to rhs.ncols (found ${thisNcols} and ${rhsNcols})`);
+        }
+        const binSize = getBinSize(this.field.ORDER - 1n);
+        const data = [];
+        for (let i = 0; i < thisNrows; ++i) {
+            const row = [];
+            for (let j = 0; j < thisNcols; ++j) {
+                if (ct) {
+                    const diff = ctSub(this.data[i][j], rhs.data[i][j], binSize);
+                    row.push(ctSelect(ctSignBit(diff, binSize), ctAdd(diff, this.field.ORDER, binSize), diff, binSize));
+                }
+                else {
+                    row.push(this.field.sub(this.data[i][j], rhs.data[i][j]));
+                }
+            }
+            data.push(row);
+        }
+        return new Matrix(this.field, data);
+    }
+
+    /**
+     * Raises each element of `this` to the power `e`.
+     */
+    pow(e: bigint): Matrix {
+        const data = [];
+        for (let i = 0; i < this.data.length; ++i) {
+            const row = [];
+            for (let j = 0; j < this.data[0].length; ++j) {
+                row.push(this.field.pow(this.data[i][j], e));
+            }
+            data.push(row);
+        }
+        return new Matrix(this.field, data);
+    }
+
+    /**
+     * Compute the determinant using Gauss elimination.
+     * Match the determinant implementation in Arcis.
+     */
+    det(): bigint {
+        // Ensure the matrix is square
+        const n = this.data.length;
+        if (n === 0 || !this.is_square()) {
+            throw Error('Matrix must be square and non-empty to compute the determinant.');
+        }
+
+        let det = this.field.ONE;
+        // Clone the data to avoid mutating the original matrix
+        let rows = this.data.map((row) => [...row]);
+
+        for (let i = 0; i < n; ++i) {
+            // we partition into rows that have a leading zero and rows that don't
+            const lzRows = rows.filter((r) => this.field.is0(r[0]));
+            const nlzRows = rows.filter((r) => !this.field.is0(r[0]));
+
+            // take pivot element
+            const pivotRow = nlzRows.shift();
+            if (pivotRow === undefined) {
+                // no pivot row implies the rank is less than n i.e. the determinant is zero
+                return this.field.ZERO;
+            }
+            const pivot = pivotRow[0];
+
+            // multiply pivot onto the determinant
+            det = this.field.mul(det, pivot);
+
+            // subtract all leading non zero values with the pivot element (forward elimination).
+
+            const pivotInverse = this.field.inv(pivot);
+            // precomputing pivot row such that the leading value is one. This reduces the number of
+            // multiplications in the forward elimination multiplications by 50%
+            const normalizedPivotRow = pivotRow.map((v) => this.field.mul(pivotInverse, v));
+
+            // forward elimination with normalized pivot row
+            const nlzRowsProcessed = nlzRows.map((row) => {
+                const lead: bigint = row[0];
+                return row.map((value, index) => this.field.sub(value, this.field.mul(lead, normalizedPivotRow[index])));
+            });
+
+            // concat the reamining rows (without pivot row) and remove the pivot column (all first
+            // elements (i.e. zeros) from the remaining rows).
+            rows = nlzRowsProcessed.concat(lzRows).map((row) => row.slice(1));
+        }
+        return det;
+    }
+
+    is_square(): boolean {
+        const n = this.data.length;
+        for (let i = 1; i < n; ++i) {
+            if (this.data[i].length !== n) {
+                return false;
+            }
+        }
+        return true;
+    }
+}
+
+/**
+ * Generate random matrix for testing.
+ * @internal
+ */
+export function randMatrix(field: FpField, nrows: number, ncols: number): Matrix {
+    const data = [];
+    for (let i = 0; i < nrows; ++i) {
+        const row = [];
+        for (let j = 0; j < ncols; ++j) {
+            row.push(generateRandomFieldElem(field.ORDER));
+        }
+        data.push(row);
+    }
+    return new Matrix(field, data);
+}