@arcium-hq/reader 0.1.46 → 0.2.0

package/README.md

@@ -1,126 +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
-
-```bash
+# or
 yarn add @arcium-hq/reader
-
-or
-
-```bash
+# or
 pnpm add @arcium-hq/reader
 ```
 
-## Usage
-
-### Getting the Read-only Program
+## Quick Start
 
-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.
+### 1. Setup
 
 ```typescript
 import * as anchor from "@coral-xyz/anchor";
 import { getArciumProgramReadonly } 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);
+// 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);
 ```
 
-### Fetching Account Information
+### 2. Query Account Information
 
-The reader SDK provides functions to fetch and deserialize various Arcium account types.
+```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,
+  });
+}
+```
 
-**1. Fetching MXE Accounts:**
+### 3. Monitor Computations
 
 ```typescript
-import { getMXEAccs, getMXEAccInfo } from "@arcium-hq/reader";
+import { subscribeComputations } from "@arcium-hq/reader";
 
-// Get all MXE account public keys
-const mxeAccPubkeys = await getMXEAccs(provider.connection);
+// Subscribe to computation events for an MXE program
+const mxeProgramId = new anchor.web3.PublicKey("YOUR_MXE_PROGRAM_ID");
 
-// 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.
+const subscriptionId = await subscribeComputations(
+  connection,
+  mxeProgramId,
+  (eventData, eventName) => {
+    console.log(`Event: ${eventName}`, eventData);
+  }
+);
+```
+
+## Account Types and Queries
+
+### MXE (Multi-party eXecution Environment) Accounts
+
+MXE accounts represent execution environments for secure computations.
+
+```typescript
+import { getMXEAccAddresses, getMXEAccInfo } from "@arcium-hq/reader";
+
+// 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 { getClusterAccs, getClusterAccInfo } from "@arcium-hq/reader";
+import { getClusterAccAddresses, getClusterAccInfo } from "@arcium-hq/reader";
+
+// 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,
+  });
+}
+```
+
+### ArxNode Accounts
 
-// Get all Cluster account public keys
-const clusterAccPubkeys = await getClusterAccs(provider.connection);
+ArxNode accounts represent individual computation nodes in the network.
 
-// 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.
+```typescript
+import { getArxNodeAccAddresses, getArxNodeAccInfo } from "@arcium-hq/reader";
+
+// 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'),
+  });
 }
 ```
 
-**3. Fetching ArxNode Accounts:**
+### Computation Definition Accounts
+
+Track available computation definitions and their configurations.
 
 ```typescript
-import { getArxNodeAccs, getArxNodeAccInfo } from "@arcium-hq/reader";
+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,
+});
+```
 
-// Get all ArxNode account public keys
-const arxNodeAccPubkeys = await getArxNodeAccs(provider.connection);
+### Computation Accounts
 
-// 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.
-}
+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(),
+});
 ```
 
-### Tracking Computation Status
+## Mempool Analysis
 
-You can subscribe to events related to a specific MXE (identified by its program ID) to track the lifecycle of computations it processes.
+Analyze pending computations in the network's memory pools.
 
 ```typescript
-import { subscribeComputations, unsubscribeComputations } from "@arcium-hq/reader";
-import { PublicKey } from "@solana/web3.js";
+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,
+  });
+}
+```
 
-// Assuming `mxeProgramId` is the PublicKey of the MXE program you want to monitor
-const mxeProgramId = new PublicKey("YOUR_MXE_PROGRAM_ID"); 
+## Event Monitoring
 
-const eventLog = [];
+### Real-time Event Subscription
 
-// Define a callback function to handle events
-const eventCallback = (eventData: any, eventName: string) => {
-  console.log(`Received event: ${eventName}`, eventData);
-  eventLog.push({ event: eventData, name: eventName });
-  // Events typically include QueueComputationEvent, InitComputationEvent, 
-  // CallbackComputationEvent, FinalizeComputationEvent
-};
+Monitor computation lifecycle events in real-time:
 
