Monorepo Solidity 使用指南

基于 pnpm 管理的智能合约开发框架，集成 Hardhat + React 前端的完整开发体验。

🌐 在线体验

• 在线演示: https://codefork.cn/blockchain-react/index.html
• 源码仓库: https://github.com/Kenneth-95/monorepo-solidity

🚀 快速开始

环境准备

确保已安装以下工具：

• Node.js (>= 16)
• pnpm (>= 8)
• Git

项目安装

# 克隆项目
git clone https://github.com/Kenneth-95/monorepo-solidity.git
cd monorepo-solidity

# 安装依赖
pnpm install

📋 开发流程

1. 启动 Hardhat 本地测试网

首先启动本地区块链节点：

# 进入 solidity 目录并启动本地网络
pnpm --filter solidity dev

# 或者直接运行
cd apps/solidity
npm run dev

这将启动一个本地的以太坊测试网络（默认端口 8545），并提供测试账户。

2. 编译和部署智能合约

在新的终端窗口中：

# 编译合约
pnpm --filter solidity compile

# 部署到本地网络并自动更新配置
pnpm --filter solidity update:config

update:config 脚本会：

• 部署所有合约到本地网络
• 自动生成合约配置文件
• 更新前端项目的合约配置

3. 配置 Sepolia 测试网（可选）

如需部署到 Sepolia 测试网：

1. 创建 .env 文件在 apps/solidity 目录下：

INFURA_API_KEY=your_infura_api_key
PRIVATE_KEY=your_private_key_without_0x_prefix

2. 部署到 Sepolia：

pnpm --filter solidity deploy:sepolia

4. 启动前端应用

# 启动 React 前端
pnpm --filter react-front dev

前端将在 http://localhost:5173 启动。

🔧 配置文件说明

Hardhat 配置 (hardhat.config.js)

module.exports = {
  solidity: "0.8.28",
  networks: {
    localhost: {
      url: "http://127.0.0.1:8545",
      chainId: 31337,
    },
    sepolia: {
      url: `https://sepolia.infura.io/v3/${process.env.INFURA_API_KEY}`,
      accounts: [`0x${process.env.PRIVATE_KEY}`],
      chainId: 11155111,
    }
  },
  defaultNetwork: "localhost"
};

TypeScript 配置 (tsconfig.node.json)

{
  "compilerOptions": {
    "composite": true,
    "skipLibCheck": true,
    "module": "ESNext",
    "moduleResolution": "bundler",
    "allowSyntheticDefaultImports": true,
    "strict": true
  },
  "include": ["vite.config.ts"]
}

📁 自动生成的配置文件

运行 update:config 脚本后，会在以下位置自动生成合约配置：

apps/react-front/src/contracts/config/
├── Counter.ts
├── Greeting.ts
├── TodoList.ts
└── ContactInfo.ts

配置文件示例 (以 Counter.ts 为例)：

export default {
  address: "0x5FbDB2315678afecb367f032d93F642f64180aa3",
  abi: [
    // ABI 内容
  ],
  chainId: 31337
}

在前端使用合约

配置会自动导出到 apps/react-front/src/contracts/index.ts：

import Counter from './config/Counter'
import Greeting from './config/Greeting'
import TodoList from './config/TodoList'
import ContactInfo from './config/ContactInfo'

export const CONTRACTS = {
    Counter,
    Greeting,
    TodoList,
    ContactInfo
}

🎯 开发工作流

完整开发流程

1. 启动本地网络

   pnpm --filter solidity dev

2. 编写/修改智能合约

   • 在 apps/solidity/contracts/ 目录下编写合约
   • 在 apps/solidity/ignition/modules/ 下添加部署脚本

3. 编译和部署

   pnpm --filter solidity update:config

4. 启动前端

   pnpm --filter react-front dev

5. 测试和开发

   • 前端会自动连接到本地网络
   • 使用 MetaMask 等钱包连接本地网络进行测试

部署到测试网

# 部署到 Sepolia 测试网
pnpm --filter solidity deploy:sepolia

📜 可用脚本

Solidity 相关

• pnpm --filter solidity dev - 启动本地测试网
• pnpm --filter solidity compile - 编译合约
• pnpm --filter solidity test - 运行测试
• pnpm --filter solidity update:config - 部署并更新配置
• pnpm --filter solidity deploy:sepolia - 部署到 Sepolia

前端相关

• pnpm --filter react-front dev - 启动开发服务器
• pnpm --filter react-front build - 构建生产版本
• pnpm --filter react-front preview - 预览构建结果

🔧 网络配置

本地网络配置

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

Sepolia 测试网配置

• 网络名称: Sepolia
• RPC URL: https://sepolia.infura.io/v3/YOUR_API_KEY
• 链 ID: 11155111
• 货币符号: SepoliaETH

📝 注意事项

1. 环境变量: 部署到测试网需要配置 .env 文件
2. Gas 配置: Sepolia 网络已预配置 gas 价格和超时时间
3. 持久化: 使用 persistent 网络配置可保持合约地址不变
4. 自动更新: 部署脚本会自动更新前端配置，无需手动操作

🆘 常见问题

Q: 前端连接不到合约？

A: 确保本地网络正在运行，并且已执行 update:config 脚本。

Q: MetaMask 连接失败？

A: 检查 MetaMask 是否添加了本地网络配置，并且账户有足够的测试 ETH。

Q: 合约部署失败？

A: 检查 Hardhat 网络是否正常运行，并且合约代码没有语法错误。

---

Happy Coding! 🎉