RWA 代币化 —— 架构总览
#RWA #Solidity

本文总结 RWA（Real World Assets）代币化平台的整体架构、模块关系、业务流程以及安全设计。

1. 项目概述

RWA 代币化平台将真实世界资产（如房产、债券、艺术品等）映射为链上代币，实现资产的数字化、可分割化和流动性提升。

1.1 核心功能

功能 说明
身份合规 KYC 验证、投资者等级、国家限制
代币管理 发行、铸造、销毁、转账限制
发行审批 多级审批工作流
认购管理 项目创建、白名单、认购、结算
分红机制 锁仓、收益分配、按份额领取

1.2 技术特点

  • 可升级架构：UUPS 代理模式，支持合约升级
  • 角色权限：基于 AccessControl 的细粒度权限管理
  • 安全机制：重入防护、暂停功能、紧急控制
  • Gas 优化：批量操作、累积分红算法

2. 系统架构

2.1 模块关系图

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
┌─────────────────────────────────────────────────────────────────────┐
│                           用户层                                     │
│   投资者  │  项目方  │  管理员  │  审批者                             │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                          业务层                                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │ Subscription │  │  Issuance    │  │  Dividend    │              │
│  │   认购管理    │  │   发行管理    │  │   分红管理    │              │
│  └──────────────┘  └──────────────┘  └──────────────┘              │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                          基础层                                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │   RWAToken   │  │IdentityRegistry│ │   Proxies   │              │
│  │   代币合约    │  │   身份注册     │  │   代理合约   │              │
│  └──────────────┘  └──────────────┘  └──────────────┘              │
└─────────────────────────────────────────────────────────────────────┘

2.2 合约清单

模块 合约 功能
tokens RWAToken ERC20 代币 + 投票 + Permit
RWACompliantToken 带合规检查的代币
compliance IdentityRegistry KYC 身份注册
ComplianceUpgradeable 合规规则检查
governance RWATokenIssuanceManager 发行请求管理
RWATokenIssuanceLogic 发行逻辑实现
subscription RWASubscription 项目认购管理
dividend RWADividendPool 分红池管理
proxies RWAProxy UUPS 代理
RWAProxyFactory 代理工厂
libraries PriceCalculationLib 价格计算辅助

3. 完整业务流程

3.1 资产代币化流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
┌─────────────────────────────────────────────────────────────────────┐
│                     资产代币化全流程                                  │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  阶段一：准备                                                        │
│  ┌────────────────────────────────────────────────────────────┐    │
│  │ 1. 资产评估 → 2. 法律架构 → 3. 确定代币参数 → 4. KYC 准备   │    │
│  └────────────────────────────────────────────────────────────┘    │
│                              │                                      │
│                              ▼                                      │
│  阶段二：发行                                                        │
│  ┌────────────────────────────────────────────────────────────┐    │
│  │ 5. 部署代币 → 6. 提交发行请求 → 7. 审批 → 8. 铸造代币       │    │
│  └────────────────────────────────────────────────────────────┘    │
│                              │                                      │
│                              ▼                                      │
│  阶段三：认购                                                        │
│  ┌────────────────────────────────────────────────────────────┐    │
│  │ 9. 创建项目 → 10. 投资者KYC → 11. 白名单签名 → 12. 认购     │    │
│  └────────────────────────────────────────────────────────────┘    │
│                              │                                      │
│                              ▼                                      │
│  阶段四：结算                                                        │
│  ┌────────────────────────────────────────────────────────────┐    │
│  │ 13. 认购期结束 → 14. 项目结算 → 15. 用户领取代币             │    │
│  └────────────────────────────────────────────────────────────┘    │
│                              │                                      │
│                              ▼                                      │
│  阶段五：运营                                                        │
│  ┌────────────────────────────────────────────────────────────┐    │
│  │ 16. 代币流通 → 17. 收益分配 → 18. 分红领取                   │    │
│  └────────────────────────────────────────────────────────────┘    │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

3.2 角色职责

角色 职责 相关合约
平台管理员 系统配置、角色管理、紧急控制 所有合约
KYC 代理 注册/更新/删除投资者身份 IdentityRegistry
发行审批者 审批代币发行请求 RWATokenIssuanceManager
项目管理员 创建认购项目 RWASubscription
白名单签名者 签发白名单签名 RWASubscription
代币池管理员 分配分红收益 RWADividendPool
投资者 KYC、认购、领取、分红 多个合约

4. 权限模型

4.1 角色层级

1
2
3
4
5
6
7
8
9
10
11
12
13
14
DEFAULT_ADMIN_ROLE
    │
    ├── MINTER_ROLE (RWAToken)
    ├── PAUSER_ROLE (RWAToken)
    ├── BURNER_ROLE (RWAToken)
    │
    ├── APPROVER_ROLE (IssuanceManager)
    ├── EMERGENCY_ROLE (IssuanceManager)
    │
    ├── PROJECT_ADMIN_ROLE (Subscription)
    ├── WHITELIST_SIGNER_ROLE (Subscription)
    │
    ├── IDENTITY_REGISTRAR_ROLE (IdentityRegistry)
    └── AGENT_ROLE (IdentityRegistry)

4.2 权限最佳实践

1
2
3
4
5
6
建议配置：
├── DEFAULT_ADMIN_ROLE → 多签钱包（3/5）
├── EMERGENCY_ROLE → 独立的紧急响应钱包
├── APPROVER_ROLE → 合规团队成员（可多人）
├── MINTER_ROLE → IssuanceManager 合约
└── PROJECT_ADMIN_ROLE → 经过验证的项目方