-// Start subscribing
-console.log(`Subscribing to computation events for ${mxeProgramId.toBase58()}`)
+```typescript
+import { 
+  subscribeComputations,
+  unsubscribeComputations,
+  ArciumEventData,
+  ArciumEventName 
+} from "@arcium-hq/reader";
+
+const eventLog: Array<{event: ArciumEventData, name: ArciumEventName, timestamp: Date}> = [];
+
+// Subscribe to events
 const subscriptionId = await subscribeComputations(
-  provider.connection,
-  mxeProgramId, 
-  eventCallback
+  connection,
+  mxeProgramId,
+  (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(provider.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

@@ -23,35 +23,102 @@ function _interopNamespaceDefault(e) {
 var anchor__namespace = /*#__PURE__*/_interopNamespaceDefault(anchor);
 
 const ARCIUM_PROGRAM_ID_STRING = 'BKck65TgoKRokMjQM3datB9oRwJ8rAj2jxPXvHXUvcL6';
+/**
+ * Discriminator for the ArxNode account type. Used to filter and identify ArxNode accounts on-chain.
+ */
 const ARX_NODE_ACC_DISCRIMINATOR = [2, 207, 122, 223, 93, 97, 231, 199];
+/**
+ * Discriminator for the Cluster account type. Used to filter and identify Cluster accounts on-chain.
+ */
 const CLUSTER_ACC_DISCRIMINATOR = [236, 225, 118, 228, 173, 106, 18, 60];
-const MXE_ACC_DISCRIMINATOR = [32, 115, 16, 240, 209, 25, 92, 165];
+/**
+ * Discriminator for the MXE account type. Used to filter and identify MXE accounts on-chain.
+ */
+const MXE_ACC_DISCRIMINATOR = [103, 26, 85, 250, 179, 159, 17, 117];
+/**
+ * The public key of the deployed Arcium program on Solana.
+ */
 const ARCIUM_PROGRAM_ID = new anchor__namespace.web3.PublicKey(ARCIUM_PROGRAM_ID_STRING);
+/**
+ * Anchor coder for encoding and decoding Arcium program instructions.
+ */
 new anchor__namespace.BorshInstructionCoder(client.ARCIUM_IDL);
+/**
+ * Anchor event parser for parsing Arcium program events from transaction logs.
+ */
 const ARCIUM_EVENT_CODER = new anchor__namespace.EventParser(ARCIUM_PROGRAM_ID, new anchor__namespace.BorshCoder(client.ARCIUM_IDL));
 
-// Returns all MXE accounts
-async function getMXEAccs(conn) {
+/**
+ * Returns all MXE account addresses.
+ * @param conn - The Solana connection object.
+ * @returns Array of MXE account public keys.
+ */
+async function getMXEAccAddresses(conn) {
     return getArciumAccPubkeys(conn, MXE_ACC_DISCRIMINATOR);
 }
-// Returns all Cluster accounts
-async function getClusterAccs(conn) {
+/**
+ * Returns all Cluster account addresses.
+ * @param conn - The Solana connection object.
+ * @returns Array of Cluster account public keys.
+ */
+async function getClusterAccAddresses(conn) {
     return getArciumAccPubkeys(conn, CLUSTER_ACC_DISCRIMINATOR);
 }
-// Returns all ArxNode accounts
-async function getArxNodeAccs(conn) {
+/**
+ * Returns all ArxNode account addresses.
+ * @param conn - The Solana connection object.
+ * @returns Array of ArxNode account public keys.
+ */
+async function getArxNodeAccAddresses(conn) {
     return getArciumAccPubkeys(conn, ARX_NODE_ACC_DISCRIMINATOR);
 }
-// Fetches and parses a given MXE account. Format:
+/**
+ * Fetches and parses a given MXE account.
+ * @param arciumProgram - The Anchor program instance.
+ * @param address - The public key of the MXE account.
+ * @param commitment - (Optional) RPC commitment level.
+ * @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.
+ * @param arciumProgram - The Anchor program instance.
+ * @param address - The public key of the Cluster account.
+ * @param commitment - (Optional) RPC commitment level.
+ * @returns The ClusterAccount object.
+ */
 async function getClusterAccInfo(arciumProgram, address, commitment) {
     return arciumProgram.account.cluster.fetch(address, commitment);
 }
+/**
+ * Fetches and parses a given ArxNode account.
+ * @param arciumProgram - The Anchor program instance.
+ * @param address - The public key of the ArxNode account.
+ * @param commitment - (Optional) RPC commitment level.
+ * @returns The ArxNodeAccount object.
+ */
 async function getArxNodeAccInfo(arciumProgram, address, commitment) {
     return arciumProgram.account.arxNode.fetch(address, commitment);
 }
+/**
+ * Fetches and parses a given ComputationDefinition account.
+ * @param arciumProgram - The Anchor program instance.
+ * @param address - The public key of the ComputationDefinition account.
+ * @param commitment - (Optional) RPC commitment level.
+ * @returns The ComputationDefinitionAccount object.
+ */
+async function getCompDefAccInfo(arciumProgram, address, commitment) {
+    return arciumProgram.account.computationDefinitionAccount.fetch(address, commitment);
+}
+/**
+ * Returns all computation references in the mempool for a given account.
+ * Only non-stake computations are included.
+ * @param arciumProgram - The Anchor program instance.
+ * @param address - The public key of the mempool account.
+ * @returns Array of ComputationReference objects.
+ */
 async function getComputationsInMempool(arciumProgram, address) {
     const mempool = await client.getMempoolAccData(arciumProgram.provider, address);
     const startIndex = mempool.inner.computations.startIndex;
@@ -75,27 +142,40 @@ async function getComputationsInMempool(arciumProgram, address) {
             refs.push(...elems[idx].entries);
         }
     }
-    return refs.flat().filter((ref) => !isNullRef(ref));
+    return refs
+        .flat()
+        .filter((ref) => !isNullRef(ref));
 }
-async function getComputation(arciumProgram, address, commitment) {
+/**
+ * Fetches and parses a given Computation account.
+ * @param arciumProgram - The Anchor program instance.
+ * @param address - The public key of the Computation account.
+ * @param commitment - (Optional) RPC commitment level.
+ * @returns The Computation object.
+ */
+async function getComputationAccInfo(arciumProgram, address, commitment) {
     return arciumProgram.account.computationAccount.fetch(address, commitment);
 }
 async function getArciumAccPubkeys(conn, discriminator) {
     const accs = await conn.getProgramAccounts(ARCIUM_PROGRAM_ID, {
         dataSlice: { offset: 0, length: 0 },
-        filters: [{
+        filters: [
+            {
                 memcmp: {
                     offset: 0,
                     encoding: 'base64',
                     bytes: Buffer.from(discriminator).toString('base64'),
                 },
-            }],
+            },
+        ],
     });
     return accs.map((acc) => acc.pubkey);
 }
 function isNullRef(ref) {
     const bigZero = new anchor__namespace.BN(0);
-    return ref.computationDefinitionOffset === 0 && ref.computationOffset === bigZero && ref.priorityFee === bigZero;
+    return (ref.computationDefinitionOffset === 0
+        && ref.computationOffset === bigZero
+        && ref.priorityFee === bigZero);
 }
 
 const ArciumEventNames = [
@@ -104,6 +184,13 @@ const ArciumEventNames = [
     'CallbackComputationEvent',
     'FinalizeComputationEvent',
 ];
+/**
+ * Subscribes to computation-related events for a given MXE program ID.
+ * @param conn - The Solana connection object.
+ * @param mxeProgramId - The public key of the MXE program.
+ * @param callback - Callback function to handle each computation event and its name.
+ * @returns The subscription ID for the logs listener.
+ */
 async function subscribeComputations(conn, mxeProgramId, callback) {
     return conn.onLogs(mxeProgramId, (logs) => {
         const events = getComputationEventsFromLogs(logs.logs);
@@ -112,14 +199,19 @@ async function subscribeComputations(conn, mxeProgramId, callback) {
         }
     });
 }
+/**
+ * Unsubscribes from computation-related events using the subscription ID.
+ * @param conn - The Solana connection object.
+ * @param subscriptionId - The subscription ID returned by subscribeComputations.
+ */
 async function unsubscribeComputations(conn, subscriptionId) {
     conn.removeOnLogsListener(subscriptionId);
 }
 /**
- * Get the computation offset from a transaction
- * @param tx - The transaction to get the computation offset from
- * @returns The computation offset if one is found, otherwise null.
- * @throws Error if multiple computation offsets are found in the transaction
+ * Gets the computation offset from a transaction.
+ * @param tx - The transaction to get the computation offset from.
+ * @returns The computation offset if one is found, otherwise undefined.
+ * @throws Error if multiple computation offsets are found in the transaction.
  */
 function getComputationOffset(tx) {
     const events = getComputationEventsFromLogs(tx.meta?.logMessages ?? []);
@@ -128,7 +220,7 @@ function getComputationOffset(tx) {
     }
     const computationOffsets = events.map((e) => e.event.computationOffset);
     const computationOffset = computationOffsets[0];
-    if (computationOffsets.some((offset) => offset !== computationOffset)) {
+    if (computationOffsets.some((offset) => !offset.eq(computationOffset))) {
         throw new Error(`Multiple computation offsets found in computation: ${JSON.stringify(computationOffsets)}`);
     }
     return computationOffset;
@@ -141,60 +233,70 @@ function getComputationOffset(tx) {
 function getComputationEventsFromLogs(logs) {
     return Array.from(ARCIUM_EVENT_CODER.parseLogs(logs))
         .filter((e) => ArciumEventNames.includes(e.name))
-        .map((e) => ({
-        event: e.data,
-        name: e.name,
-    }));
+        .map((e) => {
+        const eventData = {
+            computationOffset: e.data.computation_offset,
+            ...e.data,
+        };
+        if (e.data.mxe_program_id) {
+            eventData.mxeProgramId = e.data.mxe_program_id;
+        }
+        return {
+            event: eventData,
+            name: e.name,
+        };
+    });
 }
 
 Object.defineProperty(exports, "getArciumProgramReadonly", {
     enumerable: true,
     get: function () { return client.getArciumProgramReadonly; }
 });
-Object.defineProperty(exports, "getArxNodeAcc", {
+Object.defineProperty(exports, "getArxNodeAccAddress", {
     enumerable: true,
-    get: function () { return client.getArxNodeAcc; }
+    get: function () { return client.getArxNodeAccAddress; }
 });
-Object.defineProperty(exports, "getClockAcc", {
+Object.defineProperty(exports, "getClockAccAddress", {
     enumerable: true,
-    get: function () { return client.getClockAcc; }
+    get: function () { return client.getClockAccAddress; }
 });
-Object.defineProperty(exports, "getClusterAcc", {
+Object.defineProperty(exports, "getClusterAccAddress", {
     enumerable: true,
-    get: function () { return client.getClusterAcc; }
+    get: function () { return client.getClusterAccAddress; }
 });
-Object.defineProperty(exports, "getCompDefAcc", {
+Object.defineProperty(exports, "getCompDefAccAddress", {
     enumerable: true,
-    get: function () { return client.getCompDefAcc; }
+    get: function () { return client.getCompDefAccAddress; }
 });
-Object.defineProperty(exports, "getComputationAcc", {
+Object.defineProperty(exports, "getComputationAccAddress", {
     enumerable: true,
-    get: function () { return client.getComputationAcc; }
+    get: function () { return client.getComputationAccAddress; }
 });
-Object.defineProperty(exports, "getExecutingPoolAcc", {
+Object.defineProperty(exports, "getExecutingPoolAccAddress", {
     enumerable: true,
-    get: function () { return client.getExecutingPoolAcc; }
+    get: function () { return client.getExecutingPoolAccAddress; }
 });
-Object.defineProperty(exports, "getMXEAccAcc", {
+Object.defineProperty(exports, "getMXEAccAddress", {
     enumerable: true,
-    get: function () { return client.getMXEAccAcc; }
+    get: function () { return client.getMXEAccAddress; }
 });
-Object.defineProperty(exports, "getMempoolAcc", {
+Object.defineProperty(exports, "getMempoolAccAddress", {
     enumerable: true,
-    get: function () { return client.getMempoolAcc; }
+    get: function () { return client.getMempoolAccAddress; }
 });
-Object.defineProperty(exports, "getStakingPoolAcc", {
+Object.defineProperty(exports, "getStakingPoolAccAddress", {
     enumerable: true,
-    get: function () { return client.getStakingPoolAcc; }
+    get: function () { return client.getStakingPoolAccAddress; }
 });
+exports.getArxNodeAccAddresses = getArxNodeAccAddresses;
 exports.getArxNodeAccInfo = getArxNodeAccInfo;
-exports.getArxNodeAccs = getArxNodeAccs;
+exports.getClusterAccAddresses = getClusterAccAddresses;
 exports.getClusterAccInfo = getClusterAccInfo;
-exports.getClusterAccs = getClusterAccs;
-exports.getComputation = getComputation;
+exports.getCompDefAccInfo = getCompDefAccInfo;
+exports.getComputationAccInfo = getComputationAccInfo;
 exports.getComputationOffset = getComputationOffset;
 exports.getComputationsInMempool = getComputationsInMempool;
+exports.getMXEAccAddresses = getMXEAccAddresses;
 exports.getMXEAccInfo = getMXEAccInfo;
-exports.getMXEAccs = getMXEAccs;
 exports.subscribeComputations = subscribeComputations;
 exports.unsubscribeComputations = unsubscribeComputations;

package/build/index.d.ts

@@ -1,41 +1,130 @@
 import { ArciumIdlType } from '@arcium-hq/client';
-export { getArciumProgramReadonly, getArxNodeAcc, getClockAcc, getClusterAcc, getCompDefAcc, getComputationAcc, getExecutingPoolAcc, getMXEAccAcc, getMempoolAcc, getStakingPoolAcc } from '@arcium-hq/client';
+export { getArciumProgramReadonly, getArxNodeAccAddress, getClockAccAddress, getClusterAccAddress, getCompDefAccAddress, getComputationAccAddress, getExecutingPoolAccAddress, getMXEAccAddress, getMempoolAccAddress, getStakingPoolAccAddress } from '@arcium-hq/client';
 import * as anchor from '@coral-xyz/anchor';
 
+/**
+ * Shared type aliases and utility types for the Arcium program.
+ * Many types are derived from the Anchor-generated IDL and are used throughout the reader package.
+ */
+
 type PublicKey = anchor.web3.PublicKey;
 type Connection = anchor.web3.Connection;
 type Program<T extends anchor.Idl> = anchor.Program<T>;
 type ArciumTypes = anchor.IdlTypes<ArciumIdlType>;
+/**
+ * All events emitted by the Arcium program, keyed by event name.
+ */
 type ArciumEvent = anchor.IdlEvents<ArciumIdlType>;
+/**
+ * Capitalized event names, matching the format as emitted by the program.
+ */
 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 Computation = ArciumTypes['computationAccount'];
+type ComputationAccount = ArciumTypes['computationAccount'];
 type ComputationReference = ArciumTypes['computationReference'];
-type QueueComputationIx = ArciumIdlType['instructions']['37'];
-type CallbackComputationIx = ArciumIdlType['instructions']['4'];
-type FinalizeComputationIx = ArciumIdlType['instructions']['17'];
+type ComputationDefinitionAccount = ArciumTypes['computationDefinitionAccount'];
+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.
+ */
 type ComputationStatus = 'queued' | 'executing' | 'executed' | 'finalized' | 'failed';
 
-declare function getMXEAccs(conn: Connection): Promise<PublicKey[]>;
-declare function getClusterAccs(conn: Connection): Promise<PublicKey[]>;
-declare function getArxNodeAccs(conn: Connection): Promise<PublicKey[]>;
+/**
+ * Returns all MXE account addresses.
+ * @param conn - The Solana connection object.
+ * @returns Array of MXE account public keys.
+ */
+declare function getMXEAccAddresses(conn: Connection): Promise<PublicKey[]>;
+/**
+ * Returns all Cluster account addresses.
+ * @param conn - The Solana connection object.
+ * @returns Array of Cluster account public keys.
+ */
+declare function getClusterAccAddresses(conn: Connection): Promise<PublicKey[]>;
+/**
+ * Returns all ArxNode account addresses.
+ * @param conn - The Solana connection object.
+ * @returns Array of ArxNode account public keys.
+ */
+declare function getArxNodeAccAddresses(conn: Connection): Promise<PublicKey[]>;
+/**
+ * Fetches and parses a given MXE account.
+ * @param arciumProgram - The Anchor program instance.
+ * @param address - The public key of the MXE account.
+ * @param commitment - (Optional) RPC commitment level.
+ * @returns The MXEAccount object.
+ */
 declare function getMXEAccInfo(arciumProgram: anchor.Program<ArciumIdlType>, address: PublicKey, commitment?: anchor.web3.Commitment): Promise<MXEAccount>;
+/**
+ * Fetches and parses a given Cluster account.
+ * @param arciumProgram - The Anchor program instance.
+ * @param address - The public key of the Cluster account.
+ * @param commitment - (Optional) RPC commitment level.
+ * @returns The ClusterAccount object.
+ */
 declare function getClusterAccInfo(arciumProgram: anchor.Program<ArciumIdlType>, address: PublicKey, commitment?: anchor.web3.Commitment): Promise<ClusterAccount>;
+/**
+ * Fetches and parses a given ArxNode account.
+ * @param arciumProgram - The Anchor program instance.
+ * @param address - The public key of the ArxNode account.
+ * @param commitment - (Optional) RPC commitment level.
+ * @returns The ArxNodeAccount object.
+ */
 declare function getArxNodeAccInfo(arciumProgram: anchor.Program<ArciumIdlType>, address: PublicKey, commitment?: anchor.web3.Commitment): Promise<ArxNodeAccount>;
+/**
+ * Fetches and parses a given ComputationDefinition account.
+ * @param arciumProgram - The Anchor program instance.
+ * @param address - The public key of the ComputationDefinition account.
+ * @param commitment - (Optional) RPC commitment level.
+ * @returns The ComputationDefinitionAccount object.
+ */
+declare function getCompDefAccInfo(arciumProgram: anchor.Program<ArciumIdlType>, address: PublicKey, commitment?: anchor.web3.Commitment): Promise<ComputationDefinitionAccount>;
+/**
+ * Returns all computation references in the mempool for a given account.
+ * Only non-stake computations are included.
+ * @param arciumProgram - The Anchor program instance.
+ * @param address - The public key of the mempool account.
+ * @returns Array of ComputationReference objects.
+ */
 declare function getComputationsInMempool(arciumProgram: anchor.Program<ArciumIdlType>, address: PublicKey): Promise<ComputationReference[]>;
-declare function getComputation(arciumProgram: anchor.Program<ArciumIdlType>, address: PublicKey, commitment?: anchor.web3.Commitment): Promise<Computation>;
+/**
+ * Fetches and parses a given Computation account.
+ * @param arciumProgram - The Anchor program instance.
+ * @param address - The public key of the Computation account.
+ * @param commitment - (Optional) RPC commitment level.
+ * @returns The Computation object.
+ */
+declare function getComputationAccInfo(arciumProgram: anchor.Program<ArciumIdlType>, address: PublicKey, commitment?: anchor.web3.Commitment): Promise<ComputationAccount>;
 
+/**
+ * Subscribes to computation-related events for a given MXE program ID.
+ * @param conn - The Solana connection object.
+ * @param mxeProgramId - The public key of the MXE program.
+ * @param callback - Callback function to handle each computation event and its name.
+ * @returns The subscription ID for the logs listener.
+ */
 declare function subscribeComputations(conn: Connection, mxeProgramId: PublicKey, callback: (event: ArciumEventData, name: ArciumEventName) => void): Promise<number>;
+/**
+ * Unsubscribes from computation-related events using the subscription ID.
+ * @param conn - The Solana connection object.
+ * @param subscriptionId - The subscription ID returned by subscribeComputations.
+ */
 declare function unsubscribeComputations(conn: Connection, subscriptionId: number): Promise<void>;
 /**
- * Get the computation offset from a transaction
- * @param tx - The transaction to get the computation offset from
- * @returns The computation offset if one is found, otherwise null.
- * @throws Error if multiple computation offsets are found in the transaction
+ * Gets the computation offset from a transaction.
+ * @param tx - The transaction to get the computation offset from.
+ * @returns The computation offset if one is found, otherwise undefined.
+ * @throws Error if multiple computation offsets are found in the transaction.
  */
 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 Computation, type ComputationReference, type ComputationStatus, type Connection, type FinalizeComputationIx, type MXEAccount, type Program, type PublicKey, type QueueComputationIx, getArxNodeAccInfo, getArxNodeAccs, getClusterAccInfo, getClusterAccs, getComputation, getComputationOffset, getComputationsInMempool, getMXEAccInfo, getMXEAccs, 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

@@ -1,37 +1,104 @@
 import { ARCIUM_IDL, getMempoolAccData } from '@arcium-hq/client';
-export { getArciumProgramReadonly, getArxNodeAcc, getClockAcc, getClusterAcc, getCompDefAcc, getComputationAcc, getExecutingPoolAcc, getMXEAccAcc, getMempoolAcc, getStakingPoolAcc } from '@arcium-hq/client';
+export { getArciumProgramReadonly, getArxNodeAccAddress, getClockAccAddress, getClusterAccAddress, getCompDefAccAddress, getComputationAccAddress, getExecutingPoolAccAddress, getMXEAccAddress, getMempoolAccAddress, getStakingPoolAccAddress } from '@arcium-hq/client';
 import * as anchor from '@coral-xyz/anchor';
 
 const ARCIUM_PROGRAM_ID_STRING = 'BKck65TgoKRokMjQM3datB9oRwJ8rAj2jxPXvHXUvcL6';
+/**
+ * Discriminator for the ArxNode account type. Used to filter and identify ArxNode accounts on-chain.
+ */
 const ARX_NODE_ACC_DISCRIMINATOR = [2, 207, 122, 223, 93, 97, 231, 199];
+/**
+ * Discriminator for the Cluster account type. Used to filter and identify Cluster accounts on-chain.
+ */
 const CLUSTER_ACC_DISCRIMINATOR = [236, 225, 118, 228, 173, 106, 18, 60];
-const MXE_ACC_DISCRIMINATOR = [32, 115, 16, 240, 209, 25, 92, 165];
+/**
+ * Discriminator for the MXE account type. Used to filter and identify MXE accounts on-chain.
+ */
+const MXE_ACC_DISCRIMINATOR = [103, 26, 85, 250, 179, 159, 17, 117];
+/**
+ * The public key of the deployed Arcium program on Solana.
+ */
 const ARCIUM_PROGRAM_ID = new anchor.web3.PublicKey(ARCIUM_PROGRAM_ID_STRING);
+/**
+ * Anchor coder for encoding and decoding Arcium program instructions.
+ */
 new anchor.BorshInstructionCoder(ARCIUM_IDL);
+/**
+ * Anchor event parser for parsing Arcium program events from transaction logs.
+ */
 const ARCIUM_EVENT_CODER = new anchor.EventParser(ARCIUM_PROGRAM_ID, new anchor.BorshCoder(ARCIUM_IDL));
 
-// Returns all MXE accounts
-async function getMXEAccs(conn) {
+/**
+ * Returns all MXE account addresses.
+ * @param conn - The Solana connection object.
+ * @returns Array of MXE account public keys.
+ */
+async function getMXEAccAddresses(conn) {
     return getArciumAccPubkeys(conn, MXE_ACC_DISCRIMINATOR);
 }
-// Returns all Cluster accounts
-async function getClusterAccs(conn) {
+/**
+ * Returns all Cluster account addresses.
+ * @param conn - The Solana connection object.
+ * @returns Array of Cluster account public keys.
+ */
+async function getClusterAccAddresses(conn) {
     return getArciumAccPubkeys(conn, CLUSTER_ACC_DISCRIMINATOR);
 }
-// Returns all ArxNode accounts
-async function getArxNodeAccs(conn) {
+/**
+ * Returns all ArxNode account addresses.
+ * @param conn - The Solana connection object.
+ * @returns Array of ArxNode account public keys.
+ */
+async function getArxNodeAccAddresses(conn) {
     return getArciumAccPubkeys(conn, ARX_NODE_ACC_DISCRIMINATOR);
 }
-// Fetches and parses a given MXE account. Format:
+/**
+ * Fetches and parses a given MXE account.
+ * @param arciumProgram - The Anchor program instance.
+ * @param address - The public key of the MXE account.
+ * @param commitment - (Optional) RPC commitment level.
+ * @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.
+ * @param arciumProgram - The Anchor program instance.
+ * @param address - The public key of the Cluster account.
+ * @param commitment - (Optional) RPC commitment level.
+ * @returns The ClusterAccount object.
+ */
 async function getClusterAccInfo(arciumProgram, address, commitment) {
     return arciumProgram.account.cluster.fetch(address, commitment);
 }
+/**
+ * Fetches and parses a given ArxNode account.
+ * @param arciumProgram - The Anchor program instance.
+ * @param address - The public key of the ArxNode account.
+ * @param commitment - (Optional) RPC commitment level.
+ * @returns The ArxNodeAccount object.
+ */
 async function getArxNodeAccInfo(arciumProgram, address, commitment) {
     return arciumProgram.account.arxNode.fetch(address, commitment);
 }
+/**
+ * Fetches and parses a given ComputationDefinition account.
+ * @param arciumProgram - The Anchor program instance.
+ * @param address - The public key of the ComputationDefinition account.
+ * @param commitment - (Optional) RPC commitment level.
+ * @returns The ComputationDefinitionAccount object.
+ */
+async function getCompDefAccInfo(arciumProgram, address, commitment) {
+    return arciumProgram.account.computationDefinitionAccount.fetch(address, commitment);
+}
+/**
+ * Returns all computation references in the mempool for a given account.
+ * Only non-stake computations are included.
+ * @param arciumProgram - The Anchor program instance.
+ * @param address - The public key of the mempool account.
+ * @returns Array of ComputationReference objects.
+ */
 async function getComputationsInMempool(arciumProgram, address) {
     const mempool = await getMempoolAccData(arciumProgram.provider, address);
     const startIndex = mempool.inner.computations.startIndex;
@@ -55,27 +122,40 @@ async function getComputationsInMempool(arciumProgram, address) {
             refs.push(...elems[idx].entries);
         }
     }
-    return refs.flat().filter((ref) => !isNullRef(ref));
+    return refs
+        .flat()
+        .filter((ref) => !isNullRef(ref));
 }
-async function getComputation(arciumProgram, address, commitment) {
+/**
+ * Fetches and parses a given Computation account.
+ * @param arciumProgram - The Anchor program instance.
+ * @param address - The public key of the Computation account.
+ * @param commitment - (Optional) RPC commitment level.
+ * @returns The Computation object.
+ */
+async function getComputationAccInfo(arciumProgram, address, commitment) {
     return arciumProgram.account.computationAccount.fetch(address, commitment);
 }
 async function getArciumAccPubkeys(conn, discriminator) {
     const accs = await conn.getProgramAccounts(ARCIUM_PROGRAM_ID, {
         dataSlice: { offset: 0, length: 0 },
-        filters: [{
+        filters: [
+            {
                 memcmp: {
                     offset: 0,
                     encoding: 'base64',
                     bytes: Buffer.from(discriminator).toString('base64'),
                 },
-            }],
+            },
+        ],
     });
     return accs.map((acc) => acc.pubkey);
 }
 function isNullRef(ref) {
     const bigZero = new anchor.BN(0);
-    return ref.computationDefinitionOffset === 0 && ref.computationOffset === bigZero && ref.priorityFee === bigZero;
+    return (ref.computationDefinitionOffset === 0
+        && ref.computationOffset === bigZero
+        && ref.priorityFee === bigZero);
 }
 
 const ArciumEventNames = [
@@ -84,6 +164,13 @@ const ArciumEventNames = [
     'CallbackComputationEvent',
     'FinalizeComputationEvent',
 ];
+/**
+ * Subscribes to computation-related events for a given MXE program ID.
+ * @param conn - The Solana connection object.
+ * @param mxeProgramId - The public key of the MXE program.
+ * @param callback - Callback function to handle each computation event and its name.
+ * @returns The subscription ID for the logs listener.
+ */
 async function subscribeComputations(conn, mxeProgramId, callback) {
     return conn.onLogs(mxeProgramId, (logs) => {
         const events = getComputationEventsFromLogs(logs.logs);
@@ -92,14 +179,19 @@ async function subscribeComputations(conn, mxeProgramId, callback) {
         }
     });
 }
+/**
+ * Unsubscribes from computation-related events using the subscription ID.
+ * @param conn - The Solana connection object.
+ * @param subscriptionId - The subscription ID returned by subscribeComputations.
+ */
 async function unsubscribeComputations(conn, subscriptionId) {
     conn.removeOnLogsListener(subscriptionId);
 }
 /**
- * Get the computation offset from a transaction
- * @param tx - The transaction to get the computation offset from
- * @returns The computation offset if one is found, otherwise null.
- * @throws Error if multiple computation offsets are found in the transaction
+ * Gets the computation offset from a transaction.
+ * @param tx - The transaction to get the computation offset from.
+ * @returns The computation offset if one is found, otherwise undefined.
+ * @throws Error if multiple computation offsets are found in the transaction.
  */
 function getComputationOffset(tx) {
     const events = getComputationEventsFromLogs(tx.meta?.logMessages ?? []);
@@ -108,7 +200,7 @@ function getComputationOffset(tx) {
     }
     const computationOffsets = events.map((e) => e.event.computationOffset);
     const computationOffset = computationOffsets[0];
-    if (computationOffsets.some((offset) => offset !== computationOffset)) {
+    if (computationOffsets.some((offset) => !offset.eq(computationOffset))) {
         throw new Error(`Multiple computation offsets found in computation: ${JSON.stringify(computationOffsets)}`);
     }
     return computationOffset;
@@ -121,10 +213,19 @@ function getComputationOffset(tx) {
 function getComputationEventsFromLogs(logs) {
     return Array.from(ARCIUM_EVENT_CODER.parseLogs(logs))
         .filter((e) => ArciumEventNames.includes(e.name))
-        .map((e) => ({
-        event: e.data,
-        name: e.name,
-    }));
+        .map((e) => {
+        const eventData = {
+            computationOffset: e.data.computation_offset,
+            ...e.data,
+        };
+        if (e.data.mxe_program_id) {
+            eventData.mxeProgramId = e.data.mxe_program_id;
+        }
+        return {
+            event: eventData,
+            name: e.name,
+        };
+    });
 }
 
-export { getArxNodeAccInfo, getArxNodeAccs, getClusterAccInfo, getClusterAccs, getComputation, getComputationOffset, getComputationsInMempool, getMXEAccInfo, getMXEAccs, subscribeComputations, unsubscribeComputations };
+export { getArxNodeAccAddresses, getArxNodeAccInfo, getClusterAccAddresses, getClusterAccInfo, getCompDefAccInfo, getComputationAccInfo, getComputationOffset, getComputationsInMempool, getMXEAccAddresses, getMXEAccInfo, subscribeComputations, unsubscribeComputations };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcium-hq/reader",
-  "version": "0.1.46",
+  "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.46"
+    "@arcium-hq/client": "0.2.0"
   },
   "keywords": [
     "Cryptography",