fix: resolve tx.onceSealed() hanging indefinitely

Fixes three bugs that cause `fcl.tx(txId).onceSealed()` to hang:

1. Actor error swallowing (util-actor): The actor message loop caught ALL
   errors and continued silently. Now distinguishes transient network errors
   (ETIMEDOUT, ECONNRESET, etc.) from fatal errors (TypeError, SyntaxError)
   and propagates fatal errors to subscribers via ctx.fatalError().

2. Late subscriber race condition (legacy-polling): When a subscriber joins
   after a transaction is already sealed, no more POLLs are scheduled so
   they could miss the final state. The SUBSCRIBE handler now triggers an
   additional POLL when the transaction is already in a terminal state.

3. WebSocket subscription timeout (transaction.ts): The WebSocket
   subscription path had no timeout — if the Access Node never pushed data
   (e.g., tx already sealed), the promise hung forever. Added a configurable
   timeout (default 30s) that falls back to legacy polling.

Closes #2792

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: zenabot27

packages/fcl-core/src/transaction/transaction.test.ts

@@ -211,6 +211,88 @@ describe("transaction", () => {
     unsubscribe()
   })
 
+  test("should fall back to legacy polling if WebSocket receives no data within timeout", async () => {
+    jest.useFakeTimers()
+
+    const txId =
+      "5234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
+    const onData = jest.fn()
+    const onError = jest.fn()
+
+    // Use a short wsTimeout
+    transaction(txId, {wsTimeout: 5000}).subscribe(onData, onError)
+
+    // Flush the event loop for init()
+    await jest.advanceTimersByTimeAsync(0)
+
+    // Verify WebSocket subscription was attempted
+    expect(subscribe).toHaveBeenCalled()
+
+    const subscribeParams = jest.mocked(subscribe).mock
+      .calls[0][0] as Parameters<
+      typeof subscribe<SubscriptionTopic.TRANSACTION_STATUSES>
+    >[0]
+
+    expect(subscribeParams).toStrictEqual({
+      topic: SubscriptionTopic.TRANSACTION_STATUSES,
+      args: {transactionId: txId},
+      onData: expect.any(Function),
+      onError: expect.any(Function),
+    })
+
+    // Do NOT send any data via WebSocket — simulate a hung connection
+    // Advance past the timeout
+    await jest.advanceTimersByTimeAsync(5000)
+
+    // Should have fallen back to legacy polling
+    expect(legacyTransaction).toHaveBeenCalledWith(txId, {
+      wsTimeout: 5000,
+    })
+
+    // WebSocket subscription should have been unsubscribed
+    const unsubMock = jest.mocked(subscribe).mock.results[0].value
+    expect(unsubMock.unsubscribe).toHaveBeenCalledTimes(1)
+
+    jest.useRealTimers()
+  })
+
+  test("should NOT fall back to polling if WebSocket receives data before timeout", async () => {
+    jest.useFakeTimers()
+
+    const txId =
+      "6234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
+    const onData = jest.fn()
+    const onError = jest.fn()
+
+    transaction(txId, {wsTimeout: 5000}).subscribe(onData, onError)
+
+    // Flush the event loop for init()
+    await jest.advanceTimersByTimeAsync(0)
+
+    const subscribeParams = jest.mocked(subscribe).mock
+      .calls[0][0] as Parameters<
+      typeof subscribe<SubscriptionTopic.TRANSACTION_STATUSES>
+    >[0]
+
+    // Send data before the timeout
+    subscribeParams.onData({
+      status: TransactionExecutionStatus.PENDING,
+      blockId: "",
+      statusCode: 0,
+      errorMessage: "",
+      events: [],
+      statusString: "PENDING",
+    })
+
+    // Advance past the timeout
+    await jest.advanceTimersByTimeAsync(5000)
+
+    // Should NOT have fallen back to legacy polling
+    expect(legacyTransaction).not.toHaveBeenCalled()
+
+    jest.useRealTimers()
+  })
+
   test("should fall back to legacy polling if the Flow emulator is detected", async () => {
     mockGetChainId.mockResolvedValue("local")
 

packages/fcl-core/src/transaction/transaction.ts

@@ -114,6 +114,7 @@ export function createTransaction(context: Pick<FCLContext, "sdk" | "config">) {
     opts: {
       pollRate?: number
       txNotFoundTimeout?: number
+      wsTimeout?: number
     } = {txNotFoundTimeout: 12500, pollRate: 1000}
   ): {
     snapshot: () => Promise<TransactionStatus>
@@ -216,7 +217,7 @@ export const transaction = /* @__PURE__ */ createTransaction(
 function createObservable(
   context: Pick<FCLContext, "sdk" | "config">,
   txId: string,
-  opts: {pollRate?: number; txNotFoundTimeout?: number}
+  opts: {pollRate?: number; txNotFoundTimeout?: number; wsTimeout?: number}
 ) {
   const observers = new Set<{
     onData: (txStatus: TransactionStatus) => void
@@ -261,11 +262,20 @@ function createObservable(
 
   // Subscribe to transaction status updates
   function subscribeTransactionStatuses() {
+    const WS_TIMEOUT = opts.wsTimeout ?? 30000
+    let receivedData = false
+
     // Subscribe to transaction status updates
     const subscription = context.sdk.subscribe({
       topic: SubscriptionTopic.TRANSACTION_STATUSES,
       args: {transactionId: txId},
       onData: txStatus => {
+        receivedData = true
+        if (wsTimeoutId != null) {
+          clearTimeout(wsTimeoutId)
+          wsTimeoutId = null
+        }
+
         if (isDiff(value, txStatus)) {
           value = txStatus
           next(txStatus)
@@ -282,6 +292,11 @@ function createObservable(
         }
       },
       onError: (err: Error) => {
+        if (wsTimeoutId != null) {
+          clearTimeout(wsTimeoutId)
+          wsTimeoutId = null
+        }
+
         if (err instanceof SubscriptionsNotSupportedError) {
           console.warn(
             "Failed to subscribe to transaction status updates using real-time streaming (are you using the deprecated GRPC transport?), falling back to polling."
@@ -292,6 +307,18 @@ function createObservable(
         }
       },
     })
+
+    // If no data is received within the timeout, fall back to legacy polling
+    // This handles cases where the Access Node never pushes data (e.g., tx already sealed)
+    let wsTimeoutId: ReturnType<typeof setTimeout> | null = setTimeout(() => {
+      if (!receivedData) {
+        console.warn(
+          `No transaction status data received via WebSocket within ${WS_TIMEOUT}ms, falling back to polling.`
+        )
+        subscription.unsubscribe()
+        fallbackLegacyPolling()
+      }
+    }, WS_TIMEOUT)
   }
 
   function fallbackLegacyPolling() {