@arcium-hq/client 0.9.2 → 0.9.3

package/src/arcis/packing.ts

@@ -0,0 +1,115 @@
+/**
+ * Size descriptor for a single field in circuit packing.
+ * A "full" field occupies an entire slot; partial fields are bin-packed together.
+ * @internal
+ */
+export class DataSize {
+    /** Whether this field occupies a full slot. */
+    isFull: boolean;
+    /** Bit width of the field (0 if full). */
+    size: number;
+    /** Original index in the fields array. */
+    index: number;
+
+    constructor(index: number, size?: number) {
+        const isUndefined = size === undefined;
+        this.isFull = isUndefined;
+        this.size = isUndefined ? 0 : size;
+        this.index = index;
+    }
+}
+
+
+function sortDataSizes(arr: DataSize[]): DataSize[] {
+    return [...arr].sort((left, right) => {
+        if (left.isFull !== right.isFull) {
+            return left.isFull ? -1 : +1;
+        }
+        if (left.size !== right.size) {
+            return right.size - left.size;
+        }
+        return left.index - right.index;
+    });
+}
+
+/**
+ * Packed location of a field within the slot array.
+ * @internal
+ */
+export class PackLocation {
+    /** Slot index in the packed array. */
+    index: number;
+    /** Bit offset within the slot. */
+    offset: number;
+
+    constructor(index: number, offset: number) {
+        this.index = index;
+        this.offset = offset;
+    }
+}
+
+class PackingState {
+    maxSize: number;
+    loads: number[] = [];
+    nFull: number = 0;
+    lastInsert: number = 0;
+    constructor(maxSize: number) {
+        this.maxSize = maxSize;
+    }
+
+    getCurrentLoad(index: number): number {
+        return this.loads[index] === undefined ? 0 : this.loads[index];
+    }
+    canFit(index: number, size: number): boolean {
+        return this.getCurrentLoad(index) + size <= this.maxSize;
+    }
+    chooseInsertLocation(size: number): number {
+        if (this.canFit(this.nFull, size)) {
+            return this.nFull;
+        }
+        if (this.canFit(this.lastInsert, size)) {
+            return this.lastInsert;
+        }
+        return this.lastInsert + 1;
+    }
+    insert(size: DataSize): PackLocation {
+        if (size.isFull) {
+            this.lastInsert = this.nFull;
+            this.nFull++;
+            return new PackLocation(this.lastInsert, 0);
+        }
+        const index = this.chooseInsertLocation(size.size);
+        if (index >= this.loads.length) {
+            this.loads.push(0);
+        }
+        const load = this.loads[index];
+        this.loads[index] += size.size;
+        return new PackLocation(index, load);
+    }
+}
+
+function packing(maxSize: number, arr: DataSize[]): [number, PackLocation[]] {
+    const sortedArr = sortDataSizes(arr);
+    const inserts: [number, PackLocation][] = [];
+    const state = new PackingState(maxSize);
+    sortedArr.forEach((value) => {
+        const pack = state.insert(value);
+        inserts.push([value.index, pack]);
+    })
+    const nPacks = state.nFull + state.loads.length;
+    inserts.sort((left, right) => left[0] - right[0]);
+    const res = inserts.map((arg) => arg[1]);
+    return [nPacks, res];
+}
+
+const ARCIS_PACKING_SIZE = 214;
+
+/**
+ * Pack field sizes into minimum slots using the Arcium packing size (214 bits).
+ * @param arr - Array of field size descriptors.
+ * @returns Tuple of [total slot count, pack location for each input field].
+ * @internal
+ */
+export function arcisPacking(arr: DataSize[]): [number, PackLocation[]] {
+    return packing(ARCIS_PACKING_SIZE, arr);
+}

package/src/callback.ts

