378 lines
15 KiB
Markdown
378 lines
15 KiB
Markdown
# Genex Chain 区块链开发计划
|
||
|
||
> 基于 `docs/guides/06-区块链开发指南.md` v3.0 量产版
|
||
> 技术栈: cosmos/evm v0.5.1 + Cosmos SDK v0.53.5 + CometBFT v0.38.19 + Solidity + Foundry
|
||
|
||
---
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
blockchain/
|
||
├── genex-chain/ # Cosmos SDK 应用链（Go）
|
||
│ ├── app.go # GenexApp (BaseApp) 主配置 — 真实 Cosmos SDK
|
||
│ ├── genesis.go # 创世状态 (EVM/FeeMarket/Mint)
|
||
│ ├── export.go # 状态导出
|
||
│ ├── interfaces.go # BankKeeper 接口
|
||
│ ├── mempool.go # EVM 内存池配置
|
||
│ ├── upgrades.go # 升级处理器
|
||
│ ├── cmd/
|
||
│ │ └── genexd/ # 链二进制入口
|
||
│ │ ├── main.go # 入口 + SDK 配置
|
||
│ │ └── cmd/
|
||
│ │ └── root.go # Cosmos SDK server 命令
|
||
│ ├── x/
|
||
│ │ └── evm/
|
||
│ │ ├── keeper/
|
||
│ │ │ ├── gas.go # Gas费覆盖（平台补贴）
|
||
│ │ │ └── gas_test.go # Gas 测试（13 tests）
|
||
│ │ └── ante/
|
||
│ │ ├── compliance_ante.go # 链级合规拦截
|
||
│ │ └── compliance_ante_test.go # 合规测试（18 tests）
|
||
│ ├── config/
|
||
│ │ ├── config.toml # CometBFT 节点配置
|
||
│ │ ├── app.toml # 应用配置
|
||
│ │ ├── genesis.json # 创世配置（参考）
|
||
│ │ └── archive-node.toml # 归档节点配置 (pruning=nothing)
|
||
│ ├── scripts/
|
||
│ │ ├── init-local.sh # 本地测试链初始化
|
||
│ │ ├── init-testnet.sh # 测试网初始化（5验证+1监管）
|
||
│ │ └── build-production.sh # 生产构建脚本
|
||
│ ├── go.mod # 精确依赖 + replace 指令
|
||
│ ├── Makefile # 构建系统
|
||
│ ├── Dockerfile # 多阶段 Docker 构建
|
||
│ └── .dockerignore
|
||
│
|
||
├── genex-contracts/ # Solidity 智能合约（Foundry）
|
||
│ ├── src/ # 9 个合约
|
||
│ ├── test/ # 102 tests
|
||
│ ├── script/Deploy.s.sol
|
||
│ ├── foundry.toml
|
||
│ └── Dockerfile
|
||
│
|
||
├── enterprise-api/ # 企业API服务 (NestJS, :3020)
|
||
│ └── src/modules/ # blocks, transactions, address, coupon, stats, rpc, export, regulatory, events
|
||
│
|
||
├── wallet-service/ # MPC钱包服务 (NestJS, :3021)
|
||
│ └── src/modules/ # mpc, user-wallet, institutional, governance
|
||
│
|
||
├── gas-relayer/ # Gas代付中继 (NestJS, :3022)
|
||
│ └── src/modules/ # relay, nonce, accounting, health
|
||
│
|
||
├── faucet-service/ # 测试网水龙头 (NestJS, :3023)
|
||
│ └── src/modules/ # faucet
|
||
│
|
||
├── bridge-monitor/ # 跨链桥监控 (Go/Gin, :3024)
|
||
│ ├── cmd/monitor/
|
||
│ └── internal/ # config, monitor, eth, genex, handler
|
||
│
|
||
├── chain-monitor/ # 链监控 (Prometheus + Grafana + AlertManager)
|
||
│ ├── prometheus/ # prometheus.yml, alert-rules.yml
|
||
│ ├── alertmanager/ # alertmanager.yml
|
||
│ ├── grafana/ # dashboards + provisioning
|
||
│ └── docker-compose.monitor.yml
|
||
│
|
||
├── explorer/ # Blockscout 自定义模块 (Elixir)
|
||
│ ├── coupon-view.ex # 券 NFT 详情页
|
||
│ ├── compliance-labels.ex # 合规标签
|
||
│ ├── issuer-profile.ex # 发行人档案
|
||
│ └── cbs-pool-view.ex # CBS池详情
|
||
│
|
||
├── genex-sdk-js/ # JavaScript/TypeScript SDK (npm)
|
||
│ └── src/ # client, modules, types
|
||
│
|
||
├── genex-sdk-go/ # Go SDK (go module)
|
||
│ ├── client.go, types.go
|
||
│ ├── coupon.go, blocks.go, events.go
|
||
│ └── go.mod
|
||
│
|
||
├── genex-sdk-dart/ # Dart/Flutter SDK (pub.dev)
|
||
│ └── lib/src/ # client, models, rpc, contracts, utils
|
||
│
|
||
├── .github/workflows/
|
||
│ ├── contract-security.yml # 合约安全CI (Foundry + Slither + Mythril)
|
||
│ └── chain-ci.yml # 链+SDK+生态服务CI
|
||
│
|
||
├── docker-compose.yml # 完整链部署 (6节点+合约+生态服务)
|
||
├── docker-compose.explorer.yml # Blockscout 浏览器
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## 核心技术栈
|
||
|
||
| 组件 | 版本 | 说明 |
|
||
|------|------|------|
|
||
| cosmos/evm | v0.5.1 | EVM 兼容层 (Apache 2.0) |
|
||
| Cosmos SDK | v0.53.5 (commit: 768cb210885c) | 应用链框架 |
|
||
| CometBFT | v0.38.19 | BFT 共识引擎 |
|
||
| ibc-go | v10.3.1 | IBC 跨链 |
|
||
| go-ethereum | v1.16.2-cosmos-1 (Cosmos fork) | EVM 实现 |
|
||
| OpenZeppelin | v4.9.6 | Solidity 合约库 |
|
||
| Foundry | latest | 合约开发框架 |
|
||
|
||
## Genex Chain 参数
|
||
|
||
| 参数 | 值 |
|
||
|------|------|
|
||
| Bech32 Prefix | `genex` |
|
||
| Bond Denom | `agnx` (atto GNX, 18 decimals) |
|
||
| Display Denom | `GNX` |
|
||
| EVM Chain ID | 8888 |
|
||
| Min Gas Price | 0 (平台补贴) |
|
||
| Block Time | ≤1s |
|
||
| 节点 Home | `~/.genexd` |
|
||
|
||
---
|
||
|
||
## 开发阶段与验证状态
|
||
|
||
### 阶段 1: 智能合约核心 ✅
|
||
- [x] Foundry 工程 + OpenZeppelin v4.9.6
|
||
- [x] 接口定义: ICoupon, ICompliance, IChainlinkPriceFeed
|
||
- [x] CouponFactory.sol — Utility/Security 双轨铸造
|
||
- [x] Coupon.sol — ERC-721 + 不可转让 + 转售计数
|
||
- **验证**: `forge build` 编译通过
|
||
|
||
### 阶段 2: 业务逻辑合约 ✅
|
||
- [x] Settlement.sol — 原子交换 + 多稳定币 + 价格上限 + 退款
|
||
- [x] Redemption.sol — 销毁 + 门店验证 + 到期检查
|
||
- [x] Treasury.sol — 保障资金 + Escrow + 费用分割
|
||
|
||
### 阶段 3: 合规与治理合约 ✅
|
||
- [x] Compliance.sol — OFAC + Travel Rule + KYC L0-L3 + 冻结
|
||
- [x] Governance.sol — 3/5多签 + 48h/4h时间锁 + 回滚
|
||
- [x] ExchangeRateOracle.sol — Chainlink + 过期保护
|
||
- [x] CouponBackedSecurity.sol — CBS池 + 份额 + 收益分配
|
||
|
||
### 阶段 4: 部署脚本 ✅
|
||
- [x] Deploy.s.sol — Transparent Proxy + 角色授权
|
||
|
||
### 阶段 5: Solidity 测试套件 ✅ (102/102 pass)
|
||
- [x] CouponFactory.t.sol — 11 tests (含 fuzz)
|
||
- [x] Coupon.t.sol — 10 tests
|
||
- [x] Settlement.t.sol — 8 tests
|
||
- [x] Redemption.t.sol — 6 tests
|
||
- [x] Compliance.t.sol — 19 tests
|
||
- [x] Treasury.t.sol — 12 tests
|
||
- [x] Governance.t.sol — 11 tests
|
||
- [x] ExchangeRateOracle.t.sol — 9 tests
|
||
- [x] CouponBackedSecurity.t.sol — 10 tests
|
||
- [x] Integration.t.sol — 6 tests (端到端)
|
||
- **验证**: `forge test` → 102/102 PASS
|
||
|
||
### 阶段 6: Genex Chain 核心 (cosmos/evm v0.5.1) ✅
|
||
- [x] app.go — 真实 BaseApp + 20 个模块注册 (auth, bank, staking, evm, feemarket, erc20, ibc...)
|
||
- [x] genesis.go — EVM/FeeMarket/Mint 创世状态
|
||
- [x] export.go — 状态导出 + 零高度重置
|
||
- [x] interfaces.go — BankKeeper 接口
|
||
- [x] mempool.go — EVM 内存池配置
|
||
- [x] upgrades.go — 升级处理框架
|
||
- **依赖**: cosmos/evm v0.5.1, Cosmos SDK v0.53.5, CometBFT v0.38.19
|
||
|
||
### 阶段 7: CLI 入口 ✅
|
||
- [x] cmd/genexd/main.go — 入口 + Bech32 配置 (genex prefix)
|
||
- [x] cmd/genexd/cmd/root.go — 完整 Cosmos SDK server 命令
|
||
- init, start, keys, genesis, query, tx, status, debug, confix, pruning, snapshot
|
||
- cosmos/evm server 命令 (EVM JSON-RPC, WebSocket)
|
||
- EthSecp256k1 密钥支持 (MetaMask 兼容)
|
||
|
||
### 阶段 8: Gas 补贴模块 ✅
|
||
- [x] x/evm/keeper/gas.go — Gas 价格覆盖、EIP-1559 支持
|
||
- [x] x/evm/keeper/gas_test.go — 13 tests
|
||
- **验证**: `go test ./x/evm/keeper/` → 13/13 PASS
|
||
|
||
### 阶段 9: 链级合规拦截 ✅
|
||
- [x] x/evm/ante/compliance_ante.go — OFAC + Structuring + Travel Rule
|
||
- [x] x/evm/ante/compliance_ante_test.go — 18 tests (含并发安全)
|
||
- **验证**: `go test ./x/evm/ante/` → 18/18 PASS
|
||
|
||
### 阶段 10: 构建与部署 ✅
|
||
- [x] go.mod — 精确版本钉选 + 4 个 replace 指令
|
||
- [x] Makefile — build/test/docker/init-local/start
|
||
- [x] Dockerfile — golang:1.23-alpine 多阶段构建
|
||
- [x] docker-compose.yml — 6节点完整部署 (5验证 + 1监管)
|
||
- [x] scripts/init-local.sh — 单节点测试链
|
||
- [x] scripts/init-testnet.sh — 5验证+1监管节点
|
||
- [x] scripts/build-production.sh — 生产构建脚本
|
||
|
||
### 阶段 11: 生态基础设施 ✅
|
||
> 基于 `docs/guides/08-区块链生态基础设施开发指南.md` v1.0
|
||
|
||
- [x] **Blockscout 区块浏览器** — docker-compose.explorer.yml + 4个自定义 Elixir 模块
|
||
- coupon-view.ex (券NFT详情)、compliance-labels.ex (合规标签)
|
||
- issuer-profile.ex (发行人档案)、cbs-pool-view.ex (CBS池)
|
||
- [x] **企业API服务** (NestJS, :3020) — 4层认证 (Public/Institutional/Regulatory/Internal)
|
||
- 8个模块: blocks, transactions, address, coupon, stats, rpc, export, regulatory
|
||
- WebSocket 事件网关、API Key + mTLS 双重认证
|
||
- [x] **MPC钱包服务** (NestJS, :3021) — 2-of-3 阈值签名
|
||
- 用户钱包 (手机号→地址)、机构钱包 (mint/deposit/trade)
|
||
- 治理钱包 (Gnosis Safe 5-of-5, 3/5常规 4/5紧急)
|
||
- [x] **Gas代付中继** (NestJS, :3022) — EIP-712 Meta-TX
|
||
- Redis原子Nonce管理、熔断器 (50tx/min/user)
|
||
- Gas记账追踪
|
||
- [x] **测试网水龙头** (NestJS, :3023) — 100 GNX + 10,000 USDC per 24h
|
||
- [x] **跨链桥监控** (Go/Gin, :3024) — Axelar 桥对账
|
||
- 0.01%偏差自动暂停、Prometheus metrics、Webhook告警
|
||
- [x] **链监控** — Prometheus + Grafana + AlertManager
|
||
- 14条告警规则 (共识/EVM/存储/网络/中继/桥/业务)
|
||
- 12面板 Grafana 仪表盘
|
||
- [x] **开发者SDK** — JS/Go/Dart 三端SDK
|
||
- JS SDK: GenexClient + CouponModule + BlockModule + EventModule (WebSocket)
|
||
- Go SDK: ethclient封装 + 事件订阅 + 类型定义
|
||
- Dart SDK: JsonRpcClient + WebSocketClient + ABI编码 + 7个模型类
|
||
- [x] **归档节点** — archive-node.toml (pruning=nothing, debug API)
|
||
- [x] **合约安全CI** — GitHub Actions (Foundry + Slither + Mythril + Blockscout验证)
|
||
- [x] **链CI** — Go build/test/lint + NestJS matrix build + Dart analyze
|
||
- [x] **Docker Compose更新** — ecosystem profile集成全部生态服务
|
||
|
||
---
|
||
|
||
## 指南符合性验证 (06-区块链开发指南.md)
|
||
|
||
> 逐节检查日期: 2026-02-14
|
||
|
||
### 完全符合 (17/21 节)
|
||
§1 链架构, §3 开发环境, §4 智能合约(9>指南7), §5 升级策略,
|
||
§7 Gas补贴, §8 测试(133 tests), §9 部署, §11 多机构验证节点,
|
||
§12 安全规范, §14 不可转让券, §15 差异化KYC, §17 Treasury,
|
||
§18 回滚, §19 多稳定币, §20 Oracle, §21 CBS, §2 设计参数
|
||
|
||
### 已修复偏差 (2项)
|
||
1. **§6/§16 合规 ante handler 集成** — 已创建 `compliance_integration.go` 将
|
||
独立 ComplianceAnteHandler 桥接到 Cosmos SDK ante 链 (OFAC→TravelRule→Structuring→标准handler)
|
||
2. **§13 init-testnet.sh denom** — 已修正 `ugnx` → `agnx` (18 decimals) + 更新所有金额
|
||
|
||
### 合理偏差 (不需修复)
|
||
- Block-STM 并行执行 (§2): 性能优化特性，后期集成
|
||
- GCFN 三级路由 (§10): 运维架构，非代码层面
|
||
- Axelar 桥 (§1): 外部基础设施集成
|
||
- `agnx` 替代 `ugnx`: EVM 18位精度要求
|
||
|
||
---
|
||
|
||
## 测试验证总结
|
||
|
||
| 组件 | 框架 | 测试数 | 状态 |
|
||
|------|------|--------|------|
|
||
| 智能合约 (9 contracts) | Foundry | 102 | ✅ ALL PASS |
|
||
| 合规模块 (OFAC/Travel Rule) | Go test | 18 | ✅ ALL PASS |
|
||
| Gas 模块 (补贴/EIP-1559) | Go test | 13 | ✅ ALL PASS |
|
||
| **总计** | | **133** | **✅** |
|
||
|
||
## 生态基础设施组件清单
|
||
|
||
| 组件 | 技术栈 | 端口 | 依赖 | 状态 |
|
||
|------|--------|------|------|------|
|
||
| Blockscout 浏览器 | Elixir + PostgreSQL | 4000 | genexd RPC | ✅ |
|
||
| 企业API | NestJS | 3020 | Kong, genexd, PostgreSQL | ✅ |
|
||
| MPC钱包服务 | NestJS | 3021 | CloudHSM, genexd | ✅ |
|
||
| Gas Relayer | NestJS | 3022 | genexd, Redis | ✅ |
|
||
| 测试网 Faucet | NestJS | 3023 | genexd(testnet) | ✅ |
|
||
| 跨链桥监控 | Go/Gin | 3024 | Axelar, genexd, Ethereum | ✅ |
|
||
| 链监控 | Prometheus+Grafana | 9090/3030 | genexd metrics | ✅ |
|
||
| 归档节点 | genexd (pruning=nothing) | 8600/26717 | 大容量存储 | ✅ |
|
||
| JS SDK | TypeScript (npm) | — | — | ✅ |
|
||
| Go SDK | Go module | — | — | ✅ |
|
||
| Dart SDK | Dart (pub.dev) | — | — | ✅ |
|
||
| 合约安全CI | GitHub Actions | — | Slither, Mythril | ✅ |
|
||
|
||
---
|
||
|
||
## 构建验证
|
||
|
||
**Windows 环境限制**: 当前开发环境 (Windows, CGO_ENABLED=0) 无法编译 Cosmos SDK。
|
||
链代码的编译和部署通过 Docker 完成:
|
||
|
||
```bash
|
||
# 方式1: Docker 构建（推荐）
|
||
cd blockchain/genex-chain
|
||
docker build -t genex-chain:latest .
|
||
|
||
# 方式2: Linux 直接构建
|
||
bash scripts/build-production.sh
|
||
|
||
# 方式3: 完整测试网部署
|
||
cd blockchain
|
||
docker compose up -d
|
||
```
|
||
|
||
**已验证组件**:
|
||
- ✅ 智能合约: 102/102 Solidity tests pass (Foundry)
|
||
- ✅ Go 自定义模块: 31/31 Go tests pass (compliance + gas)
|
||
- ⏳ 链二进制编译: 需要 Docker/Linux 环境验证
|
||
- ⏳ 链启动与出块: 需要 Docker 环境验证
|
||
- ⏳ EVM JSON-RPC: 需要 Docker 环境验证
|
||
|
||
---
|
||
|
||
## 合约架构关系
|
||
|
||
```
|
||
Governance (多签治理)
|
||
├── 升级所有合约
|
||
├── 调整Gas参数
|
||
└── 紧急冻结
|
||
│
|
||
CouponFactory (铸造)
|
||
│ 创建 Coupon
|
||
▼
|
||
Coupon (ERC-721)
|
||
│ 被 Settlement/Redemption 引用
|
||
▼
|
||
Settlement (结算) Redemption (兑付)
|
||
│ 调用 Compliance │ 销毁 Coupon
|
||
│ 使用 Treasury escrow │
|
||
▼ ▼
|
||
Compliance (合规) Treasury (资金)
|
||
│ OFAC + KYC + Travel Rule │ escrow/release/guarantee
|
||
▼ ▼
|
||
ExchangeRateOracle CouponBackedSecurity
|
||
(汇率) (CBS证券化)
|
||
```
|
||
|
||
---
|
||
|
||
## 安全红线（不可升级逻辑）
|
||
1. 券类型标记（Utility/Security）— 铸造后不可修改
|
||
2. 所有权记录 — 不可被升级篡改
|
||
3. 链上转售计数器 — 防止绕过 Utility Track 限制
|
||
|
||
---
|
||
|
||
## 部署说明
|
||
|
||
```bash
|
||
# 1. 构建链镜像
|
||
cd blockchain/genex-chain
|
||
docker build -t genex-chain:latest .
|
||
|
||
# 2. 启动完整测试网（5验证+1监管节点）
|
||
cd blockchain
|
||
docker compose up -d
|
||
|
||
# 3. 仅单节点开发
|
||
docker compose up genex-node-1 -d
|
||
|
||
# 4. 部署合约
|
||
docker compose run --profile deploy contract-deployer
|
||
|
||
# 5. 启动生态基础设施服务
|
||
docker compose --profile ecosystem up -d
|
||
|
||
# 6. 启动 Blockscout 浏览器
|
||
docker compose -f docker-compose.explorer.yml up -d
|
||
|
||
# 7. 启动链监控 (Prometheus + Grafana + AlertManager)
|
||
docker compose -f chain-monitor/docker-compose.monitor.yml up -d
|
||
|
||
# 8. 检查状态
|
||
docker exec genex-us-east-1 genexd status
|
||
curl http://localhost:26657/status # CometBFT RPC
|
||
curl http://localhost:8545 # EVM JSON-RPC
|
||
curl http://localhost:3020/docs # Enterprise API Swagger
|
||
curl http://localhost:4000 # Blockscout
|
||
curl http://localhost:3030 # Grafana Dashboard
|
||
```
|