@umbra-privacy/sdk 2.1.0 → 3.0.0

package/dist/{client-Cb53GYes.d.cts → client-Baxe29tj.d.cts}

@@ -965,6 +965,23 @@ interface ComputationPrunedResult {
     /** The current slot at the time pruning was detected. */
     readonly currentSlot: bigint;
 }
+/**
+ * Result when the computation monitoring timed out.
+ *
+ * This occurs when the wall-clock safety timeout fires (RPC unresponsive)
+ * or the monitoring was cancelled via an external `AbortSignal`. Unlike
+ * `"pruned"`, this does not necessarily mean the computation failed — it may
+ * still finalize later. However, the monitor has stopped watching.
+ *
+ * @since 3.0.0
+ * @public
+ */
+interface ComputationTimedOutResult {
+    /** The monitor gave up before observing finalization or pruning. */
+    readonly status: "timed-out";
+    /** Wall-clock milliseconds from monitor start to timeout. */
+    readonly elapsedMs: number;
+}
 /**
  * Discriminated union of all computation monitoring outcomes.
  *
@@ -972,19 +989,25 @@ interface ComputationPrunedResult {
  * Callers must check `result.status` to determine the outcome:
  *
  * ```typescript
- * const result = await monitor.awaitComputation(address);
- * if (result.status === "finalized") {
- *   // MPC succeeded — continue with the encrypted result
- * } else {
- *   // Pruned — the computation will never finalize
- *   console.log(`Pruned: ${result.currentSlot - result.queuedSlot} slots elapsed`);
+ * const result = await prepared.awaitComputation();
+ * switch (result.status) {
+ *   case "finalized":
+ *     // MPC succeeded — continue with the encrypted result
+ *     break;
+ *   case "pruned":
+ *     // Pruned — the computation will never finalize
+ *     console.log(`Pruned: ${result.currentSlot - result.queuedSlot} slots elapsed`);
+ *     break;
+ *   case "timed-out":
+ *     // Monitor gave up — computation may still finalize later
+ *     break;
  * }
  * ```
  *
  * @since 2.0.0
  * @public
  */
-type ComputationMonitorResult = ComputationFinalizedResult | ComputationPrunedResult;
+type ComputationMonitorResult = ComputationFinalizedResult | ComputationPrunedResult | ComputationTimedOutResult;
 /**
  * Extended finalized result with a guaranteed callback signature.
  * Returned when `retrieveCallbackSignature` is `true` and the computation finalized.
@@ -999,12 +1022,12 @@ interface ComputationFinalizedResultWithSignature extends Omit<ComputationFinali
 /**
  * Result type when `retrieveCallbackSignature` is `true`.
  * If finalized, the callback signature is guaranteed present.
- * If pruned, no signature is available.
+ * If pruned or timed out, no signature is available.
  *
  * @since 2.0.0
  * @public
  */
