In today's article, we dive deeper into one of the most fascinating data structure/ cryptographic proof I've become obsessed with. I think you'll find it interesting too! From the title, you already know that we will be talking about Merkle Trees and Merkle Proofs, and how they are used in an airdrop distribution system.

We are going to explore:

• What is a Merkle Tree?

• How does a Merkle Proof work?

• How are Merkle Trees applied in an airdrop distribution system

Understanding Merkle Trees

A Merkle tree, also known as a hash tree, is a fundamental data structure used in cryptography and blockchain systems. It efficiently verifies the integrity of large datasets by breaking them down into smaller parts and hashing those parts repeatedly until a single root hash is formed. Each "leaf" in a Merkle tree represents a hash of a data block, while every "parent" node represents a hash of its child nodes' combined hashes. This structure allows for efficient and secure verification since only part of the tree needs to be traversed to confirm data validity. Think of it as a sort of upside down tree. Let’s take a look at a basic example .

Example of a Basic Merkle Tree

Let's take the example of four data blocks, which are labeled as Data Block 1, Data Block 2, Data Block 3, and Data Block 4.

1. First, we hash each data block:

   • Merkle Trees and Efficient Airdrop Distribution System

   • Hash of Data Block 2 results in Hash 2.

   • Hash of Data Block 3 results in Hash 3.

   • Hash of Data Block 4 results in Hash 4.

2. Then, we pair up adjacent hashes and combine them:

   • Hash 1 and Hash 2 are combined and hashed to form Hash 1-2.

   • Hash 3 and Hash 4 are combined and hashed to form Hash 3-4.

3. Finally, Hash 1-2 and Hash 3-4 are combined and hashed to create the Root Hash, which is the top node of the tree.

Here’s the Merkle tree visualization:

In this diagram:

• The Root Hash is at the top, which represents the combined hash of all data blocks.

• Each intermediate node, such as Hash 1-2 and Hash 3-4, is the hash of the concatenated hashes of the data blocks beneath it.

• The leaf nodes (Data Block 1 to Data Block 4) contain the actual data, which are hashed to create the tree.

The advantage of this structure is that it allows for efficient verification of data. For example, if someone wants to verify the integrity of Data Block 1, they only need to know Hash 2, Hash 3-4, and the root hash. This reduces the amount of data needed for verification without requiring the entire dataset cool right ?.

Why Merkle Trees ?

You might be wondering, why use a Merkle tree, and why am I even writing this article? Well, the truth is, Merkle trees are a cornerstone in many verification and chain-link systems, from blockchain to version control systems like Git. Their primary strength is in ensuring data integrity while minimizing the amount of data stored and transferred.

In essence, a Merkle tree allows you to verify that a particular piece of data belongs to a larger dataset, without needing to store or transfer the entire dataset. This is especially useful for systems where efficiency and security are crucial, like blockchains (Bitcoin, Ethereum), decentralized applications, or even systems like AirDrop distribution, which we will dive into very soon.

But it's not just in blockchain. Ever wondered how Git keeps track of all your file changes so efficiently? That’s right—Merkle trees. Git uses a Merkle-like structure to store commits, with each commit representing a snapshot of your project. When Linus Torvalds created Git, he probably wasn't thinking, "I need a Merkle tree!"—but that's exactly what Git ended up using. It helps Git keep track of every version of your code while ensuring that each commit can be verified for integrity.

And it's not just Git. BitTorrent, the peer-to-peer file-sharing protocol, uses Merkle trees to efficiently verify the integrity of large files during download. By using small pieces of the file and their corresponding hashes, it ensures that a downloaded chunk matches the original without needing the entire file at once, making it a robust system for decentralized data transfer.

Even Amazon DynamoDB, a distributed database system, employs Merkle trees for replication and consistency. Dynamo uses them to compare data between replicas, ensuring that only differences are transferred, which saves bandwidth and accelerates data synchronization in distributed systems.

And hey, if Torvalds hadn’t built Git so well, we'd probably still be using CVS—and nobody wants that! now let dive into how to use it in an airdrop system and see how the proof works

Designing an Airdrop Distribution System with Merkle Tree

In an airdrop system, a Merkle Tree allows us to keep the entire list of airdrop recipients and their respective token amounts off-chain. Instead of storing all the data on-chain, we only store a commitment—a sort of cryptographic fingerprint known as the Merkle Root (or root hash as discuss earlier)—on the blockchain.

Here’s how it works: when someone wants to claim their airdrop, they submit a proof (we will look into that shortly) that includes their address and claimable amount (e.g., 100 tokens). The contract will then verify this proof by comparing it with the on-chain Merkle Root. If the proof is valid, the contract confirms that the claim is legitimate and releases the tokens.

