@arcium-hq/client 0.1.45

package/README.md

@@ -0,0 +1,95 @@
+# 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.
+
+## Installation
+
+```bash
+npm install @arcium-hq/client
+
+or
+
+```bash
+yarn add @arcium-hq/client
+
+or
+
+```bash
+pnpm add @arcium-hq/client
+```
+
+## Usage
+
+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.
+
+1.  **Generate a client keypair:**
+    ```typescript
+    import { x25519 } from "@arcium-hq/client";
+
+    const privateKey = x25519.utils.randomPrivateKey();
+    const publicKey = x25519.getPublicKey(privateKey);
+    ```
+
+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
+    // Example public key (replace with the actual key)
+    const mxePublicKey = new Uint8Array([
+      /* ... 32 bytes of the MXE public key ... */
+    ]);
+    ```
+
+3.  **Compute the shared secret:**
+    ```typescript
+    const sharedSecret = x25519.getSharedSecret(privateKey, mxePublicKey);
+    ```
+
+4.  **Initialize the Rescue cipher:**
+    ```typescript
+    import { RescueCipher } from "@arcium-hq/client";
+
+    const cipher = new RescueCipher(sharedSecret);
+    ```
+
+5.  **Prepare plaintext and encrypt:**
+    *The plaintext should be an array of BigInts.*
+    ```typescript
+    import { randomBytes } from "crypto";
+
+    const val1 = BigInt(123);
+    const val2 = BigInt(456);
+    const plaintext: bigint[] = [val1, val2];
+
+    // Generate a random nonce (16 bytes)
+    const nonce = randomBytes(16);
+
+    // Encrypt the data
+    const ciphertext = cipher.encrypt(plaintext, nonce);
+    ```
+
+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.*
+    ```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())
+    // )...
+    ```
+
+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.*
+    ```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);
+
+    const decryptedResult = cipher.decrypt(resultCiphertextArray, resultNonceArray);
+    // decryptedResult will be an array of bigints
+    const resultValue = decryptedResult[0];
+    ```
+