diff --git a/packages/world/src/modules/core/CoreModule.sol b/packages/world/src/modules/core/CoreModule.sol index 5137adaa96..21b27ed620 100644 --- a/packages/world/src/modules/core/CoreModule.sol +++ b/packages/world/src/modules/core/CoreModule.sol @@ -35,33 +35,47 @@ import { StoreRegistrationSystem } from "./implementations/StoreRegistrationSyst import { WorldRegistrationSystem } from "./implementations/WorldRegistrationSystem.sol"; /** - * The CoreModule registers internal World tables, the CoreSystem, and its function selectors. - - * Note: - * This module only supports `installRoot` (via `World.registerRootSystem`), - * because it needs to install root tables, systems and function selectors. + * @title Core Module + * @notice Registers internal World tables, the CoreSystem, and its function selectors. + * @dev This module only supports `installRoot` because it installs root tables, systems and function selectors. */ + contract CoreModule is Module { - // Since the CoreSystem only exists once per World and writes to - // known tables, we can deploy it once and register it in multiple Worlds. + /** + * @dev Since the CoreSystem only exists once per World and writes to + * known tables, we can deploy it once and register it in multiple Worlds. + */ address immutable coreSystem = address(new CoreSystem()); + /** + * @notice Get the name of the module. + * @return Module name as bytes16. + */ function getName() public pure returns (bytes16) { return CORE_MODULE_NAME; } + /** + * @notice Root installation of the module. + * @dev Registers core tables, systems, and function selectors in the World. + */ function installRoot(bytes memory) public override { _registerCoreTables(); _registerCoreSystem(); _registerFunctionSelectors(); } + /** + * @notice Non-root installation of the module. + * @dev Installation is only supported at root level, so this function will always revert. + */ function install(bytes memory) public pure { revert Module_NonRootInstallNotSupported(); } /** - * Register core tables in the World + * @notice Register core tables in the World. + * @dev This internal function registers various tables and sets initial permissions. */ function _registerCoreTables() internal { StoreCore.registerCoreTables(); @@ -86,10 +100,10 @@ contract CoreModule is Module { } /** - * Register the CoreSystem in the World + * @notice Register the CoreSystem in the World. + * @dev Uses the CoreSystem's `registerSystem` implementation to register itself on the World. */ function _registerCoreSystem() internal { - // Use the CoreSystem's `registerSystem` implementation to register itself on the World. WorldContextProvider.delegatecallWithContextOrRevert({ msgSender: _msgSender(), msgValue: 0, @@ -99,7 +113,8 @@ contract CoreModule is Module { } /** - * Register function selectors for all CoreSystem functions in the World + * @notice Register function selectors for all CoreSystem functions in the World. + * @dev Iterates through known function signatures and registers them. */ function _registerFunctionSelectors() internal { string[19] memory functionSignatures = [ diff --git a/packages/world/src/modules/core/CoreSystem.sol b/packages/world/src/modules/core/CoreSystem.sol index cfee17d1d2..babcec3b69 100644 --- a/packages/world/src/modules/core/CoreSystem.sol +++ b/packages/world/src/modules/core/CoreSystem.sol @@ -11,8 +11,9 @@ import { StoreRegistrationSystem } from "./implementations/StoreRegistrationSyst import { WorldRegistrationSystem } from "./implementations/WorldRegistrationSystem.sol"; /** - * The CoreSystem includes all World functionality that is externalized - * from the World contract to keep the World contract's bytecode as lean as possible. + * @title Core System for World + * @notice This system aggregates all World functionalities externalized from the World contract, aiming to keep the World contract's bytecode lean. + * @dev Aggregates multiple system implementations for the World. */ contract CoreSystem is IWorldErrors, @@ -23,5 +24,4 @@ contract CoreSystem is StoreRegistrationSystem, WorldRegistrationSystem { - } diff --git a/packages/world/src/modules/core/constants.sol b/packages/world/src/modules/core/constants.sol index e228f9d3bf..2673e1ae76 100644 --- a/packages/world/src/modules/core/constants.sol +++ b/packages/world/src/modules/core/constants.sol @@ -6,8 +6,16 @@ import { ResourceId } from "@latticexyz/store/src/ResourceId.sol"; import { ROOT_NAMESPACE } from "../../constants.sol"; import { RESOURCE_SYSTEM } from "../../worldResourceTypes.sol"; +/** + * @dev Name of the core module. + * @dev Represented as a bytes16 constant. + */ bytes16 constant CORE_MODULE_NAME = bytes16("core"); +/** + * @dev Resource ID for the core system. + * @dev This ID is derived from the RESOURCE_SYSTEM type, the ROOT_NAMESPACE, and the CORE_MODULE_NAME. + */ ResourceId constant CORE_SYSTEM_ID = ResourceId.wrap( bytes32(abi.encodePacked(RESOURCE_SYSTEM, ROOT_NAMESPACE, CORE_MODULE_NAME)) ); diff --git a/packages/world/src/modules/core/implementations/AccessManagementSystem.sol b/packages/world/src/modules/core/implementations/AccessManagementSystem.sol index f259b944c0..4d5503f5e1 100644 --- a/packages/world/src/modules/core/implementations/AccessManagementSystem.sol +++ b/packages/world/src/modules/core/implementations/AccessManagementSystem.sol @@ -10,12 +10,15 @@ import { InstalledModules } from "../../../codegen/tables/InstalledModules.sol"; import { NamespaceOwner } from "../../../codegen/tables/NamespaceOwner.sol"; /** - * Granting and revoking access from/to resources. + * @title Access Management System + * @dev This contract manages the granting and revoking of access from/to resources. */ contract AccessManagementSystem is System { /** - * Grant access to the resource at the given resource ID. - * Requires the caller to own the namespace. + * @notice Grant access to the resource at the given resource ID. + * @dev Requires the caller to own the namespace. + * @param resourceId The ID of the resource to grant access to. + * @param grantee The address to which access should be granted. */ function grantAccess(ResourceId resourceId, address grantee) public virtual { // Require the caller to own the namespace @@ -26,8 +29,10 @@ contract AccessManagementSystem is System { } /** - * Revoke access from the resource at the given resource ID. - * Requires the caller to own the namespace. + * @notice Revoke access from the resource at the given resource ID. + * @dev Requires the caller to own the namespace. + * @param resourceId The ID of the resource to revoke access from. + * @param grantee The address from which access should be revoked. */ function revokeAccess(ResourceId resourceId, address grantee) public virtual { // Require the caller to own the namespace @@ -38,9 +43,10 @@ contract AccessManagementSystem is System { } /** - * Transfer ownership of the given namespace to newOwner. - * Revoke ResourceAccess for previous owner and grant to newOwner. - * Requires the caller to own the namespace. + * @notice Transfer ownership of the given namespace to newOwner and manages the access. + * @dev Requires the caller to own the namespace. Revoke ResourceAccess for previous owner and grant to newOwner. + * @param namespaceId The ID of the namespace to transfer ownership. + * @param newOwner The address to which ownership should be transferred. */ function transferOwnership(ResourceId namespaceId, address newOwner) public virtual { // Require the caller to own the namespace diff --git a/packages/world/src/modules/core/implementations/BalanceTransferSystem.sol b/packages/world/src/modules/core/implementations/BalanceTransferSystem.sol index fedf89a93e..b2c4163528 100644 --- a/packages/world/src/modules/core/implementations/BalanceTransferSystem.sol +++ b/packages/world/src/modules/core/implementations/BalanceTransferSystem.sol @@ -12,12 +12,20 @@ import { IWorldErrors } from "../../../IWorldErrors.sol"; import { Balances } from "../../../codegen/tables/Balances.sol"; +/** + * @title Balance Transfer System + * @dev A system contract that facilitates balance transfers in the World and outside of the World. + */ contract BalanceTransferSystem is System, IWorldErrors { using ResourceIdInstance for ResourceId; using WorldResourceIdInstance for ResourceId; /** - * Transfer balance to another namespace in the World + * @notice Transfer balance to another namespace in the World. + * @dev Requires the caller to have access to the source namespace and ensures the destination namespace type is valid. + * @param fromNamespaceId The source namespace from which the balance will be deducted. + * @param toNamespaceId The target namespace where the balance will be added. + * @param amount The amount to transfer. */ function transferBalanceToNamespace( ResourceId fromNamespaceId, @@ -44,7 +52,11 @@ contract BalanceTransferSystem is System, IWorldErrors { } /** - * Transfer balance out of the World + * @notice Transfer balance out of the World to a specific address. + * @dev Requires the caller to have access to the source namespace and ensures sufficient balance before transfer. + * @param fromNamespaceId The source namespace from which the balance will be deducted. + * @param toAddress The target address where the balance will be sent. + * @param amount The amount to transfer. */ function transferBalanceToAddress(ResourceId fromNamespaceId, address toAddress, uint256 amount) public virtual { // Require caller to have access to the namespace diff --git a/packages/world/src/modules/core/implementations/BatchCallSystem.sol b/packages/world/src/modules/core/implementations/BatchCallSystem.sol index e7bc1d0141..3378714eab 100644 --- a/packages/world/src/modules/core/implementations/BatchCallSystem.sol +++ b/packages/world/src/modules/core/implementations/BatchCallSystem.sol @@ -7,9 +7,16 @@ import { revertWithBytes } from "../../../revertWithBytes.sol"; import { SystemCallData, SystemCallFromData } from "../types.sol"; +/** + * @title Batch Call System + * @dev A system contract that facilitates batching of calls to various systems in a single transaction. + */ contract BatchCallSystem is System { /** - * Batch calls to multiple systems into a single transaction, return the array of return data. + * @notice Make batch calls to multiple systems into a single transaction. + * @dev Iterates through an array of system calls, executes them, and returns an array of return data. + * @param systemCalls An array of SystemCallData that contains systemId and callData for each call. + * @return returnDatas An array of bytes containing the return data for each system call. */ function batchCall(SystemCallData[] calldata systemCalls) public returns (bytes[] memory returnDatas) { IBaseWorld world = IBaseWorld(_world()); @@ -26,7 +33,10 @@ contract BatchCallSystem is System { } /** - * Batch calls to multiple systems into a single transaction, return the array of return data. + * @notice Make batch calls from specific addresses to multiple systems in a single transaction. + * @dev Iterates through an array of system calls with specified 'from' addresses, executes them, and returns an array of return data. + * @param systemCalls An array of SystemCallFromData that contains from, systemId, and callData for each call. + * @return returnDatas An array of bytes containing the return data for each system call. */ function batchCallFrom(SystemCallFromData[] calldata systemCalls) public returns (bytes[] memory returnDatas) { IBaseWorld world = IBaseWorld(_world()); diff --git a/packages/world/src/modules/core/implementations/ModuleInstallationSystem.sol b/packages/world/src/modules/core/implementations/ModuleInstallationSystem.sol index 69fa9f3fbb..af77bc3759 100644 --- a/packages/world/src/modules/core/implementations/ModuleInstallationSystem.sol +++ b/packages/world/src/modules/core/implementations/ModuleInstallationSystem.sol @@ -10,11 +10,16 @@ import { InstalledModules } from "../../../codegen/tables/InstalledModules.sol"; import { requireInterface } from "../../../requireInterface.sol"; /** - * Installation of (non-root) modules in the World. + * @title Module Installation System + * @dev A system contract to handle the installation of (non-root) modules in the World. */ contract ModuleInstallationSystem is System { /** - * Install the given module at the given namespace in the World. + * @notice Installs a module into the World under a specified namespace. + * @dev Validates the given module against the IModule interface and delegates the installation process. + * The module is then registered in the InstalledModules table. + * @param module The module to be installed. + * @param args Arguments for the module installation. */ function installModule(IModule module, bytes memory args) public { // Require the provided address to implement the IModule interface diff --git a/packages/world/src/modules/core/implementations/StoreRegistrationSystem.sol b/packages/world/src/modules/core/implementations/StoreRegistrationSystem.sol index 77fcbad182..633e377fa6 100644 --- a/packages/world/src/modules/core/implementations/StoreRegistrationSystem.sol +++ b/packages/world/src/modules/core/implementations/StoreRegistrationSystem.sol @@ -29,13 +29,22 @@ import { CORE_SYSTEM_ID } from "../constants.sol"; import { WorldRegistrationSystem } from "./WorldRegistrationSystem.sol"; /** - * Functions related to registering table resources in the World. + * @title Store Registration System + * @dev This contract provides functionality for the registration of store-related resources within the World framework. */ contract StoreRegistrationSystem is System, IWorldErrors { using WorldResourceIdInstance for ResourceId; /** - * Register a table with the given config + * @notice Register a table within the World framework. + * @dev Registers a table with the specified configuration. If the namespace for the table does not exist, it's created. + * Existing namespaces require the caller to be the owner for table registration. + * @param tableId The resource ID of the table. + * @param fieldLayout The field layout structure for the table. + * @param keySchema The schema for the keys of the table. + * @param valueSchema The schema for the values within the table. + * @param keyNames The names associated with the keys in the table. + * @param fieldNames The names of the fields in the table. */ function registerTable( ResourceId tableId, @@ -68,9 +77,14 @@ contract StoreRegistrationSystem is System, IWorldErrors { } /** - * Register a hook for the given tableId. - * Requires the caller to own the namespace. + * @notice Register a storage hook for a specified table. + * @dev The caller must be the owner of the namespace to which the table belongs. + * The hook must conform to the IStoreHook interface. + * @param tableId The resource ID of the table for which the hook is being registered. + * @param hookAddress The address of the storage hook contract. + * @param enabledHooksBitmap A bitmap indicating which hooks are enabled. */ + function registerStoreHook(ResourceId tableId, IStoreHook hookAddress, uint8 enabledHooksBitmap) public virtual { // Require the hook to implement the store hook interface requireInterface(address(hookAddress), STORE_HOOK_INTERFACE_ID); @@ -83,8 +97,10 @@ contract StoreRegistrationSystem is System, IWorldErrors { } /** - * Unregister a hook for the given tableId. - * Requires the caller to own the namespace. + * @notice Unregister a previously registered storage hook for a specified table. + * @dev The caller must be the owner of the namespace to which the table belongs. + * @param tableId The resource ID of the table from which the hook is being unregistered. + * @param hookAddress The address of the storage hook contract. */ function unregisterStoreHook(ResourceId tableId, IStoreHook hookAddress) public virtual { // Require caller to own the namespace diff --git a/packages/world/src/modules/core/implementations/WorldRegistrationSystem.sol b/packages/world/src/modules/core/implementations/WorldRegistrationSystem.sol index 9c969f67db..a4ba0bb614 100644 --- a/packages/world/src/modules/core/implementations/WorldRegistrationSystem.sol +++ b/packages/world/src/modules/core/implementations/WorldRegistrationSystem.sol @@ -29,15 +29,17 @@ import { FunctionSelectors } from "../../../codegen/tables/FunctionSelectors.sol import { FunctionSignatures } from "../../../codegen/tables/FunctionSignatures.sol"; /** - * Functions related to registering resources other than tables in the World. - * Registering tables is implemented in StoreRegistrationSystem.sol + * @title WorldRegistrationSystem + * @dev This contract provides functions related to registering resources other than tables in the World. */ contract WorldRegistrationSystem is System, IWorldErrors { using ResourceIdInstance for ResourceId; using WorldResourceIdInstance for ResourceId; /** - * Register a new namespace + * @notice Registers a new namespace + * @dev Creates a new namespace resource with the given ID + * @param namespaceId The unique identifier for the new namespace */ function registerNamespace(ResourceId namespaceId) public virtual { // Require the provided namespace ID to have type RESOURCE_NAMESPACE @@ -61,7 +63,11 @@ contract WorldRegistrationSystem is System, IWorldErrors { } /** - * Register a hook for the system at the given system ID + * @notice Registers a new system hook + * @dev Adds a new hook for the system at the provided system ID + * @param systemId The ID of the system + * @param hookAddress The address of the hook being registered + * @param enabledHooksBitmap Bitmap indicating which hooks are enabled */ function registerSystemHook(ResourceId systemId, ISystemHook hookAddress, uint8 enabledHooksBitmap) public virtual { // Require the provided address to implement the ISystemHook interface @@ -75,7 +81,10 @@ contract WorldRegistrationSystem is System, IWorldErrors { } /** - * Unregister the given hook for the system at the given system ID + * @notice Unregisters a system hook + * @dev Removes a hook for the system at the provided system ID + * @param systemId The ID of the system + * @param hookAddress The address of the hook being unregistered */ function unregisterSystemHook(ResourceId systemId, ISystemHook hookAddress) public virtual { // Require caller to own the namespace @@ -86,13 +95,17 @@ contract WorldRegistrationSystem is System, IWorldErrors { } /** - * Register the given system in the given namespace. + * @notice Registers a system + * @dev Registers or upgrades a system at the given ID * If the namespace doesn't exist yet, it is registered. - * The system is granted access to its namespace, so it can write to any table in the same namespace. + * The system is granted access to its namespace, so it can write to any + * table in the same namespace. * If publicAccess is true, no access control check is performed for calling the system. - * - * Note: this function doesn't check whether a system already exists at the given selector, + * This function doesn't check whether a system already exists at the given selector, * making it possible to upgrade systems. + * @param systemId The unique identifier for the system + * @param system The system being registered + * @param publicAccess Flag indicating if access control check is bypassed */ function registerSystem(ResourceId systemId, WorldContextConsumer system, bool publicAccess) public virtual { // Require the provided system ID to have type RESOURCE_SYSTEM @@ -149,7 +162,11 @@ contract WorldRegistrationSystem is System, IWorldErrors { } /** - * Register a World function selector for the given namespace, name and system function. + * @notice Registers a new World function selector + * @dev Creates a mapping between a World function and its associated system function + * @param systemId The system ID + * @param systemFunctionSignature The signature of the system function + * @return worldFunctionSelector The selector of the World function */ function registerFunctionSelector( ResourceId systemId, @@ -184,8 +201,12 @@ contract WorldRegistrationSystem is System, IWorldErrors { } /** - * Register a root World function selector (without namespace / name prefix). - * Requires the caller to own the root namespace. + * @notice Registers a root World function selector + * @dev Creates a mapping for a root World function without namespace or name prefix + * @param systemId The system ID + * @param worldFunctionSignature The signature of the World function + * @param systemFunctionSelector The selector of the system function + * @return worldFunctionSelector The selector of the World function */ function registerRootFunctionSelector( ResourceId systemId, @@ -211,7 +232,11 @@ contract WorldRegistrationSystem is System, IWorldErrors { } /** - * Register a delegation from the caller to the given delegatee. + * @notice Registers a delegation for the caller + * @dev Creates a new delegation from the caller to the specified delegatee + * @param delegatee The address of the delegatee + * @param delegationControlId The ID controlling the delegation + * @param initCallData The initialization data for the delegation */ function registerDelegation(address delegatee, ResourceId delegationControlId, bytes memory initCallData) public { // Store the delegation control contract address @@ -237,6 +262,13 @@ contract WorldRegistrationSystem is System, IWorldErrors { } } + /** + * @notice Registers a delegation for a namespace + * @dev Sets up a new delegation control for a specific namespace + * @param namespaceId The ID of the namespace + * @param delegationControlId The ID controlling the delegation + * @param initCallData The initialization data for the delegation + */ function registerNamespaceDelegation( ResourceId namespaceId, ResourceId delegationControlId, diff --git a/packages/world/src/modules/core/types.sol b/packages/world/src/modules/core/types.sol index 8cb71ef19f..4b1692bb0f 100644 --- a/packages/world/src/modules/core/types.sol +++ b/packages/world/src/modules/core/types.sol @@ -3,13 +3,28 @@ pragma solidity >=0.8.21; import { ResourceId } from "@latticexyz/store/src/ResourceId.sol"; +/** + * @title System Call Data Structure + * @notice Holds data for making system calls. + * @dev Used to represent a call to a specific system identified by a ResourceId. + */ struct SystemCallData { + /// @dev The ID of the system to call. ResourceId systemId; + /// @dev The call data to pass to the system function. bytes callData; } +/** + * @title System Call From Data Structure + * @notice Holds data for making system calls with a specific sender. + * @dev Used to represent a call from a specific address to a specific system. + */ struct SystemCallFromData { + /// @dev The address from which the system call is made. address from; + /// @dev The ID of the system to call. ResourceId systemId; + /// @dev The call data to pass to the system function. bytes callData; }