5. 安全设计

5.1 访问控制

所有敏感操作都有角色限制：

1
2
3
4
5
// 只有 MINTER_ROLE 可以铸造
function mint(address to, uint256 amount) external onlyRole(MINTER_ROLE) { ... }

// 只有池管理员可以分配收益
function distributeRevenue(...) external onlyTokenAdmin(token) { ... }

5.2 重入防护

关键函数使用 ReentrancyGuard：

1
2
3
4
5
6
function claim(...) external nonReentrant {
    // 先更新状态
    userSub.status = AllocationStatus.Claimed;
    // 后转账
    IERC20(token).safeTransfer(msg.sender, amount);
}

5.3 暂停机制

三级暂停控制：

级别 触发者 影响范围
全局暂停 Admin 整个合约
紧急暂停 Emergency 整个合约（独立控制）
项目暂停 Emergency 单个项目 
1
2
3
4
5
6
7
8
// 全局暂停
function pause() external onlyRole(DEFAULT_ADMIN_ROLE);

// 紧急暂停（独立角色）
function emergencyPause() external onlyRole(EMERGENCY_ROLE);

// 项目级暂停
function emergencyPause(uint256 projectId) external onlyRole(EMERGENCY_ROLE);

5.4 黑名单机制

代币转账可被黑名单阻止：

1
2
3
4
5
6
7
8
function _update(address from, address to, uint256 value)
    internal
    override
    notBlacklisted(from)
    notBlacklisted(to)
{
    super._update(from, to, value);
}

5.5 签名安全

白名单使用 EIP-712 结构化签名：

  • 防止跨合约重放
  • 防止跨链重放
  • Nonce 防止重复使用
  • Deadline 限制有效期

6. 可升级架构

6.1 UUPS 模式

所有核心合约采用 UUPS 可升级模式：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
contract RWAToken is
    Initializable,
    ...,
    UUPSUpgradeable
{
    /// @custom:oz-upgrades-unsafe-allow constructor
    constructor() {
        _disableInitializers();
    }

    function _authorizeUpgrade(address newImplementation)
        internal
        override
        onlyRole(DEFAULT_ADMIN_ROLE)
    {}
}

6.2 升级流程

1
2
3
4
1. 部署新的实现合约
2. 调用 upgradeToAndCall(newImplementation, data)
3. 代理合约指向新实现
4. 存储保持不变

6.3 升级注意事项

  • 不能改变存储布局
  • 新增变量只能追加在末尾
  • 升级前应暂停合约
  • 升级后验证功能正常

7. Gas 优化

7.1 批量操作

1
2
3
4
5
6
7
8
// 批量铸造
function batchMint(address[] calldata recipients, uint256[] calldata amounts);

// 批量审批
function batchApproveRequests(uint256[] calldata requestIds);

// 批量注册身份
function batchRegisterIdentity(...);

7.2 累积分红算法

避免遍历所有用户：

1
2
3
4
5
// 分红时只更新全局变量
revenuePerShare += (amount * PRECISION) / totalDeposited;

// 领取时计算个人收益
pending = (amount * revenuePerShare / PRECISION) - revenueDebt;

7.3 存储优化

1
2
3
4
5
6
7
8
// 使用 unchecked 优化循环
for (uint256 i = 0; i < length;) {
    // ...
    unchecked { ++i; }
}

// 缓存存储变量到内存
TokenPool memory pool = tokenPools[token];

8. 集成指南

8.1 部署顺序

1
2
3
4
5
1. IdentityRegistry（身份注册）
2. RWAToken（代币合约）
3. RWATokenIssuanceManager（发行管理）
4. RWASubscription（认购管理）
5. RWADividendPool（分红池）

8.2 初始化配置

1
2
3
4
5
6
7
8
9
10
// 1. 部署 IdentityRegistry
IdentityRegistry registry = new IdentityRegistry(admin);

// 2. 部署 Subscription（需要 registry 地址）
RWASubscription subscription = new RWASubscription();
subscription.initialize(admin, address(registry), treasury);

// 3. 部署 DividendPool
RWADividendPool dividend = new RWADividendPool();
dividend.initialize(admin);

8.3 角色授予

1
2
3
4
5
6
7
8
// 授予 IssuanceManager 铸造权限
rwaToken.grantRole(MINTER_ROLE, address(issuanceManager));

// 授予 KYC 代理身份注册权限
registry.grantRole(AGENT_ROLE, kycAgent);

// 授予项目方创建项目权限
subscription.grantRole(PROJECT_ADMIN_ROLE, projectOwner);

9. 监控与事件

9.1 关键事件

合约 事件 用途
IdentityRegistry IdentityStored KYC 完成
RWAToken Transfer 代币转账
IssuanceManager RequestApproved 发行审批
Subscription SubscriptionMade 用户认购
Subscription ProjectStatusChanged 项目状态变更
DividendPool RevenueDistributed 分红分配

9.2 监控建议

1
2
3
4
5
6
关键指标：
├── 每日新增 KYC 用户数
├── 待审批的发行请求数
├── 各项目认购进度
├── 分红池 TVL
└── 紧急暂停状态

10. 文档索引

文档 内容
合规与身份模块 IdentityRegistry、KYC、投资者等级
Token 合约解析 RWAToken、权限、黑名单
发行管理模块 发行请求、审批流程
认购模块 项目创建、白名单、认购
结算与领取 超额处理、结算、claim
分红模块 锁仓、收益分配
Prev
#RWA #Solidity