ERC-20 Transfer Facet

ERC-20 token transfers within a diamond

Key Features

• Exposes external transfer and transferFrom functions for diamond interaction.
• Manages token balances and allowances using shared diamond storage.
• Emits standard Transfer events for off-chain monitoring.
• Utilizes custom errors for clear revert reasons.

Overview

This facet implements ERC-20 token transfer functionality, exposing external functions for token movement within a diamond. It accesses shared diamond storage to manage balances and allowances, adhering to the ERC-2535 standard for upgradeability. Developers integrate this facet to enable token operations via the diamond proxy.

Storage

ERC20Storage

Definition

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

State Variables

Property	Type	Description
STORAGE_POSITION	bytes32	Diamond storage slot position for this module (Value: keccak256("erc20"))

Functions

transfer

Transfers tokens to another address. Emits a Transfer event.

function transfer(address _to, uint256 _value) external returns (bool);

Parameters:

Property	Type	Description
_to	address	The address to receive the tokens.
_value	uint256	The amount of tokens to transfer.

Returns:

Property	Type	Description
-	bool	True if the transfer was successful.

---

transferFrom

Transfers tokens on behalf of another account, provided sufficient allowance exists. Emits a Transfer event and decreases the spender's allowance.

function transferFrom(address _from, address _to, uint256 _value) external returns (bool);

Parameters:

Property	Type	Description
_from	address	The address to transfer tokens from.
_to	address	The address to transfer tokens to.
_value	uint256	The amount of tokens to transfer.

Returns:

Property	Type	Description
-	bool	True if the transfer was successful.

---

exportSelectors

Exports the function selectors of the ERC20TransferFacet 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 ERC20TransferFacet

Events

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 an account has insufficient balance for a transfer or burn.

Signature:

error ERC20InsufficientBalance(address _sender, uint256 _balance, uint256 _needed);

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

Signature:

error ERC20InvalidSender(address _sender);

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

Signature:

error ERC20InvalidReceiver(address _receiver);

Thrown when a spender tries to use more than the approved allowance.

Signature:

error ERC20InsufficientAllowance(address _spender, uint256 _allowance, uint256 _needed);

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

Signature:

error ERC20InvalidSpender(address _spender);

Best Practices

Best Practice

• Ensure the ERC20Storage struct is correctly initialized in diamond storage.
• Verify that allowances are managed correctly before calling transferFrom.
• Use the exportSelectors function during diamond upgrades to discover facet selectors.

Security Considerations

Security

Functions are protected by Compose's access control mechanisms. Input validation is performed for recipient addresses and transfer values. The transferFrom function requires sufficient allowance to be set by the token owner. Reentrancy is mitigated by adhering to the checks-effects-interactions pattern.

Was this helpful?

Last updated:March 13, 2026