🚀 完整区块链系统 - 从零到上链

一个完整的区块链系统演示项目，包含智能合约、NFT、市场等功能，模拟以太坊公链的核心功能。让您从零开始体验 Web3 的魅力！

📋 目录

项目简介
功能特性
项目结构
快速开始
部署流程
使用指南
智能合约说明
前端界面
测试
常见问题
流程图

🎯 项目简介

这是一个完整的区块链系统演示项目，旨在帮助开发者和初学者：

理解区块链基础：通过实际代码学习智能合约开发
体验 Web3 功能：从代币到 NFT，再到市场交易
学习部署流程：从本地测试到测试网，再到主网
感受数据上链：真实体验区块链的不可篡改特性

核心组件

ERC20 代币合约：标准代币功能，支持购买、转账、销毁
ERC721 NFT 合约：NFT 铸造、转账、元数据管理
NFT 市场合约：NFT 买卖、拍卖功能
前端 DApp：Web3 交互界面

✨ 功能特性

💰 ERC20 代币 (MyToken)

✅ 标准 ERC20 功能（转账、余额查询）
✅ 代币购买（使用 ETH 购买代币）
✅ 代币铸造（Owner 权限）
✅ 代币销毁（Burn）
✅ 暂停/恢复功能
✅ 最大供应量限制
✅ 价格管理

🎨 ERC721 NFT (MyNFT)

✅ 标准 ERC721 功能
✅ NFT 铸造（公共和免费）
✅ 批量铸造
✅ 元数据 URI 管理
✅ NFT 枚举
✅ 每地址持有量限制
✅ 最大供应量控制

🏪 NFT 市场 (NFTMarketplace)

✅ NFT 上架销售
✅ NFT 购买
✅ NFT 拍卖
✅ 市场手续费管理
✅ 取消上架
✅ 出价和竞拍

🌐 前端 DApp

✅ MetaMask 钱包连接
✅ 余额查询
✅ 代币购买界面
✅ NFT 铸造界面
✅ 交易状态显示
✅ 响应式设计

📁 项目结构

blockchain/
├── contracts/              # 智能合约
│   ├── MyToken.sol        # ERC20 代币合约
│   ├── MyNFT.sol          # ERC721 NFT 合约
│   └── NFTMarketplace.sol # NFT 市场合约
├── scripts/               # 部署脚本
│   └── deploy.js          # 主部署脚本
├── test/                  # 测试文件
│   ├── MyToken.test.js
│   ├── MyNFT.test.js
│   └── NFTMarketplace.test.js
├── frontend/              # 前端应用
│   ├── pages/            # Next.js 页面
│   ├── styles/           # 样式文件
│   └── package.json
├── deployments/          # 部署信息（自动生成）
├── hardhat.config.js     # Hardhat 配置
├── package.json          # 项目依赖
└── README.md            # 本文档

🚀 快速开始

环境要求

Node.js 16+
npm 或 yarn
MetaMask 浏览器扩展（用于前端交互）

安装步骤

1. 克隆项目

cd /Users/sh01728ml/code/blockchain

2. 安装依赖

npm install

3. 配置环境变量

复制 .env.example 并创建 .env 文件：

cp .env.example .env

编辑 .env 文件，填入您的配置：

# 私钥（用于部署合约）
# 注意：不要将真实私钥提交到 Git！
PRIVATE_KEY=your_private_key_here

# RPC 节点（可选，有默认值）
SEPOLIA_RPC_URL=https://rpc.sepolia.org
ETHERSCAN_API_KEY=your_etherscan_api_key

4. 编译合约

npm run compile

5. 运行测试

npm test

6. 一键启动开发环境（推荐）✨

最简单的方式 - 一个命令搞定：

npm run dev

这个命令会自动：

✅ 编译合约（如果需要）
✅ 启动本地 Hardhat 节点
✅ 等待节点就绪
✅ 部署所有合约
✅ 更新前端环境变量

同时启动前端：

npm run dev:full