The beauty of this system is that it significantly reduces on-chain storage costs (so storing on the blockchain is expensive ) while maintaining secure and efficient verification of claims through the Merkle Tree structure.

How It Works:

• All the tree construction happens off-chain.

• The contract storage only contains the Merkle Root (the "fingerprint").

• The off-chain part includes building the Merkle Tree from a set of data, such as airdrop addresses and token amounts.

At the bottom of our tree (the leaves), we have the actual data we care about:

• All the addresses eligible for the airdrop.

• The corresponding token amounts for each address.

In this example, we also include an index for each leaf, but I’ll explain that in a minute. For now, let’s focus on the basic chunks of data.

1. Hashing the Leaves:

   We take each of these leaves (the address and amount) and hash them. This hashing can be done by concatenating the address, amount, and other values (e.g., the index). The key point is to stay consistent. Once we concatenate the values, we hash them—represented by H. The result is a 256-bit hash.

2. Hashing the Pairs:

   After hashing each piece of data individually, we take each pair of hashes and combine them. We then hash the combined values together. This step is repeated at each level of the tree.

3. Constructing the Root:

   We continue combining and hashing pairs until we reach the top, resulting in the Merkle Root. This root is the fingerprint stored on-chain.

As developers, we compute all of this off-chain—it might require some computation, but since it’s off-chain, gas fees aren’t a concern. After the Merkle Tree is constructed, we either:

• Deploy the contract with the Merkle Root stored within it, or

• Use an administrative function to set the Merkle Root and write it into the contract.

Once the Merkle Root is in the contract, the airdrop system is ready to verify claims.

Here’s a way to visualize the structure and flow of the Merkle tree for an airdrop system,

Before we implement the code let us take a sometime to talk about the way the proof works, that is how we know a particular data belongs to the tree

How Does This Work?

At first glance, it might seem strange that a system based on Merkle Trees works with such minimal data, yet maintains a high level of security. You might wonder, "How can I simply provide my data, a few additional hashes, and have the contract verify my claim without needing to see the full dataset?"

The magic lies in how hash functions and Merkle Trees interact to create a secure proof of membership, even when most of the data is not directly provided to the smart contract.

Step-by-Step Breakdown:

1. Merkle Tree Construction:

   • A Merkle Tree is a binary tree where:

     • Leaves are the actual data (e.g., addresses and token amounts in an airdrop).

     • Internal nodes are hashes derived from combining the hashes of their child nodes.

     • The Merkle Root at the top is the ultimate "fingerprint" of the entire dataset.

   All the leaves at the bottom represent individual pieces of data (addresses and claim amounts). When the Merkle Tree is created off-chain, each leaf is hashed, and those hashes are combined in pairs, hashed again, until reaching the Merkle Root, which is stored in the contract.

2. How Verification Works: When you want to claim your tokens, instead of submitting the entire dataset, you submit:

   • Your leaf data (address and claim amount).

   • A Merkle Proof, which includes the sibling hashes along the path from your leaf to the root.

   The smart contract verifies the authenticity of your data by:

   • Hashing your leaf data.

   • Using the sibling hashes to recreate the path up the Merkle Tree.

   • Once the contract computes the Merkle Root, it compares it to the stored root.

   If the roots match, your proof is valid, and the contract approves your claim.

Proofs and Tree Structure

If we simply wanted to store a fingerprint of data on-chain, we could concatenate the entire dataset, hash it, and store the hash in the contract. However, this wouldn't allow us to produce Merkle Proofs.

Without a tree structure, you'd need to provide all the other data alongside your own to verify it, which would be incredibly expensive. This is where Merkle Trees shine, allowing us to prove membership efficiently with only a fraction of the data.

How Merkle Proofs Work:

To claim tokens, you need to provide the following data:

1. Your Leaf (Data): This is your address and the token amount you're claiming. The contract hashes this data.

2. Sibling Hashes: These are the hashes needed to compute the path from your leaf to the root.

The contract performs the following steps:

• Hashes your data.

• Uses sibling hashes to compute the next level's hash.

• Repeats this process until it reaches the Merkle Root.

• Compares the computed root with the stored root.

If the computed root matches, the proof is valid.

Proof Complexity: ( for my cs nerds)

For each proof of membership in the Merkle Tree, you need to provide one additional hash (sibling) per level of the tree. The beauty of this approach lies in the fact that the height of the tree is logarithmic in relation to the number of leaves.

For example:

• With 1 million data leaves, the tree has a height of 21.

• If you increase the number of leaves to 1 billion (a 1000x increase), the tree’s height only grows to 30 or 31 levels.

This logarithmic property means the proof complexity is very efficient. Even if the dataset grows massively, the height of the tree increases only slightly. The formula for proof complexity is O(log₂(n)), where n is the number of leaves.

