@arcium-hq/reader 0.1.47 → 0.2.0

package/README.md

@@ -1,136 +1,293 @@
 # Arcium Reader SDK
 
-The Arcium Reader SDK is a TypeScript library designed for passively observing and querying the state of the Arcium program on Solana. It allows you to fetch information about Arcium accounts and track the status of computations without requiring a signer.
+The Arcium Reader SDK is a TypeScript library for passively observing and querying the Arcium network state. It provides read-only access to account data, computation tracking, and event monitoring without requiring a wallet or signer.
 
 ## Installation
 
 ```bash
 npm install @arcium-hq/reader
+# or
+yarn add @arcium-hq/reader
+# or
+pnpm add @arcium-hq/reader
+```
 
-or
+## Quick Start
 
-yarn add @arcium-hq/reader
+### 1. Setup
 
-or
+```typescript
+import * as anchor from "@coral-xyz/anchor";
+import { getArciumProgramReadonly } from "@arcium-hq/reader";
 
-pnpm add @arcium-hq/reader
+// Setup connection (no wallet required)
+const connection = new anchor.web3.Connection("https://api.mainnet-beta.solana.com");
+const provider = new anchor.AnchorProvider(connection, null, {});
+const arciumProgram = getArciumProgramReadonly(provider);
 ```
 
-## Usage
+### 2. Query Account Information
 
-### Getting the Read-only Program
+```typescript
+import {
+  getMXEAccAddresses,
+  getMXEAccInfo,
+  getClusterAccAddresses,
+  getClusterAccInfo,
+} from "@arcium-hq/reader";
+
+// Get all MXE accounts
+const mxeAddresses = await getMXEAccAddresses(connection);
+console.log(`Found ${mxeAddresses.length} MXE accounts`);
+
+// Get detailed information for first MXE
+if (mxeAddresses.length > 0) {
+  const mxeInfo = await getMXEAccInfo(arciumProgram, mxeAddresses[0]);
+  console.log("MXE Info:", {
+    authority: mxeInfo.authority,
+    cluster: mxeInfo.cluster,
+    computationDefinitions: mxeInfo.computationDefinitions.length,
+  });
+}
+```
 
-To interact with the reader functions, you first need a read-only instance of the Arcium Anchor program. This doesn't require a wallet or signer.
+### 3. Monitor Computations
 
 ```typescript
-import * as anchor from "@coral-xyz/anchor";
-import { getArciumProgramReadonly } from "@arcium-hq/reader";
+import { subscribeComputations } from "@arcium-hq/reader";
 
-// Assuming you have an AnchorProvider configured (e.g., from anchor.AnchorProvider.env())
-const provider = anchor.getProvider();
-const arciumProgram = getArciumProgramReadonly(
-  provider as anchor.AnchorProvider
+// Subscribe to computation events for an MXE program
+const mxeProgramId = new anchor.web3.PublicKey("YOUR_MXE_PROGRAM_ID");
+
+const subscriptionId = await subscribeComputations(
+  connection,
+  mxeProgramId,
+  (eventData, eventName) => {
+    console.log(`Event: ${eventName}`, eventData);
+  }
 );
 ```
 
-### Fetching Account Information
+## Account Types and Queries
 
-The reader SDK provides functions to fetch and deserialize various Arcium account types.
+### MXE (Multi-party eXecution Environment) Accounts
 
-**1. Fetching MXE Accounts:**
+MXE accounts represent execution environments for secure computations.
 
 ```typescript
 import { getMXEAccAddresses, getMXEAccInfo } from "@arcium-hq/reader";
 
-// Get all MXE account public keys
-const mxeAccPubkeys = await getMXEAccAddresses(provider.connection);
-
-// Get detailed info for a specific MXE account
-if (mxeAccPubkeys.length > 0) {
-  const mxeAccInfo = await getMXEAccInfo(arciumProgram, mxeAccPubkeys[0]);
-  console.log("MXE Account Info:", mxeAccInfo);
-  // Access fields like mxeAccInfo.computationDefinitions, mxeAccInfo.cluster, etc.
+// Get all MXE account addresses
+const mxeAddresses = await getMXEAccAddresses(connection);
+
+// Fetch detailed MXE information
+for (const address of mxeAddresses) {
+  const mxeInfo = await getMXEAccInfo(arciumProgram, address);
+  
+  console.log("MXE Account:", {
+    address: address.toBase58(),
+    authority: mxeInfo.authority?.toBase58(),
+    cluster: mxeInfo.cluster,
+    x25519KeySet: 'set' in mxeInfo.x25519Pubkey,
+    computationDefinitions: mxeInfo.computationDefinitions,
+    fallbackClusters: mxeInfo.fallbackClusters,
+  });
 }
 ```
 
