World
Reference
World (interfaces)

IBaseWorld

Git Source (opens in a new tab)

Inherits: IStore, IWorldKernel, IAccessManagementSystem, IBalanceTransferSystem, IBatchCallSystem, IModuleInstallationSystem, IWorldRegistrationSystem, IRegistrationSystem

This interface integrates all systems and associated function selectors that are dynamically registered in the World during deployment.

.

Functions

storeVersion

Retrieves the version of the store.

function storeVersion() public pure returns (bytes32);

Returns

NameTypeDescription
<none>bytes32The current version of the store as a bytes32.

registerTable

Usage Sample

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

registerStoreHook

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

unregisterStoreHook

function unregisterStoreHook(ResourceId tableId, IStoreHook hookAddress) external;

grantAccess

Usage Sample

Grant access to the resource at the given resource ID.

Requires the caller to own the namespace.

function grantAccess(ResourceId resourceId, address grantee) public virtual onlyDelegatecall;

Parameters

NameTypeDescription
resourceIdResourceIdThe ID of the resource to grant access to.
granteeaddressThe address to which access should be granted.

revokeAccess

Usage Sample

Revoke access from the resource at the given resource ID.

Requires the caller to own the namespace.

function revokeAccess(ResourceId resourceId, address grantee) public virtual onlyDelegatecall;

Parameters

NameTypeDescription
resourceIdResourceIdThe ID of the resource to revoke access from.
granteeaddressThe address from which access should be revoked.

transferOwnership

Transfer ownership of the given namespace to newOwner and manages the access.

Requires the caller to own the namespace. Revoke ResourceAccess for previous owner and grant to newOwner.

function transferOwnership(ResourceId namespaceId, address newOwner) public virtual onlyDelegatecall;

Parameters

NameTypeDescription
namespaceIdResourceIdThe ID of the namespace to transfer ownership.
newOwneraddressThe address to which ownership should be transferred.

renounceOwnership

Renounces ownership of the given namespace

Requires the caller to own the namespace. Revoke ResourceAccess for previous owner

function renounceOwnership(ResourceId namespaceId) public virtual onlyDelegatecall;

Parameters

NameTypeDescription
namespaceIdResourceIdThe ID of the namespace to transfer ownership.

transferBalanceToNamespace

Transfer balance to another namespace in the World.

Requires the caller to have access to the source namespace and ensures the destination namespace type is valid.

function transferBalanceToNamespace(
  ResourceId fromNamespaceId,
  ResourceId toNamespaceId,
  uint256 amount
) public virtual onlyDelegatecall;

Parameters

NameTypeDescription
fromNamespaceIdResourceIdThe source namespace from which the balance will be deducted.
toNamespaceIdResourceIdThe target namespace where the balance will be added.
amountuint256The amount to transfer.

transferBalanceToAddress

Usage Sample

Transfer balance out of the World to a specific address.

Requires the caller to have access to the source namespace and ensures sufficient balance before transfer.

function transferBalanceToAddress(
  ResourceId fromNamespaceId,
  address toAddress,
  uint256 amount
) public virtual onlyDelegatecall;

Parameters

NameTypeDescription
fromNamespaceIdResourceIdThe source namespace from which the balance will be deducted.
toAddressaddressThe target address where the balance will be sent.
amountuint256The amount to transfer.

batchCall

Make batch calls to multiple systems into a single transaction.

Iterates through an array of system calls, executes them, and returns an array of return data.

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

Parameters

NameTypeDescription
systemCallsSystemCallData[]An array of SystemCallData that contains systemId and callData for each call.

Returns

NameTypeDescription
returnDatasbytes[]An array of bytes containing the return data for each system call.

batchCallFrom

Make batch calls from specific addresses to multiple systems in a single transaction.

Iterates through an array of system calls with specified 'from' addresses, executes them, and returns an array of return data.

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

Parameters

NameTypeDescription
systemCallsSystemCallFromData[]An array of SystemCallFromData that contains from, systemId, and callData for each call.

Returns

NameTypeDescription
returnDatasbytes[]An array of bytes containing the return data for each system call.

installModule

Installs a module into the World under a specified namespace.

Validates the given module against the IModule interface and delegates the installation process. The module is then registered in the InstalledModules table.

function installModule(IModule module, bytes memory encodedArgs) public onlyDelegatecall;

Parameters

NameTypeDescription
moduleIModuleThe module to be installed.
encodedArgsbytesThe ABI encoded arguments for module installation.

registerNamespace

Usage Sample

Registers a new namespace

Creates a new namespace resource with the given ID

function registerNamespace(ResourceId namespaceId) public virtual onlyDelegatecall;

Parameters

NameTypeDescription
namespaceIdResourceIdThe unique identifier for the new namespace

