# 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 ```