XMTP Contracts

• XMTP Contracts
  • Usage
    • Prerequisites
    • Initialize project
  • Developer tools
  • Developer documentation

⚠️ Experimental: This software is in early development. Expect frequent changes and unresolved issues.

This repository contains all the smart contracts that underpin the XMTP decentralized network.

Usage

The project is built with the Foundry framework, and dependency management is handled using native git submodules.

Additionally, it uses slither for static analysis.

Prerequisites

Install foundry

Install slither

Install node

Install prettier

Optionally, install yarn or any other preferred JS package manager.

Initialize project

Initialize the project dependencies:

yarn install # if using yarn

Initialize foundry:

forge update

Developer tools

The following can be run using npm, yarn and similar JS package managers.

# Forge scripts
build:          Builds the contracts.
test:           Tests the contracts.
clean:          Cleans the forge environment.
coverage:       Shows the test coverage.
gas-report:     Shows the gas costs.
doc:            Serves the project documentation at http://localhost:4000

# Static analysis
slither:        Runs slither static analysis.

# Linters
solhint:        Runs solhint.
solhint-fix:    Runs solhint in fix mode, potentially modifying files.
lint-staged:    Runs linters only on files that are staged in git.

# Formatters
prettier:       Runs prettier in write mode, potentially modifying files.
prettier-check: Runs prettier in check mode.

Developer documentation

The Foundry book can be found hosted on the contracts documentation page.

To dive deeper into the protocol and its architecture, read the architecture documentation.

Contents

• interfaces
• ERC5267
• ERC712
• Migratable
• ParameterRegistry
• PayloadBroadcaster

Contents

• IERC1967
• IERC5267
• IERC712
• IMigratable
• IParameterRegistry
• IPayloadBroadcaster

IERC1967

Git Source

Functions

implementation

Returns the address of the current implementation.

function implementation() external view returns (address implementation_);

Events

Upgraded

Emitted when the implementation is upgraded.

event Upgraded(address indexed implementation);

Parameters

IERC5267

Git Source

Inherits: IERC712

The interface as defined by EIP-5267: https://eips.ethereum.org/EIPS/eip-5267

Functions

eip712Domain

Returns the fields and values that describe the domain separator used by this contract for EIP-712.

function eip712Domain()
    external
    view
    returns (
        bytes1 fields_,
        string memory name_,
        string memory version_,
        uint256 chainId_,
        address verifyingContract_,
        bytes32 salt_,
        uint256[] memory extensions_
    );

Returns

Events

EIP712DomainChanged

MAY be emitted to signal that the domain could have changed.

event EIP712DomainChanged();

IERC712

Git Source

The interface as defined by EIP-712: https://eips.ethereum.org/EIPS/eip-712

Functions

DOMAIN_SEPARATOR

Returns the EIP712 domain separator used in the encoding of a signed digest.

function DOMAIN_SEPARATOR() external view returns (bytes32 domainSeparator_);

IMigratable

Git Source

Inherits: IERC1967

Unlike a simple upgrade, a migration is defined as:

• Logic to determine the migration flow based on any conditions, and/or
• Logic to determine the implementation to upgrade to, and/or
• Logic to determine if the upgrade or migration should occur, and/or
• State changes to the proxy storage, and/or
• Setting the proxy's implementation slot. All the above can be kicked off by anyone, and without parameters, which is useful in governance models.

Functions

migrate

Initiates a migration of the proxy, in a way defined by the implementation.

Normally, the implementation has a way of determining the migrator that needs to be delegatecalled.

function migrate() external;

Events

Migrated

Emitted when the implementation is migrated.

The migrator contains fixed arbitrary code to manipulate storage, including the implementation slot.

event Migrated(address indexed migrator);

Parameters

Errors

ZeroMigrator

Thrown when the migrator being delegatecalled is zero (i.e. address(0)).

error ZeroMigrator();

MigrationFailed

Thrown when the migration fails (i.e. the delegatecall to the migrator reverts).

error MigrationFailed(address migrator_, bytes revertData_);

Parameters

EmptyCode

Thrown when the migrator is empty (i.e. has no code).

error EmptyCode(address migrator_);

Parameters

IParameterRegistry

Git Source

Inherits: IMigratable, IParameterKeysErrors, IRegistryParametersErrors

A parameter registry allows admins to set parameters, including whether an account is an admin, and allows any account/contract to query the values of parameters.

Functions

initialize

Initializes the parameter registry, as used by a proxy contract.

Whether an account is an admin is tracked as a key-value pair in the registry itself.

function initialize(address[] calldata admins_) external;

Parameters

set

Sets several parameters.

The length of the keys_ and values_ arrays must be the same.

The caller must be an admin.

function set(string[] calldata keys_, bytes32[] calldata values_) external;

Parameters

set

Sets a parameter.

The caller must be an admin.

function set(string calldata key_, bytes32 value_) external;

Parameters

isAdmin

Returns whether an account is an admin (i.e. an account that can set parameters).

function isAdmin(address account_) external view returns (bool isAdmin_);

Parameters

Returns

get

Gets the values of several parameters.

The default value for each parameter is bytes32(0).

function get(string[] calldata keys_) external view returns (bytes32[] memory values_);

Parameters

Returns

get

Gets the value of a parameter.

The default value for a parameter is bytes32(0).

function get(string calldata key_) external view returns (bytes32 value_);

Parameters

Returns

migratorParameterKey

The parameter registry key used to fetch the migrator.

Uniquely, the parameter registry uses itself, so the key-value pair is stored in the contract itself.

function migratorParameterKey() external pure returns (string memory key_);

Returns

adminParameterKey

The parameter registry key used to fetch the status of an admin.

Uniquely, the parameter registry uses itself, so the key-value pair is stored in the contract itself.

function adminParameterKey() external pure returns (string memory key_);

Returns

Events

ParameterSet

Emitted when a parameter is set.

Values that are not value types (e.g. bytes, arrays, structs, etc.) must be the hash of their contents.

When passing the key as the first argument when emitting this event, it is automatically hashed since reference types are not indexable, and the hash is thus the indexable value.

event ParameterSet(string indexed keyHash, string key, bytes32 value);

Parameters

Errors

NotAdmin

Thrown when the caller is not an admin (e.g. when setting a parameter).

error NotAdmin();

NoKeys

Thrown when no keys are provided (e.g. when setting or getting parameters).

error NoKeys();

ArrayLengthMismatch

Thrown when the array length mismatch (e.g. when setting multiple parameters).

error ArrayLengthMismatch();

EmptyAdmins

Thrown when the array of admins is empty.

error EmptyAdmins();

ZeroAdmin

Thrown when an admin is the zero address.

error ZeroAdmin();

IPayloadBroadcaster

Git Source

Inherits: IMigratable, IRegistryParametersErrors

A payload broadcaster is a contract that broadcasts payloads as events, where payloads have a min and max size, both of which can be updated from a parameter registry.

Functions

initialize

Initializes the contract.

function initialize() external;

updateMinPayloadSize

Updates the minimum payload size.

Ensures the new minimum is less than the maximum.

Ensures the new minimum is not equal to the old minimum.

function updateMinPayloadSize() external;

updateMaxPayloadSize

Updates the maximum payload size.

Ensures the new maximum is greater than the minimum.

Ensures the new maximum is not equal to the old maximum.

function updateMaxPayloadSize() external;

updatePauseStatus

Updates the pause status.

Ensures the new pause status is not equal to the old pause status.

function updatePauseStatus() external;

updatePayloadBootstrapper

Updates the payload bootstrapper.

Ensures the new payload bootstrapper is not equal to the old payload bootstrapper.

function updatePayloadBootstrapper() external;

minPayloadSizeParameterKey

The parameter registry key used to fetch the minimum payload size.

function minPayloadSizeParameterKey() external pure returns (string memory key_);

maxPayloadSizeParameterKey

The parameter registry key used to fetch the maximum payload size.

function maxPayloadSizeParameterKey() external pure returns (string memory key_);

migratorParameterKey

The parameter registry key used to fetch the migrator.

function migratorParameterKey() external pure returns (string memory key_);

pausedParameterKey

The parameter registry key used to fetch the paused status.

function pausedParameterKey() external pure returns (string memory key_);

payloadBootstrapperParameterKey

The parameter registry key used to fetch the payload bootstrapper.

function payloadBootstrapperParameterKey() external pure returns (string memory key_);

parameterRegistry

The address of the parameter registry.

function parameterRegistry() external view returns (address parameterRegistry_);

minPayloadSize

Minimum valid payload size (in bytes).

function minPayloadSize() external view returns (uint32 size_);

maxPayloadSize

Maximum valid payload size (in bytes).

function maxPayloadSize() external view returns (uint32 size_);

paused

The pause status.

function paused() external view returns (bool paused_);

payloadBootstrapper

The payload bootstrapper.

function payloadBootstrapper() external view returns (address payloadBootstrapper_);

Events

MinPayloadSizeUpdated

Emitted when the minimum payload size is updated.

Will not be emitted if the new minimum is equal to the old minimum.

event MinPayloadSizeUpdated(uint256 indexed size);

Parameters

MaxPayloadSizeUpdated

Emitted when the maximum payload size is updated.

Will not be emitted if the new maximum is equal to the old maximum.

event MaxPayloadSizeUpdated(uint256 indexed size);

Parameters

PauseStatusUpdated

Emitted when the pause status is updated.

event PauseStatusUpdated(bool indexed paused);

Parameters

PayloadBootstrapperUpdated

Emitted when the payload bootstrapper is updated.

event PayloadBootstrapperUpdated(address indexed payloadBootstrapper);

Parameters

Errors

ZeroParameterRegistry

Thrown when the parameter registry address is zero (i.e. address(0)).

error ZeroParameterRegistry();

InvalidPayloadSize

Thrown when the payload size is invalid.

error InvalidPayloadSize(uint256 actualSize_, uint256 minSize_, uint256 maxSize_);

InvalidMaxPayloadSize

Thrown when the maximum payload size is invalid.

error InvalidMaxPayloadSize();

InvalidMinPayloadSize

Thrown when the minimum payload size is invalid.

error InvalidMinPayloadSize();

NoChange

Thrown when there is no change to an updated parameter.

error NoChange();

Paused

Thrown when any pausable function is called when the contract is paused.

error Paused();

NotPaused

Thrown when any pause-mode-only function is called when the payload broadcaster is not paused.

error NotPaused();

NotPayloadBootstrapper

Thrown when the payload bootstrapper is not the caller.

error NotPayloadBootstrapper();

ERC5267

Git Source

Inherits: IERC5267, ERC712

Functions

constructor

Constructs the contract.

constructor() ERC712();

_initializeERC5267

function _initializeERC5267() internal;

eip712Domain

Returns the fields and values that describe the domain separator used by this contract for EIP-712.

function eip712Domain()
    external
    view
    returns (
        bytes1 fields_,
        string memory name_,
        string memory version_,
        uint256 chainId_,
        address verifyingContract_,
        bytes32 salt_,
        uint256[] memory extensions_
    );

Returns

ERC712

Git Source

Inherits: IERC712

State Variables