Therefore, producing and verifying proofs is highly efficient, no matter how large the dataset is. The contract only needs to store one root (a 256-bit hash), even if the tree contains billions of items.

Why the System is Secure

It seems almost too simple that I can provide just my leaf (address and amount) and a few sibling hashes, and the system will trust that my claim is legitimate. But the key lies in the properties of cryptographic hash functions and Merkle Trees. Here’s why this works securely:

1. Cryptographic Hash Functions are Collision-Resistant:

A hash function is a one-way cryptographic algorithm that maps an input (of any size) to a fixed-size output, called a hash. Good hash functions, like SHA-256, have a few important properties:

• Deterministic: The same input will always produce the same output.

• Irreversible: It is practically impossible to reverse-engineer the original input from its hash.

• Collision-Resistant: It is incredibly difficult to find two different inputs that produce the same hash (a collision).

Because of this, the hash function ensures that even the smallest change to the input data results in a completely different hash. For example, if I try to modify the amount I’m eligible to claim by even a single bit, the resulting hash will be wildly different from the correct hash.

2. The Role of the Merkle Tree:

The structure of the Merkle Tree takes advantage of this collision resistance. Let’s say you try to manipulate your claim:

• Step 1: You alter your address or claim amount. This change results in a completely different hash for your leaf.

• Step 2: You would then need to find a fake sibling hash that, when combined with your new leaf hash, still produces the same parent hash as before.

• Step 3: You continue this process all the way up the tree to the root.

The challenge here is that you need to ensure each new hash at every level matches what the contract expects. But because hash functions are so sensitive to input changes, finding valid sibling hashes that would result in the same root is essentially impossible.

3. Impossibility of Faking Proofs:

• If you manipulate any part of your data (e.g., increasing the amount of tokens you want to claim), the hash of your leaf changes.

• This means you would need to invent fake hashes at every level of the tree to produce the correct root.

• Due to the collision-resistant nature of hash functions, finding such a set of fake hashes would take an astronomically long time—far longer than the lifetime of the universe, using any current computational methods.

Even though there are technically multiple inputs that could hash to the same output (due to the pigeonhole principle), finding those collisions is computationally infeasible with modern hash functions like SHA-256 incase of the EVM Keccak256 . So, it’s effectively impossible to cheat the system.

Implementing a Merkle Tree Airdrop

Let's walk through the process of implementing a Merkle tree-based airdrop system using Solidity and JavaScript.

1. Creating the Merkle Tree

First, we need to create our Merkle tree off-chain. Here's a JavaScript implementation using the OpenZeppelin Merkle tree library:

const { StandardMerkleTree } = require("@openzeppelin/merkle-tree");
const fs = require("fs");

const values = [
  ["0x70997970C51812dc3A010C7d01b50e0d17dc79C8", "0", "10000000000000000000"],
  ["0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC", "1", "20000000000000000000"],
  // ... more addresses and amounts ...
];

const tree = StandardMerkleTree.of(values, ["address", "uint256", "uint256"]);

console.log("Merkle Root:", tree.root);

fs.writeFileSync("tree.json", JSON.stringify(tree.dump(), null, 2), "utf8");

This script creates a Merkle tree from a list of addresses, indices, and token amounts, then saves the tree structure to a JSON file.

2. Smart Contract Implementation

Now, let's look at the Solidity contract that handles the airdrop claims:

// SPDX-License-Identifier: MIT
pragma solidity 0.8.24;

import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import {BitMaps} from "@openzeppelin/contracts/utils/structs/BitMaps.sol";
import {MerkleProof} from "@openzeppelin/contracts/utils/cryptography/MerkleProof.sol";

contract MerkleDrop {
    IERC20 public immutable tokenAddress;
    bytes32 public merkleRoot;
    BitMaps.BitMap internal airdropCheckList;

    constructor(address _tokenAddress, bytes32 _merkleRoot) {
        tokenAddress = IERC20(_tokenAddress);
        merkleRoot = _merkleRoot;
    }

    function claimAirDrop(bytes32[] calldata proof, uint256 index, uint256 amount) external {
        require(!BitMaps.get(airdropCheckList, index), "Already claimed");

        bytes32 leaf = keccak256(bytes.concat(keccak256(abi.encode(msg.sender, index, amount))));
        require(MerkleProof.verify(proof, merkleRoot, leaf), "Invalid proof");

        BitMaps.setTo(airdropCheckList, index, true);
        tokenAddress.transfer(msg.sender, amount);
    }
}

Key points in this contract:

• We use a bitmap to efficiently track claimed airdrops we could have used mapping but we are just trying to save a bit of 1(true) and 0(false) so using mapping will be an over kill .

• The claimAirDrop function verifies the Merkle proof before transferring tokens.

• Double-hashing is used to prevent preimage attacks.

