World
Modules

Modules

Modules are onchain installation scripts that create resources and their associated configuration when called by a World. This is somewhat similar to one of the use cases for foundry scripts (opens in a new tab), except that modules are deployed onchain and can be used by any World on the same chain.

Module installation

The easiest way to install modules is to edit the config file.

For example, here is a modified config file that installs the ERC-721 module. Note that you also need to install the viem package in packages/contracts to use it.

mud.config.ts
import { defineWorld } from "@latticexyz/world";
import { encodeAbiParameters } from "viem";
 
const erc721ModuleArgs = encodeAbiParameters(
  [
    { type: "bytes14" },
    {
      type: "tuple",
      components: [{ type: "string" }, { type: "string" }, { type: "string" }],
    },
  ],
  ["0x44444444".padEnd(30, "0"), ["No Valuable Token", "NVT", "http://www.example.com/base/uri/goes/here"]],
);
 
export default defineWorld({
  namespace: "app",
  tables: {
    Counter: {
      schema: {
        value: "uint32",
      },
      key: [],
    },
  },
  modules: [
    {
      artifactPath: "@latticexyz/world-modules/out/PuppetModule.sol/PuppetModule.json",
      root: false,
      args: [],
    },
    {
      artifactPath: "@latticexyz/world-modules/out/ERC721Module.sol/ERC721Module.json",
      root: false,
      args: [
        {
          type: "bytes",
          value: erc721ModuleArgs,
        },
      ],
    },
  ],
});
Explanation
import { encodeAbiParameters } from "viem";

In simple cases it is enough to use the config parser to specify the module arguments. However, the NFT module requires a struct as one of the arguments (opens in a new tab). We use encodeAbiParameters (opens in a new tab) to encode the struct data.

Note that this means we need to issue pnpm install viem in packages/contracts to be able to use the library here.

const erc721ModuleArgs = encodeAbiParameters(

You can see the arguments for the ERC-721 module here (opens in a new tab). There are two arguments:

However, the arguments for a module are ABI encoded (opens in a new tab) to a single value of type bytes. So we use encodeAbiParameters from the viem library to create this argument. The first parameter of this function is a list of argument types.

  [
    { type: "bytes14" },

The first parameter is simple, a 14 byte value for the namespace.

    {
      type: "tuple",
      components: [{ type: "string" }, { type: "string" }, { type: "string" }],
    },
  ],

The second value is more complicated, it's a struct, or as it is called in ABI, a tuple. It consists of three strings (the token name, symbol, and base URI (opens in a new tab)).

  [
    "0x44444444".padEnd(30, "0"),

The second encodeAbiParameters parameter is a list of the values, of the types declared in the first list.

The first parameter for the module is bytes14, which is expected to be a hexadecimal value with twenty-eight hexadecimal digits, for a total length of thirty. Here we use 0x4...40....0 with eight 4's followed by twenty 0's. This gives us the namespace DDDD, which is easy to recognize both as hex and as text.

    ["No Valuable Token", "NVT", "http://www.example.com/base/uri/goes/here"],
  ],
);

The second parameter for the module is a structure of three strings, so here we provide the three strings. Then we close all the definitions.

  modules: [
    {
      artifactPath: "@latticexyz/world-modules/out/PuppetModule.sol/PuppetModule.json",
      root: false,
      args: [],
    },

A module declaration requires three parameters:

  • artifactPath, a link to the compiled JSON file for the module.
  • root, whether to install the module with root namespace permissions or not.
  • args the module arguments.

Here we install the puppet module (opens in a new tab). We need this module because a System is supposed to be stateless, and easily upgradeable to a contract in a different address. However, both the ERC-20 standard (opens in a new tab) and the ERC-721 standard (opens in a new tab) require the token contract to emit events. The solution is to put the System in one contract and have another contract, the puppet, which receives requests and emits events according to the ERC.

    {
      artifactPath: "@latticexyz/world-modules/out/ERC721Module.sol/ERC721Module.json",
      root: false,
      args: [
        {
          type: "bytes",

The data type for this parameter is bytes, because it is treated as opaque bytes by the World and only gets parsed by the module after it is transferred.

          value: erc721ModuleArgs,
        },
      ],
    },

The module arguments, stored in erc721ModuleArgs.

Installation by script

Modules can be installed using World.installModule(address moduleAddress, bytes memory initData) (opens in a new tab). When you do this, the World calls the module's install function with initData as the argument(s). Because this is a call, the module does not have any administrative permissions on the World.

Alternatively, the owner of the root namespace can install modules using World.installRootModule(address moduleAddress, bytes memory initData) (opens in a new tab). In this case, the World uses delegatecall and module has all the permissions of a System in the root namespace.

For example, here is an installation script for the KeysWithValue module.

DeployKeyWithValueModule.s.sol
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.21;
 
import { Script } from "forge-std/Script.sol";
import { console } from "forge-std/console.sol";
 
import { IWorld } from "../src/codegen/world/IWorld.sol";
import { WorldResourceIdLib, WorldResourceIdInstance } from "@latticexyz/world/src/WorldResourceId.sol";
import { RESOURCE_TABLE } from "@latticexyz/world/src/worldResourceTypes.sol";
import { ResourceId } from "@latticexyz/store/src/ResourceId.sol";
import { KeysWithValueModule } from "@latticexyz/world-modules/src/modules/keyswithvalue/KeysWithValueModule.sol";
 
contract DeployKeyWithValueModule is Script {
  function run() external {
    uint256 deployerPrivateKey = vm.envUint("PRIVATE_KEY");
    address worldAddress = 0xC14fBdb7808D9e2a37c1a45b635C8C3fF64a1cc1;
 
    vm.startBroadcast(deployerPrivateKey);
    IWorld world = IWorld(worldAddress);
 
    // Deploy the module
    KeysWithValueModule keysWithValueModule = new KeysWithValueModule();
    ResourceId sourceTableId = WorldResourceIdLib.encode({ typeId: RESOURCE_TABLE, namespace: "", name: "Tasks" });
    world.installRootModule(keysWithValueModule, abi.encode(sourceTableId));
 
    vm.stopBroadcast();
  }
}
Explanation
    KeysWithValueModule keysWithValueModule = new KeysWithValueModule();

Deploy the module. Modules are stateless, so if there is already a copy of the contract on the blockchain you can just use that.

    ResourceId sourceTableId =
       WorldResourceIdLib.encode({ typeId: RESOURCE_TABLE, namespace: "", name: "Tasks" });

Get the resourceID for the table that needs a reverse index.

    world.installRootModule(keysWithValueModule, abi.encode(sourceTableId));

Actually install the module in the World.

Writing modules

The common use for a module is to add functionality to a World. In most cases we expect that a module would:

  1. Create a namespace for the new functionality.
  2. Create the tables and Systems for the new functionality.
  3. Create any access permissions required (beyond the default, which is that a System has access to its own namespace).
  4. Either assign the ownership of the new namespace to an entity that would administer it (a user, a multisig, etc.) or burn it by assigning the namespace ownership to address(0).

Root modules run with the same permission as Systems in the root namespace, so they do not need to create a namespace for themselves. They can just create their own tables and Systems as needed.

For more information about writing modules see the detailed guide.

Sample modules

MUD comes with several modules you can use or inspect to help you write your own:

UpgradingKeys with Value