_EIP712_DOMAIN_HASH

keccak256("EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)")

bytes32 internal constant _EIP712_DOMAIN_HASH = 0x8b73c3c69bb8fe3d512ecc4cf759cc79239f7b179b0ffacaa9a75d522b39400f;

_initialChainId

Initial Chain ID set at deployment.

uint256 internal immutable _initialChainId;

_ERC712_STORAGE_LOCATION

bytes32 internal constant _ERC712_STORAGE_LOCATION = 0xc7effa11ad597798220888e5d1ba4eeddcc8c2635d01dae8b9f958ac905c1100;

Functions

_getERC712Storage

function _getERC712Storage() internal pure returns (ERC712Storage storage $);

constructor

Constructs the EIP-712 domain separator.

constructor();

_initializeERC712

function _initializeERC712() internal;

DOMAIN_SEPARATOR

Returns the EIP712 domain separator used in the encoding of a signed digest.

function DOMAIN_SEPARATOR() public view returns (bytes32 domainSeparator_);

_getDomainSeparator

Computes the EIP-712 domain separator.

function _getDomainSeparator() internal view returns (bytes32 domainSeparator_);

Returns

_getDigest

Returns the digest to be signed, via EIP-712, given an internal digest (i.e. hash struct).

function _getDigest(bytes32 internalDigest_) internal view returns (bytes32 digest_);

Parameters

Returns

_name

The name of the contract.

function _name() internal view virtual returns (string memory name_);

_version

The version of the contract.

function _version() internal view virtual returns (string memory version_);

Structs

ERC712Storage

The UUPS storage for the ERC712 contract.

Note: storage-location: erc7201:xmtp.storage.ERC712

struct ERC712Storage {
    bytes32 initialDomainSeparator;
}

Properties

Migratable

Git Source

Inherits: IMigratable

State Variables

_IMPLEMENTATION_SLOT

Storage slot with the address of the current implementation. keccak256('eip1967.proxy.implementation') - 1.

uint256 private constant _IMPLEMENTATION_SLOT = 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc;

Functions

implementation

Returns the address of the current implementation.

function implementation() public view returns (address implementation_);

_migrate

Performs an arbitrary migration by delegate-calling migrator_.

The migrator fallback code defines the entire migration process, and takes no user-defined arguments.

function _migrate(address migrator_) internal;

Parameters

ParameterRegistry

Git Source

Inherits: IParameterRegistry, Migratable, Initializable

A parameter registry is a contract that stores key-value pairs of parameters used by a protocol. Keys should be globally unique and human-readable strings, for easier parsing and indexing. Keys can be set by admins, and whether an account is an admin is itself a key-value pair in the registry, which means that admins can be added and removed by other admins, and the parameter registry can be orphaned.

State Variables

_PARAMETER_REGISTRY_STORAGE_LOCATION

bytes32 internal constant _PARAMETER_REGISTRY_STORAGE_LOCATION =
    0xefab3f4eb315eafaa267b58974a509c07c739fbfe8e62b4eff49c4ced6985000;

Functions

_getParameterRegistryStorage

function _getParameterRegistryStorage() internal pure returns (ParameterRegistryStorage storage $);

onlyAdmin

modifier onlyAdmin();

constructor

Constructor for the implementation contract, such that the implementation cannot be initialized.

constructor();

initialize

Initializes the parameter registry, as used by a proxy contract.

Whether an account is an admin is tracked as a key-value pair in the registry itself.

function initialize(address[] calldata admins_) external initializer;

Parameters

set

Sets several parameters.

The length of the keys_ and values_ arrays must be the same.

function set(string[] calldata keys_, bytes32[] calldata values_) external onlyAdmin;

Parameters

set

Sets several parameters.

The length of the keys_ and values_ arrays must be the same.

function set(string calldata key_, bytes32 value_) external onlyAdmin;

Parameters

migrate

Initiates a migration of the proxy, in a way defined by the implementation.

Normally, the implementation has a way of determining the migrator that needs to be delegatecalled.

function migrate() external;

migratorParameterKey

The parameter registry key used to fetch the migrator.

Uniquely, the parameter registry uses itself, so the key-value pair is stored in the contract itself.

function migratorParameterKey() public pure virtual returns (string memory key_);

Returns

adminParameterKey

The parameter registry key used to fetch the status of an admin.

Uniquely, the parameter registry uses itself, so the key-value pair is stored in the contract itself.

function adminParameterKey() public pure virtual returns (string memory key_);

Returns

isAdmin

Returns whether an account is an admin (i.e. an account that can set parameters).

function isAdmin(address account_) public view returns (bool isAdmin_);

Parameters

Returns

get

Gets the values of several parameters.

The default value for each parameter is bytes32(0).

function get(string[] calldata keys_) external view returns (bytes32[] memory values_);

Parameters

Returns

get

Gets the values of several parameters.

The default value for each parameter is bytes32(0).

function get(string calldata key_) external view returns (bytes32 value_);

Parameters

Returns

_setParameter

function _setParameter(ParameterRegistryStorage storage $, string memory key_, bytes32 value_) internal;

_getAdminKey

Returns the admin-specific key used to query to parameter registry to determine if an account is an admin. The admin-specific key is the concatenation of the admin parameter key and the address of the admin. For example, if the admin parameter key is "pr.isAdmin", then the key for admin 0x1234567890123456789012345678901234567890 is "pr.isAdmin.0x1234567890123456789012345678901234567890".

function _getAdminKey(string memory adminParameterKey_, address account_) internal pure returns (string memory key_);

_getRegistryParameter

function _getRegistryParameter(string memory key_) internal view returns (bytes32 value_);

_revertIfNotAdmin

function _revertIfNotAdmin() internal view;

Structs

ParameterRegistryStorage

The UUPS storage for the parameter registry.

Note: storage-location: erc7201:xmtp.storage.ParameterRegistry

struct ParameterRegistryStorage {
    mapping(string key => bytes32 value) parameters;
}

Properties

PayloadBroadcaster

Git Source

Inherits: IPayloadBroadcaster, Migratable, Initializable

A payload broadcaster is a contract that broadcasts payloads as events, where payloads have a min and max size, both of which can be updated from a parameter registry.

State Variables

parameterRegistry

The address of the parameter registry.

address public immutable parameterRegistry;

_PAYLOAD_BROADCASTER_STORAGE_LOCATION

bytes32 internal constant _PAYLOAD_BROADCASTER_STORAGE_LOCATION =
    0xeda186f2b85b2c197e0a3ff15dc0c5c16c74d00b5c7f432acaa215db84203b00;

Functions

_getPayloadBroadcasterStorage

function _getPayloadBroadcasterStorage() internal pure returns (PayloadBroadcasterStorage storage $);

constructor

Constructor for the implementation contract, such that the implementation cannot be initialized.

The parameter registry must not be the zero address.

The parameter registry is immutable so that it is inlined in the contract code, and has minimal gas cost.

constructor(address parameterRegistry_);

Parameters

initialize

Initializes the contract.

function initialize() public virtual initializer;

updateMinPayloadSize

Updates the minimum payload size.

Ensures the new minimum is less than the maximum.

function updateMinPayloadSize() external;

updateMaxPayloadSize

Updates the maximum payload size.

Ensures the new maximum is greater than the minimum.

function updateMaxPayloadSize() external;

updatePauseStatus

Updates the pause status.

Ensures the new pause status is not equal to the old pause status.

function updatePauseStatus() external;

updatePayloadBootstrapper

Updates the payload bootstrapper.

Ensures the new payload bootstrapper is not equal to the old payload bootstrapper.

function updatePayloadBootstrapper() external;

migrate

Initiates a migration of the proxy, in a way defined by the implementation.

Normally, the implementation has a way of determining the migrator that needs to be delegatecalled.

function migrate() external;

minPayloadSizeParameterKey

The parameter registry key used to fetch the minimum payload size.

function minPayloadSizeParameterKey() public pure virtual returns (string memory key_);

maxPayloadSizeParameterKey

The parameter registry key used to fetch the maximum payload size.

function maxPayloadSizeParameterKey() public pure virtual returns (string memory key_);

migratorParameterKey

The parameter registry key used to fetch the migrator.

function migratorParameterKey() public pure virtual returns (string memory key_);

pausedParameterKey

The parameter registry key used to fetch the paused status.

function pausedParameterKey() public pure virtual returns (string memory key_);

payloadBootstrapperParameterKey

The parameter registry key used to fetch the payload bootstrapper.

function payloadBootstrapperParameterKey() public pure virtual returns (string memory key_);

minPayloadSize

Minimum valid payload size (in bytes).

function minPayloadSize() external view returns (uint32 size_);

maxPayloadSize

Maximum valid payload size (in bytes).

function maxPayloadSize() external view returns (uint32 size_);

paused

The pause status.

function paused() external view returns (bool paused_);

payloadBootstrapper

The payload bootstrapper.

function payloadBootstrapper() external view returns (address payloadBootstrapper_);

_isZero

function _isZero(address input_) internal pure returns (bool isZero_);

_revertIfPaused

function _revertIfPaused() internal view;

_revertIfNotPaused

function _revertIfNotPaused() internal view;

_revertIfInvalidPayloadSize

function _revertIfInvalidPayloadSize(uint256 payloadSize_) internal view;

_revertIfNotPayloadBootstrapper

function _revertIfNotPayloadBootstrapper() internal view;

Structs

PayloadBroadcasterStorage

The UUPS storage for the payload broadcaster.

Note: storage-location: erc7201:xmtp.storage.PayloadBroadcaster

struct PayloadBroadcasterStorage {
    uint32 minPayloadSize;
    uint32 maxPayloadSize;
    uint64 sequenceId;
    bool paused;
    address payloadBootstrapper;
}

Properties

Contents

• interfaces
• Factory
• Initializable
• Migrator
• Proxy

Contents

• IFactory
• IInitializable
• IProxy

IFactory

Git Source

Inherits: IMigratable

Functions

initialize

Initializes the contract.

function initialize() external;

deployImplementation

Deploys an implementation contract.

function deployImplementation(bytes memory bytecode_) external returns (address implementation_);

Parameters

Returns

deployProxy

Deploys a proxy contract.

function deployProxy(address implementation_, bytes32 salt_, bytes calldata initializeCallData_)
    external
    returns (address proxy_);

Parameters

Returns

pausedParameterKey

The parameter registry key used to fetch the paused status.

function pausedParameterKey() external pure returns (string memory key_);

migratorParameterKey

The parameter registry key used to fetch the migrator.

function migratorParameterKey() external pure returns (string memory key_);

paused

The pause status.

function paused() external view returns (bool paused_);

parameterRegistry

The address of the parameter registry.

function parameterRegistry() external view returns (address parameterRegistry_);

initializableImplementation

The address of the first temporary implementation that proxies will proxy.

*This contract is the first proxied implementation of any proxy, and allows the factory to then set the proxy's actual implementation, and initialize it with respect to that actual implementation. This ensures that:

• The address of a proxy is only defined by the nonce, and not by the implementation it will proxy.
• No contracts are deployed that are not used.
• The proxy can be easily initialized with respect to the actual implementation, atomically.*

