refactor: waitForStateChange -> waitForTransaction (#3210)

.changeset/thick-countries-double.md

@@ -0,0 +1,11 @@
+---
+"@latticexyz/explorer": patch
+---
+
+Renamed optional `waitForStateChange` param in `observer()` decorator to `waitForTransaction` to better align with `@latticexyz/store-sync` packages.
+
+```diff
+ const { waitForTransaction } = syncToZustand(...);
+-observer({ waitForStateChange: waitForTransaction });
++observer({ waitForTransaction });
+```

examples/local-explorer/packages/client/src/mud/setupNetwork.ts

@@ -18,7 +18,7 @@ import { getNetworkConfig } from "./getNetworkConfig";
 import IWorldAbi from "contracts/out/IWorld.sol/IWorld.abi.json";
 import { createBurnerAccount, transportObserver } from "@latticexyz/common";
 import { transactionQueue } from "@latticexyz/common/actions";
-import { observer, type WaitForStateChange } from "@latticexyz/explorer/observer";
+import { observer } from "@latticexyz/explorer/observer";
 
 /*
  * Import our MUD config, which includes strong types for
@@ -34,7 +34,6 @@ export type SetupNetworkResult = Awaited<ReturnType<typeof setupNetwork>>;
 
 export async function setupNetwork() {
   const networkConfig = await getNetworkConfig();
-  const waitForStateChange = Promise.withResolvers<WaitForStateChange>();
 
   /*
    * Create a viem public (read only) client
@@ -48,6 +47,19 @@ export async function setupNetwork() {
 
   const publicClient = createPublicClient(clientOptions);
 
+  /*
+   * Sync on-chain state into RECS and keeps our client in sync.
+   * Uses the MUD indexer if available, otherwise falls back
+   * to the viem publicClient to make RPC calls to fetch MUD
+   * events from the chain.
+   */
+  const { tables, useStore, latestBlock$, storedBlockLogs$, waitForTransaction } = await syncToZustand({
+    config: mudConfig,
+    address: networkConfig.worldAddress as Hex,
+    publicClient,
+    startBlock: BigInt(networkConfig.initialBlockNumber),
+  });
+
   /*
    * Create a temporary wallet and a viem client for it
    * (see https://viem.sh/docs/clients/wallet.html).
@@ -58,11 +70,7 @@ export async function setupNetwork() {
     account: burnerAccount,
   })
     .extend(transactionQueue())
-    .extend(
-      observer({
-        waitForStateChange: (hash) => waitForStateChange.promise.then((fn) => fn(hash)),
-      }),
-    );
+    .extend(observer({ waitForTransaction }));
 
   /*
    * Create an object for communicating with the deployed World.
@@ -73,20 +81,6 @@ export async function setupNetwork() {
     client: { public: publicClient, wallet: burnerWalletClient },
   });
 
-  /*
-   * Sync on-chain state into RECS and keeps our client in sync.
-   * Uses the MUD indexer if available, otherwise falls back
-   * to the viem publicClient to make RPC calls to fetch MUD
-   * events from the chain.
-   */
-  const { tables, useStore, latestBlock$, storedBlockLogs$, waitForTransaction } = await syncToZustand({
-    config: mudConfig,
-    address: networkConfig.worldAddress as Hex,
-    publicClient,
-    startBlock: BigInt(networkConfig.initialBlockNumber),
-  });
-  waitForStateChange.resolve(waitForTransaction);
-
   return {
     tables,
     useStore,

packages/explorer/src/exports/observer.ts

@@ -1,3 +1,3 @@
 export { createBridge, type CreateBridgeOpts } from "../observer/bridge";
 export type { Messages, MessageType, EmitMessage } from "../observer/messages";
-export { observer, type ObserverOptions, type WaitForStateChange } from "../observer/decorator";
+export { observer, type ObserverOptions, type WaitForTransaction } from "../observer/decorator";

packages/explorer/src/observer/decorator.ts

@@ -4,16 +4,16 @@ import { formatAbiItem, getAction } from "viem/utils";
 import { createBridge } from "./bridge";
 import { ReceiptSummary } from "./common";
 
-export type WaitForStateChange = (hash: Hex) => Promise<ReceiptSummary>;
+export type WaitForTransaction = (hash: Hex) => Promise<ReceiptSummary>;
 
 export type ObserverOptions = {
   explorerUrl?: string;
-  waitForStateChange?: WaitForStateChange;
+  waitForTransaction?: WaitForTransaction;
 };
 
 let writeCounter = 0;
 
-export function observer({ explorerUrl = "http://localhost:13690", waitForStateChange }: ObserverOptions = {}): <
+export function observer({ explorerUrl = "http://localhost:13690", waitForTransaction }: ObserverOptions = {}): <
   transport extends Transport,
   chain extends Chain | undefined = Chain | undefined,
   account extends Account | undefined = Account | undefined,
@@ -52,12 +52,12 @@ export function observer({ explorerUrl = "http://localhost:13690", waitForStateC
         });
       });
 
-      if (waitForStateChange) {
+      if (waitForTransaction) {
         write.then((hash) => {
-          const receipt = waitForStateChange(hash);
-          emit("waitForStateChange", { writeId });
+          const receipt = waitForTransaction(hash);
+          emit("waitForTransaction", { writeId });
           Promise.allSettled([receipt]).then(([result]) => {
-            emit("waitForStateChange:result", { ...result, writeId });
+            emit("waitForTransaction:result", { ...result, writeId });
           });
         });
       }

packages/explorer/src/observer/messages.ts

@@ -18,10 +18,10 @@ export type Messages = {
   "waitForTransactionReceipt:result": PromiseSettledResult<ReceiptSummary> & {
     writeId: string;
   };
-  waitForStateChange: {
+  waitForTransaction: {
     writeId: string;
   };
-  "waitForStateChange:result": PromiseSettledResult<ReceiptSummary> & {
+  "waitForTransaction:result": PromiseSettledResult<ReceiptSummary> & {
     writeId: string;
   };
 };

packages/store-sync/src/stash/syncToStash.ts

@@ -35,8 +35,7 @@ export type SyncToStashOptions = {
   startSync?: boolean;
 };
 
-export type SyncToStashResult = Omit<SyncResult, "waitForTransaction"> & {
-  waitForStateChange: SyncResult["waitForTransaction"];
+export type SyncToStashResult = SyncResult & {
   stopSync: () => void;
 };
 
@@ -50,7 +49,7 @@ export async function syncToStash({
 
   const storageAdapter = createStorageAdapter({ stash });
 
-  const { waitForTransaction: waitForStateChange, ...sync } = await createStoreSync({
+  const sync = await createStoreSync({
     storageAdapter,
     publicClient: client.extend(publicActions) as never,
     address,
@@ -70,7 +69,6 @@ export async function syncToStash({
 
   return {
     ...sync,
-    waitForStateChange,
     stopSync,
   };
 }