registerSystemHook

Registers a new system hook

Adds a new hook for the system at the provided system ID

function registerSystemHook(
  ResourceId systemId,
  ISystemHook hookAddress,
  uint8 enabledHooksBitmap
) public virtual onlyDelegatecall;

Parameters

NameTypeDescription
systemIdResourceIdThe ID of the system
hookAddressISystemHookThe address of the hook being registered
enabledHooksBitmapuint8Bitmap indicating which hooks are enabled

unregisterSystemHook

Unregisters a system hook

Removes a hook for the system at the provided system ID

function unregisterSystemHook(ResourceId systemId, ISystemHook hookAddress) public virtual onlyDelegatecall;

Parameters

NameTypeDescription
systemIdResourceIdThe ID of the system
hookAddressISystemHookThe address of the hook being unregistered

registerSystem

Usage Sample

Registers a system

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. If publicAccess is true, no access control check is performed for calling the system. This function doesn't check whether a system already exists at the given selector, making it possible to upgrade systems.

function registerSystem(ResourceId systemId, System system, bool publicAccess) public virtual onlyDelegatecall;

Parameters

NameTypeDescription
systemIdResourceIdThe unique identifier for the system
systemSystemThe system being registered
publicAccessboolFlag indicating if access control check is bypassed

registerFunctionSelector

Registers a new World function selector

Creates a mapping between a World function and its associated system function

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

Parameters

NameTypeDescription
systemIdResourceIdThe system ID
systemFunctionSignaturestringThe signature of the system function

Returns

NameTypeDescription
worldFunctionSelectorbytes4The selector of the World function

registerRootFunctionSelector

Usage Sample

Registers a root World function selector

Creates a mapping for a root World function without namespace or name prefix

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

Parameters

NameTypeDescription
systemIdResourceIdThe system ID
worldFunctionSignaturestringThe signature of the World function
systemFunctionSignaturestringThe signature of the system function

Returns

NameTypeDescription
worldFunctionSelectorbytes4The selector of the World function

registerDelegation

Registers a delegation for the caller

Creates a new delegation from the caller to the specified delegatee

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

Parameters

NameTypeDescription
delegateeaddressThe address of the delegatee
delegationControlIdResourceIdThe ID controlling the delegation
initCallDatabytesThe initialization data for the delegation

unregisterDelegation

Unregisters a delegation

Deletes the new delegation from the caller to the specified delegatee

function unregisterDelegation(address delegatee) public onlyDelegatecall;

Parameters

NameTypeDescription
delegateeaddressThe address of the delegatee

registerNamespaceDelegation

Registers a delegation for a namespace

Sets up a new delegation control for a specific namespace

function registerNamespaceDelegation(
  ResourceId namespaceId,
  ResourceId delegationControlId,
  bytes memory initCallData
) public onlyDelegatecall;

Parameters

NameTypeDescription
namespaceIdResourceIdThe ID of the namespace
delegationControlIdResourceIdThe ID controlling the delegation
initCallDatabytesThe initialization data for the delegation

unregisterNamespaceDelegation

Unregisters a delegation for a namespace

Deletes the delegation control for a specific namespace

function unregisterNamespaceDelegation(ResourceId namespaceId) public onlyDelegatecall;

Parameters

NameTypeDescription
namespaceIdResourceIdThe ID of the namespace

Errors

Store_TableAlreadyExists

Error raised if the provided table already exists.

error Store_TableAlreadyExists(ResourceId tableId, string tableIdString);

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table.
tableIdStringstringThe stringified ID of the table (for easier debugging if cleartext tableIds are used).

Store_TableNotFound

Error raised if the provided table cannot be found.

error Store_TableNotFound(ResourceId tableId, string tableIdString);

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table.
tableIdStringstringThe stringified ID of the table (for easier debugging if cleartext tableIds are used).

Store_InvalidResourceType

Error raised if the provided resource ID cannot be found.

error Store_InvalidResourceType(bytes2 expected, ResourceId resourceId, string resourceIdString);

Parameters

NameTypeDescription
expectedbytes2The expected resource type.
resourceIdResourceIdThe resource ID.
resourceIdStringstringThe stringified resource ID (for easier debugging).

Store_InvalidBounds

Error raised if the provided slice bounds are invalid.

error Store_InvalidBounds(uint256 start, uint256 end);

Parameters

NameTypeDescription
startuint256The start index within the dynamic field for the slice operation (inclusive).
enduint256The end index within the dynamic field for the slice operation (exclusive).

Store_IndexOutOfBounds

Error raised if the provided index is out of bounds.

Raised if the start index is larger than the previous length of the field.

error Store_IndexOutOfBounds(uint256 length, uint256 accessedIndex);