function initializableImplementation() external view returns (address initializableImplementation_);

computeImplementationAddress

Computes the address of an implementation contract that would be deployed from a given bytecode.

The address is determined only by the bytecode, and so the same bytecode results in the same address.

function computeImplementationAddress(bytes calldata bytecode_) external view returns (address implementation_);

Parameters

Returns

computeProxyAddress

Computes the address of a proxy contract that would be deployed from given a caller and salt.

The actual salt used to deploy the proxy via create2 is keccak256(abi.encodePacked(caller_, salt_)).

function computeProxyAddress(address caller_, bytes32 salt_) external view returns (address proxy_);

Parameters

Returns

Events

InitializableImplementationDeployed

Emitted when the "initializable implementation" is deployed.

This contract is only deployed once, when the factory itself is deployed.

event InitializableImplementationDeployed(address indexed implementation);

Parameters

ImplementationDeployed

Emitted when an implementation is deployed.

event ImplementationDeployed(address indexed implementation, bytes32 indexed bytecodeHash);

Parameters

ProxyDeployed

Emitted when a proxy is deployed.

The actual salt used to deploy the proxy via create2 is keccak256(abi.encodePacked(sender, salt)).

event ProxyDeployed(
    address indexed proxy,
    address indexed implementation,
    address indexed sender,
    bytes32 salt,
    bytes initializeCallData
);

Parameters

Errors

ZeroParameterRegistry

Thrown when the parameter registry is the zero address.

error ZeroParameterRegistry();

InvalidImplementation

Thrown when the implementation is the zero address.

error InvalidImplementation();

EmptyBytecode

Thrown when the bytecode is empty (i.e. of the implementation to deploy).

error EmptyBytecode();

DeployFailed

Thrown when the deployment of a contract (e.g. an implementation or proxy) fails.

error DeployFailed();

Paused

Thrown when any pausable function is called when the contract is paused.

error Paused();

IInitializable

Git Source

Functions

initialize

Initializes the contract with respect to the implementation.

function initialize(address implementation_, bytes calldata initializeCallData_) external;

Parameters

Errors

ZeroImplementation

Thrown when the implementation address is zero (i.e. address(0)).

error ZeroImplementation();

InitializationFailed

Thrown when the initialization fails.

error InitializationFailed(bytes errorData);

EmptyCode

Thrown when the implementation code is empty.

error EmptyCode(address implementation);

IProxy

Git Source

Errors

ZeroImplementation

Thrown when the implementation address is zero (i.e. address(0)).

error ZeroImplementation();

Factory

Git Source

Inherits: IFactory, Migratable, OZInitializable

This contract is used to deploy implementations and proxies deterministically, using create2, and is to only be deployed once on each chain. Implementations deployed use their own bytecode hash as their salt, so a unique bytecode (including constructor arguments) will have only one possible address. Proxies deployed use the sender's address combined with a salt of the sender's choosing as a final salt, and the constructor arguments are always the same (i.e. the "initializable implementation"), so an address has only 2 degrees of freedom. This is helpful for ensuring the address of a future/planned contract is constant, while the implementation is not yet finalized or deployed.

State Variables

parameterRegistry

The address of the parameter registry.

address public immutable parameterRegistry;

_FACTORY_STORAGE_LOCATION

bytes32 internal constant _FACTORY_STORAGE_LOCATION = 0x651b031aaeb8a5a65735ac2bad4001a08e08ce7e1a4736b27ec7d04baeb8f600;

Functions

_getFactoryStorage

function _getFactoryStorage() internal pure returns (FactoryStorage storage $);

whenNotPaused

modifier whenNotPaused();

constructor

Constructor that deploys the initializable implementation.

The parameter registry must not be the zero address.

constructor(address parameterRegistry_);

Parameters

initialize

Initializes the contract.

function initialize() external initializer;

deployImplementation

Deploys an implementation contract.

function deployImplementation(bytes calldata bytecode_) external whenNotPaused returns (address implementation_);

Parameters

Returns

deployProxy

Deploys a proxy contract.

function deployProxy(address implementation_, bytes32 salt_, bytes calldata initializeCallData_)
    external
    whenNotPaused
    returns (address proxy_);

Parameters

Returns

migrate

Initiates a migration of the proxy, in a way defined by the implementation.

Normally, the implementation has a way of determining the migrator that needs to be delegatecalled.

function migrate() external;

pausedParameterKey

The parameter registry key used to fetch the paused status.

function pausedParameterKey() public pure returns (string memory key_);

migratorParameterKey

The parameter registry key used to fetch the migrator.

function migratorParameterKey() public pure returns (string memory key_);

paused

The pause status.

function paused() external view returns (bool paused_);

initializableImplementation

The address of the first temporary implementation that proxies will proxy.

*This contract is the first proxied implementation of any proxy, and allows the factory to then set the proxy's actual implementation, and initialize it with respect to that actual implementation. This ensures that:

• The address of a proxy is only defined by the nonce, and not by the implementation it will proxy.
• No contracts are deployed that are not used.
• The proxy can be easily initialized with respect to the actual implementation, atomically.*

function initializableImplementation() external view returns (address initializableImplementation_);

computeImplementationAddress

Computes the address of an implementation contract that would be deployed from a given bytecode.

The address is determined only by the bytecode, and so the same bytecode results in the same address.

function computeImplementationAddress(bytes calldata bytecode_) external view returns (address implementation_);

Parameters

Returns

computeProxyAddress

Computes the address of a proxy contract that would be deployed from given a caller and salt.

The actual salt used to deploy the proxy via create2 is keccak256(abi.encodePacked(caller_, salt_)).

function computeProxyAddress(address caller_, bytes32 salt_) external view returns (address proxy_);

Parameters

Returns

_create2

Creates a contract via create2 and reverts if the deployment fails.

function _create2(bytes memory bytecode_, bytes32 salt_) internal returns (address deployed_);

_isZero

function _isZero(address input_) internal pure returns (bool isZero_);

_revertIfPaused

function _revertIfPaused() internal view;

Structs

FactoryStorage

The UUPS storage for the factory.

Note: storage-location: erc7201:xmtp.storage.Factory

struct FactoryStorage {
    bool paused;
    address initializableImplementation;
}

Properties

Initializable

Git Source

Inherits: IInitializable

This contract is expected to be the first and default implementation of a Proxy, so that any Proxy can have a constant constructor (and thus proxied implementation), despite remaining completely transparency, which is very helpful to allow consistency in address determinism regardless the final intended proxied implementation address. Thus, no Proxy should be left in a state of proxying this contract.

State Variables

_IMPLEMENTATION_SLOT

Storage slot with the address of the current implementation. keccak256('eip1967.proxy.implementation') - 1.

uint256 private constant _IMPLEMENTATION_SLOT = 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc;

Functions

initialize

Initializes the contract with respect to the implementation.

function initialize(address implementation_, bytes calldata initializeCallData_) external;

Parameters

Migrator

Git Source

State Variables

_IMPLEMENTATION_SLOT

Storage slot with the address of the current implementation. keccak256('eip1967.proxy.implementation') - 1.

uint256 private constant _IMPLEMENTATION_SLOT = 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc;

fromImplementation

The implementation to migrate proxies from.

address public immutable fromImplementation;

toImplementation

The implementation to migrate proxies to.

address public immutable toImplementation;

Functions

constructor

Constructs the contract such that it proxies calls to the given implementation.

constructor(address fromImplementation_, address toImplementation_);

Parameters

fallback

Migrates a proxy to the new implementation.

fallback() external;

Errors

ZeroFromImplementation

Thrown when the from implementation is the zero address.

error ZeroFromImplementation();

ZeroToImplementation

Thrown when the to implementation is the zero address.

error ZeroToImplementation();

UnexpectedImplementation

Thrown when the implementation is not the expected implementation.

error UnexpectedImplementation();

Proxy

Git Source

Inherits: IProxy

State Variables

_IMPLEMENTATION_SLOT

Storage slot with the address of the current implementation. keccak256('eip1967.proxy.implementation') - 1.

uint256 private constant _IMPLEMENTATION_SLOT = 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc;

Functions

constructor

Constructs the contract such that it proxies calls to the given implementation.

constructor(address implementation_);

Parameters

fallback

fallback() external payable;

Contents

• interfaces
• AppChainGateway
• AppChainParameterRegistry
• GroupMessageBroadcaster
• IdentityUpdateBroadcaster

Contents

• IArbSysLike
• ISettlementChainGatewayLike
• IAppChainGateway
• IAppChainParameterRegistry
• IGroupMessageBroadcaster
• IIdentityUpdateBroadcaster

IArbSysLike

Git Source

Functions

sendTxToL1

function sendTxToL1(address destination_, bytes calldata data_) external payable returns (uint256 messageId_);

ISettlementChainGatewayLike

Git Source

Functions

receiveWithdrawal

function receiveWithdrawal(address recipient_) external;

receiveWithdrawalIntoUnderlying

function receiveWithdrawalIntoUnderlying(address recipient_) external;

IAppChainGateway

Git Source

Inherits: IMigratable, IRegistryParametersErrors

The AppChainGateway exposes the ability to receive parameters from the settlement chain gateway.

Functions

initialize

Initializes the parameter registry, as used by a proxy contract.

function initialize() external;

withdraw

Withdraws funds from the app chain to the settlement chain.

function withdraw(address recipient_) external payable;

Parameters

withdrawIntoUnderlying

Withdraws funds from the app chain to the settlement chain, unwrapped as underlying fee token.

function withdrawIntoUnderlying(address recipient_) external payable;

Parameters

receiveDeposit

Receives funds from the settlement chain.

The recipient will receive the forwarded amount attached as payable.

function receiveDeposit(address recipient_) external payable;

Parameters

receiveParameters

Receives parameters from the settlement chain.

The caller must be the settlement chain gateway's L3 alias address.

function receiveParameters(uint256 nonce_, string[] calldata keys_, bytes32[] calldata values_) external;

Parameters

updatePauseStatus

Updates the pause status.

Ensures the new pause status is not equal to the old pause status.

function updatePauseStatus() external;

parameterRegistry

The address of the parameter registry.

function parameterRegistry() external view returns (address parameterRegistry_);

settlementChainGateway

The address of the settlement chain gateway.

function settlementChainGateway() external view returns (address settlementChainGateway_);

settlementChainGatewayAlias

The L3 alias address of the settlement chain gateway (i.e. the expected caller of the receiveParameters function).

function settlementChainGatewayAlias() external view returns (address settlementChainGatewayAlias_);

migratorParameterKey

The parameter registry key used to fetch the migrator.

function migratorParameterKey() external pure returns (string memory key_);

pausedParameterKey

The parameter registry key used to fetch the paused status.

function pausedParameterKey() external pure returns (string memory key_);

paused

The pause status.

function paused() external view returns (bool paused_);

Events

ParametersReceived

Emitted when parameters are received from the settlement chain.

The values are not emitted, as they are not relevant to indexing this contract, and will be emitted by the app chain parameter registry.

event ParametersReceived(uint256 indexed nonce, string[] keys);

Parameters

DepositReceived

Emitted when funds are deposited from the settlement chain.

