@arcium-hq/reader/README.md

Reader SDK for fetching onchain data for Arcium network programs

# Arcium Reader SDK

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
```

## Quick Start

### 1. Setup

```typescript
import * as anchor from "@coral-xyz/anchor";
import { getArciumProgramReadonly } from "@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);
```

### 2. Query Account Information

```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,
  });
}
```

### 3. Monitor Computations

```typescript
import { subscribeComputations } from "@arcium-hq/reader";

// 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);
  }
);
```

## 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,
  });
}
```

### Cluster Accounts

Cluster accounts manage collections of ARX nodes that execute computations.

```typescript
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

ArxNode accounts represent individual computation nodes in the network.

```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'),
  });
}
```

### Computation Definition Accounts

Track available computation definitions and their configurations.

```typescript
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 
} from "@arcium-hq/reader";

const eventLog: Array<{event: ArciumEventData, name: ArciumEventName, timestamp: Date}> = [];

// Subscribe to events
const subscriptionId = await subscribeComputations(
  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(`Subscribed to events with ID: ${subscriptionId}`);

// Later, unsubscribe
// await unsubscribeComputations(connection, subscriptionId);
```

### Transaction Analysis

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).