ERC-20 Token with Mint, Burn, and Pause

Hello! Welcome to the first lesson of our fourth module, "Fungible Tokens & DeFi Primitives."

Introduction

In our previous module, we concluded by building a UUPS upgradeable contract, using a basic ERC-20 token as our practical example. That exercise set the stage perfectly for this new module, where we will construct the core building blocks of Decentralized Finance (DeFi).

The most fundamental of these primitives is the fungible token. Today, we will go beyond the basic shell and implement a feature-rich ERC-20 token. You will learn how to use OpenZeppelin's battle-tested, modular contracts to create a token that is not only functional but also secure and manageable.

Learning Outcome: By the end of this lesson, you will be able to implement an ERC-20 token with mint, burn, and pausable functionality.

This lesson will guide you through inheriting the standard ERC-20 functionality and then extending it with capabilities for creating new tokens (minting), destroying existing ones (burning), and temporarily halting all token activity (pausing).

1. The ERC-20 Token Standard

Before we write any code, let's solidify our understanding of what an ERC-20 token is. It's not a piece of software you run, but rather a standard interface that a smart contract must implement. This standardization ensures that any application, from wallets to decentralized exchanges, can interact with any ERC-20 token in a predictable way.

To get a clear overview, let's start with a short video.

As the video mentioned, the key to modern and secure ERC-20 development is not to reinvent the wheel. We will use the OpenZeppelin library, which provides audited, gas-optimized, and community-vetted implementations of these standards.

For a quick reference, the article "Ultimate Guide to Creating and Deploying BASE..." provides a concise summary of the key features.

2. Building the Basic Token with Hardhat

We will now create our token contract within the Hardhat environment you're already familiar with. Our goal is to create a contract that inherits from OpenZeppelin's ERC20.sol.

Let's start by creating a new file in your contracts directory named MyToken.sol.

The basic structure involves:

1. Importing ERC20.sol from the OpenZeppelin library.
2. Declaring your contract to inherit from ERC20.
3. Creating a constructor to set the token's name and symbol and to mint an initial supply.

The following video segment walks through this initial implementation. While it starts in the Remix IDE, the core Solidity code is what's important. We will adapt it for our Hardhat project.

Here is the code for our initial MyToken.sol, adapted for a local Hardhat project and incorporating the concepts from the video:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "@openzeppelin/contracts/token/ERC20/ERC20.sol";

contract MyToken is ERC20 {
    constructor(string memory name, string memory symbol, uint256 initialSupply) ERC20(name, symbol) {
        // Mint the initial supply to the contract deployer
        // Note: The amount needs to account for decimals.
        // For a token with 18 decimals, 1 token is represented as 1 * 10**18.
        _mint(msg.sender, initialSupply * (10 ** decimals()));
    }
}

This is a complete, albeit basic, ERC-20 token. It has a fixed total supply minted entirely to the deployer's address upon creation.

3. Adding Mint and Burn Functionality

A fixed supply isn't always desirable. Many token models require the ability to create new tokens (minting) or destroy existing ones (burning).

• Minting: Increases the total supply. This is often a privileged action, restricted to the contract owner, used for things like inflation, rewards, or funding.
• Burning: Decreases the total supply. This can be a public function allowing any user to destroy their own tokens, or a privileged one. It's often used to create deflationary pressure.

OpenZeppelin provides modular extensions for these features. We'll use ERC20Burnable and add a custom mint function controlled by an owner.

The following article provides excellent, self-contained examples of how to integrate these features.

Let's update our MyToken.sol to include these features. We'll need to import Ownable.sol for access control and ERC20Burnable.sol for the burn functionality.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Burnable.sol";
import "@openzeppelin/contracts/access/Ownable.sol";

// Inherit from ERC20, ERC20Burnable for burn(), and Ownable for access control
contract MyToken is ERC20, ERC20Burnable, Ownable {
    constructor(string memory name, string memory symbol, address initialOwner) ERC20(name, symbol) {
        // The Ownable constructor sets the deployer as the initial owner.
        // We pass the desired owner address to the constructor.
        _transferOwnership(initialOwner);
    }

    /**
     * @dev Creates `amount` new tokens and assigns them to `to`, increasing
     * the total supply.
     *
     * Requirements:
     * - The caller must be the owner of the contract.
     */
    function mint(address to, uint256 amount) public onlyOwner {
        _mint(to, amount);
    }
}