event DepositReceived(address indexed recipient, uint256 amount);

Parameters

PauseStatusUpdated

Emitted when the pause status is set.

event PauseStatusUpdated(bool indexed paused);

Parameters

Withdrawal

Emitted when funds are withdrawn from the app chain.

event Withdrawal(uint256 indexed messageId, address indexed recipient, uint256 amount);

Parameters

Errors

ZeroParameterRegistry

Thrown when the parameter registry address is zero (i.e. address(0)).

error ZeroParameterRegistry();

ZeroSettlementChainGateway

Thrown when the settlement chain gateway address is zero (i.e. address(0)).

error ZeroSettlementChainGateway();

NotSettlementChainGateway

Thrown when the caller is not the settlement chain gateway (i.e. its L3 alias address).

error NotSettlementChainGateway();

ZeroRecipient

Thrown when the recipient address is zero (i.e. address(0)).

error ZeroRecipient();

ZeroWithdrawalAmount

Thrown when the withdrawal amount is zero.

error ZeroWithdrawalAmount();

NoChange

Thrown when there is no change to an updated parameter.

error NoChange();

Paused

Thrown when any pausable function is called when the contract is paused.

error Paused();

TransferFailed

Thrown when the transfer fails.

error TransferFailed();

IAppChainParameterRegistry

Git Source

Inherits: IParameterRegistry

An AppChainParameterRegistry is a parameter registry used by the protocol contracts on an app chain.

IGroupMessageBroadcaster

Git Source

Inherits: IPayloadBroadcaster

The GroupMessageBroadcaster is a group message payload broadcaster on an app chain.

Functions

addMessage

Adds a message to the group.

Ensures the payload length is within the allowed range and increments the sequence ID.

function addMessage(bytes16 groupId_, bytes calldata message_) external;

Parameters

bootstrapMessages

Bootstraps messages to satisfy a migration.

function bootstrapMessages(bytes16[] calldata groupIds_, bytes[] calldata messages_, uint64[] calldata sequenceIds_)
    external;

Parameters

Events

MessageSent

Emitted when a message is sent.

event MessageSent(bytes16 indexed groupId, bytes message, uint64 indexed sequenceId);

Parameters

Errors

ArrayLengthMismatch

Thrown when the lengths of input arrays don't match.

error ArrayLengthMismatch();

EmptyArray

Thrown when a supplied array is empty.

error EmptyArray();

IIdentityUpdateBroadcaster

Git Source

Inherits: IPayloadBroadcaster

The IdentityUpdateBroadcaster is an identity payload broadcaster on an app chain.

Functions

addIdentityUpdate

Adds an identity update to a specific inbox ID.

Ensures the payload length is within the allowed range and increments the sequence ID.

function addIdentityUpdate(bytes32 inboxId_, bytes calldata identityUpdate_) external;

Parameters

bootstrapIdentityUpdates

Bootstraps identity updates to satisfy a migration.

function bootstrapIdentityUpdates(
    bytes32[] calldata inboxIds_,
    bytes[] calldata identityUpdates_,
    uint64[] calldata sequenceIds_
) external;

Parameters

Events

IdentityUpdateCreated

Emitted when an identity update is sent.

event IdentityUpdateCreated(bytes32 indexed inboxId, bytes update, uint64 indexed sequenceId);

Parameters

Errors

ArrayLengthMismatch

Thrown when the lengths of input arrays don't match.

error ArrayLengthMismatch();

EmptyArray

Thrown when a supplied array is empty.

error EmptyArray();

AppChainGateway

Git Source

Inherits: IAppChainGateway, Migratable, Initializable

The AppChainGateway exposes the ability to receive parameters from the settlement chain gateway, and set them at the parameter registry on this same app chain. Currently, it is a receiver-only contract.

State Variables

_ARB_SYS

The Arbitrum system precompile address.

address internal constant _ARB_SYS = 0x0000000000000000000000000000000000000064;

parameterRegistry

The address of the parameter registry.

address public immutable parameterRegistry;

settlementChainGateway

The address of the settlement chain gateway.

address public immutable settlementChainGateway;

settlementChainGatewayAlias

The L3 alias address of the settlement chain gateway (i.e. the expected caller of the receiveParameters function).

address public immutable settlementChainGatewayAlias;

_APP_CHAIN_GATEWAY_STORAGE_LOCATION

bytes32 internal constant _APP_CHAIN_GATEWAY_STORAGE_LOCATION =
    0xf7630100a9c96f7b07fb982ff1e6dad8abbb961bacff2e820fac4ea93b280300;

Functions

_getAppChainGatewayStorage

function _getAppChainGatewayStorage() internal pure returns (AppChainGatewayStorage storage $);

onlySettlementChainGateway

Modifier to ensure the caller is the settlement chain gateway (i.e. its L3 alias address).

modifier onlySettlementChainGateway();

whenNotPaused

modifier whenNotPaused();

constructor

Constructor for the implementation contract, such that the implementation cannot be initialized.

The parameter registry and settlement chain gateway must not be the zero address.

The parameter registry, settlement chain gateway, and the settlement chain gateway alias are immutable so that they are inlined in the contract code, and have minimal gas cost.

constructor(address parameterRegistry_, address settlementChainGateway_);

Parameters

initialize

Initializes the parameter registry, as used by a proxy contract.

function initialize() external initializer;

withdraw

Withdraws funds from the app chain to the settlement chain.

function withdraw(address recipient_) external payable whenNotPaused;

Parameters

withdrawIntoUnderlying

Withdraws funds from the app chain to the settlement chain, unwrapped as underlying fee token.

function withdrawIntoUnderlying(address recipient_) external payable whenNotPaused;

Parameters

receiveDeposit

Receives funds from the settlement chain.

The recipient will receive the forwarded amount attached as payable.

function receiveDeposit(address recipient_) external payable;

Parameters

receiveParameters

Receives parameters from the settlement chain.

The caller must be the settlement chain gateway's L3 alias address.

function receiveParameters(uint256 nonce_, string[] calldata keys_, bytes32[] calldata values_)
    external
    onlySettlementChainGateway;

Parameters

updatePauseStatus

Updates the pause status.

Ensures the new pause status is not equal to the old pause status.

function updatePauseStatus() external;

migrate

Initiates a migration of the proxy, in a way defined by the implementation.

Normally, the implementation has a way of determining the migrator that needs to be delegatecalled.

function migrate() external;

migratorParameterKey

The parameter registry key used to fetch the migrator.

function migratorParameterKey() public pure returns (string memory key_);

pausedParameterKey

The parameter registry key used to fetch the paused status.

function pausedParameterKey() public pure returns (string memory key_);

paused

The pause status.

function paused() external view returns (bool paused_);

_withdraw

function _withdraw(address recipient_, bytes4 selector_) internal;

_isZero

function _isZero(address input_) internal pure returns (bool isZero_);

_revertIfNotSettlementChainGateway

function _revertIfNotSettlementChainGateway() internal view;

_revertIfPaused

function _revertIfPaused() internal view;

Structs

AppChainGatewayStorage

The UUPS storage for the app chain gateway.

Note: storage-location: erc7201:xmtp.storage.AppChainGateway

struct AppChainGatewayStorage {
    bool paused;
    mapping(string key => uint256 nonce) keyNonces;
}

Properties

AppChainParameterRegistry

Git Source

Inherits: IAppChainParameterRegistry, ParameterRegistry

An AppChainParameterRegistry is a parameter registry used by the protocol contracts on an app chain.

Functions

migratorParameterKey

The parameter registry key used to fetch the migrator.

Uniquely, the parameter registry uses itself, so the key-value pair is stored in the contract itself.

function migratorParameterKey()
    public
    pure
    override(IParameterRegistry, ParameterRegistry)
    returns (string memory key_);

Returns

adminParameterKey

The parameter registry key used to fetch the status of an admin.

Uniquely, the parameter registry uses itself, so the key-value pair is stored in the contract itself.

function adminParameterKey() public pure override(IParameterRegistry, ParameterRegistry) returns (string memory key_);

Returns

GroupMessageBroadcaster

Git Source

Inherits: IGroupMessageBroadcaster, PayloadBroadcaster

A GroupMessageBroadcaster is a group message payload broadcaster on an app chain.

Functions

constructor

Constructor for the implementation contract, such that the implementation cannot be initialized.

constructor(address parameterRegistry_) PayloadBroadcaster(parameterRegistry_);

Parameters

addMessage

Adds a message to the group.

Ensures the payload length is within the allowed range and increments the sequence ID.

function addMessage(bytes16 groupId_, bytes calldata message_) external;

Parameters

bootstrapMessages

Bootstraps messages to satisfy a migration.

function bootstrapMessages(bytes16[] calldata groupIds_, bytes[] calldata messages_, uint64[] calldata sequenceIds_)
    external;

Parameters

minPayloadSizeParameterKey

The parameter registry key used to fetch the minimum payload size.

function minPayloadSizeParameterKey()
    public
    pure
    override(IPayloadBroadcaster, PayloadBroadcaster)
    returns (string memory key_);

maxPayloadSizeParameterKey

The parameter registry key used to fetch the maximum payload size.

function maxPayloadSizeParameterKey()
    public
    pure
    override(IPayloadBroadcaster, PayloadBroadcaster)
    returns (string memory key_);

migratorParameterKey

The parameter registry key used to fetch the migrator.

function migratorParameterKey()
    public
    pure
    override(IPayloadBroadcaster, PayloadBroadcaster)
    returns (string memory key_);

pausedParameterKey

The parameter registry key used to fetch the paused status.

function pausedParameterKey()
    public
    pure
    override(IPayloadBroadcaster, PayloadBroadcaster)
    returns (string memory key_);

payloadBootstrapperParameterKey

The parameter registry key used to fetch the payload bootstrapper.

function payloadBootstrapperParameterKey()
    public
    pure
    override(IPayloadBroadcaster, PayloadBroadcaster)
    returns (string memory key_);

IdentityUpdateBroadcaster

Git Source

Inherits: IIdentityUpdateBroadcaster, PayloadBroadcaster

An IdentityUpdateBroadcaster is an identity payload broadcaster on an app chain.

Functions

constructor

Constructor for the implementation contract, such that the implementation cannot be initialized.

constructor(address parameterRegistry_) PayloadBroadcaster(parameterRegistry_);

Parameters

addIdentityUpdate

Adds an identity update to a specific inbox ID.

Ensures the payload length is within the allowed range and increments the sequence ID.

function addIdentityUpdate(bytes32 inboxId_, bytes calldata identityUpdate_) external;

Parameters

bootstrapIdentityUpdates

Bootstraps identity updates to satisfy a migration.

function bootstrapIdentityUpdates(
    bytes32[] calldata inboxIds_,
    bytes[] calldata identityUpdates_,
    uint64[] calldata sequenceIds_
) external;

Parameters

minPayloadSizeParameterKey

The parameter registry key used to fetch the minimum payload size.

function minPayloadSizeParameterKey()
    public
    pure
    override(IPayloadBroadcaster, PayloadBroadcaster)
    returns (string memory key_);

maxPayloadSizeParameterKey

