ERC-20 Burn Module

@perfect-abstractions/compose/token/ERC20/Burn/ERC20BurnMod.solCopy

Helper function for destroying ERC-20 tokens from any account

No Authorization Check

burn destroys tokens from any account you name. It performs no allowance check and no role check. Whatever facet calls it is responsible for proving the caller is allowed to do this.

Key Features

• burn(_account, _value) takes the account as a parameter, unlike the facet's caller-only burn(_value).
• Reduces balanceOf and totalSupply, then emits Transfer to address(0).
• Declares a reduced ERC20Storage with no allowance field. See below.

Module Usage

Use helper functions from Compose using your own custom facets. See Facets & Modules for more information.

Storage​

State Variables​

ERC20Storage​

This module declares only the two fields it uses. The allowance mapping that other ERC-20 contracts declare is absent.

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

Why the struct is shorter here

This is a layout-compatible prefix of the full struct, not a different slot. balanceOf and totalSupply occupy the same positions either way, so this module reads and writes exactly the same storage as the rest of ERC-20. It simply does not declare the field it never touches.

ERC20MintMod and the two Bridgeable contracts use the same two-field form. Everything that reads or writes an allowance, including ERC20BurnFacet, declares all three fields.

Functions​

getStorage​

Returns a pointer to the ERC20Storage struct.

Because this module's struct has no allowance field, the returned pointer cannot reach allowances. If your facet needs to inspect one, import a module that declares the full struct, such as ERC20TransferMod or ERC20ApproveMod.

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

Returns:

burn​

Destroys _value tokens held by _account and reduces the total supply by the same amount.

No allowance is consulted and no permission is checked. Gate this behind your own authorization, exactly as you would with a mint. Burning 0 is allowed and still emits Transfer.

function burn(address _account, uint256 _value);

Parameters:

Reverts:

Events​

Transfer

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

Errors​

ERC20InsufficientBalance

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

ERC20InvalidSender

Thrown when _account is the zero address. The facet's burnFrom has no equivalent guard, so this module is the stricter of the two.

Signature:

error ERC20InvalidSender(address _sender);

Best Practices​

• Wrap burn in an external function that checks permission first, for example an owner or role guard, or proof that the caller holds the tokens.
• If you want the ordinary "holders burn their own tokens" behaviour, use ERC20BurnFacet instead of writing a wrapper. It already binds the burn to msg.sender.
• If you want allowance-based burning, use the facet's burnFrom, or check the allowance yourself through a module that declares it before calling this helper.
• Keep the same STORAGE_POSITION and field order as the other ERC-20 contracts. Do not introduce a second balance mapping.

Integration Notes​

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

import "src/token/ERC20/Burn/ERC20BurnMod.sol" as ERC20BurnMod;
import "src/access/Owner/Data/OwnerDataMod.sol" as OwnerDataMod;

contract MyFacet {
  function burnFromAccount(address _account, uint256 _value) external {
      OwnerDataMod.requireOwner();
      ERC20BurnMod.burn(_account, _value);
  }
}

ERC20Storage lives at keccak256("erc20") inside the diamond, the same slot ERC20DataFacet reads, so a burn here is immediately visible through balanceOf() and totalSupply().

The balance and totalSupply subtractions sit inside unchecked, after an explicit balance comparison. That is safe only while no balance exceeds totalSupply. If your facet writes balanceOf directly without adjusting totalSupply, a later burn can underflow totalSupply silently. Keep the two in step.

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.