docs: enhance README as a polished learning showcase
This commit is contained in:
308
README.md
308
README.md
@@ -1,184 +1,182 @@
|
||||
# Practical Sample With Hardhat + Solidity
|
||||
# Hardhat Simple Storage 🚀
|
||||
|
||||
A fully functional Smart Contract wrriten with ```solidity```, ```node.js``` and using ```Hardhat``` to show usage of all kinds of standard development features, including:
|
||||
* running blockchain node in localhost - ```hardhat``` & ```ganache```
|
||||
* solidity prettier code beautifier setup
|
||||
* standard of developing Smart Contract with ```solidity```
|
||||
* standard of developing ```node.js``` script to use ```hardhat``` library efficiently
|
||||
* check gas fee & gas price in real-time, with usage of ```coverage```
|
||||
* auto verify contract on Etherscan.io
|
||||
* creating automate test cases - unit test & staging test
|
||||
* creating tasks etc.
|
||||
* refactor codes to reduce gas fee
|
||||
* write code in best practice, with usage of ```solhint```
|
||||
* prettier ```solidity``` & ```node.js``` code
|
||||
* gitea version control
|
||||
[](https://soliditylang.org/) [](https://hardhat.org/) [](https://yarnpkg.com/)
|
||||
|
||||
This project mainly to keep as a reference for future Web 3.0 Developments.
|
||||
> **A hands-on learning project** building and shipping Solidity smart contracts with **Hardhat** — from a local node all the way to a verified deployment on the **Sepolia testnet**. This is my personal study ground for Web 3.0 smart-contract development.
|
||||
|
||||
---
|
||||
### Success Deploy & Verified Of This Smart Contract To Sepolia Testnet
|
||||
|
||||
0xc2022b56eBC140B5FebCf9FBaB14c17db4C315C4
|
||||
https://sepolia.etherscan.io/address/0xc2022b56eBC140B5FebCf9FBaB14c17db4C315C4#code
|
||||
Via deploy.js
|
||||
https://sepolia.etherscan.io/address/0x3a827C119e1D746bb3C7bcbbf95c55246C8CcBdd#code
|
||||
Via yarn hardhat deploy --network sepolia
|
||||
## 📌 What I Learned in This Project
|
||||
|
||||
### Public Reported Hacked Code References:
|
||||
This repository documents my learning journey building smart contracts. Here's what it covers:
|
||||
|
||||
This website is records of all kind previous hacked smart contract:
|
||||
| # | Concept | What I explored |
|
||||
|---|---------|-----------------|
|
||||
| 1 | **Solidity fundamentals** | Data types (`uint`, `int`, `address`, `string`, `bytes`), `state` vs `memory` vs `calldata`, `view`/`pure` functions, `structs`, `mappings`, `arrays` |
|
||||
| 2 | **Hardhat workflow** | Local blockchain node (`hardhat` & `ganache`), compile, deploy, `hardhat console`, custom `tasks` |
|
||||
| 3 | **Contract deployment** | Both the classic `scripts/` flow and the modern **hardhat-deploy** pattern with reusable `deploy/` scripts |
|
||||
| 4 | **Real-world oracle integration** | **Chainlink price feeds** to value donations in USD (`PriceConverter`, `FundMe`) with mock deployment for local testing |
|
||||
| 5 | **Testing** | Unit tests + **staging tests against Sepolia**, `--grep` filtering, coverage reports |
|
||||
| 6 | **Gas optimization** | Coding patterns to reduce gas (prefer `private`, use `constant`/`immutable`) — verified with `hardhat-gas-reporter` |
|
||||
| 7 | **Code quality** | `solhint` best-practice linting, `prettier` + `prettier-plugin-solidity` formatting |
|
||||
| 8 | **Block explorer verification** | Auto-verification of contracts on Etherscan |
|
||||
| 9 | **Version control** | Git + Gitea workflow for source control |
|
||||
| 10 | **Security awareness** | Studied historical exploited contracts via [rekt.news](https://rekt.news/leaderboard/) |
|
||||
|
||||
https://rekt.news/leaderboard/
|
||||
---
|
||||
|
||||
## 📦 Smart Contracts
|
||||
|
||||
## 1. Git Version Control
|
||||
First time initialize:
|
||||
```
|
||||
git config --global user.name "hoelee"
|
||||
git config --global user.email "me@hoelee.com"
|
||||
git init .
|
||||
git add .
|
||||
git checkout -b main
|
||||
git commit -m "Initial Commit"
|
||||
git remote set-url origin https://username:accessToken@git.hoelee.com/hoelee/ethers-simple-storage.git
|
||||
git credential-cache exit // Fix Credential Error
|
||||
```
|
||||
| Contract | Purpose |
|
||||
|----------|---------|
|
||||
| [`SimpleStorage.sol`](contracts/SimpleStorage.sol) | Core concepts: storage variables, data types, `structs`, `mappings`, `view`/`pure` functions |
|
||||
| [`FundMe.sol`](contracts/FundMe.sol) | Real-world pattern: accept ETH, track funders, withdraw with a minimum funding value in **USD** |
|
||||
| [`PriceConverter.sol`](contracts/PriceConverter.sol) | Library that converts ETH amounts to USD using a **Chainlink price feed** |
|
||||
|
||||
Standard Update:
|
||||
```
|
||||
git add .
|
||||
git commit -m "Describe what changes"
|
||||
git push -u origin main
|
||||
// After set this, later easier usage via below line
|
||||
git push
|
||||
git pull
|
||||
```
|
||||
---
|
||||
|
||||
Development need exlude file can create root file with name .gitignore
|
||||
```
|
||||
node_modules
|
||||
package.json
|
||||
img
|
||||
artifacts
|
||||
cache
|
||||
coverage
|
||||
.env
|
||||
.*
|
||||
README.md
|
||||
coverage.json
|
||||
```
|
||||
## ✅ Live Versions — Verified on Sepolia Testnet
|
||||
|
||||
## 2. Setup Visual Studio Code Development Environment
|
||||
This project has been **successfully deployed AND verified** on the EthSepolia testnet:
|
||||
|
||||
Windows need to download install WSL
|
||||
```
|
||||
wsl --set-default Ubuntu-22.04
|
||||
mkdir theProjectFolderName
|
||||
cd theProjectFolderName
|
||||
code .
|
||||
// Install nvm
|
||||
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
|
||||
nvm install 16.14.2
|
||||
nvm install node.js
|
||||
nvm install 18 // Update node JS to v18
|
||||
```
|
||||
Visual Studio need to update code setting
|
||||
```
|
||||
"[solidity]": {
|
||||
"editor.defaultFormatter":"NomicFoundation.hardhat-solidity"
|
||||
}
|
||||
```
|
||||
Preparing of solidity development environment:
|
||||
```
|
||||
corepack enable // Enable yarn
|
||||
yarn install solc
|
||||
yarn add solc@0.8.7fixed
|
||||
yarn solcjs --bin --abi --include-path node_modules/ --base-path . -o . SimpleStorage.sol
|
||||
yarn add ethers // Compiler Error, Downgraded to v5.7.2
|
||||
yarn add fs-extra
|
||||
yarn add dotenv
|
||||
yarn add prettier
|
||||
yarn add prettier-plugin-solidity
|
||||
```
|
||||
Preparing of Hardhat Development Environment
|
||||
```
|
||||
yarn init
|
||||
// Manual delete main: index.js in package.json
|
||||
yarn add --dev hardhat // Production no need --dev
|
||||
nvm install 18
|
||||
nvm use 18
|
||||
nvm alias default 18
|
||||
corepack enable // Enable yarn
|
||||
yarn hardhat
|
||||
yarn add --dev prettier prettier-plugin-solidity
|
||||
yarn add --dev dotenv
|
||||
yarn add --dev @nomiclabs/hardhat-etherscan // Auto verify Etherscan Samrt Contract
|
||||
yarn add --dev @nomiclabs/hardhat-waffle
|
||||
yarn add --dev solhint
|
||||
yarn add --dev @nomiclabs/hardhat-ethers@npm:hardhat-deploy-ethers ethers
|
||||
yarn add --dev hardhat-gas-reporter
|
||||
yarn add --dev solidity-coverage
|
||||
yarn add --dev solhint
|
||||
```
|
||||
Other Terminal Useful Command 1:
|
||||
```
|
||||
// For Debuging Hardhat
|
||||
npx hardhat --versose
|
||||
| Deployed via | Contract Address | Etherscan (verified) |
|
||||
|---|---|---|
|
||||
| `deploy.js` script | `0xc2022b56eBC140B5FebCf9FBaB14c17db4C315C4` | [View code](https://sepolia.etherscan.io/address/0xc2022b56eBC140B5FebCf9FBaB14c17db4C315C4#code) |
|
||||
| `yarn hardhat deploy --network sepolia` | `0x3a827C119e1D746bb3C7bcbbf95c55246C8CcBdd` | [View code](https://sepolia.etherscan.io/address/0x3a827C119e1D746bb3C7bcbbf95c55246C8CcBdd#code) |
|
||||
|
||||
// For Recompile
|
||||
yarn hardhat clean // Or manual delete artifacts & cache folder
|
||||
npm install
|
||||
---
|
||||
|
||||
## 🛠️ Tech Stack
|
||||
|
||||
- **Solidity `^0.8.8`** — smart contract language (EVM-compatible: Ethereum, Avalanche, Fantom, Polygon)
|
||||
- **Hardhat 2.x** — development environment
|
||||
- **Ethers.js** — Ethereum JavaScript library
|
||||
- **hardhat-deploy** — cleaner deployment workflow
|
||||
- **Chainlink** — decentralized price feeds
|
||||
- **Node.js + Yarn** — package management
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Getting Started
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Node.js 18+ (this project used `nvm install 18`)
|
||||
- Yarn (`corepack enable`)
|
||||
- WSL on Windows (for the smoothest local setup)
|
||||
|
||||
### Install & Compile
|
||||
|
||||
```bash
|
||||
git clone https://github.com/hoelee/hardhat-simple-storage.git
|
||||
cd hardhat-simple-storage
|
||||
|
||||
yarn add --dev hardhat prettier prettier-plugin-solidity dotenv \
|
||||
@nomiclabs/hardhat-ethers@npm:hardhat-deploy-ethers ethers \
|
||||
hardhat-gas-reporter solidity-coverage solhint
|
||||
|
||||
// For Listing Hardhat Local Blockchain node
|
||||
yarn hardhat accounts
|
||||
yarn hardhat node // Run in Dedicated Terminal, Getting Blockchain server
|
||||
yarn hardhat console --network localhost // Short Life To Test Solidity Code In Terminal
|
||||
yarn hardhat compile
|
||||
yarn hardhat run scripts/deploy.js --network localhost
|
||||
yarn hardhat custom-task-name
|
||||
// Need create file in /tasks/custom-task-name.js
|
||||
// Add import in hardhat.config.js -> requir("/tasks/custom-task-name");
|
||||
yarn hardhat test
|
||||
yarn hardhat test --grep customSearchKeyword
|
||||
// Only will run the test with describe test that contain "customSearchKeyword"
|
||||
```
|
||||
Other Terminal Useful Command 2:
|
||||
|
||||
### Run Tests (Local)
|
||||
|
||||
```bash
|
||||
yarn hardhat test # unit tests
|
||||
yarn hardhat test --grep <keyword> # run matching tests only
|
||||
yarn hardhat coverage # test coverage report
|
||||
```
|
||||
// For Getting Gas Used & Gas Price
|
||||
yarn hardhat test
|
||||
// Will create a file in ./gas-report.txt
|
||||
// With .env of etherscan API key
|
||||
// For Getting Coverage
|
||||
yarn hardhat coverage
|
||||
// Checking code usage & tested percentage
|
||||
// For Checking Code Best Practice
|
||||
|
||||
### Local Development Node
|
||||
|
||||
```bash
|
||||
yarn hardhat node # run local blockchain in a dedicated terminal
|
||||
yarn hardhat console --network localhost # interactive Solidity REPL
|
||||
yarn hardhat deploy --tags mocks --network localhost # deploy local price-feed mocks
|
||||
```
|
||||
|
||||
### Deploy to Sepolia
|
||||
|
||||
```bash
|
||||
# classic script
|
||||
yarn hardhat run scripts/deploy.js --network sepolia
|
||||
|
||||
# hardhat-deploy pattern
|
||||
yarn hardhat deploy --network sepolia
|
||||
```
|
||||
|
||||
### Gas Reporting & Code Quality
|
||||
|
||||
```bash
|
||||
yarn hardhat test # produces ./gas-report.txt when ETHERSCAN_API_KEY .env is set
|
||||
yarn solhint contracts/*.sol
|
||||
// For Get Fake Price Feed On Localhost & Ganache
|
||||
yarn hardhat deploy --tags mocks --network localhost
|
||||
yarn prettier --write . # format Solidity + JS
|
||||
```
|
||||
Debug ```Node.js``` need to open **Javascript Debug Terminal** first, via ```ctrl + shift + p```
|
||||
|
||||
#### Reduce Gas Used:
|
||||
* Prioritize use ```private``` instead of ```public```
|
||||
* Use ```constant``` which declare once in constructor
|
||||
* Use ```immutable ``` which declare once only
|
||||
---
|
||||
|
||||
This is because blockchain will have higher ```read``` and ```store``` gas fee on storage block, lesser in bytes code block.
|
||||
## 🧠 Key Takeaways (Gas Optimization)
|
||||
|
||||
Working on-chain made me think hard about **cost**:
|
||||
|
||||
## 3. Known Issue
|
||||
* Dependencies combination is old, need update...
|
||||
* ...
|
||||
- Prefer `private` over `public` — avoids auto-generated (and expensive) getters
|
||||
- Use `constant` / `immutable` for values set once at deploy time
|
||||
- Remember: blockchain storage (`store`) and retrieval (`read`) cost the most gas — minimize them
|
||||
|
||||
### Find a bug?
|
||||
If you found an issue or would like to submit an improvement to this demo project, please submit an issue using the issues tab above.
|
||||
> Blockchain charges a higher gas fee for storage operations than for bytecode; write minimal, optimized state.
|
||||
|
||||
## 4. Looking Web 3.0 Developer For Your Project?
|
||||
**Mr Hoelee** is Welcome Web 3.0 Remote Job, Contact Me Immediately Via WhatsApp <a href="https://wa.me/60175885290">+60175885290</a>
|
||||
.
|
||||
---
|
||||
|
||||
Or You can email <a href="mailto:me@hoelee.com">me@hoelee.com</a> now. Thanks.
|
||||
## 📁 Project Structure
|
||||
|
||||
## 5. Like this project?
|
||||
If you are feeling generous, buy me a coffee! - <a href="https://buymeacoffee.com/hoelee">buymeacoffee.com/hoelee</a>
|
||||
```
|
||||
hardhat-simple-storage/
|
||||
├── contracts/ # Solidity source (SimpleStorage, FundMe, PriceConverter)
|
||||
├── deploy/ # hardhat-deploy scripts (mocks, fund-me, storage)
|
||||
├── deployments/ # Saved deployment artifacts per network (localhost, sepolia)
|
||||
├── ignition/ # Hardhat Ignition module
|
||||
├── scripts/ # Classic deploy / fund / withdraw scripts
|
||||
├── tasks/ # Custom Hardhat tasks (e.g. block-number)
|
||||
├── test/ # unit/ + staging/ (Sepolia) tests
|
||||
├── utils/ # Shared utilities
|
||||
├── helper-hardhat-config.js # Per-network config (price feeds, RPC URLs)
|
||||
└── hardhat.config.js # Hardhat configuration
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Known Issues
|
||||
|
||||
- The dependency combination is old — worth a dependency-upgrade pass.
|
||||
- Personal-study project; feel free to fork and improve it.
|
||||
|
||||
**Found a bug or have an idea?** Open an issue using the issues tab above. 🙏
|
||||
|
||||
---
|
||||
|
||||
## 🛡️ Security Note
|
||||
|
||||
The [rekt.news leaderboard](https://rekt.news/leaderboard/) is a great reference for learning from real-world exploited contracts — every smart-contract developer should study it to avoid repeating the mistakes of the past.
|
||||
|
||||
---
|
||||
|
||||
## 💼 Looking for a Web 3.0 Developer?
|
||||
|
||||
Hi, I'm **Mr Hoelee** 👋 — I enjoy building pragmatic, secure smart-contract solutions and I am **open to Web 3.0 remote work**.
|
||||
|
||||
- 📱 WhatsApp: **+60 17-585 5290** ([click to chat](https://wa.me/60175885290))
|
||||
- ✉️ Email: **[me@hoelee.com](mailto:me@hoelee.com)**
|
||||
- 📺 Portfolio: **[hoelee.com](https://hoelee.com)**
|
||||
|
||||
I bring a full-stack background (PHP, Java, JavaScript) plus hands-on Blockchain (Solidity, Hardhat, ethers.js) experience to the table. Let's build something great together!
|
||||
|
||||
---
|
||||
|
||||
## ☕ Support
|
||||
|
||||
If you find this project useful, you can [buy me a coffee](https://buymeacoffee.com/hoelee) — every cup fuels more learning. ⛽
|
||||
|
||||
---
|
||||
|
||||
## 📄 License
|
||||
|
||||
`UNLICENSED` — free to use, learn from, and build upon.
|
||||
|
||||
Reference in New Issue
Block a user