@@ -0,0 +1,101 @@
+import {
+    PublicKey,
+    Finality,
+} from '@solana/web3.js';
+import {
+    AnchorProvider, BN,
+} from '@coral-xyz/anchor';
+import { getArciumProgram } from './onchain.js';
+import { getComputationAccAddress, getMXEAccAddress } from './pda.js';
+
+const POLL_INTERVAL_MS = 500;
+
+/**
+ * Wait for a computation to finalize by polling the computation account
+ * status via HTTP RPC. Does not use WebSocket subscriptions.
+ *
+ * Polls every 500ms (same as Agave's send_and_confirm_transaction_with_config).
+ * Return the most recent transaction signature on the computation account
+ * once finalization is detected.
+ *
+ * @param provider - Anchor provider.
+ * @param computationOffset - Computation offset to wait for.
+ * @param mxeProgramId - MXE program public key.
+ * @param commitment - Commitment level for RPC calls (default: 'confirmed').
+ * @param timeoutMs - Maximum wait time in milliseconds (default: 120000).
+ * @returns Transaction signature from the finalization.
+ * @throws Error if the MXE account has no cluster assigned.
+ * @throws Error if the computation does not finalize within timeoutMs.
+ */
+export async function awaitComputationFinalization(
+    provider: AnchorProvider,
+    computationOffset: BN,
+    mxeProgramId: PublicKey,
+    commitment: Finality = 'confirmed',
+    timeoutMs: number = 120_000,
+): Promise<string> {
+    const conn = provider.connection;
+    const arciumProgram = getArciumProgram(provider);
+
+    // Derive computation account PDA (requires clusterOffset from MXE account)
+    const mxeAccAddress = getMXEAccAddress(mxeProgramId);
+    const mxeAcc = await arciumProgram.account.mxeAccount.fetch(mxeAccAddress, commitment);
+    if (mxeAcc.cluster === null) {
+        throw new Error('MXE account has no cluster assigned');
+    }
+    const compAccAddress = getComputationAccAddress(mxeAcc.cluster, computationOffset);
+
+    const startTime = Date.now();
+    let lastStatus: 'unknown' | 'queued' | 'finalized' = 'unknown';
+    let rpcErrorCount = 0;
+    let lastError: string | undefined;
+
+    while (Date.now() - startTime < timeoutMs) {
+        let compAcc;
+        try {
+            // eslint-disable-next-line no-await-in-loop
+            compAcc = await arciumProgram.account.computationAccount.fetchNullable(
+                compAccAddress, commitment,
+            );
+        }
+        catch (e) {
+            rpcErrorCount++;
+            lastError = e instanceof Error ? e.message : String(e);
+            // eslint-disable-next-line no-await-in-loop
+            await new Promise((r) => {
+                setTimeout(r, POLL_INTERVAL_MS);
+            });
+            continue;
+        }
+
+        if (compAcc !== null && 'finalized' in compAcc.status) {
+            lastStatus = 'finalized';
+            for (let sigRetry = 0; sigRetry < 10; sigRetry++) {
+                // eslint-disable-next-line no-await-in-loop
+                const sigs = await conn.getSignaturesForAddress(
+                    compAccAddress, { limit: 1 }, commitment,
+                );
+                if (sigs.length > 0) return sigs[0].signature;
+                // eslint-disable-next-line no-await-in-loop
+                await new Promise((r) => {
+                    setTimeout(r, POLL_INTERVAL_MS);
+                });
+            }
+            throw new Error(
+                'Computation finalized but transaction signature not indexed after retries.',
+            );
+        }
+
+        if (compAcc !== null) lastStatus = 'queued';
+
+        // eslint-disable-next-line no-await-in-loop
+        await new Promise((r) => {
+            setTimeout(r, POLL_INTERVAL_MS);
+        });
+    }
+
+    const timeoutMsg = `Computation did not finalize within ${timeoutMs}ms (status: ${lastStatus})`;
+    throw rpcErrorCount > 0
+        ? new Error(timeoutMsg, { cause: new Error(`${rpcErrorCount} RPC errors, last: ${lastError}`) })
+        : new Error(timeoutMsg);
+}

package/src/constants.ts