The parameter registry key used to fetch the maximum payload size.

function maxPayloadSizeParameterKey()
    public
    pure
    override(IPayloadBroadcaster, PayloadBroadcaster)
    returns (string memory key_);

migratorParameterKey

The parameter registry key used to fetch the migrator.

function migratorParameterKey()
    public
    pure
    override(IPayloadBroadcaster, PayloadBroadcaster)
    returns (string memory key_);

pausedParameterKey

The parameter registry key used to fetch the paused status.

function pausedParameterKey()
    public
    pure
    override(IPayloadBroadcaster, PayloadBroadcaster)
    returns (string memory key_);

payloadBootstrapperParameterKey

The parameter registry key used to fetch the payload bootstrapper.

function payloadBootstrapperParameterKey()
    public
    pure
    override(IPayloadBroadcaster, PayloadBroadcaster)
    returns (string memory key_);

Contents

• interfaces
• AddressAliasHelper
• ParameterKeys
• RegistryParameters
• SequentialMerkleProofs

Contents

• IParameterRegistryLike
• IParameterKeysErrors
• IRegistryParametersErrors
• ISequentialMerkleProofsErrors

IParameterRegistryLike

Git Source

This is the minimal interface needed by contracts within this subdirectory.

Functions

set

function set(string calldata key_, bytes32 value_) external;

get

function get(string calldata key_) external view returns (bytes32 value_);

get

function get(string[] calldata keys_) external view returns (bytes32[] memory values_);

IParameterKeysErrors

Git Source

This interface should be inherited by any contract that uses the Parameter Keys library in order to expose the errors that may be thrown by the library.

Errors

NoKeyComponents

Thrown when no key components are provided.

error NoKeyComponents();

IRegistryParametersErrors

Git Source

This interface should be inherited by any contract that uses the Registry Parameters library in order to expose the errors that may be thrown by the library.

Errors

ParameterOutOfTypeBounds

Thrown when the parameter is out of type bounds.

error ParameterOutOfTypeBounds();

ISequentialMerkleProofsErrors

Git Source

This interface should be inherited by any contract that uses the Sequential Merkle Proofs library in order to expose the errors that may be thrown by the library.

Errors

NoLeaves

Thrown when no leaves are provided.

error NoLeaves();

InvalidBitCount32Input

Thrown when the input to _bitCount32 is greater than type(uint32).max.

error InvalidBitCount32Input();

InvalidProof

Thrown when the proof is invalid.

error InvalidProof();

NoProofElements

Thrown when no proof elements are provided.

error NoProofElements();

InvalidLeafCount

Thrown when the leaf count is greater than type(uint32).max.

error InvalidLeafCount();

AddressAliasHelper

Git Source

