Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(filter-sync and dozer): explain that there are two sync types 🚗 #3179

Merged
merged 2 commits into from
Sep 17, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions docs/components/common-text/FilterTypes.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
import { Callout } from "nextra/components";

<Callout type="info">
MUD initial data hydration, and therefore filtering, comes in two flavors: [Dozer](/state-query/dozer) and [generic](/guides/hello-world/filter-sync).
Note that this is for the initial hydration, currently limits on on-going synchronization are limited to [the generic method](/guides/hello-world/filter-sync).

| | Dozer | Generic |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Filtering | Can filter on most SQL functions | Can only filter on tables and the first two key fields (limited by [`eth_getLogs`](https://ethereum.github.io/execution-apis/api-documentation/) filters) |
| Availability | [Redstone](https://redstone.xyz/docs/network-info), [Garnet](https://garnetchain.com/docs/network-info), or elsewhere if you run your own instance | Any EVM chain |
| Security assumptions | The Dozer instance returns accurate information | The endpoint returns accurate information (same assumption as any other blockchain app) |

</Callout>
15 changes: 15 additions & 0 deletions docs/pages/guides/hello-world/filter-sync.mdx
Original file line number Diff line number Diff line change
@@ -1,10 +1,25 @@
import { CollapseCode } from "../../../components/CollapseCode";
import FilterTypes from "../../../components/common-text/FilterTypes.mdx";

# Filter data synchronization

In this tutorial you modify `networkSetup.ts` to filter the information you synchronize.
Filtering information this way allows you to reduce the use of network resources and makes loading times faster.

<FilterTypes />

<details>

<summary>Why are only the first two key fields available for filtering?</summary>

Ethereum log entries can have [up to four indexed fields](https://www.evm.codes/?fork=cancun#a4).
However, Solidity only supports [three indexed fields](https://www.alchemy.com/overviews/solidity-events) because the first indexed field is used for the event name and type.
In MUD, [this field](https://github.com/latticexyz/mud/blob/main/packages/store/src/IStoreEvents.sol) specifies whether [a new record is created](https://github.com/latticexyz/mud/blob/main/packages/store/src/IStoreEvents.sol#L26-L32), a record is changed (either [static fields](https://github.com/latticexyz/mud/blob/main/packages/store/src/IStoreEvents.sol#L43) or [dynamic fields](https://github.com/latticexyz/mud/blob/main/packages/store/src/IStoreEvents.sol#L56-L64)), or [a record is deleted](https://github.com/latticexyz/mud/blob/main/packages/store/src/IStoreEvents.sol#L71).
The second indexed fields is always the table's [resource ID](/world/resource-ids).
This leaves two fields for key fields.

</details>

## Setup

To see the effects of filtering we need a table with entries to filter. To get such a table:
Expand Down
15 changes: 11 additions & 4 deletions docs/pages/state-query/dozer.mdx
Original file line number Diff line number Diff line change
@@ -1,15 +1,22 @@
import { CollapseCode } from "../../components/CollapseCode";
import FilterTypes from "../../components/common-text/FilterTypes.mdx";
import { Callout } from "nextra/components";

# Dozer

If there is a dozer instance serving a blockchain, as there is for [Redstone](https://redstone.xyz/) and [Garnet](https://garnetchain.com/docs/what-is-redstone), you can use it to run queries on the data of any `World` on that blockchain.
<FilterTypes />

If there is a dozer instance serving a blockchain, as there is for [Redstone](https://redstone.xyz/) and [Garnet](https://garnetchain.com/docs/what-is-redstone), you can use it to:

- Run queries on the data of any `World` on that blockchain.
- [Speed up the initial hydration](#dozer-with-mud-synchronization) by reducing the amount of data that needs to be synchronized.
This is important for the user experience, because until the initial hydration is done the client is typically unusable.

The query language is a subset of [the SQL `SELECT` command](<https://en.wikipedia.org/wiki/Select_(SQL)>).

## Dozer URLs

- [Redstone](https://redstone.xyz/) dozer `https://dozer.mud.redstonechain.com/q`
- [Redstone](https://redstone.xyz/) dozer - `https://dozer.mud.redstonechain.com/q`
- [Garnet](https://garnetchain.com/) dozer - `https://dozer.mud.garnetchain.com/q`

## Example `World`
Expand Down Expand Up @@ -433,7 +440,7 @@ The actual records.

## Dozer with MUD synchronization

Of course, you can also add dozer to a MUD client with synchronization.
You can also add dozer to a MUD client to speed up the initial hydration.

### Create a client to access the `World`

Expand Down Expand Up @@ -495,7 +502,7 @@ To update the client, you change `packages/client/src/mud/setupNetwork.ts` to:

<CollapseCode>

```typescript filename="setupNetwork.ts" copy showLineNumbers {17-21, 84-101, 111-112}
```typescript filename="setupNetwork.ts" copy showLineNumbers {17, 80-97, 106-107}
/*
* The MUD client code is built on top of viem
* (https://viem.sh/docs/getting-started.html).
Expand Down
Loading