State Query
Dozer

Dozer

If there is a dozer instance serving a blockchain, as there is for Redstone (opens in a new tab) and Garnet (opens in a new tab), you can use it to run queries on the data of any World on that blockchain.

The query language is a subset of the SQL SELECT command (opens in a new tab).

Dozer URLs

Example World

On Garnet there is a World at address 0x95F5d049B014114E2fEeB5d8d994358Ce4FFd06e (opens in a new tab) that runs a slightly modified version of the React template (opens in a new tab). You can see the data schema for the World in the block explorer (opens in a new tab).

Curl queries

You can run dozer queries by communicating directly with the server's API, for example using curl (opens in a new tab).

Simple query

This query looks for some fields from a single table.

  1. Create a file, query.json, with this content.

    query.json
    [
  {
    "address": "0x95F5d049B014114E2fEeB5d8d994358Ce4FFd06e",
    "query": "SELECT id, description FROM app__Tasks"
  }
]
    ℹ️

    Dozer does not support SELECT * FROM <table>, you have to specify column names.

  2. Run this command. Install curl and jq first if necessary.

    curl https://dozer.mud.garnetchain.com/q --compressed \
     -H 'Accept-Encoding: gzip'  \
     -H 'Content-Type: application/json' \
     -d @query.json | jq

The output is a mapping with two fields, the block height for which the result is valid, and the result itself. The result is a list of query responses, here it contains just one item because we only submitted a single query. The query response is also a list. The first entry is the field names, and all the other entries are rows returned by SELECT.

{
  "block_height": 5699682,
  "result": [
    [
      [
        "id",
        "description"
      ],
      [
        "0x3100000000000000000000000000000000000000000000000000000000000000",
        "Walk the dog"
      ],
      [
        "0x3e0a112aadc5e02927fb4a91649bea565fd1baa1175aae4cb4957d6348f165cf",
        "Test"
      ],
    ]
  ]
}

Here we only care about the first result, so from now on we use this command line to tell jq to only show us that information.

curl https://dozer.mud.garnetchain.com/q --compressed  \
    -H 'Accept-Encoding: gzip' \
    -H 'Content-Type: application/json' \
    -d @query.json | jq '.result[0]'

Conditions

If we want to see only those tasks that haven't been completed we can use a WHERE clause.

query.json
[
  {
    "address": "0x95F5d049B014114E2fEeB5d8d994358Ce4FFd06e",
    "query": "SELECT id, description FROM app__Tasks WHERE completedAt=0"
  }
]
Results
[
  ["id", "description"],
  ["0x3100000000000000000000000000000000000000000000000000000000000000", "Walk the dog"],
  ["0x3e0a112aadc5e02927fb4a91649bea565fd1baa1175aae4cb4957d6348f165cf", "Test"]
]

Limited results

If you only want to see a few results, you can use a LIMIT clause.

query.json
[
  {
    "address": "0x95F5d049B014114E2fEeB5d8d994358Ce4FFd06e",
    "query": "SELECT id, description FROM app__Tasks LIMIT 2"
  }
]
Results
[
  ["id", "description"],
  ["0x3100000000000000000000000000000000000000000000000000000000000000", "Walk the dog"],
  ["0x3e0a112aadc5e02927fb4a91649bea565fd1baa1175aae4cb4957d6348f165cf", "Test"]
]

You can use OFFSET to get a paging effect. For example, if you use this query.json you get two results, and the last row of the first one is repeated as the first row of the second one.

query.json
[
  {
    "address": "0x95F5d049B014114E2fEeB5d8d994358Ce4FFd06e",
    "query": "SELECT id, description FROM app__Tasks LIMIT 3"
  },
  {
    "address": "0x95F5d049B014114E2fEeB5d8d994358Ce4FFd06e",
    "query": "SELECT id, description FROM app__Tasks LIMIT 3 OFFSET 2"
  }
]
Results

Use this command to see the results of both queries.

curl https://dozer.mud.garnetchain.com/q --compressed  \
  -H 'Accept-Encoding: gzip' \
  -H 'Content-Type: application/json' -d @query.json \
  | jq '.result'

The result is:

