목적 및 범위
이 문서는 StableNet의 NativeCoinAdapter 시스템 컨트랙트에 대한 기술 문서를 제공합니다.NativeCoinAdapter는 체인의 네이티브 코인(가스 수수료에 사용됨)을 표준 ERC-20 인터페이스로 노출하여, ERC-20 토큰을 기대하는 기존 DApp·서비스와의 통합을 담당합니다. 거버넌스 시스템 전반과 민팅/소각 제어 방식은 시스템 컨트랙트 개요를, 검증자 관리 및 합의 세부사항은 Anzeon WBFT 합의 프로토콜을 참고하세요.
컨트랙트 배포 및 식별
NativeCoinAdapter는 고정 주소에 배포되고 체인 부트스트랩 중에 초기화되는 제네시스 시스템 컨트랙트입니다. 사용자 배포 컨트랙트와 달리 소유자가 없으며 하드 포크를 통해서만 업그레이드할 수 있어 탈중앙화 보장을 유지합니다.| Property | Value |
|---|---|
| Contract Address | 0x0000000000000000000000000000000000001000 |
| Deployment Method | Genesis injection via InjectContracts |
| Upgrade Mechanism | Hard fork only |
| Owner | None (system contract) |
| Standard Compliance | ERC20, FiatTokenV2_2 |
아키텍처 및 설계 원칙
이중 성격 잔액 모델
NativeCoinAdapter는 다음과 같은 고유한 이중 성격 잔액 모델을 구현합니다:- 중복 저장소 없음: 어댑터는 자체 저장소 슬롯에 잔액을 저장하지 않습니다. 모든 잔액 조회는 계정 상태의 네이티브 잔액 필드를 직접 참조합니다.
- 직접 상태 수정: 어댑터를 통한 전송 작업은 가스 수수료 지불이 수정하는 것과 동일한 네이티브 잔액을 수정하여 모든 잔액 변경 경로에서 일관성을 유지합니다.
- Allowance 격리: Allowance 매핑(
approve()/transferFrom()용)만 컨트랙트 저장소 trie에 저장됩니다. - 통합 잔액 뷰:
NativeCoinAdapter.balanceOf(address)는 항상 가스 계산에 사용되는 계정 네이티브 잔액과 정확히 동일한 값을 반환합니다.
저장소 레이아웃 및 상태 관리
컨트랙트 저장소 슬롯
NativeCoinAdapter는 네이티브 계정 상태에서 유도할 수 없는 데이터만을 추적하는 최소한의 저장소를 유지합니다:| Slot Type | Purpose | Storage Location |
|---|---|---|
| Allowances | mapping(address => mapping(address => uint256)) | Contract storage trie |
| Minter Allowances | Per-minter mint/burn limits | Contract storage trie |
| Metadata | Currency name, symbol, decimals | Contract storage trie |
| Balances | NOT STORED – references native balance directly | Account state |
핵심 전송 작업
직접 전송 흐름
NativeCoinAdapter를 통한 전송은 다음 순서로 처리됩니다:- 블랙리스트 검증: 발신자와 수신자 모두 계정 Extra 필드의 블랙리스트 플래그를 확인합니다.
- 잔액 확인: 발신자의 네이티브 잔액을 조회합니다.
- 잔액 수정: 두 계정의 네이티브 잔액을 원자적으로 수정합니다.
- 저널 기록: 모든 상태 변경은 되돌리기를 위해 저널링됩니다.
- 이벤트 발생:
Transfer(from, to, amount)이벤트가 발생합니다.
Allowance 기반 transferFrom
transferFrom()은 표준 ERC20 위임 전송 패턴을 따릅니다:
- Allowance를 컨트랙트 저장소에서 조회합니다.
- 충분한 allowance가 있으면 감소시킵니다.
- 실제 잔액 전송은 네이티브 잔액을 직접 수정합니다.
Transfer이벤트를 발생시킵니다.
Allowance 시스템 구현
Allowance는 네이티브 상태에서 파생할 수 없으므로 전용 컨트랙트 저장소가 필요합니다.| Operation | Storage Access | State Modification |
|---|---|---|
approve | WRITE | Allowance 설정 |
increaseAllowance | READ → WRITE | Allowance 증가 |
decreaseAllowance | READ → WRITE | Allowance 감소 |
transferFrom | READ (+ WRITE) | Allowance 차감 및 전송 |
allowance | READ | 조회만 수행 |
민팅 및 소각 통합
NativeCoinAdapter는 네이티브 코인의 유일한 민팅·소각 인터페이스입니다. 이 기능은 GovMinter 및 GovMasterMinter가 승인한 주소로 제한됩니다.민팅/소각 제약
- 모든 민팅·소각은
mint()/burn()을 통해서만 수행됩니다. - 승인된 민터만 호출할 수 있습니다.
- 민터별 최대 allowance가 적용됩니다.
- 표준
Transfer이벤트와 전용Mint/Burn이벤트가 발생합니다. - 네이티브 잔액이 직접 수정됩니다.
이벤트 발생 및 감사 가능성
NativeCoinAdapter는 모든 네이티브 코인 이동에 대해 이벤트를 생성하여 완전한 추적성을 제공합니다.| Event | Trigger |
|---|---|
Transfer | 모든 잔액 이동 |
Approval | Allowance 변경 |
Mint | 민팅 |
Burn | 소각 |
블랙리스트 및 승인 플래그
NativeCoinAdapter는 계정 Extra 필드에 저장된 플래그와 연동됩니다.| 계정 상태 | Extra 플래그 | 효과 |
|---|---|---|
| Blacklisted | 0x8000000000000000 | 전송·수신 차단 |
| Authorized | 0x4000000000000000 | 거버넌스 강제 gasTip 우회 허용 |
| Normal (기본) | 0x0 | 거버넌스 gasTip 강제 적용 |
ERC20 및 FiatToken 확장 준수
NativeCoinAdapter는 표준 ERC20과 FiatTokenV2_2 확장을 모두 구현하여 기존 USDC기반 스테이블코인 인프라와 호환됩니다.StateDB 통합
NativeCoinAdapter는 StateDB와 직접 통합됩니다:- 잔액 조회 → 네이티브 잔액 직접 조회
- 잔액 수정 → AddBalance / SubBalance
- 저널링 → 트랜잭션 되돌리기 지원
- 플래그 확인 → Extra 필드 조회
- 이벤트 기록 → 영수증에 포함
StateObject 구조
제네시스 초기화
NativeCoinAdapter는 제네시스에서 다음 파라미터로 초기화됩니다:- 제네시스 블록에 컨트랙트 존재
- 초기 민터 및 allowance 설정
- 토큰 메타데이터 확정
- 이후 변경은 하드 포크만 가능
요약
NativeCoinAdapter는 다음을 실현합니다:- 제로 저장소 오버헤드 ERC20
- 모든 네이티브 코인 이동의 이벤트 추적
- 거버넌스 기반 민팅·소각
- 기존 스테이블코인 생태계와 완전 호환
- 프로토콜 수준 보안 및 정책 강제