-**2. Fetching Cluster Accounts:**
+### Cluster Accounts
+
+Cluster accounts manage collections of ARX nodes that execute computations.
 
 ```typescript
 import { getClusterAccAddresses, getClusterAccInfo } from "@arcium-hq/reader";
 
-// Get all Cluster account public keys
-const clusterAccPubkeys = await getClusterAccAddresses(provider.connection);
-
-// Get detailed info for a specific Cluster account
-if (clusterAccPubkeys.length > 0) {
-  const clusterInfo = await getClusterAccInfo(
-    arciumProgram,
-    clusterAccPubkeys[0]
-  );
-  console.log("Cluster Account Info:", clusterInfo);
-  // Access fields like clusterInfo.mxes, clusterInfo.nodes, etc.
+// Get all cluster addresses
+const clusterAddresses = await getClusterAccAddresses(connection);
+
+// Analyze cluster information
+for (const address of clusterAddresses) {
+  const clusterInfo = await getClusterAccInfo(arciumProgram, address);
+  
+  console.log("Cluster:", {
+    address: address.toBase58(),
+    nodeCount: clusterInfo.nodes.length,
+    mxeCount: clusterInfo.mxes.length,
+    threshold: clusterInfo.threshold,
+    state: clusterInfo.state,
+  });
 }
 ```
 
-**3. Fetching ArxNode Accounts:**
+### ArxNode Accounts
+
+ArxNode accounts represent individual computation nodes in the network.
 
 ```typescript
 import { getArxNodeAccAddresses, getArxNodeAccInfo } from "@arcium-hq/reader";
 
-// Get all ArxNode account public keys
-const arxNodeAccPubkeys = await getArxNodeAccAddresses(provider.connection);
-
-// Get detailed info for a specific ArxNode account
-if (arxNodeAccPubkeys.length > 0) {
-  const arxNodeInfo = await getArxNodeAccInfo(
-    arciumProgram,
-    arxNodeAccPubkeys[0]
-  );
-  console.log("ArxNode Account Info:", arxNodeInfo);
-  // Access fields like arxNodeInfo.clusterMemberships, etc.
+// Get all ARX node addresses
+const arxNodeAddresses = await getArxNodeAccAddresses(connection);
+
+// Get node information
+for (const address of arxNodeAddresses) {
+  const nodeInfo = await getArxNodeAccInfo(arciumProgram, address);
+  
+  console.log("ARX Node:", {
+    address: address.toBase58(),
+    authority: nodeInfo.authority?.toBase58(),
+    clusterMemberships: nodeInfo.clusterMemberships,
+    encryptionPubkey: Buffer.from(nodeInfo.encryptionPubkey).toString('hex'),
+  });
 }
 ```
 
-### Tracking Computation Status
+### Computation Definition Accounts
 