[
  [
    ["id", "description"],
    ["0x3100000000000000000000000000000000000000000000000000000000000000", "Walk the dog"],
    ["0x3e0a112aadc5e02927fb4a91649bea565fd1baa1175aae4cb4957d6348f165cf", "Test"],
    ["0xb15fd0e41ab0bb6eb992e0a3d4f30fce6ee24a5fc9c30f725fdfc96d9d16ed95", "Do the dishes"]
  ],
  [
    ["id", "description"],
    ["0xb15fd0e41ab0bb6eb992e0a3d4f30fce6ee24a5fc9c30f725fdfc96d9d16ed95", "Do the dishes"],
    ["0xb81d5036d0b62e0f2536635cbd5d7cec1d1f0706c0c6c1a9fa74293d7b0888eb", "Take out the trash"]
  ]
]

Sorted results

If you want to control the order in which you get results, you can use an ORDER BY clause.

query.json
[
  {
    "address": "0x95F5d049B014114E2fEeB5d8d994358Ce4FFd06e",
    "query": "SELECT description, createdAt FROM app__Tasks ORDER BY createdAt"
  }
]

Note that the sort field(s) need to be part of the selected columns.

Results
[
  ["description", "createdat"],
  ["Walk the dog", "1723495628"],
  ["Take out the trash", "1723495640"],
  ["Do the dishes", "1723495642"],
  ["Test", "1723495964"],
  ["Test from a different account", "1723576522"],
  ["Another test", "1723576522"],
  ["Yet another test", "1723646440"]
]

Multiple tables

You can join multiple tables, using the same syntax SQL uses.

query.json
[
  {
    "address": "0x95F5d049B014114E2fEeB5d8d994358Ce4FFd06e",
    "query": "SELECT app__Creator.id, description, taskCreator FROM app__Tasks, app__Creator WHERE app__Creator.id=app__Tasks.id"
  }
]
Results
[
  ["id", "description", "taskcreator"],
  [
    "0x3e0a112aadc5e02927fb4a91649bea565fd1baa1175aae4cb4957d6348f165cf",
    "Test",
    "0x735b2f2c662ebedffa94027a7196f0559f7f18a4"
  ],
  [
    "0x727d7bfe00b6db638c69595059dc10e21c52a7912d090905a7c7dc8659efd3b8",
    "Test from a different account",
    "0x428b1853e5ec29d35c84a218ec5170efc7621b58"
  ],
  [
    "0xb15fd0e41ab0bb6eb992e0a3d4f30fce6ee24a5fc9c30f725fdfc96d9d16ed95",
    "Do the dishes",
    "0x8225d72f2c39f3729d7f3fc03c6aa8731eaeef48"
  ],
  [
    "0xb81d5036d0b62e0f2536635cbd5d7cec1d1f0706c0c6c1a9fa74293d7b0888eb",
    "Take out the trash",
    "0x8225d72f2c39f3729d7f3fc03c6aa8731eaeef48"
  ],
  [
    "0xd43394ecf79077f65cd83b534dd44d3b4e9e2aa553e95aafecd14b8529543cda",
    "Another test",
    "0x428b1853e5ec29d35c84a218ec5170efc7621b58"
  ]
]

Grouping results

You can use GROUP BY to identify different groups. For example, this query gets you the different task creators.

query.json
[
  {
    "address": "0x95F5d049B014114E2fEeB5d8d994358Ce4FFd06e",
    "query": "SELECT taskCreator FROM app__Creator GROUP BY taskCreator"
  }
]
Results
[
  ["taskcreator"],
  ["0x428b1853e5ec29d35c84a218ec5170efc7621b58"],
  ["0x735b2f2c662ebedffa94027a7196f0559f7f18a4"],
  ["0x8225d72f2c39f3729d7f3fc03c6aa8731eaeef48"]
]

Typescript queries

You can query dozer from Typescript (opens in a new tab) without using MUD client synchronization.

  1. Create the project (in an empty directory) and install the software.

    pnpm create ts-node
pnpm install

  2. Add the package that includes the dozer library.

    pnpm install @latticexyz/store-sync @latticexyz/store

  3. Replace src/main.ts with this file.

    main.ts
    import { fetchRecordsSql, selectFrom } from "@latticexyz/store-sync/dozer";
import { defineStore } from "@latticexyz/store";
 
const config = defineStore({
  namespace: "app",
  tables: {
    Tasks: {
      schema: {
        id: "bytes32",
        createdAt: "uint256",
        completedAt: "uint256",
        description: "string",
      },
      key: ["id"],
    },
    Creator: {
      schema: {
        id: "bytes32",
        taskCreator: "address",
      },
      key: ["id"],
    },
  },
});
 
