ERC-20 Token — Minimal Standard Implementation (Solidity + Foundry)

A clean, fully-tested ERC-20 token implementation built from scratch, without OpenZeppelin.
Developed using Solidity 0.8.x and Foundry, this project focuses on deeply understanding the ERC-20 standard, allowance mechanics, and real-world token behavior used across DeFi protocols.

---

Table of Contents

• Overview
• Features
• ERC-20 Architecture
• Core Mechanics (Balances & Allowances)
• Events
• Testing (Foundry)
• Running Tests
• Project Structure
• Security Considerations
• Design Decisions
• Future Improvements
• License

---

Overview

This project implements a standard-compliant ERC-20 token with a strong emphasis on:

• understanding why ERC-20 works the way it does
• modeling real-world DeFi interactions
• writing explicit, well-scoped tests
• avoiding blind dependency usage

The contract mirrors the behavior of production ERC-20 tokens used in DEXs, lending protocols, DAOs, vaults, and wallets, serving as a solid foundation for more advanced Web3 systems.

---

Features

• ERC-20 compliant interface:
  • transfer
  • approve
  • transferFrom
  • balanceOf
  • allowance
  • totalSupply
• Fixed total supply minted at deployment
• Initial supply assigned to deployer
• Full allowance system (owner → spender)
• Support for infinite allowance (type(uint256).max)
• Strict revert conditions with explicit error messages
• Complete Foundry test suite (happy paths + reverts)

---

ERC-20 Architecture

Core State Variables

• totalSupply — total number of tokens in existence
• _balances[address] — token balance ledger
• _allowances[owner][spender] — delegated spending limits

Constructor Behavior

• Mints the entire supply once at deployment
• Assigns all tokens to the deployer
• Emits a Transfer(address(0), deployer, totalSupply) event

This mirrors how most real ERC-20 tokens are initialized in production.

---

Core Mechanics

Transfers

transfer(to, amount)

• Moves tokens from msg.sender to to
• Requires sufficient balance
• Rejects zero-address transfers
• Emits Transfer

---

Allowances (Delegated Spending)

approve(spender, amount)

• Grants permission to spender to spend tokens on behalf of the owner
• Does not move tokens
• Does not check current balance
• Emits Approval

transferFrom(from, to, amount)

• Executed by the spender
• Moves tokens from from → to
• Decreases allowance unless it is infinite (MAX_UINT)
• Emits Transfer
• Emits Approval when allowance is updated

Allowance acts as a spending permission, not ownership transfer — a core DeFi concept.

---

Events

Event	Description
Transfer(address from, address to, uint256 value)	Emitted on every token movement
Approval(address owner, address spender, uint256 value)	Emitted when allowance is set or updated

---

Testing (Foundry)

The project includes an 11-test Foundry suite covering:

Constructor

• initial supply minting
• correct deployer balance
• Transfer from zero address

Transfers

• successful transfers
• insufficient balance reverts
• zero-address reverts
• state immutability on revert

Approvals

• allowance creation
• approval event emission
• zero-address spender reverts

transferFrom

• allowance consumption
• balance updates
• allowance reduction
• allowance insufficient reverts
• owner balance insufficient reverts
• infinite allowance behavior (MAX_UINT)

Foundry cheatcodes used:

• vm.prank() — simulate callers
• vm.expectRevert() — validate failures
• vm.expectEmit() — assert events
• assertEq, assertTrue — state validation

---

Running Tests

Install Foundry

curl -L https://foundry.paradigm.xyz | bash

foundryup

Build

forge build

Run tests

forge test -vv

---

Project Structure

src/

└── MyToken.sol

test/

└── MyToken.t.sol

Each repository focuses on one protocol / concept, keeping scope explicit and reviewable.

---

Security Considerations

• No reentrancy risk (no external calls)
• Strict input validation
• Explicit revert messages
• No privileged roles (pure ERC-20 model)
• Allowance behavior matches production expectations
• Infinite allowance handled safely

---

Design Decisions

• No OpenZeppelin: implementation written manually to ensure deep understanding
• Fixed supply: simplifies reasoning and mirrors BTC-like token models
• Allowance logic explicit: no hidden behavior
• MAX_UINT support: required for real DeFi compatibility
• Internal helper functions (_transfer, _approve) to centralize logic

---

Future Improvements

• Mintable / burnable extension (separate branch or repo)
• Permit (EIP-2612)
• Snapshot support
• Pausable transfers
• Role-based access (Ownable / AccessControl)
• Gas optimizations
• ERC-20 metadata interface split

---

License

MIT License — free to use, modify, and distribute.