@arcium-hq/client 0.1.47 → 0.3.0

package/README.md

@@ -1,102 +1,206 @@
 # Arcium Client SDK
 
-The Arcium client SDK is a TypeScript library for interacting with the Arcium program. It exports the Arcium program's IDL as well as types for interacting with the program's accounts.
+The Arcium Client SDK is a TypeScript library for interacting with the Arcium Solana program, enabling secure multi-party computation on encrypted data.
 
 ## Installation
 
 ```bash
 npm install @arcium-hq/client
+# or
+yarn add @arcium-hq/client
+# or
+pnpm add @arcium-hq/client
+```
 
-or
+## Quick Start
 
-yarn add @arcium-hq/client
+### 1. Setup and Environment
 
-or
+```typescript
+import { getArciumEnv } from "@arcium-hq/client";
+import * as anchor from "@coral-xyz/anchor";
 
-pnpm add @arcium-hq/client
+// Get Arcium environment configuration
+const arciumEnv = getArciumEnv();
+
+// Setup Anchor provider
+anchor.setProvider(anchor.AnchorProvider.env());
+const provider = anchor.getProvider();
 ```
 
-## Usage
+### 2. Encryption Setup
+
+To send private data for computation within Arcium, you need to encrypt it using a shared secret derived from your keypair and the Arcium MXE's public key.
 
-To send private data for computation within Arcium, you need to encrypt it using a shared secret derived from your keypair and the Arcium MXE's public key. The client SDK provides utilities for this using X25519 key exchange and the Rescue cipher.
+#### Generate a client keypair:
 
-1.  **Generate a client keypair:**
+```typescript
+import { x25519 } from "@arcium-hq/client";
 
-    ```typescript
-    import { x25519 } from "@arcium-hq/client";
+const privateKey = x25519.utils.randomSecretKey();
+const publicKey = x25519.getPublicKey(privateKey);
+```
 
-    const privateKey = x25519.utils.randomPrivateKey();
-    const publicKey = x25519.getPublicKey(privateKey);
-    ```
+#### Obtain the MXE's public key:
 
-2.  **Obtain the MXE's public key:**
-    _This key is typically specific to the Arcium cluster you are interacting with. You might obtain it through configuration or environment variables._
+```typescript
+import { getMXEPublicKey } from "@arcium-hq/client";
 
-    ```typescript
-    // Example public key (replace with the actual key)
-    const mxePublicKey = new Uint8Array([
-      /* ... 32 bytes of the MXE public key ... */
-    ]);
-    ```
+// Fetch the MXE public key (handles the complex extraction logic internally)
+const mxePublicKey = await getMXEPublicKey(provider, program.programId);
 
-3.  **Compute the shared secret:**
+if (!mxePublicKey) {
+  throw new Error("MXE public key not set");
+}
+```
 
-    ```typescript
-    const sharedSecret = x25519.getSharedSecret(privateKey, mxePublicKey);
-    ```
+#### Compute the shared secret and initialize cipher:
 
-4.  **Initialize the Rescue cipher:**
+```typescript
+import { RescueCipher } from "@arcium-hq/client";
 
-    ```typescript
-    import { RescueCipher } from "@arcium-hq/client";
+const sharedSecret = x25519.getSharedSecret(privateKey, mxePublicKey);
+const cipher = new RescueCipher(sharedSecret);
+```
 
-    const cipher = new RescueCipher(sharedSecret);
-    ```
+### 3. Encrypt and Submit Data
+
+```typescript
+import { randomBytes } from "crypto";
+import { deserializeLE } from "@arcium-hq/client";
+
+// Prepare your data as BigInts
+const val1 = BigInt(123);
+const val2 = BigInt(456);
+const plaintext = [val1, val2];
+
+// Generate a random nonce (16 bytes)
+const nonce = randomBytes(16);
+
+// Encrypt the data
+const ciphertext = cipher.encrypt(plaintext, nonce);
+
+// Submit to your program
+const computationOffset = new anchor.BN(randomBytes(8), "hex");
+
+const sig = await program.methods
+  .yourComputationMethod(
+    computationOffset,
+    Array.from(ciphertext[0]),
+    Array.from(ciphertext[1]),
+    Array.from(publicKey),
+    new anchor.BN(deserializeLE(nonce).toString())
+  )
+  .accountsPartial({
+    // Account setup - see Account Helpers section
+  })
+  .rpc({ skipPreflight: true, commitment: "confirmed" });
+```
 
-5.  **Prepare plaintext and encrypt:**
-    _The plaintext should be an array of BigInts._
+### 4. Track and Finalize Computation
 
-    ```typescript
-    import { randomBytes } from "crypto";
+```typescript
+import { awaitComputationFinalization } from "@arcium-hq/client";
 