-type ComputationMonitorResultWithSignature = ComputationFinalizedResultWithSignature | ComputationPrunedResult;
+type ComputationMonitorResultWithSignature = ComputationFinalizedResultWithSignature | ComputationPrunedResult | ComputationTimedOutResult;
 /**
  * Progress event types fired via the `onProgress` callback.
  *
@@ -1101,33 +1124,70 @@ interface PollingComputationMonitorOptions extends ComputationMonitorOptions {
     readonly pollingIntervalMs?: number;
 }
 /**
- * Monitors an Arcium `ComputationAccount` for finalization or pruning.
+ * A prepared computation monitor with an active subscription.
  *
- * @since 2.0.0
+ * Created by {@link ComputationMonitor.prepareMonitor}. The subscription is
+ * established during preparation so that no account change notifications are
+ * missed between the queue transaction and the start of monitoring.
+ *
+ * @remarks
+ * Callers **must** call {@link cleanup} when the monitor is no longer needed,
+ * even if {@link awaitComputation} was never called (e.g. if the queue
+ * transaction fails). {@link cleanup} is idempotent.
+ *
+ * @since 3.0.0
+ * @public
+ */
+interface PreparedComputationMonitor {
+    /**
+     * Waits for the computation to finalize, prune, or time out.
+     *
+     * The first account-change notification (from the `queue_computation`
+     * transaction itself) is consumed silently — only the MPC callback
+     * notification triggers a finalized result.
+     *
+     * @returns A promise resolving to a finalized, pruned, or timed-out result.
+     *
+     * @throws {ComputationMonitorError} With stage `"subscription"` if the
+     *   underlying transport (WebSocket) encounters an unrecoverable failure.
+     * @throws {ComputationMonitorError} With stage `"signature-retrieval"` if
+     *   callback signature lookup fails after finalization.
+     */
+    awaitComputation(): Promise<ComputationMonitorResult | ComputationMonitorResultWithSignature>;
+    /**
+     * Tears down the underlying subscription and timers.
+     *
+     * Safe to call multiple times. Called automatically at the end of
+     * {@link awaitComputation}, but should also be called if
+     * `awaitComputation` is never invoked (e.g. when the queue transaction
+     * fails before monitoring begins).
+     */
+    cleanup(): void;
+}
+/**
+ * Factory for preparing computation monitors.
+ *
+ * The two-phase design (prepare → await) ensures the subscription is active
+ * **before** the `queue_computation` transaction is sent, eliminating the race
+ * condition where a fast MPC callback could land between transaction confirmation
+ * and subscription establishment.
+ *
+ * @since 3.0.0
  * @public
  */
 interface ComputationMonitor {
     /**
-     * Monitors a ComputationAccount until it finalizes or is pruned.
+     * Establishes a subscription for the given computation account and returns
+     * a {@link PreparedComputationMonitor} ready to await finalization.
      *
      * @param computationAddress - The on-chain address of the ComputationAccount PDA.
-     * @param options - Monitor options.
-     * @returns A promise resolving to a finalized or pruned result.
-     *
-     * @throws {ComputationMonitorError} With stage `"timeout"` if the safety wall-clock
-     *   timeout fires (indicates RPC issues, not normal pruning).
-     * @throws {ComputationMonitorError} With stage `"subscription"` if WebSocket fails.
-     * @throws {ComputationMonitorError} With stage `"signature-retrieval"` if callback
-     *   signature lookup fails after finalization.
+     * @param options - Monitor options (slot window, timeout, progress, etc.).
+     * @returns A prepared monitor whose subscription is already active.
+     *
+     * @throws {ComputationMonitorError} With stage `"subscription"` if the
+     *   initial subscription setup fails.
      */
-    awaitComputation: {
-        (computationAddress: Address, options?: ComputationMonitorOptions & {
-            retrieveCallbackSignature?: false;
-        }): Promise<ComputationMonitorResult>;
-        (computationAddress: Address, options: ComputationMonitorOptions & {
-            retrieveCallbackSignature: true;
-        }): Promise<ComputationMonitorResultWithSignature>;
-    };
+    prepareMonitor(computationAddress: Address, options?: ComputationMonitorOptions): Promise<PreparedComputationMonitor>;
 }
 /**
  * Configuration for the WebSocket-based computation monitor.
@@ -1178,22 +1238,22 @@ interface PollingBasedComputationMonitorDeps {
  * subscriptions for real-time detection of computation finalization or pruning.
  *
  * @remarks
- * **Detection strategy:** Subscribes to `accountNotifications` for the
- * computation account. On each notification, decodes the account and checks
- * the `status` field. Periodically fetches the current slot to detect pruning
- * when the slot window is exceeded.
+ * **Two-phase design:** {@link ComputationMonitor.prepareMonitor | prepareMonitor}
+ * establishes the WebSocket subscription immediately so it is active before the
+ * `queue_computation` transaction is sent. This eliminates the race condition
+ * where a fast MPC callback could land between transaction confirmation and
+ * subscription establishment.
  *
- * **Initial state check:** Before subscribing, performs an HTTP fetch to handle
- * the case where the computation already finalized before the monitor started.
+ * **Detection strategy:** Subscribes to `accountNotifications` for the
+ * computation account. The first notification (from the `queue_computation`
+ * transaction itself) is consumed silently to capture the queued slot. Subsequent
+ * notifications are checked for `Finalized` status. Periodic slot checks detect
+ * pruning when the slot window is exceeded.
  *
  * @param config - HTTP RPC URL and WebSocket URL.
  * @param deps - Optional dependency overrides for testing.
  * @returns A {@link ComputationMonitor} instance.
  *
- * @throws {ComputationMonitorError} Stage `"timeout"` if safety timeout fires.
- * @throws {ComputationMonitorError} Stage `"subscription"` if WebSocket fails.
- * @throws {ComputationMonitorError} Stage `"signature-retrieval"` if lookup fails.
- *
  * @example
  * ```typescript
  * const monitor = getWebsocketComputationMonitor({
@@ -1201,16 +1261,29 @@ interface PollingBasedComputationMonitorDeps {
  *   rpcSubscriptionsUrl: "wss://api.mainnet-beta.solana.com",
  * });
  *
- * const result = await monitor.awaitComputation(computationAddress);
- * if (result.status === "finalized") {
- *   console.log(`Done in ${result.elapsedMs}ms`);
- * } else {
- *   console.log(`Pruned after ${result.currentSlot - result.queuedSlot} slots`);
+ * // Phase 1: establish subscription
+ * const prepared = await monitor.prepareMonitor(computationAddress);
+ *
+ * // Phase 2: send queue_computation transaction
+ * await forwarder.forwardSequentially([signedTx]);
+ *
+ * // Phase 3: await result (first WS notification from queue tx is ignored)
+ * const result = await prepared.awaitComputation();
+ * switch (result.status) {
+ *   case "finalized":
+ *     console.log(`Done in ${result.elapsedMs}ms`);
+ *     break;
+ *   case "pruned":
+ *     console.log(`Pruned after ${result.currentSlot - result.queuedSlot} slots`);
+ *     break;
+ *   case "timed-out":
+ *     console.log(`Timed out after ${result.elapsedMs}ms`);
+ *     break;
  * }
  * ```
  *
  * @see {@link getPollingComputationMonitor} for the polling alternative
- * @since 2.0.0
+ * @since 3.0.0
  * @public
  */
 declare function getWebsocketComputationMonitor(config: WebsocketBasedComputationMonitorConfig, deps?: WebsocketBasedComputationMonitorDeps): ComputationMonitor;
