05 · コントラクトインターフェースとイベント

本章は、発行、オンボーディング、mint、transfer、burn をコントラクトメソッドへ対応付ける実装リファレンスです。

5.1 最初に正しいコントラクトを特定する

外部アプリケーションが Suite 全体へ直接接続する必要はありません。対象資産の Token プロキシアドレスから開始します。

推奨探索順序：

1. 公開アドレス表から対象環境の Token プロキシアドレスを取得。
2. Token.identityRegistry() で資産 Registry を取得。
3. Token.compliance() でコンプライアンス入口を取得。
4. IdFactory.getIdentity(wallet) でウォレットの ONCHAINID を取得。
5. オンチェーン結果を公開設定と比較し、実装アドレスを業務入口に使用しない。

5.2 権限早見表

呼出者	主な write メソッド	説明
任意のユーザーまたはアプリ	すべての view	read-only。トランザクションとユーザー gas は不要
Token 保有者	transfer, approve, transferFrom	ID、pause、freeze、ルール検査が適用
投資家 ID 管理ウォレット	deployIdentityForWallet, addClaim	自分の ONCHAINID を作成・管理
IR Agent	registerIdentity, updateIdentity, updateCountry, deleteIdentity	1 資産の投資家登録を管理
Token Agent	mint, burn, pause, unpause, freeze、強制移転、復旧	資産管理操作
Contract Owner	Registry、Compliance、ガバナンス設定の変更	通常アプリ統合の範囲外

操作表示前に現在のウォレットロールを識別してください。フロントエンドのボタン非表示はオンチェーン権限制御の代替になりません。

5.3 Token

主な read メソッド

メソッド	戻り値	用途
name() / symbol()	string	資産名・シンボル表示
decimals()	uint8	金額変換
totalSupply()	uint256	現在の総供給量
balanceOf(wallet)	uint256	ウォレット総残高
identityRegistry()	address	資産適格性 Registry
compliance()	address	コンプライアンス入口
paused()	bool	通常 transfer の pause 状態
isFrozen(wallet)	bool	ウォレット全体の freeze 状態
getFrozenTokens(wallet)	uint256	一部 freeze 数量

availableBalance = balanceOf(wallet) - getFrozenTokens(wallet)

保有者 write メソッド

メソッド	用途	主な前提
transfer(to, amount)	直接 transfer	Token 稼働、wallet 状態許可、受取人適格、ルール合格
approve(spender, amount)	allowance 設定	保有者署名
transferFrom(from, to, amount)	allowance を使う transfer	allowance、残高、適格性、ルール合格

Token Agent メソッド

メソッド	用途	主な結果
mint(to, amount)	Mint	Transfer(0x0, to, amount)
burn(wallet, amount)	Burn	Transfer(wallet, 0x0, amount)
pause() / unpause()	通常 transfer の停止・有効化	Paused / Unpaused
setAddressFrozen(wallet, frozen)	ウォレット全体を freeze / 解除	AddressFrozen
freezePartialTokens(wallet, amount)	残高の一部を freeze	TokensFrozen
unfreezePartialTokens(wallet, amount)	一部 freeze を解除	TokensUnfrozen
forcedTransfer(from, to, amount)	管理者による強制移転	Transfer
recoveryAddress(lost, new, identity)	新ウォレットへ資産復旧	RecoverySuccess と Transfer

すべての amount は最小単位の整数です。バッチは block gas limit に達し得るため分割し、各トランザクションを個別追跡します。

操作	pause 中に停止	受取人適格性	canTransfer	freeze 残高
transfer / transferFrom	はい	検査	検査	freeze 数量は移転不可
mint	いいえ	検査	検査	対象外
burn	いいえ	非検査	非検査	Agent が解除を要する場合あり
forcedTransfer	いいえ	検査	非検査	Agent が解除を要する場合あり
recoveryAddress	いいえ	復旧フロー規則	非検査	freeze 状態を移行可能

pause は主に通常の保有者 transfer を制限し、Agent の mint、burn、強制移転、ウォレット復旧は停止しません。

5.4 IdentityRegistry

対象 Token の identityRegistry() からアドレスを取得します。

主な read メソッド

メソッド	意味
contains(wallet)	登録レコードの有無
isVerified(wallet)	現行要件をすべて満たすか
identity(wallet)	登録済み ONCHAINID
investorCountry(wallet)	登録済み国・地域コード
topicsRegistry()	必須 Claim Topics の Registry
issuersRegistry()	承認 ClaimIssuers の Registry

contains == true は登録だけを示し、isVerified == true の代わりになりません。

IR Agent メソッド

