config.mdx

import { Aside } from "../../components/Aside";

Store Config & tablegen Tool

Currently, `tablegen` is only compatible with Foundry, and MUD 2 uses Foundry for testing and building. Hardhat will be available in the future.

The tablegen CLI tool generates libraries for Store tables. It makes it much less error-prone than using the Store low-level API, and comes with typed Solidity APIs when setting and retrieving records.

Using tablegen with the MUD framework

If you are using the MUD framework and have a mud.config.ts file in your project, you can edit your Store config directly in this file! Keep reading from the "Adding Tables" section

Using tablegen without the MUD framework

We are making this process easier, and will not require a MUD config in the future in order to use `tablegen`

A Store config should be named mud.config.ts, and placed at the root of your project (if you are building a mono-repo, put it at the root folder of where your contracts will be, in the same folder as your Foundry config).

This is the minimal config:

import { mudConfig } from "@latticexyz/store/register";

export default mudConfig({
  tables: {}, // an empty config with no tables
});

Generating the tables

To generate the tables, run pnpm mud tablegen in the same folder as the config file.

Adding Tables

Adding a table is done by creating an entry in the table object of the config.

import { mudConfig } from "@latticexyz/store/register";

export default mudConfig({
  tables: {
    MyTable: {
      valueSchema: {
        value: "uint32",
      },
    },
  },
});

The key of the entry is the name of the table, and the value is another object: the table configuration.

The table configuration can have these properties:

directory (optional): a string: which directory to create the table in. the default is tables (in the source directory as defined by the Foundry config; in MUD the default in src, so the default table directory is src/tables)

fileSelector (optional) only used with the World framework: a string: where to create the table in the namespace.

tableIdArgument (optional): bool: whether to create getter and setter functions with the table ID as an argument, this is used to generate a single library to operate on multiple tables with the same key and value structure.

storeArgument (optional): bool: whether to create getter and setter functions with the store address as an argument, this is used to generate a single library to operate on the same table in multiple stores. This adds new functions to the library, doubling the amount of functions created (each getter/setter will comes in a pair of “with storeArgument” and “without storeArgument”)

dataStruct (optional): bool: whether to create getter and setter functions with a data struct.

For 1-column tables it’s false by default. For multi-column tables it’s true by default.

Example of a table library with dataStruct:

// no data struct
MyTable.set(keccak256("some.key"), 1, 12, "foo");
// data struct
MyTable.set(keccak256("some.key"), { field1: 1, field2: 12, stringField: "foo" });

keySchema (optional): an object with keys being the key name, and value being types of the keys. By default, the table will have a single key of type bytes32.

Example:

tables: {
  MyTableWithTwoKeys: {
    valueSchema: {
      value1: "uint32",
      value2: "uint32",
    },
    keySchema: {
      key1: "uint256",
      key2: "string",
    },
  },
}

valueSchema (required): an object with keys being the column name, and value being types from SchemaType

Example:

tables: {
  MyTableWithFourValues: {
    valueSchema: {
      x: "uint32",
      y: "uint32",
      stringField: "string",
      uintArray: "uint256",
    },
  },
}

Shortcut: table with a single column

There is a shortcut to create a table with a uint256 key and a single column in the value schema:

tables: {
  // Create a table with key uint256 and a single column with type address
  CounterTable: "address";
}

Singleton tables

In order to create Singleton tables that do not have keys (and effectively store a single value), you must pass an empty object to the keySchema property

Example:

tables: {
  MySingletonTable: {
    valueSchema: {
      value1: "uint32",
      value2: "uint32",
    },
    keySchema: {},
  },
}

The getter and setter functions will not have a key argument.

User types

tablegen supports Solidity enums as keys and values. They must be defined in your config as enums in the userTypes property of the config:

import { mudConfig } from "@latticexyz/store/register";

export default mudConfig({
  tables: {},
  enums: {
    AnimalType: ["NONE", "DOG", "CAT", "SQUIREL"],
  },
});

You can then use the name of your enum as a string in place of a type from SchemaType

Example:

tables: {
  // Create a table with key uint256 and a single column with type AnimalType
  AnimalTypeTable: "AnimalType";
}