diff --git a/docs/guides/06-区块链开发指南.md b/docs/guides/06-区块链开发指南.md index e904f86..c7b063c 100644 --- a/docs/guides/06-区块链开发指南.md +++ b/docs/guides/06-区块链开发指南.md @@ -29,13 +29,13 @@ | 参数 | 目标值 | |------|--------| -| 共识机制 | CometBFT PoS（初期平台运营验证节点） | +| 共识机制 | CometBFT PoS（平台运营 + 合格机构验证节点） | | EVM兼容 | 完全兼容（Solidity、Hardhat、MetaMask全套工具链） | | 出块时间 | **≤ 1秒**（CometBFT即时终结性） | | TPS | ≥ 5,000（Block-STM并行执行） | | Gas策略 | 平台前期全额补贴，用户零Gas | | 原生代币 | GNX（Gas + 治理；前期Gas补贴，用户不接触） | -| 节点运营 | 平台自营验证节点 + 未来开放合格机构节点 | +| 节点运营 | 平台运营验证节点 + 合格机构验证节点 | | 跨链 | IBC连接Cosmos生态 + Axelar桥连接Ethereum | ### 为什么自建链 @@ -189,15 +189,18 @@ contract CouponFactory is Initializable, AccessControlUpgradeable { uint256 quantity, CouponConfig calldata config ) external onlyRole(MINTER_ROLE) returns (uint256[] memory tokenIds) { - // 当前仅开放Utility类型，Securities Track需牌照后启用 - require(config.couponType == CouponType.Utility, "Only Utility Track enabled"); - - // Utility Track强制：价格上限 = 面值 + // Utility Track强制：价格上限 = 面值，最长12个月 if (config.couponType == CouponType.Utility) { require(config.maxPrice <= faceValue, "Utility: maxPrice <= faceValue"); require(config.expiryDate <= block.timestamp + 365 days, "Utility: max 12 months"); } + // Securities Track强制：必须通过合格投资者验证 + Broker-Dealer合规 + if (config.couponType == CouponType.Security) { + require(config.expiryDate > 0, "Security: expiry required"); + // Securities Track由Compliance合约强制合格投资者KYC L2+ + } + // 铸造逻辑 tokenIds = _mintTokens(issuer, faceValue, quantity, config); @@ -545,7 +548,50 @@ forge verify-contract \ --- -## 11. 安全规范 +## 11. 多机构验证节点架构 + +### 11.1 节点类型与准入 + +| 节点类型 | 运营方 | 权限 | 准入条件 | +|---------|--------|------|---------| +| **创世验证节点** | Genex平台 | 出块 + 治理 | 平台自有 | +| **机构验证节点** | 持牌金融机构 | 出块 + 治理 | KYC L3 + 机构资质审查 + 最低质押 | +| **监管观察节点** | 监管机构 | 只读 + 审计API | 监管机构官方申请 | +| **全节点** | 任何人 | 只读同步 | 无门槛 | + +### 11.2 验证节点配置 + +```toml +# genex-chain/config/config.toml — 生产验证节点配置 + +[consensus] + timeout_propose = "1s" + timeout_prevote = "500ms" + timeout_precommit = "500ms" + timeout_commit = "800ms" + +[mempool] + size = 10000 + max_txs_bytes = 1073741824 # 1GB + +[p2p] + max_num_inbound_peers = 100 + max_num_outbound_peers = 50 + persistent_peers = "node1@us-east:26656,node2@sg:26656,node3@eu:26656" +``` + +### 11.3 节点部署拓扑 + +``` +生产网络（最少5个验证节点，推荐7-11个）： + Genex节点 x3 — 美国(2) + 新加坡(1) + 机构节点 x4+ — 合格金融机构各自运维 + 监管节点 x3 — FinCEN / MAS / FCA 只读 +``` + +--- + +## 12. 安全规范 - 所有合约上线前必须通过第三方安全审计 - 核心合约采用Transparent Proxy部署 @@ -556,20 +602,20 @@ forge verify-contract \ --- -## 12. GNX原生代币经济模型 +## 13. GNX原生代币经济模型 -### 12.1 代币用途 +### 13.1 代币用途 | 用途 | 说明 | 状态 | |------|------|------| | **Gas消耗** | 支付交易费用（平台全额补贴） | 已上线 | | **治理投票** | 参与链参数决策 | 平台内部运行 | -| **质押收益** | 验证节点质押获奖励 | 待法律意见书后开放 | -| **二级市场交易** | 交易所买卖GNX | 待合规审批后开放 | +| **质押收益** | 验证节点质押获奖励 | 需合规审批 | +| **二级市场交易** | 交易所买卖GNX | 需合规审批 | -> GNX当前用于Gas（平台补贴），不上交易所，回避SEC证券风险。质押和二级市场交易需取得法律意见书后开放。 +> GNX当前用于Gas（平台补贴），不上交易所，回避SEC证券风险。质押和二级市场交易需取得合规审批后开放。 -### 12.2 代币分配（预留设计） +### 13.2 代币分配 ``` 总供应量: 1,000,000,000 GNX @@ -580,7 +626,7 @@ forge verify-contract \ └── 社区治理: 10%（1亿）— DAO治理基金 ``` -### 12.3 Gas经济模型 +### 13.3 Gas经济模型 ```go // genex-chain/x/evm/keeper/gas.go @@ -598,7 +644,7 @@ func (k Keeper) GetBaseFee(ctx sdk.Context) *big.Int { --- -## 13. Coupon合约补充 — 不可转让券 +## 14. Coupon合约补充 — 不可转让券 ```solidity // src/Coupon.sol — 补充transfer限制逻辑 @@ -642,7 +688,7 @@ contract Coupon is ERC721Upgradeable, AccessControlUpgradeable { --- -## 14. Compliance合约补充 — 差异化KYC检查 +## 15. Compliance合约补充 — 差异化KYC检查 ```solidity // src/Compliance.sol — 补充KYC等级差异化检查 @@ -709,7 +755,7 @@ contract Compliance is Initializable, AccessControlUpgradeable { --- -## 15. 验证节点级交易拦截 +## 16. 验证节点级交易拦截 ```go // genex-chain/x/evm/ante/compliance_ante.go @@ -756,7 +802,7 @@ func (h ComplianceAnteHandler) AnteHandle( --- -## 16. Treasury合约 — 保障资金锁定 +## 17. Treasury合约 — 保障资金锁定 ```solidity // src/Treasury.sol — 补充保障资金逻辑 @@ -822,7 +868,7 @@ contract Treasury is Initializable, AccessControlUpgradeable { --- -## 17. 合约升级回滚能力 +## 18. 合约升级回滚能力 ```solidity // src/Governance.sol — 补充回滚能力 @@ -854,7 +900,7 @@ contract Governance is Initializable { --- -## 18. 多稳定币支持 +## 19. 多稳定币支持 ```solidity // src/Settlement.sol — 补充多稳定币支持 @@ -889,7 +935,7 @@ contract Settlement is Initializable, AccessControlUpgradeable { --- -## 19. Oracle集成（汇率） +## 20. Oracle集成（汇率） ```solidity // src/Oracle.sol — 汇率预言机集成 @@ -918,29 +964,103 @@ contract ExchangeRateOracle is Initializable { --- -## 20. 资产证券化合约预留（Phase 4） +## 21. 资产证券化合约 — CBS（Coupon-Backed Securities） ```solidity -// src/future/CouponBackedSecurity.sol — 预留设计 -// Phase 4: 券收益流打包为CBS（Coupon-Backed Securities） -// 仅在Securities Track + Broker-Dealer牌照后启用 +// src/CouponBackedSecurity.sol — 券收益流打包为资产支持证券 +// Securities Track + Broker-Dealer牌照下运营 -/** - * @notice 预留接口定义，待Securities Track启用后实现 - * - 券收益流打包 - * - 信用评级接口 - * - 收益曲线计算 - */ -interface ICouponBackedSecurity { - function createPool(uint256[] calldata couponIds) external returns (uint256 poolId); - function getCreditRating(uint256 poolId) external view returns (string memory); - function getYieldCurve(uint256 poolId) external view returns (uint256[] memory); +contract CouponBackedSecurity is Initializable, AccessControlUpgradeable { + ICompliance public compliance; + ICoupon public couponContract; + IERC20 public stablecoin; + + struct Pool { + uint256[] couponIds; // 底层券资产 + uint256 totalFaceValue; // 底层面值总额 + uint256 totalShares; // 份额总数 + uint256 maturityDate; // 到期日 + string creditRating; // 信用评级（由链下评级机构写入） + address issuer; // 池创建方 + bool active; // 是否活跃 + } + + mapping(uint256 => Pool) public pools; + // 份额持有：poolId → holder → shares + mapping(uint256 => mapping(address => uint256)) public shares; + uint256 public nextPoolId; + + event PoolCreated(uint256 indexed poolId, address indexed issuer, uint256 couponCount, uint256 totalFaceValue); + event SharesPurchased(uint256 indexed poolId, address indexed buyer, uint256 shares, uint256 amount); + event YieldDistributed(uint256 indexed poolId, uint256 totalYield); + + /// @notice 创建CBS池 — 将一组券的收益流打包 + function createPool( + uint256[] calldata couponIds, + uint256 totalShares, + uint256 maturityDate + ) external onlyRole(ISSUER_ROLE) returns (uint256 poolId) { + // 合规检查：创建者必须KYC L3 + Broker-Dealer资质 + compliance.requireKycLevel(msg.sender, 3); + + uint256 totalFace = 0; + for (uint256 i = 0; i < couponIds.length; i++) { + CouponConfig memory config = couponContract.getConfig(couponIds[i]); + require(config.couponType == CouponType.Security, "CBS: only Security coupons"); + totalFace += couponContract.getFaceValue(couponIds[i]); + // 锁定底层券到池中 + couponContract.safeTransferFrom(msg.sender, address(this), couponIds[i]); + } + + poolId = nextPoolId++; + pools[poolId] = Pool({ + couponIds: couponIds, + totalFaceValue: totalFace, + totalShares: totalShares, + maturityDate: maturityDate, + creditRating: "", + issuer: msg.sender, + active: true + }); + + emit PoolCreated(poolId, msg.sender, couponIds.length, totalFace); + } + + /// @notice 购买CBS份额 — 仅合格投资者（KYC L2+） + function purchaseShares( + uint256 poolId, + uint256 shareCount + ) external { + compliance.requireKycLevel(msg.sender, 2); + require(pools[poolId].active, "Pool not active"); + + uint256 price = (pools[poolId].totalFaceValue * shareCount) / pools[poolId].totalShares; + stablecoin.transferFrom(msg.sender, address(this), price); + shares[poolId][msg.sender] += shareCount; + + emit SharesPurchased(poolId, msg.sender, shareCount, price); + } + + /// @notice 链下评级机构写入信用评级 + function setCreditRating( + uint256 poolId, + string calldata rating + ) external onlyRole(RATING_AGENCY_ROLE) { + pools[poolId].creditRating = rating; + } + + /// @notice 收益分配 — 按份额比例分配到期收益 + function distributeYield(uint256 poolId, uint256 totalYield) external onlyRole(SETTLER_ROLE) { + require(block.timestamp >= pools[poolId].maturityDate, "Not matured"); + // 按份额比例分配由链下clearing-service计算后调用 + emit YieldDistributed(poolId, totalYield); + } } ``` --- -*文档版本: v2.0* +*文档版本: v3.0（量产版）* *基于: Genex 券交易平台 - 软件需求规格说明书 v4.1 + 技术架构开发需求 v3.0* *技术栈: Cosmos SDK + cosmos/evm + CometBFT + Solidity + Foundry* -*更新: 补充GNX代币经济/不可转让revert/差异化KYC/验证节点拦截/批量转移/Treasury保障资金/回滚能力/多稳定币/Oracle/资产证券化预留* +*v3.0更新: 去除MVP/阶段性限制，全面进入量产模式 — 开放Securities Track双轨制、CBS资产证券化完整合约、多机构验证节点架构、GNX代币完整模型*