-You can subscribe to events related to a specific MXE (identified by its program ID) to track the lifecycle of computations it processes.
+Track available computation definitions and their configurations.
 
 ```typescript
-import {
+import { getCompDefAccInfo } from "@arcium-hq/reader";
+import { getCompDefAccAddress } from "@arcium-hq/reader";
+
+// Get computation definition for a specific circuit
+const circuitName = "your_circuit_name";
+const mxeProgramId = new anchor.web3.PublicKey("YOUR_MXE_PROGRAM_ID");
+
+const compDefAddress = getCompDefAccAddress(mxeProgramId, /* offset */);
+const compDefInfo = await getCompDefAccInfo(arciumProgram, compDefAddress);
+
+console.log("Computation Definition:", {
+  finalizationAuthority: compDefInfo.finalizationAuthority?.toBase58(),
+  finalizesDuringCallback: compDefInfo.finalizeDuringCallback,
+  cuAmount: compDefInfo.cuAmount.toString(),
+  circuitSource: compDefInfo.circuitSource,
+});
+```
+
+### Computation Accounts
+
+Monitor individual computation instances and their status.
+
+```typescript
+import { getComputationAccInfo } from "@arcium-hq/reader";
+import { getComputationAccAddress } from "@arcium-hq/reader";
+
+// Get computation account info
+const computationOffset = new anchor.BN("123456789");
+const computationAddress = getComputationAccAddress(mxeProgramId, computationOffset);
+const computationInfo = await getComputationAccInfo(arciumProgram, computationAddress);
+
+console.log("Computation:", {
+  status: computationInfo.status,
+  arguments: computationInfo.arguments,
+  results: computationInfo.results,
+  submitter: computationInfo.submitter.toBase58(),
+});
+```
+
+## Mempool Analysis
+
+Analyze pending computations in the network's memory pools.
+
+```typescript
+import { 
+  getComputationsInMempool,
+  getMempoolAccAddress
+} from "@arcium-hq/reader";
+
+// Get mempool for an MXE
+const mempoolAddress = getMempoolAccAddress(mxeProgramId);
+const pendingComputations = await getComputationsInMempool(arciumProgram, mempoolAddress);
+
+console.log(`Found ${pendingComputations.length} pending computations:`);
+
+for (const compRef of pendingComputations) {
+  console.log("Pending Computation:", {
+    computationOffset: compRef.computationOffset.toString(),
+    priorityFee: compRef.priorityFee.toString(),
+    computationDefinitionOffset: compRef.computationDefinitionOffset,
+  });
+}
+```
+
+## Event Monitoring
+
+### Real-time Event Subscription
+
+Monitor computation lifecycle events in real-time:
+
+```typescript
+import { 
   subscribeComputations,
   unsubscribeComputations,
   ArciumEventData,
-  ArciumEventName,
+  ArciumEventName 
 } from "@arcium-hq/reader";
-import { PublicKey } from "@solana/web3.js";
-
-// Assuming `mxeProgramId` is the PublicKey of the MXE program you want to monitor
-const mxeProgramId = new PublicKey("YOUR_MXE_PROGRAM_ID");
 
-const eventLog = [];
+const eventLog: Array<{event: ArciumEventData, name: ArciumEventName, timestamp: Date}> = [];
 
-// Define a callback function to handle events
-const eventCallback = (
-  eventData: ArciumEventData,
-  eventName: ArciumEventName
-) => {
-  console.log(`Received event: ${eventName}`, eventData);
-  eventLog.push({ event: eventData, name: eventName });
-};
-
-// Start subscribing
-console.log(`Subscribing to computation events for ${mxeProgramId.toBase58()}`);
+// Subscribe to events
 const subscriptionId = await subscribeComputations(
   connection,
   mxeProgramId,
-  eventCallback
+  (eventData, eventName) => {
+    eventLog.push({
+      event: eventData,
+      name: eventName,
+      timestamp: new Date()
+    });
+
+    console.log(`[${eventName}] Computation ${eventData.computationOffset.toString()}`);
+    
+    // Handle specific event types
+    switch (eventName) {
+      case 'QueueComputationEvent':
+        console.log("  → Computation queued for execution");
+        break;
+      case 'InitComputationEvent':
+        console.log("  → Computation execution started");
+        break;
+      case 'CallbackComputationEvent':
+        console.log("  → Computation callback received");
+        break;
+      case 'FinalizeComputationEvent':
+        console.log("  → Computation finalized");
+        break;
+    }
+  }
 );
 
-console.log(`Subscription active with ID: ${subscriptionId}`);
+console.log(`Subscribed to events with ID: ${subscriptionId}`);
+
+// Later, unsubscribe
+// await unsubscribeComputations(connection, subscriptionId);
+```
 
