ERC-3643 - SMART CONTRACTS LIBRARY
구조
ERC-3643(T-REX)는 증권형 토큰(STO)의 규제 요건을 충족하기 위해 토큰 로직, 신원 관리, 규제 판단, 배포 권한을 각각 분리한 모듈형 스마트컨트랙트 구조를 채택한다.
토큰 자체는 Permissioned Token 계약이 담당하며,
투자자 자격 검증은 ONCHAINID(ERC-734/735)와 Identity Registry 계층에서 수행된다.
규제 적합성 판단은 Compliance 계약이 전담하며, 토큰 전송 전canTransfer()를 통해 사전 검증하고 전송 후 Hook 함수로 상태를 갱신한다.
모든 구성요소는 T-REX Factory를 통해 단일 트랜잭션으로 배포되며, 실제 배포 권한·수수료·정책 통제는 Gateway 계약이 담당한다.
이러한 구조를 통해 ERC-3643는 규제 변경에 유연하고, 감사 가능하며, 대규모 STO 발행 플랫폼에 적합한 토큰 아키텍처를 제공한다.
Permissioned Tokens
Tokens Interface
: 토큰의 생명주기를 관리하고 규제하는 데 필수적인 포괄적인 기능 및 이벤트를 정의
이벤트
| 이벤트 | 설명 |
| UpdatedTokenInformation | 토큰이름, 심볼, 소수점, 버전, OnchainID 등 메타데이터 변경시 발생 |
| IdentityRegistryAdded | 토큰에 Identity Registry가 설정될 때 발생 |
| ComplianceAdded | 토큰에 Compliance 계약이 설정될 때 발생 |
| RecoverySuccess | 분실 지갑에서 신규 지갑으로 토큰 복구가 성공했을 때 발생 |
| AddressFrozen | 주소가 동결 또는 동결해제될 때 발생 |
| TokensFrozen | 특정 주소의 토큰 일부가 동결될 때 발생 |
| TokensUnfrozen | 특정 주소의 동결된 토큰 일부가 해제될 때 발생 |
| Paused | 토큰 전송이 일시중지될 때 발생 |
| Unpaused | 토큰 전송이 재개될 때 발생 |
토큰 제어 및 관리 함수
– 토큰 소유자 또는 권한을 부여받은 에이전트가 운영 및 컴플라이언스 관련 기능을 제어할 수 있도록 한다.
메타데이터 & 신원 - 토큰 계약의 소유자만 함수 호출 가능
| 메서드 | 접근권한 | 설명 |
| setName(string) | Owner | 토큰 이름을 변경한다 |
| setSymbol(string) | Owner | 토큰 심볼을 변경한다 |
| setOnchainID(address) | Owner | 토큰 발행 주체의 온체인 신원을 설정한다 |
| setIdentityRegistry(address) | Owner | 투자자 신원 검증에 사용되는 Identity Registry를 연결한다 |
일시중지 & 동결 제어 – 토큰의 에이전트만 함수 호출 가능
| 메서드 | 접근권한 | 설명 |
| pause() | Agent | 모든 토큰 전송을 일시중지한다 |
| unpause() | Agent | 중지된 토큰 전송을 재개한다 |
| setAddressFrozen(address,bool) | Agent | 특정 주소의 전체 전송을 동결 또는 해제한다 |
| freezePartialTokens(address,uint256) | Agent | 특정 주소의 토큰 일부 수량을 동결한다 |
| unfreezePartialTokens(address,uint256) | Agent | 동결된 토큰 일부수 량을 해제한다 |
컴플라이언스 & 전송 규칙
| 메서드 | 접근권한 | 설명 |
| setCompliance(address) | Owner | 토큰 전송규칙을 정의하는 Compliance 계약을 설정한다 |
| forcedTransfer(address,address,uint256) | Agent | 법적·규제사유에 따라 두 주소간 토큰 전송을 강제로 수행한다 |
토큰 발행 & 소각 – 토큰의 에이전트만 함수 호출 가능
| 메서드 | 접근권한 | 설명 |
| mint(address,uint256) | Agent | 인증된 주소로 신규 토큰을 발행한다 |
| burn(address,uint256) | Agent | 특정 주소의 토큰을 소각한다 |
복구 – 토큰의 에이전트만 함수 호출 가능
| 메서드 | 접근권한 | 설명 |
| recoveryAddress(address,address,address) | Agent | 분실된 지갑의 토큰을 투자자의 신규 지갑으로 복구한다 |
배치(Batch) 연산
| 메서드 | 접근권한 | 설명 |
| batchTransfer(address[],uint256[]) | User | 여러 주소로 토큰을 일괄 전송한다 |
| batchForcedTransfer(address[],address[],uint256[]) | Agent | 여러 주소쌍간 토큰을 강제 전송한다 |
| batchMint(address[],uint256[]) | Agent | 여러 주소로 토큰을 일괄 발행한다 |
| batchBurn(address[],uint256[]) | Agent | 여러 주소의 토큰을 일괄 소각한다 |
| batchSetAddressFrozen(address[],bool[]) | Agent | 여러 주소의 동결 상태를 일괄 설정한다 |
| batchFreezePartialTokens(address[],uint256[]) | Agent | 여러 주소의 토큰을 부분 동결한다 |
| batchUnfreezePartialTokens(address[],uint256[]) | Agent | 여러 주소의 동결된 토큰을 일괄 해제한다 |
포함된 ERC-20 표준 함수
ERC-20과의 호환성을 유지하기 위해 모든 표준 ERC-20 함수가 포함된다.
* totalSupply() — 총 발행된 토큰 수
* balanceOf(address) — 특정 주소의 잔액
* transfer(address, uint256) — 토큰 전송(권한 조건 적용)
* allowance(owner, spender) — 허용된 사용 한도 조회
* approve(spender, amount) — 사용 한도 승인
* transferFrom(from, to, amount) — 승인된 한도 내에서 토큰 전송
ONCHAINID 인터페이스
: ONCHAINID 인터페이스는 블록체인에서 신원 및 클레임을 관리하는 데 사용되는 함수 및 이벤트 집합을 정의한다. 이는 두 가지 주요 인터페이스인 ERC-734와 ERC-735의 기능을 확장한다.
ERC-734 — 키(key) 관리 및 실행(execution)
ERC-735 — 클레임(검증 가능한 자격 증명, verifiable credentials)
키 관리 (ERC-734 기반)
ERC-734 (Key Management & Execution)
| 메서드 | 설명 |
| addKey(bytes32,uint256,uint256) | 신원에 새로운 권한 키를 추가한다 |
| removeKey(bytes32,uint256) | 신원에 등록된 키를 제거한다 |
| approve(uint256,bool) | 실행 요청을 승인 또는 거부한다 |
| execute(address,uint256,bytes) | 신원을 대신하여 트랜잭션을 실행한다 |
| getKey(bytes32) | 특정 키의 목적과 타입을 조회한다 |
| getKeyPurposes(bytes32) | 특정 키에 할당된 목적을 조회한다 |
| keyHasPurpose(bytes32,uint256) | 키가 특정 목적을 보유했는지 확인한다 |
클레임 관리 (ERC-735 기반) - 신원에 연결된 검증 가능한 자격 증명
ERC-735 (Claims Management)
| 메서드 | 설명 |
| addClaim(uint256,uint256,address,bytes,bytes,string) | 신원에 검증가능한 클레임을 추가 또는 갱신한다 |
| removeClaim(bytes32) | 등록된 클레임을 제거한다 |
| getClaim(bytes32) | 특정 클레임의 상세정보를 조회한다 |
| getClaimIdsByTopic(uint256) | 특정 주제에 해당하는 클레임 ID 목록을 조회한다 |
| isClaimValid(IIdentity,uint256,bytes,bytes) | 지정된 청구주제 및 신원계약과 서명 및 데이터를 대조하여 청구의 유효성을 검증한다 |
Identity Registry interface
: T-REX 프로토콜 내에서 Identity를 관리하고 확인하는 데 사용되는 함수 및 이벤트 세트를 정의한다.
이벤트(Event)
| 이벤트명 | 발생시점 |
| ClaimTopicsRegistrySet | 신원 레지스트리에 대해 클레임 토픽 레지스트리가 설정 되었을 때 발행 |
| IdentityStorageSet | Identity Registry Storage가 Identity Registry에 대해 설정 되었을 때 발행 |
| TrustedIssuersRegistrySet | 신뢰할수있는발급자레지스트리가 Identity 레지스트리에 대해 설정된 경우 발행 |
| IdentityRegistered | 신원 등록부에 신원이 등록되었을 때 발행 |
| IdentityRemoved | 신원 레지스트리에서 신원이 제거될 때발 행 |
| IdentityUpdated | 신원 레지스트리에서 신원이 업데이트 되었을 때 발행 |
| CountryUpdated | 투자자 국가 코드 변경 |
쓰기 함수 (관리 기능)
투자자 신원 관리
| 함수 | 설명 |
| registerIdentity | 사용자 주소에 해당하는 신원 계약을 등록 |
| deleteIdentity | 투자자 신원 삭제 |
| updateIdentity | 사용자 주소에 해당하는 신원 계약을 업데이트(기존 ONCHAINID 변경) |
| updateCountry | 투자자 국가 코드 변경 |
| batchRegisterIdentity | 여러 ID를 일괄적으로 등록 |
※ 주체: Agent(관리자)
레지스트리 설정 (Owner 전용)
| 함수 | 설명 |
| setIdentityRegistryStorage | 현재 Identity Registry Storage 계약을 새 계약으로 대체 |
| setClaimTopicsRegistry | 현재 청구 주제 레지스트리 계약을 새 계약으로 대체 |
| setTrustedIssuersRegistry | 현재 신뢰할 수 있는 발행자 등록 계약을 새 계약으로 대체 |
읽기 함수 (조회 기능)
| 함수 | 반환내용 |
| contains | 해당 지갑 주소 등록 여부 확인 |
| isVerified | 사용자 주소에 해당하는 신원 계약에 확인에 필요한 청구가 있는지 확인 |
| identity | 지갑 주소를 기반으로 투자자의 ONCHAINID를 반환 |
| investorCountry | 지갑 주소를 기반으로 투자자 국가 코드 반환 |
| identityStorage | 현재 ID 레지스트리에 연결된 ID 레지스트리 저장소를 반환 |
| issuersRegistry | 현재 Identity 레지스트리에 연결된 Trusted Issuers 레지스트리를 반환 |
| topicsRegistry | 현재 ID 레지스트리에 연결된 클레임 주제 레지스트리를 반환 |
Identity Registry Storage Interface
: T-REX 프로토콜 내에서 ID 데이터를 관리하고 저장하는 데 사용되는 함수 및 이벤트를 정의한다.
설계 특징: 아이덴티티 저장(Storage)과 로직(Registry)을 분리
활용 구조: 여러 개의 Identity Registry 컨트랙트가 하나의 Storage 컨트랙트를 공유할 수 있다.
핵심 역할: 실제 토큰 전송 검증 로직은 Registry에 있고, Storage는 데이터 보관 전용
이벤트(Event)
| 이벤트명 | 발생조건 |
| IdentityStored | 신원이 저장 계약에 등록 되었을 때 발행 |
| IdentityUnstored | ID가 저장 계약에서 제거될 때 발행 |
| IdentityModified | 저장 공간 계약에서 ID가 업데이트 되었을 때 행 |
| CountryModified | 국가 코드가 번경되었을 때 발행 |
| IdentityRegistryBound | Registry에 Storage 쓰기 권한 부여 |
| IdentityRegistryUnbound | Registry 권한 제거 |
쓰기 함수 (Identity Registry 전용)
* 권한이 부여된 Identity Registry만 호출 가능
| 함수 | 기능 |
| addIdentityToStorage | 저장소의 사용자 주소에 해당하는 ID 계약을 추가 |
| removeIdentityFromStorage | 저장된 아이덴티티 정보 삭제 |
| modifyStoredIdentity | 지갑주소에 연결된 ONCHAINID 변경 |
| modifyStoredInvestorCountry | 투자자 국가 코드 변경 |
※ 주체: Agent(관리자)
레지스트리 권한 관리 (Owner 전용)
* Storage 컨트랙트 Owner만 호출 가능
| 함수 | 기능 |
| bindIdentityRegistry | Identity Registry Storage Contract의 에이전트로 ID 레지스트리를 추가 |
| unbindIdentityRegistry | Registry 접근 권한 제거 |
| linkedIdentityRegistries | 연결된 Registry 주소 목록 조회 |
조회 함수 (View)
| 함수 | 반환정보 |
| storedIdentity | 지갑 주소에 저장된 ONCHAINID 반환 |
| storedInvestorCountry | 지갑 주소에 저장된 국가 코드 반환 |
Trusted Issuers Registry Interface
: T-REX(ERC-3643) 프로토콜 내에서 신뢰할 수 있는 Claim Issuer를 관리하고, 해당 발행자가 특정 Claim을 발급할 수 있는지 검증하기 위한 함수와 이벤트를 정의한 인터페이스이다.
이벤트(Event)
| 이벤트명 | 발생시점 |
| TrustedIssuerAdded | 신뢰할 수 있는 발급자가 레지스트리에 추가될 때 발행 |
| TrustedIssuerRemoved | 신뢰할 수 있는 발급자가 레지스트리에서 제거될 때 발행 |
| ClaimTopicsUpdated | 지정된 신뢰할 수 있는 발급자에 대해 청구 주제 집합이 변경될 때 발행 |
관리자 전용 함수 (Owner Only)
* 컨트랙트 Owner(일반적으로 토큰 발행자)만 호출 가능
| 함수 | 기능 |
| addTrustedIssuer | Claim Issuer 등록 및 발급가능 Claim Topic 지정 |
| removeTrustedIssuer | Claim Issuer 제거 (발급 Claim 신뢰상실) |
| updateIssuerClaimTopics | Issuer의발급가능 Claim Topic 수정 |
조회(Read-only) 함수
| 함수 | 반환/기능 |
| getTrustedIssuers | 모든신뢰된 Claim Issuer 목록 |
| getTrustedIssuersForClaimTopic | 특정 Claim Topic 발급가능한 Issuer 목록 |
| isTrustedIssuer | 주어진 ClaimIssuer 계약이신뢰할수있는지확인 |
| getTrustedIssuerClaimTopics | Issuer별 허용 Claim Topic |
| hasClaimTopic | Issuer가 특정 Claim Topic 발급가능여부확인 |
Claim Topics Registry Interface
: ERC-3643(T-REX) 프로토콜에서 토큰을 보유하거나 전송하기 위해 필수적으로 요구되는 클레임(Claim)의 종류(토픽)를 관리하는 스마트컨트랙트 인터페이스이다. -> “이 토큰을 보유하려면 어떤 자격이 필요한가”를 온체인에서 정의
핵심 목적
토큰 보유자가 반드시 충족해야 하는 클레임 유형 목록을 저장
Identity Registry 및 Compliance 모듈이 해당 토큰의 규제 요건 충족 여부를 검증할 때 참조
일반적으로 컨트랙트 소유자(owner)만 수정 가능
* Claim Topics Registry는 발급 주체를 관리하지 않는다.
누가(claim issuer) 클레임을 발급할 수 있는지는 다루지 않고 어떤 종류의 클레임이 필요한지만 정의한다.
(→ 발급 주체 관리는 Trusted Issuers Registry 담당)
이벤트(Event)
| 이벤트명 | 의미 |
| ClaimTopicAdded | 클레임 주제가 클레임 주제 레지스트리에 추가되었을 때 발행 |
| ClaimTopicRemoved | 클레임 주제가 클레임 주제 레지스트리에서 제거되었을 때 발행 |
- 이벤트는 규제 요건 변경 이력 추적 및 감사 목적으로 사용
관리자(Owner) 전용 함수
| 함수 | 기능 |
| addClaimTopic | 새로운 Claim Topic 추가 |
| removeClaimTopic | 기존 Claim Topic 제거 |
Compliance Interface
: ERC-3643에서 토큰 전송·발행·소각의 규제 적합성을 판단하는 표준 인터페이스이다. 토큰 거래가 규제 요건을 충족하는지 사전·사후 판단한다.
이벤트(Event)
| 이벤트 | 발생시점 | 의미 |
| TokenBound(address _token) | 토큰이 규정 준수 계약에 바인딩 되었을 때 발행 | 해당 Compliance가 토큰 규제 담당 |
| TokenUnbound(address _token) | 토큰이 규정 준수 계약에서 바인딩 해제 되었을 때 발행 | 규제 적용 종료 |
토큰 바인딩 관리 함수
| 함수 | 기능 | 비고 |
| bindToken(address _token) | 특정 토큰을 Compliance에 등록 | 이후 전송은 규제 적용 |
| unbindToken(address _token) | 토큰 연결 해제 | 규제 적용 중단 |
상태 업데이트용 Hook 함수
(전송 허용 여부 판단X / 상태반영O) Hook 함수는 canTransfer 판단 이후에만 호출
| 함수 | 호출시점 | 용도 |
| transferred(address _from, address _to, uint256 _amount) | 토큰이 한주소에서 다른주소로 전송된 후 | 보유량 · 전송기록 갱신 |
| created(address _to, uint256 _amount) | 토큰이 발행(mint) 되었을 때 | 총 발행량 · 보유한도 관리 |
| destroyed(address _from, uint256 _amount) | 토큰이 소각(burn) 되었을 때 | 유통량 감소 반영 |
조회(Read-only) 함수
| 함수 | 반환값 | 의미 |
| isTokenAgent(address _agentAddress) | bool | 해당주소가 Token Agent 인지 여부 반환 |
| isTokenBound(address _token) | bool | 토큰이 연결되어 있는지 여부 |
| canTransfer(address _from, address _to, uint256 _amount) | bool | 전송 가능 여부 최종 판단 |
T-REX Factory Interface
: 컴플라이언스 토큰에 필요한 모든 인프라를 단일 트랜잭션으로 배포하기 위한 표준 인터페이스이다. 규제 준수 증권형 토큰(STO) 전체 세트를 단일 트랜잭션으로 배포가 목적이다.
Struct – TokenDetails: 토큰 및 관련 컨트랙트 배포에 필요한 정보를 담는 구조체
struct TokenDetails {
address owner; // 배포 후 모든 컨트랙트의 소유자가 될 주소
string name; // 토큰 이름
string symbol; // 토큰 심볼
uint8 decimals; // 토큰 소수점 자리수 (0~18)
address irs; // Identity Registry Storage 주소
address ONCHAINID; // 토큰의 ONCHAINID 주소
address[] irAgents; // Identity Registry의 에이전트 주소 목록
address[] tokenAgents; // 토큰 컨트랙트의 에이전트 주소 목록
address[] complianceModules; // 추가할 컴플라이언스 모듈 주소 목록
bytes[] complianceSettings; // 각 컴플라이언스 모듈에 대한 설정 값 (ABI 인코딩)
}
Struct – ClaimDetails: KYC/AML 등 클레임 기반 컴플라이언스 조건을 정의하는 구조체
struct ClaimDetails {
uint256[] claimTopics; // 필수 클레임 토픽 ID 목록
address[] issuers; // 신뢰된 클레임 발급자(Trusted Issuer) 주소 목록
uint256[][] issuerClaims; // 각 발급자가 발급할 수 있는 클레임 토픽 목록
}
이벤트 (Events)
| 이벤트 | 의미 |
| Deployed(address) | 팩토리를 통해 컨트랙트가 배포됨 |
| IdFactorySet(address) | Identity Factory 주소설정 |
| ImplementationAuthoritySet(address) | 구현체 관리 컨트랙트 변경 |
| TREXSuiteDeployed | T-REX 토큰 전체 세트가 성공적으로 배포 |
설정
| 함수 | 설명 | 권한 |
| setImplementationAuthority(address _implementationAuthority) | 프록시 구현체 관리 주소 설정 | Factory Owner |
| setIdFactory(address _idFactory) | ONCHAINID 생성용 팩토리 설정 | Factory Owner |
배포
| 함수 | 설명 |
| deployTREXSuite | T-REX 토큰 + IR + IRS + CTR + TIR + Compliance 전체 배포 |
| 배포방식 | CREATE2 사용 (결정론적주소생성) |
| 입력값 | salt, TokenDetails, ClaimDetails |
| 특징 | 단일 트랜잭션으로 STO 인프라완성 |
function deployTREXSuite(
string memory _salt,
TokenDetails calldata _tokenDetails,
ClaimDetails calldata _claimDetails
) external;
운영 및 조회
| 함수 | 기능 |
| recoverContractOwnership(address _contract, address _newOwner) | 배포된 컨트랙트 소유권 이전 |
| getImplementationAuthority() → address | 현재 설정된 Implementation Authority 주소 반환 |
| getIdFactory() → address | 현재 설정된 Identity Factory 주소 반환 |
| getToken(string _salt) → address | 특정 _salt 값으로 배포된 T-REX 토큰 주소반환 |
Gateway Interface
: 실제 토큰 및 관련 계약을 배포하는 역할은 Factory, 누가, 어떤 조건으로, 얼마의 비용을 내고 배포할 수 있는지를 관리하는 역할은 Gateway가 담당한다.
규제형 토큰(STO, RWA 등)을 플랫폼 단위로 안전하게 배포하기 위한 핵심 컴포넌트이다.
Struct – TokenDetails: T-REX 토큰과 관련된 기본 설정 정보를 담는 구조체
struct TokenDetails {
address owner;
string name;
string symbol;
uint8 decimals;
address irs; // Identity Registry Storage 주소
address ONCHAINID; // 토큰 자산의 온체인 아이덴티티
address[] irAgents; // Identity Registry 관리자(에이전트)
address[] tokenAgents; // 토큰 관리자(발행, 전송 제어 가능)
address[] complianceModules; // 적용할 컴플라이언스 모듈 목록
bytes[] complianceSettings; // 각 모듈에 대한 설정값
}
ClaimDetails: 토큰 전송 및 보유 조건을 정의하는 클레임(Claim) 관련 정보
struct ClaimDetails {
uint256[] claimTopics; // 요구되는 클레임 토픽 (ex. KYC, AML)
address[] issuers; // 신뢰된 클레임 발급자 주소
uint256[][] issuerClaims; // 각 발급자가 발급 가능한 클레임 종류
}
Fee: 토큰 배포 시 필요한 수수료 정보
struct Fee {
uint256 fee; // 배포 비용
address feeToken; // 수수료로 사용할 토큰 주소
address feeCollector; // 수수료 수령자
}
T-REX Gateway 이벤트 (Events)
| 이벤트명 | 설명 |
| FactorySet | Gateway가 사용하는 T-REX Factory 주소 변경 |
| PublicDeploymentStatusSet | 퍼블릭 배포 허용 여부 변경 |
| DeploymentFeeSet | 배포 수수료 조건(금액·토큰·수령자) 설정 |
| DeploymentFeeEnabled | 배포 수수료 기능 활성화/비활성화 |
| DeployerAdded | 승인된 배포자(Deployer) 추가 |
| DeployerRemoved | 승인된 배포자 제거 |
| FeeDiscountApplied | 특정 배포자에 수수료 할인 적용 |
| GatewaySuiteDeploymentProcessed | T-REX Suite 배포 완료 기록 |
관리 기능 (Management Functions)
- Factory 관리
| 함수명 | 설명 |
| setFactory(address) | Gateway가 사용할 Factory 계약 설정 |
| getFactory() | 현재 연결된 Factory 주소 조회 |
| transferFactoryOwnership(address) | Factory 계약의 소유권 이전 |
- 퍼블릭 배포 제어
| 함수명 | 설명 |
| setPublicDeploymentStatus(bool) | 누구나 배포 가능할지 여부 설정 |
| getPublicDeploymentStatus() | 퍼블릭 배포 허용 상태 조회 |
- 배포 수수료 관리 (Deployment Fee)
| 함수명 | 설명 |
| enableDeploymentFee(bool) | 배포 수수료 사용 여부 설정 |
| setDeploymentFee(uint256, address, address) | 수수료 금액 / 결제 토큰 / 수령자 설정 |
| getDeploymentFee() | 현재 수수료 설정 조회 |
| isDeploymentFeeEnabled() | 수수료 활성화 여부 확인 |
| calculateFee(address) | 배포자별 할인 적용 후 실제 수수료 계산 |
Deployer(배포자) 관리
배포자 추가 / 제거
| 함수명 | 설명 |
| addDeployer(address) | 승인된 배포자 추가 |
| batchAddDeployer(address[]) | 배포자 일괄 추가 |
| removeDeployer(address) | 승인된 배포자 제거 |
| batchRemoveDeployer(address[]) | 배포자 일괄 제거 |