diff --git a/docs/pages/world/modules/erc20.mdx b/docs/pages/world/modules/erc20.mdx index 1da9f6beab..6907306d24 100644 --- a/docs/pages/world/modules/erc20.mdx +++ b/docs/pages/world/modules/erc20.mdx @@ -12,11 +12,13 @@ This module is unaudited and may change in the future. The [`erc20` module](https://github.com/latticexyz/mud/tree/main/packages/world-module-erc20/) lets you create [ERC-20](https://ethereum.org/en/developers/docs/standards/tokens/erc-20/) tokens as part of a MUD `World`. The advantage of doing this, rather than creating a separate [ERC-20 contract](https://github.com/OpenZeppelin/openzeppelin-contracts/tree/master/contracts/token/ERC20) and merely controlling it from MUD, is that all the information is in MUD tables and is immediately available in the client. +The token contract can be seen as a hybrid system contract which contains functions directly callable from outside the world (ERC20 functions like `transfer`, `balanceOf`, etc), and restricted functions that must be called as a system function through the World (`mint`, `pause`, etc). + The ERC20Module receives the namespace, name and symbol of the token as parameters, and deploys the new token. Currently it installs a [default ERC20](https://github.com/latticexyz/mud/tree/main/packages/world-module-erc20/src/examples/ERC20WithWorld.sol) with the following features: - ERC20Burnable: Allows users to burn their tokens (or the ones approved to them) using the `burn` and `burnFrom` function. -- ERC20Pausable: Supports pausing and unpausing token operations. This is combined with the `pause` and `unpause` public functions that can be called by addresses with access to the token's namespace. -- Minting: Addresses with namespace access can call the `mint` function to mint tokens to any address. +- ERC20Pausable: Supports pausing and unpausing token operations. This is combined with the `pause` and `unpause` public functions that can be called by addresses and systems with access to the token's namespace. Must be done through a World call. +- Minting: Addresses and Systems with namespace access can call the `mint` function to mint tokens to any address. This must be done through a World call. ## Installation @@ -58,7 +60,7 @@ For example, run this script. -```solidity filename="ManageERC20.s.sol" copy showLineNumbers {16,34-38,43,48-56} +```solidity filename="ManageERC20.s.sol" copy showLineNumbers {18,36-41,46,51-60} import { Script } from "forge-std/Script.sol"; import { console } from "forge-std/console.sol"; import { StoreSwitch } from "@latticexyz/store/src/StoreSwitch.sol"; @@ -142,12 +144,13 @@ contract ManageERC20 is Script { ResourceId namespaceResource = WorldResourceIdLib.encodeNamespace(bytes14("erc20Namespace")); ResourceId erc20RegistryResource = WorldResourceIdLib.encode(RESOURCE_TABLE, "erc20-module", "ERC20_REGISTRY"); address tokenAddress = ERC20Registry.getTokenAddress(erc20RegistryResource, namespaceResource); + ResourceId tokenSystem = SystemRegistry.get(tokenAddress); console.log("Token address", tokenAddress); ``` -This is the process to get the address of our token contract. +This is the process to get the address of our token contract and the system id of the token. First, we get the [`resourceId` values](/world/resource-ids) for the `erc20-module__ERC20Registry` table and the namespace we are interested in (each namespace can only have one ERC-20 token). -Then we use that table to get the token address. +Then we use that table to get the token address. Finally, we obtain the token system id from the `SystemRegistry` table. ```solidity // Use the token @@ -157,13 +160,15 @@ Then we use that table to get the token address. Cast the token address to an `ERC20` contract so we can call its methods. ```solidity + // Mint some tokens + // We must call the token system (instead of calling mint directly) console.log("Minting for myself"); - erc20.mint(myAddress, 1000); + IWorldCall(worldAddress).call(tokenSystem, abi.encodeCall(ERC20.mint, (myAddress, 1000))); reportBalances(erc20, myAddress); ``` Mint tokens for your address. -Note that only the owner of the name space is authorized to mint tokens. +Note that the mint function must be called through the world as a system function, as it is restricted to entities with access to the token's namespace. ```solidity console.log("Transfering to Alice");