# Genex Chain 生态基础设施开发指南 > 区块浏览器 + 企业API + Gas Relayer + 链监控 + 开发者SDK + 跨链桥 --- ## 1. 生态全景 链和合约是区块链的内核，但量产级运营需要完整的生态工具链。 ``` ┌──────────────────────────────────────────────────────────────────────┐ │ Genex Chain 生态基础设施 │ ├──────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌────────────┐ │ │ │ 区块浏览器 │ │ 企业API网关 │ │ Gas Relayer │ │ 水龙头 │ │ │ │ Blockscout │ │ RPC + REST │ │ Meta-TX │ │ 测试网 │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ └────────────┘ │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌────────────┐ │ │ │ 链监控平台 │ │ 开发者SDK │ │ 归档节点 │ │ 合约验证 │ │ │ │ Prometheus │ │ JS/Go/Dart │ │ Archive Node│ │ 源码公示 │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ └────────────┘ │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ 跨链桥监控 │ │ 交易监控AML │ │ CI安全检查 │ │ │ │ Axelar/IBC │ │ Chainalysis │ │ Slither等 │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ └──────────────────────────────────────────────────────────────────────┘ ``` ### 与06-区块链开发指南的关系 | 文档 | 范围 | |------|------| | **06-区块链开发指南** | 链内核：Cosmos SDK链 + 9个智能合约 + 共识/合规/Gas | | **本文档（08）** | 链生态：围绕链内核的所有配套基础设施和工具 | --- ## 2. 区块链浏览器（Block Explorer） 用户、监管、开发者查看链上所有数据的统一入口。 ### 2.1 技术选型 | 项目 | 说明 | |------|------| | **技术选型** | Blockscout（开源EVM浏览器，Apache 2.0） | | **部署地址** | `https://explorer.gogenex.com`（主网）/ `https://testnet-explorer.gogenex.com`（测试网） | | **后端** | Elixir + PostgreSQL，索引 Genex Chain 全量区块数据 | | **定制开发** | 券资产专属页面、合规标签、发行方档案 | ### 2.2 核心功能 | 功能 | 说明 | |------|------| | 区块/交易查询 | 按区块号、TX哈希、地址搜索 | | 合约源码验证 | 上传Solidity源码，链上bytecode比对（Foundry verify集成） | | 券资产浏览器 | ERC-721/1155 券NFT详情：面值、类型、转售次数、到期日、发行方 | | Token Tracker | GNX余额、稳定币（USDC/USDT）流转 | | 合约交互 | Read/Write Contract UI（类Etherscan） | | 验证节点面板 | 节点状态、出块率、质押量、在线时间 | | API | REST + GraphQL，供第三方接入 | | 合规标签 | 被冻结地址标红、Travel Rule交易标记、OFAC命中高亮 | ### 2.3 Blockscout 部署配置 ```yaml # docker-compose.explorer.yml services: blockscout: image: blockscout/blockscout:latest environment: ETHEREUM_JSONRPC_VARIANT: geth # cosmos/evm兼容geth JSON-RPC ETHEREUM_JSONRPC_HTTP_URL: http://genexd:8545 ETHEREUM_JSONRPC_WS_URL: ws://genexd:8546 DATABASE_URL: postgresql://blockscout:password@db:5432/blockscout CHAIN_ID: 8888 COIN: GNX COIN_NAME: Genex LOGO: /images/genex-logo.svg NETWORK: Genex Chain SUBNETWORK: Mainnet ports: - "4000:4000" db: image: postgres:16 volumes: - blockscout-db:/var/lib/postgresql/data ``` ### 2.4 券资产定制页面（二次开发） ```elixir # Blockscout定制：券NFT详情页扩展 # 解析CouponFactory事件，展示券业务字段 defmodule BlockScoutWeb.CouponView do # 从CouponBatchMinted事件解析 def render_coupon_detail(token_id) do %{ face_value: decode_face_value(token_id), coupon_type: decode_type(token_id), # Utility / Security resale_count: call_contract(:getResaleCount, token_id), max_resale: call_contract(:getConfig, token_id).maxResaleCount, expiry_date: call_contract(:getConfig, token_id).expiryDate, issuer: call_contract(:getConfig, token_id).issuer, transferable: call_contract(:getConfig, token_id).transferable } end end ``` ### 2.5 浏览器定制功能清单 | 定制项 | 说明 | 优先级 | |--------|------|--------| | 券NFT详情页 | 展示面值、类型、到期日、转售计数等券业务字段 | P0 | | 发行方档案页 | 聚合某发行方的所有券批次、保障资金、信用评级 | P0 | | 合规标签系统 | 冻结地址标红、可疑交易标橙、Travel Rule标记 | P0 | | CBS池详情页 | 资产证券化池的底层券、份额持有人、收益分配记录 | P1 | | 验证节点排行 | 出块率、在线时间、质押量排名 | P1 | | Gas补贴统计 | 平台Gas补贴总量、趋势图、按用户/合约分布 | P2 | --- ## 3. 企业API服务（RPC + REST Gateway） 为机构客户、合作伙伴、监管方提供受控的链数据访问。 ### 3.1 架构 ``` 外部请求 → Kong API Gateway(:8080) → 企业API服务(:3020) │ ┌─────────────────────┼─────────────────────┐ ▼ ▼ ▼ JSON-RPC Proxy REST API WebSocket (链上读写) (业务聚合) (实时订阅) │ │ │ ▼ ▼ ▼ genexd:8545 PostgreSQL genexd:26657 (EVM JSON-RPC) (索引数据) (CometBFT WS) ``` ### 3.2 API分层与认证 | 层级 | 认证方式 | 调用方 | 接口 | |------|---------|--------|------| | **公开API** | API Key | 任何开发者 | 区块/交易查询、合约只读调用 | | **机构API** | mTLS + API Key | 持牌机构 | 批量数据导出、高频RPC、WebSocket订阅 | | **监管API** | mTLS + 机构证书 | 监管机构 | 地址关联分析、全量交易流水、Travel Rule数据、冻结操作 | | **内部API** | 服务间mTLS | Genex后端微服务 | chain-indexer、clearing-service调用 | ### 3.3 核心端点 ```typescript // enterprise-api/src/routes.ts // === 公开API === GET /v1/blocks/:height // 区块详情 GET /v1/transactions/:hash // 交易详情 GET /v1/address/:addr/balance // 地址余额（GNX + 稳定币） GET /v1/address/:addr/tokens // 地址持有的券NFT列表 GET /v1/coupon/:tokenId // 券详情（面值/类型/到期/转售次数） GET /v1/stats // 链统计（TPS/区块高度/活跃地址/券总量） // === 机构API === POST /v1/rpc // JSON-RPC代理（eth_call, eth_sendRawTransaction等） GET /v1/export/transactions?from=&to= // 批量交易导出（CSV/JSON） WS /v1/ws/events // 实时事件订阅（新区块/大额交易/合规事件） GET /v1/coupon/batch/:batchId/holders // 某批次券的当前持有人列表 // === 监管API === GET /v1/regulatory/address/:addr/graph // 地址关联图谱（资金流向分析） GET /v1/regulatory/travel-rule/records // Travel Rule记录查询 GET /v1/regulatory/suspicious // 可疑交易列表（AI标记 + 规则触发） POST /v1/regulatory/freeze // 请求冻结地址（触发Governance多签流程） GET /v1/regulatory/audit-trail // 完整审计日志 ``` ### 3.4 限流策略 ```yaml # Kong rate-limiting配置 plugins: - name: rate-limiting config: # 公开API public_minute: 60 public_hour: 1000 # 机构API institution_minute: 600 institution_hour: 50000 # 监管API regulatory_minute: unlimited ``` --- ## 4. Gas Relayer（Meta-Transaction 中继器） > 用户零Gas体验的技术实现。用户签名操作意图，Relayer代付Gas广播上链。 ### 5.1 工作流 ``` 用户App → 签名meta-tx（EIP-712）→ Relayer服务 → 包装为链上TX（Relayer付Gas）→ Genex Chain ``` ### 5.2 实现 ```typescript // gas-relayer/src/relayer.ts class GasRelayer { private relayerWallet: Wallet; // Relayer热钱包（预充GNX） private nonceManager: NonceManager; /// 接收用户的meta-transaction，代付Gas广播 async relay(metaTx: MetaTransaction): Promise { // 1. 验证用户签名（EIP-712） const signer = verifyTypedData(metaTx.domain, metaTx.types, metaTx.value, metaTx.signature); require(signer === metaTx.from, "Invalid signature"); // 2. 防重放：检查nonce require(await this.checkNonce(metaTx.from, metaTx.nonce), "Nonce already used"); // 3. 构造链上交易（Relayer为tx.origin，Gas由Relayer钱包支付） const tx = await this.relayerWallet.sendTransaction({ to: metaTx.target, // 目标合约 data: metaTx.calldata, // 用户操作编码 gasLimit: metaTx.gasLimit, nonce: await this.nonceManager.next(), }); // 4. Gas费用记账（从平台Gas补贴池扣除） await this.accounting.recordGasSpent(metaTx.from, tx.gasUsed); return tx.hash; } } ``` ### 5.3 运维指标 | 指标 | 阈值 | |------|------| | Relayer热钱包GNX余额 | < 10,000 GNX 时自动从补贴池补充 | | 并发中继能力 | ≥ 1,000 TPS | | Nonce管理 | Redis原子递增，防nonce冲突 | | 熔断器 | 单用户每分钟 > 50 笔时触发限流 | --- ## 5. 链监控与运维平台 ### 5.1 监控栈 ``` Genex Chain 节点 → Prometheus Exporter → Prometheus → Grafana Dashboard │ CometBFT Metrics ──────────────────────────────────────────┤ EVM Metrics ────────────────────────────────────────────────┤ Application Metrics ────────────────────────────────────────┘ │ AlertManager → PagerDuty / Slack ``` ### 5.2 关键监控指标 | 类别 | 指标 | 告警阈值 | |------|------|---------| | **共识** | 出块时间 | > 3s 告警 | | **共识** | 验证节点在线率 | < 80% 严重告警 | | **共识** | 共识轮次 | > 3轮未达成共识告警 | | **EVM** | 交易成功率 | < 95% 告警 | | **EVM** | 待处理交易池 | > 5000 笔告警 | | **EVM** | 平均Gas消耗 | 异常波动告警 | | **存储** | 区块数据磁盘使用 | > 80% 告警 | | **存储** | 状态数据库大小 | 周增长 > 20% 告警 | | **网络** | P2P连接数 | < 10 peers 告警 | | **网络** | 区块同步延迟 | > 10 blocks 告警 | | **业务** | 日铸造券数量 | 异常波动告警 | | **业务** | 大额交易频率 | 突增告警（可能洗钱） | | **Relayer** | 热钱包余额 | < 10,000 GNX 告警 | | **跨链桥** | 桥锁定资产偏差 | > 0.01% 严重告警 | ### 5.3 Grafana Dashboard ```json { "dashboard": "Genex Chain Operations", "panels": [ { "title": "Block Height", "type": "stat", "query": "cometbft_consensus_height" }, { "title": "Block Time", "type": "graph", "query": "rate(cometbft_consensus_height[1m])" }, { "title": "Validator Status", "type": "table", "query": "cometbft_consensus_validators" }, { "title": "TX Throughput", "type": "graph", "query": "rate(evm_tx_count[5m])" }, { "title": "Mempool Size", "type": "gauge", "query": "cometbft_mempool_size" }, { "title": "Relayer GNX Balance", "type": "stat", "query": "relayer_wallet_balance_gnx" }, { "title": "Coupon Minted (24h)", "type": "stat", "query": "increase(coupon_minted_total[24h])" }, { "title": "Bridge TVL", "type": "graph", "query": "bridge_total_value_locked" } ] } ``` --- ## 6. 测试网水龙头（Faucet） 为开发者和测试用户分发测试网 GNX 和测试稳定币。 ```typescript // faucet-service/src/faucet.ts class Faucet { // 限制：每个地址每24小时最多领取一次 // 分发量：100 GNX + 10,000 USDC（测试币） async drip(address: string): Promise<{ gnxTxHash: string; usdcTxHash: string }> { // 频率检查 require(!await this.hasClaimedRecently(address), "Already claimed in last 24h"); // 分发GNX（原生代币） const gnxTx = await this.faucetWallet.sendTransaction({ to: address, value: parseEther("100"), }); // 分发测试USDC（调用MockUSDC合约mint） const usdcTx = await this.mockUsdc.mint(address, parseUnits("10000", 6)); return { gnxTxHash: gnxTx.hash, usdcTxHash: usdcTx.hash }; } } ``` **部署地址：** `https://faucet.testnet.gogenex.com` --- ## 7. 开发者SDK 为外部开发者和内部微服务提供类型安全的链交互工具。 ### 7.1 SDK 矩阵 | SDK | 语言 | 用途 | |-----|------|------| | **genex-sdk-js** | TypeScript/JavaScript | 前端（admin-web）、Node.js后端微服务 | | **genex-sdk-go** | Go | trading-service、chain-indexer | | **genex-sdk-dart** | Dart | genex-mobile、admin-app | ### 7.2 JS SDK 核心接口 ```typescript // @genex/sdk import { GenexClient } from '@genex/sdk'; const client = new GenexClient({ rpcUrl: 'https://rpc.gogenex.com', chainId: 8888, }); // 查询券信息 const coupon = await client.coupon.getDetail(tokenId); // → { faceValue, couponType, expiryDate, resaleCount, transferable, issuer } // 查询地址持有的券 const holdings = await client.coupon.getHoldings(address); // 监听事件 client.events.on('CouponBatchMinted', (event) => { console.log(`新券发行: ${event.quantity}张, 面值${event.faceValue}`); }); // 合约交互（需签名） const tx = await client.settlement.executeSwap(tokenId, buyer, seller, price, { signer: mpcSigner, // MPC签名器 }); ``` ### 7.3 Go SDK 核心接口 ```go // github.com/gogenex/genex-sdk-go package genex type Client struct { rpcURL string chainID int64 } // 查询券详情 func (c *Client) GetCouponDetail(tokenId *big.Int) (*CouponDetail, error) // 监听链上事件 func (c *Client) SubscribeEvents(ctx context.Context, filter EventFilter) (<-chan ChainEvent, error) // 构造+签名+广播交易 func (c *Client) ExecuteSwap(params SwapParams, signer Signer) (*TxReceipt, error) ``` ### 7.4 Dart SDK 核心接口 ```dart // package:genex_sdk class GenexClient { final String rpcUrl; final int chainId; /// 查询用户持有的券列表 Future> getHoldings(String address); /// 查询券详情 Future getCouponDetail(BigInt tokenId); /// 监听事件流 Stream subscribeEvents(EventFilter filter); } ``` --- ## 8. 归档节点（Archive Node） | 项目 | 说明 | |------|------| | **用途** | 保存链创世以来的全部历史状态，支持任意历史区块的状态查询 | | **普通全节点** | 只保留最近N个区块的状态（默认pruning） | | **归档节点** | 保留所有状态，支持 `eth_call` 指定任意区块号 | | **存储需求** | 远大于普通节点（预估年增长 500GB-2TB） | | **部署数量** | 至少2个（美国+新加坡各一） | | **使用者** | Blockscout、监管API、历史数据分析、审计 | ```toml # genex-chain/config/app.toml — 归档节点配置 [pruning] pruning = "nothing" # 不裁剪任何状态 pruning-keep-recent = "0" pruning-interval = "0" [state-sync] snapshot-interval = 1000 # 每1000块生成快照（供新节点快速同步） ``` --- ## 9. 跨链桥监控 ### 9.1 监控架构 ``` Ethereum ←── Axelar Bridge ──→ Genex Chain 监控要点： ├── 锁定资产一致性：Ethereum侧锁定 = Genex Chain侧铸造 ├── 桥交易延迟：正常 < 5分钟，> 15分钟告警 ├── 大额桥转账：> $100,000 触发人工审核 ├── Axelar验证者状态：签名节点在线率 └── 紧急暂停：异常时自动暂停桥，需多签恢复 ``` ### 9.2 桥对账服务 ```typescript // bridge-monitor/src/monitor.ts class BridgeMonitor { /// 定期对账：两侧资产必须一致 async reconcile(): Promise { // Ethereum侧：查询Axelar Gateway合约锁定的USDC const ethLocked = await this.ethGateway.getLockedAmount('USDC'); // Genex Chain侧：查询桥铸造的wrapped USDC总量 const genexMinted = await this.genexBridgeToken.totalSupply(); const discrepancy = Math.abs(ethLocked - genexMinted); if (discrepancy > ethLocked * 0.0001) { // > 0.01% 偏差 await this.alert.critical('Bridge asset discrepancy detected', { ethLocked, genexMinted }); await this.emergencyPause(); // 自动暂停桥 } return { ethLocked, genexMinted, discrepancy, healthy: discrepancy === 0 }; } } ``` --- ## 10. 合约源码验证与安全 | 工具 | 用途 | |------|------| | **Blockscout合约验证** | 上传源码+编译参数，链上bytecode比对 | | **Foundry verify** | CI/CD自动验证新部署合约 | | **Slither** | 静态分析（CI集成，每次PR必须通过） | | **Mythril** | 符号执行漏洞检测 | | **第三方审计** | Trail of Bits / OpenZeppelin / Certik（上线前必须） | ```yaml # .github/workflows/contract-security.yml name: Contract Security on: [push, pull_request] jobs: security: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Foundry Tests run: cd genex-contracts && forge test -vvv - name: Slither Analysis uses: crytic/slither-action@v0.3 with: target: genex-contracts/ - name: Mythril Scan run: myth analyze genex-contracts/src/*.sol --solv 0.8.20 ``` --- ## 11. 生态基础设施部署清单 | 组件 | 技术栈 | 部署位置 | 端口 | 依赖 | |------|--------|---------|------|------| | **Blockscout** | Elixir + PostgreSQL | US-East + SG | 4000 | genexd RPC | | **企业API** | NestJS | US-East + SG | 3020 | Kong, genexd, PostgreSQL | | **Gas Relayer** | NestJS | US-East + SG | 3022 | genexd, Redis | | **Faucet** | NestJS | US-East | 3023 | genexd(testnet) | | **Bridge Monitor** | Go | US-East + SG | 3024 | Axelar, genexd, Ethereum | | **链监控** | Prometheus + Grafana | US-East | 9090/3000 | genexd metrics | | **归档节点** | genexd (pruning=nothing) | US-East + SG | 8545/26657 | 大容量存储 | | **JS SDK** | TypeScript (npm) | npm registry | — | — | | **Go SDK** | Go module | go proxy | — | — | | **Dart SDK** | Dart (pub.dev) | pub.dev | — | — | ### 与现有后端微服务的端口分配 ``` 已有服务（06-区块链开发指南 / 05-后端开发指南）： 3001-3010 — 10个后端微服务 3009 — chain-indexer（已有，链事件索引） 8080 — Kong API Gateway 8545 — genexd EVM JSON-RPC 26657 — genexd CometBFT RPC 新增生态服务（本文档）： 3020 — 企业API服务 3022 — Gas Relayer 3023 — 测试网Faucet 3024 — 跨链桥监控 4000 — Blockscout浏览器 9090 — Prometheus 3000 — Grafana（注意与admin-web的Next.js dev port区分） ``` --- *文档版本: v1.0* *基于: 06-区块链开发指南 v3.0（量产版）* *覆盖: 区块浏览器(Blockscout)、企业API网关(4层认证)、Gas Relayer(Meta-TX)、链监控(Prometheus+Grafana)、测试网水龙头、开发者SDK(JS/Go/Dart)、归档节点、跨链桥监控(Axelar)、合约安全CI(Slither+Mythril)*