3. Generating Proofs for Claims

To claim their airdrop, users need to provide a Merkle proof. Here's how we can generate these proofs:

const { StandardMerkleTree } = require("@openzeppelin/merkle-tree");
const fs = require("fs");

function generateProof(address) {
  const tree = StandardMerkleTree.load(JSON.parse(fs.readFileSync("tree.json", "utf8")));

  for (const [i, v] of tree.entries()) {
    if (v[0].toLowerCase() === address.toLowerCase()) {
      return {
        value: v,
        proof: tree.getProof(i),
      };
    }
  }

  throw new Error(`Address ${address} not found in Merkle tree`);
}

/// the output of this will be out proof that we will pass into the claimairdrop 
/// function

This function loads the Merkle tree from our JSON file and generates a proof for a given address.

Full Codebase

If you want the full codebase, check out my GitHub repository and wrote some hardhat tests too.

Gas Efficiency and Scalability

The beauty of using Merkle trees for airdrops lies in their gas efficiency and scalability:

1. Constant Gas Cost: The gas cost for claiming an airdrop remains constant regardless of the number of total recipients.

2. Minimal On-Chain Storage: Only the Merkle root is stored on-chain, not the entire list of recipients.

3. Scalable to Millions: The system can handle millions of recipients without significant increases in complexity or cost.

Security Considerations

While Merkle trees provide an efficient solution, there are security aspects to consider:

1. Proof Generation: Ensure that proof generation is done securely off-chain.

2. Double-Claiming Prevention: The bitmap in the contract prevents double-claiming.

3. Root Updates: If the airdrop list needs updating, a new Merkle root can be set by the contract owner.

Conclusion: Security Without Sacrifice—Why Merkle Trees Are Pure Genius

Merkle Trees work like magic—but it’s all math! Here’s the quick rundown:

First, hash functions (like SHA-256) are super secure. They take any input, hash it, and even the tiniest change in the input completely alters the hash. This makes tampering with data nearly impossible.

Second, Merkle Trees are incredibly efficient. Even with millions of entries, verifying a single airdrop claim only takes a few steps. All you need is your claim and a few sibling hashes. The smart contract then verifies everything without storing huge amounts of data on-chain, keeping costs low while maintaining security.

The reason this system works so well is that it leverages the collision resistance of hash functions and the logarithmic structure of Merkle Trees. The Merkle Proof lets the contract efficiently check whether your data is part of a larger set, all while keeping on-chain operations minimal.

In short, Merkle Trees make airdrop verification fast, secure, and scalable. Pretty genius, right?

Thanks for Sticking With Me!

If you’ve made it this far, pat yourself on the back! You’re now well-versed in the magical world of Merkle Trees, and you’ve seen firsthand how they can make airdrop distribution (and other use cases) both scalable and secure. It’s not every day that you dive into the inner workings of cryptographic proofs and come out on the other side with a smile!

So, whether you're a developer looking to implement this system, or someone just curious about how blockchain sorcery works under the hood, I hope you enjoyed the ride! Thanks for reading to the end—and remember, you now hold the power of Merkle Magic in your hands!

Go forth and prove your membership with confidence!

Refrecences

• https://hackernoon.com/merkle-trees-181cb4bc30b4

• Merkle Trees for Airdrops on EVM: Logic, Use Cases, and Solidity Implementation (I strongly recommend)

Introduction

Sending Ether is a fundamental operation in Ethereum smart contracts. Over time, the recommended methods for transferring Ether have evolved due to security considerations and changes in the Ethereum protocol. This article will explore the three main methods of sending Ether: transfer(), send(), and call(), discussing their technical aspects, pros, cons, and current best practices.

The Three Methods of Sending Ether

1. transfer()

The transfer() function was introduced in later versions of Solidity as a safer alternative for sending Ether.

Syntax:

receivingAddress.transfer(amount);

Key Features:

• Has a fixed gas stipend of 2300 gas

• Automatically reverts the transaction if the transfer fails

• Throws an exception on failure, allowing the calling contract to handle the error

Initial Appeal:

1. Automatic reversion: If the transfer failed, the transaction would automatically revert.

2. Fixed gas stipend: It forwarded a fixed amount of 2300 gas to the receiving contract.

Limitations and Issues:

• The fixed gas stipend can cause problems if gas costs change

• May fail if the receiving contract's fallback function requires more than 2300 gas

• Relies on fixed gas costs, making it vulnerable to network upgrades that change opcode gas costs

Current Status: No longer recommended due to its reliance on fixed gas costs.

2. send()

The send() function is similar to transfer() but with slightly different behavior.

Syntax:

bool success = receivingAddress.send(amount);

Key Features:

• Also has a fixed gas stipend of 2300 gas