-// ... later, when you want to stop listening ...
+### Transaction Analysis
 
-// Unsubscribe
-await unsubscribeComputations(connection, subscriptionId);
-console.log(`Unsubscribed from computation events.`);
+Extract computation events from transaction logs:
+
+```typescript
+import { getComputationOffset } from "@arcium-hq/reader";
+
+// Analyze a specific transaction
+const txSignature = "YOUR_TRANSACTION_SIGNATURE";
+const tx = await connection.getTransaction(txSignature, {
+  commitment: "confirmed",
+  maxSupportedTransactionVersion: 0
+});
+
+if (tx) {
+  const computationOffset = getComputationOffset(tx);
+  if (computationOffset) {
+    console.log(`Transaction contains computation: ${computationOffset.toString()}`);
+  }
+}
 ```
+
+## API Reference
+
+<!-- TODO: Add API reference url -->
+
+For detailed API documentation, please refer to the [Arcium TypeScript SDK API reference](https://github.com/arcium-hq).

package/build/index.cjs

@@ -32,9 +32,9 @@ const ARX_NODE_ACC_DISCRIMINATOR = [2, 207, 122, 223, 93, 97, 231, 199];
  */
 const CLUSTER_ACC_DISCRIMINATOR = [236, 225, 118, 228, 173, 106, 18, 60];
 /**
- * Discriminator for the MXE account type. Used to filter and identify persistent MXE accounts on-chain.
+ * Discriminator for the MXE account type. Used to filter and identify MXE accounts on-chain.
  */
-const MXE_ACC_DISCRIMINATOR = [32, 115, 16, 240, 209, 25, 92, 165];
+const MXE_ACC_DISCRIMINATOR = [103, 26, 85, 250, 179, 159, 17, 117];
 /**
  * The public key of the deployed Arcium program on Solana.
  */
@@ -80,7 +80,7 @@ async function getArxNodeAccAddresses(conn) {
  * @returns The MXEAccount object.
  */
 async function getMXEAccInfo(arciumProgram, address, commitment) {
-    return arciumProgram.account.persistentMxeAccount.fetch(address, commitment);
+    return arciumProgram.account.mxeAccount.fetch(address, commitment);
 }
 /**
  * Fetches and parses a given Cluster account.

package/build/index.d.ts

@@ -23,15 +23,15 @@ type ArciumEventName = Capitalize<keyof ArciumEvent>;
  * Data structure for any Arcium event, as parsed from logs.
  */
 type ArciumEventData = ArciumEvent[keyof ArciumEvent];
-type MXEAccount = ArciumTypes['persistentMxeAccount'];
+type MXEAccount = ArciumTypes['mxeAccount'];
 type ClusterAccount = ArciumTypes['cluster'];
 type ArxNodeAccount = ArciumTypes['arxNode'];
 type ComputationAccount = ArciumTypes['computationAccount'];
 type ComputationReference = ArciumTypes['computationReference'];
 type ComputationDefinitionAccount = ArciumTypes['computationDefinitionAccount'];
-type QueueComputationIx = ArciumIdlType['instructions']['37'];
-type CallbackComputationIx = ArciumIdlType['instructions']['4'];
-type FinalizeComputationIx = ArciumIdlType['instructions']['17'];
+type QueueComputationIx = ArciumIdlType['instructions']['23'];
+type CallbackComputationIx = ArciumIdlType['instructions']['3'];
+type FinalizeComputationIx = ArciumIdlType['instructions']['8'];
 /**
  * Status values for a computation, as defined by the Arcium protocol.
  */
@@ -126,4 +126,5 @@ declare function unsubscribeComputations(conn: Connection, subscriptionId: numbe
  */
 declare function getComputationOffset(tx: anchor.web3.VersionedTransactionResponse): anchor.BN | undefined;
 
-export { type ArciumEvent, type ArciumEventData, type ArciumEventName, type ArciumTypes, type ArxNodeAccount, type CallbackComputationIx, type ClusterAccount, type ComputationAccount, type ComputationDefinitionAccount, type ComputationReference, type ComputationStatus, type Connection, type FinalizeComputationIx, type MXEAccount, type Program, type PublicKey, type QueueComputationIx, getArxNodeAccAddresses, getArxNodeAccInfo, getClusterAccAddresses, getClusterAccInfo, getCompDefAccInfo, getComputationAccInfo, getComputationOffset, getComputationsInMempool, getMXEAccAddresses, getMXEAccInfo, subscribeComputations, unsubscribeComputations };
+export { getArxNodeAccAddresses, getArxNodeAccInfo, getClusterAccAddresses, getClusterAccInfo, getCompDefAccInfo, getComputationAccInfo, getComputationOffset, getComputationsInMempool, getMXEAccAddresses, getMXEAccInfo, subscribeComputations, unsubscribeComputations };
+export type { ArciumEvent, ArciumEventData, ArciumEventName, ArciumTypes, ArxNodeAccount, CallbackComputationIx, ClusterAccount, ComputationAccount, ComputationDefinitionAccount, ComputationReference, ComputationStatus, Connection, FinalizeComputationIx, MXEAccount, Program, PublicKey, QueueComputationIx };

package/build/index.mjs

@@ -12,9 +12,9 @@ const ARX_NODE_ACC_DISCRIMINATOR = [2, 207, 122, 223, 93, 97, 231, 199];
  */
 const CLUSTER_ACC_DISCRIMINATOR = [236, 225, 118, 228, 173, 106, 18, 60];
 /**
- * Discriminator for the MXE account type. Used to filter and identify persistent MXE accounts on-chain.
+ * Discriminator for the MXE account type. Used to filter and identify MXE accounts on-chain.
  */
-const MXE_ACC_DISCRIMINATOR = [32, 115, 16, 240, 209, 25, 92, 165];
+const MXE_ACC_DISCRIMINATOR = [103, 26, 85, 250, 179, 159, 17, 117];
 /**
  * The public key of the deployed Arcium program on Solana.
  */
@@ -60,7 +60,7 @@ async function getArxNodeAccAddresses(conn) {
  * @returns The MXEAccount object.
  */
 async function getMXEAccInfo(arciumProgram, address, commitment) {
-    return arciumProgram.account.persistentMxeAccount.fetch(address, commitment);
+    return arciumProgram.account.mxeAccount.fetch(address, commitment);
 }
 /**
  * Fetches and parses a given Cluster account.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcium-hq/reader",
-  "version": "0.1.47",
+  "version": "0.2.0",
   "description": "Reader SDK for fetching onchain data for Arcium network programs",
   "author": "Arcium",
   "license": "GPL-3.0-only",
@@ -41,24 +41,26 @@
     "@types/bn.js": "^5.1.6",
     "@types/chai": "^5.0.0",
     "@types/mocha": "^10.0.9",
+    "@types/node": "^22.10.2",
     "@types/snarkjs": "^0.7.8",
-    "@typescript-eslint/eslint-plugin": "6.12.0",
-    "@typescript-eslint/parser": "6.12.0",
+    "@typescript-eslint/eslint-plugin": "^8.15.0",
+    "@typescript-eslint/parser": "^8.15.0",
     "chai": "^5.1.2",
-    "eslint": "8.54.0",
-    "eslint-config-airbnb-base": "15.0.0",
-    "eslint-plugin-import": "2.29.0",
+    "eslint": "^9.15.0",
+    "eslint-config-airbnb-base": "^15.0.0",
+    "eslint-plugin-import": "^2.31.0",
     "mocha": "^10.8.2",
     "rollup": "^4.24.0",
     "rollup-plugin-dts": "^6.1.1",
     "ts-node": "^10.9.2",
-    "typescript": "^4.5.2"
+    "typescript": "^5.6.3",
+    "typescript-eslint": "^8.15.0"
   },
   "dependencies": {
     "@coral-xyz/anchor": "^0.31.1",
     "@noble/curves": "^1.8.1",
     "@noble/hashes": "^1.7.1",
-    "@arcium-hq/client": "0.1.47"
+    "@arcium-hq/client": "0.2.0"
   },
   "keywords": [
     "Cryptography",