ERC-20 Bridgeable Facet

Cross-chain ERC-20 token minting and burning

Key Features

• Enables cross-chain minting and burning of ERC-20 tokens.
• Enforces trusted-bridge role for authorized operations via access control.
• Functions are callable via the diamond proxy, adhering to ERC-2535.
• Exports its own selectors for discovery by the diamond.

Overview

This facet exposes cross-chain mint and burn functionalities for ERC-20 tokens within a diamond. It enforces access control via the trusted-bridge role, ensuring only authorized entities can perform these operations. Calls are routed through the diamond proxy, leveraging shared diamond storage for state management.

Storage

ERC20Storage

Definition

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

---

AccessControlStorage

Definition

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

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

crosschainMint

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

function crosschainMint(address _account, uint256 _value) external;

Parameters:

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

---

crosschainBurn

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

function crosschainBurn(address _from, uint256 _value) external;

Parameters:

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

---

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) external view;

Parameters:

Property	Type	Description
_caller	address	The address to validate

---

exportSelectors

Exports the function selectors of the ERC20BridgeableFacet This function is use as a selector discovery mechanism for diamonds

function exportSelectors() external pure returns (bytes memory);

Returns:

Property	Type	Description
-	bytes	selectors The exported function selectors of the ERC20BridgeableFacet

Events

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 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 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

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);

Revert when caller is not a trusted bridge.

Signature:

error ERC20InvalidBridgeAccount(address _caller);

Revert when caller address is invalid.

Signature:

error ERC20InvalidCallerAddress(address _caller);

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);

Best Practices

Best Practice

• Ensure the trusted-bridge role is correctly assigned before calling crosschainMint or crosschainBurn.
• Verify caller identity and permissions through the diamond proxy before executing cross-chain operations.
• Use checkTokenBridge to confirm trusted bridge addresses when necessary.

Security Considerations

Security

State-changing functions crosschainMint and crosschainBurn are protected by the trusted-bridge role, enforced by internal checks. The checkTokenBridge function reverts if the caller is not a trusted bridge address or is the zero address. Input validation for _account, _from, and _value is crucial and should be handled by the caller or prior facets. Follow standard Solidity security practices for external calls and state updates.

Was this helpful?

Last updated:March 13, 2026