@arcium-hq/reader 0.4.0 → 0.5.0

package/README.md

@@ -18,12 +18,12 @@ pnpm add @arcium-hq/reader
 
 ```typescript
 import * as anchor from "@coral-xyz/anchor";
-import { getArciumProgramReadonly } from "@arcium-hq/reader";
+import { getArciumProgram } 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);
+const arciumProgram = getArciumProgram(provider);
 ```
 
 ### 2. Query Account Information
@@ -288,6 +288,6 @@ if (tx) {
 
 ## 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).
+- **[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

package/build/index.cjs

@@ -22,7 +22,26 @@ function _interopNamespaceDefault(e) {
 
 var anchor__namespace = /*#__PURE__*/_interopNamespaceDefault(anchor);
 
-const ARCIUM_PROGRAM_ID_STRING = 'Bv3Fb9VjzjWGfX18QTUcVycAfeLoQ5zZN6vv2g3cTZxp';
+/**
+ * Prefix for program data logs in Solana transaction logs.
+ * @constant {string}
+ */
+const PROGRAM_DATA_PREFIX = 'Program data: ';
+/**
+ * Prefix for program log messages in Solana transaction logs.
+ * @constant {string}
+ */
+const PROGRAM_LOG_PREFIX = 'Program log: ';
+/**
+ * Valid Arcium event names for computation lifecycle tracking.
+ * @constant {ArciumEventName[]}
+ */
+const ARCIUM_EVENT_NAMES = [
+    'QueueComputationEvent',
+    'InitComputationEvent',
+    'CallbackComputationEvent',
+    'FinalizeComputationEvent',
+];
 /**
  * Discriminator for the ArxNode account type. Used to filter and identify ArxNode accounts on-chain.
  */
@@ -38,7 +57,7 @@ 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);
+const ARCIUM_PROGRAM_ID = new anchor__namespace.web3.PublicKey(client.ARCIUM_ADDR);
 /**
  * Anchor coder for encoding and decoding Arcium program instructions.
  */
@@ -117,40 +136,6 @@ async function getArxNodeAccInfo(arciumProgram, address, commitment) {
 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;
-    const length = mempool.inner.computations.length;
-    const elems = mempool.inner.computations.elems;
-    function isValid(validBits, idx) {
-        const byte = idx >>> 3;
-        const bit = idx & 7;
-        if (byte >= validBits.length) {
-            // This should never happen, so we'll want to know about it
-            throw new Error(`isValid: byte ${byte} >= validBits.length ${validBits.length}`);
-        }
-        return (validBits[byte] & (1 << bit)) !== 0;
-    }
-    // Handle circular buffer wraparound
-    const refs = [];
-    for (let i = 0; i < length; i++) {
-        const idx = (startIndex + i) % elems.length;
-        // Only save non-stake computations
-        if (isValid(mempool.inner.computations.validBits, idx)) {
-            refs.push(...elems[idx].entries);
-        }
-    }
-    return refs
-        .flat()
-        .filter((ref) => !isNullRef(ref));
-}
 /**
  * Fetches and parses a given Computation account.
  * @param arciumProgram - The Anchor program instance.
@@ -176,19 +161,7 @@ async function getArciumAccPubkeys(conn, discriminator) {
     });
     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);
-}
 
-const ArciumEventNames = [
-    'QueueComputationEvent',
-    'InitComputationEvent',
-    'CallbackComputationEvent',
-    'FinalizeComputationEvent',
-];
 /**
  * Subscribes to computation-related events for a given MXE program ID.
  * @param conn - The Solana connection object.
@@ -262,17 +235,17 @@ function getComputationEventsFromLogs(logs) {
     // Scan all event logs and rely on discriminators to identify valid Arcium events.
     // This works for both MXE→Arcium CPI and Arcium→MXE CPI transactions.
     for (const log of logs) {
-        if (log.startsWith('Program data: ')) {
-            const eventData = log.slice('Program data: '.length);
+        if (log.startsWith(PROGRAM_DATA_PREFIX)) {
+            const eventData = log.slice(PROGRAM_DATA_PREFIX.length);
             const decoded = ARCIUM_BORSH_CODER.events.decode(eventData);
-            if (decoded && ArciumEventNames.includes(decoded.name)) {
+            if (decoded && ARCIUM_EVENT_NAMES.includes(decoded.name)) {
                 events.push(decoded);
             }
         }
-        else if (log.startsWith('Program log: ')) {
-            const eventData = log.slice('Program log: '.length);
+        else if (log.startsWith(PROGRAM_LOG_PREFIX)) {
+            const eventData = log.slice(PROGRAM_LOG_PREFIX.length);
             const decoded = ARCIUM_BORSH_CODER.events.decode(eventData);
-            if (decoded && ArciumEventNames.includes(decoded.name)) {
+            if (decoded && ARCIUM_EVENT_NAMES.includes(decoded.name)) {
                 events.push(decoded);
             }
         }
@@ -293,9 +266,9 @@ function getComputationEventsFromLogs(logs) {
     });
 }
 
-Object.defineProperty(exports, "getArciumProgramReadonly", {
+Object.defineProperty(exports, "getArciumProgram", {
     enumerable: true,
-    get: function () { return client.getArciumProgramReadonly; }
+    get: function () { return client.getArciumProgram; }
 });
 Object.defineProperty(exports, "getArxNodeAccAddress", {
     enumerable: true,
@@ -317,6 +290,10 @@ Object.defineProperty(exports, "getComputationAccAddress", {
     enumerable: true,
     get: function () { return client.getComputationAccAddress; }
 });
+Object.defineProperty(exports, "getComputationsInMempool", {
+    enumerable: true,
+    get: function () { return client.getComputationsInMempool; }
+});
 Object.defineProperty(exports, "getExecutingPoolAccAddress", {
     enumerable: true,
     get: function () { return client.getExecutingPoolAccAddress; }
@@ -333,6 +310,10 @@ Object.defineProperty(exports, "getMempoolAccAddress", {
     enumerable: true,
     get: function () { return client.getMempoolAccAddress; }
 });
+Object.defineProperty(exports, "getMempoolPriorityFeeStats", {
+    enumerable: true,
+    get: function () { return client.getMempoolPriorityFeeStats; }
+});
 exports.getArxNodeAccAddresses = getArxNodeAccAddresses;
 exports.getArxNodeAccInfo = getArxNodeAccInfo;
 exports.getClusterAccAddresses = getClusterAccAddresses;
@@ -340,7 +321,6 @@ exports.getClusterAccInfo = getClusterAccInfo;
 exports.getCompDefAccInfo = getCompDefAccInfo;
 exports.getComputationAccInfo = getComputationAccInfo;
 exports.getComputationOffset = getComputationOffset;
-exports.getComputationsInMempool = getComputationsInMempool;
 exports.getMXEAccAddresses = getMXEAccAddresses;
 exports.getMXEAccInfo = getMXEAccInfo;
 exports.subscribeComputations = subscribeComputations;

package/build/index.d.ts

@@ -1,5 +1,5 @@
 import { ArciumIdlType } from '@arcium-hq/client';
-export { getArciumProgramReadonly, getArxNodeAccAddress, getClockAccAddress, getClusterAccAddress, getCompDefAccAddress, getComputationAccAddress, getExecutingPoolAccAddress, getFeePoolAccAddress, getMXEAccAddress, getMempoolAccAddress } from '@arcium-hq/client';
+export { getArciumProgram, getArxNodeAccAddress, getClockAccAddress, getClusterAccAddress, getCompDefAccAddress, getComputationAccAddress, getComputationsInMempool, getExecutingPoolAccAddress, getFeePoolAccAddress, getMXEAccAddress, getMempoolAccAddress, getMempoolPriorityFeeStats } from '@arcium-hq/client';
 import * as anchor from '@coral-xyz/anchor';
 
 /**
@@ -7,9 +7,21 @@ import * as anchor from '@coral-xyz/anchor';
  * Many types are derived from the Anchor-generated IDL and are used throughout the reader package.
  */
 
+/**
+ * Solana PublicKey type alias for convenience.
+ */
 type PublicKey = anchor.web3.PublicKey;
+/**
+ * Solana Connection type alias for convenience.
+ */
 type Connection = anchor.web3.Connection;
+/**
+ * Anchor Program type alias with generic IDL support.
+ */
 type Program<T extends anchor.Idl> = anchor.Program<T>;
+/**
+ * Arcium IDL types derived from the Arcium program interface.
+ */
 type ArciumTypes = anchor.IdlTypes<ArciumIdlType>;
 /**
  * All events emitted by the Arcium program, keyed by event name.
@@ -23,14 +35,42 @@ type ArciumEventName = Capitalize<keyof ArciumEvent>;
  * Data structure for any Arcium event, as parsed from logs.
  */
 type ArciumEventData = ArciumEvent[keyof ArciumEvent];
+/**
+ * MXE (Multi-party eXecution Environment) account data structure.
+ */
 type MXEAccount = ArciumTypes['mxeAccount'];
+/**
+ * Cluster account data structure containing node information.
+ */
 type ClusterAccount = ArciumTypes['cluster'];
+/**
+ * ArxNode account data structure for individual computation nodes.
+ */
 type ArxNodeAccount = ArciumTypes['arxNode'];
+/**
+ * Computation account data structure tracking computation state.
+ */
 type ComputationAccount = ArciumTypes['computationAccount'];
+/**
+ * Reference to a computation in a mempool or executing pool.
+ */
 type ComputationReference = ArciumTypes['computationReference'];
+/**
+ * Computation definition account containing circuit configuration.
+ */
 type ComputationDefinitionAccount = ArciumTypes['computationDefinitionAccount'];
-type QueueComputationIx = ArciumIdlType['instructions']['25'];
+/**
+ * Queue computation instruction type from the Arcium IDL.
+ */
+type QueueComputationIx = ArciumIdlType['instructions']['26'];
+/**
+ * Callback computation instruction type from the Arcium IDL.
+ */
 type CallbackComputationIx = ArciumIdlType['instructions']['3'];
+/**
+ * Valid instruction names from the Arcium IDL.
+ */
+type ArciumInstructionName = ArciumIdlType['instructions'][number]['name'];
 /**
  * Status values for a computation, as defined by the Arcium protocol.
  */
@@ -86,14 +126,6 @@ declare function getArxNodeAccInfo(arciumProgram: anchor.Program<ArciumIdlType>,
  * @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[]>;
 /**
  * Fetches and parses a given Computation account.
  * @param arciumProgram - The Anchor program instance.
@@ -125,5 +157,5 @@ declare function unsubscribeComputations(conn: Connection, subscriptionId: numbe
  */
 declare function getComputationOffset(tx: anchor.web3.VersionedTransactionResponse): anchor.BN | undefined;
 
-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, MXEAccount, Program, PublicKey, QueueComputationIx };
+export { getArxNodeAccAddresses, getArxNodeAccInfo, getClusterAccAddresses, getClusterAccInfo, getCompDefAccInfo, getComputationAccInfo, getComputationOffset, getMXEAccAddresses, getMXEAccInfo, subscribeComputations, unsubscribeComputations };
+export type { ArciumEvent, ArciumEventData, ArciumEventName, ArciumInstructionName, ArciumTypes, ArxNodeAccount, CallbackComputationIx, ClusterAccount, ComputationAccount, ComputationDefinitionAccount, ComputationReference, ComputationStatus, Connection, MXEAccount, Program, PublicKey, QueueComputationIx };

package/build/index.mjs

@@ -1,8 +1,27 @@
-import { ARCIUM_IDL, getMempoolAccData } from '@arcium-hq/client';
-export { getArciumProgramReadonly, getArxNodeAccAddress, getClockAccAddress, getClusterAccAddress, getCompDefAccAddress, getComputationAccAddress, getExecutingPoolAccAddress, getFeePoolAccAddress, getMXEAccAddress, getMempoolAccAddress } from '@arcium-hq/client';
+import { ARCIUM_ADDR, ARCIUM_IDL } from '@arcium-hq/client';
+export { getArciumProgram, getArxNodeAccAddress, getClockAccAddress, getClusterAccAddress, getCompDefAccAddress, getComputationAccAddress, getComputationsInMempool, getExecutingPoolAccAddress, getFeePoolAccAddress, getMXEAccAddress, getMempoolAccAddress, getMempoolPriorityFeeStats } from '@arcium-hq/client';
 import * as anchor from '@coral-xyz/anchor';
 
-const ARCIUM_PROGRAM_ID_STRING = 'Bv3Fb9VjzjWGfX18QTUcVycAfeLoQ5zZN6vv2g3cTZxp';
+/**
+ * Prefix for program data logs in Solana transaction logs.
+ * @constant {string}
+ */
+const PROGRAM_DATA_PREFIX = 'Program data: ';
+/**
+ * Prefix for program log messages in Solana transaction logs.
+ * @constant {string}
+ */
+const PROGRAM_LOG_PREFIX = 'Program log: ';
+/**
+ * Valid Arcium event names for computation lifecycle tracking.
+ * @constant {ArciumEventName[]}
+ */
+const ARCIUM_EVENT_NAMES = [
+    'QueueComputationEvent',
+    'InitComputationEvent',
+    'CallbackComputationEvent',
+    'FinalizeComputationEvent',
+];
 /**
  * Discriminator for the ArxNode account type. Used to filter and identify ArxNode accounts on-chain.
  */
@@ -18,7 +37,7 @@ 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);
+const ARCIUM_PROGRAM_ID = new anchor.web3.PublicKey(ARCIUM_ADDR);
 /**
  * Anchor coder for encoding and decoding Arcium program instructions.
  */
@@ -97,40 +116,6 @@ async function getArxNodeAccInfo(arciumProgram, address, commitment) {
 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;
-    const length = mempool.inner.computations.length;
-    const elems = mempool.inner.computations.elems;
-    function isValid(validBits, idx) {
-        const byte = idx >>> 3;
-        const bit = idx & 7;
-        if (byte >= validBits.length) {
-            // This should never happen, so we'll want to know about it
-            throw new Error(`isValid: byte ${byte} >= validBits.length ${validBits.length}`);
-        }
-        return (validBits[byte] & (1 << bit)) !== 0;
-    }
-    // Handle circular buffer wraparound
-    const refs = [];
-    for (let i = 0; i < length; i++) {
-        const idx = (startIndex + i) % elems.length;
-        // Only save non-stake computations
-        if (isValid(mempool.inner.computations.validBits, idx)) {
-            refs.push(...elems[idx].entries);
-        }
-    }
-    return refs
-        .flat()
-        .filter((ref) => !isNullRef(ref));
-}
 /**
  * Fetches and parses a given Computation account.
  * @param arciumProgram - The Anchor program instance.
@@ -156,19 +141,7 @@ async function getArciumAccPubkeys(conn, discriminator) {
     });
     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);
-}
 
-const ArciumEventNames = [
-    'QueueComputationEvent',
-    'InitComputationEvent',
-    'CallbackComputationEvent',
-    'FinalizeComputationEvent',
-];
 /**
  * Subscribes to computation-related events for a given MXE program ID.
  * @param conn - The Solana connection object.
@@ -242,17 +215,17 @@ function getComputationEventsFromLogs(logs) {
     // Scan all event logs and rely on discriminators to identify valid Arcium events.
     // This works for both MXE→Arcium CPI and Arcium→MXE CPI transactions.
     for (const log of logs) {
-        if (log.startsWith('Program data: ')) {
-            const eventData = log.slice('Program data: '.length);
+        if (log.startsWith(PROGRAM_DATA_PREFIX)) {
+            const eventData = log.slice(PROGRAM_DATA_PREFIX.length);
             const decoded = ARCIUM_BORSH_CODER.events.decode(eventData);
-            if (decoded && ArciumEventNames.includes(decoded.name)) {
+            if (decoded && ARCIUM_EVENT_NAMES.includes(decoded.name)) {
                 events.push(decoded);
             }
         }
-        else if (log.startsWith('Program log: ')) {
-            const eventData = log.slice('Program log: '.length);
+        else if (log.startsWith(PROGRAM_LOG_PREFIX)) {
+            const eventData = log.slice(PROGRAM_LOG_PREFIX.length);
             const decoded = ARCIUM_BORSH_CODER.events.decode(eventData);
-            if (decoded && ArciumEventNames.includes(decoded.name)) {
+            if (decoded && ARCIUM_EVENT_NAMES.includes(decoded.name)) {
                 events.push(decoded);
             }
         }
@@ -273,4 +246,4 @@ function getComputationEventsFromLogs(logs) {
     });
 }
 
-export { getArxNodeAccAddresses, getArxNodeAccInfo, getClusterAccAddresses, getClusterAccInfo, getCompDefAccInfo, getComputationAccInfo, getComputationOffset, getComputationsInMempool, getMXEAccAddresses, getMXEAccInfo, subscribeComputations, unsubscribeComputations };
+export { getArxNodeAccAddresses, getArxNodeAccInfo, getClusterAccAddresses, getClusterAccInfo, getCompDefAccInfo, getComputationAccInfo, getComputationOffset, getMXEAccAddresses, getMXEAccInfo, subscribeComputations, unsubscribeComputations };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcium-hq/reader",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Reader SDK for fetching onchain data for Arcium network programs",
   "author": "Arcium",
   "license": "GPL-3.0-only",
@@ -31,10 +31,7 @@
       "require": "./build/index.cjs"
     }
   ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/arcium-hq/arcium-tooling.git"
-  },
+  "homepage": "https://ts.arcium.com",
   "devDependencies": {
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-typescript": "^12.1.1",
@@ -60,7 +57,7 @@
     "@coral-xyz/anchor": "^0.32.1",
     "@noble/curves": "^1.9.5",
     "@noble/hashes": "^1.7.1",
-    "@arcium-hq/client": "0.4.0"
+    "@arcium-hq/client": "0.5.0"
   },
   "keywords": [
     "Cryptography",