6.1 分步启动（可选）

如果你想分步操作：

# 终端 1: 启动节点
npm run node

# 终端 2: 部署合约
npm run deploy:local

📦 部署流程

流程图

详细步骤

步骤 1: 本地部署（开发测试）

# 1. 启动本地 Hardhat 节点
npm run node

# 2. 在另一个终端部署合约
npm run deploy:local

# 3. 记录部署的合约地址
# 合约地址会显示在终端，并保存到 deployments/localhost.json

步骤 2: 测试网部署（Sepolia）

# 1. 确保 .env 文件配置了 PRIVATE_KEY 和 SEPOLIA_RPC_URL
# 2. 确保账户有足够的测试 ETH（从 faucet 获取）

# 3. 部署到 Sepolia 测试网
npm run deploy:testnet

# 4. 等待区块确认后，合约会自动验证

步骤 3: 主网部署（谨慎！）

# ⚠️ 警告：主网部署需要真实 ETH，请谨慎操作！

# 1. 确保 .env 文件配置了主网 RPC
# 2. 确保账户有足够的 ETH（用于 gas 费）

# 3. 部署到主网
npm run deploy:mainnet

部署后操作

保存合约地址：部署脚本会自动保存到 deployments/{network}.json
更新前端配置：在 frontend/.env.local 中配置合约地址
验证合约：在 Etherscan 上验证合约代码（测试网和主网）

📖 使用指南

智能合约交互

1. 购买代币

// 使用 ethers.js
const tokenContract = new ethers.Contract(
  TOKEN_ADDRESS,
  TOKEN_ABI,
  signer
);

// 购买代币（需要发送 ETH）
const tx = await tokenContract.buyTokens({ 
  value: ethers.parseEther("0.001") 
});
await tx.wait();

2. 铸造 NFT

const nftContract = new ethers.Contract(
  NFT_ADDRESS,
  NFT_ABI,
  signer
);

// 铸造 NFT（需要支付 mintPrice）
const price = await nftContract.mintPrice();
const tx = await nftContract.mint("ipfs://QmYourHash", { 
  value: price 
});
await tx.wait();

3. 上架 NFT 到市场

const marketplace = new ethers.Contract(
  MARKETPLACE_ADDRESS,
  MARKETPLACE_ABI,
  signer
);

// 1. 先授权市场合约
await nftContract.approve(MARKETPLACE_ADDRESS, tokenId);

// 2. 上架 NFT
const price = ethers.parseEther("0.1");
await marketplace.listNFT(tokenId, price);

4. 购买 NFT

// 购买上架的 NFT
await marketplace.buyNFT(tokenId, { 
  value: listingPrice 
});

前端使用

1. 安装前端依赖

cd frontend
npm install

2. 配置合约地址

创建 frontend/.env.local：

NEXT_PUBLIC_TOKEN_ADDRESS=0x...
NEXT_PUBLIC_NFT_ADDRESS=0x...
NEXT_PUBLIC_MARKETPLACE_ADDRESS=0x...

3. 启动前端

npm run dev

访问 http://localhost:3000

4. 连接钱包

点击"连接 MetaMask 钱包"
在 MetaMask 中确认连接
切换到正确的网络（本地/测试网）

🔧 智能合约说明

MyToken.sol (ERC20)

功能：

标准 ERC20 代币实现
使用 ETH 购买代币
Owner 可以铸造新代币
用户可以销毁自己的代币
支持暂停/恢复功能

主要函数：

buyTokens(): 使用 ETH 购买代币
mint(address, amount): 铸造代币（仅 Owner）
burn(amount): 销毁代币
pause() / unpause(): 暂停/恢复（仅 Owner）

MyNFT.sol (ERC721)

功能：

标准 ERC721 NFT 实现
公共铸造（需要支付费用）
Owner 免费铸造
批量铸造
元数据 URI 管理

主要函数：