@@ -0,0 +1,104 @@
+/**
+ * Seed for ClockAccount PDA.
+ * @constant {string}
+ */
+export const CLOCK_ACC_SEED = 'ClockAccount';
+/**
+ * Seed for FeePool PDA.
+ * @constant {string}
+ */
+export const POOL_ACC_SEED = 'FeePool';
+/**
+ * Seed for ComputationAccount PDA.
+ * @constant {string}
+ */
+export const COMPUTATION_ACC_SEED = 'ComputationAccount';
+/**
+ * Seed for Mempool PDA.
+ * @constant {string}
+ */
+export const MEMPOOL_ACC_SEED = 'Mempool';
+/**
+ * Seed for ExecutingPoolAccount PDA.
+ * @constant {string}
+ */
+export const EXEC_POOL_ACC_SEED = 'Execpool';
+/**
+ * Seed for ClusterAccount PDA.
+ * @constant {string}
+ */
+export const CLUSTER_ACC_SEED = 'Cluster';
+/**
+ * Seed for ArxNodeAccount PDA.
+ * @constant {string}
+ */
+export const ARX_NODE_ACC_SEED = 'ArxNode';
+/**
+ * Seed for MXE Account PDA.
+ * @constant {string}
+ */
+export const MXE_ACCOUNT_SEED = 'MXEAccount';
+/**
+ * Seed for CompDefAccount PDA.
+ * @constant {string}
+ */
+export const COMP_DEF_ACC_SEED = 'ComputationDefinitionAccount';
+/**
+ * Seed for RecoveryClusterAccount PDA.
+ * @constant {string}
+ */
+export const RECOVERY_CLUSTER_ACC_SEED = 'RecoveryClusterAccount';
+/**
+ * Seed for MxeRecoveryAccount PDA.
+ * @constant {string}
+ */
+export const MXE_RECOVERY_ACC_SEED = 'MxeRecoveryAccount';
+/**
+ * Seed for ComputationDefinitionRaw PDA.
+ * @constant {string}
+ */
+export const RAW_CIRCUIT_ACC_SEED = 'ComputationDefinitionRaw';
+/**
+ * Maximum number of bytes that can be reallocated per instruction.
+ * @constant {number}
+ */
+export const MAX_REALLOC_PER_IX = 10240;
+/**
+ * Maximum number of bytes that can be uploaded in a single transaction with the upload instruction.
+ * @constant {number}
+ */
+export const MAX_UPLOAD_PER_TX_BYTES = 814;
+/**
+ * Maximum size of an account in bytes (10MB = 10 * 1024 * 1024).
+ * @constant {number}
+ */
+export const MAX_ACCOUNT_SIZE = 10485760;
+/**
+ * Maximum number of Arcium embiggen instructions allowed in a single transaction (due to compute unit limits).
+ * @constant {number}
+ */
+export const MAX_EMBIGGEN_IX_PER_TX = 18;
+
+/**
+ * Size of account discriminator in bytes.
+ * @constant {number}
+ */
+export const DISCRIMINATOR_SIZE = 8;
+
+/**
+ * Size of offset buffer in bytes (u32).
+ * @constant {number}
+ */
+export const OFFSET_BUFFER_SIZE = 4;
+
+/**
+ * Size of computation definition offset slice in bytes.
+ * @constant {number}
+ */
+export const COMP_DEF_OFFSET_SIZE = 4;
+
+/**
+ * Size of a uint128 in bytes.
+ * @constant {number}
+ */
+export const UINT128_BYTE_SIZE = 16;

package/src/cryptography/aes128Cipher.ts

@@ -0,0 +1,16 @@
+import { AesCtrCipher } from './aesCtrCipher.js';
+
+/**
+ * AES-128 cipher in Counter (CTR) mode, using SHA3-256 to derive the key from a shared secret.
+ * See: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38a.pdf (Section 6.5) for details on CTR mode.
+ */
+export class Aes128Cipher extends AesCtrCipher {
+    /**
+     * Construct an AES-128 cipher instance using a shared secret.
+     * The key is derived using SHA3-256.
+     * @param sharedSecret - Shared secret to derive the AES key from.
+     */
+    constructor(sharedSecret: Uint8Array) {
+        super(sharedSecret, 128);
+    }
+}

