@arcium-hq/reader 0.1.46 → 0.1.47

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +32 -22
  2. package/build/index.cjs +145 -43
  3. package/build/index.d.ts +99 -11
  4. package/build/index.mjs +124 -23
  5. package/package.json +2 -2
package/README.md CHANGED
@@ -9,12 +9,10 @@ npm install @arcium-hq/reader
9
9
 
10
10
  or
11
11
 
12
- ```bash
13
12
  yarn add @arcium-hq/reader
14
13
 
15
14
  or
16
15
 
17
- ```bash
18
16
  pnpm add @arcium-hq/reader
19
17
  ```
20
18
 
@@ -30,7 +28,9 @@ import { getArciumProgramReadonly } from "@arcium-hq/reader";
30
28
 
31
29
  // Assuming you have an AnchorProvider configured (e.g., from anchor.AnchorProvider.env())
32
30
  const provider = anchor.getProvider();
33
- const arciumProgram = getArciumProgramReadonly(provider as anchor.AnchorProvider);
31
+ const arciumProgram = getArciumProgramReadonly(
32
+ provider as anchor.AnchorProvider
33
+ );
34
34
  ```
35
35
 
36
36
  ### Fetching Account Information
@@ -40,10 +40,10 @@ The reader SDK provides functions to fetch and deserialize various Arcium accoun
40
40
  **1. Fetching MXE Accounts:**
41
41
 
42
42
  ```typescript
43
- import { getMXEAccs, getMXEAccInfo } from "@arcium-hq/reader";
43
+ import { getMXEAccAddresses, getMXEAccInfo } from "@arcium-hq/reader";
44
44
 
45
45
  // Get all MXE account public keys
46
- const mxeAccPubkeys = await getMXEAccs(provider.connection);
46
+ const mxeAccPubkeys = await getMXEAccAddresses(provider.connection);
47
47
 
48
48
  // Get detailed info for a specific MXE account
49
49
  if (mxeAccPubkeys.length > 0) {
@@ -56,14 +56,17 @@ if (mxeAccPubkeys.length > 0) {
56
56
  **2. Fetching Cluster Accounts:**
57
57
 
58
58
  ```typescript
59
- import { getClusterAccs, getClusterAccInfo } from "@arcium-hq/reader";
59
+ import { getClusterAccAddresses, getClusterAccInfo } from "@arcium-hq/reader";
60
60
 
61
61
  // Get all Cluster account public keys
62
- const clusterAccPubkeys = await getClusterAccs(provider.connection);
62
+ const clusterAccPubkeys = await getClusterAccAddresses(provider.connection);
63
63
 
64
64
  // Get detailed info for a specific Cluster account
65
65
  if (clusterAccPubkeys.length > 0) {
66
- const clusterInfo = await getClusterAccInfo(arciumProgram, clusterAccPubkeys[0]);
66
+ const clusterInfo = await getClusterAccInfo(
67
+ arciumProgram,
68
+ clusterAccPubkeys[0]
69
+ );
67
70
  console.log("Cluster Account Info:", clusterInfo);
68
71
  // Access fields like clusterInfo.mxes, clusterInfo.nodes, etc.
69
72
  }
