💰 Asset Tokenization Project — ERC20 Crowdsale with KYC (Truffle)

Dự án triển khai tokenization tài sản bằng chuẩn ERC20 (OpenZeppelin), kèm theo Crowdsale contract để bán token và cơ chế KYC Whitelisting nhằm kiểm soát ai được phép mua token. Có kèm frontend React để tương tác qua MetaMask/Web3.js.

📚 Dự án được thực hiện trong khóa học Ethereum Blockchain Developer 2025 (Udemy).

---

📁 Cấu trúc thư mục

.
├── contracts/
│   ├── MyToken.sol           # ERC20 token contract (OpenZeppelin)
│   ├── MyTokenSale.sol        # Crowdsale contract (bán token)
│   └── KYC.sol                # Whitelisting contract cho crowdsale
├── migrations/                 # Truffle migration scripts
├── test/                        # Unit test (Mocha + Chai + Chai-as-promised)
├── client/                      # Frontend React (TokenSale App)
├── truffle-config.js
├── .env                         # Cấu hình tập trung (KHÔNG commit)
└── README.md

---

⚙️ Công nghệ sử dụng

Thành phần	Công cụ
Ngôn ngữ contract	Solidity ^0.6.x
Chuẩn token	ERC20 (OpenZeppelin)
Bán token	OpenZeppelin Crowdsale contract
Kiểm soát người mua	KYC Whitelisting (custom contract)
Framework	Truffle + Truffle Boxes
Unit test	Mocha, Chai, Chai-Expect, Chai-As-Promised
Cấu hình môi trường	dotenv (.env)
Deploy	Truffle HDWallet Provider
Ví tương tác	MetaMask
Frontend	React + Web3.js

---

🚀 Bắt đầu

1. Cài đặt

git clone https://github.com/<username>/asset-tokenization.git
cd asset-tokenization
npm install

2. Cấu hình .env

Toàn bộ config (mnemonic, RPC URL, API key...) được gộp vào 1 file .env duy nhất bằng dotenv:

MNEMONIC="your twelve word seed phrase here"
INFURA_PROJECT_ID=<your_infura_project_id>
ETHERSCAN_API_KEY=<your_key>

⚠️ Không bao giờ commit file .env lên GitHub. File này đã được thêm vào .gitignore.

---

🪙 ERC20 Token (MyToken)

Token chuẩn ERC20 kế thừa từ OpenZeppelin, đại diện cho tài sản được tokenize.

Compile & migrate:

truffle compile
truffle migrate --network development

---

🛒 Crowdsale (MyTokenSale)

Contract crowdsale từ OpenZeppelin cho phép người dùng mua MyToken bằng ETH theo tỷ giá quy đổi (rate) đã cấu hình.

Migration được tách riêng để dễ quản lý:

truffle migrate --network development --f 2 --to 2

---

🔐 KYC Whitelisting

Contract KYC.sol đóng vai trò mockup kiểm soát whitelist — chỉ những địa chỉ đã được xác thực (KYC-approved) mới được phép tham gia crowdsale mua token.

---

✅ Unit Test

Chạy toàn bộ test:

truffle test

Bao gồm:

• Test cho MyToken (mint, transfer, balance...)
• Test riêng cho MyTokenSale (mua token, kiểm tra rate, kiểm tra whitelist)
• Setup chung (common setup) cho Chai/Chai-Expect để tránh lặp code giữa các file test

---

🖥️ Frontend (React + Web3.js)

cd client
npm install
npm start

Chức năng frontend:

• Kết nối MetaMask
• Hiển thị whitelist / trạng thái KYC của địa chỉ đang kết nối
• Mua token trực tiếp qua giao diện web (gọi hàm crowdsale qua Web3.js)
• Hiển thị số dư token đã mua

---

🚀 Deploy lên Testnet

Khuyến nghị dùng Sepolia thay vì Goerli (đã deprecated).

truffle migrate --network sepolia

Deploy dùng Truffle HDWallet Provider, cấu hình mnemonic lấy từ .env (xem truffle-config.js).

---

🦊 Tương tác qua MetaMask

1. Import địa chỉ contract token vào MetaMask để hiển thị số dư token (Add Token → Custom Token → paste địa chỉ contract).
2. Gửi ETH trực tiếp đến địa chỉ crowdsale contract bằng chức năng Send trong MetaMask để mua token (nếu địa chỉ đã được whitelist).
3. Hoặc mua token thông qua giao diện website (frontend React) — thân thiện hơn, có validate KYC trước khi cho phép giao dịch.

---

🐞 Các lỗi thường gặp

• Lỗi account/private key không khớp: kiểm tra lại mnemonic trong .env và đảm bảo truffle-config.js trỏ đúng biến môi trường.
• Contract not deployed / undefined: chạy lại truffle migrate --reset để deploy lại từ đầu.
• Không mua được token dù đủ ETH: kiểm tra địa chỉ ví đã được thêm vào whitelist (KYC contract) chưa.

---

📄 License

MIT License — tự do sử dụng cho mục đích học tập.