Key changes:

1. We now inherit from ERC20Burnable and Ownable.
2. The ERC20Burnable extension provides the public burn(uint256 amount) and burnFrom(address account, uint256 amount) functions out of the box.
3. We removed the initialSupply from the constructor. Instead, the owner can now call the mint function anytime to create new tokens.
4. The mint function is public but restricted by the onlyOwner modifier from Ownable. It calls the internal _mint function provided by the base ERC20 contract.

4. Implementing Pausable Functionality

For security, it's often wise to include an "emergency stop" button. The Pausable pattern allows a contract owner to halt key functions in case a vulnerability is discovered, preventing further damage. When applied to an ERC-20 token, this typically means stopping all transfers.

OpenZeppelin provides the Pausable contract and a specific ERC-20 extension, ERC20Pausable, that makes this incredibly simple.

The ERC20Pausable extension conveniently pre-wires this for us. By inheriting from it, all transfer functions are automatically protected by the whenNotPaused modifier.

Let's integrate this into our final contract.

5. The Complete Token Contract

Here is the final version of MyToken.sol that fulfills all the requirements of our learning outcome. It is a fungible token with mint, burn, and pausable capabilities, all secured by an owner.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Burnable.sol";
import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Pausable.sol";
import "@openzeppelin/contracts/access/Ownable.sol";

/**
 * @title MyToken
 * @dev A feature-rich ERC20 token with mint, burn, and pausable functionalities.
 * - Minting is restricted to the owner.
 * - Burning can be done by any token holder for their own tokens.
 * - Pausing/unpausing all token transfers is restricted to the owner.
 */
contract MyToken is ERC20, ERC20Burnable, ERC20Pausable, Ownable {
    constructor(string memory name, string memory symbol, address initialOwner) ERC20(name, symbol) {
        _transferOwnership(initialOwner);
    }

    /**
     * @dev Creates `amount` new tokens and assigns them to `to`.
     * Can only be called by the contract owner.
     */
    function mint(address to, uint256 amount) public onlyOwner {
        _mint(to, amount);
    }

    /**
     * @dev Pauses all token transfers.
     * Can only be called by the contract owner.
     */
    function pause() public onlyOwner {
        _pause();
    }

    /**
     * @dev Resumes all token transfers.
     * Can only be called by the contract owner.
     */
    function unpause() public onlyOwner {
        _unpause();
    }

    /**
     * @dev Hook that is called before any token transfer.
     * Overridden to apply the `whenNotPaused` modifier.
     */
    function _beforeTokenTransfer(address from, address to, uint256 amount)
        internal
        override(ERC20, ERC20Pausable)
    {
        super._beforeTokenTransfer(from, to, amount);
    }
}

To compile this contract, you can run npx hardhat compile in your project terminal. Thanks to the modular nature of OpenZeppelin contracts, it should compile without issues. The override(ERC20, ERC20Pausable) keyword is necessary because both parent contracts define a _beforeTokenTransfer function, and we need to explicitly state which one we are extending.

Conclusion

Excellent work! You have successfully designed and implemented a robust ERC-20 token that goes far beyond the basics. By composing modular contracts from the OpenZeppelin library, you've created a token with essential management features in a secure and gas-efficient way.

Key Takeaways:

• ERC-20 is a Standard: It defines a common interface for fungible tokens, ensuring interoperability.
• Composition over Reinvention: We built our token by inheriting from pre-built, audited OpenZeppelin contracts: ERC20, ERC20Burnable, ERC20Pausable, and Ownable.
• Minting: New tokens can be created via a privileged mint function that calls the internal _mint.
• Burning: The ERC20Burnable extension provides a public burn function for users to destroy their tokens.
• Pausable: The ERC20Pausable extension provides a powerful safety mechanism to halt token transfers, controlled by the owner.

Next Steps:

Our token is functional, but there's a common user-experience friction point in DeFi: the approve and transferFrom flow, which requires two separate transactions. In the next lesson, we will solve this by implementing ERC-2612, a standard that allows for gasless approvals via signatures, dramatically improving the user experience.