feat: Add useTransactionStatus and example

Author: maggo

examples/react/pages/index.tsx

@@ -12,6 +12,7 @@ export default function Index() {
         <Example name="use-wallet-discovery" />
         <Example name="use-mutation" />
         <Example name="use-account" />
+        <Example name="use-transaction-status" />
       </ul>
     </>
   );

examples/react/pages/use-transaction-status.tsx

@@ -0,0 +1,116 @@
+import {
+  createClient,
+  FlowProvider,
+  networks,
+  useTransactionStatus,
+} from "@maggo/use-flow";
+import { block, decode, getEventsAtBlockIds, send } from "@onflow/fcl";
+import { useRef, useState } from "react";
+
+const client = createClient({
+  fclConfig: {
+    ...networks.mainnet,
+  },
+});
+
+export default function UseTransactionStatus() {
+  return (
+    <FlowProvider client={client}>
+      <h1>useTransactionStatus Example</h1>
+      <Subscription />
+    </FlowProvider>
+  );
+}
+
+function Subscription() {
+  const formRef = useRef<HTMLFormElement>(null);
+  const [query, setQuery] = useState<string>();
+
+  const { status, isLoading } = useTransactionStatus({
+    id: query,
+  });
+
+  async function getLatestTx() {
+    const blockData = await block();
+
+    const events = await send([
+      getEventsAtBlockIds("A.f919ee77447b7497.FlowFees.FeesDeducted", [
+        blockData.id,
+      ]),
+    ]).then(decode);
+
+    if (!events.length) return;
+
+    const txId = events[events.length - 1].transactionId;
+
+    if (formRef.current) {
+      const el = formRef.current.elements.namedItem(
+        "query"
+      ) as HTMLInputElement;
+
+      el.value = txId;
+    }
+
+    setQuery(txId);
+  }
+
+  const Header = (
+    <>
+      <form
+        ref={formRef}
+        style={{ display: "flex", gap: ".5rem", alignItems: "center" }}
+        onSubmit={(e) => {
+          e.preventDefault();
+          const el = e.currentTarget.elements.namedItem(
+            "query"
+          ) as HTMLInputElement;
+          setQuery(el.value);
+        }}
+      >
+        <input type="search" name="query" defaultValue={query} />
+        <button type="submit">Submit</button>
+        {" | "}
+        <button type="button" onClick={() => getLatestTx()}>
+          Get latest tx
+        </button>
+      </form>
+      <br />
+    </>
+  );
+
+  if (isLoading) {
+    return (
+      <>
+        {Header}
+        <p>Loading…</p>
+      </>
+    );
+  }
+
+  if (!status) {
+    return (
+      <>
+        {Header}
+        <p>No transaction selected…</p>
+      </>
+    );
+  }
+
+  return (
+    <>
+      {Header}
+      <p>
+        Transaction Status:{" "}
+        <code>
+          {status?.status} = {status?.statusString}
+        </code>
+      </p>
+      <details>
+        <summary>Raw Result</summary>
+        <pre style={{ overflowX: "auto" }}>
+          {JSON.stringify(status, null, 2)}
+        </pre>
+      </details>
+    </>
+  );
+}

packages/core/src/index.ts

@@ -8,4 +8,5 @@ export { useBlock } from "./useBlock";
 export { useEventSubscription } from "./useEventSubscription";
 export { useMutation } from "./useMutation";
 export { useScript } from "./useScript";
+export { useTransactionStatus } from "./useTransactionStatus";
 export { useWalletDiscovery } from "./useWalletDiscovery";

packages/core/src/useTransactionStatus.ts

@@ -0,0 +1,91 @@
+import { tx } from "@onflow/fcl";
+import { useEffect, useState } from "react";
+
+export enum TransactionStatus {
+  /** Transaction unknown */
+  Unknown = 0,
+  /**	Transaction Pending - Awaiting Finalization */
+  Pending = 1,
+  /** Transaction Finalized - Awaiting Execution */
+  Finalized = 2,
+  /** Transaction Executed - Awaiting Sealing */
+  Executed = 3,
+  /** Transaction Sealed - Transaction Complete. At this point the transaction result has been committed to the blockchain. */
+  Sealed = 4,
+  /** Transaction Expired */
+  Expired = 5,
+}
+
+interface Event {
+  type: string;
+  transactionId: string;
+  transactionIndex: number;
+  eventIndex: number;
+  data: Record<string, any>;
+}
+
+interface TransactionResult {
+  blockId: string;
+  errorMessage: string;
+  events: Event[];
+  status: TransactionStatus;
+  statusCode: 0 | 1;
+  statusString: "SEALED";
+}
+
+interface UseTransactionStatusProps {
+  /** A valid transaction id. */
+  id?: string;
+  /** Provides the transaction once status `2` is returned. */
+  onceFinalized?: (txStatus: TransactionResult) => void;
+  /** Provides the transaction once status `3` is returned. */
+  onceExecuted?: (txStatus: TransactionResult) => void;
+  /** Provides the transaction once status `4` is returned. */
+  onceSealed?: (txStatus: TransactionResult) => void;
+}
+
+/**
+ * This hook enables you to get status updates (via polling) and the finalized result of a transaction once available.
+ *
+ * The status is polled every 2.5 seconds.
+ *
+ * @TODO Refactor to custom getTransactionStatus calls since FCL tx() has no error handling and isn't cancelable.
+ * @TODO Investigate transaction statuses that are just empty strings
+ * @see {@link https://developers.flow.com/tools/fcl-js/reference/api#tx}
+ */
+export function useTransactionStatus({
+  id,
+  onceFinalized,
+  onceExecuted,
+  onceSealed,
+}: UseTransactionStatusProps) {
+  const [isLoading, setIsLoading] = useState(true);
+  const [status, setStatus] = useState<TransactionResult>();
+
+  useEffect(() => {
+    if (!id) {
+      setIsLoading(false);
+      return;
+    }
+
+    setIsLoading(true);
+
+    const txHandler = tx(id);
+    txHandler.subscribe((txStatus: TransactionResult) => {
+      setIsLoading(false);
+      setStatus(txStatus);
+    });
+
+    txHandler.onceFinalized(onceFinalized);
+    txHandler.onceExecuted(onceExecuted);
+    txHandler.onceSealed(onceSealed);
+  }, [id]);
+
+  return {
+    isLoading,
+    status,
+    isFinalized: status?.status === TransactionStatus.Finalized,
+    isExecuted: status?.status === TransactionStatus.Executed,
+    isSealed: status?.status === TransactionStatus.Sealed,
+  };
+}