• Returns a boolean indicating success or failure

• Does not automatically revert the transaction on failure

Limitations:

• Shares the same gas stipend limitations as transfer()

• Requires manual checking of the return value and error handling

Current Status: Not recommended due to the same issues as transfer().

3. call()

The call() function is currently the recommended method for sending Ether.

Syntax:

(bool success, bytes memory data) = receivingAddress.call{value: amount}("");

Key Features:

• Allows for customizable gas limits

• Returns a boolean for success/failure and any return data

• More flexible, allowing for function calls along with Ether transfers

Advantages:

• Not limited by fixed gas stipends

• Can adapt to changes in gas costs

• Provides more control over the transaction

• Allows transfer of data with ether

Considerations:

• Requires careful implementation to prevent re-entrancy attacks

• Needs manual checking of the return value and error handling

The Impact of Changing Opcode Gas Costs

The fundamental issue with transfer() and send() lies in their reliance on a fixed gas stipend, which becomes problematic when gas costs for opcodes change. The Ethereum network periodically undergoes upgrades that can alter the gas costs of various operations, including storage operations (SSTORE and SLOAD).

The Constantinople Upgrade: A Case Study

The Constantinople upgrade in 2019 provides a clear example of how network changes can affect existing smart contracts. This upgrade aimed to optimize the network by reducing gas costs for certain SSTORE operations. While this change was beneficial in many ways, it had an unexpected consequence for contracts relying on transfer() and send().

Prior to the upgrade, the 2300 gas stipend was insufficient to perform storage operations, which was seen as a security feature preventing reentrancy attacks. However, the reduced gas costs meant that this stipend could now potentially allow for storage modifications, opening up new attack vectors.

Best Practices for Sending Ether

Given the lessons learned from the transfer() and send() deprecation, here are some best practices for sending Ether:

1. Use call() instead of transfer() or send(): This is the current recommendation from the Ethereum community.

2. Implement reentrancy guards: When using call(), always protect against reentrancy attacks.

3. Check return values: Always check the success boolean returned by call() and handle failures appropriately.

   1. **Follow the checks-effects-interactions patternn                     **

Example Implementation

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

contract SafeEtherSender {
    // Reentrancy guard
    bool private locked = false;

    modifier noReentrant() {
        require(!locked, "No reentrancy");
        locked = true;
        _;
        locked = false;
    }

    function sendEther(address payable _to, uint256 _amount) public payable noReentrant {
        // Perform any necessary checks
        require(_amount <= address(this).balance, "Insufficient balance");

        // Use call to send Ether
        (bool success, ) = _to.call{value: _amount}("");
        require(success, "Failed to send Ether");

        // Emit an event or perform any post-send operations
        emit EtherSent(_to, _amount);
    }

    event EtherSent(address indexed to, uint256 amount);
}

Conclusion

The evolution of Ether sending methods in Solidity serves as an important reminder of the dynamic nature of blockchain networks. While transfer() and send() were once considered safe methods for sending Ether, changes in the Ethereum protocol have made them less reliable.

The current best practice is to use call() with proper safeguards against reentrancy and other potential vulnerabilities. This method offers more flexibility and resilience to network changes, but it requires developers to implement additional security measures.

As the Ethereum ecosystem continues to evolve, it's crucial for developers to create flexible, adaptable smart contracts that can withstand changes in the underlying protocol. By understanding the reasons behind the shift away from transfer() and send(), and adopting best practices, developers can create more robust and future-proof smart contracts.

Always stay updated with the latest Ethereum security recommendations and be prepared to adapt your code as the ecosystem evolves. Regular audits and updates to smart contracts are essential to ensure they remain secure and functional in the face of network changes.

Reference

https://solidity-by-example.org/sending-ether/

https://blockchain-academy.hs-mittweida.de/courses/solidity-coding-beginners-to-intermediate/lessons/solidity-2-sending-ether-receiving-ether-emitting-events/topic/sending-ether-send-vs-transfer-vs-call/

https://www.immunebytes.com/blog/transfer-in-solidity-why-you-should-stop-using-it/

https://github.com/ethereum/solidity/issues/7455

Welcome back... ohh wait this is the first blog .In today's article, we cover in more detail one of the most important ERC in the smart contract development

We will see how the ERC20 the contract works, how to write and deploy our every own ERC20 Token. We will also use some contracts from OpenZeppelin to learn how the ERC20 token implementation work in practice while learning the Solidity code behind these popular contracts along the way.

Table Of Content .

• Introduction

• Anatomy of an ERC-20 Token

• Deep dive into Openzepplin Implementation

• Conclusion

Introduction