@@ -1221,7 +1294,8 @@ declare function getWebsocketComputationMonitor(config: WebsocketBasedComputatio
  * @remarks
  * Each poll iteration fetches the `ComputationAccount` and the current slot
  * in parallel. If the account is finalized, the monitor resolves. If the slot
- * window is exceeded, the monitor resolves with a pruned result.
+ * window is exceeded, the monitor resolves with a pruned result. If the
+ * wall-clock safety timeout fires, a `"timed-out"` result is returned.
  *
  * **Transient error handling** — RPC fetch errors during polling are silently
  * swallowed and the poll loop continues.
@@ -1230,7 +1304,6 @@ declare function getWebsocketComputationMonitor(config: WebsocketBasedComputatio
  * @param deps - Optional dependency overrides for testing.
  * @returns A {@link ComputationMonitor} instance.
  *
- * @throws {ComputationMonitorError} Stage `"timeout"` if safety timeout fires.
  * @throws {ComputationMonitorError} Stage `"signature-retrieval"` if lookup fails.
  *
  * @example
@@ -1239,19 +1312,22 @@ declare function getWebsocketComputationMonitor(config: WebsocketBasedComputatio
  *   rpcUrl: "https://api.mainnet-beta.solana.com",
  * });
  *
- * const result = await monitor.awaitComputation(computationAddress, {
+ * const prepared = await monitor.prepareMonitor(computationAddress, {
  *   maxSlotWindow: 250,
  *   pollingIntervalMs: 3_000,
  *   retrieveCallbackSignature: true,
  * });
  *
+ * // ... send queue_computation transaction ...
+ *
+ * const result = await prepared.awaitComputation();
  * if (result.status === "finalized") {
  *   console.log(`Callback: ${result.callbackSignature}`);
  * }
  * ```
  *
  * @see {@link getWebsocketComputationMonitor} for the WebSocket alternative
- * @since 2.0.0
+ * @since 3.0.0
  * @public
  */
 declare function getPollingComputationMonitor(config: PollingBasedComputationMonitorConfig, deps?: PollingBasedComputationMonitorDeps): ComputationMonitor;
@@ -2444,8 +2520,9 @@ interface IUmbraClient {
      *
      * @remarks
      * When provided, enables monitoring of ComputationAccount status changes
-     * (Queued → Finalized) after queue_computation transactions. Callers invoke
-     * `computationMonitor.awaitComputation(address)` to wait for finalization.
+     * (Queued → Finalized) after queue_computation transactions. The monitor
+     * is prepared before the queue transaction is sent, then awaited afterward
+     * via `prepareMonitor(address).awaitComputation()`.
      *
      * If not provided, callers must implement their own monitoring logic or
      * use fire-and-forget behavior (send the queue transaction and don't wait
@@ -2625,4 +2702,4 @@ interface IUmbraClient {
     };
 }
 
-export { type MerkleProofData as $, type AccountInfoProviderFunction as A, type BatchMerkleProofFetcherFunction as B, type CreateSolanaRpcFunction as C, DEFAULT_MAX_SLOT_WINDOW as D, type PollingBasedComputationMonitorDeps as E, type PollingComputationMonitorOptions as F, type GetLatestBlockhash as G, type WebsocketBasedComputationMonitorDeps as H, type IUmbraSigner as I, getPollingComputationMonitor as J, getWebsocketComputationMonitor as K, type GetMasterSeedFunction as L, type MerkleProofFetcherFunction as M, type ClaimableUtxoResult as N, type DecryptedUtxoData as O, type PollingBasedComputationMonitorConfig as P, type EpochInfoResult as Q, type FireAndForget as R, type SendAndConfirmTransactionFactoryFunction as S, type TransactionForwarder as T, type UtxoDataFetcherFunction as U, type ForwardInParallel as V, type WebsocketBasedComputationMonitorConfig as W, type ForwardSequentially as X, type H1Components as Y, type IUmbraIndexer as Z, type LatestBlockhashResult as _, type GetEpochInfo as a, type ScannedUtxoResult as a0, type SignableTransaction as a1, type SignedMessage as a2, type TimestampComponents as a3, type UtxoDataItem as a4, type UtxoFetchResult as a5, type CreateSolanaRpcSubscriptionsFunction as b, type ComputationMonitor as c, type IUmbraClient as d, type GetMerkleProofFetcherArgs as e, type GetMerkleProofFetcherDeps as f, type GetUtxoDataFetcherArgs as g, type GetUtxoDataFetcherDeps as h, type ScannedUtxoData as i, type BatchMerkleProofResult as j, type ClaimableUtxoData as k, type GetClaimableUtxoScannerFunctionArgs as l, type GetClaimableUtxoScannerFunctionDeps as m, type ClaimableUtxoScannerFunction as n, type AesDecryptorFunction as o, type AesEncryptorFunction as p, type ComputationFinalizedResult as q, type ComputationFinalizedResultWithSignature as r, type ComputationMonitorOptions as s, type ComputationMonitorProgressEvent as t, type ComputationMonitorResult as u, type ComputationMonitorResultWithSignature as v, type ComputationPrunedResult as w, DEFAULT_POLLING_INTERVAL_MS as x, DEFAULT_SAFETY_TIMEOUT_MS as y, DEFAULT_SIGNATURE_RETRIEVAL_LIMIT as z };
+export { type MerkleProofData as $, type AccountInfoProviderFunction as A, type BatchMerkleProofResult as B, type CreateSolanaRpcFunction as C, DEFAULT_MAX_SLOT_WINDOW as D, getPollingComputationMonitor as E, getWebsocketComputationMonitor as F, type GetLatestBlockhash as G, type GetMasterSeedFunction as H, type IUmbraSigner as I, type BatchMerkleProofFetcherFunction as J, type ClaimableUtxoResult as K, type DecryptedUtxoData as L, type EpochInfoResult as M, type FireAndForget as N, type ForwardInParallel as O, type PollingBasedComputationMonitorConfig as P, type ForwardSequentially as Q, type GetMerkleProofFetcherArgs as R, type SendAndConfirmTransactionFactoryFunction as S, type TransactionForwarder as T, type GetMerkleProofFetcherDeps as U, type GetUtxoDataFetcherArgs as V, type WebsocketBasedComputationMonitorConfig as W, type GetUtxoDataFetcherDeps as X, type H1Components as Y, type IUmbraIndexer as Z, type LatestBlockhashResult as _, type GetEpochInfo as a, type MerkleProofFetcherFunction as a0, type ScannedUtxoResult as a1, type SignableTransaction as a2, type SignedMessage as a3, type TimestampComponents as a4, type UtxoDataFetcherFunction as a5, type UtxoDataItem as a6, type UtxoFetchResult as a7, type CreateSolanaRpcSubscriptionsFunction as b, type ComputationMonitor as c, type IUmbraClient as d, type ScannedUtxoData as e, type ClaimableUtxoData as f, type GetClaimableUtxoScannerFunctionArgs as g, type GetClaimableUtxoScannerFunctionDeps as h, type ClaimableUtxoScannerFunction as i, type AesDecryptorFunction as j, type AesEncryptorFunction as k, type ComputationFinalizedResult as l, type ComputationFinalizedResultWithSignature as m, type ComputationMonitorOptions as n, type ComputationMonitorProgressEvent as o, type ComputationMonitorResult as p, type ComputationMonitorResultWithSignature as q, type ComputationPrunedResult as r, type ComputationTimedOutResult as s, DEFAULT_POLLING_INTERVAL_MS as t, DEFAULT_SAFETY_TIMEOUT_MS as u, DEFAULT_SIGNATURE_RETRIEVAL_LIMIT as v, type PollingBasedComputationMonitorDeps as w, type PollingComputationMonitorOptions as x, type PreparedComputationMonitor as y, type WebsocketBasedComputationMonitorDeps as z };

package/dist/{client-CJ5S6Qln.d.ts → client-Cqv_5hHQ.d.ts}

@@ -965,6 +965,23 @@ interface ComputationPrunedResult {
     /** The current slot at the time pruning was detected. */
     readonly currentSlot: bigint;
 }
+/**
+ * Result when the computation monitoring timed out.
+ *
+ * This occurs when the wall-clock safety timeout fires (RPC unresponsive)
+ * or the monitoring was cancelled via an external `AbortSignal`. Unlike
+ * `"pruned"`, this does not necessarily mean the computation failed — it may
+ * still finalize later. However, the monitor has stopped watching.
+ *
+ * @since 3.0.0
+ * @public
+ */
+interface ComputationTimedOutResult {
+    /** The monitor gave up before observing finalization or pruning. */
+    readonly status: "timed-out";
+    /** Wall-clock milliseconds from monitor start to timeout. */
+    readonly elapsedMs: number;
+}
 /**
  * Discriminated union of all computation monitoring outcomes.
  *
@@ -972,19 +989,25 @@ interface ComputationPrunedResult {
  * Callers must check `result.status` to determine the outcome:
  *
  * ```typescript
- * const result = await monitor.awaitComputation(address);
- * if (result.status === "finalized") {
- *   // MPC succeeded — continue with the encrypted result
- * } else {
- *   // Pruned — the computation will never finalize
- *   console.log(`Pruned: ${result.currentSlot - result.queuedSlot} slots elapsed`);
+ * const result = await prepared.awaitComputation();
+ * switch (result.status) {
+ *   case "finalized":
+ *     // MPC succeeded — continue with the encrypted result
+ *     break;
+ *   case "pruned":
+ *     // Pruned — the computation will never finalize
+ *     console.log(`Pruned: ${result.currentSlot - result.queuedSlot} slots elapsed`);
+ *     break;
+ *   case "timed-out":
+ *     // Monitor gave up — computation may still finalize later
+ *     break;
  * }
  * ```
  *
  * @since 2.0.0
  * @public
  */
-type ComputationMonitorResult = ComputationFinalizedResult | ComputationPrunedResult;
+type ComputationMonitorResult = ComputationFinalizedResult | ComputationPrunedResult | ComputationTimedOutResult;
 /**
  * Extended finalized result with a guaranteed callback signature.
  * Returned when `retrieveCallbackSignature` is `true` and the computation finalized.
@@ -999,12 +1022,12 @@ interface ComputationFinalizedResultWithSignature extends Omit<ComputationFinali
 /**
  * Result type when `retrieveCallbackSignature` is `true`.
  * If finalized, the callback signature is guaranteed present.
- * If pruned, no signature is available.
+ * If pruned or timed out, no signature is available.
  *
  * @since 2.0.0
  * @public
  */
-type ComputationMonitorResultWithSignature = ComputationFinalizedResultWithSignature | ComputationPrunedResult;
+type ComputationMonitorResultWithSignature = ComputationFinalizedResultWithSignature | ComputationPrunedResult | ComputationTimedOutResult;
 /**
  * Progress event types fired via the `onProgress` callback.
  *
@@ -1101,33 +1124,70 @@ interface PollingComputationMonitorOptions extends ComputationMonitorOptions {
     readonly pollingIntervalMs?: number;
 }
 /**
- * Monitors an Arcium `ComputationAccount` for finalization or pruning.
+ * A prepared computation monitor with an active subscription.
  *
- * @since 2.0.0
+ * Created by {@link ComputationMonitor.prepareMonitor}. The subscription is
+ * established during preparation so that no account change notifications are
+ * missed between the queue transaction and the start of monitoring.
+ *
+ * @remarks
+ * Callers **must** call {@link cleanup} when the monitor is no longer needed,
+ * even if {@link awaitComputation} was never called (e.g. if the queue
+ * transaction fails). {@link cleanup} is idempotent.
+ *
+ * @since 3.0.0
+ * @public
+ */
+interface PreparedComputationMonitor {
+    /**
+     * Waits for the computation to finalize, prune, or time out.
+     *
+     * The first account-change notification (from the `queue_computation`
+     * transaction itself) is consumed silently — only the MPC callback
+     * notification triggers a finalized result.
+     *
+     * @returns A promise resolving to a finalized, pruned, or timed-out result.
+     *
+     * @throws {ComputationMonitorError} With stage `"subscription"` if the
+     *   underlying transport (WebSocket) encounters an unrecoverable failure.
+     * @throws {ComputationMonitorError} With stage `"signature-retrieval"` if
+     *   callback signature lookup fails after finalization.
+     */
+    awaitComputation(): Promise<ComputationMonitorResult | ComputationMonitorResultWithSignature>;
+    /**
+     * Tears down the underlying subscription and timers.
+     *
+     * Safe to call multiple times. Called automatically at the end of
+     * {@link awaitComputation}, but should also be called if
+     * `awaitComputation` is never invoked (e.g. when the queue transaction
+     * fails before monitoring begins).
+     */
+    cleanup(): void;
+}
+/**
+ * Factory for preparing computation monitors.
+ *
+ * The two-phase design (prepare → await) ensures the subscription is active
+ * **before** the `queue_computation` transaction is sent, eliminating the race
+ * condition where a fast MPC callback could land between transaction confirmation
+ * and subscription establishment.
+ *
+ * @since 3.0.0
  * @public
  */
 interface ComputationMonitor {
     /**
-     * Monitors a ComputationAccount until it finalizes or is pruned.
+     * Establishes a subscription for the given computation account and returns
+     * a {@link PreparedComputationMonitor} ready to await finalization.
      *
      * @param computationAddress - The on-chain address of the ComputationAccount PDA.
-     * @param options - Monitor options.
-     * @returns A promise resolving to a finalized or pruned result.
-     *
-     * @throws {ComputationMonitorError} With stage `"timeout"` if the safety wall-clock
-     *   timeout fires (indicates RPC issues, not normal pruning).
-     * @throws {ComputationMonitorError} With stage `"subscription"` if WebSocket fails.
-     * @throws {ComputationMonitorError} With stage `"signature-retrieval"` if callback
-     *   signature lookup fails after finalization.
+     * @param options - Monitor options (slot window, timeout, progress, etc.).
+     * @returns A prepared monitor whose subscription is already active.
+     *
+     * @throws {ComputationMonitorError} With stage `"subscription"` if the
+     *   initial subscription setup fails.
      */
-    awaitComputation: {
-        (computationAddress: Address, options?: ComputationMonitorOptions & {
-            retrieveCallbackSignature?: false;
-        }): Promise<ComputationMonitorResult>;
-        (computationAddress: Address, options: ComputationMonitorOptions & {
-            retrieveCallbackSignature: true;
-        }): Promise<ComputationMonitorResultWithSignature>;
-    };
+    prepareMonitor(computationAddress: Address, options?: ComputationMonitorOptions): Promise<PreparedComputationMonitor>;
 }
 /**
  * Configuration for the WebSocket-based computation monitor.
@@ -1178,22 +1238,22 @@ interface PollingBasedComputationMonitorDeps {
  * subscriptions for real-time detection of computation finalization or pruning.
  *
  * @remarks
- * **Detection strategy:** Subscribes to `accountNotifications` for the
- * computation account. On each notification, decodes the account and checks
- * the `status` field. Periodically fetches the current slot to detect pruning
- * when the slot window is exceeded.
+ * **Two-phase design:** {@link ComputationMonitor.prepareMonitor | prepareMonitor}
+ * establishes the WebSocket subscription immediately so it is active before the
+ * `queue_computation` transaction is sent. This eliminates the race condition
+ * where a fast MPC callback could land between transaction confirmation and
+ * subscription establishment.
  *
- * **Initial state check:** Before subscribing, performs an HTTP fetch to handle
- * the case where the computation already finalized before the monitor started.
+ * **Detection strategy:** Subscribes to `accountNotifications` for the
+ * computation account. The first notification (from the `queue_computation`
+ * transaction itself) is consumed silently to capture the queued slot. Subsequent
+ * notifications are checked for `Finalized` status. Periodic slot checks detect
+ * pruning when the slot window is exceeded.
  *
  * @param config - HTTP RPC URL and WebSocket URL.
  * @param deps - Optional dependency overrides for testing.
  * @returns A {@link ComputationMonitor} instance.
  *
- * @throws {ComputationMonitorError} Stage `"timeout"` if safety timeout fires.
- * @throws {ComputationMonitorError} Stage `"subscription"` if WebSocket fails.
- * @throws {ComputationMonitorError} Stage `"signature-retrieval"` if lookup fails.
- *
  * @example
  * ```typescript
  * const monitor = getWebsocketComputationMonitor({
@@ -1201,16 +1261,29 @@ interface PollingBasedComputationMonitorDeps {
  *   rpcSubscriptionsUrl: "wss://api.mainnet-beta.solana.com",
  * });
  *
- * const result = await monitor.awaitComputation(computationAddress);
- * if (result.status === "finalized") {
- *   console.log(`Done in ${result.elapsedMs}ms`);
- * } else {
- *   console.log(`Pruned after ${result.currentSlot - result.queuedSlot} slots`);
+ * // Phase 1: establish subscription
+ * const prepared = await monitor.prepareMonitor(computationAddress);
+ *
+ * // Phase 2: send queue_computation transaction
+ * await forwarder.forwardSequentially([signedTx]);
+ *
+ * // Phase 3: await result (first WS notification from queue tx is ignored)
+ * const result = await prepared.awaitComputation();
+ * switch (result.status) {
+ *   case "finalized":
+ *     console.log(`Done in ${result.elapsedMs}ms`);
+ *     break;
+ *   case "pruned":
+ *     console.log(`Pruned after ${result.currentSlot - result.queuedSlot} slots`);
+ *     break;
+ *   case "timed-out":
+ *     console.log(`Timed out after ${result.elapsedMs}ms`);
+ *     break;
  * }
  * ```
  *
  * @see {@link getPollingComputationMonitor} for the polling alternative
- * @since 2.0.0
+ * @since 3.0.0
  * @public
  */
 declare function getWebsocketComputationMonitor(config: WebsocketBasedComputationMonitorConfig, deps?: WebsocketBasedComputationMonitorDeps): ComputationMonitor;
@@ -1221,7 +1294,8 @@ declare function getWebsocketComputationMonitor(config: WebsocketBasedComputatio
  * @remarks
  * Each poll iteration fetches the `ComputationAccount` and the current slot
  * in parallel. If the account is finalized, the monitor resolves. If the slot
- * window is exceeded, the monitor resolves with a pruned result.
+ * window is exceeded, the monitor resolves with a pruned result. If the
+ * wall-clock safety timeout fires, a `"timed-out"` result is returned.
  *
  * **Transient error handling** — RPC fetch errors during polling are silently
  * swallowed and the poll loop continues.
@@ -1230,7 +1304,6 @@ declare function getWebsocketComputationMonitor(config: WebsocketBasedComputatio
  * @param deps - Optional dependency overrides for testing.
  * @returns A {@link ComputationMonitor} instance.
  *
- * @throws {ComputationMonitorError} Stage `"timeout"` if safety timeout fires.
  * @throws {ComputationMonitorError} Stage `"signature-retrieval"` if lookup fails.
  *
  * @example
@@ -1239,19 +1312,22 @@ declare function getWebsocketComputationMonitor(config: WebsocketBasedComputatio
  *   rpcUrl: "https://api.mainnet-beta.solana.com",
  * });
  *
- * const result = await monitor.awaitComputation(computationAddress, {
+ * const prepared = await monitor.prepareMonitor(computationAddress, {
  *   maxSlotWindow: 250,
  *   pollingIntervalMs: 3_000,
  *   retrieveCallbackSignature: true,
  * });
  *
+ * // ... send queue_computation transaction ...
+ *
+ * const result = await prepared.awaitComputation();
  * if (result.status === "finalized") {
  *   console.log(`Callback: ${result.callbackSignature}`);
  * }
  * ```
  *
  * @see {@link getWebsocketComputationMonitor} for the WebSocket alternative
- * @since 2.0.0
+ * @since 3.0.0
  * @public
  */
 declare function getPollingComputationMonitor(config: PollingBasedComputationMonitorConfig, deps?: PollingBasedComputationMonitorDeps): ComputationMonitor;
@@ -2444,8 +2520,9 @@ interface IUmbraClient {
      *
      * @remarks
      * When provided, enables monitoring of ComputationAccount status changes
-     * (Queued → Finalized) after queue_computation transactions. Callers invoke
-     * `computationMonitor.awaitComputation(address)` to wait for finalization.
+     * (Queued → Finalized) after queue_computation transactions. The monitor
+     * is prepared before the queue transaction is sent, then awaited afterward
+     * via `prepareMonitor(address).awaitComputation()`.
      *
      * If not provided, callers must implement their own monitoring logic or
      * use fire-and-forget behavior (send the queue transaction and don't wait
@@ -2625,4 +2702,4 @@ interface IUmbraClient {
     };
 }
 
-export { type MerkleProofData as $, type AccountInfoProviderFunction as A, type BatchMerkleProofFetcherFunction as B, type CreateSolanaRpcFunction as C, DEFAULT_MAX_SLOT_WINDOW as D, type PollingBasedComputationMonitorDeps as E, type PollingComputationMonitorOptions as F, type GetLatestBlockhash as G, type WebsocketBasedComputationMonitorDeps as H, type IUmbraSigner as I, getPollingComputationMonitor as J, getWebsocketComputationMonitor as K, type GetMasterSeedFunction as L, type MerkleProofFetcherFunction as M, type ClaimableUtxoResult as N, type DecryptedUtxoData as O, type PollingBasedComputationMonitorConfig as P, type EpochInfoResult as Q, type FireAndForget as R, type SendAndConfirmTransactionFactoryFunction as S, type TransactionForwarder as T, type UtxoDataFetcherFunction as U, type ForwardInParallel as V, type WebsocketBasedComputationMonitorConfig as W, type ForwardSequentially as X, type H1Components as Y, type IUmbraIndexer as Z, type LatestBlockhashResult as _, type GetEpochInfo as a, type ScannedUtxoResult as a0, type SignableTransaction as a1, type SignedMessage as a2, type TimestampComponents as a3, type UtxoDataItem as a4, type UtxoFetchResult as a5, type CreateSolanaRpcSubscriptionsFunction as b, type ComputationMonitor as c, type IUmbraClient as d, type GetMerkleProofFetcherArgs as e, type GetMerkleProofFetcherDeps as f, type GetUtxoDataFetcherArgs as g, type GetUtxoDataFetcherDeps as h, type ScannedUtxoData as i, type BatchMerkleProofResult as j, type ClaimableUtxoData as k, type GetClaimableUtxoScannerFunctionArgs as l, type GetClaimableUtxoScannerFunctionDeps as m, type ClaimableUtxoScannerFunction as n, type AesDecryptorFunction as o, type AesEncryptorFunction as p, type ComputationFinalizedResult as q, type ComputationFinalizedResultWithSignature as r, type ComputationMonitorOptions as s, type ComputationMonitorProgressEvent as t, type ComputationMonitorResult as u, type ComputationMonitorResultWithSignature as v, type ComputationPrunedResult as w, DEFAULT_POLLING_INTERVAL_MS as x, DEFAULT_SAFETY_TIMEOUT_MS as y, DEFAULT_SIGNATURE_RETRIEVAL_LIMIT as z };
+export { type MerkleProofData as $, type AccountInfoProviderFunction as A, type BatchMerkleProofResult as B, type CreateSolanaRpcFunction as C, DEFAULT_MAX_SLOT_WINDOW as D, getPollingComputationMonitor as E, getWebsocketComputationMonitor as F, type GetLatestBlockhash as G, type GetMasterSeedFunction as H, type IUmbraSigner as I, type BatchMerkleProofFetcherFunction as J, type ClaimableUtxoResult as K, type DecryptedUtxoData as L, type EpochInfoResult as M, type FireAndForget as N, type ForwardInParallel as O, type PollingBasedComputationMonitorConfig as P, type ForwardSequentially as Q, type GetMerkleProofFetcherArgs as R, type SendAndConfirmTransactionFactoryFunction as S, type TransactionForwarder as T, type GetMerkleProofFetcherDeps as U, type GetUtxoDataFetcherArgs as V, type WebsocketBasedComputationMonitorConfig as W, type GetUtxoDataFetcherDeps as X, type H1Components as Y, type IUmbraIndexer as Z, type LatestBlockhashResult as _, type GetEpochInfo as a, type MerkleProofFetcherFunction as a0, type ScannedUtxoResult as a1, type SignableTransaction as a2, type SignedMessage as a3, type TimestampComponents as a4, type UtxoDataFetcherFunction as a5, type UtxoDataItem as a6, type UtxoFetchResult as a7, type CreateSolanaRpcSubscriptionsFunction as b, type ComputationMonitor as c, type IUmbraClient as d, type ScannedUtxoData as e, type ClaimableUtxoData as f, type GetClaimableUtxoScannerFunctionArgs as g, type GetClaimableUtxoScannerFunctionDeps as h, type ClaimableUtxoScannerFunction as i, type AesDecryptorFunction as j, type AesEncryptorFunction as k, type ComputationFinalizedResult as l, type ComputationFinalizedResultWithSignature as m, type ComputationMonitorOptions as n, type ComputationMonitorProgressEvent as o, type ComputationMonitorResult as p, type ComputationMonitorResultWithSignature as q, type ComputationPrunedResult as r, type ComputationTimedOutResult as s, DEFAULT_POLLING_INTERVAL_MS as t, DEFAULT_SAFETY_TIMEOUT_MS as u, DEFAULT_SIGNATURE_RETRIEVAL_LIMIT as v, type PollingBasedComputationMonitorDeps as w, type PollingComputationMonitorOptions as x, type PreparedComputationMonitor as y, type WebsocketBasedComputationMonitorDeps as z };

package/dist/constants/index.cjs

@@ -2,7 +2,7 @@
 
 var chunk43JEHY7D_cjs = require('../chunk-43JEHY7D.cjs');
 var chunkTQQZGNOI_cjs = require('../chunk-TQQZGNOI.cjs');
-require('../chunk-BL6WXLPV.cjs');
+require('../chunk-KCHHJKQN.cjs');
 require('../chunk-FSK2ICMB.cjs');
 require('../chunk-QJAUUYZU.cjs');
 var chunkPK6SKIKE_cjs = require('../chunk-PK6SKIKE.cjs');

package/dist/constants/index.js

@@ -1,6 +1,6 @@
 export { ASSOCIATED_TOKEN_PROGRAM_ID, DEFAULT_ALGORITHM_VERSION, DEFAULT_NETWORK, DEFAULT_PROTOCOL_VERSION, DEFAULT_SCHEME_VERSION, SPL_TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID, assertNetwork, assertValidAlgorithmVersion, assertValidProtocolVersion, assertValidSchemeVersion, assertValidVersion, getDefaultAlgorithmVersion, getDefaultProtocolVersion, getDefaultSchemeVersion, getNetworkConfig, getNetworkSpecifier } from '../chunk-FQDYYTPG.js';
 export { ARCIUM_CLUSTER_SEED, ARCIUM_COMPUTATION_SEED, ARCIUM_COMP_DEF_SEED, ARCIUM_EXEC_POOL_SEED, ARCIUM_MEMPOOL_SEED, ARCIUM_MXE_ACCOUNT_SEED, ARCIUM_OFFSET_BUFFER_SIZE } from '../chunk-EEKF4553.js';
-import '../chunk-GP26R377.js';
+import '../chunk-AUNYA6JP.js';
 import '../chunk-5KPQXPQM.js';
 import '../chunk-4TZVXB5G.js';
 import { __name } from '../chunk-7QVYU63E.js';