목적 및 범위
이 문서는 StableNet의 NativeCoinAdapter 시스템 컨트랙트에 대한 기술 문서를 제공합니다.NativeCoinAdapter는 체인의 네이티브 코인(가스 수수료에 사용됨)을 표준 ERC-20 인터페이스로 노출하여, ERC-20 토큰을 기대하는 기존 DApp·서비스와의 통합을 담당합니다. 거버넌스 시스템 전반과 민팅/소각 제어 방식은 시스템 컨트랙트 개요를, 검증자 관리 및 합의 세부사항은 Anzeon WBFT 합의 프로토콜을 참고하세요.
컨트랙트 배포 및 식별
NativeCoinAdapter는 고정 주소에 배포되고 체인 부트스트랩 중에 초기화되는 제네시스 시스템 컨트랙트입니다. 사용자 배포 컨트랙트와 달리 소유자가 없으며 하드 포크를 통해서만 업그레이드할 수 있어 탈중앙화 보장을 유지합니다.
컨트랙트는 통화 이름, 심볼, 소수점 및 초기 마스터 민터 구성을 포함한 매개변수로 제네시스 블록 생성 중에 초기화됩니다.
아키텍처 및 설계 원칙
이중 성격 잔액 모델
NativeCoinAdapter는 다음과 같은 고유한 이중 성격 잔액 모델을 구현합니다:- 중복 저장소 없음: 어댑터는 자체 저장소 슬롯에 잔액을 저장하지 않습니다. 모든 잔액 조회는 계정 상태의 네이티브 잔액 필드를 직접 참조합니다.
- 직접 상태 수정: 어댑터를 통한 전송 작업은 가스 수수료 지불이 수정하는 것과 동일한 네이티브 잔액을 수정하여 모든 잔액 변경 경로에서 일관성을 유지합니다.
- Allowance 격리: Allowance 매핑(
approve()/transferFrom()용)만 컨트랙트 저장소 trie에 저장됩니다. - 통합 잔액 뷰:
NativeCoinAdapter.balanceOf(address)는 항상 가스 계산에 사용되는 계정 네이티브 잔액과 정확히 동일한 값을 반환합니다.
저장소 레이아웃 및 상태 관리
컨트랙트 저장소 슬롯
NativeCoinAdapter는 네이티브 계정 상태에서 유도할 수 없는 데이터만을 추적하는 최소한의 저장소를 유지합니다:
어댑터 저장소는 네이티브 상태에서 추론할 수 없는 매핑만 포함하여, 전체 ERC20 기능을 유지하면서 저장소 오버헤드를 최소화합니다.
핵심 전송 작업
직접 전송 흐름
NativeCoinAdapter를 통한 전송은 다음 순서로 처리됩니다:- 블랙리스트 검증: 발신자와 수신자 모두 계정 Extra 필드의 블랙리스트 플래그를 확인합니다.
- 잔액 확인: 발신자의 네이티브 잔액을 조회합니다.
- 잔액 수정: 두 계정의 네이티브 잔액을 원자적으로 수정합니다.
- 저널 기록: 모든 상태 변경은 되돌리기를 위해 저널링됩니다.
- 이벤트 발생:
Transfer(from, to, amount)이벤트가 발생합니다.
Allowance 기반 transferFrom
transferFrom()은 표준 ERC20 위임 전송 패턴을 따릅니다:
- Allowance를 컨트랙트 저장소에서 조회합니다.
- 충분한 allowance가 있으면 감소시킵니다.
- 실제 잔액 전송은 네이티브 잔액을 직접 수정합니다.
Transfer이벤트를 발생시킵니다.
Allowance 시스템 구현
Allowance는 네이티브 상태에서 파생할 수 없으므로 전용 컨트랙트 저장소가 필요합니다.
Allowance 저장소는 Solidity 중첩 매핑 레이아웃을 따르며 keccak256 기반 슬롯 계산을 사용합니다.
민팅 및 소각 통합
NativeCoinAdapter는 네이티브 코인의 유일한 민팅·소각 인터페이스입니다. 이 기능은 GovMinter 및 GovMasterMinter가 승인한 주소로 제한됩니다.민팅/소각 제약
- 모든 민팅·소각은
mint()/burn()을 통해서만 수행됩니다. - 승인된 민터만 호출할 수 있습니다.
- 민터별 최대 allowance가 적용됩니다.
- 표준
Transfer이벤트와 전용Mint/Burn이벤트가 발생합니다. - 네이티브 잔액이 직접 수정됩니다.
이벤트 발생 및 감사 가능성
NativeCoinAdapter는 모든 네이티브 코인 이동에 대해 이벤트를 생성하여 완전한 추적성을 제공합니다.
이를 통해 모든 기본 코인 이동이 인덱싱·감사·프론트엔드 표시 대상이 됩니다.
블랙리스트 및 승인 플래그
NativeCoinAdapter는 계정 Extra 필드에 저장된 플래그와 연동됩니다.ERC20 및 FiatToken 확장 준수
NativeCoinAdapter는 표준 ERC20과 FiatTokenV2_2 확장을 모두 구현하여 기존 USDC기반 스테이블코인 인프라와 호환됩니다.StateDB 통합
NativeCoinAdapter는 StateDB와 직접 통합됩니다:- 잔액 조회 → 네이티브 잔액 직접 조회
- 잔액 수정 → AddBalance / SubBalance
- 저널링 → 트랜잭션 되돌리기 지원
- 플래그 확인 → Extra 필드 조회
- 이벤트 기록 → 영수증에 포함
StateObject 구조
제네시스 초기화
NativeCoinAdapter는 제네시스에서 다음 파라미터로 초기화됩니다:- 제네시스 블록에 컨트랙트 존재
- 초기 민터 및 allowance 설정
- 토큰 메타데이터 확정
- 이후 변경은 하드 포크만 가능
요약
NativeCoinAdapter는 다음을 실현합니다:- 제로 저장소 오버헤드 ERC20
- 모든 네이티브 코인 이동의 이벤트 추적
- 거버넌스 기반 민팅·소각
- 기존 스테이블코인 생태계와 완전 호환
- 프로토콜 수준 보안 및 정책 강제