ERC-3643 プロトコル紹介
目次
1. 概要
ERC-3643は、本人確認とコンプライアンス検査を備えたERC-20発行フレームワークです。トークンを保有できる主体、送金の可否、権限者による凍結・強制移転・資産回復、一貫した実装アップグレードを定義します。
| 観点 | 通常のERC-20 | ERC-3643 |
|---|---|---|
| 受取可能者 | 任意のアドレス | 検証済みIDのみ |
| 送金 | ビジネスルールによる拒否不可 | コンプライアンスモジュールが拒否可能 |
| 凍結・強制移転・ウォレット回復 | 利用不可 | 利用可能 |
| ルール変更 | 通常は別コントラクトが必要 | 設定またはモジュールを変更 |
2. 5つの中核概念
| 概念 | 意味 |
|---|---|
| ONCHAINID | ウォレットから独立したオンチェーンのユーザーID。1つのIDに複数ウォレットを紐付け可能 |
| Claim | IDに付与される署名済み資格証明 |
| Claim 発行者 | Claimの発行・失効権限を持つ機関コントラクト |
| Identity Registry | アドレスが適格投資家に属するかを判定する「人」の検査 |
| Compliance module | 取引がルールに従うかを判定する「取引」の検査 |
両方のゲートを通過する必要があります。KYC承認済みの投資家でも、保有上限などのコンプライアンスルールにより拒否される場合があります。
3. コントラクト全体構成
3.1 4つのレイヤー
| レイヤー | インスタンス数 | 目的 |
|---|---|---|
| プラットフォーム | 通常はチェーンごとに1つ | 発行アクセス、ID作成、共通アップグレード |
| Suite | 資産ごとに6コントラクト | 残高、ID、コンプライアンス、ガバナンス |
| ONCHAINID | ユーザーごとに1つ | キーとClaim |
| コンプライアンスモジュール | ルール単位でデプロイし再利用 | 実行可能な取引ルール |
各責務を独立して進化させるため、コントラクトは分離されています。Tokenは台帳、IR・IRS・CTR・TIRは本人資格、MCは取引ルールを管理します。Proxyアドレスは固定されます。 Proxyが状態を保持し、実装がロジックを提供します。
3.2 3つのアップグレード方式
| 対象 | 方式 | アップグレード入口 | 影響範囲 |
|---|---|---|---|
| 6つのTREXコントラクト | IA参照Proxy | TREX IA | そのIAを参照し続ける資産 |
| ONCHAINID | ONCHAINID IA | updateImplementation | そのIAを参照するID |
| コンプライアンスモジュール | ERC1967 + UUPS | モジュールOwnerのupgradeTo | そのモジュールに紐付く資産 |
4. コントラクトの責務とオンチェーン状態
チェーンには業務状態とルール設定を保存します。本人確認書類の画像、氏名、ID番号などの機微情報はオフチェーンKYCシステムに保持します。チェーンには資格種別、保有状況、送金適格性などの判定結果を記録します。
4.1 チェーン共通プラットフォームコントラクト
| コントラクト | 目的 | 主なオンチェーン状態 | 重要な上限 |
|---|---|---|---|
TREXImplementationAuthority | RWA資産が使用する実装バージョンを選択 | 現在のバージョンと各バージョンの6実装アドレス | 6実装を一括登録する必要あり |
IAFactory | 資産専用の独立アップグレード管理機関を作成 | 独立管理機関を付与した資産 | グローバル管理機関の管理者のみ作成可能 |
TREXFactory | 完全なRWA Suiteをデプロイ・初期化 | 使用済みsalt、管理機関、IDファクトリー、許可済みデプロイヤー | 初期設定はTopic・発行者・Agentが各最大5、モジュール操作が30 |
TREXGateway | 発行者、公開発行、手数料、割引を管理 | 公開設定、手数料トークン・金額・受取先、発行者一覧、割引、管理者 | 1バッチ最大5 Suite |
IdFactory | オンチェーンIDプロファイルとウォレット対応関係を作成 | ウォレット→IDおよびID→ウォレットの対応 | 1 IDあたり最大101ウォレット |
ONCHAINID ImplementationAuthority | ID実装バージョンを選択 | 現在の実装とアップグレード管理機関 | 変更は参照中の全IDに影響 |
ONCHAINID Gateway | プラットフォーム承認署名によりユーザーがIDを作成可能 | 承認済み署名者と失効済み署名 | 通常はデモの主要フロー外 |
4.2 RWA資産ごとの6つの中核コントラクト
| コントラクト | 目的 | 主なオンチェーン状態 | 重要な上限 |
|---|---|---|---|
Token | 台帳、送金、Mint、Burn、一時停止、凍結、強制移転、ウォレット回復 | 残高、Allowance、供給量、メタデータ、停止状態、全体・部分凍結、接続先IR/MC、Owner、Agent | decimalsは0〜18 |
IdentityRegistry | 送金・Mint前に受取人の適格性を確認 | CTR・TIR・IRSへの参照とRegistry管理者 | 要件と発行者が増えるほどGasコスト増加 |
IdentityRegistryStorage | ウォレットのIDと国を保存し、共有可能 | ウォレット→ID・国、およびストレージを使うRegistry | 最大300 IdentityRegistry、ウォレットごとに1レコード |
ClaimTopicsRegistry | 資産保有に必要な資格を定義 | 必須Topicと管理者 | 一意なTopicは最大15 |
TrustedIssuersRegistry | 承認する発行者と許可Topicを定義 | 発行者と資格種別 | 発行者は最大50、各発行者のTopicは最大15 |
ModularCompliance | 金額、国、ロックアップなどの取引ルールを適用 | 紐付くToken、接続済みモジュール、管理者 | Token 1つ、モジュール最大25 |
4.3 ユーザーIDとルールモジュール
| コントラクト | 目的 | 主なオンチェーン状態 |
|---|---|---|
ONCHAINID / Identity | 1人につき1つの再利用可能なオンチェーンID。ウォレットは交換可能な手段 | Management・Action・Claimキーと受領済みClaim |
ClaimIssuer | 証明を発行・失効するKYC/AML機関コントラクト | IDキーと失効済み署名 |
ModuleProxy | 1つの業務ルールに対する固定の入口 | 現在の実装と資産別パラメータ |
ソース配置：プラットフォームコントラクトはcontracts/factory/とproxy/authority/、資産コントラクトはtoken/・registry/・compliance/modular/、ID機能は@onchain-id/solidityにあります。
5. コントラクト間の連携
5.1 依存関係
5.3 発行
Gatewayのsaltには通常、Ownerアドレスの16進表現とToken名を連結した値を使います。手数料を有効にする場合は、先に手数料トークンをapproveします。
5.4 投資家オンボーディング：ID、KYC署名、オンチェーンClaim
オンボーディングはIDコントラクト作成、資格署名、Claim送信、資産側登録の4段階です。各段階を明確に区別します。
- ONCHAINIDの作成はオンチェーントランザクションであり、投資家のIDコントラクトをデプロイします。
- ClaimSignerによるKYC署名はオフチェーンであり、トランザクションもGasコストも発生しません。
addClaimはオンチェーントランザクションであり、ClaimSigner署名とKYC判定を投資家のONCHAINIDに保存します。
5.4.1 本番フロー：ONCHAINID GatewayによるセルフサービスID作成
IdFactory.createIdentityはonlyOwnerです。投資家からFactoryへの直接呼出しは許可されません。本番では公式Gateway.solをデプロイし、IdFactoryの所有権を移して、投資家がGateway.deployIdentityForWallet(investor)を呼び出す構成にします。GatewayがOwnerとして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にウォレット、ID、国を記録 |
| 6 | 結果確認 | 誰でもIdentityRegistry.isVerifiedを呼出し可能 | いいえ（view） | なし | Mintまたは送金受取前にtrueが必要 |
5.4.3 ClaimSignerのKYC署名はオンチェーンか
署名自体はオフチェーンで生成します。
digest = keccak256(abi.encode(identity, topic, data))
signature = ClaimSigner.signMessage(digest)
続くaddClaimトランザクションが次の引数を保存します。
Identity.addClaim(
topic,
1,
claim発行者,
signature,
data,
uri
)
投資家がaddClaimを送信すると、IDコントラクトがClaimIssuer.isClaimValid(...)を呼び出し、信頼済み発行者、登録済みClaimキー由来の署名、未失効の署名、必須Topicを検証します。信頼の根拠はClaimSignerの署名であり、addClaimの送信者には依存しません。
5.5 送金・Mint・Burnの判定表
| Operation | 呼出元 | Paused check | Freeze check | Identity check | Compliance check | Auto-unfreeze |
|---|---|---|---|---|---|---|
| 送金 / 委任送金 | 保有者 / 承認済み支出者 | あり | 双方 | 受取人 | あり | なし |
| Mint | Agent | なし | なし | 受取人 | あり | なし |
| Burn | Agent | なし | なし | なし | なし | あり |
| 強制移転 | Agent | なし | なし | 受取人 | なし、transferredは呼出し | あり |
| ウォレット回復 | Agent | なし | なし | 強制移転を使用 | なし | あり |
ゲート1は受取人だけを検証します。一時停止中も管理操作は実行できます。強制移転はcanTransferを省略し、部分凍結はAgentの操作を妨げません。
5.7 アップグレード連携
| 対象 | 呼出しチェーン | 影響 |
|---|---|---|
| TREX contracts | IA owner → addTREXVersion → useTREXVersion | 基準IAを参照するProxy |
| Detach one asset | 同一アドレスが6つすべてを所有 → changeImplementationAuthority | 対象資産のみ |
| ONCHAINID | OID IA owner → updateImplementation | 参照中の全ID |
| Compliance module | Module owner → upgradeTo | そのモジュールに紐付くMC |
6. 権限とマルチシグ
6.1 4つの権限モデル
| モデル | 認可 | 用途 | Safe対応 |
|---|---|---|---|
| Owner | msg.sender == owner | ガバナンス、コンポーネント交換、アップグレード、ルール | 対応、EOA制限なし |
| Agent | Agent list | 頻繁なMint・凍結・登録操作 | 技術的には対応。高頻度操作ごとのマルチシグは非効率 |
| onlyToken / onlyComplianceCall | 紐付け済みコントラクトアドレス | 自動Callbackとパラメータ転送 | 人が操作するアカウントではない |
| ONCHAINID Key | Purpose別のkeccak256(address) | キー管理、外部呼出し、Claim | SafeはActionキーを管理可能。Claimのネイティブ署名は不可 |
ネイティブTimelockはありません。transferOwnershipで所有権をSafeに割り当てられます。renounceOwnershipはOwnerを恒久的に削除するため、本番環境では実行防止策が必要です。
6.2 権限マトリクス
| コントラクト | ロール | 重要な権限 | Safe推奨構成 |
|---|---|---|---|
| TREX IA / ONCHAINID IA | Owner | グローバルアップグレード | 最高セキュリティのSafe + Timelock |
| TREXFactory | Owner | SuiteのデプロイとFactory所有コントラクトの回収 | 通常はGatewayが所有 |
| TREXGateway | Owner / Agent | アクセス、手数料、Factory所有権、デプロイヤー | Owner → Safe、Agent → サービスアカウント |
| Token | Owner / Agent | IR/MC交換、Agent管理、Mint、Burn、凍結、強制移転、回復 | Owner → Safe、Agentの職務を分離 |
| IR | Owner / Agent | CTR/TIR/IRS交換と投資家登録管理 | Owner → Safe、Agent → KYCアカウント |
| IRS | Owner / Agent | IR紐付けとIDマスターデータ書込み | 先に所有権モデルを確立 |
| CTR / TIR / MC | Owner | Topic、発行者、モジュール、パラメータ | コンプライアンスSafe + Timelock |
| Upgradeable Module | Module owner | UUPSアップグレード | Safe + Timelock |
| IdFactory | Owner | ID作成 | プラットフォームSafe |
| Identity | Management/action/Claim keys | キー管理、呼出し実行、Claim管理 | SafeがManagement/Actionキーを保有可能 |
| ClaimIssuer | Management + Claim keys | 失効と発行 | Management → Safe、発行 → EOA/HSM/MPC |
6.3 Safeに関する結論
Safeを直接利用できる対象： Suite・プラットフォームのOwner、モジュールアップグレードOwner、ONCHAINIDのManagement/Actionキー、および同じSafeが6コントラクトを所有する場合の資産別IA交換。
SafeはClaimをネイティブ署名できません。 検証にEOAを復元するecrecoverを使います。発行者管理にはSafe、Purpose 3署名には独立した署名者を使用します。
高頻度操作には権限を制限したサービスアカウントを使用します。 投資家登録、定常的なMint/Burn、デプロイヤー保守、緊急停止・凍結、強制移転、回復が対象です。オフチェーン承認とアラートを適用し、重大リスクには二重承認または専用マルチシグを使います。
6.4 推奨レイヤーと3つの注意点
- IRSの所有権は他の5コントラクトと同時には移転されません。
recoverContractOwnershipを呼ぶまでFactoryに残り、通常そのFactoryはGatewayが所有します。 - 1資産のIA変更には、6つすべての
owner()が同じmsg.senderである必要があります。 分離したSafeから個別承認する構成には対応しません。 - SafeとTimelockは異なる統制を提供します。 グローバルアップグレード、IR/MC交換、Topic・発行者・モジュール変更には外部実行遅延が必要です。
7. 調査・デモの結論
| 結論 | コード上の事実 |
|---|---|
| Topicに固定番号はない | 1=KYCのハードコードはなく、デモはkeccak256("KYC_APPROVED")を使用。チェーン共通Topic台帳が必要 |
| IdentityはBeaconではない | ONCHAINIDはnpm 2.2.1のImplementationAuthorityを使用 |
| 本番用コンプライアンスモジュールが不足 | 未監査のDemoCountryAllowlistModuleとTestModuleのみ。旧機能はデプロイ可能モジュールではない |
| 送金入口 | 投資家はTokenを直接呼び出し、IdentityProxy.executeは不要 |
| 国コード | uint16のISO 3166-1数値（156、702など）。デモモジュールは受取人のみ確認 |
| モジュールパラメータ | MCアドレスごとに分離され、1モジュールを複数資産で利用可能 |
| ID再利用 | 発行者共有でKYC重複を回避。IRS共有は再利用性とともにガバナンス範囲を拡大 |
| 依存バージョン | package.jsonは^2.0.0、インストール済みは2.2.1。本番バージョンを固定する |
デモ後のカスタムモジュール優先順位：国別アクセス、保有者別上限、総供給上限、保有者数 → ロックアップ、投資家区分、金額制限 → 条件付き送金、取引場所制限。
KYC/AML発行者とモジュールパラメータはオンチェーン設定に直結します。カストディ、監査、法定通貨レールは主に承認フローへ影響します。Claimのdataに平文PIIを保存しないでください。
8. セキュリティ境界
- Owner、Agent、IA、ClaimIssuerの侵害は資産や適格性を直接変更し得ます。長期保有するOwner署名者とAgent署名者を分離します。
- 強制移転とBurnは自動的に凍結解除する場合があります。一時停止中も管理操作は実行されます。
- 信頼済み発行者の削除やTopicの全消去は、多数ユーザーの適格性を同時に変更します。
- グローバルIAアップグレードは影響範囲が広く、マルチシグ、Timelock、ストレージレイアウト検証、ロールバック演習が必要です。
- コントラクトだけでは裏付資産の真正性、法的権利、償還、法域横断の適法性を確定できません。別のルールマトリクスで定義します。
9. 用語集
| 用語 | 意味 |
|---|---|
| T-REX / Suite | ERC-3643参照実装 / 1資産を構成する6つの業務コントラクト |
| ONCHAINID / Claim / Topic / 発行者 | IDコントラクト / 資格証明 / 証明種別 / 発行機関 |
| IR / IRS / CTR / TIR / MC | IDレジストリ / IDストレージ / Topicレジストリ / 発行者レジストリ / コンプライアンス調整役 |
| Owner / Agent | 設定ガバナンス権限 / 運用権限 |
| Implementation Authority | 現在のProxy実装を選択するバージョン管理機関 |
| TREXFactory / Gateway / IdFactory | 資産ファクトリー / 発行アクセスGateway / IDファクトリー |