ERC20BridgeableFacet

Cross-chain ERC-20 token minting and burning

Key Features

• Enables cross-chain token minting and burning.
• Restricts minting and burning to addresses with the trusted-bridge role.
• Integrates with the diamond storage pattern for token state management.
• Follows Compose's convention of explicit function calls.

Overview

This facet enables cross-chain ERC-20 token minting and burning operations within a diamond. It exposes functions that are callable only by addresses with the trusted-bridge role, ensuring secure and controlled token movements across different chains. Integrate this facet to manage bridged token supply.

---

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("compose.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

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 ERC20InvalidReciever(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 assigned only to authorized bridge contracts or entities.
• Call crosschainMint and crosschainBurn through the diamond proxy to ensure correct function routing.
• Validate that the caller possesses the trusted-bridge role before invoking minting or burning operations.

Security Considerations

Security

The crosschainMint and crosschainBurn functions are protected by access control, requiring the caller to have the trusted-bridge role. The checkTokenBridge internal function enforces this role check. Input validation for _account, _from, and _value is crucial to prevent unexpected behavior. Follow standard Solidity security practices for handling token transfers and state updates.

Related Documentation

📦

ERC20BridgeableMod

Module used by ERC20BridgeableFacet

💎

ERC20PermitFacet

Related facet in token

💎

ERC20Facet

Related facet in token

💎

ERC20BurnFacet

Related facet in token

Was this helpful?

Last updated:December 30, 2025