@arcium-hq/client
Version:
Client SDK for interacting with encrypted Solana programs
1,412 lines (1,400 loc) • 274 kB
TypeScript
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 RescuePrimeHash 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, offering 256 bits
* of security against collision, preimage and second-preimage attacks for any field of size at least 102 bits.
* We use the sponge construction with fixed rate = 7 and capacity = 5 (i.e., m = 12), and truncate the
* output to 5 field elements.
*/
declare class RescuePrimeHash {
desc: RescueDesc;
rate: number;
digestLength: number;
/**
* Constructs a RescuePrimeHash instance with rate = 7 and capacity = 5.
*/
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 = digestLength).
*/
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;
/**
* Supported AES key sizes in bits.
*/
type AesKeyBits = 128 | 192 | 256;
/**
* 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.
*/
declare class AesCtrCipher {
protected key: Uint8Array;
private readonly keyBits;
/**
* Constructs an AES cipher instance using a shared secret.
* The key is derived using SHA3-256.
* @param sharedSecret - The shared secret to derive the AES key from.
* @param keyBits - The AES key size in bits (128, 192, or 256).
*/
constructor(sharedSecret: Uint8Array, keyBits: AesKeyBits);
/**
* 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-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.
*/
declare class Aes128Cipher extends AesCtrCipher {
/**
* Constructs an AES-128 cipher instance using a shared secret.
* The key is derived using SHA3-256.
* @param sharedSecret - The shared secret to derive the AES key from.
*/
constructor(sharedSecret: Uint8Array);
}
/**
* 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.
*/
declare class Aes192Cipher extends AesCtrCipher {
/**
* Constructs an AES-192 cipher instance using a shared secret.
* The key is derived using SHA3-256.
* @param sharedSecret - The shared secret to derive the AES key from.
*/
constructor(sharedSecret: Uint8Array);
}
/**
* 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.
*/
declare class Aes256Cipher extends AesCtrCipher {
/**
* Constructs an AES-256 cipher instance using a shared secret.
* The key is derived using SHA3-256.
* @param sharedSecret - The shared secret to derive the AES key from.
*/
constructor(sharedSecret: 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": "F3G6Q9tRicyznCqcZLydJ6RxkwDSBeHWM458J7V6aeyk";
"metadata": {
"name": "arcium";
"version": "0.5.4";
"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": "account";
"path": "mxe.cluster.ok_or(ArciumError :: ClusterNotSet) ? ";
"account": "mxeAccount";
},
{
"kind": "arg";
"path": "compOffset";
}
];
};
},
{
"name": "mempool";
"writable": true;
"pda": {
"seeds": [
{
"kind": "const";
"value": [
77,
101,
109,
112,
111,
111,
108
];
},
{
"kind": "account";
"path": "mxe.cluster.ok_or(ArciumError :: ClusterNotSet) ? ";
"account": "mxeAccount";
}
];
};
},
{
"name": "executingPool";
"writable": true;
"pda": {
"seeds": [
{
"kind": "const";
"value": [
69,
120,
101,
99,
112,
111,
111,
108
];
},
{
"kind": "account";
"path": "mxe.cluster.ok_or(ArciumError :: ClusterNotSet) ? ";
"account": "mxeAccount";
}
];
};
},
{
"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": "callbackTransactionIndex";
"type": "u8";
}
];
},
{
"name": "claimComputationRent";
"discriminator": [
215,
218,
1,
166,
81,
218,
16,
151
];
"accounts": [
{
"name": "signer";
"writable": true;
"signer": true;
},
{
"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": "clusterOffset";
},
{
"kind": "arg";
"path": "compOffset";
}
];
};
},
{
"name": "systemProgram";
"address": "11111111111111111111111111111111";
}
];
"args": [
{
"name": "compOffset";
"type": "u64";
},
{
"name": "clusterOffset";
"type": "u32";
}
];
},
{
"name": "claimFailureAppend";
"discriminator": [
92,
52,
184,
203,
76,
221,
128,
69
];
"accounts": [
{
"name": "signer";
"writable": true;
"signer": true;
},
{
"name": "failureAcc";
"writable": true;
"pda": {
"seeds": [
{
"kind": "const";
"value": [
70,
97,
105,
108,
117,
114,
101,
67,
108,
97,
105,
109,
65,
99,
99,
111,
117,
110,
116,
72,
101,
97,
100,
101,
114
];
},
{
"kind": "arg";
"path": "mxeProgram";
},
{
"kind": "arg";
"path": "compOffset";
}
];
};
},
{
"name": "systemProgram";
"address": "11111111111111111111111111111111";
}
];
"args": [
{
"name": "compOffset";
"type": "u64";
},
{
"name": "nodeOffset";
"type": "u32";
},
{
"name": "mxeProgram";
"type": "pubkey";
},
{
"name": "chunk";
"type": "bytes";
},
{
"name": "failureClaimOffset";
"type": "u32";
}
];
},
{
"name": "claimFailureFinalize";
"discriminator": [
192,
133,
215,
19,
76,
107,
111,
217
];
"accounts": [
{
"name": "signer";
"signer": true;
},
{
"name": "failureAcc";
"writable": true;
"pda": {
"seeds": [
{
"kind": "const";
"value": [
70,
97,
105,
108,
117,
114,
101,
67,
108,
97,
105,
109,
65,
99,
99,
111,
117,
110,
116,
72,
101,
97,
100,
101,
114
];
},
{
"kind": "arg";
"path": "mxeProgram";
},
{
"kind": "arg";
"path": "compOffset";
}
];
};
},
{
"name": "executingPool";
"writable": true;
"pda": {
"seeds": [
{
"kind": "const";
"value": [
69,
120,
101,
99,
112,
111,
111,
108
];
},
{
"kind": "account";
"path": "mxe.cluster.ok_or(ArciumError :: ClusterNotSet) ? ";
"account": "mxeAccount";
}
];
};
},
{
"name": "mempool";
"writable": true;
"pda": {
"seeds": [
{
"kind": "const";
"value": [
77,
101,
109,
112,
111,
111,
108
];
},
{
"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": "account";
"path": "mxe.cluster.ok_or(ArciumError :: ClusterNotSet) ? ";
"account": "mxeAccount";
},
{
"kind": "arg";
"path": "compOffset";
}
];
};
},
{
"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": "mxe";
"pda": {
"seeds": [
{
"kind": "const";
"value": [
77,
88,
69,
65,
99,
99,
111,
117,
110,
116
];
},
{
"kind": "arg";
"path": "mxeProgram";
}
];
};
}
];
"args": [
{
"name": "compOffset";
"type": "u64";
},
{
"name": "nodeOffset";
"type": "u32";
},
{
"name": "mxeProgram";
"type": "pubkey";
}
];
},
{
"name": "claimFailureInit";
"discriminator": [
204,
106,
245,
73,
212,
136,
61,
99
];
"accounts": [
{
"name": "signer";
"writable": true;
"signer": true;
},
{
"name": "nodeAcc";
"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": "compAcc";
"pda": {
"seeds": [
{
"kind": "const";
"value": [
67,
111,
109,
112,
117,
116,
97,
116,
105,
111,
110,
65,
99,
99,
111,
117,
110,
116
];
},
{
"kind": "account";
"path": "mxe.cluster.ok_or(ArciumError :: ClusterNotSet) ? ";
"account": "mxeAccount";
},
{
"kind": "arg";
"path": "compOffset";
}
];
};
},
{
"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": "account";
"path": "comp_acc.computation_definition_offset";
"account": "computationAccount";
}
];
};
},
{
"name": "failureAcc";
"writable": true;
"pda": {
"seeds": [
{
"kind": "const";
"value": [
70,
97,
105,
108,
117,
114,
101,
67,
108,
97,
105,
109,
65,
99,
99,
111,
117,
110,
116,
72,
101,
97,
100,
101,
114
];