Roll-up layer address aliasing as per EIP-6735 (see https://eips.ethereum.org/EIPS/eip-6735).

State Variables

OFFSET

uint160 internal constant OFFSET = uint160(0x1111000000000000000000000000000000001111);

Functions

toAlias

Convert a settlement layer address to roll-up layer alias address.

function toAlias(address account_) internal pure returns (address alias_);

Parameters

Returns

fromAlias

Convert a roll-up layer alias address to settlement layer address.

function fromAlias(address alias_) internal pure returns (address account_);

Parameters

Returns

ParameterKeys

Git Source

A parameter key is a string that uniquely identifies a parameter.

State Variables

DELIMITER

The delimiter used to combine key components.

string internal constant DELIMITER = ".";

Functions

getKey

Combines an array of key components into a single key, using the delimiter.

function getKey(string[] memory keyComponents_) internal pure returns (string memory key_);

Parameters

Returns

combineKeyComponents

function combineKeyComponents(string memory left_, string memory right_) internal pure returns (string memory key_);

addressToKeyComponent

function addressToKeyComponent(address account_) internal pure returns (string memory keyComponent_);

uint256ToKeyComponent

function uint256ToKeyComponent(uint256 value_) internal pure returns (string memory keyComponent_);

RegistryParameters

Git Source

Exposes getters, setters, and parsers for parameters stored in a parameter registry.

Functions

setRegistryParameter

function setRegistryParameter(address parameterRegistry_, string memory key_, bytes32 value_) internal;

getRegistryParameters

function getRegistryParameters(address parameterRegistry_, string[] memory keys_)
    internal
    view
    returns (bytes32[] memory value_);

getRegistryParameter

function getRegistryParameter(address parameterRegistry_, string memory key_) internal view returns (bytes32 value_);

getAddressParameter

function getAddressParameter(address parameterRegistry_, string memory key_) internal view returns (address output_);

getBoolParameter

function getBoolParameter(address parameterRegistry_, string memory key_) internal view returns (bool output_);

getUint8Parameter

function getUint8Parameter(address parameterRegistry_, string memory key_) internal view returns (uint8 output_);

getUint16Parameter

function getUint16Parameter(address parameterRegistry_, string memory key_) internal view returns (uint16 output_);

getUint32Parameter

function getUint32Parameter(address parameterRegistry_, string memory key_) internal view returns (uint32 output_);

getUint64Parameter

function getUint64Parameter(address parameterRegistry_, string memory key_) internal view returns (uint64 output_);

getUint96Parameter

function getUint96Parameter(address parameterRegistry_, string memory key_) internal view returns (uint96 output_);

getAddressFromRawParameter

function getAddressFromRawParameter(bytes32 parameter_) internal pure returns (address output_);

SequentialMerkleProofs

Git Source

A sequential Merkle proof is a proof that leaves appear sequentially in a Merkle tree.

State Variables

EMPTY_TREE_ROOT

bytes32 internal constant EMPTY_TREE_ROOT = 0;

LEAF_PREFIX

The leaf prefix used to hash to a leaf ("leaf|").

bytes5 internal constant LEAF_PREFIX = 0x6c6561667c;

NODE_PREFIX

The node prefix used to hash to a node ("node|").

bytes5 internal constant NODE_PREFIX = 0x6e6f64657c;

ROOT_PREFIX

The root prefix used to hash to a root.

bytes5 internal constant ROOT_PREFIX = 0x726f6f747c;

Functions

verify

Verifies a sequential Merkle proof.

proofElements_[0] is the total number of leaves in the Merkle tree, the rest are the decommitments.

Can also revert with an array out-of-bounds access panic.

function verify(bytes32 root_, uint256 startingIndex_, bytes[] calldata leaves_, bytes32[] calldata proofElements_)
    internal
    pure;

Parameters

getRoot

Gets the root of a sequential Merkle proof.

proofElements_[0] is the total number of leaves in the Merkle tree, the rest are the decommitments.

Can also revert with an array out-of-bounds access panic.

function getRoot(uint256 startingIndex_, bytes[] calldata leaves_, bytes32[] calldata proofElements_)
    internal
    pure
    returns (bytes32 root_);

Parameters

getLeafCount

Extracts the leaf count from a sequential Merkle proof, without verifying the proof.

proofElements_[0] is the total number of leaves in the Merkle tree.

Does not verify the proof. Only extracts the leaf count from the proof elements.

function getLeafCount(bytes32[] calldata proofElements_) internal pure returns (uint32 leafCount_);

Parameters

_bitCount32

Counts number of set bits (1's) in 32-bit unsigned integer.

See https://en.wikipedia.org/wiki/Hamming_weight implementation popcount64b.

Literals are inlined as they are very specific to this algorithm/function, and actually improve readability, given their patterns.

function _bitCount32(uint256 n_) internal pure returns (uint256 bitCount_);

Parameters

Returns

_roundUpToPowerOf2

Rounds a 32-bit unsigned integer up to the nearest power of 2.

Literals are inlined as they are very specific to this algorithm/function, and actually improve readability, given their patterns.

function _roundUpToPowerOf2(uint256 n_) internal pure returns (uint256 powerOf2_);

Parameters

Returns

_getBalancedLeafCount

Gets the balanced leaf count for a sequential Merkle proof.

function _getBalancedLeafCount(uint256 leafCount_) internal pure returns (uint256 balancedLeafCount_);

Parameters

Returns

_getRoot

Gets the root of a sequential Merkle proof.

proofElements_[0] is the total number of leaves in the Merkle tree, the rest are the decommitments.

function _getRoot(uint256 startingIndex_, bytes32[] memory hashes_, bytes32[] calldata proofElements_)
    internal
    pure
    returns (bytes32 root_);

Parameters

_isEven

The following variables are used while iterating through the root reconstruction from the proof.

readIndex_ is the index of hashes_ circular queue currently being read from.

writeIndex_ is the index of hashes_ circular queue currently being written to.

proofIndex_ is the index of proofElements_ array that is to be read from.

upperBound_ is the rightmost tree index, of the current level of the tree, such that all nodes to the right, if any, are non-existent.

lowestTreeIndex_ is the tree index, of the current level of the tree, of the leftmost node we have.

highestLeafNodeIndex_ is the tree index of the rightmost leaf node we have.

nodeIndex_ is the tree index of the current node we are handling.

nextNodeIndex_ is the tree index of the next node we may be handling.

root_ will temporarily be used as the right part of the node pair hash, it is being used to save much needed stack space.

left_ is the left part of the node pair hash.

function _isEven(uint256 n_) internal pure returns (bool isEven_);

_isLeftAnExistingHash

Checks if the left part of the hash should be an existing computed hash.

function _isLeftAnExistingHash(uint256 nodeIndex_, uint256 nextNodeIndex_)
    internal
    pure
    returns (bool isLeftAnExistingHash_);

Parameters

Returns

_hashLeaf

Hashes a leaf of arbitrary size into a 32-byte leaf node.

function _hashLeaf(bytes calldata leaf_) internal pure returns (bytes32 hash_);

Parameters

Returns

_hashNodePair

Hashes a pair of 32-byte nodes into a 32-byte parent node.

function _hashNodePair(bytes32 leftNode_, bytes32 rightNode_) internal pure returns (bytes32 hash_);

Parameters

Returns

_hashPairlessNode

Hashes a 32-byte node, without a right paired node, into a 32-byte parent node.

function _hashPairlessNode(bytes32 node_) internal pure returns (bytes32 hash_);

Parameters

Returns

_hashRoot

Hashes the topmost 32-byte node in the tree, combined with the tree's leaf count, into a 32-byte root.

function _hashRoot(uint256 leafCount_, bytes32 node_) internal pure returns (bytes32 hash_);

Parameters

Returns

_getReversedLeafNodesFromLeaves

Get leaf nodes from arbitrary size leaves in calldata, in reverse order.

function _getReversedLeafNodesFromLeaves(bytes[] calldata leaves_)
    internal
    pure
    returns (bytes32[] memory leafNodes_);

Contents

• interfaces
• DepositSplitter
• DistributionManager
• FeeToken
• NodeRegistry
• PayerRegistry
• PayerReportManager
• RateRegistry
• SettlementChainGateway
• SettlementChainParameterRegistry

Contents

• IERC20Like
• IERC20InboxLike
• IAppChainGatewayLike
• INodeRegistryLike
• IPayerRegistryLike
• IPayerReportManagerLike
• IPermitErc20Like
• IFeeTokenLike
• ISettlementChainGatewayLike
• IDepositSplitter
• IDistributionManager
• IFeeToken
• INodeRegistry
• IPayerRegistry
• IPayerReportManager
• IRateRegistry
• ISettlementChainGateway
• ISettlementChainParameterRegistry

IERC20Like

Git Source

This is the minimal interface needed by contracts within this subdirectory.

Functions

approve

function approve(address spender_, uint256 amount_) external returns (bool success_);

transfer

function transfer(address recipient_, uint256 amount_) external returns (bool success_);

transferFrom

function transferFrom(address sender_, address recipient_, uint256 amount_) external returns (bool success_);

balanceOf

function balanceOf(address account_) external view returns (uint256 balance_);

decimals

function decimals() external view returns (uint8 decimals_);

IERC20InboxLike

Git Source

This is the minimal interface needed by contracts within this subdirectory.

Functions

sendContractTransaction

Sends a contract transaction to the L2 inbox, with a single-try execution on the L3.

function sendContractTransaction(
    uint256 gasLimit_,
    uint256 maxFeePerGas_,
    address to_,
    uint256 value_,
    bytes calldata data_
) external returns (uint256 messageNumber_);

createRetryableTicket

Put a message in the L2 inbox that can be re-executed for some fixed amount of time if it reverts.

All tokenTotalFeeAmount will be deposited to callValueRefundAddress on L2.

Gas limit and maxFeePerGas should not be set to 1 as that is used to trigger the RetryableData error

In case of native token having non-18 decimals: tokenTotalFeeAmount is denominated in native token's decimals. All other value params - l2CallValue, maxSubmissionCost and maxFeePerGas are denominated in child chain's native 18 decimals.

tokenTotalFeeAmount_ (converted to 18 decimals on the L2) must be greater than or equal to the sum of gasLimit_ multiplied by maxFeePerGas_ and maxSubmissionCost_.

Retryable ticket's submission fee is not charged when ERC20 token is used to pay for fees (see https://github.com/OffchainLabs/nitro-contracts/blob/v3.1.0/src/bridge/ERC20Inbox.sol#L118).

function createRetryableTicket(
    address to_,
    uint256 l2CallValue_,
    uint256 maxSubmissionCost_,
    address excessFeeRefundAddress_,
    address callValueRefundAddress_,
    uint256 gasLimit_,
    uint256 maxFeePerGas_,
    uint256 tokenTotalFeeAmount_,
    bytes calldata data_
) external returns (uint256 messageNumber_);

Parameters

Returns

depositERC20

Deposits an ERC20 token into the L2 inbox, to be sent to the L3 where it is the gas token of that chain.

function depositERC20(uint256 amount_) external returns (uint256 messageNumber_);

calculateRetryableSubmissionFee

Calculates the submission fee for a retryable ticket.

function calculateRetryableSubmissionFee(uint256 dataLength_, uint256 baseFee_)
    external
    view
    returns (uint256 submissionFee_);

IAppChainGatewayLike

Git Source

This is the minimal interface needed by contracts within this subdirectory.

Functions

receiveDeposit

function receiveDeposit(address recipient_) external payable;

receiveParameters

function receiveParameters(uint256 nonce_, string[] calldata keys_, bytes32[] calldata values_) external;

INodeRegistryLike

Git Source

This is the minimal interface needed by contracts within this subdirectory.

Functions

canonicalNodesCount

function canonicalNodesCount() external view returns (uint8 canonicalNodesCount_);

getIsCanonicalNode

function getIsCanonicalNode(uint32 nodeId_) external view returns (bool isCanonicalNode_);

getSigner

function getSigner(uint32 nodeId_) external view returns (address signer_);

ownerOf

function ownerOf(uint256 nodeId_) external view returns (address owner_);

IPayerRegistryLike

Git Source

This is the minimal interface needed by contracts within this subdirectory.

Functions

deposit

function deposit(address payer_, uint96 amount_) external;

settleUsage

function settleUsage(bytes32 payerReportId_, PayerFee[] calldata payerFees_) external returns (uint96 feesSettled_);

sendExcessToFeeDistributor

function sendExcessToFeeDistributor() external returns (uint96 excess_);

Structs

PayerFee

struct PayerFee {
    address payer;
    uint96 fee;
}

IPayerReportManagerLike

Git Source

This is the minimal interface needed by contracts within this subdirectory.

Functions

getPayerReports

function getPayerReports(uint32[] calldata originatorNodeIds_, uint256[] calldata payerReportIndices_)
    external
    view
    returns (PayerReport[] memory payerReports_);

Structs

PayerReport

struct PayerReport {
    uint64 startSequenceId;
    uint64 endSequenceId;
    uint96 feesSettled;
    uint32 offset;
    bool isSettled;
    uint16 protocolFeeRate;
    bytes32 payersMerkleRoot;
    uint32[] nodeIds;
}

IPermitErc20Like

Git Source

This is the minimal interface needed by contracts within this subdirectory.

Functions

permit

function permit(address owner_, address spender_, uint256 value_, uint256 deadline_, uint8 v_, bytes32 r_, bytes32 s_)
    external;

IFeeTokenLike

Git Source

This is the minimal interface needed by contracts within this subdirectory.

Functions

deposit

function deposit(uint256 amount_) external;

withdrawTo

function withdrawTo(address recipient_, uint256 amount_) external returns (bool success_);

underlying

function underlying() external view returns (address underlying_);

ISettlementChainGatewayLike

Git Source

This is the minimal interface needed by contracts within this subdirectory.

Functions

deposit

function deposit(uint256 chainId_, address recipient_, uint256 amount_, uint256 gasLimit_, uint256 maxFeePerGas_)
    external;

IDepositSplitter

Git Source

This interface exposes functionality for splitting deposits between the Payer Registry and App Chain.

Functions

deposit

Deposits payerRegistryAmount_ fee tokens into the Payer Registry for payer_, and appChainAmount_ fee tokens into the App Chain for appChainRecipient_.

function deposit(
    address payer_,
    uint96 payerRegistryAmount_,
    address appChainRecipient_,
    uint96 appChainAmount_,
    uint256 appChainGasLimit_,
    uint256 appChainMaxFeePerGas_
) external;

Parameters

depositWithPermit

Deposits payerRegistryAmount_ fee tokens into the Payer Registry for payer_, and appChainAmount_ fee tokens into the App Chain for appChainRecipient_.

function depositWithPermit(
    address payer_,
    uint96 payerRegistryAmount_,
    address appChainRecipient_,
    uint96 appChainAmount_,
    uint256 appChainGasLimit_,
    uint256 appChainMaxFeePerGas_,
    uint256 deadline_,
    uint8 v_,
    bytes32 r_,
    bytes32 s_
) external;

Parameters

depositFromUnderlying

Deposits payerRegistryAmount_ fee tokens into the Payer Registry for payer_, and appChainAmount_ fee tokens into the App Chain for appChainRecipient_, wrapping them from underlying fee tokens.

function depositFromUnderlying(
    address payer_,
    uint96 payerRegistryAmount_,
    address appChainRecipient_,
    uint96 appChainAmount_,
    uint256 appChainGasLimit_,
    uint256 appChainMaxFeePerGas_
) external;

Parameters

depositFromUnderlyingWithPermit

Deposits payerRegistryAmount_ fee tokens into the Payer Registry for payer_, and appChainAmount_ fee tokens into the App Chain for appChainRecipient_, wrapping them from underlying fee tokens.

function depositFromUnderlyingWithPermit(
    address payer_,
    uint96 payerRegistryAmount_,
    address appChainRecipient_,
    uint96 appChainAmount_,
    uint256 appChainGasLimit_,
    uint256 appChainMaxFeePerGas_,
    uint256 deadline_,
    uint8 v_,
    bytes32 r_,
    bytes32 s_
) external;

Parameters

appChainId

The app chain ID.

function appChainId() external view returns (uint256 appChainId_);

feeToken

The address of the fee token contract used for deposits.

function feeToken() external view returns (address feeToken_);

payerRegistry

The address of the payer registry.

function payerRegistry() external view returns (address payerRegistry_);

settlementChainGateway

The address of the settlement chain gateway.

function settlementChainGateway() external view returns (address settlementChainGateway_);

Errors

TransferFromFailed

Thrown when the ERC20.transferFrom call fails.

This is an identical redefinition of SafeTransferLib.TransferFromFailed.

error TransferFromFailed();

ZeroFeeToken

Thrown when the fee token is the zero address.

error ZeroFeeToken();

ZeroPayerRegistry

Thrown when the payer registry is the zero address.

error ZeroPayerRegistry();

ZeroSettlementChainGateway

Thrown when the settlement chain gateway is the zero address.

error ZeroSettlementChainGateway();

ZeroAppChainId

Thrown when the app chain ID is zero.

error ZeroAppChainId();

ZeroTotalAmount

Thrown when the total amount is zero.

error ZeroTotalAmount();

IDistributionManager

Git Source

Inherits: IMigratable, IRegistryParametersErrors

This interface exposes functionality for distributing fees.

Functions

initialize

Initializes the contract.

function initialize() external;

claimProtocolFees

Claims protocol fees.

function claimProtocolFees(uint32[] calldata originatorNodeIds_, uint256[] calldata payerReportIndices_)
    external
    returns (uint96 claimed_);

Parameters

Returns

claim

Claims fees for a node for an array of payer reports.

The node IDs in originatorNodeIds_ don't need to be unique.

function claim(uint32 nodeId_, uint32[] calldata originatorNodeIds_, uint256[] calldata payerReportIndices_)
    external
    returns (uint96 claimed_);

Parameters

Returns

withdrawProtocolFees

Withdraws protocol fees.

function withdrawProtocolFees() external returns (uint96 withdrawn_);

Returns

withdrawProtocolFeesIntoUnderlying

Withdraws protocol fees, unwrapped as underlying token.

function withdrawProtocolFeesIntoUnderlying() external returns (uint96 withdrawn_);

Returns

withdraw

Withdraws fees for a node.

function withdraw(uint32 nodeId_, address recipient_) external returns (uint96 withdrawn_);

Parameters

Returns

withdrawIntoUnderlying

Withdraws fees for a node, unwrapped as underlying fee token.

function withdrawIntoUnderlying(uint32 nodeId_, address recipient_) external returns (uint96 withdrawn_);

Parameters

Returns

updatePauseStatus

Updates the pause status.

Ensures the new pause status is not equal to the old pause status.

function updatePauseStatus() external;

updateProtocolFeesRecipient

Updates the protocol fees recipient.

function updateProtocolFeesRecipient() external;

migratorParameterKey

The parameter registry key used to fetch the migrator.

function migratorParameterKey() external pure returns (string memory key_);

pausedParameterKey

The parameter registry key used to fetch the paused status.

function pausedParameterKey() external pure returns (string memory key_);

protocolFeesRecipientParameterKey

The parameter registry key used to fetch the protocol fees recipient.

function protocolFeesRecipientParameterKey() external pure returns (string memory key_);

parameterRegistry

The address of the parameter registry.

function parameterRegistry() external view returns (address parameterRegistry_);

nodeRegistry

The address of the node registry.

function nodeRegistry() external view returns (address nodeRegistry_);

payerReportManager

The address of the payer report manager.

function payerReportManager() external view returns (address payerReportManager_);

payerRegistry

The address of the payer registry.

function payerRegistry() external view returns (address payerRegistry_);

feeToken

The address of the fee token.

function feeToken() external view returns (address feeToken_);

protocolFeesRecipient

The address of the protocol fees recipient.

function protocolFeesRecipient() external view returns (address protocolFeesRecipient_);

owedProtocolFees

The amount of claimed protocol fees owed to the protocol.

function owedProtocolFees() external view returns (uint96 owedProtocolFees_);

totalOwedFees

The total amount of fees owed.

function totalOwedFees() external view returns (uint96 totalOwedFees_);

paused

The pause status.

function paused() external view returns (bool paused_);

getOwedFees

Returns the amount of claimed fees owed to a node.

function getOwedFees(uint32 nodeId_) external view returns (uint96 owedFees_);

Parameters

Returns

areProtocolFeesClaimed

Returns whether protocol fees associated with a settled payer report have been claimed.

function areProtocolFeesClaimed(uint32 originatorNodeId_, uint256 payerReportIndex_)
    external
    view
    returns (bool areClaimed_);

Parameters

Returns

areFeesClaimed

Returns whether a node has claimed fees associated with a settled payer report.

function areFeesClaimed(uint32 nodeId_, uint32 originatorNodeId_, uint256 payerReportIndex_)
    external
    view
    returns (bool areClaimed_);

Parameters

Returns

Events

ProtocolFeesClaim

Emitted when protocol fees are claimed.

event ProtocolFeesClaim(uint32 indexed originatorNodeId, uint256 indexed payerReportIndex, uint96 amount);

Parameters

Claim

Emitted when a claim is made.

event Claim(uint32 indexed nodeId, uint32 indexed originatorNodeId, uint256 indexed payerReportIndex, uint96 amount);

Parameters

ProtocolFeesWithdrawal

Emitted when protocol fees are withdrawn.

event ProtocolFeesWithdrawal(uint96 amount);

Parameters

Withdrawal

Emitted when a withdrawal of owed fees is made.

event Withdrawal(uint32 indexed nodeId, uint96 amount);

Parameters

PauseStatusUpdated

Emitted when the pause status is set.

event PauseStatusUpdated(bool indexed paused);

Parameters

ProtocolFeesRecipientUpdated

Emitted when the protocol fees recipient is updated.

event ProtocolFeesRecipientUpdated(address protocolFeesRecipient);

Parameters

Errors

ZeroParameterRegistry

Thrown when the parameter registry address is being set to zero (i.e. address(0)).

error ZeroParameterRegistry();

ZeroNodeRegistry

Thrown when the node registry address is being set to zero (i.e. address(0)).

error ZeroNodeRegistry();

ZeroPayerReportManager

Thrown when the payer report manager address is being set to zero (i.e. address(0)).

error ZeroPayerReportManager();

ZeroPayerRegistry

Thrown when the payer registry address is being set to zero (i.e. address(0)).

error ZeroPayerRegistry();

ZeroFeeToken

Thrown when the fee token address is being set to zero (i.e. address(0)).

error ZeroFeeToken();

NotNodeOwner

Thrown when the caller is not the owner of the specified node.

error NotNodeOwner();

ArrayLengthMismatch

Thrown when the lengths of input arrays don't match.

error ArrayLengthMismatch();

AlreadyClaimed

Thrown when a payer report has already been claimed.

error AlreadyClaimed(uint32 originatorNodeId, uint256 payerReportIndex);

PayerReportNotSettled

Thrown when the payer report is not settled.

error PayerReportNotSettled(uint32 originatorNodeId, uint256 payerReportIndex);

NotInPayerReport

Thrown when the node ID is not in a payer report.

error NotInPayerReport(uint32 originatorNodeId, uint256 payerReportIndex);

ZeroRecipient

Thrown when the recipient address is zero (i.e. address(0)).

error ZeroRecipient();

NoFeesOwed

Thrown when the node has no fees owed.

error NoFeesOwed();

ZeroAvailableBalance

Thrown when the contract's available balance is zero.

error ZeroAvailableBalance();

Paused

Thrown when any pausable function is called when the contract is paused.

error Paused();

NoChange

Thrown when there is no change to an updated parameter.

error NoChange();

ZeroProtocolFeeRecipient

Thrown when the protocol fees recipient address is zero (i.e. address(0)).

error ZeroProtocolFeeRecipient();

IFeeToken

Git Source

Inherits: IERC20, IERC20Metadata, IERC20Errors, IMigratable, IRegistryParametersErrors

This interface exposes functionality for wrapping and unwrapping tokens for use as fees in the protocol.

Functions

initialize

Initializes the contract.

function initialize() external;

permit

Sets value_ as the allowance of spender_ over owner_'s tokens, given `owner_'s signed approval.

function permit(address owner_, address spender_, uint256 value_, uint256 deadline_, uint8 v_, bytes32 r_, bytes32 s_)
    external;

Parameters

deposit

Deposits amount_ of the underlying token.

function deposit(uint256 amount_) external;

Parameters

depositWithPermit

Deposits amount_ of the underlying token, given owner_'s signed approval.

The permit signature must be for the underlying token, not for this token.

function depositWithPermit(uint256 amount_, uint256 deadline_, uint8 v_, bytes32 r_, bytes32 s_) external;

Parameters

depositFor

Deposits amount_ of the underlying token for recipient_.

This function conforms to ERC20Wrapper.depositFor.

function depositFor(address recipient_, uint256 amount_) external returns (bool success_);

Parameters

depositForWithPermit

Deposits amount_ of the underlying token for recipient_, given owner_'s signed approval.

The permit signature must be for the underlying token, not for this token.

This function conforms to ERC20Wrapper.depositFor.

function depositForWithPermit(address recipient_, uint256 amount_, uint256 deadline_, uint8 v_, bytes32 r_, bytes32 s_)
    external
    returns (bool success_);

Parameters

withdraw

Withdraws amount_ of the underlying token.

function withdraw(uint256 amount_) external;

Parameters

withdrawTo

Withdraws amount_ of the underlying token for recipient_.

This function conforms to ERC20Wrapper.withdrawTo.

function withdrawTo(address recipient_, uint256 amount_) external returns (bool success_);

Parameters

DOMAIN_SEPARATOR

Returns the EIP712 domain separator used in the encoding of a signed digest.

function DOMAIN_SEPARATOR() external view returns (bytes32 domainSeparator_);

PERMIT_TYPEHASH

Returns the EIP712 typehash used in the encoding of a signed digest for a permit.

function PERMIT_TYPEHASH() external pure returns (bytes32 permitTypehash_);

underlying

Returns the address of the underlying token.

function underlying() external view returns (address underlying_);

migratorParameterKey

The parameter registry key used to fetch the migrator.

function migratorParameterKey() external pure returns (string memory key_);

parameterRegistry

The address of the parameter registry.

function parameterRegistry() external view returns (address parameterRegistry_);

getPermitDigest

Returns the EIP-712 digest for a permit.

function getPermitDigest(address owner_, address spender_, uint256 value_, uint256 nonce_, uint256 deadline_)
    external
    view
    returns (bytes32 digest_);

Parameters

Returns

nonces

Returns the current nonce for owner_ that must be included for the next valid permit signature.

function nonces(address owner_) external view returns (uint256 nonce_);

Parameters

Returns

Errors

ZeroParameterRegistry

Thrown when the parameter registry address is being set to zero (i.e. address(0)).

error ZeroParameterRegistry();

ZeroUnderlying

Thrown when the underlying token address is being set to zero (i.e. address(0)).

error ZeroUnderlying();

ZeroAmount

Thrown when the amount to deposit or withdraw is zero.

error ZeroAmount();

ZeroRecipient

Thrown when the recipient address is zero (i.e. address(0)).

error ZeroRecipient();

TransferFailed

Thrown when the ERC20.transfer call fails.

This is an identical redefinition of SafeTransferLib.TransferFailed.

error TransferFailed();

TransferFromFailed

Thrown when the ERC20.transferFrom call fails.

This is an identical redefinition of SafeTransferLib.TransferFromFailed.

error TransferFromFailed();

INodeRegistry

Git Source

Inherits: IERC721, IERC721Metadata, IERC721Errors, IMigratable, IRegistryParametersErrors

This interface defines the ERC721-based registry for “nodes” in the system. Each node is minted as an NFT with a unique ID (starting at 100 and increasing by 100 with each new node). In addition to the standard ERC721 functionality, the contract supports node-specific features, including node property updates.

Functions

initialize

Initializes the contract.

function initialize() external;

addNode

Adds a new node to the registry and mints its corresponding ERC721 token.

Node IDs start at 100 and increase by 100 for each new node.

function addNode(address owner_, bytes calldata signingPublicKey_, string calldata httpAddress_)
    external
    returns (uint32 nodeId_, address signer_);

Parameters

Returns

addToNetwork

Adds a node to the canonical network.

function addToNetwork(uint32 nodeId_) external;

Parameters

removeFromNetwork

Removes a node from the canonical network.

function removeFromNetwork(uint32 nodeId_) external;

Parameters

setBaseURI

Set the base URI for the node NFTs.

function setBaseURI(string calldata baseURI_) external;

Parameters

setHttpAddress

Set the HTTP address of an existing node.

function setHttpAddress(uint32 nodeId_, string calldata httpAddress_) external;

Parameters

updateAdmin

Updates the admin by referring to the admin parameter from the parameter registry.

function updateAdmin() external;

updateMaxCanonicalNodes

Updates the max canonical nodes by referring to the max canonical nodes parameter from the parameter registry.

function updateMaxCanonicalNodes() external;

NODE_INCREMENT

The increment for node IDs, which allows for 100 shard node IDs per node in the future (modulus 100).

function NODE_INCREMENT() external pure returns (uint32 nodeIncrement_);

admin

The address of the admin.

function admin() external view returns (address admin_);

adminParameterKey

The parameter registry key used to fetch the admin.

function adminParameterKey() external pure returns (string memory key_);

maxCanonicalNodesParameterKey

The parameter registry key used to fetch the max canonical nodes.

function maxCanonicalNodesParameterKey() external pure returns (string memory key_);

migratorParameterKey

The parameter registry key used to fetch the migrator.

function migratorParameterKey() external pure returns (string memory key_);

parameterRegistry

The address of the parameter registry.

function parameterRegistry() external view returns (address parameterRegistry_);

maxCanonicalNodes

The maximum number of nodes that can be part of the canonical network.

function maxCanonicalNodes() external view returns (uint8 maxCanonicalNodes_);

canonicalNodesCount

The number of nodes that are part of the canonical network.

function canonicalNodesCount() external view returns (uint8 canonicalNodesCount_);

getAllNodes

Gets all nodes regardless of their health status.

function getAllNodes() external view returns (NodeWithId[] memory allNodes_);

Returns

getAllNodesCount

Gets the total number of nodes in the registry.

function getAllNodesCount() external view returns (uint32 nodeCount_);

Returns

getNode

Retrieves the details of a given node.

function getNode(uint32 nodeId_) external view returns (Node memory node_);

Parameters

Returns

getIsCanonicalNode

Retrieves whether a node is part of the canonical network.

function getIsCanonicalNode(uint32 nodeId_) external view returns (bool isCanonicalNode_);

Parameters

Returns

getSigner

Retrieves the signer of a node.

function getSigner(uint32 nodeId_) external view returns (address signer_);

Parameters

Returns

Events

AdminUpdated

Emitted when the admin is updated.

event AdminUpdated(address indexed admin);

Parameters

BaseURIUpdated

Emitted when the base URI is updated.

event BaseURIUpdated(string baseURI);

Parameters

HttpAddressUpdated

Emitted when the HTTP address for a node is updated.

event HttpAddressUpdated(uint32 indexed nodeId, string httpAddress);

Parameters

MaxCanonicalNodesUpdated

Emitted when the maximum number of canonical nodes is updated.

event MaxCanonicalNodesUpdated(uint8 maxCanonicalNodes);

Parameters

NodeAdded

Emitted when a new node is added and its NFT minted.

event NodeAdded(
    uint32 indexed nodeId, address indexed owner, address indexed signer, bytes signingPublicKey, string httpAddress
);

Parameters

NodeAddedToCanonicalNetwork

Emitted when a node is added to the canonical network.

event NodeAddedToCanonicalNetwork(uint32 indexed nodeId);

Parameters

NodeRemovedFromCanonicalNetwork

Emitted when a node is removed from the canonical network.

event NodeRemovedFromCanonicalNetwork(uint32 indexed nodeId);

Parameters

Errors

ZeroParameterRegistry

Thrown when the parameter registry address is being set to zero (i.e. address(0)).

error ZeroParameterRegistry();

FailedToAddNodeToCanonicalNetwork

Thrown when failing to add a node to the canonical network.

error FailedToAddNodeToCanonicalNetwork();

FailedToRemoveNodeFromCanonicalNetwork

Thrown when failing to remove a node from the canonical network.

error FailedToRemoveNodeFromCanonicalNetwork();

InvalidOwner

Thrown when an invalid owner is provided.

error InvalidOwner();

InvalidHttpAddress

Thrown when an invalid HTTP address is provided.

error InvalidHttpAddress();

InvalidSigningPublicKey

Thrown when an invalid signing public key is provided.

error InvalidSigningPublicKey();

InvalidURI

Thrown when an invalid URI is provided.

error InvalidURI();

MaxCanonicalNodesBelowCurrentCount

Thrown when trying to set max canonical nodes below current canonical count.

error MaxCanonicalNodesBelowCurrentCount();

MaxCanonicalNodesReached

Thrown when the maximum number of canonical nodes is reached.

error MaxCanonicalNodesReached();

NoChange

Thrown when there is no change to an updated parameter.

error NoChange();

NotAdmin

Thrown when the caller is not the admin.

error NotAdmin();

MaxNodesReached

Thrown when the maximum number of nodes is reached.

error MaxNodesReached();

NotNodeOwner

Thrown when the caller is not the node owner.

error NotNodeOwner();

Structs

Node

Struct representing a node in the registry.

struct Node {
    address signer;
    bool isCanonical;
    bytes signingPublicKey;
    string httpAddress;
}

Properties

NodeWithId

Struct representing a node with its ID.

struct NodeWithId {
    uint32 nodeId;
    Node node;
}

Properties

IPayerRegistry

Git Source

Inherits: IMigratable, IRegistryParametersErrors

This interface exposes functionality:

• for payers to deposit, request withdrawals, and finalize withdrawals of a fee token,
• for some settler contract to settle usage fees for payers,
• for anyone to send excess fee tokens in the contract to the fee distributor.

Functions

initialize

Initializes the contract.

function initialize() external;

deposit

Deposits amount_ fee tokens into the registry for payer_.

function deposit(address payer_, uint96 amount_) external;

Parameters

depositWithPermit

Deposits amount_ fee tokens into the registry for payer_, given caller's signed approval.

function depositWithPermit(address payer_, uint96 amount_, uint256 deadline_, uint8 v_, bytes32 r_, bytes32 s_)
    external;

Parameters

depositFromUnderlying

Deposits amount_ fee tokens into the registry for payer_, wrapping them from underlying fee tokens.

function depositFromUnderlying(address payer_, uint96 amount_) external;

Parameters

depositFromUnderlyingWithPermit

Deposits amount_ fee tokens into the registry for payer_, wrapping them from underlying fee tokens, given caller's signed approval.

function depositFromUnderlyingWithPermit(
    address payer_,
    uint96 amount_,
    uint256 deadline_,
    uint8 v_,
    bytes32 r_,
    bytes32 s_
) external;

Parameters

requestWithdrawal

Requests a withdrawal of amount_ fee tokens.

The caller must have enough balance to cover the withdrawal.

function requestWithdrawal(uint96 amount_) external;

Parameters

cancelWithdrawal

Cancels a pending withdrawal of fee tokens, returning the amount to the balance.

function cancelWithdrawal() external;

finalizeWithdrawal

Finalizes a pending withdrawal of fee tokens, transferring the amount to the recipient.

The caller must not be currently in debt.

function finalizeWithdrawal(address recipient_) external;

Parameters

finalizeWithdrawalIntoUnderlying

Finalizes a pending withdrawal of fee tokens, unwrapping the amount into underlying fee tokens to the recipient.

The caller must not be currently in debt.

function finalizeWithdrawalIntoUnderlying(address recipient_) external;

Parameters

settleUsage

Settles the usage fees for a list of payers.

function settleUsage(bytes32 payerReportId_, PayerFee[] calldata payerFees_) external returns (uint96 feesSettled_);

Parameters

Returns

sendExcessToFeeDistributor

Sends the excess tokens in the contract to the fee distributor.

function sendExcessToFeeDistributor() external returns (uint96 excess_);

Returns

updateSettler

Updates the settler of the contract.

Ensures the new settler is not zero (i.e. address(0)).

function updateSettler() external;

updateFeeDistributor

Updates the fee distributor of the contract.

Ensures the new fee distributor is not zero (i.e. address(0)).

function updateFeeDistributor() external;

updateMinimumDeposit

Updates the minimum deposit amount.

Ensures the new minimum deposit is not zero (i.e. address(0)).

function updateMinimumDeposit() external;

updateWithdrawLockPeriod

Updates the withdraw lock period.

function updateWithdrawLockPeriod() external;

updatePauseStatus

Updates the pause status.

function updatePauseStatus() external;

settlerParameterKey

The parameter registry key used to fetch the settler.

function settlerParameterKey() external pure returns (string memory key_);

feeDistributorParameterKey

The parameter registry key used to fetch the fee distributor.

function feeDistributorParameterKey() external pure returns (string memory key_);

minimumDepositParameterKey

The parameter registry key used to fetch the minimum deposit.

function minimumDepositParameterKey() external pure returns (string memory key_);

withdrawLockPeriodParameterKey

The parameter registry key used to fetch the withdraw lock period.

function withdrawLockPeriodParameterKey() external pure returns (string memory key_);

pausedParameterKey

The parameter registry key used to fetch the paused status.

function pausedParameterKey() external pure returns (string memory key_);

migratorParameterKey

The parameter registry key used to fetch the migrator.

function migratorParameterKey() external pure returns (string memory key_);

parameterRegistry

The address of the parameter registry.

function parameterRegistry() external view returns (address parameterRegistry_);

feeToken

The address of the fee token contract used for deposits and withdrawals.

function feeToken() external view returns (address feeToken_);

settler

The address of the settler that can call settleUsage.

function settler() external view returns (address settler_);

feeDistributor

The address of the fee distributor that receives unencumbered fees from usage settlements.

function feeDistributor() external view returns (address feeDistributor_);

totalDeposits

The sum of all payer balances and pending withdrawals.

function totalDeposits() external view returns (int104 totalDeposits_);

paused

The pause status.

function paused() external view returns (bool paused_);

totalDebt

The sum of all payer debts.

function totalDebt() external view returns (uint96 totalDebt_);

totalWithdrawable

The sum of all withdrawable balances (sum of all positive payer balances and pending withdrawals).

function totalWithdrawable() external view returns (uint96 totalWithdrawable_);

minimumDeposit

The minimum amount required for any deposit.

function minimumDeposit() external view returns (uint96 minimumDeposit_);

withdrawLockPeriod

The withdraw lock period.

function withdrawLockPeriod() external view returns (uint32 withdrawLockPeriod_);

excess

The amount of excess tokens in the contract that are not withdrawable by payers.

function excess() external view returns (uint96 excess_);

getBalance

Returns the balance of a payer.

function getBalance(address payer_) external view returns (int104 balance_);

Parameters

Returns

getBalances

Returns the balances of an array of payers.

This is a periphery function for nodes, and is not required for the core protocol.

function getBalances(address[] calldata payers_) external view returns (int104[] memory balances_);

Parameters

Returns

getPendingWithdrawal

Returns the pending withdrawal of a payer.

function getPendingWithdrawal(address payer_)
    external
    view
    returns (uint96 pendingWithdrawal_, uint32 withdrawableTimestamp_, uint24 nonce_);

Parameters

Returns

Events

SettlerUpdated

Emitted when the settler is updated.

event SettlerUpdated(address indexed settler);

Parameters

FeeDistributorUpdated

Emitted when the fee distributor is updated.

event FeeDistributorUpdated(address indexed feeDistributor);

Parameters

MinimumDepositUpdated

Emitted when the minimum deposit is updated.

event MinimumDepositUpdated(uint96 minimumDeposit);

Parameters

WithdrawLockPeriodUpdated

Emitted when the withdraw lock period is updated.

event WithdrawLockPeriodUpdated(uint32 withdrawLockPeriod);

Parameters

Deposit

Emitted when a deposit of fee tokens occurs for a payer.

event Deposit(address indexed payer, uint96 amount);

Parameters

WithdrawalRequested

Emitted when a withdrawal is requested by a payer.

event WithdrawalRequested(address indexed payer, uint96 amount, uint32 withdrawableTimestamp, uint24 nonce);

Parameters

WithdrawalCancelled

Emitted when a payer's pending withdrawal is cancelled.

event WithdrawalCancelled(address indexed payer, uint24 nonce);

Parameters

WithdrawalFinalized

Emitted when a payer's pending withdrawal is finalized.

event WithdrawalFinalized(address indexed payer, uint24 nonce);

Parameters

UsageSettled

Emitted when a payer's usage is settled.

event UsageSettled(bytes32 indexed payerReportId, address indexed payer, uint96 amount);

Parameters

ExcessTransferred

Emitted when excess fee tokens are transferred to the fee distributor.

event ExcessTransferred(uint96 amount);

Parameters

PauseStatusUpdated

Emitted when the pause status is set.

event PauseStatusUpdated(bool indexed paused);

Parameters

Errors

NotSettler

Thrown when caller is not the settler.

error NotSettler();

ZeroParameterRegistry

Thrown when the parameter registry address is being set to zero (i.e. address(0)).

error ZeroParameterRegistry();

ZeroFeeToken