ERC-20 Transfer Module

Internal ERC-20 token transfer functions

Key Features

• Internal functions for token transfers, designed for use within custom facets.
• Utilizes diamond storage (EIP-8042) for state management.
• No external dependencies, promoting composability.
• Emits Transfer events upon successful transfers.

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 executing ERC-20 token transfers and transfers from an allowance. Facets can import and utilize these functions to manage token balances and operations within the diamond storage pattern. Changes to balances are immediately reflected across all facets accessing the same storage.

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

getStorage

Returns a pointer to the ERC-20 storage struct. Uses inline assembly to bind the storage struct to the fixed storage position.

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

Returns:

Property	Type	Description
s	ERC20Storage	The ERC-20 storage struct.

---

transfer

Transfers tokens from the caller to another address. Updates balances directly without allowance mechanism.

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

Parameters:

Property	Type	Description
_to	address	The address to send tokens to.
_value	uint256	The number of tokens to transfer.

Returns:

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

---

transferFrom

Transfers tokens from one address to another using an allowance. Deducts the spender's allowance and updates balances.

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

Parameters:

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

Returns:

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

Events

Emitted when an approval is made for a spender by an owner.

Signature:

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

Parameters:

Property	Type	Description
_owner	address	The address granting the allowance.
_spender	address	The address receiving the allowance.
_value	uint256	The amount approved.

Emitted when tokens are transferred between addresses.

Signature:

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

Parameters:

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

Errors

Thrown when a spender tries to spend more than their allowance.

Signature:

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

Thrown when a sender attempts to transfer or burn more tokens than their balance.

Signature:

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

Thrown when the receiver address 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);

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

Signature:

error ERC20InvalidSpender(address _spender);

Best Practices

Best Practice

• Ensure the caller has sufficient balance before calling transfer.
• Verify the spender has sufficient allowance before calling transferFrom.
• Handle potential errors such as ERC20InvalidReceiver or ERC20InsufficientBalance.
• Use the getStorage() function to access the storage pointer for direct inspection if necessary.

Integration Notes

Shared Storage

This module reads and writes to diamond storage at the STORAGE_POSITION, identified by keccak256("erc20"). The ERC20Storage struct, containing fields like totalSupply, is managed here. All functions operate directly on this shared storage, ensuring that balance updates are immediately visible to any facet that accesses the same storage slot. The getStorage() function provides a direct pointer to this struct via inline assembly.

Was this helpful?

Last updated:March 13, 2026