ERC-3643 协议介绍
目录
1. 一页读懂
ERC-3643 不是收益或估值协议，而是带身份验证和合规检查的 ERC-20 发行框架。它回答：谁有资格持有、这笔转账能否通过、监管方如何冻结/强制转移/恢复资产、合约如何统一升级。
| 维度 | 普通 ERC-20 | ERC-3643 |
|---|---|---|
| 谁能收币 | 任何地址 | 须通过身份验证 |
| 转账 | 不能按规则拒绝 | 可按合规模块拒绝 |
| 冻结 / 强制转移 / 钱包恢复 | 无 | 有 |
| 规则变更 | 通常换合约 | 改配置或换模块 |
2. 五个核心概念
| 概念 | 含义 |
|---|---|
| ONCHAINID | 用户链上身份档案，与钱包分离；一个身份可绑多个钱包 |
| Claim | 身份上的资格声明（含签发方签名） |
| Claim Issuer | 有权签发/撤销 Claim 的机构合约 |
| Identity Registry | 判断「这个地址是不是合格投资者」（看人） |
| Compliance 模块 | 判断「这笔交易是否合规」（看交易） |
两道闸门都必须过：KYC 合格但仍可能因持仓上限等原因被合规模块拒绝。
3. 合约总体架构
3.1 四层架构
| 层级 | 实例数量 | 解决什么 |
|---|---|---|
| 平台层 | 通常每链一套 | 发行准入、身份创建、统一升级 |
| Suite 层 | 每资产六合约 | 余额、身份、合规、治理 |
| ONCHAINID | 每用户一个 | 密钥与 Claim |
| 合规模块 | 按规则部署，可复用 | 可执行交易规则 |
六个业务合约拆开是为了独立变更：Token 管账本；IR/IRS/CTR/TIR 管身份资格；MC 管交易规则。对外稳定的是 Proxy 地址——状态在 Proxy，Implementation 只提供逻辑。
3.2 三套升级机制
| 对象 | 机制 | 升级入口 | 影响范围 |
|---|---|---|---|
| TREX 六业务合约 | IA 指针代理 | TREX IA | 仍引用该 IA 的资产 |
| ONCHAINID | ONCHAINID IA | updateImplementation | 引用该 IA 的身份 |
| 合规模块 | ERC1967 + UUPS | 模块 Owner upgradeTo | 绑定该模块的资产 |
4. 各合约干什么、链上存什么
先用一句话说清楚：链上存的是业务状态和规则配置，不是用户身份证照片。姓名、证件号等敏感资料在链下 KYC 系统；链上只留「谁过了哪类资格、持有多少份额、能不能转」这类结论。
4.1 整条链共用的平台能力（一般只部署一套）
| 中文名（代码名） | 干什么 | 链上主要存什么 | 要注意的上限 |
|---|---|---|---|
资产升级总开关（TREXImplementationAuthority） | 决定整条链上 RWA 资产「跑哪一版逻辑」；升级时改这里，不必改每个资产地址 | 当前版本号；每个版本对应的六套逻辑地址；谁有权改版本 | 六个业务逻辑必须成套登记，缺一不可 |
| 单资产升级开关工厂（IAFactory） | 某个资产不想跟全链一起升级时，给它单独开一套升级开关 | 哪些资产已单独开过开关 | 只有总开关管理员才能创建 |
| 资产发行工厂（TREXFactory） | 一键部署「一种 RWA 资产」所需的整套合约，并完成初始化 | 用过哪个发行代号；关联的升级总开关、身份工厂；谁有权发行 | 首次配置时：资格类型/签发机构/操作员各最多 5 个；规则模块操作最多 30 条 |
| 发行准入网关（TREXGateway） | 管谁能发行、是否对公众开放、收不收部署费、给谁打折 | 是否公开可发；费用币种/金额/收款账户；获准发行方名单；折扣；管理员与运营员 | 一次批量最多发 5 套资产 |
| 身份开户工厂（IdFactory） | 给投资者（或资产本身）创建链上身份档案，并记住钱包和身份的对应关系 | 哪个钱包对应哪个身份；一个身份绑了哪些钱包； | 一个身份最多绑 101 个钱包 |
身份逻辑升级开关（ONCHAINID ImplementationAuthority） | 决定所有用户身份档案「跑哪一版身份逻辑」 | 当前身份逻辑地址；谁有权升级 | 一改，所有引用它的身份一起变 |
| ONCHAINID Gateway | 用平台预授权签名，让用户自助开身份 | 哪些地址可以签授权；哪些签名已作废 | 演示主流程一般不用 |
4.2 每种 RWA 资产一套的六个核心合约
每发行一种资产，都会生成下面这六份（对外给钱包/交易所用的是固定地址，升级不换地址）。
| 中文名（代码名） | 干什么 | 链上主要存什么 | 要注意的上限 |
|---|---|---|---|
| 资产账本（Token） | 记谁持有多少；支持转账、增发、销毁、暂停、冻结、强制划转、钱包找回 | 每个地址余额；授权额度；总发行量；资产名称/代码/小数位；是否全局暂停；哪些地址被整户冻结；冻结了多少份额；挂了哪套身份校验和哪套交易规则；管理员与运营员 | 小数位 0 ～ 18 |
| 投资者资格门（IdentityRegistry） | 转账/增发前问一句：接收方是不是合格投资者 | 指向下面三份配置：资格要求清单、可信签发机构清单、投资者档案库；谁有权登记/管理 | 要求越多、可信机构越多，每笔校验越贵 |
| 投资者档案库（IdentityRegistryStorage） | 存「这个钱包对应哪个链上身份、属于哪个国家/地区」；多套资产可以共用一份 | 钱包 → 身份档案地址 + 国家数字代码；哪些资格门在用这份库 | 最多服务 300 套资产的资格门；一个钱包只记一条 |
| 资格要求清单（ClaimTopicsRegistry） | 规定持有本资产必须具备哪些资格（如已 KYC、已过反洗钱） | 必需资格类型列表；谁能改清单 | 最多 15 项，不能重复 |
| 可信签发机构表（TrustedIssuersRegistry） | 规定相信哪些机构出具的资格证明，以及每家能签哪几类 | 机构名单；每家能签的资格类型 | 最多 50 家机构；每家最多 15 类资格 |
| 交易规则中枢（ModularCompliance） | 在「人合格」之外，再检查这笔买卖是否符合额度、国家、锁定期等规则 | 绑定了哪本资产账本；挂了哪些规则模块；谁能改规则 | 一本账本；最多挂 25 个规则模块 |
4.3 用户身份与交易规则模块
| 中文名（代码名） | 干什么 | 链上主要存什么 |
|---|---|---|
| 用户身份档案（ONCHAINID / Identity） | 一人一份「链上身份档案」；钱包只是操作工具，可换绑 | 谁有管理权/操作权/声明权；已获得的资格证明 |
| 资格签发机构（ClaimIssuer） | KYC/AML 等机构用来盖章和作废证明 | 同上（它也是一种身份）+ 哪些盖章签名已被作废 |
| 规则模块代理（ModuleProxy） | 单条业务规则的稳定入口（如国家白名单） | 当前规则逻辑地址 + 各资产自己的参数 |
研发对照目录（产品可忽略）：平台在 contracts/factory/、proxy/authority/；单资产在 token/、registry/、compliance/modular/；身份能力在 npm 包 @onchain-id/solidity。
5. 合约间交互
5.1 依赖关系
5.3 发行流程
Gateway 的 salt 一般为「Owner 地址十六进制 + Token 名称」。收费开启时须先 approve 费用代币。
5.4 投资者准入：创建身份、签发 KYC、Claim 上链
投资者准入不是单个交易，而是「身份合约创建 + 资格签名 + Claim 写入 + 资产侧登记」四段动作。核心要分清三件事：
- 创建 ONCHAINID 是上链交易，会产生一个投资者身份合约。
- ClaimSigner 签 KYC 是链下签名，本身不产生交易、不花 gas。
- addClaim 是上链交易，把 ClaimSigner 的签名和 KYC 结论写进投资者自己的 ONCHAINID。
5.4.1 生产流程：投资者通过 ONCHAINID Gateway 自助创建身份
IdFactory.createIdentity 本身是 onlyOwner，投资者不能直接调 Factory。生产上不建议让 Platform Owner 为 1 万个用户逐笔代调 createIdentity，更合理的做法是：
- 部署官方
@onchain-id/solidity/contracts/gateway/Gateway.sol。 - 把
IdFactory的 Owner 转给这个 ONCHAINID Gateway。 - 投资者自己调用
Gateway.deployIdentityForWallet(investor)。 - Gateway 作为
IdFactoryOwner 代为调用IdFactory.createIdentity。 - 交易发起人仍是投资者，所以创建身份的 gas 由投资者支付。
5.4.2 各步骤谁调用、谁付 gas
| 步骤 | 动作 | 谁发起 | 是否上链 | 谁付 gas | 说明 |
|---|---|---|---|---|---|
| 1 | KYC 资料审核 | 投资者与审核系统 | 否 | 无 | 链下业务流程，链上不保存明文个人资料 |
| 2 | 创建 ONCHAINID | 投资者调用 Gateway.deployIdentityForWallet | 是 | 投资者 | Gateway 再调用 IdFactory.createIdentity |
| 3 | 签发 KYC 签名 | ClaimSigner 对 hash(identity, topic, data) 签名 | 否 | 无 | 只是 EOA/HSM/MPC 签名，不是交易 |
| 4 | KYC Claim 上链 | 投资者调用自己的 Identity.addClaim | 是 | 投资者 | 合约会调用 ClaimIssuer.isClaimValid 验签 |
| 5 | 登记到资产准入表 | IR Agent 调 IdentityRegistry.registerIdentity | 是 | IR Agent | 把钱包、身份合约、国家码登记到某个资产 Suite |
| 6 | 校验结果 | 任意人调用 IdentityRegistry.isVerified | 否（view） | 无 | 返回 true 才能接收 mint / transfer |
5.4.3 ClaimSigner 签 KYC 到底是不是上链操作
不是。签名动作发生在链下，类似下面这段逻辑：
digest = keccak256(abi.encode(identity, topic, data))
signature = ClaimSigner.signMessage(digest)
链上真正保存的是下一步 addClaim 交易的入参：
Identity.addClaim(
topic,
1,
claimIssuer,
signature,
data,
uri
)
addClaim 交易由投资者发起，但不能伪造资格，因为身份合约会调用 ClaimIssuer.isClaimValid(...) 校验：
issuer是否是可信签发机构；signature是否由 ClaimIssuer 上登记的 Claim Key 签出；- 该签名是否未被撤销；
topic是否是本资产要求的资格类型。
所以信任来源是 ClaimSigner 的签名，不是 addClaim 交易发送者。
5.5 转账 / 增发 / 销毁差异与校验矩阵
| 操作 | 谁 | 暂停拦？ | 查冻结 | 查身份 | 查合规模块 | 自动解冻 |
|---|---|---|---|---|---|---|
| 普通/授权转账 | 持币人/被授权方 | 是 | 双方 | 接收方 | 是 | 否 |
| 增发 | Agent | 否 | 否 | 接收方 | 是 | 否 |
| 销毁 | Agent | 否 | 否 | 否 | 否 | 是 |
| 强制转移 | Agent | 否 | 否 | 接收方 | 否（仍调 transferred） | 是 |
| 钱包恢复 | Agent | 否 | 否 | 走强制转移 | 否 | 是 |
要点：闸门一只验接收方；暂停不拦管理操作；强制转移不走 canTransfer，部分冻结挡不住 Agent。
5.7 升级交互
| 对象 | 调用链 | 影响 |
|---|---|---|
| TREX 主体 | IA Owner → addTREXVersion → useTREXVersion | 仍引用 Reference IA 的代理 |
| 单资产脱离全局 | 同一地址须为六合约 Owner → changeImplementationAuthority | 仅目标资产 |
| ONCHAINID | OID IA Owner → updateImplementation | 全部引用身份 |
| 合规模块 | Module Owner → upgradeTo | 绑定该模块的 MC |
6. 权限体系与多签
6.1 四种权限模型
| 模型 | 判断 | 用途 | Safe |
|---|---|---|---|
| Owner | msg.sender == owner | 治理、换组件、升级、配规则 | 可以，无 EOA 限制 |
| Agent | Agent 名单 | 增发、冻结、登记等高频操作 | 技术可以，高频不宜全走多签 |
| onlyToken / onlyComplianceCall | 须为已绑定合约 | 自动回调、模块参数转发 | 非人工账户 |
| ONCHAINID Key | keccak256(address) 用途 | 密钥、外部调用、Claim | 管理/操作 Key 可用 Safe；Claim 签名不行 |
无原生 Timelock。transferOwnership 可转给 Safe；renounceOwnership 会永久失去 Owner，生产应禁止误用。
6.2 权限矩阵
| 合约 | 角色 | 关键能力 | Safe 建议 |
|---|---|---|---|
| TREX IA / ONCHAINID IA | Owner | 全局升级 | 最高级 Safe + Timelock |
| TREXFactory | Owner | 部署 Suite、找回仍归 Factory 的 Owner | 通常由 Gateway 合约持有 |
| TREXGateway | Owner / Agent | 准入、费用、Factory 所有权 / Deployer | Owner→Safe；Agent→ 服务账户 |
| Token | Owner / Agent | 换 IR/MC、管 Agent / 增发销毁冻结强制转移恢复 | Owner→Safe；Agent 职责分离 |
| IR | Owner / Agent | 换 CTR/TIR/IRS / 注册删身份 | Owner→Safe；Agent→KYC 账户 |
| IRS | Owner / Agent | 绑 IR / 写身份主数据 | 先明确归属再定 Safe |
| CTR / TIR / MC | Owner | Topic、Issuer、模块与参数 | 合规 Safe + Timelock |
| 可升级 Module | Module Owner | UUPS 升级 | Safe + Timelock |
| IdFactory | Owner | 创建身份 | 平台 Safe |
| Identity | 管理/操作/声明 Key | 改密钥、执行、管 Claim | Safe 可作管理/操作 Key |
| ClaimIssuer | 管理 Key + 声明 Key | 撤销 / 签发 | 管理 →Safe；签发 →EOA/HSM/MPC |
6.3 Safe 结论
可以直接用 Safe： Suite 与平台各 Owner；模块升级 Owner；ONCHAINID 管理/操作 Key；单资产换 IA（前提是同一个 Safe 同时拥有六个合约）。
不能用 Safe 原生签 Claim： 验签依赖 ecrecover，只能恢复 EOA。正确做法是 Safe 管 Issuer 管理权，独立签名机持 Purpose 3。
不建议全走 Safe 的高频动作： 投资者注册、常规增发销毁、Deployer 维护、秒级暂停冻结、强制转移与恢复——宜用受限服务账户 + 链下审批与告警；极高风险动作仍可双人复核或专用多签。
6.4 推荐分层与三个陷阱
- IRS Owner 不随五合约自动移交，默认留在 Factory（通常再由 Gateway 持有），须主动
recoverContractOwnership。 - 单资产换 IA 要求六个
owner()都等于同一次msg.sender，不能拆成多个 Safe 分别点同意。 - Safe ≠ Timelock；全局升级、换 IR/MC、改 Topic/Issuer/模块等须外置延迟执行。
7. 调研与演示关键结论
以下与本仓库 demo / 外部参考图对照直接相关，避免配置踩坑。
| 结论 | 代码事实 |
|---|---|
| Topic 无固定编号 | 无 1=KYC 硬编码；demo 用 keccak256("KYC_APPROVED")，须自建链级 Topic 台账 |
| 身份不是 Beacon | ONCHAINID 用 ImplementationAuthority（npm 2.2.1） |
| 生产合规模块缺失 | 仅有 DemoCountryAllowlistModule（未审计）与 TestModule；legacy features 不能当模块部署 |
| 转账入口 | 投资者直接调 Token；不必经 IdentityProxy.execute |
| 国家码 | uint16，ISO 3166-1 numeric（如 156 中国、702 新加坡）；演示模块只查接收方 |
| 模块参数 | 按 MC 地址隔离，同一模块可服务多资产 |
| 身份复用 | 共享签发方即可免重复 KYC；共享 IRS 能力更强但治理面更大 |
| 依赖版本 | package.json 为 ^2.0.0，实际安装 2.2.1，生产应锁死版本 |
自建模块建议优先级（演示外）：国别准入、持仓上限、总量上限、人数上限 → 锁定期、投资者类别、额度 → 条件转账、场所限制等。
第三方：真正驱动链上配置的是 KYC/AML/Issuer 与合规模块参数；托管、审计、法币通道主要影响审批，不直接改合约状态。Claim data 禁止上链明文 PII。
8. 安全红线
- Owner / Agent / IA / ClaimIssuer 权限失控均可直接动资产或资格；Owner 与 Agent 不得长期同一单签。
- 强制转移、销毁可自动解冻；暂停拦不住管理操作。
- 摘除可信 Issuer 或清空 Topic 会批量改变用户资格。
- 全局 IA 升级影响面大，须多签 + Timelock + 存储布局校验 + 演练回滚。
- 合约解决不了：底层资产真实性、法律权属、兑付与跨辖区合法性——须另签规则矩阵。
9. 术语表
| 术语 | 含义 |
|---|---|
| T-REX / Suite | ERC-3643 参考实现 / 一套资产的六个业务合约 |
| ONCHAINID / Claim / Topic / Issuer | 身份合约 / 资格声明 / 声明类型 / 签发机构 |
| IR / IRS / CTR / TIR / MC | 身份登记处 / 身份存储 / Topic 表 / Issuer 表 / 合规编排器 |
| Owner / Agent | 配置治理权 / 运营操作权 |
| Implementation Authority | 版本中枢，决定代理当前实现 |
| TREXFactory / Gateway / IdFactory | 资产工厂 / 发行准入网关 / 身份工厂 |