Have ever wondered why every website you have evere visited uses HTTP and HTTPS ? This is because of something called RFCs , or "Requests for Comments," which are the standards that define how the internet operates. RFCs provide the foundational rules that enable different systems to communicate seamlessly, ensuring a consistent experience across the web. Similarly, in the world of blockchain, particularly within the Ethereum ecosystem, we have Ethereum Improvement Proposal (EIPs) and Ethereum Request for Comments (ERCs).

EIPs are proposals that outline new features or standards for Ethereum, guiding its ongoing development and improvement. Among these EIPs, certain proposals evolve into ERCs when they define specific technical standards for smart contracts and tokens, much like how certain RFCs become the backbone of internet protocols.

One of the most prominent and widely adopted ERCs is ERC-20. This standard governs the creation and behavior of fungible tokens on Ethereum, establishing a set of rules that all ERC-20 tokens must follow. Just as HTTP/HTTPS ensures that all web browsers and servers can communicate efficiently, ERC-20 ensures that all tokens within its framework are interoperable across various platforms, wallets, and decentralized applications (DApps). Whether it's trading on decentralized exchanges or integrating with DeFi platforms, ERC-20 provides the necessary standardization that enables the smooth functioning of the Ethereum token ecosystem. In this article, we will delve into the ERC-20 specification, exploring its key functions, events, and how it can be implemented in smart contracts.

But wait ...

Before we start we need to get something right , the difference between EIP20 and ERC20. EIP-20 and ERC-20 refer to the same standard for fungible tokens on Ethereum "EIP-20" is the official Ethereum Improvement Proposal defining the standard, while "ERC-20" (Ethereum Request for Comments 20) is the common term used to describe tokens that follow this standard. Both terms are often used interchangeably.

Anatomy of an ERC-20 Token

An ERC-20 token according to the EIP-20 consists of a smart contract that implements the standardized interface, which comprises a set of six mandatory functions:

• totalSupply(): Returns the total supply of the token.

• balanceOf(address): Provides the balance of tokens held by a specific address.

• transfer(address, uint256): Transfers a specified amount of tokens from the sender's address to the specified recipient's address.

• transferFrom(address, address, uint256): Enables a third party to transfer tokens on behalf of the token owner, given that the owner has approved the transaction.

• approve(address, uint256): Allows the token owner to grant permission to a third party to spend a specified amount of tokens on their behalf.

• allowance(address, address): Returns the amount of tokens the token owner has allowed a third party to spend on their behalf.

Additionally, ERC-20 tokens can include optional functions that provide descriptive information about the token:

• name(): Returns the name of the token, for example, "WEB3BRIDGE"

• symbol(): Provides the token's symbol, like "WEB3BD"

• decimals(): Indicates the number of decimal places the token can be divided into, typically 18 for most tokens.

Deep dive into Openzepplin Implementation

Enough of the boring stuff let's get into the code ): . This of the article assumes you are familiar with Solidity . We will we explaining every block of code in the Openzepplin ERC.sol contract with you can find here and how it relates to the original EIP-20 specification.

In the code there are three types of functions (View, Internal and Public). But before we go over the functions let's check out the state variable and imports

The imports

pragma solidity ^0.8.20;

import {IERC20} from "./IERC20.sol";
import {IERC20Metadata} from "./extensions/IERC20Metadata.sol";
import {Context} from "../../utils/Context.sol";
import {IERC20Errors} from "../../interfaces/draft-IERC6093.sol";

• import {IERC20} from "./IERC20.sol"; : Imports the ERC20 interface defining the core functions for token transfers, allowances, and balance queries, which all ERC20 tokens must implement.

• import {IERC20Metadata} from "./extensions/IERC20Metadata.sol"; : Imports the ERC20Metadata interface that extends the basic ERC20 interface by adding functions for querying token name, symbol, and decimals.

• import {Context} from "../../utils/Context.sol"; : Imports the Context contract, which provides information about the current execution context, such as the sender of the transaction, useful for implementing access control.

• import {IERC20Errors} from "../../interfaces/draft-IERC6093.sol"; : Imports the IERC20Errors interface, which defines common error codes for ERC20 operations, ensuring standardized error handling.

The state variable

// to track individual account and the ammount of token own by them
mapping(address account => uint256) private _balances;

// this is a 2d mapping i will explain soon
mapping(address account => mapping(address spender => uint256))
  private _allowances;

// to store the total supply
    uint256 private _totalSupply;

// to store the token name
    string private _name;
// to store the token symbol
    string private _symbol;

Constructor

The constructor of a smart contract runs once, during deployment, and allows the deployer to define custom data for the initial contract state. For ERC20.sol, the constructor takes 2 parameters to determine the name and the symbol of the token .

// the constructor intailize the state variable _name and _symbol
constructor(string memory name_, string memory symbol_) {
        _name = name_;
        _symbol = symbol_;
    }

Getter Functions

