hailin
/
gcx
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
gcx/.claude/blockchain-dev-plan.md

9.6 KiB
Raw Blame History

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           # 创世配置（参考）
│   ├── 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
│
├── docker-compose.yml              # 完整链部署（6节点+合约）
└── 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 — 生产构建脚本

指南符合性验证 (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 ✅

构建验证

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证券化)

安全红线（不可升级逻辑）

  1. 券类型标记（Utility/Security）— 铸造后不可修改
  2. 所有权记录 — 不可被升级篡改
  3. 链上转售计数器 — 防止绕过 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 exec genex-us-east-1 genexd status
curl http://localhost:26657/status  # CometBFT RPC
curl http://localhost:8545          # EVM JSON-RPC