Core Systems

When developing or using autonomous worlds, most of the functionality we interact with is implemented by the core systems within the Mud framework. Their main functions are as follows:

AccessManagementSystem

The Access Management System is used to manage access control for resources in the World. It handles granting and revoking access to resources, as well as transferring and renouncing namespace ownership.

grantAccess

Grants access to a resource for a specific address.

function grantAccess(ResourceId resourceId, address grantee)

  • Requires caller to own the namespace containing the resource

  • resourceId: ID of the resource to grant access to

  • grantee: Address to grant access to

  • Resource must exist

revokeAccess

Revokes access to a resource from a specific address.

function revokeAccess(ResourceId resourceId, address grantee)

  • Requires caller to own the namespace containing the resource

  • resourceId: ID of the resource to revoke access from

  • grantee: Address to revoke access from

transferOwnership

Transfers ownership of a namespace to a new owner.

function transferOwnership(ResourceId namespaceId, address newOwner)

  • Requires caller to own the namespace

  • namespaceId: ID of the namespace to transfer

  • newOwner: Address to transfer ownership to

  • Resource must be a namespace and exist

  • Revokes access from old owner and grants access to new owner

renounceOwnership

Renounces ownership of a namespace, effectively abandoning it.

function renounceOwnership(ResourceId namespaceId)

  • Requires caller to own the namespace

  • namespaceId: ID of the namespace to renounce

  • Resource must be a namespace and exist

  • Removes namespace owner and revokes access from current owner

Important

If the original owner previously granted themselves access to individual system or table resources, changing ownership will not cause them to lose access to these resources. If the new owner wants to prevent this access, they should manually revoke these permissions.

BalanceTransferSystem

The Balance Transfer System facilitates balance transfers both within the World (between namespaces) and from the World to external addresses.

transferBalanceToNamespace

Transfers balance from one namespace to another within the World.

function transferBalanceToNamespace(
  ResourceId fromNamespaceId,
  ResourceId toNamespaceId,
  uint256 amount
)

  • fromNamespaceId: Source namespace to transfer from

  • toNamespaceId: Target namespace to transfer to

  • amount: Amount to transfer

  • Requires caller to have access to source namespace

  • Both namespaces must exist and be valid namespace types

  • Source namespace must have sufficient balance

  • Updates balances of both namespaces

transferBalanceToAddress

Transfers balance from a namespace to an external address.

function transferBalanceToAddress(
  ResourceId fromNamespaceId,
  address toAddress,
  uint256 amount
)

  • fromNamespaceId: Source namespace to transfer from

  • toAddress: Target address to transfer to

  • amount: Amount to transfer

  • Requires caller to have access to source namespace

  • Source namespace must have sufficient balance

  • Updates source namespace balance and transfers funds to target address

  • Reverts if external transfer fails

BatchCallSystem

The Batch Call System enables batching multiple system calls into a single transaction for efficiency. It provides two main functions:

batchCall

Makes multiple system calls in a single transaction.

function batchCall(SystemCallData[] calldata systemCalls) returns (bytes[] memory returnDatas)

  • systemCalls: Array of system calls containing systemId and callData for each call

  • returnDatas: Array of return data bytes from each system call

  • Executes each system call in sequence

  • Reverts entire batch if any call fails

batchCallFrom

Makes multiple system calls from specified addresses in a single transaction.

function batchCallFrom(SystemCallFromData[] calldata systemCalls) returns (bytes[] memory returnDatas)

  • systemCalls: Array of system calls containing from address, systemId and callData for each call

  • returnDatas: Array of return data bytes from each system call

  • Executes each system call in sequence using specified from address

  • Reverts entire batch if any call fails

ModuleInstallationSystem

The Module Installation System handles the installation of non-root modules in the World. It provides functionality to install modules under specific namespaces.

installModule

Installs a non-rootmodule into the World under a specified namespace.

function installModule(IModule module, bytes memory encodedArgs)

  • module: The module contract to be installed

  • encodedArgs: ABI encoded arguments for module installation

  • Validates that module implements IModule interface

  • Registers module in InstalledModules table

Important

The Module Installation System cannot install root modules. Root module installation is implemented by the World contract itself, not the Module Installation System.

StoreRegistrationSystem

The Store Registration System handles registration of tables and store hooks within the World. It provides functionality for registering tables with specific schemas and layouts, as well as managing storage hooks for tables.

registerTable

Registers a new table with specified configuration.

function registerTable(
  ResourceId tableId,
  FieldLayout fieldLayout,
  Schema keySchema,
  Schema valueSchema,
  string[] calldata keyNames,
  string[] calldata fieldNames
)

  • tableId: Resource ID of the table to register

  • fieldLayout: Field layout structure for the table

  • keySchema: Schema for table keys

  • valueSchema: Schema for table values

  • keyNames: Names for the table keys

  • fieldNames: Names for the table fields

  • Requires caller to own the namespace containing the table

  • Table name cannot be the root name(empty string)

