ERC-3643 프로토콜 소개
목차
1. 한눈에 보기
ERC-3643은 신원 확인과 컴플라이언스 검사를 갖춘 ERC-20 발행 프레임워크입니다. 토큰 보유 자격, 전송 허용 여부, 권한자의 동결·강제 전송·자산 복구 방식과 일관된 구현 업그레이드 방식을 정의합니다.
| 구분 | 일반 ERC-20 | ERC-3643 |
|---|---|---|
| 수신 가능 대상 | 모든 주소 | 검증된 신원만 |
| 전송 | 비즈니스 규칙에 따른 거부 불가 | 컴플라이언스 모듈이 거부 가능 |
| 동결·강제 전송·지갑 복구 | 지원 안 함 | 지원 |
| 규칙 변경 | 일반적으로 별도 컨트랙트 필요 | 설정 또는 모듈 변경 |
2. 다섯 가지 핵심 개념
| 개념 | 의미 |
|---|---|
| ONCHAINID | 지갑과 분리된 온체인 사용자 신원. 하나의 신원에 여러 지갑 연결 가능 |
| Claim | 신원에 연결된 서명된 자격 증명 |
| Claim 발급자 | Claim 발급·취소 권한을 가진 기관 컨트랙트 |
| Identity Registry | 주소가 적격 투자자에게 속하는지 판단하는 사람 검사 |
| Compliance module | 거래가 규칙을 준수하는지 판단하는 거래 검사 |
두 게이트를 모두 통과해야 합니다. KYC 승인 투자자도 보유 한도 등 다른 컴플라이언스 규칙에 따라 거부될 수 있습니다.
3. 전체 컨트랙트 아키텍처
3.1 네 개 레이어
| 레이어 | 인스턴스 수 | 목적 |
|---|---|---|
| 플랫폼 | 일반적으로 체인당 하나 | 발행 접근, 신원 생성, 공통 업그레이드 |
| Suite | 자산당 6개 컨트랙트 | 잔액, 신원, 컴플라이언스, 거버넌스 |
| ONCHAINID | 사용자당 하나 | 키와 Claim |
| 컴플라이언스 모듈 | 규칙별 배포 후 재사용 | 실행 가능한 거래 규칙 |
각 책임을 독립적으로 발전시키기 위해 컨트랙트를 분리했습니다. Token은 원장, IR·IRS·CTR·TIR은 신원 자격, MC는 거래 규칙을 관리합니다. Proxy 주소는 유지됩니다. Proxy가 상태를 저장하고 구현체가 로직을 제공합니다.
3.2 세 가지 업그레이드 방식
| 대상 | 방식 | 업그레이드 진입점 | 범위 |
|---|---|---|---|
| 6개 TREX 컨트랙트 | IA 포인터 Proxy | TREX IA | 해당 IA를 계속 참조하는 자산 |
| ONCHAINID | ONCHAINID IA | updateImplementation | 해당 IA를 참조하는 신원 |
| 컴플라이언스 모듈 | ERC1967 + UUPS | 모듈 Owner의 upgradeTo | 해당 모듈에 연결된 자산 |
4. 컨트랙트 책임과 온체인 상태
체인에는 비즈니스 상태와 규칙 설정을 저장합니다. 신원 문서 이미지, 이름, 신분증 번호 등 민감 데이터는 오프체인 KYC 시스템에 보관합니다. 체인에는 자격 유형, 보유량, 전송 적격성 같은 판정 결과를 기록합니다.
4.1 체인 공통 플랫폼 컨트랙트
| 컨트랙트 | 목적 | 주요 온체인 상태 | 중요 제한 |
|---|---|---|---|
TREXImplementationAuthority | RWA 자산이 사용할 구현 버전 선택 | 현재 버전과 버전별 6개 구현 주소 | 6개 구현을 함께 등록해야 함 |
IAFactory | 자산용 독립 업그레이드 관리 기관 생성 | 독립 관리 기관을 부여받은 자산 | 글로벌 관리 기관 관리자만 생성 가능 |
TREXFactory | 완전한 RWA Suite 배포 및 초기화 | 사용한 salt, 관리 기관, 신원 팩토리, 허가된 배포자 | 초기 설정은 Topic·발급자·Agent 각각 최대 5개, 모듈 작업 30회 |
TREXGateway | 발급자, 공개 발행, 수수료, 할인 관리 | 공개 설정, 수수료 토큰·금액·수신자, 발급자 목록, 할인, 관리자 | 배치당 최대 5개 Suite |
IdFactory | 온체인 신원 프로필과 지갑 매핑 생성 | 지갑→신원 및 신원→지갑 매핑 | 신원당 최대 101개 지갑 |
ONCHAINID ImplementationAuthority | 신원 구현 버전 선택 | 현재 구현과 업그레이드 관리 기관 | 변경 시 참조 중인 모든 신원에 영향 |
ONCHAINID Gateway | 플랫폼 승인 서명으로 사용자가 신원을 생성하도록 지원 | 승인된 서명자와 취소된 서명 | 일반적으로 데모 핵심 흐름 밖 |
4.2 RWA 자산별 6개 핵심 컨트랙트
| 컨트랙트 | 목적 | 주요 온체인 상태 | 중요 제한 |
|---|---|---|---|
Token | 원장, 전송, Mint, Burn, 일시 중지, 동결, 강제 전송, 지갑 복구 | 잔액, Allowance, 공급량, 메타데이터, 중지 상태, 전체·부분 동결, 연결된 IR/MC, Owner, Agent | decimals는 0~18 |
IdentityRegistry | 전송 또는 Mint 전 수신자 적격성 확인 | CTR·TIR·IRS 참조와 Registry 관리자 | 요건과 발급자가 늘수록 Gas 비용 증가 |
IdentityRegistryStorage | 지갑 신원과 국가 저장, 공유 가능 | 지갑 → 신원·국가 및 스토리지를 사용하는 Registry | 최대 300개 IdentityRegistry, 지갑당 한 레코드 |
ClaimTopicsRegistry | 자산 보유에 필요한 자격 정의 | 필수 Topic과 관리자 | 고유 Topic 최대 15개 |
TrustedIssuersRegistry | 허용 발급자와 Topic 정의 | 발급자와 자격 유형 | 발급자 최대 50개, 발급자별 Topic 최대 15개 |
ModularCompliance | 금액, 국가, 락업 등 거래 규칙 적용 | 연결된 Token, 부착 모듈, 관리자 | Token 하나와 최대 25개 모듈 |
4.3 사용자 신원과 규칙 모듈
| 컨트랙트 | 목적 | 주요 온체인 상태 |
|---|---|---|
ONCHAINID / Identity | 사용자당 재사용 가능한 온체인 신원 하나. 지갑은 교체 가능한 도구 | Management·Action·Claim 키와 수신한 Claim |
ClaimIssuer | 증명을 발급·취소하는 KYC/AML 기관 컨트랙트 | 신원 키와 취소된 서명 |
ModuleProxy | 단일 비즈니스 규칙의 고정 진입점 | 현재 구현과 자산별 파라미터 |
소스 위치: 플랫폼 컨트랙트는 contracts/factory/와 proxy/authority/, 자산 컨트랙트는 token/·registry/·compliance/modular/에 있으며 신원 기능은 @onchain-id/solidity에서 제공합니다.
5. 컨트랙트 상호작용
5.1 의존 관계
5.3 발행
Gateway salt는 일반적으로 Owner 주소의 16진수 표현과 Token 이름을 조합합니다. 수수료를 활성화하면 수수료 토큰을 먼저 approve해야 합니다.
5.4 투자자 온보딩: 신원, KYC 서명, 온체인 Claim
온보딩은 신원 컨트랙트 생성, 자격 서명, Claim 제출, 자산 측 등록의 네 단계로 구성됩니다. 각 단계를 명확히 구분합니다.
- ONCHAINID 생성은 온체인 트랜잭션이며 투자자 신원 컨트랙트를 배포합니다.
- ClaimSigner KYC 서명은 오프체인에서 생성되며 트랜잭션과 Gas 비용이 없습니다.
addClaim은 온체인 트랜잭션이며 ClaimSigner 서명과 KYC 판정 결과를 투자자의 ONCHAINID에 저장합니다.
5.4.1 운영 흐름: ONCHAINID Gateway를 통한 셀프서비스 신원 생성
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에 지갑·신원·국가 기록 |
| 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을 제출하면 신원 컨트랙트가 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 | 참조 중인 모든 신원 |
| Compliance module | Module owner → upgradeTo | 해당 모듈에 연결된 MC |
6. 권한과 멀티시그
6.1 네 가지 권한 모델
| 모델 | 인증 | 목적 | 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 연결과 신원 마스터 데이터 기록 | 소유권 모델을 먼저 확립 |
| CTR / TIR / MC | Owner | Topic, 발급자, 모듈, 파라미터 | 컴플라이언스 Safe + Timelock |
| Upgradeable Module | Module owner | UUPS 업그레이드 | Safe + Timelock |
| IdFactory | Owner | 신원 생성 | 플랫폼 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 권장 레이어와 세 가지 주의점
- IRS 소유권은 나머지 5개 컨트랙트와 별도로 이전됩니다.
recoverContractOwnership을 호출할 때까지 Factory에 남으며, 일반적으로 Gateway가 해당 Factory를 소유합니다. - 한 자산의 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 주소별로 분리되므로 모듈 하나를 여러 자산에 사용 가능 |
| 신원 재사용 | 발급자 공유로 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 참조 구현 / 단일 자산용 6개 비즈니스 컨트랙트 |
| ONCHAINID / Claim / Topic / 발급자 | 신원 컨트랙트 / 자격 증명 / 증명 유형 / 발급 기관 |
| IR / IRS / CTR / TIR / MC | 신원 레지스트리 / 신원 스토리지 / Topic 레지스트리 / 발급자 레지스트리 / 컴플라이언스 조정자 |
| Owner / Agent | 설정 거버넌스 권한 / 운영 권한 |
| Implementation Authority | 현재 Proxy 구현을 선택하는 버전 관리 기관 |
| TREXFactory / Gateway / IdFactory | 자산 팩토리 / 발행 접근 Gateway / 신원 팩토리 |