mint(tokenURI): 公共铸造（需支付 mintPrice）
freeMint(to, tokenURI): 免费铸造（仅 Owner）
batchMint(to, tokenURI, amount): 批量铸造（仅 Owner）

NFTMarketplace.sol

功能：

NFT 上架销售
NFT 购买
NFT 拍卖
市场手续费管理

主要函数：

listNFT(tokenId, price): 上架 NFT
buyNFT(tokenId): 购买 NFT
cancelListing(tokenId): 取消上架
createAuction(tokenId, startingPrice, duration): 创建拍卖
placeBid(tokenId): 出价
endAuction(tokenId): 结束拍卖

🧪 测试

运行所有测试

npm test

运行特定测试

# 测试代币合约
npx hardhat test test/MyToken.test.js

# 测试 NFT 合约
npx hardhat test test/MyNFT.test.js

# 测试市场合约
npx hardhat test test/NFTMarketplace.test.js

测试覆盖率

npx hardhat coverage

📊 流程图详解

完整系统架构

代币购买流程

NFT 铸造流程

NFT 市场交易流程

❓ 常见问题

Q: 如何获取测试 ETH？

Sepolia 测试网: https://sepoliafaucet.com/
Goerli 测试网: https://goerlifaucet.com/
本地网络: Hardhat 会自动提供测试账户和 ETH

Q: 部署失败怎么办？

A: 检查以下几点：

账户是否有足够的 ETH（用于 gas 费）
网络配置是否正确
私钥是否正确配置
RPC 节点是否可用

Q: 如何查看合约代码？

本地部署：查看 artifacts/contracts/ 目录
测试网/主网：在 Etherscan 上查看（需要先验证合约）

Q: 前端无法连接钱包？

确保安装了 MetaMask 扩展
确保 MetaMask 连接到正确的网络
检查浏览器控制台是否有错误

Q: 如何验证合约？

npx hardhat verify --network sepolia <CONTRACT_ADDRESS> <CONSTRUCTOR_ARGS>

Q: Gas 费用太高怎么办？

使用测试网（Sepolia/Goerli）进行测试
在 gas 价格较低时部署
优化合约代码减少 gas 消耗

🎓 学习资源

📝 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📞 支持

如有问题，请创建 Issue 或联系维护团队。

Happy Coding! 🚀 让我们一起探索 Web3 的世界！

web3.0入门项目

🚀 完整区块链系统 - 从零到上链

📋 目录

🎯 项目简介

核心组件

✨ 功能特性

💰 ERC20 代币 (MyToken)

🎨 ERC721 NFT (MyNFT)

🏪 NFT 市场 (NFTMarketplace)

🌐 前端 DApp

📁 项目结构

🚀 快速开始

环境要求

安装步骤

1. 克隆项目

2. 安装依赖

3. 配置环境变量

4. 编译合约

5. 运行测试

6. 一键启动开发环境（推荐）✨

6.1 分步启动（可选）

📦 部署流程

流程图

详细步骤

步骤 1: 本地部署（开发测试）

步骤 2: 测试网部署（Sepolia）

步骤 3: 主网部署（谨慎！）

部署后操作

📖 使用指南

智能合约交互

1. 购买代币

2. 铸造 NFT

3. 上架 NFT 到市场

4. 购买 NFT

前端使用

1. 安装前端依赖

2. 配置合约地址

3. 启动前端

4. 连接钱包

🔧 智能合约说明

MyToken.sol (ERC20)

MyNFT.sol (ERC721)

NFTMarketplace.sol

🧪 测试

运行所有测试

运行特定测试

测试覆盖率

📊 流程图详解

完整系统架构

代币购买流程

NFT 铸造流程

NFT 市场交易流程

❓ 常见问题

Q: 如何获取测试 ETH？

Q: 部署失败怎么办？

Q: 如何查看合约代码？

Q: 前端无法连接钱包？

Q: 如何验证合约？

Q: Gas 费用太高怎么办？

🎓 学习资源

📝 许可证

🤝 贡献

📞 支持

评论区