package/src/cryptography/aes192Cipher.ts

@@ -0,0 +1,16 @@
+import { AesCtrCipher } from './aesCtrCipher.js';
+
+/**
+ * AES-192 cipher in Counter (CTR) mode, using SHA3-256 to derive the key from a shared secret.
+ * See: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38a.pdf (Section 6.5) for details on CTR mode.
+ */
+export class Aes192Cipher extends AesCtrCipher {
+    /**
+     * Construct an AES-192 cipher instance using a shared secret.
+     * The key is derived using SHA3-256.
+     * @param sharedSecret - Shared secret to derive the AES key from.
+     */
+    constructor(sharedSecret: Uint8Array) {
+        super(sharedSecret, 192);
+    }
+}

package/src/cryptography/aes256Cipher.ts

@@ -0,0 +1,16 @@
+import { AesCtrCipher } from './aesCtrCipher.js';
+
+/**
+ * AES-256 cipher in Counter (CTR) mode, using SHA3-256 to derive the key from a shared secret.
+ * See: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38a.pdf (Section 6.5) for details on CTR mode.
+ */
+export class Aes256Cipher extends AesCtrCipher {
+    /**
+     * Construct an AES-256 cipher instance using a shared secret.
+     * The key is derived using SHA3-256.
+     * @param sharedSecret - Shared secret to derive the AES key from.
+     */
+    constructor(sharedSecret: Uint8Array) {
+        super(sharedSecret, 256);
+    }
+}

package/src/cryptography/aesCtrCipher.ts

@@ -0,0 +1,84 @@
+import { createHash, createCipheriv, createDecipheriv } from 'crypto';
+
+/**
+ * Supported AES key sizes in bits.
+ */
+export type AesKeyBits = 128 | 192 | 256;
+
+/**
+ * Mapping from key bits to key byte length.
+ */
+const KEY_BYTES: Record<AesKeyBits, number> = { 128: 16, 192: 24, 256: 32 };
+
+/**
+ * Generic AES cipher in Counter (CTR) mode, using SHA3-256 to derive the key from a shared secret.
+ * See: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38a.pdf (Section 6.5) for details on CTR mode.
+ */
+export class AesCtrCipher {
+    protected key: Uint8Array;
+    private readonly keyBits: AesKeyBits;
+
+    /**
+     * Construct an AES cipher instance using a shared secret.
+     * The key is derived using SHA3-256.
+     * @param sharedSecret - Shared secret to derive the AES key from.
+     * @param keyBits - AES key size in bits (128, 192, or 256).
+     */
+    constructor(sharedSecret: Uint8Array, keyBits: AesKeyBits) {
+        this.keyBits = keyBits;
+        const hasher = createHash('sha3-256');
+        // We follow [Section 4, Option 1.](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Cr2.pdf).
+        // For our choice of hash function, we have:
+        // - H_outputBits = 256
+        // - max_H_inputBits = arbitrarily long, as SHA3 is built upon the sponge
+        //   construction
+        // - L = keyBits (128, 192, or 256).
+
+        // Build the vector `counter || Z || FixedInfo` (we only have i = 1, since reps = 1).
+        // the counter is a big-endian 4-byte unsigned integer
+        const counter = [0, 0, 0, 1];
+        for (let i = 0; i < sharedSecret.length; ++i) {
+            counter.push(sharedSecret[i]);
+        }
+        // For the FixedInfo we simply take L. We represent L as a big-endian 2-byte
+        // unsigned integer.
+        counter.push(Math.floor(keyBits / 256));
+        counter.push(keyBits % 256);
+        hasher.update(new Uint8Array(counter));
+        this.key = new Uint8Array(hasher.digest()).slice(0, KEY_BYTES[keyBits]);
+    }
+
+    /**
+     * Encrypt the plaintext array in Counter (CTR) mode.
+     * @param plaintext - Data to encrypt.
+     * @param nonce - 8-byte nonce for CTR mode.
+     * @returns Encrypted ciphertext as a Uint8Array.
+     * @throws Error if the nonce is not 8 bytes long.
+     */
+    encrypt(plaintext: Uint8Array, nonce: Uint8Array): Uint8Array {
+        if (nonce.length !== 8) {
+            throw Error(`nonce must be of length 8 (found ${nonce.length})`);
+        }
+        const paddedNonce = Buffer.concat([nonce, Buffer.alloc(16 - nonce.length, 0)]);
+        const cipher = createCipheriv(`aes-${this.keyBits}-ctr`, this.key, paddedNonce);
+        const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+        return new Uint8Array(ciphertext);
+    }
+
+    /**
+     * Decrypt the ciphertext array in Counter (CTR) mode.
+     * @param ciphertext - Data to decrypt.
+     * @param nonce - 8-byte nonce for CTR mode.
+     * @returns Decrypted plaintext as a Uint8Array.
+     * @throws Error if the nonce is not 8 bytes long.
+     */
+    decrypt(ciphertext: Uint8Array, nonce: Uint8Array): Uint8Array {
+        if (nonce.length !== 8) {
+            throw Error(`nonce must be of length 8 (found ${nonce.length})`);
+        }
+        const paddedNonce = Buffer.concat([nonce, Buffer.alloc(16 - nonce.length, 0)]);
+        const cipher = createDecipheriv(`aes-${this.keyBits}-ctr`, this.key, paddedNonce);
+        const decrypted = Buffer.concat([cipher.update(ciphertext), cipher.final()]);
+        return new Uint8Array(decrypted);
+    }
+}