const queryUncompleted = selectFrom({
  table: config.tables.app__Tasks,
  where: "completedAt = 0",
  limit: 2,
});
 
const queryResult = await fetchRecordsSql({
  dozerUrl: "https://dozer.mud.garnetchain.com/q",
  storeAddress: "0x95F5d049B014114E2fEeB5d8d994358Ce4FFd06e",
  queries: [queryUncompleted],
});
 
console.log("\n\nTwo uncompleted tasks");
console.log(`SQL: ${queryUncompleted.sql}\nResult:`);
console.log(queryResult.result[0].records);

  4. Compile and execute the application.

    pnpm build && pnpm start
Explanation
import { fetchRecordsSql, selectFrom } from "@latticexyz/store-sync/dozer";
import { defineStore } from "@latticexyz/store";

Import the necessary definitions.

const config = defineStore({
  namespace: "app",
  tables: {
    ...
  },
})

Create the table configuration. The input to defineStore is the same as used in the the mud.config.ts file.

const queryUncompleted = selectFrom({
  table: config.tables.app__Tasks,
  where: "completedAt = 0",
  limit: 2,
});

Create a query using selectFrom (opens in a new tab). The queries supported by selectFrom are a subset of those dozer supports. The results come from a single table, and only WHERE and LIMIT clauses are supported.

const queryResult = await fetchRecordsSql({
  dozerUrl: "https://dozer.mud.garnetchain.com/q",
  storeAddress: "0x95F5d049B014114E2fEeB5d8d994358Ce4FFd06e",
  queries: [queryUncompleted],
});

Run the query.

console.log("\n\nTwo uncompleted tasks");
console.log(`SQL: ${queryUncompleted.sql}\nResult:`);

The SQL query that generated the resulting records.

console.log(queryResult.result[0].records);

The actual records.

Dozer with MUD synchronization

Of course, you can also add dozer to a MUD client with synchronization.

Create a client to access the World

These are the steps to create a client that can access the World.

  1. Create and run a react template application.

    pnpm create mud@latest tasks --template react
cd tasks
pnpm dev

  2. Browse to the application (opens in a new tab). The URL specifies the chainId and worldAddress for the World.

  3. In MUD DevTools see your account address and fund it on Garnet (opens in a new tab). You may need to get test ETH for your own address, and then transfer it to the account address the application uses.

  4. You can now create, complete, and delete tasks.

  5. To see the content of the app__Creator table, edit packages/contracts/mud.config.ts to add the Creator table definition.

    mud.config.ts
    import { defineWorld } from "@latticexyz/world";
 
export default defineWorld({
  namespace: "app",
  tables: {
    Tasks: {
      schema: {
        id: "bytes32",
        createdAt: "uint256",
        completedAt: "uint256",
        description: "string",
      },
      key: ["id"],
    },
    Creator: {
      schema: {
        id: "bytes32",
        taskCreator: "address",
      },
      key: ["id"],
    },
  },
});

Updating the client to use dozer

The main purpose of dozer is to allow MUD clients to specify the subset of table records that a client needs, instead of synchronizing whole tables.

To update the client, you change packages/client/src/mud/setupNetwork.ts to:

setupNetwork.ts
/*
 * The MUD client code is built on top of viem
 * (https://viem.sh/docs/getting-started.html).
 * This line imports the functions we need from it.
 */
import {
  createPublicClient,
  fallback,
  webSocket,
  http,
  createWalletClient,
  Hex,
  ClientConfig,
  getContract,
} from "viem";
 
import { DozerSyncFilter, getSnapshot, selectFrom } from "@latticexyz/store-sync/dozer";
 
import { syncToZustand } from "@latticexyz/store-sync/zustand";
import { getNetworkConfig } from "./getNetworkConfig";
import IWorldAbi from "contracts/out/IWorld.sol/IWorld.abi.json";
import { createBurnerAccount, transportObserver, ContractWrite } from "@latticexyz/common";
import { transactionQueue, writeObserver } from "@latticexyz/common/actions";
import { Subject, share } from "rxjs";
 
/*
 * Import our MUD config, which includes strong types for
 * our tables and other config options. We use this to generate
 * things like RECS components and get back strong types for them.
 *
 * See https://mud.dev/templates/typescript/contracts#mudconfigts
 * for the source of this information.
 */
import mudConfig from "contracts/mud.config";
 
export type SetupNetworkResult = Awaited<ReturnType<typeof setupNetwork>>;
 