Getter functions are public view functions in the contract that allow users to read the state (state variables )of a smart contract. For ERC20.sol, we can see the following getter functions.

// this function returns the name of erc20 token
function name() public view virtual returns (string memory) {
        return _name;
    }
// this function returns the number of decimal places used by the ERC20 token.
// Decimal places determine the smallest unit of the token that can be represented and transacted.
// For example, if a token has 18 decimals, 
//it can be divided into 10^18 (1,000,000,000,000,000,000) smaller units.
// This is important for precision in financial calculations and 
//token transfers, allowing for very fine-grained transactions.
// The standard setting for most ERC20 tokens is 18 decimals,
//which aligns with Ethereum's own precision for Ether (ETH) to  
//wei since 1 ETHER is 10^18 wei.
  function decimals() public view virtual returns (uint8) {
        return 18;
    }
// this function returns the symbol of the ERC20 token.
 function symbol() public view virtual returns (string memory) {
        return _symbol;
    }

// this function returns the total supply of the ERC20 token.
// the total supply is the total amount of tokens that exist in circulation.
 function totalSupply() public view virtual returns (uint256) {
        return _totalSupply;
    }

// remember the state variable the  mapping of a the balances to owner.
// this function returns the balance of tokens held by a specific account.
// it provides the amount of tokens that the account address has in its balance.

 function balanceOf(address account) public view virtual returns (uint256) {
        return _balances[account];
    }
// it remain the the allowances view function more about that later

Before going further into the code we need to understand some concept such transfer,approval and allowance

Balances and Transfers in ERC-20

The ERC-20 token contract plays a crucial role in managing user balances and facilitating token transfers. Think of it as a digital ledger that tracks ownership and transactions of tokens.

Token Balances

An ERC-20 contract must keep track of the balance of each user, which can be read by calling the balanceOf(address) view function. This function takes in an address and returns the amount of tokens owned by that address.

In many ERC-20 implementations, the entire initial supply of tokens is typically assigned to the contract creator when the contract is deployed. And the initial supply of token can be set by a process called mint

 function _mint(address account, uint256 value) internal {
        if (account == address(0)) {
            revert ERC20InvalidReceiver(address(0));
        }
   // will explain this function soon
        _update(address(0), account, value);
    }

Direct Token Transfers

ERC-20 tokens can be transferred between users in two primary ways. The first method involves the sender directly instructing the ERC-20 contract to transfer tokens to a recipient by calling the transfer(address _to, uint256 _amount) function.

• Function: transfer(address _to, uint256 _amount) → bool

• Description: Transfers _amount of tokens from the sender (msg.sender) to the recipient (_to). Returns true if the transfer is successful, otherwise the transaction reverts.

The transfer function deducts the specified amount from the sender's balance and credits it to the recipient's balance. If the sender does not have enough tokens, the function will revert the transaction. In most ERC-20 implementations, if the transfer is valid, it will always return true.

function transfer(address to, uint256 value) public virtual returns (bool) {
        address owner = _msgSender();
        _transfer(owner, to, value);
        return true;
    }
// this is a helper function to help user check if they are not
//sending to a zero address like my great mentor with it help perform sanity check
 function _transfer(address from, address to, uint256 value) internal {
        if (from == address(0)) {
          
            revert ERC20InvalidSender(address(0));
        }
        if (to == address(0)) {
            revert ERC20InvalidReceiver(address(0));
        }
   
        _update(from, to, value);
    }

  // This is way the main logic is implemented
 // the function to update balances and total supply during token transfers or minting/burning.
 // If `from` is the zero address, tokens are being minted, so the total supply is increased by `value`.
 // - If `to` is the zero address, tokens are being burned, so the total supply is decreased by `value`.
 // Otherwise, tokens are being transferred: the balance of `from` is decreased by `value` 
