ERC-20 Bridgeable Module

Internal functions for cross-chain ERC20 token operations

Key Features

• Internal functions for cross-chain token operations.
• Leverages diamond storage for access control roles (trusted-bridge).
• Emits CrosschainBurn and CrosschainMint events for off-chain monitoring.
• Does not use using directives or external dependencies.

Module Usage

This module provides internal functions for use in your custom facets. Import it to access shared logic and storage.

Overview

This module provides internal functions for cross-chain ERC20 token transfers, specifically for burning and minting tokens across different chains. It relies on diamond storage for managing access control roles, ensuring that only trusted bridges can execute these sensitive operations. Changes to token balances are immediately visible to all facets interacting with the same diamond storage.

Storage

AccessControlStorage

storage struct for the AccessControl. storage-location: erc8042:compose.accesscontrol

Definition

struct AccessControlStorage {
  mapping(address account => mapping(bytes32 role => bool hasRole)) hasRole;
}

---

ERC20Storage

ERC-8042 compliant storage struct for ERC20 token data. storage-location: erc8042:erc20

Definition

struct ERC20Storage {
  mapping(address owner => uint256 balance) balanceOf;
  uint256 totalSupply;
}

State Variables

Property	Type	Description
ERC20_STORAGE_POSITION	bytes32	Diamond storage slot position for this module (Value: keccak256("erc20"))
ACCESS_STORAGE_POSITION	bytes32	Diamond storage slot position for this module (Value: keccak256("compose.accesscontrol"))

Functions

checkTokenBridge

Internal check to check if the bridge (caller) is trusted. Reverts if caller is zero or not in the AccessControl trusted-bridge role.

function checkTokenBridge(address _caller) view;

Parameters:

Property	Type	Description
_caller	address	The address to validate

---

crosschainBurn

Cross-chain burn — callable only by an address having the trusted-bridge role.

function crosschainBurn(address _from, uint256 _value) ;

Parameters:

Property	Type	Description
_from	address	The account to burn tokens from.
_value	uint256	The amount to burn.

---

crosschainMint

Cross-chain mint — callable only by an address having the trusted-bridge role.

function crosschainMint(address _account, uint256 _value) ;

Parameters:

Property	Type	Description
_account	address	The account to mint tokens to.
_value	uint256	The amount to mint.

---

getAccessControlStorage

helper to return AccessControlStorage at its diamond slot

function getAccessControlStorage() pure returns (AccessControlStorage storage s);

---

getERC20Storage

Returns the ERC20 storage struct from the predefined diamond storage slot. Uses inline assembly to set the storage slot reference.

function getERC20Storage() pure returns (ERC20Storage storage s);

Returns:

Property	Type	Description
s	ERC20Storage	The ERC20 storage struct reference.

Events

Emitted when a crosschain transfer burns tokens.

Signature:

event CrosschainBurn(address indexed _from, uint256 _amount, address indexed _sender);

Parameters:

Property	Type	Description
_from	address	Address of the account tokens are being burned from.
_amount	uint256	Amount of tokens burned.
_sender	address	Address of the caller (msg.sender) who invoked crosschainBurn.

Emitted when tokens are minted via a cross-chain bridge.

Signature:

event CrosschainMint(address indexed _to, uint256 _amount, address indexed _sender);

Parameters:

Property	Type	Description
_to	address	The recipient of minted tokens.
_amount	uint256	The amount minted.
_sender	address	The bridge account that triggered the mint (msg.sender).

Emitted when tokens are transferred between two addresses.

Signature:

event Transfer(address indexed _from, address indexed _to, uint256 _value);

Parameters:

Property	Type	Description
_from	address	Address sending the tokens.
_to	address	Address receiving the tokens.
_value	uint256	Amount of tokens transferred.

Errors

Thrown when the account does not have a specific role.

Signature:

error AccessControlUnauthorizedAccount(address _account, bytes32 _role);

Signature:

error ERC20InsufficientBalance(address _from, uint256 _accountBalance, uint256 _value);

Revert when caller is not a trusted bridge.

Signature:

error ERC20InvalidBridgeAccount(address _caller);

Revert when caller address is invalid.

Signature:

error ERC20InvalidCallerAddress(address _caller);

Revert when a provided receiver is invalid(e.g,zero address) .

Signature:

error ERC20InvalidReceiver(address _receiver);

Thrown when the sender address is invalid (e.g., zero address).

Signature:

error ERC20InvalidSender(address _sender);

Best Practices

Best Practice

• Ensure the caller has the trusted-bridge role before invoking crosschainBurn or crosschainMint.
• Verify that the diamond storage layout remains compatible when upgrading facets to prevent storage collisions.
• Handle potential reverts from ERC20InsufficientBalance, ERC20InvalidBridgeAccount, ERC20InvalidCallerAddress, ERC20InvalidReceiver, or ERC20InvalidSender.

Integration Notes

Shared Storage

This module utilizes the diamond storage pattern, with its state stored at the ERC20_STORAGE_POSITION slot, identified by keccak256("erc20"). Functions like crosschainBurn and crosschainMint directly read from and write to the shared diamond storage. The AccessControlStorage struct, though empty in the provided definition, is conceptually used for role management. Any changes made to token balances via this module are immediately reflected for all other facets accessing the same storage.

Was this helpful?

Last updated:March 13, 2026