package/src/cryptography/arcisEd25519.ts

@@ -0,0 +1,96 @@
+import { ed25519 } from '@noble/curves/ed25519';
+import { randomBytes } from '@noble/hashes/utils';
+import { CurveFn, twistedEdwards } from '@noble/curves/abstract/edwards';
+import { isNegativeLE, mod, pow2 } from '@noble/curves/abstract/modular';
+// to please the linter
+import { sha3_512 as sha3 } from '@noble/hashes/sha3';
+
+// The arcisEd25519 signature scheme. This is essentially ed25519 but we use the hash function
+// SHA3-512 instead of SHA-512 since its multiplicative depth is much lower, which
+// makes it much better suited to be evaluated in MPC.
+
+// Those are the parameters specified [here](https://datatracker.ietf.org/doc/html/rfc8032#section-5.1)
+// (except for the hash function, see above). The below is copied from [here](https://github.com/paulmillr/noble-curves/blob/main/src/ed25519.ts).
+const arcisEd25519Defaults = (() => ({
+    a: BigInt('57896044618658097711785492504343953926634992332820282019728792003956564819948'),
+    d: BigInt('37095705934669439343138083508754565189542113879843219016388785533085940283555'),
+    Fp: ed25519.CURVE.Fp,
+    n: BigInt('7237005577332262213973186563042994240857116359379907606001950938285454250989'),
+    h: BigInt(8),
+    Gx: BigInt('15112221349535400772501151409588531511454012693041857206046113283949847762202'),
+    Gy: BigInt('46316835694926478169428394003475163141307993866256225615783033603165251855960'),
+    hash: sha3,
+    randomBytes,
+    adjustScalarBytes,
+    uvRatio,
+}) as const)();
+
+/**
+ * Ed25519 curve instance using SHA3-512 for hashing, suitable for MPC (ArcisEd25519 signature scheme).
+ * This is essentially Ed25519 but with SHA3-512 instead of SHA-512 for lower multiplicative depth.
+ * See: https://datatracker.ietf.org/doc/html/rfc8032#section-5.1
+ */
+export const arcisEd25519: CurveFn = (() => twistedEdwards(arcisEd25519Defaults))();
+
+// Helper function for the sqrt in Fp.
+function ed25519_pow_2_252_3(x: bigint) {
+    // prettier-ignore
+    const _10n = BigInt(10), _20n = BigInt(20), _40n = BigInt(40), _80n = BigInt(80);
+    const P = ed25519.CURVE.Fp.ORDER;
+    const x2 = (x * x) % P;
+    const b2 = (x2 * x) % P; // x^3, 11
+    const b4 = (pow2(b2, 2n, P) * b2) % P; // x^15, 1111
+    const b5 = (pow2(b4, 1n, P) * x) % P; // x^31
+    const b10 = (pow2(b5, 5n, P) * b5) % P;
+    const b20 = (pow2(b10, _10n, P) * b10) % P;
+    const b40 = (pow2(b20, _20n, P) * b20) % P;
+    const b80 = (pow2(b40, _40n, P) * b40) % P;
+    const b160 = (pow2(b80, _80n, P) * b80) % P;
+    const b240 = (pow2(b160, _80n, P) * b80) % P;
+    const b250 = (pow2(b240, _10n, P) * b10) % P;
+    const pow_p_5_8 = (pow2(b250, 2n, P) * x) % P;
+    // ^ To pow to (p+3)/8, multiply it by x.
+    return { pow_p_5_8, b2 };
+}
+
+// Fp.sqrt(Fp.neg(1))
+const ED25519_SQRT_M1 = /* @__PURE__ */ BigInt(
+    '19681161376707505956807079304988542015446066515923890162744021073123829784752'
+);
+
+/**
+ * Clamp a 32-byte scalar as required by the Ed25519 signature scheme.
+ * See: https://datatracker.ietf.org/doc/html/rfc8032#section-5.1.5
+ * @param bytes - 32-byte scalar to clamp.
+ * @returns Clamped scalar as a Uint8Array.
+ */
+function adjustScalarBytes(bytes: Uint8Array): Uint8Array {
+    const clamped = bytes;
+    clamped[0] &= 248;
+    clamped[31] &= 127;
+    clamped[31] |= 64;
+    return clamped;
+}
+
+/**
+ * Helper function for decompression, calculating √(u/v).
+ * @returns Object with isValid and value.
+ */
+function uvRatio(u: bigint, v: bigint): { isValid: boolean; value: bigint } {
+    const P = ed25519.CURVE.Fp.ORDER;
+    const v3 = mod(v * v * v, P); // v³
+    const v7 = mod(v3 * v3 * v, P); // v⁷
+    // (p+3)/8 and (p-5)/8
+    const pow = ed25519_pow_2_252_3(u * v7).pow_p_5_8;
+    let x = mod(u * v3 * pow, P); // (uv³)(uv⁷)^(p-5)/8
+    const vx2 = mod(v * x * x, P); // vx²
+    const root1 = x; // First root candidate
+    const root2 = mod(x * ED25519_SQRT_M1, P); // Second root candidate
+    const useRoot1 = vx2 === u; // If vx² = u (mod p), x is a square root
+    const useRoot2 = vx2 === mod(-u, P); // If vx² = -u, set x <-- x * 2^((p-1)/4)
+    const noRoot = vx2 === mod(-u * ED25519_SQRT_M1, P); // There is no valid root, vx² = -u√(-1)
+    if (useRoot1) x = root1;
+    if (useRoot2 || noRoot) x = root2; // We return root2 anyway, for const-time
+    if (isNegativeLE(x, P)) x = mod(-x, P);
+    return { isValid: useRoot1 || useRoot2, value: x };
+}

