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. You can see an example of this method on the ERC-721 module page.
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.
// 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:
- Create a namespace for the new functionality.
- Create the tables and
System
s for the new functionality. - Create any access permissions required (beyond the default, which is that a
System
has access to its own namespace). - 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 System
s in the root namespace, so they do not need to create a namespace for themselves.
They can just create their own tables and System
s 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:
KeysInTable
(opens in a new tab) - automatically tracks the keys in a table to make them enumerable.KeysWithValue
(opens in a new tab) - automatically tracks a reverse mapping for a table that maps a value hash to a list of keys with this value.Puppet
(opens in a new tab) - installs the PuppetDelegationControl to allow creating Puppet contracts, eg used by the ERC20 and ERC721 modules.ERC20
(opens in a new tab) - installs an ERC20 token into a namespace in a World.ERC721
(opens in a new tab) - installs an ERC721 token into a namespace in a World.UniqueEntity
(opens in a new tab) - add methods to get a unique entity ID.Standard Delegations
(opens in a new tab) - add delegations limited by time or number of calls.