You can run the indexer locally by checking out the MUD monorepo, installing/building everything, and running pnpm start:local from packages/store-indexer.

To query the indexer in the client, you can create a tRPC client with a URL pointing to the indexer service and call the available tRPC methods:

import { createIndexerClient } from "@latticexyz/store-sync/trpc-indexer";

const indexer = createIndexerClient({ url: indexerUrl });
const result = await indexer.findAll.query({
  chainId: publicClient.chain.id,
  address,
});

If you're using syncToRecs, you can just pass in the indexerUrl option as a shortcut to the above:

import { syncToRecs } from "@latticexyz/store-sync/recs";

syncToRecs({
  ...
  indexerUrl: "https://your.indexer.service",
});

fix: changeset package name (#1270) (@latticexyz/cli, @latticexyz/common, @latticexyz/recs, @latticexyz/store-indexer, create-mud)

Templates and examples now use MUD's new sync packages, all built on top of viem. This greatly speeds up and stabilizes our networking code and improves types throughout.

These new sync packages come with support for our recs package, including encodeEntity and decodeEntity utilities for composite keys.

If you're using store-cache and useRow/useRows, you should wait to upgrade until we have a suitable replacement for those libraries. We're working on a sql.js-powered sync module that will replace store-cache.

Migrate existing RECS apps to new sync packages

As you migrate, you may find some features replaced, removed, or not included by default. Please open an issue and let us know if we missed anything.

Add @latticexyz/store-sync package to your app's client package and make sure viem is pinned to version 1.3.1 (otherwise you may get type errors)

In your supportedChains.ts, replace foundry chain with our new mudFoundry chain.

- import { foundry } from "viem/chains";
- import { MUDChain, latticeTestnet } from "@latticexyz/common/chains";
+ import { MUDChain, latticeTestnet, mudFoundry } from "@latticexyz/common/chains";

- export const supportedChains: MUDChain[] = [foundry, latticeTestnet];
+ export const supportedChains: MUDChain[] = [mudFoundry, latticeTestnet];

In getNetworkConfig.ts, remove the return type (to let TS infer it for now), remove now-unused config values, and add the viem chain object.

- export async function getNetworkConfig(): Promise<NetworkConfig> {
+ export async function getNetworkConfig() {

  const initialBlockNumber = params.has("initialBlockNumber")
    ? Number(params.get("initialBlockNumber"))
-   : world?.blockNumber ?? -1; // -1 will attempt to find the block number from RPC
+   : world?.blockNumber ?? 0n;

+ return {
+   privateKey: getBurnerWallet().value,
+   chain,
+   worldAddress,
+   initialBlockNumber,
+   faucetServiceUrl: params.get("faucet") ?? chain.faucetUrl,
+ };

In setupNetwork.ts, replace setupMUDV2Network with syncToRecs.

- import { setupMUDV2Network } from "@latticexyz/std-client";
- import { createFastTxExecutor, createFaucetService, getSnapSyncRecords } from "@latticexyz/network";
+ import { createFaucetService } from "@latticexyz/network";
+ import { createPublicClient, fallback, webSocket, http, createWalletClient, getContract, Hex, parseEther, ClientConfig } from "viem";
+ import { encodeEntity, syncToRecs } from "@latticexyz/store-sync/recs";
+ import { createBurnerAccount, createContract, transportObserver } from "@latticexyz/common";

- const result = await setupMUDV2Network({
-   ...
- });

+ const clientOptions = {
+   chain: networkConfig.chain,
+   transport: transportObserver(fallback([webSocket(), http()])),
+   pollingInterval: 1000,
+ } as const satisfies ClientConfig;

+ const publicClient = createPublicClient(clientOptions);

+ const burnerAccount = createBurnerAccount(networkConfig.privateKey as Hex);
+ const burnerWalletClient = createWalletClient({
+   ...clientOptions,
+   account: burnerAccount,
+ });

+ const { components, latestBlock$, blockStorageOperations$, waitForTransaction } = await syncToRecs({
+   world,
+   config: storeConfig,
+   address: networkConfig.worldAddress as Hex,
+   publicClient,
+   components: contractComponents,
+   startBlock: BigInt(networkConfig.initialBlockNumber),
+   indexerUrl: networkConfig.indexerUrl ?? undefined,
+ });

+ const worldContract = createContract({
+   address: networkConfig.worldAddress as Hex,
+   abi: IWorld__factory.abi,
+   publicClient,
+   walletClient: burnerWalletClient,
+ });

  // Request drip from faucet
- const signer = result.network.signer.get();
- if (networkConfig.faucetServiceUrl && signer) {
-   const address = await signer.getAddress();
+ if (networkConfig.faucetServiceUrl) {
+   const address = burnerAccount.address;

  const requestDrip = async () => {
-   const balance = await signer.getBalance();
+   const balance = await publicClient.getBalance({ address });
    console.info(`[Dev Faucet]: Player balance -> ${balance}`);
-   const lowBalance = balance?.lte(utils.parseEther("1"));
+   const lowBalance = balance < parseEther("1");

You can remove the previous ethers worldContract, snap sync code, and fast transaction executor.

The return of setupNetwork is a bit different than before, so you may have to do corresponding app changes.

+ return {
+   world,
+   components,
+   playerEntity: encodeEntity({ address: "address" }, { address: burnerWalletClient.account.address }),
+   publicClient,
+   walletClient: burnerWalletClient,
+   latestBlock$,
+   blockStorageOperations$,
+   waitForTransaction,
+   worldContract,
+ };

Update createSystemCalls with the new return type of setupNetwork.

  export function createSystemCalls(
-   { worldSend, txReduced$, singletonEntity }: SetupNetworkResult,
+   { worldContract, waitForTransaction }: SetupNetworkResult,
    { Counter }: ClientComponents
  ) {
     const increment = async () => {
-      const tx = await worldSend("increment", []);
-      await awaitStreamValue(txReduced$, (txHash) => txHash === tx.hash);
+      const tx = await worldContract.write.increment();
+      await waitForTransaction(tx);
       return getComponentValue(Counter, singletonEntity);
     };

(optional) If you still need a clock, you can create it with:

import { map, filter } from "rxjs";
import { createClock } from "@latticexyz/network";

const clock = createClock({
  period: 1000,
  initialTime: 0,
  syncInterval: 5000,
});

world.registerDisposer(() => clock.dispose());

latestBlock$
  .pipe(
    map((block) => Number(block.timestamp) * 1000), // Map to timestamp in ms
    filter((blockTimestamp) => blockTimestamp !== clock.lastUpdateTime), // Ignore if the clock was already refreshed with this block
    filter((blockTimestamp) => blockTimestamp !== clock.currentTime), // Ignore if the current local timestamp is correct
  )
  .subscribe(clock.update); // Update the local clock

If you're using the previous LoadingState component, you'll want to migrate to the new SyncProgress:

import { SyncStep, singletonEntity } from "@latticexyz/store-sync/recs";

const syncProgress = useComponentValue(SyncProgress, singletonEntity, {
  message: "Connecting",
  percentage: 0,
  step: SyncStep.INITIALIZE,
});

if (syncProgress.step === SyncStep.LIVE) {
  // we're live!
}

feat(common): replace TableId with tableIdToHex/hexToTableId (#1258) (@latticexyz/cli, @latticexyz/common, @latticexyz/dev-tools, @latticexyz/network, @latticexyz/std-client, @latticexyz/store-sync)

Add tableIdToHex and hexToTableId pure functions and move/deprecate TableId.

feat(common): add createContract, createNonceManager utils (#1261) (@latticexyz/common)

Add utils for using viem with MUD

createContract is a wrapper around viem's getContract but with better nonce handling for faster executing of transactions. It has the same arguments and return type as getContract.
createNonceManager helps track local nonces, used by createContract.

Also renames mudTransportObserver to transportObserver.

Minor changes

feat(common): add viem utils (#1245) (@latticexyz/common)

Add utils for using viem with MUD

mudFoundry chain with a transaction request formatter that temporarily removes max fees to work better with anvil --base-fee 0
createBurnerAccount that also temporarily removes max fees during transaction signing to work better with anvil --base-fee 0
mudTransportObserver that will soon let MUD Dev Tools observe transactions

You can use them like:

import { createBurnerAccount, mudTransportObserver } from "@latticexyz/common";
import { mudFoundry } from "@latticexyz/common/chains";

createWalletClient({
  account: createBurnerAccount(privateKey),
  chain: mudFoundry,
  transport: mudTransportObserver(http()),
  pollingInterval: 1000,
});

feat(store-indexer,store-sync): make chain optional, configure indexer with RPC (#1234) (@latticexyz/store-indexer, @latticexyz/store-sync)

Accept a plain viem PublicClient (instead of requiring a Chain to be set) in store-sync and store-indexer functions. These functions now fetch chain ID using publicClient.getChainId() when no publicClient.chain.id is present.
Allow configuring store-indexer with a set of RPC URLs (RPC_HTTP_URL and RPC_WS_URL) instead of CHAIN_ID.

feat(store-sync): export singletonEntity as const, allow startBlock in syncToRecs (#1235) (@latticexyz/store-sync)

Export singletonEntity as const rather than within the syncToRecs result.

- const { singletonEntity, ... } = syncToRecs({ ... });
+ import { singletonEntity, syncToRecs } from "@latticexyz/store-sync/recs";
+ const { ... } = syncToRecs({ ... });

feat(schema-type): add type narrowing isStaticAbiType (#1196) (@latticexyz/schema-type)

add type narrowing isStaticAbiType

feat(common): move zero gas fee override to createContract (#1266) (@latticexyz/common)

Moves zero gas fee override to createContract until https://github.com/wagmi-dev/viem/pull/963 or similar feature lands
Skip simulation if gas is provided

Patch changes

fix(cli): add support for legacy transactions in deploy script (#1178) (@latticexyz/cli)

Add support for legacy transactions in deploy script by falling back to gasPrice if lastBaseFeePerGas is not available

feat: protocol-parser in go (#1116) (@latticexyz/services)

protocol-parser in Go

refactor(store): optimize Storage library (#1194) (@latticexyz/store)

Optimize storage library

feat(common): remove need for tx queue in createContract (#1271) (@latticexyz/common)

Remove need for tx queue in createContract

feat(store-sync): add block numbers to SyncProgress (#1228) (@latticexyz/store-sync)

Adds latestBlockNumber and lastBlockNumberProcessed to internal SyncProgress component

feat(store-sync): sync to RECS (#1197) (@latticexyz/store-sync)

Add RECS sync strategy and corresponding utils

import { createPublicClient, http } from 'viem';
import { syncToRecs } from '@latticexyz/store-sync';
import storeConfig from 'contracts/mud.config';
import { defineContractComponents } from './defineContractComponents';

const publicClient = createPublicClient({
  chain,
  transport: http(),
  pollingInterval: 1000,
});

const { components, singletonEntity, latestBlock$, blockStorageOperations$, waitForTransaction } = await syncToRecs({
  world,
  config: storeConfig,
  address: '0x...',
  publicClient,
  components: defineContractComponents(...),
});

fix(store): align Store event names between IStoreWrite and StoreCore (#1237) (@latticexyz/store)

Align Store events parameter naming between IStoreWrite and StoreCore

fix(cli): explicit import of world as type (#1206) (@latticexyz/cli, @latticexyz/std-client)

Generated contractComponents now properly import World as type

feat(store-sync): export singletonEntity as const, allow startBlock in syncToRecs (#1235) (@latticexyz/store-sync)

Add startBlock option to syncToRecs.

import { syncToRecs } from "@latticexyz/store-sync/recs";
import worlds from "contracts/worlds.json";

syncToRecs({
  startBlock: worlds['31337'].blockNumber,
  ...
});

chore: pin node to 18.16.1 (#1200) (@latticexyz/network)

Remove devEmit function when sending network events from SyncWorker because they can't be serialized across the web worker boundary.

feat(cli,recs,std-client): update RECS components with v2 key/value schemas (#1195) (@latticexyz/cli, @latticexyz/recs, @latticexyz/std-client)

Update RECS components with v2 key/value schemas. This helps with encoding/decoding composite keys and strong types for keys/values.

This may break if you were previously dependent on component.id, component.metadata.componentId, or component.metadata.tableId:

component.id is now the on-chain bytes32 hex representation of the table ID
component.metadata.componentName is the table name (e.g. Position)
component.metadata.tableName is the namespaced table name (e.g. myworld:Position)
component.metadata.keySchema is an object with key names and their corresponding ABI types
component.metadata.valueSchema is an object with field names and their corresponding ABI types

refactor(store): update tightcoder codegen, optimize TightCoder library (#1210) (@latticexyz/common, @latticexyz/store, @latticexyz/world)