ERC-20 Transfer Module

ERC20Storage​

/** @custom:storage-location erc8042:erc20 */
struct ERC20Storage {
  mapping(address owner => uint256 balance) balanceOf;
  uint256 totalSupply;
  mapping(address owner => mapping(address spender => uint256 allowance)) allowance;
}

Functions​

getStorage​

Returns a pointer to the ERC20Storage struct.

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

Returns:

transfer​

Moves _value tokens from the caller to _to.

Inside a diamond, your facet runs through delegatecall, so msg.sender here is the account that called the diamond, not the diamond itself. Transferring 0 is allowed and still emits Transfer.

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

Parameters:

Returns:

Reverts:

transferFrom​

Moves _value tokens from _from to _to, spending the allowance that _from granted to msg.sender.

The allowance is checked before the balance. If both are insufficient, the call reverts with ERC20InsufficientAllowance. When the allowance is exactly type(uint256).max it is left untouched, otherwise it is reduced by _value.

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

Parameters:

Returns:

Reverts:

Events​

Transfer

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

Approval

Declared here for shared use across the ERC-20 contracts. This module never emits it, not even when transferFrom lowers an allowance. ERC20ApproveMod emits it when an allowance is set.

Signature:

event Approval(address indexed _owner, address indexed _spender, uint256 _value);

Errors​

ERC20InsufficientBalance

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

ERC20InvalidSender

error ERC20InvalidSender(address _sender);

ERC20InvalidReceiver

error ERC20InvalidReceiver(address _receiver);

ERC20InsufficientAllowance

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

ERC20InvalidSpender

Declared here for shared use across the ERC-20 contracts. This module does not revert with it. ERC20ApproveMod throws it when approving the zero address.

Signature:

error ERC20InvalidSpender(address _spender);

Best Practices​

• Use transfer when your facet moves tokens on behalf of whoever called it, for example a wrapper that transfers and then performs a second action in one transaction.
• To move tokens for an account that is not msg.sender, these helpers will not do it. Write getStorage().balanceOf directly and emit Transfer yourself, after your own authorization check.
• Keep the same STORAGE_POSITION and ERC20Storage layout as the other ERC-20 modules. Do not introduce a second balance mapping.
• Do not assume the recipient reacted to the transfer. Neither helper calls into _to.

Integration Notes​

Import the module under a namespace and call it from your facet:

import "src/token/ERC20/Transfer/ERC20TransferMod.sol" as ERC20TransferMod;

contract MyFacet {
  function transferTokens(address _to, uint256 _value) external returns (bool) {
      return ERC20TransferMod.transfer(_to, _value);
  }
}

ERC20Storage lives at keccak256("erc20") inside the diamond. That is the same slot ERC20DataFacet, ERC20TransferFacet, and the other ERC-20 contracts use, so balances written here are what balanceOf() reports.

Every balance subtraction sits inside unchecked, but only after an explicit comparison has proved the balance or allowance is large enough, so it cannot underflow. Keep that ordering if you adapt the code.

Last updated:September 16, 2026

Newsletter

Get notified about releases, feature announcements, and technical deep-dives on building smart contracts with Compose.

Subscribe

No spam. Unsubscribe anytime.