package/src/cryptography/cSplRescueCipher.ts

@@ -0,0 +1,41 @@
+import {
+    CURVE25519_SCALAR_FIELD,
+} from './rescueDesc.js';
+import { RescueCipherCommon } from './rescueCipherCommon.js';
+
+/**
+ * The Rescue cipher over Curve25519's scalar field in Counter (CTR) mode, with a fixed block size m = 5.
+ * See: https://tosc.iacr.org/index.php/ToSC/article/view/8695/8287
+ */
+export class CSplRescueCipher {
+    cipher: RescueCipherCommon;
+
+    /**
+     * Construct a CSplRescueCipher instance using a shared secret.
+     * The key is derived using RescuePrimeHash and used to initialize the RescueDesc.
+     * @param sharedSecret - Shared secret to derive the cipher key from.
+     */
+    constructor(sharedSecret: Uint8Array) {
+        this.cipher = new RescueCipherCommon(sharedSecret, CURVE25519_SCALAR_FIELD);
+    }
+
+    /**
+     * Encrypt the plaintext vector in Counter (CTR) mode and serialize each block.
+     * @param plaintext - Array of plaintext bigints to encrypt.
+     * @param nonce - 16-byte nonce for CTR mode.
+     * @returns Ciphertext as an array of arrays of numbers (each 32 bytes).
+     */
+    encrypt(plaintext: bigint[], nonce: Uint8Array): number[][] {
+        return this.cipher.encrypt(plaintext, nonce);
+    }
+
+    /**
+     * Deserialize and decrypt the ciphertext vector in Counter (CTR) mode.
+     * @param ciphertext - Array of arrays of numbers (each 32 bytes) to decrypt.
+     * @param nonce - 16-byte nonce for CTR mode.
+     * @returns Decrypted plaintext as an array of bigints.
+     */
+    decrypt(ciphertext: number[][], nonce: Uint8Array): bigint[] {
+        return this.cipher.decrypt(ciphertext, nonce);
+    }
+}

