Add optional block ID parameter to getTransactionStatus

.changeset/bright-oranges-pick.md

@@ -0,0 +1,6 @@
+---
+"@onflow/transport-http": minor
+"@onflow/sdk": minor
+---
+
+Add optional `blockId` field to `GetTransactionResult`. This is used to disambiguate system transactions sharing IDs between blocks and is not applicable to most developers.

packages/react-sdk/src/components/TransactionDialog.tsx

@@ -9,6 +9,7 @@ import {useFlowTransactionStatus} from "../hooks/useFlowTransactionStatus"
 interface TransactionDialogProps {
   open: boolean
   onOpenChange: (open: boolean) => void
+  /** The transaction ID (256-bit hash as hex string) or scheduled transaction ID (UInt64 as decimal string) to monitor */
   txId?: string
   onSuccess?: () => void
   pendingTitle?: string

packages/react-sdk/src/components/TransactionLink.tsx

@@ -6,6 +6,7 @@ import {FlowNetwork} from "../core/types"
 import {ExternalLinkIcon} from "../icons/ExternalLink"
 
 interface TransactionLinkProps {
+  /** The transaction ID (256-bit hash as hex string) or scheduled transaction ID (UInt64 as decimal string) */
   txId: string
   variant?: ButtonProps["variant"]
 }

packages/react-sdk/src/hooks/useFlowTransaction.ts

@@ -6,7 +6,7 @@ import {useFlowQueryClient} from "../provider/FlowQueryClient"
 import {useFlowClient} from "./useFlowClient"
 
 export interface UseFlowTransactionArgs {
-  /** Flow transaction ID to fetch */
+  /** The transaction ID (256-bit hash as hex string) or scheduled transaction ID (UInt64 as decimal string) to fetch */
   txId?: string
   /** React Query settings (staleTime, retry, enabled, select, etc.) */
   query?: Omit<
@@ -20,7 +20,7 @@ export interface UseFlowTransactionArgs {
 /**
  * Fetches a Flow transaction by ID.
  *
- * @param args.txId - Flow transaction ID
+ * @param args.txId - The transaction ID (256-bit hash as hex string) or scheduled transaction ID (UInt64 as decimal string)
  * @param args.query - Optional React Query options
  * @returns {UseQueryResult<Transaction | null, Error>} Transaction object or null
  */

packages/react-sdk/src/hooks/useFlowTransactionStatus.ts

@@ -4,7 +4,7 @@ import {useFlowClient} from "./useFlowClient"
 import {TransactionError} from "@onflow/fcl"
 
 export interface UseFlowTransactionStatusArgs {
-  /** The Flow transaction ID to monitor */
+  /** The transaction ID (256-bit hash as hex string) or scheduled transaction ID (UInt64 as decimal string) to monitor */
   id?: string | null
   flowClient?: ReturnType<typeof useFlowClient>
 }
@@ -22,7 +22,7 @@ export interface UseFlowTransactionStatusResult {
  * @remarks
  * This hook was previously named `useFlowTransaction`.
  *
- * @param args.id - The Flow transaction ID to watch
+ * @param args.id - The transaction ID (256-bit hash as hex string) or scheduled transaction ID (UInt64 as decimal string) to watch
  * @returns {UseFlowTransactionStatusResult}
  */
 export function useFlowTransactionStatus({

packages/sdk/readme.md

@@ -484,7 +484,10 @@ const txId: string = "9dda49b2f2b1b9bc12d5cabe09f8a8cb49828c9c449574c1f46f3b3a5e
 
 // Build the interaction
 const interaction = await sdk.build([
-  sdk.getTransactionStatus(txId)
+  sdk.getTransactionStatus(txId),
+  // Optionally disambiguate system txns by providing a specific block id
+  // (uses HTTP query param ?block_id=... under the hood)
+  sdk.atBlockId("abc123blockid")
 ])
 
 // Send the interaction to the Access Node

packages/sdk/src/build/build-get-transaction-status.ts

@@ -12,7 +12,7 @@ import {
  *
  * Consider using 'fcl.tx(id)' instead of calling this method directly for real-time transaction monitoring.
  *
- * @param transactionId The id of the transaction to get the status of
+ * @param transactionId The transaction ID (256-bit hash as hex string) or scheduled transaction ID (UInt64 as decimal string)
  * @returns A function that processes an interaction object
  *
  * @example

packages/sdk/src/build/build-get-transaction.ts

@@ -15,7 +15,7 @@ import {
  *
  * Consider using 'fcl.tx(id).onceExecuted()' instead of calling this method directly for real-time transaction monitoring.
  *
- * @param transactionId The id of the transaction to get
+ * @param id The transaction ID (256-bit hash as hex string) or scheduled transaction ID (UInt64 as decimal string)
  * @returns A function that processes an interaction object
  *
  * @example

packages/transport-http/src/send/send-get-transaction-status.js

@@ -28,9 +28,16 @@ export async function sendGetTransactionStatus(ix, context = {}, opts = {}) {
 
   ix = await ix
 
+  const blockId = ix && ix.block && ix.block.id
+  const path = blockId
+    ? `/v1/transaction_results/${ix.transaction.id}?block_id=${encodeURIComponent(
+        blockId
+      )}`
+    : `/v1/transaction_results/${ix.transaction.id}`
+
   const res = await httpRequest({
     hostname: opts.node,
-    path: `/v1/transaction_results/${ix.transaction.id}`,
+    path,
     method: "GET",
     body: null,
   })

packages/transport-http/src/send/send-get-transaction-status.test.js

@@ -77,4 +77,49 @@ describe("Get Transaction Status", () => {
       ],
     })
   })
+
+  test("GetTransactionResult with block_id query when atBlockId is provided", async () => {
+    const httpRequestMock = jest.fn()
+
+    const returnedTransactionStatus = {
+      status: "Sealed",
+      status_code: 0,
+      error_message: "",
+      computation_used: "100",
+      block_id: "blockABC",
+      events: [],
+    }
+
+    httpRequestMock.mockReturnValue(returnedTransactionStatus)
+
+    const response = await sendGetTransactionStatus(
+      await resolve(
+        await build([
+          getTransactionStatus("MyTxID"),
+          // set block id through existing builder
+          ix => ({...ix, block: {...ix.block, id: "blockABC"}}),
+        ])
+      ),
+      {
+        response: responseADT,
+        Buffer,
+      },
+      {
+        httpRequest: httpRequestMock,
+        node: "localhost",
+      }
+    )
+
+    expect(httpRequestMock.mock.calls.length).toEqual(1)
+    const valueSent = httpRequestMock.mock.calls[0][0]
+
+    expect(valueSent).toEqual({
+      hostname: "localhost",
+      path: "/v1/transaction_results/MyTxID?block_id=blockABC",
+      method: "GET",
+      body: null,
+    })
+
+    expect(response.transactionStatus.blockId).toBe("blockABC")
+  })
 })