# 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: 智能合约核心 ✅
- [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 — 生产构建脚本

---

## 指南符合性验证 (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 完成:

```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 exec genex-us-east-1 genexd status
curl http://localhost:26657/status  # CometBFT RPC
curl http://localhost:8545          # EVM JSON-RPC
```