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