-    const val1 = BigInt(123);
-    const val2 = BigInt(456);
-    const plaintext: bigint[] = [val1, val2];
+// Wait for computation to complete
+const finalizeSig = await awaitComputationFinalization(
+  provider as anchor.AnchorProvider,
+  computationOffset,
+  program.programId,
+  "confirmed"
+);
 
-    // Generate a random nonce (16 bytes)
-    const nonce = randomBytes(16);
+console.log("Computation finalized:", finalizeSig);
+```
+
+### 5. Decrypt Results
 
-    // Encrypt the data
-    const ciphertext = cipher.encrypt(plaintext, nonce);
-    ```
+```typescript
+// Listen for program events
+const event = await awaitEvent("yourResultEvent");
 
-6.  **Send data to Arcium:**
-    _You typically send the `ciphertext`, your `publicKey`, and the `nonce` (often converted to a `BN`) when calling an Arcium program instruction that requires encrypted inputs._
+// Decrypt the result using the same cipher
+const decrypted = cipher.decrypt([event.encryptedResult], event.nonce)[0];
+console.log("Decrypted result:", decrypted);
+```
 
-    ```typescript
-    // Example structure (actual usage depends on the specific program)
-    // await program.methods.yourInstruction(
-    //   /* ... other args ... */,
-    //   Array.from(ciphertext[0]),
-    //   Array.from(ciphertext[1]),
-    //   Array.from(publicKey),
-    //   new anchor.BN(deserializeLE(nonce).toString())
-    // )...
-    ```
+## Account Helpers
+
+The SDK provides helper functions to derive all necessary Arcium PDAs:
+
+```typescript
+import {
+  getMXEAccAddress,
+  getMempoolAccAddress,
+  getCompDefAccAddress,
+  getExecutingPoolAccAddress,
+  getComputationAccAddress,
+  getCompDefAccOffset,
+  getArciumAccountBaseSeed,
+  getArciumProgAddress,
+} from "@arcium-hq/client";
+
+// Get various account addresses
+const mxeAccount = getMXEAccAddress(program.programId);
+const mempoolAccount = getMempoolAccAddress(program.programId);
+const executingPool = getExecutingPoolAccAddress(program.programId);
+
+// Get computation definition address
+const compDefOffset = getCompDefAccOffset("your_computation_name");
+const compDefAccount = getCompDefAccAddress(
+  program.programId,
+  Buffer.from(compDefOffset).readUInt32LE()
+);
+
+// Get computation account for a specific offset
+const computationAccount = getComputationAccAddress(
+  program.programId,
+  computationOffset
+);
+```
+
+## Circuit Management
+
+### Upload a Circuit
+
+```typescript
+import { uploadCircuit } from "@arcium-hq/client";
+import * as fs from "fs";
+
+const rawCircuit = fs.readFileSync("build/your_circuit.arcis");
+
+await uploadCircuit(
+  provider as anchor.AnchorProvider,
+  "your_circuit_name",
+  program.programId,
+  rawCircuit,
+  true // use raw circuit
+);
+```
+
+### Finalize Computation Definition
+
+```typescript
+import { buildFinalizeCompDefTx } from "@arcium-hq/client";
+
+const finalizeTx = await buildFinalizeCompDefTx(
+  provider as anchor.AnchorProvider,
+  Buffer.from(compDefOffset).readUInt32LE(),
+  program.programId
+);
+
+// Set blockhash and sign
+const latestBlockhash = await provider.connection.getLatestBlockhash();
+finalizeTx.recentBlockhash = latestBlockhash.blockhash;
+finalizeTx.lastValidBlockHeight = latestBlockhash.lastValidBlockHeight;
+finalizeTx.sign(owner);
+
+// Send transaction
+await provider.sendAndConfirm(finalizeTx);
+```
 
-7.  **Decrypting results:**
-    _When your program receives results from Arcium (e.g., via an event), they will likely be encrypted. Use the same `cipher` instance and the `nonce` provided in the result/event to decrypt._
+## API Reference
 
-    ```typescript
-    // Assuming `event.encryptedResult` is a Uint8Array or number[]
-    // and `event.resultNonce` is a Uint8Array or number[] from the Arcium callback
-    const resultCiphertextArray = [event.encryptedResult];
-    const resultNonceArray = new Uint8Array(event.resultNonce);
+<!-- TODO: Add API reference url -->
 
-    const decryptedResult = cipher.decrypt(
-      resultCiphertextArray,
-      resultNonceArray
-    );
-    // decryptedResult will be an array of bigints
-    const resultValue = decryptedResult[0];
-    ```
+For detailed API documentation, please refer to the [API reference](https://github.com/arcium-hq) included with the package.