registerStoreHook

Registers a store hook for a specified table.

function registerStoreHook(
  ResourceId tableId,
  IStoreHook hookAddress,
  uint8 enabledHooksBitmap
)

  • tableId: Resource ID of the table to register the hook for

  • hookAddress: Address of the hook contract

  • enabledHooksBitmap: Bitmap indicating which hook functionalities are enabled

  • Requires caller to own the namespace containing the table

  • Hook contract must implement the IStoreHook interface

unregisterStoreHook

Unregisters a store hook for a specified table.

function unregisterStoreHook(ResourceId tableId, IStoreHook hookAddress)

  • tableId: Resource ID of the table to unregister the hook from

  • hookAddress: Address of the hook contract to unregister

  • Requires caller to own the namespace containing the table

WorldRegistrationSystem

The World Registration System provides functions for registering resources other than tables in the World.

registerNamespace

Registers a new namespace.

function registerNamespace(ResourceId namespaceId)

  • namespaceId: Resource ID for the new namespace

  • Namespace must not already exist

  • Namespace name should be valid that not contain reserved characters like __ and not end with _

registerSystemHook

Registers a system hook for a specified system.

function registerSystemHook(
  ResourceId systemId,
  ISystemHook hookAddress,
  uint8 enabledHooksBitmap
)

  • systemId: Resource ID of the system to register the hook for

  • hookAddress: Address of the hook contract

  • enabledHooksBitmap: Bitmap indicating which hook functionalities are enabled

  • Requires caller to own the namespace containing the system

  • Hook contract must implement the ISystemHook interface

unregisterSystemHook

Unregisters a system hook for a specified system.

function unregisterSystemHook(ResourceId systemId, ISystemHook hookAddress)

  • systemId: Resource ID of the system to unregister the hook from

  • hookAddress: Address of the hook contract to unregister

  • Requires caller to own the namespace containing the system

registerSystem

Registers or upgrades a system at the given ID.

function registerSystem(ResourceId systemId, System system, bool publicAccess)

  • systemId: Resource ID for the system

  • system: The system contract being registered

  • publicAccess: Flag indicating if access control check is bypassed

  • Requires caller to own the namespace containing the system

  • Requires the system not registered before with different resource ID

  • Can upgrade existing systems

  • System must implement WorldContextConsumer interface

registerFunctionSelector

Registers a new World function selector.

function registerFunctionSelector(
  ResourceId systemId,
  string memory systemFunctionSignature
) returns (bytes4 worldFunctionSelector)

  • systemId: Resource ID of the system

  • systemFunctionSignature: Signature of the system function

  • Requires the selector to be unique

  • Creates mapping between World function and system function with namespace prefix

  • Requires caller to own the namespace containing the system

registerRootFunctionSelector

Registers a root World function selector.

function registerRootFunctionSelector(
  ResourceId systemId,
  string memory worldFunctionSignature,
  string memory systemFunctionSignature
) returns (bytes4 worldFunctionSelector)

  • systemId: Resource ID of the system

  • worldFunctionSignature: Signature of the World function

  • systemFunctionSignature: Signature of the system function

  • Requires the selector to be unique

  • Creates mapping between World function and system function without namespace prefix

  • Requires caller to own the root namespace

registerDelegation

Registers a delegation for the caller.

function registerDelegation(
  address delegatee,
  ResourceId delegationControlId,
  bytes memory initCallData
)

  • delegatee: Address of the delegatee

  • delegationControlId: ID controlling the delegation

  • initCallData: Initialization data for the delegation

  • Creates new delegation from caller to specified delegatee

unregisterDelegation

Unregisters a delegation.

function unregisterDelegation(address delegatee)

  • delegatee: Address of the delegatee to unregister

  • Deletes the delegation from caller to specified delegatee

registerNamespaceDelegation

Registers a delegation for a namespace.

function registerNamespaceDelegation(
  ResourceId namespaceId,
  ResourceId delegationControlId,
  bytes memory initCallData
)

  • namespaceId: ID of the namespace

  • delegationControlId: ID controlling the delegation

  • initCallData: Initialization data for the delegation

  • Sets up delegation control for a specific namespace

  • Requires caller to own the namespace

  • Delegation cannot be unlimited

unregisterNamespaceDelegation

Unregisters a delegation for a namespace.

function unregisterNamespaceDelegation(ResourceId namespaceId)

  • namespaceId: ID of the namespace

  • Deletes the delegation control for a specific namespace

  • Requires caller to own the namespace