package/src/cryptography/cryptography.ts

@@ -0,0 +1,82 @@
+import { createHash, randomBytes } from 'crypto';
+import { ed25519 } from '@noble/curves/ed25519';
+
+/**
+ * Scalar field prime modulus for Curve25519: 2^252 + 27742317777372353535851937790883648493
+ */
+export const CURVE25519_SCALAR_FIELD_MODULUS = ed25519.CURVE.n;
+
+/**
+ * Generate a random value within the field bound by q.
+ * @param q - Upper bound (exclusive) for the random value.
+ * @returns Random bigint value between 0 and q-1.
+ */
+export function generateRandomFieldElem(q: bigint): bigint {
+    const byteLength = (q.toString(2).length + 7) >> 3;
+    let r: bigint;
+    do {
+        const randomBuffer = randomBytes(byteLength);
+        r = BigInt(`0x${randomBuffer.toString('hex')}`);
+    } while (r >= q);
+    return r;
+}
+
+/**
+ * Compute the positive modulo of a over m.
+ * @param a - Dividend.
+ * @param m - Modulus.
+ * @returns Positive remainder of a mod m.
+ */
+export function positiveModulo(a: bigint, m: bigint): bigint {
+    return ((a % m) + m) % m;
+}
+
+/**
+ * Serialize a bigint to a little-endian Uint8Array of the specified length.
+ * @param val - Bigint value to serialize.
+ * @param lengthInBytes - Desired length of the output array.
+ * @returns Serialized value as a Uint8Array.
+ * @throws Error if the value is too large for the specified length.
+ */
+export function serializeLE(val: bigint, lengthInBytes: number): Uint8Array {
+    const result = new Uint8Array(lengthInBytes);
+    let tempVal = val;
+
+    for (let i = 0; i < lengthInBytes; i++) {
+        result[i] = Number(tempVal & BigInt(255));
+        tempVal >>= BigInt(8);
+    }
+
+    if (tempVal > BigInt(0)) {
+        throw new Error(`Value ${val} is too large for the byte length ${lengthInBytes}`);
+    }
+
+    return result;
+}
+
+/**
+ * Deserialize a little-endian Uint8Array to a bigint.
+ * @param bytes - Uint8Array to deserialize.
+ * @returns Deserialized bigint value.
+ */
+export function deserializeLE(bytes: Uint8Array): bigint {
+    let result = BigInt(0);
+    for (let i = 0; i < bytes.length; i++) {
+        result |= BigInt(bytes[i]) << (BigInt(i) * BigInt(8));
+    }
+    return result;
+}
+
+// GENERAL
+/**
+ * Compute the SHA-256 hash of an array of Uint8Arrays.
+ * @param byteArrays - Arrays to hash.
+ * @returns SHA-256 hash as a Buffer.
+ */
+export function sha256(byteArrays: Uint8Array[]): Buffer {
+    const hash = createHash('sha256');
+    byteArrays.forEach((byteArray) => {
+        hash.update(byteArray);
+    });
+    return hash.digest();
+}