@arcium-hq/client 0.9.7 → 0.10.0

package/README.md

@@ -1,215 +1,71 @@
-# Arcium Client SDK
+<div align="center">
+  <img src="https://raw.githubusercontent.com/arcium-hq/.github/refs/heads/main/profile/arcium.svg" alt="Arcium" width="200"/>
 
-The Arcium Client SDK is a TypeScript library for interacting with the Arcium Solana program, enabling secure multi-party computation on encrypted data.
+<h1>@arcium-hq/client</h1>
 
-## Installation
-
-```bash
-npm install @arcium-hq/client
-# or
-yarn add @arcium-hq/client
-# or
-pnpm add @arcium-hq/client
-```
-
-## Quick Start
-
-### 1. Setup and Environment
+<p>TypeScript SDK for encryption, PDA helpers, and Arcium computation flows.</p>
 
-```typescript
-import { getArciumEnv } from "@arcium-hq/client";
-import * as anchor from "@coral-xyz/anchor";
+[![npm](https://img.shields.io/npm/v/@arcium-hq/client)](https://www.npmjs.com/package/@arcium-hq/client)
 
-// Get Arcium environment configuration
-const arciumEnv = getArciumEnv();
+**[API Docs](https://ts.arcium.com/api)** | **[Developer Docs](https://docs.arcium.com/developers/js-client-library)**
 
-// Setup Anchor provider
-anchor.setProvider(anchor.AnchorProvider.env());
-const provider = anchor.getProvider();
-```
-
-### 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.
-
-#### Generate a client keypair:
-
-```typescript
-import { x25519 } from "@arcium-hq/client";
-
-const privateKey = x25519.utils.randomSecretKey();
-const publicKey = x25519.getPublicKey(privateKey);
-```
+</div>
 
-#### Obtain the MXE's public key:
+## When To Use
 
-```typescript
-import { getMXEPublicKey } from "@arcium-hq/client";
-
-// Fetch the MXE public key (handles the complex extraction logic internally)
-const mxePublicKey = await getMXEPublicKey(provider, program.programId);
-
-if (!mxePublicKey) {
-  throw new Error("MXE public key not set");
-}
-```
-
-#### Compute the shared secret and initialize cipher:
-
-```typescript
-import { RescueCipher } from "@arcium-hq/client";
-
-const sharedSecret = x25519.getSharedSecret(privateKey, mxePublicKey);
-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" });
-```
-
-### 4. Track and Finalize Computation
-
-```typescript
-import { awaitComputationFinalization } from "@arcium-hq/client";
-
-// Wait for computation to complete
-const finalizeSig = await awaitComputationFinalization(
-  provider as anchor.AnchorProvider,
-  computationOffset,
-  program.programId,
-  "confirmed"
-);
+- Encrypting inputs for Arcium computations
+- Deriving Arcium PDAs from TypeScript
+- Waiting for computation finalization and interacting with Arcium account state
 
-console.log("Computation finalized:", finalizeSig);
-```
+## Requirements
 
-### 5. Decrypt Results
+- Node.js `>=20.18.0`
+- `@anchor-lang/core` `0.32.1`
 
-```typescript
-// After finalization, fetch your program's result account
-const resultAccount = await program.account.yourResultAccount.fetch(resultAddress);
+## Installation
 
-// Decrypt the result using the same cipher and nonce
-const decrypted = cipher.decrypt(
-  resultAccount.encryptedResult,
-  nonce,
-);
-console.log("Decrypted result:", decrypted);
+```bash
+npm install @arcium-hq/client @anchor-lang/core
 ```
 
-## Account Helpers
-
-The SDK provides helper functions to derive all necessary Arcium PDAs:
+## Quick Start
 
-```typescript
+```ts
+import * as anchor from "@anchor-lang/core";
 import {
+  awaitComputationFinalization,
   getArciumEnv,
-  getMXEAccAddress,
-  getMempoolAccAddress,
-  getCompDefAccAddress,
-  getExecutingPoolAccAddress,
-  getComputationAccAddress,
   getCompDefAccOffset,
-  getArciumAccountBaseSeed,
-  getArciumProgramId,
+  getComputationAccAddress,
+  getMempoolAccAddress,
+  getMXEAccAddress,
 } from "@arcium-hq/client";
 
-// Get cluster offset from environment
-const arciumEnv = getArciumEnv();
-
-// Get MXE account address (uses MXE program ID)
-const mxeAccount = getMXEAccAddress(program.programId);
-
-// Get pool addresses (use cluster offset, not program ID)
-const mempoolAccount = getMempoolAccAddress(arciumEnv.arciumClusterOffset);
-const executingPool = getExecutingPoolAccAddress(arciumEnv.arciumClusterOffset);
-
-// 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 (uses cluster offset)
-const computationAccount = getComputationAccAddress(
-  arciumEnv.arciumClusterOffset,
-  computationOffset
+const env = getArciumEnv();
+const computationAddress = getComputationAccAddress(
+  env.arciumClusterOffset,
+  new anchor.BN(1),
 );
-```
-
-## 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");
+const compDefOffset = getCompDefAccOffset("my_circuit");
+const mempool = getMempoolAccAddress(env.arciumClusterOffset);
 
-await uploadCircuit(
-  provider as anchor.AnchorProvider,
-  "your_circuit_name",
-  program.programId,
-  rawCircuit,
-  true // enable logging
-);
+// `mxeProgramId` is the PublicKey of your Anchor program that hosts the MXE.
+const mxe = getMXEAccAddress(mxeProgramId);
 ```
 
-### 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);
+## Main Exports
 
-// Send transaction
-await provider.sendAndConfirm(finalizeTx);
-```
+| Area | Description |
+|------|-------------|
+| Cryptography | Rescue/AES helpers, hashing, and X25519 utilities. |
+| `createPacker()` | Pack and unpack circuit inputs and outputs. |
+| PDA helpers | Derive computation, mempool, MXE, cluster, and comp-def addresses. |
+| `awaitComputationFinalization()` | Poll for finalized computations. |
+| IDL exports | Generated Arcium program types and constants. |
 
-## API Reference
+## See Also
 
-- **[API Reference](https://ts.arcium.com/api)** - Complete API documentation
-- **[Developer Docs](https://docs.arcium.com/developers/js-client-library)** - Guides and tutorials
-- **[Examples](https://github.com/arcium-hq/examples)** - Code examples
+- [`@arcium-hq/reader`](https://www.npmjs.com/package/@arcium-hq/reader)
+- [API Docs](https://ts.arcium.com/api)
+- [Developer Docs](https://docs.arcium.com/developers/js-client-library)