Skip to content

Commit 042c1f7

Browse files
CodesenSysCodesenSys
authored
Update README.md
1 parent 05c70da commit 042c1f7

1 file changed

Lines changed: 165 additions & 66 deletions

File tree

‎README.md‎

Lines changed: 165 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -1,66 +1,165 @@
1-
## Foundry
2-
3-
**Foundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.**
4-
5-
Foundry consists of:
6-
7-
- **Forge**: Ethereum testing framework (like Truffle, Hardhat and DappTools).
8-
- **Cast**: Swiss army knife for interacting with EVM smart contracts, sending transactions and getting chain data.
9-
- **Anvil**: Local Ethereum node, akin to Ganache, Hardhat Network.
10-
- **Chisel**: Fast, utilitarian, and verbose solidity REPL.
11-
12-
## Documentation
13-
14-
https://book.getfoundry.sh/
15-
16-
## Usage
17-
18-
### Build
19-
20-
```shell
21-
$ forge build
22-
```
23-
24-
### Test
25-
26-
```shell
27-
$ forge test
28-
```
29-
30-
### Format
31-
32-
```shell
33-
$ forge fmt
34-
```
35-
36-
### Gas Snapshots
37-
38-
```shell
39-
$ forge snapshot
40-
```
41-
42-
### Anvil
43-
44-
```shell
45-
$ anvil
46-
```
47-
48-
### Deploy
49-
50-
```shell
51-
$ forge script script/Counter.s.sol:CounterScript --rpc-url <your_rpc_url> --private-key <your_private_key>
52-
```
53-
54-
### Cast
55-
56-
```shell
57-
$ cast <subcommand>
58-
```
59-
60-
### Help
61-
62-
```shell
63-
$ forge --help
64-
$ anvil --help
65-
$ cast --help
66-
```
1+
# ERC20 Implementation Foundry | Solady
2+
3+
A production-grade, security-first ERC20 token implementation built by **CodesenSys** using **Foundry**.
4+
This repository is not a toy example. It is designed as a **reference-grade, extensible, auditable ERC20 codebase** suitable for real-world deployments.
5+
6+
The focus is on:
7+
- Correctness
8+
- Security
9+
- Gas efficiency
10+
- Testability
11+
- Upgrade-readiness
12+
- Professional engineering standards
13+
14+
---
15+
16+
## Why This Repository Exists
17+
18+
Most ERC20 examples stop at “it compiles and transfers tokens”.
19+
20+
This implementation goes further:
21+
22+
- Models **real production concerns**
23+
- Enforces **strict invariants**
24+
- Uses **Foundry’s testing, fuzzing, and tooling**
25+
- Separates **business logic from mechanics**
26+
- Documents **design decisions explicitly**
27+
- Provides a **clean base for further token systems** (vesting, staking, governance, bridges, etc.)
28+
29+
This is intended to be:
30+
- A **starting point for serious token projects**
31+
- A **learning reference for professional Solidity engineers**
32+
- A **baseline for audits and production deployments**
33+
34+
---
35+
36+
## Architecture Overview
37+
38+
The system is structured around:
39+
40+
- Core ERC20 storage and accounting
41+
- Explicit allowance and approval mechanics
42+
- Internal mint/burn primitives
43+
- Strict invariant enforcement:
44+
- Total supply consistency
45+
- Balance conservation
46+
- Allowance correctness
47+
- Clear separation between:
48+
- Public API
49+
- Internal mechanics
50+
- Policy layers (who can mint, burn, pause, etc.)
51+
52+
Design goals:
53+
- Predictable storage layout
54+
- Minimal branching in hot paths
55+
- Explicit revert reasons
56+
- Zero ambiguity in accounting logic
57+
58+
---
59+
60+
## ERC20 Features Implemented
61+
62+
- Standard ERC20 interface:
63+
- `totalSupply()`
64+
- `balanceOf()`
65+
- `transfer()`
66+
- `approve()`
67+
- `transferFrom()`
68+
- `allowance()`
69+
- Internal primitives:
70+
- `_mint()`
71+
- `_burn()`
72+
- `_transfer()`
73+
- `_approve()`
74+
- Full event compliance:
75+
- `Transfer`
76+
- `Approval`
77+
- Safety checks:
78+
- Zero address protection
79+
- Underflow/overflow safety (Solidity ^0.8)
80+
- Allowance spending correctness
81+
- Gas-optimized flow for:
82+
- Transfers
83+
- Allowance updates
84+
- Supply changes
85+
86+
---
87+
88+
## Engineering Principles
89+
90+
### 1. Correctness Over Convenience
91+
Every state mutation is explicit. No hidden side effects. No magical flows.
92+
93+
### 2. Invariants First
94+
The implementation is written around invariants:
95+
- Sum of balances == totalSupply
96+
- Transfers do not create or destroy value
97+
- Mint and burn are the only supply-changing operations
98+
99+
### 3. Minimal Surface Area
100+
No unnecessary features in the core layer. Policy features (roles, caps, pauses, etc.) are intended to be layered on top.
101+
102+
### 4. Audit-First Design
103+
The code is structured to be:
104+
- Readable
105+
- Traceable
106+
- Verifiable
107+
- Easy to reason about in formal or manual audits
108+
109+
---
110+
111+
## Testing Strategy (Foundry)
112+
113+
This repository uses Foundry for:
114+
115+
- Unit tests
116+
- Invariant tests
117+
- Fuzz testing
118+
- Gas profiling
119+
120+
Test categories include:
121+
- Transfer correctness
122+
- Allowance behavior
123+
- Mint/Burn supply invariants
124+
- Edge cases:
125+
- Zero amounts
126+
- Self-transfers
127+
- Boundary values
128+
- Full allowance spending
129+
- Fuzzing:
130+
- Randomized transfer sequences
131+
- Randomized allowance consumption
132+
- Randomized mint/burn operations
133+
134+
This ensures:
135+
- No silent balance corruption
136+
- No supply drift
137+
- No allowance desync
138+
139+
---
140+
141+
## Project Structure
142+
src/<br />
143+
├── ERC20.sol # Core ERC20 implementation<br />
144+
├── interfaces/<br />
145+
│ └── IERC20.sol # ERC20 interface<br />
146+
└── extensions/ # Future extensions (cap, roles, etc<br />
147+
<br />
148+
test/<br />
149+
├── ERC20.t.sol # Unit tests<br />
150+
├── ERC20.fuzz.t.sol # Fuzz tests<br />
151+
└── ERC20.invariant.t.sol# Invariant tests<br />
152+
<br />
153+
##Extending This Implementation
154+
155+
This base is intentionally clean and minimal.
156+
It is designed to be extended with:
157+
Capped supply
158+
Role-based minting
159+
Pausable transfers
160+
Vesting systems
161+
Staking systems
162+
Governance voting power
163+
Bridging adapters
164+
Upgradeable proxies
165+
Without modifying the core accounting engine.

0 commit comments

Comments
 (0)