diff --git a/README.md b/README.md index c6deed2..af27836 100644 --- a/README.md +++ b/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 +[![Solidity](https://img.shields.io/badge/Solidity-^0.8.8-black?logo=solidity&logoColor=white)](https://soliditylang.org/) [![Hardhat](https://img.shields.io/badge/Hardhat-2.x-FFF04D?logo=hardhat)](https://hardhat.org/) [![Yarn](https://img.shields.io/badge/yarn-1.22-2C8EBB?logo=yarn&logoColor=white)](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 # 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 +60175885290 -. +--- -Or You can email me@hoelee.com now. Thanks. +## 📁 Project Structure -## 5. Like this project? -If you are feeling generous, buy me a coffee! - buymeacoffee.com/hoelee +``` +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.