Hello Contract DApp

一个简单而完整的 Hello World 智能合约 DApp，展示了从智能合约开发到前端集成的完整 Web3 开发流程。

✨ 功能特点

• 🔗 钱包连接: 支持多种钱包连接（MetaMask、WalletConnect 等）
• 📝 智能合约交互: 读取和修改区块链上的问候语
• 🚨 Alert 提示: 连接成功后显示钱包地址 + "hello"
• 🎨 现代化 UI: 基于 Tailwind CSS 的美观界面
• 📱 响应式设计: 支持桌面和移动端
• 🔧 开发友好: 完整的开发环境和调试工具

🚀 快速开始

前置要求

• Node.js 18+
• pnpm 8+
• Foundry
• Git

安装

1. 克隆项目

git clone <your-repo-url>
cd hello-contract

2. 安装依赖

pnpm install

3. 安装 Foundry（如果未安装）

# macOS/Linux
curl -L https://foundry.paradigm.xyz | bash
foundryup

# 或使用 Homebrew
brew install foundry

运行项目

1. 启动本地区块链

# 在新终端窗口中运行
anvil

2. 编译和部署智能合约

# 编译合约
cd packages/contracts
forge build

# 部署到本地网络
ETHERSCAN_API_KEY=dummy forge script script/Deploy.s.sol \
  --rpc-url http://localhost:8545 \
  --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 \
  --broadcast

3. 配置前端环境

# 创建环境变量文件
cd packages/frontend
cp .env.example .env.local

# 编辑 .env.local，设置合约地址
# NEXT_PUBLIC_CONTRACT_ADDRESS=0x5FbDB2315678afecb367f032d93F642f64180aa3

4. 启动前端应用

# 回到项目根目录
cd ../..

# 启动前端开发服务器
pnpm frontend:dev

5. 访问应用
   • 打开浏览器访问: http://localhost:3000
   • 连接钱包并开始使用！

🏗️ 项目结构

hello-contract/
├── packages/
│   ├── contracts/              # 智能合约 (Foundry)
│   │   ├── src/
│   │   │   └── HelloWorld.sol # 主合约文件
│   │   ├── script/
│   │   │   └── Deploy.s.sol   # 部署脚本
│   │   ├── test/
│   │   │   └── HelloWorld.t.sol # 测试文件
│   │   └── foundry.toml       # Foundry 配置
│   └── frontend/              # 前端应用 (Next.js)
│       ├── src/
│       │   ├── app/           # Next.js App Router
│       │   ├── components/    # React 组件
│       │   ├── hooks/         # 自定义 Hooks
│       │   └── lib/           # 工具库
│       ├── next.config.js     # Next.js 配置
│       └── tailwind.config.js # Tailwind 配置
├── docs/                      # 详细技术文档
├── package.json              # 根 package.json
└── pnpm-workspace.yaml       # pnpm 工作空间配置

🔧 技术栈

智能合约

• Foundry: 现代化的智能合约开发框架
• Solidity: 智能合约编程语言
• Anvil: 本地以太坊测试网络

前端

• Next.js 15: React 全栈框架（App Router）
• TypeScript: 类型安全的 JavaScript
• Wagmi: React Hook 库，用于以太坊交互
• ConnectKit: 优雅的钱包连接 UI
• Tailwind CSS: 原子化 CSS 框架
• Viem: 轻量级以太坊 TypeScript 库

开发工具

• pnpm: 快速、节省磁盘空间的包管理器
• ESLint: 代码质量检查
• Prettier: 代码格式化

📚 使用指南

基础使用

1. 连接钱包

   • 点击"连接钱包"按钮
   • 选择你的钱包类型（推荐 MetaMask）
   • 授权连接

2. 获取问候语

   • 钱包连接成功后，点击"获取问候语 (显示 Alert)"
   • 系统会弹出包含你的钱包地址和 "hello" 的提示框

3. 修改问候语

   • 在输入框中输入新的问候语
   • 点击"设置问候语"
   • 在钱包中确认交易
   • 等待交易被区块链确认

钱包配置

MetaMask 本地网络配置

如果你的 MetaMask 中没有本地网络，请添加以下配置：

• 网络名称: Localhost 8545
• RPC URL: http://localhost:8545
• 链 ID: 31337
• 货币符号: ETH