//(reverting if insufficient), and the balance of `to` is increased by `value`.
 // The function ensures that overflows are not possible and that total supply remains consistent.
 

 function _update(address from, address to, uint256 value) internal virtual {
        if (from == address(0)) {
            // Overflow check required: The rest of the code assumes that totalSupply never overflows
            _totalSupply += value;
        } else {
            uint256 fromBalance = _balances[from];
            if (fromBalance < value) {
                revert ERC20InsufficientBalance(from, fromBalance, value);
            }
            unchecked {
                // Overflow not possible: value <= fromBalance <= totalSupply.
                _balances[from] = fromBalance - value;
            }
        }

        if (to == address(0)) {
            unchecked {
                // Overflow not possible: value <= totalSupply or value <= fromBalance <= totalSupply.
                _totalSupply -= value;
            }
        } else {
            unchecked {
                // Overflow not possible: balance + value is at most totalSupply, which we know fits into a uint256.
                _balances[to] += value;
            }
        }

Approved Token Transfers

The second method for transferring tokens involves a more indirect process where:

1. The token owner first approves another address (referred to as the "spender") to spend a certain amount of tokens on their behalf.

2. The approved spender then initiates a transfer from the owner's address to a recipient.

This method is particularly useful in scenarios where smart contracts, such as decentralized exchanges, need to manage tokens on behalf of users. The ERC-20 standard includes the approve and transferFrom functions to facilitate this form of transfer. The amount that a spender is authorized to transfer can be checked using the allowance view function.

• Function: allowance(address _owner, address _spender) → uint256

• Description: Returns the remaining number of tokens that _spender is allowed to transfer on behalf of _owner.

• Function: approve(address _spender, uint256 _amount) → bool

• Description: Approves _spender to transfer up to _amount of tokens from the sender's (msg.sender) account. Returns true if the approval is successful.

• Function: transferFrom(address _from, address _to, uint256 _amount) → bool

• Description: Transfers _amount of tokens from _from to _to, using the allowance mechanism. The caller (msg.sender) must have prior approval from _from. Returns true if the transfer is successful, otherwise the transaction reverts.

The transferFrom function will decrease the spender's allowance by the amount transferred. If there are insufficient funds or the allowance is too low, the transaction will revert. As with direct transfers, the function generally either returns true or reverts if it encounters an error.

     /**
 * This function handles token transfers on behalf of a third party. 
 * When a user (the "spender") wants to transfer tokens from someone else's account 
 * (the "from" address), this function is used. First, it ensures the spender is 
 * allowed to move the specified amount of tokens by checking their allowance. 
 * If everything checks out, the function proceeds to transfer the tokens 
 * from the "from" address to the "to" address. Finally, it returns `true` 
 * to signal that the transfer was successful.
 */
function transferFrom(
    address from,
    address to,
    uint256 value
) public virtual returns (bool) {
    address spender = _msgSender();  // Identify who is trying to spend the tokens.
    _spendAllowance(from, spender, value);  // Make sure the spender has permission to spend this amount.
    _transfer(from, to, value);  // Perform the actual transfer of tokens.
    return true;  // Confirm that the transfer was successful.
}

/**
 * Before a spender can transfer tokens on someone else’s behalf, we need to make sure 
 * they have the right to do so. This function checks the current allowance (the maximum 
 * amount the spender is allowed to transfer) and then reduces it by the amount being transferred. 
 * If the spender tries to transfer more than their allowance, the function will stop the transaction. 
 * If the allowance is valid, it gets adjusted downwards to reflect the new balance.
 */
function _spendAllowance(
    address owner,
    address spender,
    uint256 value
) internal virtual {
    uint256 currentAllowance = allowance(owner, spender);  // Check the current allowance.
    if (currentAllowance != type(uint256).max) {  // If allowance isn't unlimited, verify and adjust it.
        if (currentAllowance < value) {  // Stop the transaction if the allowance is too low.
            revert ERC20InsufficientAllowance(
                spender,
                currentAllowance,
                value
            );
        }
        unchecked {
            _approve(owner, spender, currentAllowance - value, false);  // Reduce the allowance by the amount spent.
        }
    }
}

/**
 * The `_approve` function is the workhorse behind setting allowances. 
 * It updates the amount of tokens that a spender is allowed to use on behalf of the owner. 
 * If needed, it also triggers an event to notify the network of the new allowance, 
 * although in some cases (like internal adjustments) the event might not be necessary. 
 * This function ensures that everything stays in sync and that all transactions are transparent.
 */
function _approve(
    address owner,
    address spender,
    uint256 value,
    bool emitEvent
) internal virtual {
    _allowances[owner][spender] = value;  // Set the new allowance amount.

    if (emitEvent) {
        emit Approval(owner, spender, value);  // Emit an event to log this action, if necessary.
    }
}

I think with that we are done with the deep dive hope you are not drowning .

Here’s a simple example of a smart contract for a erc20 token:

pragma solidity ^0.8.20;

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

contract DragonToken is ERC20 {
    constructor(uint256 initialSupply) ERC20("WEB3BRIDGE", "WEB3BD") {
        _mint(msg.sender, initialSupply);
    }
}

Conclusion

In this article, we've taken a deep dive into the ERC-20 standard, one of the foundational elements of smart contract development on Ethereum. We've explored how ERC-20 contracts work, learned the key functions and mechanics behind them, and even looked at how to create one. By utilizing contracts from OpenZeppelin, we've not only seen how these tokens are implemented in practice but also gained insight into the Solidity code that powers these widely-used contracts. With this knowledge, you're now equipped to leverage the ERC-20 standard in your own projects, ensuring interoperability and efficiency in the ever-expanding world of decentralized finance.

see you next time ...... IAM0TI