Parameters

NameTypeDescription
lengthuint256FIXME
accessedIndexuint256FIXME

Store_InvalidStaticDataLength

Error raised if the provided static data length is invalid.

error Store_InvalidStaticDataLength(uint256 expected, uint256 received);

Parameters

NameTypeDescription
expecteduint256The expected length.
receiveduint256The provided length.

Store_InvalidKeyNamesLength

Error raised if the provided key names length is invalid.

error Store_InvalidKeyNamesLength(uint256 expected, uint256 received);

Parameters

NameTypeDescription
expecteduint256The expected length.
receiveduint256The provided length.

Store_InvalidFieldNamesLength

Error raised if the provided field names length is invalid.

error Store_InvalidFieldNamesLength(uint256 expected, uint256 received);

Parameters

NameTypeDescription
expecteduint256The expected length.
receiveduint256The provided length.

Store_InvalidValueSchemaLength

Error raised if the provided value schema length is invalid.

error Store_InvalidValueSchemaLength(uint256 expected, uint256 received);

Parameters

NameTypeDescription
expecteduint256The expected length.
receiveduint256The provided length.

Store_InvalidValueSchemaStaticLength

Error raised if the provided schema static length is invalid.

error Store_InvalidValueSchemaStaticLength(uint256 expected, uint256 received);

Parameters

NameTypeDescription
expecteduint256The expected length.
receiveduint256The provided length.

Store_InvalidValueSchemaDynamicLength

Error raised if the provided schema dynamic length is invalid.

error Store_InvalidValueSchemaDynamicLength(uint256 expected, uint256 received);

Parameters

NameTypeDescription
expecteduint256The expected length.
receiveduint256The provided length.

Store_InvalidSplice

Error raised if the provided splice is invalid.

Raised if the splice total length of the field is changed but the splice is not at the end of the field.

error Store_InvalidSplice(uint40 startWithinField, uint40 deleteCount, uint40 fieldLength);

Parameters

NameTypeDescription
startWithinFielduint40The start index within the field for the splice operation.
deleteCountuint40The number of bytes to delete in the splice operation.
fieldLengthuint40The field length for the splice operation.

IWorldCall

Git Source (opens in a new tab)

This interface defines the contract for executing calls on the World's systems.

Functions

call

Usage Sample

Call the system at the given system ID.

If the system is not public, the caller must have access to the namespace or name (encoded in the system ID).

function call(ResourceId systemId, bytes memory callData) external payable returns (bytes memory);

Parameters

NameTypeDescription
systemIdResourceIdThe ID of the system to be called.
callDatabytesThe data to pass with the call, function selector (4 bytes) followed by the ABI encoded parameters.

Returns

NameTypeDescription
<none>bytesThe abi encoded return data from the called system.

callFrom

Call the system at the given system ID on behalf of the given delegator.

If the system is not public, the delegator must have access to the namespace or name (encoded in the system ID).

function callFrom(
  address delegator,
  ResourceId systemId,
  bytes memory callData
) external payable returns (bytes memory);

Parameters

NameTypeDescription
delegatoraddressThe address on whose behalf the call is made.
systemIdResourceIdThe ID of the system to be called.
callDatabytesThe data to pass with the call, function selector (4 bytes) followed by the ABI encoded parameters.

Returns

NameTypeDescription
<none>bytesThe abi encoded return data from the called system.

IWorldKernel

Git Source (opens in a new tab)

Inherits: IWorldModuleInstallation, IWorldCall, IWorldErrors, IWorldEvents, IModuleErrors

The IWorldKernel interface includes all methods that are part of the World contract's internal bytecode. Consumers should use the IBaseWorld interface instead, which includes dynamically registered functions selectors from the InitModule.

The IWorldKernel interface inherits IModuleErrors because the world can be delegatecalled with module code, so it's ABI should include these errors.

Functions

worldVersion

Retrieve the version of the World.

function worldVersion() external view returns (bytes32);

Returns

NameTypeDescription
<none>bytes32The version identifier of the World.

creator

Retrieve the immutable original deployer of the World.

function creator() external view returns (address);

Returns

NameTypeDescription
<none>addressThe address of the World's creator.

initialize

Initializes the World.

Can only be called once by the creator.

function initialize(IModule initModule) external;

Parameters

NameTypeDescription
initModuleIModuleThe InitModule to be installed during initialization.

IWorldModuleInstallation

Git Source (opens in a new tab)

This interface defines the contract responsible for managing root modules installation.

Functions

installRootModule

Install the given root module in the World.

Requires the caller to own the root namespace. The module is delegatecalled and installed in the root namespace.

function installRootModule(IModule module, bytes memory encodedArgs) external;

