15 KiB
15 KiB
Genex Chain 区块链开发计划
基于
docs/guides/06-区块链开发指南.mdv3.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: 智能合约核心 ✅
- Foundry 工程 + OpenZeppelin v4.9.6
- 接口定义: ICoupon, ICompliance, IChainlinkPriceFeed
- CouponFactory.sol — Utility/Security 双轨铸造
- Coupon.sol — ERC-721 + 不可转让 + 转售计数
- 验证:
forge build编译通过
阶段 2: 业务逻辑合约 ✅
- Settlement.sol — 原子交换 + 多稳定币 + 价格上限 + 退款
- Redemption.sol — 销毁 + 门店验证 + 到期检查
- Treasury.sol — 保障资金 + Escrow + 费用分割
阶段 3: 合规与治理合约 ✅
- Compliance.sol — OFAC + Travel Rule + KYC L0-L3 + 冻结
- Governance.sol — 3/5多签 + 48h/4h时间锁 + 回滚
- ExchangeRateOracle.sol — Chainlink + 过期保护
- CouponBackedSecurity.sol — CBS池 + 份额 + 收益分配
阶段 4: 部署脚本 ✅
- Deploy.s.sol — Transparent Proxy + 角色授权
阶段 5: Solidity 测试套件 ✅ (102/102 pass)
- CouponFactory.t.sol — 11 tests (含 fuzz)
- Coupon.t.sol — 10 tests
- Settlement.t.sol — 8 tests
- Redemption.t.sol — 6 tests
- Compliance.t.sol — 19 tests
- Treasury.t.sol — 12 tests
- Governance.t.sol — 11 tests
- ExchangeRateOracle.t.sol — 9 tests
- CouponBackedSecurity.t.sol — 10 tests
- Integration.t.sol — 6 tests (端到端)
- 验证:
forge test→ 102/102 PASS
阶段 6: Genex Chain 核心 (cosmos/evm v0.5.1) ✅
- app.go — 真实 BaseApp + 20 个模块注册 (auth, bank, staking, evm, feemarket, erc20, ibc...)
- genesis.go — EVM/FeeMarket/Mint 创世状态
- export.go — 状态导出 + 零高度重置
- interfaces.go — BankKeeper 接口
- mempool.go — EVM 内存池配置
- upgrades.go — 升级处理框架
- 依赖: cosmos/evm v0.5.1, Cosmos SDK v0.53.5, CometBFT v0.38.19
阶段 7: CLI 入口 ✅
- cmd/genexd/main.go — 入口 + Bech32 配置 (genex prefix)
- 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/evm/keeper/gas.go — Gas 价格覆盖、EIP-1559 支持
- x/evm/keeper/gas_test.go — 13 tests
- 验证:
go test ./x/evm/keeper/→ 13/13 PASS
阶段 9: 链级合规拦截 ✅
- x/evm/ante/compliance_ante.go — OFAC + Structuring + Travel Rule
- x/evm/ante/compliance_ante_test.go — 18 tests (含并发安全)
- 验证:
go test ./x/evm/ante/→ 18/18 PASS
阶段 10: 构建与部署 ✅
- go.mod — 精确版本钉选 + 4 个 replace 指令
- Makefile — build/test/docker/init-local/start
- Dockerfile — golang:1.23-alpine 多阶段构建
- docker-compose.yml — 6节点完整部署 (5验证 + 1监管)
- scripts/init-local.sh — 单节点测试链
- scripts/init-testnet.sh — 5验证+1监管节点
- scripts/build-production.sh — 生产构建脚本
阶段 11: 生态基础设施 ✅
基于
docs/guides/08-区块链生态基础设施开发指南.mdv1.0
- Blockscout 区块浏览器 — docker-compose.explorer.yml + 4个自定义 Elixir 模块
- coupon-view.ex (券NFT详情)、compliance-labels.ex (合规标签)
- issuer-profile.ex (发行人档案)、cbs-pool-view.ex (CBS池)
- 企业API服务 (NestJS, :3020) — 4层认证 (Public/Institutional/Regulatory/Internal)
- 8个模块: blocks, transactions, address, coupon, stats, rpc, export, regulatory
- WebSocket 事件网关、API Key + mTLS 双重认证
- MPC钱包服务 (NestJS, :3021) — 2-of-3 阈值签名
- 用户钱包 (手机号→地址)、机构钱包 (mint/deposit/trade)
- 治理钱包 (Gnosis Safe 5-of-5, 3/5常规 4/5紧急)
- Gas代付中继 (NestJS, :3022) — EIP-712 Meta-TX
- Redis原子Nonce管理、熔断器 (50tx/min/user)
- Gas记账追踪
- 测试网水龙头 (NestJS, :3023) — 100 GNX + 10,000 USDC per 24h
- 跨链桥监控 (Go/Gin, :3024) — Axelar 桥对账
- 0.01%偏差自动暂停、Prometheus metrics、Webhook告警
- 链监控 — Prometheus + Grafana + AlertManager
- 14条告警规则 (共识/EVM/存储/网络/中继/桥/业务)
- 12面板 Grafana 仪表盘
- 开发者SDK — JS/Go/Dart 三端SDK
- JS SDK: GenexClient + CouponModule + BlockModule + EventModule (WebSocket)
- Go SDK: ethclient封装 + 事件订阅 + 类型定义
- Dart SDK: JsonRpcClient + WebSocketClient + ABI编码 + 7个模型类
- 归档节点 — archive-node.toml (pruning=nothing, debug API)
- 合约安全CI — GitHub Actions (Foundry + Slither + Mythril + Blockscout验证)
- 链CI — Go build/test/lint + NestJS matrix build + Dart analyze
- 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项)
- §6/§16 合规 ante handler 集成 — 已创建
compliance_integration.go将 独立 ComplianceAnteHandler 桥接到 Cosmos SDK ante 链 (OFAC→TravelRule→Structuring→标准handler) - §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 完成:
# 方式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证券化)
安全红线（不可升级逻辑）
- 券类型标记（Utility/Security）— 铸造后不可修改
- 所有权记录 — 不可被升级篡改
- 链上转售计数器 — 防止绕过 Utility Track 限制
部署说明
# 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