UNPKG

@arcium-hq/client

Version:

Client SDK for interacting with encrypted Solana programs

1,413 lines (1,402 loc) 267 kB
import { IField } from '@noble/curves/abstract/modular'; import { CurveFn } from '@noble/curves/abstract/edwards'; import * as anchor from '@coral-xyz/anchor'; import { AnchorProvider, Program, BN } from '@coral-xyz/anchor'; import { PublicKey, Finality } from '@solana/web3.js'; export { x25519 } from '@noble/curves/ed25519'; /** * Scalar field prime modulus for Curve25519: 2^252 + 27742317777372353535851937790883648493 */ declare const CURVE25519_SCALAR_FIELD_MODULUS: bigint; /** * Generates a random value within the field bound by q. * @param q - The upper bound (exclusive) for the random value. * @returns A random bigint value between 0 and q-1. */ declare function generateRandomFieldElem(q: bigint): bigint; /** * Computes the positive modulo of a over m. * @param a - The dividend. * @param m - The modulus. * @returns The positive remainder of a mod m. */ declare function positiveModulo(a: bigint, m: bigint): bigint; /** * Serializes a bigint to a little-endian Uint8Array of the specified length. * @param val - The bigint value to serialize. * @param lengthInBytes - The desired length of the output array. * @returns The serialized value as a Uint8Array. * @throws Error if the value is too large for the specified length. */ declare function serializeLE(val: bigint, lengthInBytes: number): Uint8Array; /** * Deserializes a little-endian Uint8Array to a bigint. * @param bytes - The Uint8Array to deserialize. * @returns The deserialized bigint value. */ declare function deserializeLE(bytes: Uint8Array): bigint; /** * Computes the SHA-256 hash of an array of Uint8Arrays. * @param byteArrays - The arrays to hash. * @returns The SHA-256 hash as a Buffer. */ declare function sha256(byteArrays: Uint8Array[]): Buffer; /** * Matrix class over FpField. Data is row-major. */ declare class Matrix { field: FpField; data: readonly bigint[][]; constructor(field: FpField, data: readonly bigint[][]); /** * Matrix multiplication between `this` and `rhs`. */ matMul(rhs: Matrix): Matrix; /** * Element-wise addition between `this` and `rhs`. */ add(rhs: Matrix, ct?: boolean): Matrix; /** * Element-wise subtraction between `this` and `rhs`. */ sub(rhs: Matrix, ct?: boolean): Matrix; /** * Raises each element of `this` to the power `e`. */ pow(e: bigint): Matrix; /** * computs the determinant using gaus elimination * matches the determinant implementation in arcis */ det(): bigint; is_square(): boolean; } declare function randMatrix(field: FpField, nrows: number, ncols: number): Matrix; /** * Represents the operational mode for the Rescue cryptographic primitive. * Can be either a block cipher mode with a key, or a hash function mode with parameters. */ type RescueMode = BlockCipher | HashFunction; /** * Block cipher mode configuration for Rescue. * Uses a key for encryption/decryption operations. */ type BlockCipher = { kind: 'cipher'; key: bigint[]; }; /** * Hash function mode configuration for Rescue. * @param m - The rate (number of field elements absorbed per round). * @param capacity - The capacity (number of field elements in the state that are not directly accessible). */ type HashFunction = { kind: 'hash'; m: number; capacity: number; }; /** * Field type for Curve25519 base field. */ type FpField = IField<bigint>; /** * Curve25519 base field as an IField instance. */ declare const CURVE25519_BASE_FIELD: FpField; /** * Description and parameters for the Rescue cipher or hash function, including round constants, MDS matrix, and key schedule. * See: https://tosc.iacr.org/index.php/ToSC/article/view/8695/8287 */ declare class RescueDesc { mode: RescueMode; field: FpField; alpha: bigint; alphaInverse: bigint; nRounds: number; m: number; mdsMat: Matrix; mdsMatInverse: Matrix; roundKeys: Matrix[]; /** * Constructs a RescueDesc for a given field and mode (cipher or hash). * Initializes round constants, MDS matrix, and key schedule. * @param field - The field to use (e.g., CURVE25519_BASE_FIELD). * @param mode - The mode: block cipher or hash function. */ constructor(field: FpField, mode: RescueMode); /** * Samples round constants for the Rescue permutation, using SHAKE256. * @param nRounds - The number of rounds. * @returns An array of round constant matrices. */ sampleConstants(nRounds: number): Matrix[]; /** * Applies the Rescue permutation to a state matrix. * @param state - The input state matrix. * @returns The permuted state matrix. */ permute(state: Matrix): Matrix; /** * Applies the inverse Rescue permutation to a state matrix. * @param state - The input state matrix. * @returns The inverse-permuted state matrix. */ permuteInverse(state: Matrix): Matrix; } declare function toVec(data: bigint[]): bigint[][]; /** * The Rescue cipher in Counter (CTR) mode, with a fixed block size m = 5. * See: https://tosc.iacr.org/index.php/ToSC/article/view/8695/8287 */ declare class RescueCipher { desc: RescueDesc; /** * Constructs a RescueCipher instance using a shared secret. * The key is derived using HKDF-RescuePrime and used to initialize the RescueDesc. * @param sharedSecret - The shared secret to derive the cipher key from. */ constructor(sharedSecret: Uint8Array); /** * Encrypts the plaintext vector in Counter (CTR) mode (raw, returns bigints). * @param plaintext - The array of plaintext bigints to encrypt. * @param nonce - A 16-byte nonce for CTR mode. * @returns The ciphertext as an array of bigints. * @throws Error if the nonce is not 16 bytes long. */ encrypt_raw(plaintext: bigint[], nonce: Uint8Array): bigint[]; /** * Encrypts the plaintext vector in Counter (CTR) mode and serializes each block. * @param plaintext - The array of plaintext bigints to encrypt. * @param nonce - A 16-byte nonce for CTR mode. * @returns The ciphertext as an array of arrays of numbers (each 32 bytes). */ encrypt(plaintext: bigint[], nonce: Uint8Array): number[][]; /** * Decrypts the ciphertext vector in Counter (CTR) mode (raw, expects bigints). * @param ciphertext - The array of ciphertext bigints to decrypt. * @param nonce - A 16-byte nonce for CTR mode. * @returns The decrypted plaintext as an array of bigints. * @throws Error if the nonce is not 16 bytes long. */ decrypt_raw(ciphertext: bigint[], nonce: Uint8Array): bigint[]; /** * Deserializes and decrypts the ciphertext vector in Counter (CTR) mode. * @param ciphertext - The array of arrays of numbers (each 32 bytes) to decrypt. * @param nonce - A 16-byte nonce for CTR mode. * @returns The decrypted plaintext as an array of bigints. */ decrypt(ciphertext: number[][], nonce: Uint8Array): bigint[]; } /** * The Rescue-Prime hash function, as described in https://eprint.iacr.org/2020/1143.pdf. * Used with fixed m = 6 and capacity = 1 (rate = 5). According to Section 2.2, this offers log2(CURVE25519_BASE_FIELD.ORDER) / 2 bits of security against collision, preimage, and second-preimage attacks. * See the referenced paper for further details. */ declare class RescuePrimeHash { desc: RescueDesc; rate: number; /** * Constructs a RescuePrimeHash instance with m = 6 and capacity = 1. */ constructor(); /** * Computes the Rescue-Prime hash of a message, with padding as described in Algorithm 2 of the paper. * @param message - The input message as an array of bigints. * @returns The hash output as an array of bigints (length = rate). */ digest(message: bigint[]): bigint[]; } /** * 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 */ declare const arcisEd25519: CurveFn; /** * AES-128 cipher in Counter (CTR) mode, using HKDF-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. */ declare class Aes128Cipher { key: Uint8Array; /** * Constructs an AES-128 cipher instance using a shared secret. * The key is derived using HKDF-SHA3-256. * @param sharedSecret - The shared secret to derive the AES key from. */ constructor(sharedSecret: Uint8Array); /** * Encrypts the plaintext array in Counter (CTR) mode. * @param plaintext - The data to encrypt. * @param nonce - An 8-byte nonce for CTR mode. * @returns The encrypted ciphertext as a Uint8Array. * @throws Error if the nonce is not 8 bytes long. */ encrypt(plaintext: Uint8Array, nonce: Uint8Array): Uint8Array; /** * Decrypts the ciphertext array in Counter (CTR) mode. * @param ciphertext - The data to decrypt. * @param nonce - An 8-byte nonce for CTR mode. * @returns The decrypted plaintext as a Uint8Array. * @throws Error if the nonce is not 8 bytes long. */ decrypt(ciphertext: Uint8Array, nonce: Uint8Array): Uint8Array; } /** * AES-192 cipher in Counter (CTR) mode, using HKDF-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. */ declare class Aes192Cipher { key: Uint8Array; /** * Constructs an AES-192 cipher instance using a shared secret. * The key is derived using HKDF-SHA3-256. * @param sharedSecret - The shared secret to derive the AES key from. */ constructor(sharedSecret: Uint8Array); /** * Encrypts the plaintext array in Counter (CTR) mode. * @param plaintext - The data to encrypt. * @param nonce - An 8-byte nonce for CTR mode. * @returns The encrypted ciphertext as a Uint8Array. * @throws Error if the nonce is not 8 bytes long. */ encrypt(plaintext: Uint8Array, nonce: Uint8Array): Uint8Array; /** * Decrypts the ciphertext array in Counter (CTR) mode. * @param ciphertext - The data to decrypt. * @param nonce - An 8-byte nonce for CTR mode. * @returns The decrypted plaintext as a Uint8Array. * @throws Error if the nonce is not 8 bytes long. */ decrypt(ciphertext: Uint8Array, nonce: Uint8Array): Uint8Array; } /** * AES-256 cipher in Counter (CTR) mode, using HKDF-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. */ declare class Aes256Cipher { key: Uint8Array; /** * Constructs an AES-256 cipher instance using a shared secret. * The key is derived using HKDF-SHA3-256. * @param sharedSecret - The shared secret to derive the AES key from. */ constructor(sharedSecret: Uint8Array); /** * Encrypts the plaintext array in Counter (CTR) mode. * @param plaintext - The data to encrypt. * @param nonce - An 8-byte nonce for CTR mode. * @returns The encrypted ciphertext as a Uint8Array. * @throws Error if the nonce is not 8 bytes long. */ encrypt(plaintext: Uint8Array, nonce: Uint8Array): Uint8Array; /** * Decrypts the ciphertext array in Counter (CTR) mode. * @param ciphertext - The data to decrypt. * @param nonce - An 8-byte nonce for CTR mode. * @returns The decrypted plaintext as a Uint8Array. * @throws Error if the nonce is not 8 bytes long. */ decrypt(ciphertext: Uint8Array, nonce: Uint8Array): Uint8Array; } /** * Program IDL in camelCase format in order to be used in JS/TS. * * Note that this is only a type helper and is not the actual IDL. The original * IDL can be found at `target/idl/arcium.json`. */ type Arcium = { "address": "BKck65TgoKRokMjQM3datB9oRwJ8rAj2jxPXvHXUvcL6"; "metadata": { "name": "arcium"; "version": "0.3.0"; "spec": "0.1.0"; "description": "The Arcium program"; }; "instructions": [ { "name": "activateArx"; "discriminator": [ 15, 203, 48, 186, 243, 85, 60, 115 ]; "accounts": [ { "name": "signer"; "writable": true; "signer": true; }, { "name": "arxNodeAcc"; "writable": true; "pda": { "seeds": [ { "kind": "const"; "value": [ 65, 114, 120, 78, 111, 100, 101 ]; }, { "kind": "arg"; "path": "nodeOffset"; } ]; }; }, { "name": "clock"; "writable": true; "pda": { "seeds": [ { "kind": "const"; "value": [ 67, 108, 111, 99, 107, 65, 99, 99, 111, 117, 110, 116 ]; } ]; }; } ]; "args": [ { "name": "nodeOffset"; "type": "u32"; } ]; }, { "name": "activateCluster"; "discriminator": [ 228, 170, 10, 172, 246, 96, 63, 154 ]; "accounts": [ { "name": "authority"; "writable": true; "signer": true; }, { "name": "clusterAcc"; "writable": true; "pda": { "seeds": [ { "kind": "const"; "value": [ 67, 108, 117, 115, 116, 101, 114 ]; }, { "kind": "arg"; "path": "id"; } ]; }; }, { "name": "clock"; "pda": { "seeds": [ { "kind": "const"; "value": [ 67, 108, 111, 99, 107, 65, 99, 99, 111, 117, 110, 116 ]; } ]; }; }, { "name": "systemProgram"; "address": "11111111111111111111111111111111"; } ]; "args": [ { "name": "clusterId"; "type": "u32"; } ]; }, { "name": "bumpEpochCluster"; "discriminator": [ 172, 203, 90, 207, 128, 221, 229, 246 ]; "accounts": [ { "name": "signer"; "writable": true; "signer": true; }, { "name": "clusterAcc"; "writable": true; "pda": { "seeds": [ { "kind": "const"; "value": [ 67, 108, 117, 115, 116, 101, 114 ]; }, { "kind": "arg"; "path": "clusterOffset"; } ]; }; }, { "name": "clock"; "pda": { "seeds": [ { "kind": "const"; "value": [ 67, 108, 111, 99, 107, 65, 99, 99, 111, 117, 110, 116 ]; } ]; }; } ]; "args": [ { "name": "clusterOffset"; "type": "u32"; } ]; }, { "name": "callbackComputation"; "discriminator": [ 11, 224, 42, 236, 0, 154, 74, 163 ]; "accounts": [ { "name": "signer"; "writable": true; "signer": true; }, { "name": "node"; "pda": { "seeds": [ { "kind": "const"; "value": [ 65, 114, 120, 78, 111, 100, 101 ]; }, { "kind": "arg"; "path": "nodeOffset"; } ]; }; }, { "name": "mxe"; "pda": { "seeds": [ { "kind": "const"; "value": [ 77, 88, 69, 65, 99, 99, 111, 117, 110, 116 ]; }, { "kind": "arg"; "path": "mxeProgram"; } ]; }; }, { "name": "clusterAcc"; "writable": true; "pda": { "seeds": [ { "kind": "const"; "value": [ 67, 108, 117, 115, 116, 101, 114 ]; }, { "kind": "account"; "path": "mxe.cluster.ok_or(ArciumError :: ClusterNotSet) ? "; "account": "mxeAccount"; } ]; }; }, { "name": "comp"; "writable": true; "pda": { "seeds": [ { "kind": "const"; "value": [ 67, 111, 109, 112, 117, 116, 97, 116, 105, 111, 110, 65, 99, 99, 111, 117, 110, 116 ]; }, { "kind": "arg"; "path": "mxeProgram"; }, { "kind": "arg"; "path": "compOffset"; } ]; }; }, { "name": "mempool"; "writable": true; "pda": { "seeds": [ { "kind": "const"; "value": [ 77, 101, 109, 112, 111, 111, 108 ]; }, { "kind": "arg"; "path": "mxeProgram"; } ]; }; }, { "name": "executingPool"; "writable": true; "pda": { "seeds": [ { "kind": "const"; "value": [ 69, 120, 101, 99, 112, 111, 111, 108 ]; }, { "kind": "arg"; "path": "mxeProgram"; } ]; }; }, { "name": "compDefAcc"; "pda": { "seeds": [ { "kind": "const"; "value": [ 67, 111, 109, 112, 117, 116, 97, 116, 105, 111, 110, 68, 101, 102, 105, 110, 105, 116, 105, 111, 110, 65, 99, 99, 111, 117, 110, 116 ]; }, { "kind": "arg"; "path": "mxeProgram"; }, { "kind": "arg"; "path": "compDefOffset"; } ]; }; }, { "name": "systemProgram"; "address": "11111111111111111111111111111111"; }, { "name": "instructionsSysvar"; "address": "Sysvar1nstructions1111111111111111111111111"; } ]; "args": [ { "name": "compOffset"; "type": "u64"; }, { "name": "nodeOffset"; "type": "u32"; }, { "name": "compDefOffset"; "type": "u32"; }, { "name": "mxeProgram"; "type": "pubkey"; }, { "name": "executionStatus"; "type": { "defined": { "name": "executionStatus"; }; }; } ]; }, { "name": "deactivateArx"; "discriminator": [ 117, 244, 137, 148, 25, 190, 175, 164 ]; "accounts": [ { "name": "signer"; "writable": true; "signer": true; }, { "name": "arxNodeAcc"; "writable": true; "pda": { "seeds": [ { "kind": "const"; "value": [ 65, 114, 120, 78, 111, 100, 101 ]; }, { "kind": "arg"; "path": "nodeOffset"; } ]; }; }, { "name": "clock"; "pda": { "seeds": [ { "kind": "const"; "value": [ 67, 108, 111, 99, 107, 65, 99, 99, 111, 117, 110, 116 ]; } ]; }; }, { "name": "clusterAcc0"; "optional": true; "pda": { "seeds": [ { "kind": "const"; "value": [ 67, 108, 117, 115, 116, 101, 114 ]; }, { "kind": "account"; "path": "arx_node_acc.cluster_memberships"; "account": "arxNode"; } ]; }; }, { "name": "clusterAcc1"; "optional": true; "pda": { "seeds": [ { "kind": "const"; "value": [ 67, 108, 117, 115, 116, 101, 114 ]; }, { "kind": "account"; "path": "arx_node_acc.cluster_memberships.get(1).ok_or(ArciumError ::\nInvalidClusterMembership) ? "; "account": "arxNode"; } ]; }; }, { "name": "clusterAcc2"; "optional": true; "pda": { "seeds": [ { "kind": "const"; "value": [ 67, 108, 117, 115, 116, 101, 114 ]; }, { "kind": "account"; "path": "arx_node_acc.cluster_memberships.get(2).ok_or(ArciumError ::\nInvalidClusterMembership) ? "; "account": "arxNode"; } ]; }; }, { "name": "clusterAcc3"; "optional": true; "pda": { "seeds": [ { "kind": "const"; "value": [ 67, 108, 117, 115, 116, 101, 114 ]; }, { "kind": "account"; "path": "arx_node_acc.cluster_memberships.get(3).ok_or(ArciumError ::\nInvalidClusterMembership) ? "; "account": "arxNode"; } ]; }; }, { "name": "clusterAcc4"; "optional": true; "pda": { "seeds": [ { "kind": "const"; "value": [ 67, 108, 117, 115, 116, 101, 114 ]; }, { "kind": "account"; "path": "arx_node_acc.cluster_memberships.get(4).ok_or(ArciumError ::\nInvalidClusterMembership) ? "; "account": "arxNode"; } ]; }; }, { "name": "clusterAcc5"; "optional": true; "pda": { "seeds": [ { "kind": "const"; "value": [ 67, 108, 117, 115, 116, 101, 114 ]; }, { "kind": "account"; "path": "arx_node_acc.cluster_memberships.get(5).ok_or(ArciumError ::\nInvalidClusterMembership) ? "; "account": "arxNode"; } ]; }; }, { "name": "clusterAcc6"; "optional": true; "pda": { "seeds": [ { "kind": "const"; "value": [ 67, 108, 117, 115, 116, 101, 114 ]; }, { "kind": "account"; "path": "arx_node_acc.cluster_memberships.get(6).ok_or(ArciumError ::\nInvalidClusterMembership) ? "; "account": "arxNode"; } ]; }; }, { "name": "clusterAcc7"; "optional": true; "pda": { "seeds": [ { "kind": "const"; "value": [ 67, 108, 117, 115, 116, 101, 114 ]; }, { "kind": "account"; "path": "arx_node_acc.cluster_memberships.get(7).ok_or(ArciumError ::\nInvalidClusterMembership) ? "; "account": "arxNode"; } ]; }; }, { "name": "clusterAcc8"; "optional": true; "pda": { "seeds": [ { "kind": "const"; "value": [ 67, 108, 117, 115, 116, 101, 114 ]; }, { "kind": "account"; "path": "arx_node_acc.cluster_memberships.get(8).ok_or(ArciumError ::\nInvalidClusterMembership) ? "; "account": "arxNode"; } ]; }; }, { "name": "clusterAcc9"; "optional": true; "pda": { "seeds": [ { "kind": "const"; "value": [ 67, 108, 117, 115, 116, 101, 114 ]; }, { "kind": "account"; "path": "arx_node_acc.cluster_memberships.get(9).ok_or(ArciumError ::\nInvalidClusterMembership) ? "; "account": "arxNode"; } ]; }; } ]; "args": [ { "name": "nodeOffset"; "type": "u32"; } ]; }, { "name": "deactivateCluster"; "discriminator": [ 13, 42, 182, 159, 184, 10, 212, 178 ]; "accounts": [ { "name": "authority"; "writable": true; "signer": true; }, { "name": "clusterAcc"; "writable": true; "pda": { "seeds": [ { "kind": "const"; "value": [ 67, 108, 117, 115, 116, 101, 114 ]; }, { "kind": "arg"; "path": "id"; } ]; }; }, { "name": "clock"; "pda": { "seeds": [ { "kind": "const"; "value": [ 67, 108, 111, 99, 107, 65, 99, 99, 111, 117, 110, 116 ]; } ]; }; }, { "name": "systemProgram"; "address": "11111111111111111111111111111111"; } ]; "args": [ { "name": "clusterId"; "type": "u32"; }, { "name": "deactivationEpoch"; "type": { "defined": { "name": "epoch"; }; }; } ]; }, { "name": "dummyInstruction"; "docs": [ "Only present so the mempool and execpool accounts are actually included in the idl, since we", "don't explicitly declare them in the accounts section of the other instructions." ]; "discriminator": [ 57, 4, 200, 151, 58, 19, 120, 9 ]; "accounts": [ { "name": "tinyMempool"; }, { "name": "tinyExecpool"; }, { "name": "smallMempool"; }, { "name": "smallExecpool"; }, { "name": "mediumMempool"; }, { "name": "mediumExecpool"; }, { "name": "largeMempool"; }, { "name": "largeExecpool"; } ]; "args": []; }, { "name": "embiggenRawCircuitAcc"; "discriminator": [ 92, 195, 192, 21, 193, 242, 135, 194 ]; "accounts": [ { "name": "signer"; "writable": true; "signer": true; }, { "name": "compDefAcc"; "pda": { "seeds": [ { "kind": "const"; "value": [ 67, 111, 109, 112, 117, 116, 97, 116, 105, 111, 110, 68, 101, 102, 105, 110, 105, 116, 105, 111, 110, 65, 99, 99, 111, 117, 110, 116 ]; }, { "kind": "arg"; "path": "mxeProgram"; }, { "kind": "arg"; "path": "compOffset"; } ]; }; }, { "name": "compDefRaw"; "writable": true; "pda": { "seeds": [ { "kind": "const"; "value": [ 67, 111, 109, 112, 117, 116, 97, 116, 105, 111, 110, 68, 101, 102, 105, 110, 105, 116, 105, 111, 110, 82, 97, 119 ]; }, { "kind": "account"; "path": "compDefAcc"; }, { "kind": "arg"; "path": "rawCircuitIndex"; } ]; }; }, { "name": "systemProgram"; "address": "11111111111111111111111111111111"; } ]; "args": [ { "name": "compOffset"; "type": "u32"; }, { "name": "mxeProgram"; "type": "pubkey"; }, { "name": "rawCircuitIndex"; "type": "u8"; } ]; }, { "name": "finalizeComputation"; "discriminator": [ 43, 29, 152, 92, 241, 179, 193,