Parameters

NameTypeDescription
moduleIModuleThe module to be installed.
encodedArgsbytesThe ABI encoded arguments for the module installation.

IWorldErrors

Git Source (opens in a new tab)

This interface contains custom error types for the World contract. These errors provide more informative messages for certain operations within the World contract.

Errors

World_AlreadyInitialized

Raised when trying to initialize an already initialized World.

error World_AlreadyInitialized();

World_ResourceAlreadyExists

Raised when trying to register a resource that already exists.

error World_ResourceAlreadyExists(ResourceId resourceId, string resourceIdString);

Parameters

NameTypeDescription
resourceIdResourceIdThe ID of the resource.
resourceIdStringstringThe string representation of the resource ID.

World_ResourceNotFound

Raised when the specified resource is not found.

error World_ResourceNotFound(ResourceId resourceId, string resourceIdString);

Parameters

NameTypeDescription
resourceIdResourceIdThe ID of the resource.
resourceIdStringstringThe string representation of the resource ID.

World_AccessDenied

Raised when a user tries to access a resource they don't have permission for.

error World_AccessDenied(string resource, address caller);

Parameters

NameTypeDescription
resourcestringThe resource's identifier.
calleraddressThe address of the user trying to access the resource.

World_InvalidResourceId

Raised when an invalid resource ID is provided.

error World_InvalidResourceId(ResourceId resourceId, string resourceIdString);

Parameters

NameTypeDescription
resourceIdResourceIdThe ID of the resource.
resourceIdStringstringThe string representation of the resource ID.

World_InvalidNamespace

Raised when an namespace contains an invalid sequence of characters ("__").

error World_InvalidNamespace(bytes14 namespace);

Parameters

NameTypeDescription
namespacebytes14The invalid namespace.

World_SystemAlreadyExists

Raised when trying to register a system that already exists.

error World_SystemAlreadyExists(address system);

Parameters

NameTypeDescription
systemaddressThe address of the system.

World_FunctionSelectorAlreadyExists

Raised when trying to register a function selector that already exists.

error World_FunctionSelectorAlreadyExists(bytes4 functionSelector);

Parameters

NameTypeDescription
functionSelectorbytes4The function selector in question.

World_FunctionSelectorNotFound

Raised when the specified function selector is not found.

error World_FunctionSelectorNotFound(bytes4 functionSelector);

Parameters

NameTypeDescription
functionSelectorbytes4The function selector in question.

World_DelegationNotFound

Raised when the specified delegation is not found.

error World_DelegationNotFound(address delegator, address delegatee);

Parameters

NameTypeDescription
delegatoraddressThe address of the delegator.
delegateeaddressThe address of the delegatee.

World_UnlimitedDelegationNotAllowed

Raised when trying to create an unlimited delegation in a context where it is not allowed, e.g. when registering a namespace fallback delegation.

error World_UnlimitedDelegationNotAllowed();

World_InsufficientBalance

Raised when there's an insufficient balance for a particular operation.

error World_InsufficientBalance(uint256 balance, uint256 amount);

Parameters

NameTypeDescription
balanceuint256The current balance.
amountuint256The amount needed.

World_InterfaceNotSupported

Raised when the specified interface is not supported by the contract.

error World_InterfaceNotSupported(address contractAddress, bytes4 interfaceId);

Parameters

NameTypeDescription
contractAddressaddressThe address of the contract in question.
interfaceIdbytes4The ID of the interface.

World_InvalidResourceType

Raised when an invalid resource type is provided.

error World_InvalidResourceType(bytes2 expected, ResourceId resourceId, string resourceIdString);

Parameters

NameTypeDescription
expectedbytes2The expected resource type.
resourceIdResourceIdThe ID of the resource.
resourceIdStringstringThe string representation of the resource ID.

World_CallbackNotAllowed

Raised when the World is calling itself via an external call.

error World_CallbackNotAllowed(bytes4 functionSelector);

Parameters

NameTypeDescription
functionSelectorbytes4The function selector of the disallowed callback.

IWorldFactory

Git Source (opens in a new tab)

This interface defines the contract responsible for deploying and keeping track of World contract instances.

Functions

deployWorld

Deploys a new World contract.

The deployment of the World contract will result in the WorldDeployed event being emitted.

function deployWorld(bytes memory salt) external returns (address worldAddress);

Returns

NameTypeDescription
worldAddressaddressThe address of the newly deployed World contract.

Events

WorldDeployed

Emitted when a new World contract is deployed.

event WorldDeployed(address indexed newContract, uint256 salt);

Parameters

NameTypeDescription
newContractaddressThe address of the newly deployed World contract.
saltuint256User defined salt for deterministic world addresses across chains.