@@ -72,14 +75,17 @@ if (clusterAccPubkeys.length > 0) {
72
75
  **3. Fetching ArxNode Accounts:**
73
76
 
74
77
  ```typescript
75
- import { getArxNodeAccs, getArxNodeAccInfo } from "@arcium-hq/reader";
78
+ import { getArxNodeAccAddresses, getArxNodeAccInfo } from "@arcium-hq/reader";
76
79
 
77
80
  // Get all ArxNode account public keys
78
- const arxNodeAccPubkeys = await getArxNodeAccs(provider.connection);
81
+ const arxNodeAccPubkeys = await getArxNodeAccAddresses(provider.connection);
79
82
 
80
83
  // Get detailed info for a specific ArxNode account
81
84
  if (arxNodeAccPubkeys.length > 0) {
82
- const arxNodeInfo = await getArxNodeAccInfo(arciumProgram, arxNodeAccPubkeys[0]);
85
+ const arxNodeInfo = await getArxNodeAccInfo(
86
+ arciumProgram,
87
+ arxNodeAccPubkeys[0]
88
+ );
83
89
  console.log("ArxNode Account Info:", arxNodeInfo);
84
90
  // Access fields like arxNodeInfo.clusterMemberships, etc.
85
91
  }
@@ -90,27 +96,33 @@ if (arxNodeAccPubkeys.length > 0) {
90
96
  You can subscribe to events related to a specific MXE (identified by its program ID) to track the lifecycle of computations it processes.
91
97
 
92
98
  ```typescript
93
- import { subscribeComputations, unsubscribeComputations } from "@arcium-hq/reader";
99
+ import {
100
+ subscribeComputations,
101
+ unsubscribeComputations,
102
+ ArciumEventData,
103
+ ArciumEventName,
104
+ } from "@arcium-hq/reader";
94
105
  import { PublicKey } from "@solana/web3.js";
95
106
 
96
107
  // Assuming `mxeProgramId` is the PublicKey of the MXE program you want to monitor
97
- const mxeProgramId = new PublicKey("YOUR_MXE_PROGRAM_ID");
108
+ const mxeProgramId = new PublicKey("YOUR_MXE_PROGRAM_ID");
98
109
 
99
110
  const eventLog = [];
100
111
 
101
112
  // Define a callback function to handle events
102
- const eventCallback = (eventData: any, eventName: string) => {
113
+ const eventCallback = (
114
+ eventData: ArciumEventData,
115
+ eventName: ArciumEventName
116
+ ) => {
103
117
  console.log(`Received event: ${eventName}`, eventData);
104
118
  eventLog.push({ event: eventData, name: eventName });
105
- // Events typically include QueueComputationEvent, InitComputationEvent,
106
- // CallbackComputationEvent, FinalizeComputationEvent
107
119
  };
108
120
 
109
121
  // Start subscribing
110
- console.log(`Subscribing to computation events for ${mxeProgramId.toBase58()}`)
122
+ console.log(`Subscribing to computation events for ${mxeProgramId.toBase58()}`);
111
123
  const subscriptionId = await subscribeComputations(
112
- provider.connection,
113
- mxeProgramId,
124
+ connection,
125
+ mxeProgramId,
114
126
  eventCallback
115
127
  );
116
128
 
@@ -119,8 +131,6 @@ console.log(`Subscription active with ID: ${subscriptionId}`);
119
131
  // ... later, when you want to stop listening ...
120
132
 
121
133
  // Unsubscribe
122
- await unsubscribeComputations(provider.connection, subscriptionId);
134
+ await unsubscribeComputations(connection, subscriptionId);
123
135
  console.log(`Unsubscribed from computation events.`);
124
-
125
136
  ```
126
-
package/build/index.cjs CHANGED
@@ -23,35 +23,102 @@ function _interopNamespaceDefault(e) {
23
23
  var anchor__namespace = /*#__PURE__*/_interopNamespaceDefault(anchor);
24
24
 
25
25
  const ARCIUM_PROGRAM_ID_STRING = 'BKck65TgoKRokMjQM3datB9oRwJ8rAj2jxPXvHXUvcL6';
26
+ /**
27
+ * Discriminator for the ArxNode account type. Used to filter and identify ArxNode accounts on-chain.
28
+ */
26
29
  const ARX_NODE_ACC_DISCRIMINATOR = [2, 207, 122, 223, 93, 97, 231, 199];
30
+ /**
31
+ * Discriminator for the Cluster account type. Used to filter and identify Cluster accounts on-chain.
32
+ */
27
33
  const CLUSTER_ACC_DISCRIMINATOR = [236, 225, 118, 228, 173, 106, 18, 60];
34
+ /**
35
+ * Discriminator for the MXE account type. Used to filter and identify persistent MXE accounts on-chain.
36
+ */
28
37
  const MXE_ACC_DISCRIMINATOR = [32, 115, 16, 240, 209, 25, 92, 165];
38
+ /**
39
+ * The public key of the deployed Arcium program on Solana.
40
+ */
29
41
  const ARCIUM_PROGRAM_ID = new anchor__namespace.web3.PublicKey(ARCIUM_PROGRAM_ID_STRING);
42
+ /**
43
+ * Anchor coder for encoding and decoding Arcium program instructions.
44
+ */
30
45
  new anchor__namespace.BorshInstructionCoder(client.ARCIUM_IDL);
46
+ /**
47
+ * Anchor event parser for parsing Arcium program events from transaction logs.
48
+ */
31
49
  const ARCIUM_EVENT_CODER = new anchor__namespace.EventParser(ARCIUM_PROGRAM_ID, new anchor__namespace.BorshCoder(client.ARCIUM_IDL));
32
50
 
33
- // Returns all MXE accounts
34
- async function getMXEAccs(conn) {
51
+ /**
52
+ * Returns all MXE account addresses.
53
+ * @param conn - The Solana connection object.
54
+ * @returns Array of MXE account public keys.
55
+ */
56
+ async function getMXEAccAddresses(conn) {
35
57
  return getArciumAccPubkeys(conn, MXE_ACC_DISCRIMINATOR);
36
58
  }
37
- // Returns all Cluster accounts
38
- async function getClusterAccs(conn) {
59
+ /**
60
+ * Returns all Cluster account addresses.
61
+ * @param conn - The Solana connection object.
62
+ * @returns Array of Cluster account public keys.
63
+ */
64
+ async function getClusterAccAddresses(conn) {
39
65
  return getArciumAccPubkeys(conn, CLUSTER_ACC_DISCRIMINATOR);
40
66
  }
41
- // Returns all ArxNode accounts
42
- async function getArxNodeAccs(conn) {
67
+ /**
68
+ * Returns all ArxNode account addresses.
69
+ * @param conn - The Solana connection object.
70
+ * @returns Array of ArxNode account public keys.
71
+ */
72
+ async function getArxNodeAccAddresses(conn) {
43
73
  return getArciumAccPubkeys(conn, ARX_NODE_ACC_DISCRIMINATOR);
44
74
  }
45
- // Fetches and parses a given MXE account. Format:
75
+ /**
76
+ * Fetches and parses a given MXE account.
77
+ * @param arciumProgram - The Anchor program instance.
78
+ * @param address - The public key of the MXE account.
79
+ * @param commitment - (Optional) RPC commitment level.
80
+ * @returns The MXEAccount object.
81
+ */
46
82
  async function getMXEAccInfo(arciumProgram, address, commitment) {
47
83
  return arciumProgram.account.persistentMxeAccount.fetch(address, commitment);
48
84
  }
85
+ /**
86
+ * Fetches and parses a given Cluster account.
87
+ * @param arciumProgram - The Anchor program instance.
88
+ * @param address - The public key of the Cluster account.
89
+ * @param commitment - (Optional) RPC commitment level.
90
+ * @returns The ClusterAccount object.
91
+ */
49
92
  async function getClusterAccInfo(arciumProgram, address, commitment) {
50
93
  return arciumProgram.account.cluster.fetch(address, commitment);
51
94
  }
95
+ /**
96
+ * Fetches and parses a given ArxNode account.
97
+ * @param arciumProgram - The Anchor program instance.
98
+ * @param address - The public key of the ArxNode account.
99
+ * @param commitment - (Optional) RPC commitment level.
100
+ * @returns The ArxNodeAccount object.
101
+ */
52
102
  async function getArxNodeAccInfo(arciumProgram, address, commitment) {
53
103
  return arciumProgram.account.arxNode.fetch(address, commitment);
54
104
  }
105
+ /**
106
+ * Fetches and parses a given ComputationDefinition account.
107
+ * @param arciumProgram - The Anchor program instance.
108
+ * @param address - The public key of the ComputationDefinition account.
109
+ * @param commitment - (Optional) RPC commitment level.
110
+ * @returns The ComputationDefinitionAccount object.
111
+ */
112
+ async function getCompDefAccInfo(arciumProgram, address, commitment) {
113
+ return arciumProgram.account.computationDefinitionAccount.fetch(address, commitment);
114
+ }
115
+ /**
116
+ * Returns all computation references in the mempool for a given account.
117
+ * Only non-stake computations are included.
118
+ * @param arciumProgram - The Anchor program instance.
119
+ * @param address - The public key of the mempool account.
120
+ * @returns Array of ComputationReference objects.
121
+ */
55
122
  async function getComputationsInMempool(arciumProgram, address) {
56
123
  const mempool = await client.getMempoolAccData(arciumProgram.provider, address);
57
124
  const startIndex = mempool.inner.computations.startIndex;
@@ -75,27 +142,40 @@ async function getComputationsInMempool(arciumProgram, address) {
75
142
  refs.push(...elems[idx].entries);
76
143
  }
77
144
  }
78
- return refs.flat().filter((ref) => !isNullRef(ref));
145
+ return refs
146
+ .flat()
147
+ .filter((ref) => !isNullRef(ref));
79
148
  }
80
- async function getComputation(arciumProgram, address, commitment) {
149
+ /**
150
+ * Fetches and parses a given Computation account.
151
+ * @param arciumProgram - The Anchor program instance.
152
+ * @param address - The public key of the Computation account.
153
+ * @param commitment - (Optional) RPC commitment level.
154
+ * @returns The Computation object.
155
+ */
156
+ async function getComputationAccInfo(arciumProgram, address, commitment) {
81
157
  return arciumProgram.account.computationAccount.fetch(address, commitment);
82
158
  }
83
159
  async function getArciumAccPubkeys(conn, discriminator) {
84
160
  const accs = await conn.getProgramAccounts(ARCIUM_PROGRAM_ID, {
85
161
  dataSlice: { offset: 0, length: 0 },
86
- filters: [{
162
+ filters: [
163
+ {
87
164
  memcmp: {
88
165
  offset: 0,
89
166
  encoding: 'base64',
90
167
  bytes: Buffer.from(discriminator).toString('base64'),
91
168
  },
92
- }],
169
+ },
170
+ ],
93
171
  });
94
172
  return accs.map((acc) => acc.pubkey);
95
173
  }
96
174
  function isNullRef(ref) {
97
175
  const bigZero = new anchor__namespace.BN(0);
98
- return ref.computationDefinitionOffset === 0 && ref.computationOffset === bigZero && ref.priorityFee === bigZero;
176
+ return (ref.computationDefinitionOffset === 0
177
+ && ref.computationOffset === bigZero
178
+ && ref.priorityFee === bigZero);
99
179
  }
100
180
 
101
181
  const ArciumEventNames = [
@@ -104,6 +184,13 @@ const ArciumEventNames = [
104
184
  'CallbackComputationEvent',
105
185
  'FinalizeComputationEvent',
106
186
  ];
187
+ /**
188
+ * Subscribes to computation-related events for a given MXE program ID.
189
+ * @param conn - The Solana connection object.
190
+ * @param mxeProgramId - The public key of the MXE program.
191
+ * @param callback - Callback function to handle each computation event and its name.
192
+ * @returns The subscription ID for the logs listener.
193
+ */
107
194
  async function subscribeComputations(conn, mxeProgramId, callback) {
108
195
  return conn.onLogs(mxeProgramId, (logs) => {
109
196
  const events = getComputationEventsFromLogs(logs.logs);
@@ -112,14 +199,19 @@ async function subscribeComputations(conn, mxeProgramId, callback) {
112
199
  }
113
200
  });
114
201
  }
202
+ /**
203
+ * Unsubscribes from computation-related events using the subscription ID.
204
+ * @param conn - The Solana connection object.
205
+ * @param subscriptionId - The subscription ID returned by subscribeComputations.
206
+ */
115
207
  async function unsubscribeComputations(conn, subscriptionId) {
116
208
  conn.removeOnLogsListener(subscriptionId);
117
209
  }
118
210
  /**
119
- * Get the computation offset from a transaction
120
- * @param tx - The transaction to get the computation offset from
121
- * @returns The computation offset if one is found, otherwise null.
122
- * @throws Error if multiple computation offsets are found in the transaction
211
+ * Gets the computation offset from a transaction.
212
+ * @param tx - The transaction to get the computation offset from.
213
+ * @returns The computation offset if one is found, otherwise undefined.
214
+ * @throws Error if multiple computation offsets are found in the transaction.
123
215
  */
124
216
  function getComputationOffset(tx) {
125
217
  const events = getComputationEventsFromLogs(tx.meta?.logMessages ?? []);
@@ -128,7 +220,7 @@ function getComputationOffset(tx) {
128
220
  }
129
221
  const computationOffsets = events.map((e) => e.event.computationOffset);
130
222
  const computationOffset = computationOffsets[0];
131
- if (computationOffsets.some((offset) => offset !== computationOffset)) {
223
+ if (computationOffsets.some((offset) => !offset.eq(computationOffset))) {
132
224
  throw new Error(`Multiple computation offsets found in computation: ${JSON.stringify(computationOffsets)}`);
133
225
  }
134
226
  return computationOffset;
@@ -141,60 +233,70 @@ function getComputationOffset(tx) {
141
233
  function getComputationEventsFromLogs(logs) {
142
234
  return Array.from(ARCIUM_EVENT_CODER.parseLogs(logs))
143
235
  .filter((e) => ArciumEventNames.includes(e.name))
144
- .map((e) => ({
145
- event: e.data,
146
- name: e.name,
147
- }));
236
+ .map((e) => {
237
+ const eventData = {
238
+ computationOffset: e.data.computation_offset,
239
+ ...e.data,
240
+ };
241
+ if (e.data.mxe_program_id) {
242
+ eventData.mxeProgramId = e.data.mxe_program_id;
243
+ }
244
+ return {
245
+ event: eventData,
246
+ name: e.name,
247
+ };
248
+ });
148
249
  }
149
250
 
150
251
  Object.defineProperty(exports, "getArciumProgramReadonly", {
151
252
  enumerable: true,
152
253
  get: function () { return client.getArciumProgramReadonly; }
153
254
  });
154
- Object.defineProperty(exports, "getArxNodeAcc", {
255
+ Object.defineProperty(exports, "getArxNodeAccAddress", {
155
256
  enumerable: true,
156
- get: function () { return client.getArxNodeAcc; }
257
+ get: function () { return client.getArxNodeAccAddress; }
157
258
  });
158
- Object.defineProperty(exports, "getClockAcc", {
259
+ Object.defineProperty(exports, "getClockAccAddress", {
159
260
  enumerable: true,
160
- get: function () { return client.getClockAcc; }
261
+ get: function () { return client.getClockAccAddress; }
161
262
  });
162
- Object.defineProperty(exports, "getClusterAcc", {
263
+ Object.defineProperty(exports, "getClusterAccAddress", {
163
264
  enumerable: true,
164
- get: function () { return client.getClusterAcc; }
265
+ get: function () { return client.getClusterAccAddress; }
165
266
  });
166
- Object.defineProperty(exports, "getCompDefAcc", {
267
+ Object.defineProperty(exports, "getCompDefAccAddress", {
167
268
  enumerable: true,
168
- get: function () { return client.getCompDefAcc; }
269
+ get: function () { return client.getCompDefAccAddress; }
169
270
  });
170
- Object.defineProperty(exports, "getComputationAcc", {
271
+ Object.defineProperty(exports, "getComputationAccAddress", {
171
272
  enumerable: true,
172
- get: function () { return client.getComputationAcc; }
273
+ get: function () { return client.getComputationAccAddress; }
173
274
  });
174
- Object.defineProperty(exports, "getExecutingPoolAcc", {
275
+ Object.defineProperty(exports, "getExecutingPoolAccAddress", {
175
276
  enumerable: true,
176
- get: function () { return client.getExecutingPoolAcc; }
277
+ get: function () { return client.getExecutingPoolAccAddress; }
177
278
  });
178
- Object.defineProperty(exports, "getMXEAccAcc", {
279
+ Object.defineProperty(exports, "getMXEAccAddress", {
179
280
  enumerable: true,
180
- get: function () { return client.getMXEAccAcc; }
281
+ get: function () { return client.getMXEAccAddress; }
181
282
  });
182
- Object.defineProperty(exports, "getMempoolAcc", {
283
+ Object.defineProperty(exports, "getMempoolAccAddress", {
183
284
  enumerable: true,
184
- get: function () { return client.getMempoolAcc; }
285
+ get: function () { return client.getMempoolAccAddress; }
185
286
  });
186
- Object.defineProperty(exports, "getStakingPoolAcc", {
287
+ Object.defineProperty(exports, "getStakingPoolAccAddress", {
187
288
  enumerable: true,
188
- get: function () { return client.getStakingPoolAcc; }
289
+ get: function () { return client.getStakingPoolAccAddress; }
189
290
  });
291
+ exports.getArxNodeAccAddresses = getArxNodeAccAddresses;
190
292
  exports.getArxNodeAccInfo = getArxNodeAccInfo;
191
- exports.getArxNodeAccs = getArxNodeAccs;
293
+ exports.getClusterAccAddresses = getClusterAccAddresses;
192
294
  exports.getClusterAccInfo = getClusterAccInfo;
193
- exports.getClusterAccs = getClusterAccs;
194
- exports.getComputation = getComputation;
295
+ exports.getCompDefAccInfo = getCompDefAccInfo;
296
+ exports.getComputationAccInfo = getComputationAccInfo;
195
297
  exports.getComputationOffset = getComputationOffset;
196
298
  exports.getComputationsInMempool = getComputationsInMempool;
299
+ exports.getMXEAccAddresses = getMXEAccAddresses;
197
300
  exports.getMXEAccInfo = getMXEAccInfo;
198
- exports.getMXEAccs = getMXEAccs;
199
301
  exports.subscribeComputations = subscribeComputations;
200
302
  exports.unsubscribeComputations = unsubscribeComputations;
package/build/index.d.ts CHANGED
@@ -1,41 +1,129 @@
1
1
  import { ArciumIdlType } from '@arcium-hq/client';
2
- export { getArciumProgramReadonly, getArxNodeAcc, getClockAcc, getClusterAcc, getCompDefAcc, getComputationAcc, getExecutingPoolAcc, getMXEAccAcc, getMempoolAcc, getStakingPoolAcc } from '@arcium-hq/client';
2
+ export { getArciumProgramReadonly, getArxNodeAccAddress, getClockAccAddress, getClusterAccAddress, getCompDefAccAddress, getComputationAccAddress, getExecutingPoolAccAddress, getMXEAccAddress, getMempoolAccAddress, getStakingPoolAccAddress } from '@arcium-hq/client';
3
3
  import * as anchor from '@coral-xyz/anchor';
4
4
 
5
+ /**
6
+ * Shared type aliases and utility types for the Arcium program.
7
+ * Many types are derived from the Anchor-generated IDL and are used throughout the reader package.
8
+ */
9
+
5
10
  type PublicKey = anchor.web3.PublicKey;
6
11
  type Connection = anchor.web3.Connection;
7
12
  type Program<T extends anchor.Idl> = anchor.Program<T>;
8
13
  type ArciumTypes = anchor.IdlTypes<ArciumIdlType>;
14
+ /**
15
+ * All events emitted by the Arcium program, keyed by event name.
16
+ */
9
17
  type ArciumEvent = anchor.IdlEvents<ArciumIdlType>;
18
+ /**
19
+ * Capitalized event names, matching the format as emitted by the program.
20
+ */
10
21
  type ArciumEventName = Capitalize<keyof ArciumEvent>;
22
+ /**
23
+ * Data structure for any Arcium event, as parsed from logs.
24
+ */
11
25
  type ArciumEventData = ArciumEvent[keyof ArciumEvent];
12
26
  type MXEAccount = ArciumTypes['persistentMxeAccount'];
13
27
  type ClusterAccount = ArciumTypes['cluster'];
14
28
  type ArxNodeAccount = ArciumTypes['arxNode'];
15
- type Computation = ArciumTypes['computationAccount'];
29
+ type ComputationAccount = ArciumTypes['computationAccount'];
16
30
  type ComputationReference = ArciumTypes['computationReference'];
31
+ type ComputationDefinitionAccount = ArciumTypes['computationDefinitionAccount'];
17
32
  type QueueComputationIx = ArciumIdlType['instructions']['37'];
18
33
  type CallbackComputationIx = ArciumIdlType['instructions']['4'];
19
34
  type FinalizeComputationIx = ArciumIdlType['instructions']['17'];
35
+ /**
36
+ * Status values for a computation, as defined by the Arcium protocol.
37
+ */
20
38
  type ComputationStatus = 'queued' | 'executing' | 'executed' | 'finalized' | 'failed';
21
39
 
22
- declare function getMXEAccs(conn: Connection): Promise<PublicKey[]>;
23
- declare function getClusterAccs(conn: Connection): Promise<PublicKey[]>;
24
- declare function getArxNodeAccs(conn: Connection): Promise<PublicKey[]>;
40
+ /**
41
+ * Returns all MXE account addresses.
42
+ * @param conn - The Solana connection object.
43
+ * @returns Array of MXE account public keys.
44
+ */
45
+ declare function getMXEAccAddresses(conn: Connection): Promise<PublicKey[]>;
46
+ /**
47
+ * Returns all Cluster account addresses.
48
+ * @param conn - The Solana connection object.
49
+ * @returns Array of Cluster account public keys.
50
+ */
51
+ declare function getClusterAccAddresses(conn: Connection): Promise<PublicKey[]>;
52
+ /**
53
+ * Returns all ArxNode account addresses.
54
+ * @param conn - The Solana connection object.
55
+ * @returns Array of ArxNode account public keys.
56
+ */
57
+ declare function getArxNodeAccAddresses(conn: Connection): Promise<PublicKey[]>;
58
+ /**
59
+ * Fetches and parses a given MXE account.
60
+ * @param arciumProgram - The Anchor program instance.
61
+ * @param address - The public key of the MXE account.
62
+ * @param commitment - (Optional) RPC commitment level.
63
+ * @returns The MXEAccount object.
64
+ */
25
65
  declare function getMXEAccInfo(arciumProgram: anchor.Program<ArciumIdlType>, address: PublicKey, commitment?: anchor.web3.Commitment): Promise<MXEAccount>;
66
+ /**
67
+ * Fetches and parses a given Cluster account.
68
+ * @param arciumProgram - The Anchor program instance.
69
+ * @param address - The public key of the Cluster account.
70
+ * @param commitment - (Optional) RPC commitment level.
71
+ * @returns The ClusterAccount object.
72
+ */
26
73
  declare function getClusterAccInfo(arciumProgram: anchor.Program<ArciumIdlType>, address: PublicKey, commitment?: anchor.web3.Commitment): Promise<ClusterAccount>;
74
+ /**
75
+ * Fetches and parses a given ArxNode account.
76
+ * @param arciumProgram - The Anchor program instance.
77
+ * @param address - The public key of the ArxNode account.
78
+ * @param commitment - (Optional) RPC commitment level.
79
+ * @returns The ArxNodeAccount object.
80
+ */
27
81
  declare function getArxNodeAccInfo(arciumProgram: anchor.Program<ArciumIdlType>, address: PublicKey, commitment?: anchor.web3.Commitment): Promise<ArxNodeAccount>;
82
+ /**
83
+ * Fetches and parses a given ComputationDefinition account.
84
+ * @param arciumProgram - The Anchor program instance.
85
+ * @param address - The public key of the ComputationDefinition account.
86
+ * @param commitment - (Optional) RPC commitment level.
87
+ * @returns The ComputationDefinitionAccount object.
88
+ */
89
+ declare function getCompDefAccInfo(arciumProgram: anchor.Program<ArciumIdlType>, address: PublicKey, commitment?: anchor.web3.Commitment): Promise<ComputationDefinitionAccount>;
90
+ /**
91
+ * Returns all computation references in the mempool for a given account.
92
+ * Only non-stake computations are included.
93
+ * @param arciumProgram - The Anchor program instance.
94
+ * @param address - The public key of the mempool account.
95
+ * @returns Array of ComputationReference objects.
96
+ */
28
97
  declare function getComputationsInMempool(arciumProgram: anchor.Program<ArciumIdlType>, address: PublicKey): Promise<ComputationReference[]>;
29
- declare function getComputation(arciumProgram: anchor.Program<ArciumIdlType>, address: PublicKey, commitment?: anchor.web3.Commitment): Promise<Computation>;
98
+ /**
99
+ * Fetches and parses a given Computation account.
100
+ * @param arciumProgram - The Anchor program instance.
101
+ * @param address - The public key of the Computation account.
102
+ * @param commitment - (Optional) RPC commitment level.
103
+ * @returns The Computation object.
104
+ */
105
+ declare function getComputationAccInfo(arciumProgram: anchor.Program<ArciumIdlType>, address: PublicKey, commitment?: anchor.web3.Commitment): Promise<ComputationAccount>;
30
106
 
107
+ /**
108
+ * Subscribes to computation-related events for a given MXE program ID.
109
+ * @param conn - The Solana connection object.
110
+ * @param mxeProgramId - The public key of the MXE program.
111
+ * @param callback - Callback function to handle each computation event and its name.
112
+ * @returns The subscription ID for the logs listener.
113
+ */
31
114
  declare function subscribeComputations(conn: Connection, mxeProgramId: PublicKey, callback: (event: ArciumEventData, name: ArciumEventName) => void): Promise<number>;
115
+ /**
116
+ * Unsubscribes from computation-related events using the subscription ID.
117
+ * @param conn - The Solana connection object.
118
+ * @param subscriptionId - The subscription ID returned by subscribeComputations.
119
+ */
32
120
  declare function unsubscribeComputations(conn: Connection, subscriptionId: number): Promise<void>;
33
121
  /**
34
- * Get the computation offset from a transaction
35
- * @param tx - The transaction to get the computation offset from
36
- * @returns The computation offset if one is found, otherwise null.
37
- * @throws Error if multiple computation offsets are found in the transaction
122
+ * Gets the computation offset from a transaction.
123
+ * @param tx - The transaction to get the computation offset from.
124
+ * @returns The computation offset if one is found, otherwise undefined.
125
+ * @throws Error if multiple computation offsets are found in the transaction.
38
126
  */
39
127
  declare function getComputationOffset(tx: anchor.web3.VersionedTransactionResponse): anchor.BN | undefined;
40
128
 
41
- 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 };
129
+ 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 };
package/build/index.mjs CHANGED
@@ -1,37 +1,104 @@
1
1
  import { ARCIUM_IDL, getMempoolAccData } from '@arcium-hq/client';
2
- export { getArciumProgramReadonly, getArxNodeAcc, getClockAcc, getClusterAcc, getCompDefAcc, getComputationAcc, getExecutingPoolAcc, getMXEAccAcc, getMempoolAcc, getStakingPoolAcc } from '@arcium-hq/client';
2
+ export { getArciumProgramReadonly, getArxNodeAccAddress, getClockAccAddress, getClusterAccAddress, getCompDefAccAddress, getComputationAccAddress, getExecutingPoolAccAddress, getMXEAccAddress, getMempoolAccAddress, getStakingPoolAccAddress } from '@arcium-hq/client';
3
3
  import * as anchor from '@coral-xyz/anchor';
4
4
 
5
5
  const ARCIUM_PROGRAM_ID_STRING = 'BKck65TgoKRokMjQM3datB9oRwJ8rAj2jxPXvHXUvcL6';
6
+ /**
7
+ * Discriminator for the ArxNode account type. Used to filter and identify ArxNode accounts on-chain.
8
+ */
6
9
  const ARX_NODE_ACC_DISCRIMINATOR = [2, 207, 122, 223, 93, 97, 231, 199];
10
+ /**
11
+ * Discriminator for the Cluster account type. Used to filter and identify Cluster accounts on-chain.
12
+ */
7
13
  const CLUSTER_ACC_DISCRIMINATOR = [236, 225, 118, 228, 173, 106, 18, 60];
14
+ /**
15
+ * Discriminator for the MXE account type. Used to filter and identify persistent MXE accounts on-chain.
16
+ */
8
17
  const MXE_ACC_DISCRIMINATOR = [32, 115, 16, 240, 209, 25, 92, 165];
18
+ /**
19
+ * The public key of the deployed Arcium program on Solana.
20
+ */
9
21
  const ARCIUM_PROGRAM_ID = new anchor.web3.PublicKey(ARCIUM_PROGRAM_ID_STRING);
22
+ /**
23
+ * Anchor coder for encoding and decoding Arcium program instructions.
24
+ */
10
25
  new anchor.BorshInstructionCoder(ARCIUM_IDL);
26
+ /**
27
+ * Anchor event parser for parsing Arcium program events from transaction logs.
28
+ */
11
29
  const ARCIUM_EVENT_CODER = new anchor.EventParser(ARCIUM_PROGRAM_ID, new anchor.BorshCoder(ARCIUM_IDL));
12
30
 
13
- // Returns all MXE accounts
14
- async function getMXEAccs(conn) {
31
+ /**
32
+ * Returns all MXE account addresses.
33
+ * @param conn - The Solana connection object.
34
+ * @returns Array of MXE account public keys.
35
+ */
36
+ async function getMXEAccAddresses(conn) {
15
37
  return getArciumAccPubkeys(conn, MXE_ACC_DISCRIMINATOR);
16
38
  }
17
- // Returns all Cluster accounts
18
- async function getClusterAccs(conn) {
39
+ /**
40
+ * Returns all Cluster account addresses.
41
+ * @param conn - The Solana connection object.
42
+ * @returns Array of Cluster account public keys.
43
+ */
44
+ async function getClusterAccAddresses(conn) {
19
45
  return getArciumAccPubkeys(conn, CLUSTER_ACC_DISCRIMINATOR);
20
46
  }
21
- // Returns all ArxNode accounts
22
- async function getArxNodeAccs(conn) {
47
+ /**
48
+ * Returns all ArxNode account addresses.
49
+ * @param conn - The Solana connection object.
50
+ * @returns Array of ArxNode account public keys.
51
+ */
52
+ async function getArxNodeAccAddresses(conn) {
23
53
  return getArciumAccPubkeys(conn, ARX_NODE_ACC_DISCRIMINATOR);
24
54
  }
25
- // Fetches and parses a given MXE account. Format:
55
+ /**
56
+ * Fetches and parses a given MXE account.
57
+ * @param arciumProgram - The Anchor program instance.
58
+ * @param address - The public key of the MXE account.
59
+ * @param commitment - (Optional) RPC commitment level.
60
+ * @returns The MXEAccount object.
61
+ */
26
62
  async function getMXEAccInfo(arciumProgram, address, commitment) {
27
63
  return arciumProgram.account.persistentMxeAccount.fetch(address, commitment);
28
64
  }
65
+ /**
66
+ * Fetches and parses a given Cluster account.
67
+ * @param arciumProgram - The Anchor program instance.
68
+ * @param address - The public key of the Cluster account.
69
+ * @param commitment - (Optional) RPC commitment level.
70
+ * @returns The ClusterAccount object.
71
+ */
29
72
  async function getClusterAccInfo(arciumProgram, address, commitment) {
30
73
  return arciumProgram.account.cluster.fetch(address, commitment);
31
74
  }
75
+ /**
76
+ * Fetches and parses a given ArxNode account.
77
+ * @param arciumProgram - The Anchor program instance.
78
+ * @param address - The public key of the ArxNode account.
79
+ * @param commitment - (Optional) RPC commitment level.
80
+ * @returns The ArxNodeAccount object.
81
+ */
32
82
  async function getArxNodeAccInfo(arciumProgram, address, commitment) {
33
83
  return arciumProgram.account.arxNode.fetch(address, commitment);
34
84
  }
85
+ /**
86
+ * Fetches and parses a given ComputationDefinition account.
87
+ * @param arciumProgram - The Anchor program instance.
88
+ * @param address - The public key of the ComputationDefinition account.
89
+ * @param commitment - (Optional) RPC commitment level.
90
+ * @returns The ComputationDefinitionAccount object.
91
+ */
92
+ async function getCompDefAccInfo(arciumProgram, address, commitment) {
93
+ return arciumProgram.account.computationDefinitionAccount.fetch(address, commitment);
94
+ }
95
+ /**
96
+ * Returns all computation references in the mempool for a given account.
97
+ * Only non-stake computations are included.
98
+ * @param arciumProgram - The Anchor program instance.
99
+ * @param address - The public key of the mempool account.
100
+ * @returns Array of ComputationReference objects.
101
+ */
35
102
  async function getComputationsInMempool(arciumProgram, address) {
36
103
  const mempool = await getMempoolAccData(arciumProgram.provider, address);
37
104
  const startIndex = mempool.inner.computations.startIndex;
@@ -55,27 +122,40 @@ async function getComputationsInMempool(arciumProgram, address) {
55
122
  refs.push(...elems[idx].entries);
56
123
  }
57
124
  }
58
- return refs.flat().filter((ref) => !isNullRef(ref));
125
+ return refs
126
+ .flat()
127
+ .filter((ref) => !isNullRef(ref));
59
128
  }
60
- async function getComputation(arciumProgram, address, commitment) {
129
+ /**
130
+ * Fetches and parses a given Computation account.
131
+ * @param arciumProgram - The Anchor program instance.
132
+ * @param address - The public key of the Computation account.
133
+ * @param commitment - (Optional) RPC commitment level.
134
+ * @returns The Computation object.
135
+ */
136
+ async function getComputationAccInfo(arciumProgram, address, commitment) {
61
137
  return arciumProgram.account.computationAccount.fetch(address, commitment);
62
138
  }
63
139
  async function getArciumAccPubkeys(conn, discriminator) {
64
140
  const accs = await conn.getProgramAccounts(ARCIUM_PROGRAM_ID, {
65
141
  dataSlice: { offset: 0, length: 0 },
66
- filters: [{
142
+ filters: [
143
+ {
67
144
  memcmp: {
68
145
  offset: 0,
69
146
  encoding: 'base64',
70
147
  bytes: Buffer.from(discriminator).toString('base64'),
71
148
  },
72
- }],
149
+ },
150
+ ],
73
151
  });
74
152
  return accs.map((acc) => acc.pubkey);
75
153
  }
76
154
  function isNullRef(ref) {
77
155
  const bigZero = new anchor.BN(0);
78
- return ref.computationDefinitionOffset === 0 && ref.computationOffset === bigZero && ref.priorityFee === bigZero;
156
+ return (ref.computationDefinitionOffset === 0
157
+ && ref.computationOffset === bigZero
158
+ && ref.priorityFee === bigZero);
79
159
  }
80
160
 
81
161
  const ArciumEventNames = [
@@ -84,6 +164,13 @@ const ArciumEventNames = [
84
164
  'CallbackComputationEvent',
85
165
  'FinalizeComputationEvent',
86
166
  ];
167
+ /**
168
+ * Subscribes to computation-related events for a given MXE program ID.
169
+ * @param conn - The Solana connection object.
170
+ * @param mxeProgramId - The public key of the MXE program.
171
+ * @param callback - Callback function to handle each computation event and its name.
172
+ * @returns The subscription ID for the logs listener.
173
+ */
87
174
  async function subscribeComputations(conn, mxeProgramId, callback) {
88
175
  return conn.onLogs(mxeProgramId, (logs) => {
89
176
  const events = getComputationEventsFromLogs(logs.logs);
@@ -92,14 +179,19 @@ async function subscribeComputations(conn, mxeProgramId, callback) {
92
179
  }
93
180
  });
94
181
  }
182
+ /**
183
+ * Unsubscribes from computation-related events using the subscription ID.
184
+ * @param conn - The Solana connection object.
185
+ * @param subscriptionId - The subscription ID returned by subscribeComputations.
186
+ */
95
187
  async function unsubscribeComputations(conn, subscriptionId) {
96
188
  conn.removeOnLogsListener(subscriptionId);
97
189
  }
98
190
  /**
99
- * Get the computation offset from a transaction
100
- * @param tx - The transaction to get the computation offset from
101
- * @returns The computation offset if one is found, otherwise null.
102
- * @throws Error if multiple computation offsets are found in the transaction
191
+ * Gets the computation offset from a transaction.
192
+ * @param tx - The transaction to get the computation offset from.
193
+ * @returns The computation offset if one is found, otherwise undefined.
194
+ * @throws Error if multiple computation offsets are found in the transaction.
103
195
  */
104
196
  function getComputationOffset(tx) {
105
197
  const events = getComputationEventsFromLogs(tx.meta?.logMessages ?? []);
@@ -108,7 +200,7 @@ function getComputationOffset(tx) {
108
200
  }
109
201
  const computationOffsets = events.map((e) => e.event.computationOffset);
110
202
  const computationOffset = computationOffsets[0];
111
- if (computationOffsets.some((offset) => offset !== computationOffset)) {
203
+ if (computationOffsets.some((offset) => !offset.eq(computationOffset))) {
112
204
  throw new Error(`Multiple computation offsets found in computation: ${JSON.stringify(computationOffsets)}`);
113
205
  }
114
206
  return computationOffset;
@@ -121,10 +213,19 @@ function getComputationOffset(tx) {
121
213
  function getComputationEventsFromLogs(logs) {
122
214
  return Array.from(ARCIUM_EVENT_CODER.parseLogs(logs))
123
215
  .filter((e) => ArciumEventNames.includes(e.name))
124
- .map((e) => ({
125
- event: e.data,
126
- name: e.name,
127
- }));
216
+ .map((e) => {
217
+ const eventData = {
218
+ computationOffset: e.data.computation_offset,
219
+ ...e.data,
220
+ };
221
+ if (e.data.mxe_program_id) {
222
+ eventData.mxeProgramId = e.data.mxe_program_id;
223
+ }
224
+ return {
225
+ event: eventData,
226
+ name: e.name,
227
+ };
228
+ });
128
229
  }
129
230
 
130
- export { getArxNodeAccInfo, getArxNodeAccs, getClusterAccInfo, getClusterAccs, getComputation, getComputationOffset, getComputationsInMempool, getMXEAccInfo, getMXEAccs, subscribeComputations, unsubscribeComputations };
231
+ export { getArxNodeAccAddresses, getArxNodeAccInfo, getClusterAccAddresses, getClusterAccInfo, getCompDefAccInfo, getComputationAccInfo, getComputationOffset, getComputationsInMempool, getMXEAccAddresses, getMXEAccInfo, subscribeComputations, unsubscribeComputations };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@arcium-hq/reader",
3
- "version": "0.1.46",
3
+ "version": "0.1.47",
4
4
  "description": "Reader SDK for fetching onchain data for Arcium network programs",
5
5
  "author": "Arcium",
6
6
  "license": "GPL-3.0-only",
@@ -58,7 +58,7 @@
58
58
  "@coral-xyz/anchor": "^0.31.1",
59
59
  "@noble/curves": "^1.8.1",
60
60
  "@noble/hashes": "^1.7.1",
61
- "@arcium-hq/client": "0.1.46"
61
+ "@arcium-hq/client": "0.1.47"
62
62
  },
63
63
  "keywords": [
64
64
  "Cryptography",