export async function setupNetwork() {
  const networkConfig = await getNetworkConfig();
 
  /*
   * Create a viem public (read only) client
   * (https://viem.sh/docs/clients/public.html)
   */
  const clientOptions = {
    chain: networkConfig.chain,
    transport: transportObserver(fallback([webSocket(), http()])),
    pollingInterval: 1000,
  } as const satisfies ClientConfig;
 
  const publicClient = createPublicClient(clientOptions);
 
  /*
   * Create an observable for contract writes that we can
   * pass into MUD dev tools for transaction observability.
   */
  const write$ = new Subject<ContractWrite>();
 
  /*
   * Create a temporary wallet and a viem client for it
   * (see https://viem.sh/docs/clients/wallet.html).
   */
  const burnerAccount = createBurnerAccount(networkConfig.privateKey as Hex);
  const burnerWalletClient = createWalletClient({
    ...clientOptions,
    account: burnerAccount,
  })
    .extend(transactionQueue())
    .extend(writeObserver({ onWrite: (write) => write$.next(write) }));
 
  /*
   * Create an object for communicating with the deployed World.
   */
  const worldContract = getContract({
    address: networkConfig.worldAddress as Hex,
    abi: IWorldAbi,
    client: { public: publicClient, wallet: burnerWalletClient },
  });
 
  const dozerUrl = "https://dozer.mud.garnetchain.com/q";
  const yesterday = Date.now() / 1000 - 24 * 60 * 60;
  const filters: DozerSyncFilter[] = [
    selectFrom({
      table: mudConfig.tables.app__Tasks,
      where: `"createdAt" > ${yesterday}`,
    }),
    { table: mudConfig.tables.app__Creator },
  ];
  const { initialBlockLogs } = await getSnapshot({
    dozerUrl,
    storeAddress: networkConfig.worldAddress as Hex,
    filters,
    chainId: networkConfig.chainId,
  });
  const liveSyncFilters = filters.map((filter) => ({
    tableId: filter.table.tableId,
  }));
 
  /*
   * 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({
    initialBlockLogs,
    filters: liveSyncFilters,
    config: mudConfig,
    address: networkConfig.worldAddress as Hex,
    publicClient,
    startBlock: BigInt(networkConfig.initialBlockNumber),
  });
 
  return {
    tables,
    useStore,
    publicClient,
    walletClient: burnerWalletClient,
    latestBlock$,
    storedBlockLogs$,
    waitForTransaction,
    worldContract,
    write$: write$.asObservable().pipe(share()),
  };
}
Explanation
import { DozerSyncFilter, getSnapshot, selectFrom } from "@latticexyz/store-sync/dozer";

Import the dozer definitions we need.

const dozerUrl = "https://dozer.mud.garnetchain.com/q";

The URL for the dozer service. This is simplified testing code, on a production system this will probably be a lookup table based on the chainId.

const yesterday = Date.now() / 1000 - 24 * 60 * 60;

In JavaScript (and therefore TypeScript), time is stored as milliseconds since the beginning of the epoch (opens in a new tab). In UNIX, and therefore in Ethereum, time is stored as seconds since that same point. This is the timestamp 24 hours ago.

  const filters: DozerSyncFilter[] = [

We create the filters for the tables we're interested in.

    selectFrom({
      table: mudConfig.tables.app__Tasks,
      where: `"createdAt" > ${yesterday}`,
    }),

From the app__Tasks table we only want entries created in the last 24 hours. To verify that the filter works as expected you can later change the code to only look for entries older than 24 hours.

    { table: mudConfig.tables.app__Creator },
  ];

We also want the app__Counter table.

const { initialBlockLogs } = await getSnapshot({
  dozerUrl,
  storeAddress: networkConfig.worldAddress as Hex,
  filters,
  chainId: networkConfig.chainId,
});

Get the initial snapshot to hydrate (fill with initial information) the data store. Note that this snapshot does not have the actual data, but the events that created it.

const liveSyncFilters = filters.map((filter) => ({
  tableId: filter.table.tableId,
}));

The synchronization filters are a lot more limited. You can read the description of these filters here.

  const { ... } = await syncToZustand({
    initialBlockLogs,
    filters: liveSyncFilters,
      ...
  });

Finally, we provide initialBlockLogs for the hydration and filters for the updates to the synchronization function (either syncToRecs or syncToZustand).

mud set-versionRECS