ERC-20 Data Facet

ERC20Storage​

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

Functions​

totalSupply​

Returns the total number of tokens in circulation.

function totalSupply() external view returns (uint256);

Returns:

balanceOf​

Returns the token balance held by an account.

function balanceOf(address _account) external view returns (uint256);

Parameters:

Returns:

allowance​

Returns how many tokens a spender may still move on an owner's behalf.

function allowance(address _owner, address _spender) external view returns (uint256);

Parameters:

Returns:

Best Practices​

• Add this facet whenever tokens are exposed to wallets, explorers, or other contracts. totalSupply(), balanceOf() and allowance() are what integrators expect from any ERC-20.
• Pair it with ERC20MetadataFacet so name(), symbol() and decimals() are available too. That pair is the minimum most integrations assume.
• Do not add a second facet that reads token balances from a different slot. Keep all ERC-20 state at erc20 so every facet observes the same numbers.
• Reading allowance() before calling transferFrom does not guarantee the value still holds at execution time. Treat it as informational, not as a lock.

Security Considerations​

This facet only reads storage, so it cannot corrupt token state on its own. Two things are still worth knowing:

• balanceOf() reflects whatever the write-side facets recorded. A custom facet that writes to the erc20 slot with an incompatible struct layout makes these reads report wrong values with no error.
• An allowance of type(uint256).max is a deliberate sentinel for "unlimited" in ERC20TransferFacet. Interfaces that render the raw number should special-case it rather than showing the full integer.

Last updated:September 6, 2026

Newsletter

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

Subscribe

No spam. Unsubscribe anytime.