@arcium-hq/reader 0.10.3 → 0.11.0

package/README.md

@@ -13,7 +13,7 @@
 
 ## When To Use
 
-- Listing MXE, cluster, and ARX node accounts
+- Listing MXE (MPC eXecution Environment), cluster, and Arx node accounts
 - Fetching typed account state from the Arcium program
 - Monitoring computation activity without writing transactions
 

package/build/index.cjs

@@ -61,7 +61,7 @@ const ARCIUM_PROGRAM_ID = new anchor__namespace.web3.PublicKey(client.ARCIUM_ADD
 /**
  * Anchor coder for encoding and decoding Arcium program instructions.
  */
-new anchor__namespace.BorshInstructionCoder(client.ARCIUM_IDL);
+const ARCIUM_IX_CODER = new anchor__namespace.BorshInstructionCoder(client.ARCIUM_IDL);
 /**
  * Anchor event parser for parsing Arcium program events from transaction logs.
  */
@@ -191,6 +191,7 @@ async function getArciumAccPubkeys(conn, discriminator) {
     return accs.map((acc) => acc.pubkey);
 }
 
+const { BN } = anchor;
 /**
  * Subscribe to computation events for an MXE program.
  *
@@ -311,11 +312,276 @@ function getComputationEventsFromLogs(logs) {
         };
     });
 }
+function formatUnknownError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * `getTransaction` rejects the `processed` commitment, so map down to a
+ * `Finality`: `finalized` passes through, everything else reads `confirmed`.
+ */
+function mapCommitmentToFinality(commitment) {
+    return commitment === 'finalized' ? 'finalized' : 'confirmed';
+}
+/**
+ * Type guard for {@link DecodedQueueIxFields}. Anchor's coder types
+ * `decode().data` as the unspecific `Object`, so the surfaced fields must be
+ * proven present and correctly shaped before they are read.
+ */
+function isDecodedQueueIx(data) {
+    if (data === null || typeof data !== 'object') {
+        return false;
+    }
+    if (!('comp_offset' in data)
+        || !('cu_price_micro' in data)
+        || !('callback_cu_limit' in data)
+        || !('padding' in data)
+        || !('computation_definition_offset' in data)
+        || !('callback_transactions_required' in data)
+        || !('custom_callback_instructions' in data)
+        || !('mxe_program' in data)) {
+        return false;
+    }
+    return (BN.isBN(data.comp_offset)
+        && BN.isBN(data.cu_price_micro)
+        && typeof data.callback_cu_limit === 'number'
+        && typeof data.padding === 'number'
+        && typeof data.computation_definition_offset === 'number'
+        && typeof data.callback_transactions_required === 'number'
+        && Array.isArray(data.custom_callback_instructions)
+        && data.mxe_program instanceof anchor__namespace.web3.PublicKey);
+}
+function feeFromQueueIx(decoded, queueTxSignature) {
+    return {
+        source: 'queueTx',
+        cuPriceMicro: decoded.cu_price_micro,
+        callbackCuLimit: decoded.callback_cu_limit,
+        customCallbackInstructionCount: decoded.custom_callback_instructions.length,
+        computationDefinitionOffset: decoded.computation_definition_offset,
+        callbackTransactionsRequired: decoded.callback_transactions_required,
+        queueTxSignature,
+    };
+}
+/**
+ * Find the `queue_computation` ix in a transaction whose decoded `mxe_program`
+ * and `comp_offset` match, scanning outer ixs first and inner CPI ixs second.
+ *
+ * The ix must carry a `comp` account at IDL index 2. When `match.compPDA` is
+ * given, that account must also equal it: this binds the result to one
+ * historical lifecycle and rejects a same-tx queue for a different cluster's
+ * PDA. When it is omitted, the index-2 slot only has to exist, so an
+ * exact-signature decode needs no current cluster state.
+ *
+ * `queue_computation` is normally a CPI from the MXE program, so the inner-ix
+ * list is the primary path. Outers are scanned first so a present outer match
+ * is never masked by an omitted inner list; only when no outer matched and the
+ * RPC gave no inner list (`innerInstructions` null or absent) do we report
+ * `innerInstructionsOmitted`, distinct from "no queue ix exists".
+ *
+ * Outer ix `data` is `Uint8Array`; inner ix `data` is base58 `string`, routed
+ * by JS type. Anchor's `decode` returns `null` on discriminator mismatch, so
+ * the name check doubles as a discriminator check.
+ */
+function findArciumQueueIx(tx, signature, match) {
+    if (!tx.meta) {
+        throw new Error(`Transaction metadata missing for queue tx ${signature}; cannot resolve account keys.`);
+    }
+    let keys;
+    try {
+        keys = tx.transaction.message.getAccountKeys({
+            accountKeysFromLookups: tx.meta.loadedAddresses,
+        });
+    }
+    catch (error) {
+        throw new Error(`Account keys could not be resolved for queue tx ${signature} `
+            + `(RPC may be missing address-lookup-table metadata): ${formatUnknownError(error)}`);
+    }
+    const tryMatch = (ix) => {
+        const programId = keys.get(ix.programIdIndex);
+        if (!programId || !programId.equals(ARCIUM_PROGRAM_ID)) {
+            return null;
+        }
+        // Index 2 is `comp`; enforce equality to compPDA only when one was supplied.
+        const accountIndexes = ix.accountKeyIndexes ?? ix.accounts;
+        const compIndex = accountIndexes?.[2];
+        const compIxKey = compIndex === undefined ? undefined : keys.get(compIndex);
+        if (!compIxKey) {
+            return null;
+        }
+        if (match.compPDA && !compIxKey.equals(match.compPDA)) {
+            return null;
+        }
+        const decoded = typeof ix.data === 'string'
+            ? ARCIUM_IX_CODER.decode(ix.data, 'base58')
+            : ARCIUM_IX_CODER.decode(Buffer.from(ix.data));
+        if (decoded?.name !== 'queue_computation') {
+            return null;
+        }
+        if (!isDecodedQueueIx(decoded.data)) {
+            return { kind: 'idlMismatch' };
+        }
+        if (!decoded.data.mxe_program.equals(match.mxeProgramId)) {
+            return null;
+        }
+        if (!decoded.data.comp_offset.eq(match.computationOffset)) {
+            return null;
+        }
+        return { kind: 'found', data: decoded.data };
+    };
+    for (const ix of tx.transaction.message.compiledInstructions) {
+        const result = tryMatch(ix);
+        if (result) {
+            return result;
+        }
+    }
+    if (tx.meta.innerInstructions == null) {
+        return { kind: 'innerInstructionsOmitted' };
+    }
+    for (const inner of tx.meta.innerInstructions) {
+        for (const ix of inner.instructions) {
+            const result = tryMatch(ix);
+            if (result) {
+                return result;
+            }
+        }
+    }
+    return { kind: 'notFound' };
+}
+/**
+ * Decode the matching `queue_computation` fee inputs from a fetched tx, or throw
+ * a descriptive `Error` for each non-success outcome.
+ */
+function decodeQueueFeeFromTx(tx, signature, match) {
+    const result = findArciumQueueIx(tx, signature, match);
+    switch (result.kind) {
+        case 'found':
+            return feeFromQueueIx(result.data, signature);
+        case 'idlMismatch':
+            throw new Error(`queue_computation instruction in tx ${signature} does not match the current Arcium IDL.`);
+        case 'innerInstructionsOmitted':
+            throw new Error(`Cannot read inner instructions for tx ${signature}: the RPC omitted them, so the `
+                + `queue_computation CPI is not visible. Use an RPC that records inner instructions.`);
+        case 'notFound':
+            throw new Error(`No matching queue_computation instruction found in tx ${signature} `
+                + `for computation ${match.computationOffset.toString()}.`);
+    }
+}
+/**
+ * Fetch a live computation's on-chain fee by its offset.
+ *
+ * Returns the {@link ComputationFee} `account` variant while the computation
+ * account is alive, or `null` once it has been closed (`claim_computation_rent`,
+ * `reclaim_expired_computation_fee`, or a failure-claim flow). There is no
+ * automatic fallback for closed accounts: the on-chain data is gone, so a caller
+ * that stored the queue tx signature must pass it to
+ * {@link getComputationFeeFromQueueTx} to reconstruct the fee inputs.
+ *
+ * Throws if the live account at `(cluster, offset)` belongs to a different MXE:
+ * the computation PDA is keyed on `(cluster, comp_offset)` only, so two MXEs on
+ * a shared cluster can collide on it across lifecycles, and silently returning
+ * the wrong MXE's fee would be a correctness bug.
+ *
+ * @param arciumProgram - Anchor program instance (Arcium IDL).
+ * @param mxeProgramId - MXE program the computation belongs to; derives the
+ *                       cluster and computation PDA.
+ * @param computationOffset - Computation offset.
+ * @param commitment - RPC commitment for the account reads.
+ * @returns The live account fee, or `null` if the account is closed.
+ *
+ * @example
+ * import { getArciumProgram, getComputationFee, getComputationFeeFromQueueTx } from '@arcium-hq/reader';
+ *
+ * const program = getArciumProgram(provider);
+ * const fee = await getComputationFee(program, mxeProgramId, computationOffset);
+ * if (fee) {
+ *   console.log('Live fee:', fee.baseFee.add(fee.priorityFee).toString());
+ * }
+ * else {
+ *   // Closed: reconstruct from the stored queue tx signature.
+ *   const queued = await getComputationFeeFromQueueTx(program, queueTxSignature, mxeProgramId, computationOffset);
+ *   console.log('cuPriceMicro:', queued.cuPriceMicro.toString());
+ * }
+ */
+async function getComputationFee(arciumProgram, mxeProgramId, computationOffset, commitment) {
+    const mxe = await arciumProgram.account.mxeAccount.fetch(client.getMXEAccAddress(mxeProgramId), commitment);
+    const compPDA = client.getComputationAccAddress(mxe.cluster, computationOffset);
+    const acc = await arciumProgram.account.computationAccount.fetchNullable(compPDA, commitment);
+    if (!acc) {
+        return null;
+    }
+    if (!acc.mxeProgramId.equals(mxeProgramId)) {
+        throw new Error(`Computation at offset ${computationOffset.toString()} (cluster ${mxe.cluster}) is owned by `
+            + `MXE ${acc.mxeProgramId.toBase58()}, not the requested ${mxeProgramId.toBase58()}.`);
+    }
+    return {
+        source: 'account',
+        baseFee: acc.executionFee.baseFee,
+        priorityFee: acc.executionFee.priorityFee,
+        callbackCuLimit: acc.executionFee.callbackCuLimit,
+    };
+}
+/**
+ * Decode a closed computation's raw fee inputs from its `queue_computation`
+ * transaction.
+ *
+ * Fetches the exact `queueTxSignature` (no signature scanning), rejects a failed
+ * or unavailable tx, and decodes the `queue_computation` ix matching
+ * `mxeProgramId` + `computationOffset`. Reads no current MXE/cluster state, so it
+ * stays correct across cluster migration.
+ *
+ * Pass `opts.cluster` to additionally bind the match to the comp PDA derived
+ * from that historical cluster (rejects a same-tx queue for a different
+ * cluster's PDA). Omit it for the common case of a single queue per tx.
+ *
+ * Returns raw queue-time ix inputs, not lamport fees. Exact reconstruction also
+ * needs queue-time state absent from the ix: cluster `cu_price`, comp-def
+ * `cuAmount`, and the callback context: when `callbackCuLimit` is 0 the callback
+ * priority term defaults from `customCallbackInstructionCount`.
+ *
+ * @param arciumProgram - Anchor program instance (Arcium IDL).
+ * @param queueTxSignature - Signature of the tx that queued the computation.
+ * @param mxeProgramId - MXE program the computation belongs to.
+ * @param computationOffset - Computation offset.
+ * @param opts - `cluster` binds the match to a historical cluster's comp PDA;
+ *               `commitment` maps to `confirmed`/`finalized` for the tx fetch.
+ * @returns The `queueTx` fee variant.
+ * @throws `Error` if the tx is unavailable, failed, or carries no matching
+ *         `queue_computation` instruction.
+ */
+async function getComputationFeeFromQueueTx(arciumProgram, queueTxSignature, mxeProgramId, computationOffset, opts = {}) {
+    const rpcFinality = mapCommitmentToFinality(opts.commitment);
+    let tx;
+    try {
+        tx = await arciumProgram.provider.connection.getTransaction(queueTxSignature, {
+            maxSupportedTransactionVersion: 0,
+            commitment: rpcFinality,
+        });
+    }
+    catch (error) {
+        throw new Error(`Failed to fetch queue tx ${queueTxSignature}: ${formatUnknownError(error)}`);
+    }
+    if (!tx) {
+        throw new Error(`Queue transaction ${queueTxSignature} is unavailable from RPC. Use an archive RPC.`);
+    }
+    if (tx.meta?.err != null) {
+        throw new Error(`Queue transaction ${queueTxSignature} failed and did not pay the queue fee.`);
+    }
+    return decodeQueueFeeFromTx(tx, queueTxSignature, {
+        mxeProgramId,
+        computationOffset,
+        compPDA: opts.cluster === undefined
+            ? undefined
+            : client.getComputationAccAddress(opts.cluster, computationOffset),
+    });
+}
 
 Object.defineProperty(exports, "getArciumProgram", {
     enumerable: true,
     get: function () { return client.getArciumProgram; }
 });
+Object.defineProperty(exports, "getArciumSignerAccAddress", {
+    enumerable: true,
+    get: function () { return client.getArciumSignerAccAddress; }
+});
 Object.defineProperty(exports, "getArxNodeAccAddress", {
     enumerable: true,
     get: function () { return client.getArxNodeAccAddress; }
@@ -344,10 +610,18 @@ Object.defineProperty(exports, "getExecutingPoolAccAddress", {
     enumerable: true,
     get: function () { return client.getExecutingPoolAccAddress; }
 });
+Object.defineProperty(exports, "getFailureClaimAccAddress", {
+    enumerable: true,
+    get: function () { return client.getFailureClaimAccAddress; }
+});
 Object.defineProperty(exports, "getFeePoolAccAddress", {
     enumerable: true,
     get: function () { return client.getFeePoolAccAddress; }
 });
+Object.defineProperty(exports, "getLookupTableAddress", {
+    enumerable: true,
+    get: function () { return client.getLookupTableAddress; }
+});
 Object.defineProperty(exports, "getMXEAccAddress", {
     enumerable: true,
     get: function () { return client.getMXEAccAddress; }
@@ -360,12 +634,34 @@ Object.defineProperty(exports, "getMempoolPriorityFeeStats", {
     enumerable: true,
     get: function () { return client.getMempoolPriorityFeeStats; }
 });
+Object.defineProperty(exports, "getMxeRecoveryAccAddress", {
+    enumerable: true,
+    get: function () { return client.getMxeRecoveryAccAddress; }
+});
+Object.defineProperty(exports, "getOperatorAccAddress", {
+    enumerable: true,
+    get: function () { return client.getOperatorAccAddress; }
+});
+Object.defineProperty(exports, "getRawCircuitAccAddress", {
+    enumerable: true,
+    get: function () { return client.getRawCircuitAccAddress; }
+});
+Object.defineProperty(exports, "getRecoveryClusterAccAddress", {
+    enumerable: true,
+    get: function () { return client.getRecoveryClusterAccAddress; }
+});
+Object.defineProperty(exports, "getRecoveryPeerAccAddress", {
+    enumerable: true,
+    get: function () { return client.getRecoveryPeerAccAddress; }
+});
 exports.getArxNodeAccAddresses = getArxNodeAccAddresses;
 exports.getArxNodeAccInfo = getArxNodeAccInfo;
 exports.getClusterAccAddresses = getClusterAccAddresses;
 exports.getClusterAccInfo = getClusterAccInfo;
 exports.getCompDefAccInfo = getCompDefAccInfo;
 exports.getComputationAccInfo = getComputationAccInfo;
+exports.getComputationFee = getComputationFee;
+exports.getComputationFeeFromQueueTx = getComputationFeeFromQueueTx;
 exports.getComputationOffset = getComputationOffset;
 exports.getMXEAccAddresses = getMXEAccAddresses;
 exports.getMXEAccInfo = getMXEAccInfo;

package/build/index.mjs

@@ -1,6 +1,7 @@
-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 { ARCIUM_ADDR, ARCIUM_IDL, getMXEAccAddress, getComputationAccAddress } from '@arcium-hq/client';
+export { getArciumProgram, getArciumSignerAccAddress, getArxNodeAccAddress, getClockAccAddress, getClusterAccAddress, getCompDefAccAddress, getComputationAccAddress, getComputationsInMempool, getExecutingPoolAccAddress, getFailureClaimAccAddress, getFeePoolAccAddress, getLookupTableAddress, getMXEAccAddress, getMempoolAccAddress, getMempoolPriorityFeeStats, getMxeRecoveryAccAddress, getOperatorAccAddress, getRawCircuitAccAddress, getRecoveryClusterAccAddress, getRecoveryPeerAccAddress } from '@arcium-hq/client';
 import * as anchor from '@anchor-lang/core';
+import anchor__default from '@anchor-lang/core';
 
 /**
  * Prefix for program data logs in Solana transaction logs.
@@ -41,7 +42,7 @@ const ARCIUM_PROGRAM_ID = new anchor.web3.PublicKey(ARCIUM_ADDR);
 /**
  * Anchor coder for encoding and decoding Arcium program instructions.
  */
-new anchor.BorshInstructionCoder(ARCIUM_IDL);
+const ARCIUM_IX_CODER = new anchor.BorshInstructionCoder(ARCIUM_IDL);
 /**
  * Anchor event parser for parsing Arcium program events from transaction logs.
  */
@@ -171,6 +172,7 @@ async function getArciumAccPubkeys(conn, discriminator) {
     return accs.map((acc) => acc.pubkey);
 }
 
+const { BN } = anchor__default;
 /**
  * Subscribe to computation events for an MXE program.
  *
@@ -291,5 +293,266 @@ function getComputationEventsFromLogs(logs) {
         };
     });
 }
+function formatUnknownError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * `getTransaction` rejects the `processed` commitment, so map down to a
+ * `Finality`: `finalized` passes through, everything else reads `confirmed`.
+ */
+function mapCommitmentToFinality(commitment) {
+    return commitment === 'finalized' ? 'finalized' : 'confirmed';
+}
+/**
+ * Type guard for {@link DecodedQueueIxFields}. Anchor's coder types
+ * `decode().data` as the unspecific `Object`, so the surfaced fields must be
+ * proven present and correctly shaped before they are read.
+ */
+function isDecodedQueueIx(data) {
+    if (data === null || typeof data !== 'object') {
+        return false;
+    }
+    if (!('comp_offset' in data)
+        || !('cu_price_micro' in data)
+        || !('callback_cu_limit' in data)
+        || !('padding' in data)
+        || !('computation_definition_offset' in data)
+        || !('callback_transactions_required' in data)
+        || !('custom_callback_instructions' in data)
+        || !('mxe_program' in data)) {
+        return false;
+    }
+    return (BN.isBN(data.comp_offset)
+        && BN.isBN(data.cu_price_micro)
+        && typeof data.callback_cu_limit === 'number'
+        && typeof data.padding === 'number'
+        && typeof data.computation_definition_offset === 'number'
+        && typeof data.callback_transactions_required === 'number'
+        && Array.isArray(data.custom_callback_instructions)
+        && data.mxe_program instanceof anchor.web3.PublicKey);
+}
+function feeFromQueueIx(decoded, queueTxSignature) {
+    return {
+        source: 'queueTx',
+        cuPriceMicro: decoded.cu_price_micro,
+        callbackCuLimit: decoded.callback_cu_limit,
+        customCallbackInstructionCount: decoded.custom_callback_instructions.length,
+        computationDefinitionOffset: decoded.computation_definition_offset,
+        callbackTransactionsRequired: decoded.callback_transactions_required,
+        queueTxSignature,
+    };
+}
+/**
+ * Find the `queue_computation` ix in a transaction whose decoded `mxe_program`
+ * and `comp_offset` match, scanning outer ixs first and inner CPI ixs second.
+ *
+ * The ix must carry a `comp` account at IDL index 2. When `match.compPDA` is
+ * given, that account must also equal it: this binds the result to one
+ * historical lifecycle and rejects a same-tx queue for a different cluster's
+ * PDA. When it is omitted, the index-2 slot only has to exist, so an
+ * exact-signature decode needs no current cluster state.
+ *
+ * `queue_computation` is normally a CPI from the MXE program, so the inner-ix
+ * list is the primary path. Outers are scanned first so a present outer match
+ * is never masked by an omitted inner list; only when no outer matched and the
+ * RPC gave no inner list (`innerInstructions` null or absent) do we report
+ * `innerInstructionsOmitted`, distinct from "no queue ix exists".
+ *
+ * Outer ix `data` is `Uint8Array`; inner ix `data` is base58 `string`, routed
+ * by JS type. Anchor's `decode` returns `null` on discriminator mismatch, so
+ * the name check doubles as a discriminator check.
+ */
+function findArciumQueueIx(tx, signature, match) {
+    if (!tx.meta) {
+        throw new Error(`Transaction metadata missing for queue tx ${signature}; cannot resolve account keys.`);
+    }
+    let keys;
+    try {
+        keys = tx.transaction.message.getAccountKeys({
+            accountKeysFromLookups: tx.meta.loadedAddresses,
+        });
+    }
+    catch (error) {
+        throw new Error(`Account keys could not be resolved for queue tx ${signature} `
+            + `(RPC may be missing address-lookup-table metadata): ${formatUnknownError(error)}`);
+    }
+    const tryMatch = (ix) => {
+        const programId = keys.get(ix.programIdIndex);
+        if (!programId || !programId.equals(ARCIUM_PROGRAM_ID)) {
+            return null;
+        }
+        // Index 2 is `comp`; enforce equality to compPDA only when one was supplied.
+        const accountIndexes = ix.accountKeyIndexes ?? ix.accounts;
+        const compIndex = accountIndexes?.[2];
+        const compIxKey = compIndex === undefined ? undefined : keys.get(compIndex);
+        if (!compIxKey) {
+            return null;
+        }
+        if (match.compPDA && !compIxKey.equals(match.compPDA)) {
+            return null;
+        }
+        const decoded = typeof ix.data === 'string'
+            ? ARCIUM_IX_CODER.decode(ix.data, 'base58')
+            : ARCIUM_IX_CODER.decode(Buffer.from(ix.data));
+        if (decoded?.name !== 'queue_computation') {
+            return null;
+        }
+        if (!isDecodedQueueIx(decoded.data)) {
+            return { kind: 'idlMismatch' };
+        }
+        if (!decoded.data.mxe_program.equals(match.mxeProgramId)) {
+            return null;
+        }
+        if (!decoded.data.comp_offset.eq(match.computationOffset)) {
+            return null;
+        }
+        return { kind: 'found', data: decoded.data };
+    };
+    for (const ix of tx.transaction.message.compiledInstructions) {
+        const result = tryMatch(ix);
+        if (result) {
+            return result;
+        }
+    }
+    if (tx.meta.innerInstructions == null) {
+        return { kind: 'innerInstructionsOmitted' };
+    }
+    for (const inner of tx.meta.innerInstructions) {
+        for (const ix of inner.instructions) {
+            const result = tryMatch(ix);
+            if (result) {
+                return result;
+            }
+        }
+    }
+    return { kind: 'notFound' };
+}
+/**
+ * Decode the matching `queue_computation` fee inputs from a fetched tx, or throw
+ * a descriptive `Error` for each non-success outcome.
+ */
+function decodeQueueFeeFromTx(tx, signature, match) {
+    const result = findArciumQueueIx(tx, signature, match);
+    switch (result.kind) {
+        case 'found':
+            return feeFromQueueIx(result.data, signature);
+        case 'idlMismatch':
+            throw new Error(`queue_computation instruction in tx ${signature} does not match the current Arcium IDL.`);
+        case 'innerInstructionsOmitted':
+            throw new Error(`Cannot read inner instructions for tx ${signature}: the RPC omitted them, so the `
+                + `queue_computation CPI is not visible. Use an RPC that records inner instructions.`);
+        case 'notFound':
+            throw new Error(`No matching queue_computation instruction found in tx ${signature} `
+                + `for computation ${match.computationOffset.toString()}.`);
+    }
+}
+/**
+ * Fetch a live computation's on-chain fee by its offset.
+ *
+ * Returns the {@link ComputationFee} `account` variant while the computation
+ * account is alive, or `null` once it has been closed (`claim_computation_rent`,
+ * `reclaim_expired_computation_fee`, or a failure-claim flow). There is no
+ * automatic fallback for closed accounts: the on-chain data is gone, so a caller
+ * that stored the queue tx signature must pass it to
+ * {@link getComputationFeeFromQueueTx} to reconstruct the fee inputs.
+ *
+ * Throws if the live account at `(cluster, offset)` belongs to a different MXE:
+ * the computation PDA is keyed on `(cluster, comp_offset)` only, so two MXEs on
+ * a shared cluster can collide on it across lifecycles, and silently returning
+ * the wrong MXE's fee would be a correctness bug.
+ *
+ * @param arciumProgram - Anchor program instance (Arcium IDL).
+ * @param mxeProgramId - MXE program the computation belongs to; derives the
+ *                       cluster and computation PDA.
+ * @param computationOffset - Computation offset.
+ * @param commitment - RPC commitment for the account reads.
+ * @returns The live account fee, or `null` if the account is closed.
+ *
+ * @example
+ * import { getArciumProgram, getComputationFee, getComputationFeeFromQueueTx } from '@arcium-hq/reader';
+ *
+ * const program = getArciumProgram(provider);
+ * const fee = await getComputationFee(program, mxeProgramId, computationOffset);
+ * if (fee) {
+ *   console.log('Live fee:', fee.baseFee.add(fee.priorityFee).toString());
+ * }
+ * else {
+ *   // Closed: reconstruct from the stored queue tx signature.
+ *   const queued = await getComputationFeeFromQueueTx(program, queueTxSignature, mxeProgramId, computationOffset);
+ *   console.log('cuPriceMicro:', queued.cuPriceMicro.toString());
+ * }
+ */
+async function getComputationFee(arciumProgram, mxeProgramId, computationOffset, commitment) {
+    const mxe = await arciumProgram.account.mxeAccount.fetch(getMXEAccAddress(mxeProgramId), commitment);
+    const compPDA = getComputationAccAddress(mxe.cluster, computationOffset);
+    const acc = await arciumProgram.account.computationAccount.fetchNullable(compPDA, commitment);
+    if (!acc) {
+        return null;
+    }
+    if (!acc.mxeProgramId.equals(mxeProgramId)) {
+        throw new Error(`Computation at offset ${computationOffset.toString()} (cluster ${mxe.cluster}) is owned by `
+            + `MXE ${acc.mxeProgramId.toBase58()}, not the requested ${mxeProgramId.toBase58()}.`);
+    }
+    return {
+        source: 'account',
+        baseFee: acc.executionFee.baseFee,
+        priorityFee: acc.executionFee.priorityFee,
+        callbackCuLimit: acc.executionFee.callbackCuLimit,
+    };
+}
+/**
+ * Decode a closed computation's raw fee inputs from its `queue_computation`
+ * transaction.
+ *
+ * Fetches the exact `queueTxSignature` (no signature scanning), rejects a failed
+ * or unavailable tx, and decodes the `queue_computation` ix matching
+ * `mxeProgramId` + `computationOffset`. Reads no current MXE/cluster state, so it
+ * stays correct across cluster migration.
+ *
+ * Pass `opts.cluster` to additionally bind the match to the comp PDA derived
+ * from that historical cluster (rejects a same-tx queue for a different
+ * cluster's PDA). Omit it for the common case of a single queue per tx.
+ *
+ * Returns raw queue-time ix inputs, not lamport fees. Exact reconstruction also
+ * needs queue-time state absent from the ix: cluster `cu_price`, comp-def
+ * `cuAmount`, and the callback context: when `callbackCuLimit` is 0 the callback
+ * priority term defaults from `customCallbackInstructionCount`.
+ *
+ * @param arciumProgram - Anchor program instance (Arcium IDL).
+ * @param queueTxSignature - Signature of the tx that queued the computation.
+ * @param mxeProgramId - MXE program the computation belongs to.
+ * @param computationOffset - Computation offset.
+ * @param opts - `cluster` binds the match to a historical cluster's comp PDA;
+ *               `commitment` maps to `confirmed`/`finalized` for the tx fetch.
+ * @returns The `queueTx` fee variant.
+ * @throws `Error` if the tx is unavailable, failed, or carries no matching
+ *         `queue_computation` instruction.
+ */
+async function getComputationFeeFromQueueTx(arciumProgram, queueTxSignature, mxeProgramId, computationOffset, opts = {}) {
+    const rpcFinality = mapCommitmentToFinality(opts.commitment);
+    let tx;
+    try {
+        tx = await arciumProgram.provider.connection.getTransaction(queueTxSignature, {
+            maxSupportedTransactionVersion: 0,
+            commitment: rpcFinality,
+        });
+    }
+    catch (error) {
+        throw new Error(`Failed to fetch queue tx ${queueTxSignature}: ${formatUnknownError(error)}`);
+    }
+    if (!tx) {
+        throw new Error(`Queue transaction ${queueTxSignature} is unavailable from RPC. Use an archive RPC.`);
+    }
+    if (tx.meta?.err != null) {
+        throw new Error(`Queue transaction ${queueTxSignature} failed and did not pay the queue fee.`);
+    }
+    return decodeQueueFeeFromTx(tx, queueTxSignature, {
+        mxeProgramId,
+        computationOffset,
+        compPDA: opts.cluster === undefined
+            ? undefined
+            : getComputationAccAddress(opts.cluster, computationOffset),
+    });
+}
 
-export { getArxNodeAccAddresses, getArxNodeAccInfo, getClusterAccAddresses, getClusterAccInfo, getCompDefAccInfo, getComputationAccInfo, getComputationOffset, getMXEAccAddresses, getMXEAccInfo, getMxeRecoveryAccInfo, getRecoveryClusterAccInfo, subscribeComputations, unsubscribeComputations };
+export { getArxNodeAccAddresses, getArxNodeAccInfo, getClusterAccAddresses, getClusterAccInfo, getCompDefAccInfo, getComputationAccInfo, getComputationFee, getComputationFeeFromQueueTx, getComputationOffset, getMXEAccAddresses, getMXEAccInfo, getMxeRecoveryAccInfo, getRecoveryClusterAccInfo, subscribeComputations, unsubscribeComputations };

package/build/types/computationGetters.d.ts

@@ -1,5 +1,6 @@
 import * as anchor from '@anchor-lang/core';
-import { ArciumEventName, ComputationEventData, Connection, PublicKey } from './types.js';
+import { ArciumIdlType } from '@arcium-hq/client';
+import type { ArciumEventName, ComputationEventData, ComputationFee, Connection, PublicKey } from './types.js';
 /**
  * Subscribe to computation events for an MXE program.
  *
@@ -38,4 +39,77 @@ export declare function unsubscribeComputations(conn: Connection, subscriptionId
  * @throws Error if multiple computation offsets are found in the transaction.
  */
 export declare function getComputationOffset(tx: anchor.web3.VersionedTransactionResponse): anchor.BN | undefined;
+/**
+ * Fetch a live computation's on-chain fee by its offset.
+ *
+ * Returns the {@link ComputationFee} `account` variant while the computation
+ * account is alive, or `null` once it has been closed (`claim_computation_rent`,
+ * `reclaim_expired_computation_fee`, or a failure-claim flow). There is no
+ * automatic fallback for closed accounts: the on-chain data is gone, so a caller
+ * that stored the queue tx signature must pass it to
+ * {@link getComputationFeeFromQueueTx} to reconstruct the fee inputs.
+ *
+ * Throws if the live account at `(cluster, offset)` belongs to a different MXE:
+ * the computation PDA is keyed on `(cluster, comp_offset)` only, so two MXEs on
+ * a shared cluster can collide on it across lifecycles, and silently returning
+ * the wrong MXE's fee would be a correctness bug.
+ *
+ * @param arciumProgram - Anchor program instance (Arcium IDL).
+ * @param mxeProgramId - MXE program the computation belongs to; derives the
+ *                       cluster and computation PDA.
+ * @param computationOffset - Computation offset.
+ * @param commitment - RPC commitment for the account reads.
+ * @returns The live account fee, or `null` if the account is closed.
+ *
+ * @example
+ * import { getArciumProgram, getComputationFee, getComputationFeeFromQueueTx } from '@arcium-hq/reader';
+ *
+ * const program = getArciumProgram(provider);
+ * const fee = await getComputationFee(program, mxeProgramId, computationOffset);
+ * if (fee) {
+ *   console.log('Live fee:', fee.baseFee.add(fee.priorityFee).toString());
+ * }
+ * else {
+ *   // Closed: reconstruct from the stored queue tx signature.
+ *   const queued = await getComputationFeeFromQueueTx(program, queueTxSignature, mxeProgramId, computationOffset);
+ *   console.log('cuPriceMicro:', queued.cuPriceMicro.toString());
+ * }
+ */
+export declare function getComputationFee(arciumProgram: anchor.Program<ArciumIdlType>, mxeProgramId: PublicKey, computationOffset: anchor.BN, commitment?: anchor.web3.Commitment): Promise<Extract<ComputationFee, {
+    source: 'account';
+}> | null>;
+/**
+ * Decode a closed computation's raw fee inputs from its `queue_computation`
+ * transaction.
+ *
+ * Fetches the exact `queueTxSignature` (no signature scanning), rejects a failed
+ * or unavailable tx, and decodes the `queue_computation` ix matching
+ * `mxeProgramId` + `computationOffset`. Reads no current MXE/cluster state, so it
+ * stays correct across cluster migration.
+ *
+ * Pass `opts.cluster` to additionally bind the match to the comp PDA derived
+ * from that historical cluster (rejects a same-tx queue for a different
+ * cluster's PDA). Omit it for the common case of a single queue per tx.
+ *
+ * Returns raw queue-time ix inputs, not lamport fees. Exact reconstruction also
+ * needs queue-time state absent from the ix: cluster `cu_price`, comp-def
+ * `cuAmount`, and the callback context: when `callbackCuLimit` is 0 the callback
+ * priority term defaults from `customCallbackInstructionCount`.
+ *
+ * @param arciumProgram - Anchor program instance (Arcium IDL).
+ * @param queueTxSignature - Signature of the tx that queued the computation.
+ * @param mxeProgramId - MXE program the computation belongs to.
+ * @param computationOffset - Computation offset.
+ * @param opts - `cluster` binds the match to a historical cluster's comp PDA;
+ *               `commitment` maps to `confirmed`/`finalized` for the tx fetch.
+ * @returns The `queueTx` fee variant.
+ * @throws `Error` if the tx is unavailable, failed, or carries no matching
+ *         `queue_computation` instruction.
+ */
+export declare function getComputationFeeFromQueueTx(arciumProgram: anchor.Program<ArciumIdlType>, queueTxSignature: string, mxeProgramId: PublicKey, computationOffset: anchor.BN, opts?: {
+    cluster?: number;
+    commitment?: anchor.web3.Commitment;
+}): Promise<Extract<ComputationFee, {
+    source: 'queueTx';
+}>>;
 //# sourceMappingURL=computationGetters.d.ts.map

package/build/types/computationGetters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"computationGetters.d.ts","sourceRoot":"","sources":["../../src/computationGetters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAC5C,OAAO,EACH,eAAe,EACf,oBAAoB,EACpB,UAAU,EACV,SAAS,EACZ,MAAM,YAAY,CAAC;AAGpB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,qBAAqB,CACvC,IAAI,EAAE,UAAU,EAChB,YAAY,EAAE,SAAS,EACvB,QAAQ,EAAE,CAAC,KAAK,EAAE,oBAAoB,EAAE,IAAI,EAAE,eAAe,KAAK,IAAI,GACvE,OAAO,CAAC,MAAM,CAAC,CAOjB;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CACzC,IAAI,EAAE,UAAU,EAChB,cAAc,EAAE,MAAM,GACvB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAChC,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,4BAA4B,GAC7C,MAAM,CAAC,EAAE,GAAG,SAAS,CAkBvB"}
+{"version":3,"file":"computationGetters.d.ts","sourceRoot":"","sources":["../../src/computationGetters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAM5C,OAAO,EACH,aAAa,EAGhB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EACR,eAAe,EACf,oBAAoB,EACpB,cAAc,EACd,UAAU,EACV,SAAS,EACZ,MAAM,YAAY,CAAC;AAYpB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,qBAAqB,CACvC,IAAI,EAAE,UAAU,EAChB,YAAY,EAAE,SAAS,EACvB,QAAQ,EAAE,CAAC,KAAK,EAAE,oBAAoB,EAAE,IAAI,EAAE,eAAe,KAAK,IAAI,GACvE,OAAO,CAAC,MAAM,CAAC,CAOjB;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CACzC,IAAI,EAAE,UAAU,EAChB,cAAc,EAAE,MAAM,GACvB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAChC,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,4BAA4B,GAC7C,MAAM,CAAC,EAAE,GAAG,SAAS,CAkBvB;AAwTD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAsB,iBAAiB,CACnC,aAAa,EAAE,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,EAC5C,YAAY,EAAE,SAAS,EACvB,iBAAiB,EAAE,MAAM,CAAC,EAAE,EAC5B,UAAU,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,UAAU,GACpC,OAAO,CAAC,OAAO,CAAC,cAAc,EAAE;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,CAAC,GAAG,IAAI,CAAC,CAyBhE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,4BAA4B,CAC9C,aAAa,EAAE,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,EAC5C,gBAAgB,EAAE,MAAM,EACxB,YAAY,EAAE,SAAS,EACvB,iBAAiB,EAAE,MAAM,CAAC,EAAE,EAC5B,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,UAAU,CAAA;CAAO,GACrE,OAAO,CAAC,OAAO,CAAC,cAAc,EAAE;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,CAAC,CAAC,CA6BzD"}

package/build/types/index.d.ts

@@ -8,7 +8,7 @@
  *
  * @packageDocumentation
  */
-export { getClusterAccAddress, getArxNodeAccAddress, getMXEAccAddress, getArciumProgram, getComputationAccAddress, getMempoolAccAddress, getClockAccAddress, getFeePoolAccAddress, getExecutingPoolAccAddress, getCompDefAccAddress, getComputationsInMempool, getMempoolPriorityFeeStats, } from '@arcium-hq/client';
+export { getClusterAccAddress, getArxNodeAccAddress, getMXEAccAddress, getArciumProgram, getComputationAccAddress, getMempoolAccAddress, getClockAccAddress, getFeePoolAccAddress, getExecutingPoolAccAddress, getCompDefAccAddress, getRecoveryClusterAccAddress, getMxeRecoveryAccAddress, getRecoveryPeerAccAddress, getOperatorAccAddress, getFailureClaimAccAddress, getArciumSignerAccAddress, getRawCircuitAccAddress, getLookupTableAddress, getComputationsInMempool, getMempoolPriorityFeeStats, } from '@arcium-hq/client';
 export * from './accGetters.js';
 export * from './computationGetters.js';
 export * from './types.js';

package/build/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EACH,oBAAoB,EACpB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,wBAAwB,EACxB,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACpB,0BAA0B,EAC1B,oBAAoB,EACpB,wBAAwB,EACxB,0BAA0B,GAC7B,MAAM,mBAAmB,CAAC;AAE3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,yBAAyB,CAAC;AACxC,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EACH,oBAAoB,EACpB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,wBAAwB,EACxB,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACpB,0BAA0B,EAC1B,oBAAoB,EACpB,4BAA4B,EAC5B,wBAAwB,EACxB,yBAAyB,EACzB,qBAAqB,EACrB,yBAAyB,EACzB,yBAAyB,EACzB,uBAAuB,EACvB,qBAAqB,EACrB,wBAAwB,EACxB,0BAA0B,GAC7B,MAAM,mBAAmB,CAAC;AAE3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,yBAAyB,CAAC;AACxC,cAAc,YAAY,CAAC"}

package/build/types/types.d.ts

@@ -4,6 +4,7 @@
  */
 import { ArciumIdlType } from '@arcium-hq/client';
 import * as anchor from '@anchor-lang/core';
+export type { MempoolPriorityFeeStats } from '@arcium-hq/client';
 /**
  * Solana PublicKey type alias for convenience.
  */
@@ -95,4 +96,33 @@ export type ArciumInstructionName = ArciumIdlType['instructions'][number]['name'
  * Status values for a computation, as defined by the Arcium protocol.
  */
 export type ComputationStatus = 'queued' | 'executing' | 'executed' | 'finalized' | 'failed';
+/**
+ * Fee information for a computation, tagged by the source it was read from.
+ *
+ * - `account`: read from the live on-chain `ComputationAccount.executionFee`.
+ * - `queueTx`: the raw queue-time ix inputs decoded from the original
+ *   `queueComputation` instruction, for callers reconstructing a closed
+ *   computation's fee from its queue transaction.
+ *
+ * The `queueTx` variant surfaces raw inputs, not lamport fees. Exact
+ * reconstruction needs queue-time state absent from the ix: `baseFee` from
+ * `cluster.cu_price` x comp-def `cuAmount`, and `priorityFee` from
+ * `cuPriceMicro` x `cuAmount` plus a callback term. When `callbackCuLimit` is 0
+ * (no explicit budget) that callback term defaults from
+ * `customCallbackInstructionCount`, so the count is surfaced for that case.
+ */
+export type ComputationFee = {
+    source: 'account';
+    baseFee: anchor.BN;
+    priorityFee: anchor.BN;
+    callbackCuLimit: number;
+} | {
+    source: 'queueTx';
+    cuPriceMicro: anchor.BN;
+    callbackCuLimit: number;
+    customCallbackInstructionCount: number;
+    computationDefinitionOffset: number;
+    callbackTransactionsRequired: number;
+    queueTxSignature: string;
+};
 //# sourceMappingURL=types.d.ts.map

package/build/types/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAE5C;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC;AAE9C;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC;AAEhD;;GAEG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAE9D;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;AAEzD;;;GAGG;AACH,MAAM,MAAM,eAAe,CAAC,IAAI,SAAS,MAAM,IAAI,OAAO,CAAC,aAAa,CAAC,cAAc,CAAC,CAAC,MAAM,CAAC,EAAE;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC,CAAC;AAElH;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC;AAE1D;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,MAAM,WAAW,CAAC,CAAC;AAE5D;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,WAAW,CAAC,MAAM,WAAW,CAAC,CAAC;AAE7D;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,uBAAuB,GAAG,sBAAsB,GAAG,0BAA0B,GAAG,0BAA0B,CAAC;AAE9I;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,WAAW,CAAC,oBAAoB,CAAC,CAAC;AAErE;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC,YAAY,CAAC,CAAC;AAEnD;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;AAEpD;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,WAAW,CAAC,wBAAwB,CAAC,CAAC;AAE3E;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,WAAW,CAAC,oBAAoB,CAAC,CAAC;AAEnE;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;AAEpD;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,WAAW,CAAC,oBAAoB,CAAC,CAAC;AAEnE;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,WAAW,CAAC,sBAAsB,CAAC,CAAC;AAEvE;;GAEG;AACH,MAAM,MAAM,4BAA4B,GAAG,WAAW,CAAC,8BAA8B,CAAC,CAAC;AAEvF;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,eAAe,CAAC,kBAAkB,CAAC,CAAC;AAErE;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,eAAe,CAAC,qBAAqB,CAAC,CAAC;AAE3E;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,aAAa,CAAC,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;AAElF;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,WAAW,GAAG,UAAU,GAAG,WAAW,GAAG,QAAQ,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAE5C,YAAY,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAEjE;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC;AAE9C;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC;AAEhD;;GAEG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAE9D;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;AAEzD;;;GAGG;AACH,MAAM,MAAM,eAAe,CAAC,IAAI,SAAS,MAAM,IAAI,OAAO,CAAC,aAAa,CAAC,cAAc,CAAC,CAAC,MAAM,CAAC,EAAE;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC,CAAC;AAElH;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC;AAE1D;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,MAAM,WAAW,CAAC,CAAC;AAE5D;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,WAAW,CAAC,MAAM,WAAW,CAAC,CAAC;AAE7D;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,uBAAuB,GAAG,sBAAsB,GAAG,0BAA0B,GAAG,0BAA0B,CAAC;AAE9I;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,WAAW,CAAC,oBAAoB,CAAC,CAAC;AAErE;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC,YAAY,CAAC,CAAC;AAEnD;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;AAEpD;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,WAAW,CAAC,wBAAwB,CAAC,CAAC;AAE3E;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,WAAW,CAAC,oBAAoB,CAAC,CAAC;AAEnE;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;AAEpD;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,WAAW,CAAC,oBAAoB,CAAC,CAAC;AAEnE;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,WAAW,CAAC,sBAAsB,CAAC,CAAC;AAEvE;;GAEG;AACH,MAAM,MAAM,4BAA4B,GAAG,WAAW,CAAC,8BAA8B,CAAC,CAAC;AAEvF;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,eAAe,CAAC,kBAAkB,CAAC,CAAC;AAErE;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,eAAe,CAAC,qBAAqB,CAAC,CAAC;AAE3E;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,aAAa,CAAC,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;AAElF;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,WAAW,GAAG,UAAU,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE7F;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,cAAc,GACpB;IACE,MAAM,EAAE,SAAS,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC,EAAE,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC,EAAE,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;CAC3B,GACC;IACE,MAAM,EAAE,SAAS,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC,EAAE,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,8BAA8B,EAAE,MAAM,CAAC;IACvC,2BAA2B,EAAE,MAAM,CAAC;IACpC,4BAA4B,EAAE,MAAM,CAAC;IACrC,gBAAgB,EAAE,MAAM,CAAC;CAC5B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcium-hq/reader",
-  "version": "0.10.3",
+  "version": "0.11.0",
   "description": "Reader SDK for fetching onchain data for Arcium network programs",
   "author": "Arcium",
   "license": "GPL-3.0-only",
@@ -58,7 +58,7 @@
     "@anchor-lang/core": "^1.0.2",
     "@noble/curves": "^1.9.5",
     "@noble/hashes": "^1.7.1",
-    "@arcium-hq/client": "0.10.3"
+    "@arcium-hq/client": "0.11.0"
   },
   "keywords": [
     "Cryptography",

package/src/computationGetters.ts

@@ -1,11 +1,31 @@
 import * as anchor from '@anchor-lang/core';
+// `anchor.BN` is exposed on the CJS module via `Object.defineProperty` with a
+// runtime getter, which Node's ESM-CJS interop does not hoist into the
+// namespace import. The default import bypasses this and lands the constructor
+// reliably under both Rollup bundling and ts-node/esm test execution.
+import anchorPkg from '@anchor-lang/core';
 import {
+    ArciumIdlType,
+    getComputationAccAddress,
+    getMXEAccAddress,
+} from '@arcium-hq/client';
+import type {
     ArciumEventName,
     ComputationEventData,
+    ComputationFee,
     Connection,
     PublicKey,
 } from './types.js';
-import { ARCIUM_BORSH_CODER, PROGRAM_DATA_PREFIX, PROGRAM_LOG_PREFIX, ARCIUM_EVENT_NAMES } from './constants.js';
+import {
+    ARCIUM_BORSH_CODER,
+    ARCIUM_IX_CODER,
+    ARCIUM_PROGRAM_ID,
+    PROGRAM_DATA_PREFIX,
+    PROGRAM_LOG_PREFIX,
+    ARCIUM_EVENT_NAMES,
+} from './constants.js';
+
+const { BN } = anchorPkg;
 
 /**
  * Subscribe to computation events for an MXE program.
@@ -154,3 +174,375 @@ function getComputationEventsFromLogs(
         };
     });
 }
+
+/**
+ * Fields decoded from a `queue_computation` instruction.
+ *
+ * snake_case because the runtime IDL (`arcium.json`) names args in snake_case,
+ * even though the camelCase TS IDL types differ. Runtime narrowing target for
+ * the {@link anchor.BorshInstructionCoder} `decode` result, whose `data` is
+ * typed as the unspecific `Object`.
+ */
+type DecodedQueueIxFields = {
+    comp_offset: anchor.BN;
+    cu_price_micro: anchor.BN;
+    callback_cu_limit: number;
+    padding: number;
+    computation_definition_offset: number;
+    callback_transactions_required: number;
+    custom_callback_instructions: unknown[];
+    mxe_program: anchor.web3.PublicKey;
+};
+
+type QueueIxSearchResult =
+    | { kind: 'found'; data: DecodedQueueIxFields }
+    | { kind: 'notFound' }
+    | { kind: 'idlMismatch' }
+    | { kind: 'innerInstructionsOmitted' };
+
+function formatUnknownError(error: unknown): string {
+    return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * `getTransaction` rejects the `processed` commitment, so map down to a
+ * `Finality`: `finalized` passes through, everything else reads `confirmed`.
+ */
+function mapCommitmentToFinality(commitment: anchor.web3.Commitment | undefined): anchor.web3.Finality {
+    return commitment === 'finalized' ? 'finalized' : 'confirmed';
+}
+
+/**
+ * Type guard for {@link DecodedQueueIxFields}. Anchor's coder types
+ * `decode().data` as the unspecific `Object`, so the surfaced fields must be
+ * proven present and correctly shaped before they are read.
+ */
+function isDecodedQueueIx(data: unknown): data is DecodedQueueIxFields {
+    if (data === null || typeof data !== 'object') {
+        return false;
+    }
+
+    if (
+        !('comp_offset' in data)
+        || !('cu_price_micro' in data)
+        || !('callback_cu_limit' in data)
+        || !('padding' in data)
+        || !('computation_definition_offset' in data)
+        || !('callback_transactions_required' in data)
+        || !('custom_callback_instructions' in data)
+        || !('mxe_program' in data)
+    ) {
+        return false;
+    }
+
+    return (
+        BN.isBN(data.comp_offset)
+        && BN.isBN(data.cu_price_micro)
+        && typeof data.callback_cu_limit === 'number'
+        && typeof data.padding === 'number'
+        && typeof data.computation_definition_offset === 'number'
+        && typeof data.callback_transactions_required === 'number'
+        && Array.isArray(data.custom_callback_instructions)
+        && data.mxe_program instanceof anchor.web3.PublicKey
+    );
+}
+
+function feeFromQueueIx(
+    decoded: DecodedQueueIxFields,
+    queueTxSignature: string,
+): Extract<ComputationFee, { source: 'queueTx' }> {
+    return {
+        source: 'queueTx',
+        cuPriceMicro: decoded.cu_price_micro,
+        callbackCuLimit: decoded.callback_cu_limit,
+        customCallbackInstructionCount: decoded.custom_callback_instructions.length,
+        computationDefinitionOffset: decoded.computation_definition_offset,
+        callbackTransactionsRequired: decoded.callback_transactions_required,
+        queueTxSignature,
+    };
+}
+
+/**
+ * Find the `queue_computation` ix in a transaction whose decoded `mxe_program`
+ * and `comp_offset` match, scanning outer ixs first and inner CPI ixs second.
+ *
+ * The ix must carry a `comp` account at IDL index 2. When `match.compPDA` is
+ * given, that account must also equal it: this binds the result to one
+ * historical lifecycle and rejects a same-tx queue for a different cluster's
+ * PDA. When it is omitted, the index-2 slot only has to exist, so an
+ * exact-signature decode needs no current cluster state.
+ *
+ * `queue_computation` is normally a CPI from the MXE program, so the inner-ix
+ * list is the primary path. Outers are scanned first so a present outer match
+ * is never masked by an omitted inner list; only when no outer matched and the
+ * RPC gave no inner list (`innerInstructions` null or absent) do we report
+ * `innerInstructionsOmitted`, distinct from "no queue ix exists".
+ *
+ * Outer ix `data` is `Uint8Array`; inner ix `data` is base58 `string`, routed
+ * by JS type. Anchor's `decode` returns `null` on discriminator mismatch, so
+ * the name check doubles as a discriminator check.
+ */
+function findArciumQueueIx(
+    tx: anchor.web3.VersionedTransactionResponse,
+    signature: string,
+    match: {
+        mxeProgramId: PublicKey;
+        computationOffset: anchor.BN;
+        compPDA?: PublicKey;
+    },
+): QueueIxSearchResult {
+    if (!tx.meta) {
+        throw new Error(`Transaction metadata missing for queue tx ${signature}; cannot resolve account keys.`);
+    }
+
+    let keys: anchor.web3.MessageAccountKeys;
+    try {
+        keys = tx.transaction.message.getAccountKeys({
+            accountKeysFromLookups: tx.meta.loadedAddresses,
+        });
+    }
+    catch (error) {
+        throw new Error(
+            `Account keys could not be resolved for queue tx ${signature} `
+                + `(RPC may be missing address-lookup-table metadata): ${formatUnknownError(error)}`,
+        );
+    }
+
+    // Outer (compiled) ixs expose `accountKeyIndexes`; inner ixs expose
+    // `accounts`. Both are `number[]` indexing the same resolved key map.
+    type MaybeIx = {
+        programIdIndex: number;
+        data: Uint8Array | string;
+        accountKeyIndexes?: number[];
+        accounts?: number[];
+    };
+
+    const tryMatch = (ix: MaybeIx): QueueIxSearchResult | null => {
+        const programId = keys.get(ix.programIdIndex);
+        if (!programId || !programId.equals(ARCIUM_PROGRAM_ID)) {
+            return null;
+        }
+
+        // Index 2 is `comp`; enforce equality to compPDA only when one was supplied.
+        const accountIndexes = ix.accountKeyIndexes ?? ix.accounts;
+        const compIndex = accountIndexes?.[2];
+        const compIxKey = compIndex === undefined ? undefined : keys.get(compIndex);
+        if (!compIxKey) {
+            return null;
+        }
+        if (match.compPDA && !compIxKey.equals(match.compPDA)) {
+            return null;
+        }
+
+        const decoded = typeof ix.data === 'string'
+            ? ARCIUM_IX_CODER.decode(ix.data, 'base58')
+            : ARCIUM_IX_CODER.decode(Buffer.from(ix.data));
+
+        if (decoded?.name !== 'queue_computation') {
+            return null;
+        }
+
+        if (!isDecodedQueueIx(decoded.data)) {
+            return { kind: 'idlMismatch' };
+        }
+
+        if (!decoded.data.mxe_program.equals(match.mxeProgramId)) {
+            return null;
+        }
+
+        if (!decoded.data.comp_offset.eq(match.computationOffset)) {
+            return null;
+        }
+
+        return { kind: 'found', data: decoded.data };
+    };
+
+    for (const ix of tx.transaction.message.compiledInstructions) {
+        const result = tryMatch(ix);
+        if (result) {
+            return result;
+        }
+    }
+
+    if (tx.meta.innerInstructions == null) {
+        return { kind: 'innerInstructionsOmitted' };
+    }
+
+    for (const inner of tx.meta.innerInstructions) {
+        for (const ix of inner.instructions) {
+            const result = tryMatch(ix);
+            if (result) {
+                return result;
+            }
+        }
+    }
+
+    return { kind: 'notFound' };
+}
+
+/**
+ * Decode the matching `queue_computation` fee inputs from a fetched tx, or throw
+ * a descriptive `Error` for each non-success outcome.
+ */
+function decodeQueueFeeFromTx(
+    tx: anchor.web3.VersionedTransactionResponse,
+    signature: string,
+    match: {
+        mxeProgramId: PublicKey;
+        computationOffset: anchor.BN;
+        compPDA?: PublicKey;
+    },
+): Extract<ComputationFee, { source: 'queueTx' }> {
+    const result = findArciumQueueIx(tx, signature, match);
+    switch (result.kind) {
+        case 'found':
+            return feeFromQueueIx(result.data, signature);
+        case 'idlMismatch':
+            throw new Error(
+                `queue_computation instruction in tx ${signature} does not match the current Arcium IDL.`,
+            );
+        case 'innerInstructionsOmitted':
+            throw new Error(
+                `Cannot read inner instructions for tx ${signature}: the RPC omitted them, so the `
+                    + `queue_computation CPI is not visible. Use an RPC that records inner instructions.`,
+            );
+        case 'notFound':
+            throw new Error(
+                `No matching queue_computation instruction found in tx ${signature} `
+                    + `for computation ${match.computationOffset.toString()}.`,
+            );
+    }
+}
+
+/**
+ * Fetch a live computation's on-chain fee by its offset.
+ *
+ * Returns the {@link ComputationFee} `account` variant while the computation
+ * account is alive, or `null` once it has been closed (`claim_computation_rent`,
+ * `reclaim_expired_computation_fee`, or a failure-claim flow). There is no
+ * automatic fallback for closed accounts: the on-chain data is gone, so a caller
+ * that stored the queue tx signature must pass it to
+ * {@link getComputationFeeFromQueueTx} to reconstruct the fee inputs.
+ *
+ * Throws if the live account at `(cluster, offset)` belongs to a different MXE:
+ * the computation PDA is keyed on `(cluster, comp_offset)` only, so two MXEs on
+ * a shared cluster can collide on it across lifecycles, and silently returning
+ * the wrong MXE's fee would be a correctness bug.
+ *
+ * @param arciumProgram - Anchor program instance (Arcium IDL).
+ * @param mxeProgramId - MXE program the computation belongs to; derives the
+ *                       cluster and computation PDA.
+ * @param computationOffset - Computation offset.
+ * @param commitment - RPC commitment for the account reads.
+ * @returns The live account fee, or `null` if the account is closed.
+ *
+ * @example
+ * import { getArciumProgram, getComputationFee, getComputationFeeFromQueueTx } from '@arcium-hq/reader';
+ *
+ * const program = getArciumProgram(provider);
+ * const fee = await getComputationFee(program, mxeProgramId, computationOffset);
+ * if (fee) {
+ *   console.log('Live fee:', fee.baseFee.add(fee.priorityFee).toString());
+ * }
+ * else {
+ *   // Closed: reconstruct from the stored queue tx signature.
+ *   const queued = await getComputationFeeFromQueueTx(program, queueTxSignature, mxeProgramId, computationOffset);
+ *   console.log('cuPriceMicro:', queued.cuPriceMicro.toString());
+ * }
+ */
+export async function getComputationFee(
+    arciumProgram: anchor.Program<ArciumIdlType>,
+    mxeProgramId: PublicKey,
+    computationOffset: anchor.BN,
+    commitment?: anchor.web3.Commitment,
+): Promise<Extract<ComputationFee, { source: 'account' }> | null> {
+    const mxe = await arciumProgram.account.mxeAccount.fetch(
+        getMXEAccAddress(mxeProgramId),
+        commitment,
+    );
+    const compPDA = getComputationAccAddress(mxe.cluster, computationOffset);
+
+    const acc = await arciumProgram.account.computationAccount.fetchNullable(compPDA, commitment);
+    if (!acc) {
+        return null;
+    }
+
+    if (!acc.mxeProgramId.equals(mxeProgramId)) {
+        throw new Error(
+            `Computation at offset ${computationOffset.toString()} (cluster ${mxe.cluster}) is owned by `
+                + `MXE ${acc.mxeProgramId.toBase58()}, not the requested ${mxeProgramId.toBase58()}.`,
+        );
+    }
+
+    return {
+        source: 'account',
+        baseFee: acc.executionFee.baseFee,
+        priorityFee: acc.executionFee.priorityFee,
+        callbackCuLimit: acc.executionFee.callbackCuLimit,
+    };
+}
+
+/**
+ * Decode a closed computation's raw fee inputs from its `queue_computation`
+ * transaction.
+ *
+ * Fetches the exact `queueTxSignature` (no signature scanning), rejects a failed
+ * or unavailable tx, and decodes the `queue_computation` ix matching
+ * `mxeProgramId` + `computationOffset`. Reads no current MXE/cluster state, so it
+ * stays correct across cluster migration.
+ *
+ * Pass `opts.cluster` to additionally bind the match to the comp PDA derived
+ * from that historical cluster (rejects a same-tx queue for a different
+ * cluster's PDA). Omit it for the common case of a single queue per tx.
+ *
+ * Returns raw queue-time ix inputs, not lamport fees. Exact reconstruction also
+ * needs queue-time state absent from the ix: cluster `cu_price`, comp-def
+ * `cuAmount`, and the callback context: when `callbackCuLimit` is 0 the callback
+ * priority term defaults from `customCallbackInstructionCount`.
+ *
+ * @param arciumProgram - Anchor program instance (Arcium IDL).
+ * @param queueTxSignature - Signature of the tx that queued the computation.
+ * @param mxeProgramId - MXE program the computation belongs to.
+ * @param computationOffset - Computation offset.
+ * @param opts - `cluster` binds the match to a historical cluster's comp PDA;
+ *               `commitment` maps to `confirmed`/`finalized` for the tx fetch.
+ * @returns The `queueTx` fee variant.
+ * @throws `Error` if the tx is unavailable, failed, or carries no matching
+ *         `queue_computation` instruction.
+ */
+export async function getComputationFeeFromQueueTx(
+    arciumProgram: anchor.Program<ArciumIdlType>,
+    queueTxSignature: string,
+    mxeProgramId: PublicKey,
+    computationOffset: anchor.BN,
+    opts: { cluster?: number; commitment?: anchor.web3.Commitment } = {},
+): Promise<Extract<ComputationFee, { source: 'queueTx' }>> {
+    const rpcFinality = mapCommitmentToFinality(opts.commitment);
+
+    let tx: anchor.web3.VersionedTransactionResponse | null;
+    try {
+        tx = await arciumProgram.provider.connection.getTransaction(queueTxSignature, {
+            maxSupportedTransactionVersion: 0,
+            commitment: rpcFinality,
+        });
+    }
+    catch (error) {
+        throw new Error(`Failed to fetch queue tx ${queueTxSignature}: ${formatUnknownError(error)}`);
+    }
+
+    if (!tx) {
+        throw new Error(`Queue transaction ${queueTxSignature} is unavailable from RPC. Use an archive RPC.`);
+    }
+
+    if (tx.meta?.err != null) {
+        throw new Error(`Queue transaction ${queueTxSignature} failed and did not pay the queue fee.`);
+    }
+
+    return decodeQueueFeeFromTx(tx, queueTxSignature, {
+        mxeProgramId,
+        computationOffset,
+        compPDA: opts.cluster === undefined
+            ? undefined
+            : getComputationAccAddress(opts.cluster, computationOffset),
+    });
+}

package/src/index.ts

@@ -19,6 +19,14 @@ export {
     getFeePoolAccAddress,
     getExecutingPoolAccAddress,
     getCompDefAccAddress,
+    getRecoveryClusterAccAddress,
+    getMxeRecoveryAccAddress,
+    getRecoveryPeerAccAddress,
+    getOperatorAccAddress,
+    getFailureClaimAccAddress,
+    getArciumSignerAccAddress,
+    getRawCircuitAccAddress,
+    getLookupTableAddress,
     getComputationsInMempool,
     getMempoolPriorityFeeStats,
 } from '@arcium-hq/client';

package/src/types.ts

@@ -5,6 +5,8 @@
 import { ArciumIdlType } from '@arcium-hq/client';
 import * as anchor from '@anchor-lang/core';
 
+export type { MempoolPriorityFeeStats } from '@arcium-hq/client';
+
 /**
  * Solana PublicKey type alias for convenience.
  */
@@ -115,3 +117,35 @@ export type ArciumInstructionName = ArciumIdlType['instructions'][number]['name'
  * Status values for a computation, as defined by the Arcium protocol.
  */
 export type ComputationStatus = 'queued' | 'executing' | 'executed' | 'finalized' | 'failed';
+
+/**
+ * Fee information for a computation, tagged by the source it was read from.
+ *
+ * - `account`: read from the live on-chain `ComputationAccount.executionFee`.
+ * - `queueTx`: the raw queue-time ix inputs decoded from the original
+ *   `queueComputation` instruction, for callers reconstructing a closed
+ *   computation's fee from its queue transaction.
+ *
+ * The `queueTx` variant surfaces raw inputs, not lamport fees. Exact
+ * reconstruction needs queue-time state absent from the ix: `baseFee` from
+ * `cluster.cu_price` x comp-def `cuAmount`, and `priorityFee` from
+ * `cuPriceMicro` x `cuAmount` plus a callback term. When `callbackCuLimit` is 0
+ * (no explicit budget) that callback term defaults from
+ * `customCallbackInstructionCount`, so the count is surfaced for that case.
+ */
+export type ComputationFee =
+    | {
+        source: 'account';
+        baseFee: anchor.BN;
+        priorityFee: anchor.BN;
+        callbackCuLimit: number;
+    }
+    | {
+        source: 'queueTx';
+        cuPriceMicro: anchor.BN;
+        callbackCuLimit: number;
+        customCallbackInstructionCount: number;
+        computationDefinitionOffset: number;
+        callbackTransactionsRequired: number;
+        queueTxSignature: string;
+    };