测试账户

Anvil 提供了预设的测试账户，你可以导入以下私钥到 MetaMask：

私钥: 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
地址: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
余额: 10000 ETH

⚠️ 警告: 仅用于本地开发，切勿在主网使用！

🧪 开发指南

智能合约开发

cd packages/contracts

# 编译合约
forge build

# 运行测试
forge test

# 运行特定测试
forge test --match-test testSetGreeting

# 测试覆盖率
forge coverage

前端开发

cd packages/frontend

# 启动开发服务器
pnpm dev

# 类型检查
pnpm type-check

# 代码检查
pnpm lint

# 构建生产版本
pnpm build

常用命令

# 根目录下可用的命令
pnpm dev                    # 启动前端开发服务器
pnpm build                  # 构建所有包
pnpm test                   # 运行所有测试
pnpm contracts:compile     # 编译合约
pnpm contracts:test        # 测试合约
pnpm contracts:deploy      # 部署合约
pnpm frontend:dev          # 启动前端开发服务器
pnpm frontend:build        # 构建前端

🌐 部署指南

测试网部署

1. 准备工作

• 获取测试网 ETH（从 Faucet）
• 获取 Alchemy 或 Infura API Key
• 获取 Etherscan API Key（用于合约验证）

2. 环境配置

# 创建环境变量文件
cp .env.example .env

# 编辑 .env 文件，填入以下信息：
export SEPOLIA_RPC_URL="https://eth-sepolia.g.alchemy.com/v2/YOUR_API_KEY"
export PRIVATE_KEY="your-wallet-private-key"
export ETHERSCAN_API_KEY="your-etherscan-api-key"

3. 部署到 Sepolia 测试网

cd packages/contracts

# 部署并验证合约
forge script script/Deploy.s.sol \
  --rpc-url $SEPOLIA_RPC_URL \
  --private-key $PRIVATE_KEY \
  --broadcast \
  --verify \
  --etherscan-api-key $ETHERSCAN_API_KEY

4. 更新前端配置

# 更新前端环境变量
cd packages/frontend
echo "NEXT_PUBLIC_CONTRACT_ADDRESS=your-deployed-contract-address" >> .env.local

生产部署

前端部署（Vercel）

1. 连接 GitHub 仓库到 Vercel
2. 设置环境变量：
   • NEXT_PUBLIC_CONTRACT_ADDRESS
   • NEXT_PUBLIC_INFURA_API_KEY
3. 部署

前端部署（其他平台）

cd packages/frontend

# 构建生产版本
pnpm build

# 启动生产服务器
pnpm start

🐛 故障排除

常见问题

1. 钱包连接失败

问题: 点击连接钱包后没有反应 解决方案:

• 确保安装了 MetaMask 或其他兼容钱包
• 检查浏览器是否阻止了弹窗
• 尝试刷新页面

2. 合约调用失败

问题: 交易被拒绝或失败 解决方案:

• 检查钱包中是否有足够的 ETH 支付 Gas
• 确认连接的网络是否正确（Localhost 或 Sepolia）
• 查看浏览器控制台的错误信息

3. 本地网络连接问题

问题: 无法连接到 Anvil 本地网络 解决方案:

• 确保 Anvil 正在运行 (anvil 命令)
• 检查端口 8545 是否被其他程序占用
• 在 MetaMask 中添加本地网络配置

4. 合约地址错误

问题: 前端无法找到合约 解决方案:

• 确认 .env.local 中的合约地址正确
• 重新部署合约并更新地址
• 检查网络是否匹配

调试技巧

查看合约状态

cd packages/contracts

# 使用 cast 查询合约
cast call 0x5FbDB2315678afecb367f032d93F642f64180aa3 "getHello()" --rpc-url http://localhost:8545

查看交易详情

# 查看交易收据
cast receipt <transaction-hash> --rpc-url http://localhost:8545

前端调试

• 打开浏览器开发者工具
• 查看 Console 标签页的错误信息
• 使用 Network 标签页查看 RPC 调用

📖 详细文档

更多详细信息请查看：

• 技术文档 - 完整的技术架构和实现细节
• 智能合约文档 - 合约开发指南
• 前端文档 - 前端开发指南

---