メソッド	用途	イベント
registerIdentity(wallet, identity, country)	初回登録	IdentityRegistered
updateIdentity(wallet, identity)	関連 ID 置換	IdentityUpdated
updateCountry(wallet, country)	国・地域コード更新	CountryUpdated
deleteIdentity(wallet)	資産から登録削除	IdentityRemoved

1 つの ONCHAINID は複数資産から参照できますが、各資産の IdentityRegistry へ通常は個別登録が必要です。

5.5 ONCHAINID Gateway、IdFactory、Identity

ID を作成または照会

コントラクト	メソッド	呼出者	用途
ONCHAINID Gateway	deployIdentityForWallet(wallet)	投資家	wallet の決定論的 ONCHAINID を作成
IdFactory	getIdentity(wallet)	任意のアプリ	関連 ID を照会

作成後に IdFactory は Deployed と WalletLinked を発火します。getIdentity(wallet) を再照会し、最終オンチェーン対応を使用します。

Claim メソッド

addClaim(
    uint256 topic,
    uint256 scheme,
    address issuer,
    bytes signature,
    bytes data,
    string uri
) returns (bytes32 claimId)

メソッド	用途
getClaim(claimId)	1 Claim の全フィールドを取得
getClaimIdsByTopic(topic)	Topic の Claim IDs を照会
isClaimValid(identity, topic, signature, data)	ClaimIssuer 署名を検証

主要イベントは ClaimAdded、ClaimChanged、ClaimRemoved です。ClaimSigner はオフチェーン署名を生成し、ClaimIssuer は署名が属するオンチェーン機関コントラクトです。

5.6 ModularCompliance

canTransfer は Token ではなく ModularCompliance に定義されます。

canTransfer(address from, address to, uint256 amount) view returns (bool)

メソッド	用途
canTransfer(from, to, amount)	現行ルールによる transfer 事前検査
getModules()	紐づくルールモジュール一覧
getTokenBound()	紐づく Token
isModuleBound(module)	モジュール紐付けを確認

canTransfer == true は照会時点のルール合格を示します。pause、freeze、残高、適格性、ルールは確定前に変化し得るため、レシートが最終判断です。transferred、created、destroyed は紐づく Token が状態変更を通知する callback で、通常アプリは直接呼び出しません。

5.7 イベント索引

イベント	発生元	用途
Transfer	Token	Mint、burn、transfer
Approval	Token	allowance 変更
Paused / Unpaused	Token	transfer 状態変更
AddressFrozen	Token	wallet 全体の freeze
TokensFrozen / TokensUnfrozen	Token	一部 freeze 変更
RecoverySuccess	Token	wallet 復旧
IdentityRegistered / IdentityRemoved	IdentityRegistry	登録変更
IdentityUpdated / CountryUpdated	IdentityRegistry	ID・国変更
ClaimAdded / ClaimChanged / ClaimRemoved	ONCHAINID	適格性証明変更
ModuleAdded / ModuleRemoved	ModularCompliance	ルールモジュール変更

イベントは変更を示します。reorg、backfill、長時間オフライン後はコントラクト状態を再読込して照合します。

5.8 最小 ABI

const tokenAbi = [
  'function name() view returns (string)',
  'function symbol() view returns (string)',
  'function decimals() view returns (uint8)',
  'function totalSupply() view returns (uint256)',
  'function balanceOf(address) view returns (uint256)',
  'function identityRegistry() view returns (address)',
  'function compliance() view returns (address)',
  'function paused() view returns (bool)',
  'function isFrozen(address) view returns (bool)',
  'function getFrozenTokens(address) view returns (uint256)',
  'function transfer(address,uint256) returns (bool)',
  'event Transfer(address indexed from,address indexed to,uint256 value)',
];

const identityRegistryAbi = [
  'function contains(address) view returns (bool)',
  'function isVerified(address) view returns (bool)',
  'function identity(address) view returns (address)',
  'function investorCountry(address) view returns (uint16)',
  'event IdentityRegistered(address indexed investorAddress,address indexed identity)',
];

const complianceAbi = [
  'function canTransfer(address,address,uint256) view returns (bool)',
  'function getModules() view returns (address[])',
];

実際の write 操作にはデプロイ済みバージョンに一致する公式 ABI を使用し、メソッド名から引数順を推測しないでください。

5.9 推奨呼び出し順序

Chain ID を検証
→ Token.decimals を読み取り
→ paused / isFrozen / getFrozenTokens を読み取り
→ Token.identityRegistry から正しい Registry を取得
→ 受取人 contains / isVerified を照会
→ Token.compliance から Compliance を取得
→ canTransfer
→ estimateGas または static simulation
→ トランザクション送信、レシート待機
→ イベントと最新状態からアプリを更新

次へ：06 · 環境設定と受入検証