Changelog

Version 2.0.0-next.3

Major changes

feat(world, store): stop loading schema from storage, require schema as an argument (#1174) (opens in a new tab) (@latticexyz/cli, @latticexyz/store, @latticexyz/world, create-mud)

All Store methods now require the table's value schema to be passed in as an argument instead of loading it from storage. This decreases gas cost and removes circular dependencies of the Schema table (where it was not possible to write to the Schema table before the Schema table was registered).

  function setRecord(
    bytes32 table,
    bytes32[] calldata key,
    bytes calldata data,
+   Schema valueSchema
  ) external;

The same diff applies to getRecord, getField, setField, pushToField, popFromField, updateInField, and deleteRecord.

This change only requires changes in downstream projects if the Store methods were accessed directly. In most cases it is fully abstracted in the generated table libraries, so downstream projects only need to regenerate their table libraries after updating MUD.

refactor(world): combine name and namespace to resource selector in World methods (#1208) (opens in a new tab) (@latticexyz/cli, @latticexyz/world)

  • All World function selectors that previously had bytes16 namespace, bytes16 name arguments now use bytes32 resourceSelector instead. This includes setRecord, setField, pushToField, popFromField, updateInField, deleteRecord, call, grantAccess, revokeAccess, registerTable, registerStoreHook, registerSystemHook, registerFunctionSelector, registerSystem and registerRootFunctionSelector. This change aligns the World function selectors with the Store function selectors, reduces clutter, reduces gas cost and reduces the World's contract size.

  • The World's registerHook function is removed. Use registerStoreHook or registerSystemHook instead.

  • The deploy script is updated to integrate the World interface changes

refactor: remove v1 network package, remove snap sync module, deprecate std-client (#1311) (opens in a new tab) (@latticexyz/world)

The SnapSyncModule is removed. The recommended way of loading the initial state of a MUD app is via the new store-indexer (opens in a new tab). Loading state via contract getter functions is not recommended, as it's computationally heavy on the RPC, can't be cached, and is an easy way to shoot yourself in the foot with exploding RPC costs.

The @latticexyz/network package was deprecated and is now removed. All consumers should upgrade to the new sync stack from @latticexyz/store-sync.

refactor(store): optimize PackedCounter (#1231) (opens in a new tab) (@latticexyz/cli, @latticexyz/protocol-parser, @latticexyz/services, @latticexyz/store-sync, @latticexyz/store, @latticexyz/world)

Reverse PackedCounter encoding, to optimize gas for bitshifts. Ints are right-aligned, shifting using an index is straightforward if they are indexed right-to-left.

  • Previous encoding: (7 bytes | accumulator),(5 bytes | counter 1),...,(5 bytes | counter 5)
  • New encoding: (5 bytes | counter 5),...,(5 bytes | counter 1),(7 bytes | accumulator)

feat(store,world): combine schema and metadata registration, rename getSchema to getValueSchema, change Schema table id (#1182) (opens in a new tab) (@latticexyz/cli, @latticexyz/store, @latticexyz/world, @latticexyz/store-sync, create-mud)

  • Store's internal schema table is now a normal table instead of using special code paths. It is renamed to Tables, and the table ID changed from mudstore:schema to mudstore:Tables

  • Store's registerSchema and setMetadata are combined into a single registerTable method. This means metadata (key names, field names) is immutable and indexers can create tables with this metadata when a new table is registered on-chain.

    -  function registerSchema(bytes32 table, Schema schema, Schema keySchema) external;
    -
    -  function setMetadata(bytes32 table, string calldata tableName, string[] calldata fieldNames) external;
     
    +  function registerTable(
    +    bytes32 table,
    +    Schema keySchema,
    +    Schema valueSchema,
    +    string[] calldata keyNames,
    +    string[] calldata fieldNames
    +  ) external;
  • World's registerTable method is updated to match the Store interface, setMetadata is removed

  • The getSchema method is renamed to getValueSchema on all interfaces

    - function getSchema(bytes32 table) external view returns (Schema schema);
    + function getValueSchema(bytes32 table) external view returns (Schema valueSchema);
  • The store-sync and cli packages are updated to integrate the breaking protocol changes. Downstream projects only need to manually integrate these changes if they access low level Store or World functions. Otherwise, a fresh deploy with the latest MUD will get you these changes.

refactor: remove v1 network package, remove snap sync module, deprecate std-client (#1311) (opens in a new tab) (@latticexyz/services, create-mud)

Move createFaucetService from @latticexyz/network to @latticexyz/services/faucet.

- import { createFaucetService } from "@latticexyz/network";
+ import { createFaucetService } from "@latticexyz/services/faucet";

refactor: remove v1 network package, remove snap sync module, deprecate std-client (#1311) (opens in a new tab) (@latticexyz/std-client, @latticexyz/common, create-mud)

Deprecate @latticexyz/std-client and remove v1 network dependencies.

  • getBurnerWallet is replaced by getBurnerPrivateKey from @latticexyz/common. It now returns a Hex string instead of an rxjs BehaviorSubject.

    - import { getBurnerWallet } from "@latticexyz/std-client";
    + import { getBurnerPrivateKey } from "@latticexyz/common";
    
    - const privateKey = getBurnerWallet().value;
    - const privateKey = getBurnerPrivateKey();
  • All functions from std-client that depended on v1 network code are removed (most notably setupMUDNetwork and setupMUDV2Network). Consumers should upgrade to v2 networking code from @latticexyz/store-sync.

  • The following functions are removed from std-client because they are very use-case specific and depend on deprecated code: getCurrentTurn, getTurnAtTime, getGameConfig, isUntraversable, getPlayerEntity, resolveRelationshipChain, findEntityWithComponentInRelationshipChain, findInRelationshipChain. Consumers should vendor these functions if they are still needed.

  • Remaining exports from std-client are moved to /deprecated. The package will be removed in a future release (once there are replacements for the deprecated exports).

    - import { ... } from "@latticexyz/std-client";
    + import { ... } from "@latticexyz/std-client/deprecated";

Patch changes

feat(common,store-sync): improve initial sync to not block returned promise (#1315) (opens in a new tab) (@latticexyz/common, @latticexyz/store-sync)

Initial sync from indexer no longer blocks the promise returning from createStoreSync, syncToRecs, and syncToSqlite. This should help with rendering loading screens using the SyncProgress RECS component and avoid the long flashes of no content in templates.

By default, syncToRecs and syncToSqlite will start syncing (via observable subscription) immediately after called.

If your app needs to control when syncing starts, you can use the startSync: false option and then blockStoreOperations$.subscribe() to start the sync yourself. Just be sure to unsubscribe to avoid memory leaks.

const { blockStorageOperations$ } = syncToRecs({
  ...
  startSync: false,
});
 
// start sync manually by subscribing to `blockStorageOperation$`
const subcription = blockStorageOperation$.subscribe();
 
// clean up subscription
subscription.unsubscribe();

refactor(store): optimize table libraries (#1303) (opens in a new tab) (@latticexyz/store)

Optimize autogenerated table libraries

feat(store-sync): add more logging to waitForTransaction (#1317) (opens in a new tab) (@latticexyz/store-sync)

add retry attempts and more logging to waitForTransaction

refactor(store): optimize Schema (#1252) (opens in a new tab) (@latticexyz/store, @latticexyz/world)

Optimize Schema methods. Return uint256 instead of uint8 in SchemaInstance numFields methods


Version 2.0.0-next.2

Major changes

feat(store-indexer): use fastify, move trpc to /trpc (#1232) (opens in a new tab) (@latticexyz/store-indexer)

Adds a Fastify (opens in a new tab) server in front of tRPC and puts tRPC endpoints under /trpc to make way for other top-level endpoints (e.g. tRPC panel (opens in a new tab) or other API frontends like REST or gRPC).

If you're using @latticexyz/store-sync packages with an indexer (either createIndexerClient or indexerUrl argument of syncToRecs), then you'll want to update your indexer URL:

 createIndexerClient({
-  url: "https://indexer.dev.linfra.xyz",
+  url: "https://indexer.dev.linfra.xyz/trpc",
 });
 syncToRecs({
   ...
-  indexerUrl: "https://indexer.dev.linfra.xyz",
+  indexerUrl: "https://indexer.dev.linfra.xyz/trpc",
 });

refactor(store): remove TableId library (#1279) (opens in a new tab) (@latticexyz/store)

Remove TableId library to simplify store package

feat(create-mud): infer recs components from config (#1278) (opens in a new tab) (@latticexyz/cli, @latticexyz/std-client, @latticexyz/store-sync, @latticexyz/store, @latticexyz/world, create-mud)

RECS components are now dynamically created and inferred from your MUD config when using syncToRecs.

To migrate existing projects after upgrading to this MUD version:

  1. Remove contractComponents.ts from client/src/mud

  2. Remove components argument from syncToRecs

  3. Update build:mud and dev scripts in contracts/package.json to remove tsgen

    - "build:mud": "mud tablegen && mud worldgen && mud tsgen --configPath mud.config.ts --out ../client/src/mud",
    + "build:mud": "mud tablegen && mud worldgen",
    - "dev": "pnpm mud dev-contracts --tsgenOutput ../client/src/mud",
    + "dev": "pnpm mud dev-contracts",

feat: bump viem to 1.6.0 (#1308) (opens in a new tab) (@latticexyz/block-logs-stream)

  • removes our own getLogs function now that viem's getLogs supports using multiple events per RPC call.
  • removes isNonPendingBlock and isNonPendingLog helpers now that viem narrows Block and Log types based on inputs
  • simplifies groupLogsByBlockNumber types and tests

feat(dev-tools): use new sync stack (#1284) (opens in a new tab) (@latticexyz/dev-tools, create-mud)

MUD dev tools is updated to latest sync stack. You must now pass in all of its data requirements rather than relying on magic globals.

import { mount as mountDevTools } from "@latticexyz/dev-tools";
 
- mountDevTools();
+ mountDevTools({
+   config,
+   publicClient,
+   walletClient,
+   latestBlock$,
+   blockStorageOperations$,
+   worldAddress,
+   worldAbi,
+   write$,
+   // if you're using recs
+   recsWorld,
+ });

It's also advised to wrap dev tools so that it is only mounted during development mode. Here's how you do this with Vite:

// https://vitejs.dev/guide/env-and-mode.html
if (import.meta.env.DEV) {
  mountDevTools({ ... });
}

Minor changes

feat(dev-tools): use new sync stack (#1284) (opens in a new tab) (@latticexyz/common)

createContract now has an onWrite callback so you can observe writes. This is useful for wiring up the transanction log in MUD dev tools.

import { createContract, ContractWrite } from "@latticexyz/common";
import { Subject } from "rxjs";
 
const write$ = new Subject<ContractWrite>();
creactContract({
  ...
  onWrite: (write) => write$.next(write),
});

feat: bump viem to 1.6.0 (#1308) (opens in a new tab) (@latticexyz/common)

  • adds defaultPriorityFee to mudFoundry for better support with MUD's default anvil config and removes workaround in createContract
  • improves nonce error detection using viem's custom errors

feat(store-sync,store-indexer): consolidate sync logic, add syncToSqlite (#1240) (opens in a new tab) (@latticexyz/dev-tools, @latticexyz/store-indexer, @latticexyz/store-sync)

Store sync logic is now consolidated into a createStoreSync function exported from @latticexyz/store-sync. This simplifies each storage sync strategy to just a simple wrapper around the storage adapter. You can now sync to RECS with syncToRecs or SQLite with syncToSqlite and PostgreSQL support coming soon.

There are no breaking changes if you were just using syncToRecs from @latticexyz/store-sync or running the sqlite-indexer binary from @latticexyz/store-indexer.

feat(dev-tools): use new sync stack (#1284) (opens in a new tab) (@latticexyz/react)

Adds a usePromise hook that returns a native PromiseSettledResult object (opens in a new tab).

const promise = fetch(url);
const result = usePromise(promise);
 
if (result.status === "idle" || result.status === "pending") {
  return <>fetching</>;
}
 
if (result.status === "rejected") {
  return <>error fetching: {String(result.reason)}</>;
}
 
if (result.status === "fulfilled") {
  return <>fetch status: {result.value.status}</>;
}

Patch changes

feat: bump viem to 1.6.0 (#1308) (opens in a new tab) (@latticexyz/block-logs-stream, @latticexyz/common, @latticexyz/dev-tools, @latticexyz/network, @latticexyz/protocol-parser, @latticexyz/schema-type, @latticexyz/std-client, @latticexyz/store-indexer, @latticexyz/store-sync, create-mud)

bump viem to 1.6.0

feat(dev-tools): improve support for non-store recs components (#1302) (opens in a new tab) (@latticexyz/dev-tools, @latticexyz/store-sync)

Improves support for internal/client-only RECS components

feat: bump viem to 1.6.0 (#1308) (opens in a new tab) (@latticexyz/store-sync)

remove usages of isNonPendingBlock and isNonPendingLog (fixed with more specific viem types)


Version 2.0.0-next.1

Major changes

chore: fix changeset type (#1220) (opens in a new tab) (@latticexyz/store-indexer, @latticexyz/store-sync)

Adds store indexer service package with utils to query the indexer service.

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) (opens in a new tab) (@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 (opens in a new tab). 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 (opens in a new tab)-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 (opens in a new tab) and let us know if we missed anything.

  1. 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)

  2. 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];
  3. 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,
    + };
  4. 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,
    + };
  5. 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);
         };
  6. (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) (opens in a new tab) (@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) (opens in a new tab) (@latticexyz/common)

Add utils for using viem with MUD

  • createContract is a wrapper around viem's getContract (opens in a new tab) 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) (opens in a new tab) (@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) (opens in a new tab) (@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) (opens in a new tab) (@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) (opens in a new tab) (@latticexyz/schema-type)

add type narrowing isStaticAbiType

feat(common): move zero gas fee override to createContract (#1266) (opens in a new tab) (@latticexyz/common)

Patch changes

fix(cli): add support for legacy transactions in deploy script (#1178) (opens in a new tab) (@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) (opens in a new tab) (@latticexyz/services)

protocol-parser in Go

refactor(store): optimize Storage library (#1194) (opens in a new tab) (@latticexyz/store)

Optimize storage library

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

  • Remove need for tx queue in createContract

feat(store-sync): add block numbers to SyncProgress (#1228) (opens in a new tab) (@latticexyz/store-sync)

Adds latestBlockNumber and lastBlockNumberProcessed to internal SyncProgress component

feat(store-sync): sync to RECS (#1197) (opens in a new tab) (@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) (opens in a new tab) (@latticexyz/store)

Align Store events parameter naming between IStoreWrite and StoreCore

fix(cli): explicit import of world as type (#1206) (opens in a new tab) (@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) (opens in a new tab) (@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) (opens in a new tab) (@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) (opens in a new tab) (@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) (opens in a new tab) (@latticexyz/common, @latticexyz/store, @latticexyz/world)

  • Refactor tightcoder to use typescript functions instead of ejs
  • Optimize TightCoder library
  • Add isLeftAligned and getLeftPaddingBits common codegen helpers

Version 2.0.0-next.0

Minor changes

feat(store-sync): add store sync package (#1075) (opens in a new tab) (@latticexyz/block-logs-stream, @latticexyz/protocol-parser, @latticexyz/store-sync, @latticexyz/store)

Add store sync package

feat(protocol-parser): add abiTypesToSchema (#1100) (opens in a new tab) (@latticexyz/protocol-parser)

feat: add abiTypesToSchema, a util to turn a list of abi types into a Schema by separating static and dynamic types

chore(protocol-parser): add changeset for #1099 (#1111) (opens in a new tab) (@latticexyz/protocol-parser)

feat: add encodeKeyTuple, a util to encode key tuples in Typescript (equivalent to key tuple encoding in Solidity and inverse of decodeKeyTuple). Example:

encodeKeyTuple({ staticFields: ["uint256", "int32", "bytes16", "address", "bool", "int8"], dynamicFields: [] }, [
  42n,
  -42,
  "0x12340000000000000000000000000000",
  "0xFFfFfFffFFfffFFfFFfFFFFFffFFFffffFfFFFfF",
  true,
  3,
]);
// [
//  "0x000000000000000000000000000000000000000000000000000000000000002a",
//  "0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffd6",
//  "0x1234000000000000000000000000000000000000000000000000000000000000",
//  "0x000000000000000000000000ffffffffffffffffffffffffffffffffffffffff",
//  "0x0000000000000000000000000000000000000000000000000000000000000001",
//  "0x0000000000000000000000000000000000000000000000000000000000000003",
// ]

feat(store-sync): rework blockLogsToStorage (#1176) (opens in a new tab) (@latticexyz/block-logs-stream, @latticexyz/store-sync)

  • Replace blockEventsToStorage with blockLogsToStorage that exposes a storeOperations callback to perform database writes from store operations. This helps encapsulates database adapters into a single wrapper/instance of blockLogsToStorage and allows for wrapping a block of store operations in a database transaction.
  • Add toBlock option to groupLogsByBlockNumber and remove blockHash from results. This helps track the last block number for a given set of logs when used in the context of RxJS streams.

feat(block-logs-stream): add block logs stream package (#1070) (opens in a new tab) (@latticexyz/block-logs-stream)

Add block logs stream package

import { filter, map, mergeMap } from "rxjs";
import { createPublicClient, parseAbi } from "viem";
import {
  createBlockStream,
  isNonPendingBlock,
  groupLogsByBlockNumber,
  blockRangeToLogs,
} from "@latticexyz/block-logs-stream";
 
const publicClient = createPublicClient({
  // your viem public client config here
});
 
const latestBlock$ = await createBlockStream({ publicClient, blockTag: "latest" });
 
const latestBlockNumber$ = latestBlock$.pipe(
  filter(isNonPendingBlock),
  map((block) => block.number)
);
 
latestBlockNumber$
  .pipe(
    map((latestBlockNumber) => ({ startBlock: 0n, endBlock: latestBlockNumber })),
    blockRangeToLogs({
      publicClient,
      address,
      events: parseAbi([
        "event StoreDeleteRecord(bytes32 table, bytes32[] key)",
        "event StoreSetField(bytes32 table, bytes32[] key, uint8 schemaIndex, bytes data)",
        "event StoreSetRecord(bytes32 table, bytes32[] key, bytes data)",
        "event StoreEphemeralRecord(bytes32 table, bytes32[] key, bytes data)",
      ]),
    }),
    mergeMap(({ logs }) => from(groupLogsByBlockNumber(logs)))
  )
  .subscribe((block) => {
    console.log("got events for block", block);
  });

feat(gas-report): create package, move relevant files to it (#1147) (opens in a new tab) (@latticexyz/cli, @latticexyz/gas-report, @latticexyz/store)

Create gas-report package, move gas-report cli command and GasReporter contract to it

refactor(store,world): replace isStore with storeAddress (#1061) (opens in a new tab) (@latticexyz/std-contracts, @latticexyz/store, @latticexyz/world)

Rename MudV2Test to MudTest and move from @latticexyz/std-contracts to @latticexyz/store.

// old import
import { MudV2Test } from "@latticexyz/std-contracts/src/test/MudV2Test.t.sol";
// new import
import { MudTest } from "@latticexyz/store/src/MudTest.sol";

Refactor StoreSwitch to use a storage slot instead of function isStore() to determine which contract is Store:

  • Previously StoreSwitch called isStore() on msg.sender to determine if msg.sender is a Store contract. If the call succeeded, the Store methods were called on msg.sender, otherwise the data was written to the own storage.
  • With this change StoreSwitch instead checks for an address in a known storage slot. If the address equals the own address, data is written to the own storage. If it is an external address, Store methods are called on this address. If it is unset (address(0)), store methods are called on msg.sender.
  • In practice this has the same effect as before: By default the World contracts sets its own address in StoreSwitch, while System contracts keep the Store address undefined, so Systems write to their caller (World) if they are executed via call or directly to the World storage if they are executed via delegatecall.
  • Besides gas savings, this change has two additional benefits:
    1. it is now possible for Systems to explicitly set a Store address to make them exclusive to that Store and
    2. table libraries can now be used in tests without having to provide an explicit Store argument, because the MudTest base contract redirects reads and writes to the internal World contract.

feat(store-sync): sync to sqlite (#1185) (opens in a new tab) (@latticexyz/store-sync)

blockLogsToStorage(sqliteStorage(...)) converts block logs to SQLite operations. You can use it like:

import { drizzle } from "drizzle-orm/better-sqlite3";
import Database from "better-sqlite3";
import { BaseSQLiteDatabase } from "drizzle-orm/sqlite-core";
import { createPublicClient } from "viem";
import { blockLogsToStorage } from "@latticexyz/store-sync";
import { sqliteStorage } from "@latticexyz/store-sync/sqlite";
 
const database = drizzle(new Database('store.db')) as any as BaseSQLiteDatabase<"sync", void>;
const publicClient = createPublicClient({ ... });
 
blockLogs$
  .pipe(
    concatMap(blockLogsToStorage(sqliteStorage({ database, publicClient }))),
    tap(({ blockNumber, operations }) => {
      console.log("stored", operations.length, "operations for block", blockNumber);
    })
  )
  .subscribe();

feat(common): new utils, truncate table ID parts (#1173) (opens in a new tab) (@latticexyz/common)

TableId.toHex() now truncates name/namespace to 16 bytes each, to properly fit into a bytes32 hex string.

Also adds a few utils we'll need in the indexer:

  • bigIntMin is similar to Math.min but for bigints
  • bigIntMax is similar to Math.max but for bigints
  • bigIntSort for sorting an array of bigints
  • chunk to split an array into chunks
  • wait returns a Promise that resolves after specified number of milliseconds

feat(cli): update set-version to match new release structure, add --tag, --commit (#1157) (opens in a new tab) (@latticexyz/cli)

  • update the set-version cli command to work with the new release process by adding two new options:
    • --tag: install the latest version of the given tag. For snapshot releases tags correspond to the branch name, commits to main result in an automatic snapshot release, so --tag main is equivalent to what used to be -v canary
    • --commit: install a version based on a given commit hash. Since commits from main result in an automatic snapshot release it works for all commits on main, and it works for manual snapshot releases from branches other than main
  • set-version now updates all package.json nested below the current working directory (expect node_modules), so no need for running it each workspace of a monorepo separately.

Example:

pnpm mud set-version --tag main && pnpm install
pnpm mud set-version --commit db19ea39 && pnpm install

Patch changes

fix(protocol-parser): properly decode empty records (#1177) (opens in a new tab) (@latticexyz/protocol-parser)

decodeRecord now properly decodes empty records

refactor(store): clean up Memory, make mcopy pure (#1153) (opens in a new tab) (@latticexyz/cli, @latticexyz/common, @latticexyz/store, @latticexyz/world)

Clean up Memory.sol, make mcopy pure

fix(recs): improve messages for v2 components (#1167) (opens in a new tab) (@latticexyz/recs)

improve RECS error messages for v2 components

test: bump forge-std and ds-test (#1168) (opens in a new tab) (@latticexyz/cli, @latticexyz/gas-report, @latticexyz/noise, @latticexyz/schema-type, @latticexyz/solecs, @latticexyz/std-contracts, @latticexyz/store, @latticexyz/world, create-mud)

bump forge-std and ds-test dependencies

fix(schema-type): fix byte lengths for uint64/int64 (#1175) (opens in a new tab) (@latticexyz/schema-type)

Fix byte lengths for uint64 and int64.

build: bump TS (#1165) (opens in a new tab) (@latticexyz/cli, create-mud, @latticexyz/utils, @latticexyz/world)

bump to latest TS version (5.1.6)

build: bump viem, abitype (#1179) (opens in a new tab) (@latticexyz/block-logs-stream, @latticexyz/cli, @latticexyz/common, @latticexyz/dev-tools, @latticexyz/network, @latticexyz/protocol-parser, @latticexyz/schema-type, @latticexyz/std-client, @latticexyz/store-cache, @latticexyz/store-sync, @latticexyz/store)

  • bump to viem 1.3.0 and abitype 0.9.3
  • move @wagmi/chains imports to viem/chains
  • refine a few types

test(e2e): add more test cases (#1074) (opens in a new tab) (@latticexyz/services)

fix a bug related to encoding negative bigints in MODE

fix: remove devEmit when sending events from SyncWorker (#1109) (opens in a new tab) (@latticexyz/network)

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