메인 콘텐츠로 건너뛰기

Documentation Index

Fetch the complete documentation index at: https://docs.stablenet.network/llms.txt

Use this file to discover all available pages before exploring further.

​
목적 및 범위

StableNet은 기본 스테이블코인의 민팅 및 소각 관리를 위한 2단계 거버넌스 시스템을 구현합니다. 이 아키텍처는 승인(누가 민터가 될 수 있는지)과 실행(민트/소각 작업 수행)을 명확히 분리합니다:
  • GovMasterMinter: 민터 엔티티를 승인하고 관리합니다
  • GovMinter: 집단 투표를 통해 민트/소각 작업을 실행합니다
이 문서는 두 거버넌스 컨트랙트 간의 아키텍처, 책임, 저장소 상호 작용, 실행 흐름을 설명합니다. 민터가 민트/소각 작업을 수행할 때 따르는 운영 프로토콜은 민팅 및 번 프로토콜을 참조하세요. 민팅된 토큰이 체인 상에서 어떻게 표현되는지는 NativeCoinAdapter 컨트랙트를 참조하세요. 모든 시스템 컨트랙트에 대한 개요는 시스템 컨트랙트 개요를 참조하세요.

​
2단계 민팅 아키텍처

민팅 거버넌스는 유연성과 보안을 동시에 만족시키기 위해 계층적 승인 모델을 사용합니다. 이 아키텍처는 고정 주소의 두 시스템 컨트랙트와 NativeCoinAdapter의 저장소 슬롯을 통해 구현됩니다: 주요 설계 원칙:
LayerContract AddressMembersOperations
Authorization0x0000...1002Master minter membersconfigureMinter(), removeMinter()
Execution0x0000...1003Minter membersmint(), burn() (quorum approval required)
이 분리는 NativeCoinAdapter 컨트랙트의 접근 제어 수정자에 의해 강제됩니다:
  • onlyMasterMinter: msg.sender == masterMinter 조건을 검증합니다 (슬롯 0x0)
  • onlyMinters: _minters[msg.sender] == true 조건을 검증합니다 (슬롯 0x1)
  • Allowance 확인: _minterAllowed[msg.sender] >= amount 조건을 검증합니다 (슬롯 0x2)

​
GovMasterMinter 컨트랙트

​
컨트랙트 식별 및 배포

GovMasterMinter는 제네시스에서 시스템 컨트랙트로 배포됩니다:
  • 주소: 0x0000000000000000000000000000000000001002
  • 배포 방식: 제네시스 블록 직접 주입 (소유자 없음)
  • 업그레이드 방식: 하드 포크를 통해서만 교체 가능
  • 버전: 제네시스 구성에 명시됨 (예: "v1")

​
책임

GovMasterMinter는 민팅 작업을 위한 승인 레이어 역할을 합니다:
  1. 민터 등록: 특정 주소를 민터로 승인
  2. 민터 제거: 기존 민터의 권한 철회
  3. Allowance 관리: 민터당 최대 민팅/소각 허용량 설정
  4. 확장성 확보: 향후 브리지 기반 민터, 시스템 민터 등 다양한 타입의 민터 승인 가능
이 구조는 Circle의 FiatToken 계열에서 사용하는 masterMinter 개념을 온체인 거버넌스 모델로 일반화한 것입니다.

​
제네시스 매개변수

GovMasterMinter는 params.ChainConfig.Anzeon.SystemContracts.GovMasterMinter 구조를 통해 제네시스에서 초기화됩니다:
ParameterTypePurposeExample ValueGenesis Location
membersaddress listMaster minter 거버넌스 멤버"0xaa5f...4697"params.GovMasterMinter.Params["members"]
quorumuint제안 승인에 필요한 최소 투표 수"1"params.GovMasterMinter.Params["quorum"]
expiryuint제안 만료 시간 (초)"604800"params.GovMasterMinter.Params["expiry"]
memberVersionuint멤버십 버전"1"params.GovMasterMinter.Params["memberVersion"]
fiatTokenaddressNativeCoinAdapter 주소"0x0000...1000"params.GovMasterMinter.Params["fiatToken"]
mintersaddress list초기 승인 민터 목록"0x0000...1003"params.GovMasterMinter.Params["minters"]
maxMinterAllowanceuint256민터당 최대 allowance"10000000000000000000000000000"params.GovMasterMinter.Params["maxMinterAllowance"]
maxProposalsuint동시 활성 제안 수 상한"3"params.GovMasterMinter.Params["maxProposals"]

​
초기화 시퀀스

  1. core.SetupGenesisBlock()이 core.InjectContracts()를 호출합니다
  2. InjectContracts()가 systemcontracts.InjectGovMasterMinter()를 호출합니다
  3. InjectGovMasterMinter()는 NativeCoinAdapter 저장소를 직접 초기화합니다:
    • 슬롯 0x0: masterMinter = 0x0000...1002
    • 슬롯 0x1: 각 민터 주소에 대해 _minters[address] = true
    • 슬롯 0x2: 각 민터 주소에 대해 _minterAllowed[address] = maxMinterAllowance

​
저장소 레이아웃

GovMasterMinter는 자체 저장소가 아니라 NativeCoinAdapter의 저장소 슬롯을 통해 상태를 관리합니다. 슬롯 정의는 systemcontracts/coin_adapter.go에 상수로 선언되어 있습니다: 
SLOT_COIN_ADAPTER_MASTER_MINTER = "0x0" // address masterMinter
SLOT_COIN_ADAPTER_MINTERS = "0x1" // mapping(address => bool) _minters
SLOT_COIN_ADAPTER_MINTER_ALLOWED = "0x2" // mapping(address => uint256) _minterAllowed
저장소 접근 패턴:
OperationSlotKey DerivationValue Type
Read master minter0x0Direct slot accessaddress
Check minter0x1`keccak256(addressslot)`bool
Read allowance0x2`keccak256(addressslot)`uint256
매핑 슬롯 계산은 Solidity 저장소 레이아웃 규칙을 그대로 따릅니다.

​
NativeCoinAdapter와의 상호 작용

GovMasterMinter는 NativeCoinAdapter의 권한 관리 함수만 호출할 수 있습니다. 이 함수들은 onlyMasterMinter 수정자로 보호됩니다. 함수 시그니처:
  • configureMinter(address minter, uint256 minterAllowedAmount) external onlyMasterMinter
  • removeMinter(address minter) external onlyMasterMinter
접근 제어 흐름:
  1. 거버넌스 제안이 쿼럼을 충족하면 실행 단계에서 트랜잭션 생성
  2. msg.sender는 GovMasterMinter 컨트랙트 주소
  3. NativeCoinAdapter가 슬롯 0x0의 masterMinter와 msg.sender를 비교
  4. 일치 시 저장소 슬롯 0x1, 0x2가 갱신되고 이벤트 발생

​
GovMinter 컨트랙트

​
컨트랙트 식별 및 배포

GovMinter는 제네시스에서 시스템 컨트랙트로 배포됩니다:
  • 주소: 0x0000000000000000000000000000000000001003
  • 배포 방식: 제네시스 블록 직접 주입
  • 업그레이드 방식: 하드 포크만 허용
  • 버전: 제네시스 구성에 지정됨

​
책임

GovMinter는 민팅 작업의 실행 레이어입니다:
  1. 민트 실행: 네이티브 스테이블코인 발행
  2. 소각 실행: 네이티브 스테이블코인 소각
  3. 오라클 역할: 오프체인 법정화폐 예치/인출 검증
  4. 멤버 거버넌스: 자체 멤버 추가·제거
  5. 다중 승인 조정: 민트/소각 제안의 집단 승인 관리
단일 멤버는 어떠한 경우에도 단독으로 민팅 또는 소각을 실행할 수 없습니다.

​
제네시스 매개변수

GovMinter는 params.ChainConfig.Anzeon.SystemContracts.GovMinter 구조를 통해 제네시스에서 구성됩니다:
ParameterTypePurposeExample ValueGenesis Location
membersaddress list민터 운영 멤버"0xaa5f...4697"params.GovMinter.Params["members"]
quorumuint민트/소각 실행 최소 승인 수"1"params.GovMinter.Params["quorum"]
expiryuint제안 만료 시간"604800"params.GovMinter.Params["expiry"]
memberVersionuint멤버 버전"1"params.GovMinter.Params["memberVersion"]
fiatTokenaddressNativeCoinAdapter 주소"0x0000...1000"params.GovMinter.Params["fiatToken"]
maxProposalsuint동시 활성 제안 수"3"params.GovMinter.Params["maxProposals"]

​
초기화 전제 조건

GovMinter는 실행되기 전에 반드시 민터로 승인되어야 합니다:
  1. GovMasterMinter의 minters 목록에 GovMinter 주소 포함
  2. GovMasterMinter가 GovMinter에 대한 allowance 설정
  3. 제네시스 중 InjectGovMasterMinter()가 이를 NativeCoinAdapter 슬롯 0x1, 0x2에 기록
이 조건이 충족되지 않으면 모든 mint() / burn() 호출은 onlyMinters 단계에서 거부됩니다.

​
민트 및 소각 워크플로우

민트 및 소각은 잔액 변경 전에 다음 검증 체인을 통과해야 합니다: 접근 제어 검증 체인:
  1. 민터 승인 확인: _minters[msg.sender] == true
  2. Allowance 확인: _minterAllowed[msg.sender] >= amount
  3. 잔액 수정: 네이티브 코인 프리컴파일을 통해 StateDB 잔액 직접 수정
  4. Allowance 차감: _minterAllowed[msg.sender] -= amount
함수 시그니처:
  • mint(address to, uint256 amount) external onlyMinters
  • burn(uint256 amount) external onlyMinters

​
멤버 자체 거버넌스

GovMinter는 자체 멤버십을 관리할 수 있습니다. 이는 운영 유연성을 제공하지만, GovMasterMinter가 민터 승인을 철회할 경우 GovMinter 전체의 실행 권한은 즉시 무효화됩니다.

​
거버넌스 메커니즘

GovMasterMinter와 GovMinter는 공통의 GovBase 패턴을 공유합니다.

​
투표 프로세스

제안 라이프사이클:
  1. 생성: 멤버가 제안 생성
  2. 투표: 승인 또는 거절 투표
  3. 쿼럼 도달: quorum 이상 승인
  4. 실행: 만료 전 실행
  5. 만료: 쿼럼 미달 시 자동 폐기

​
쿼럼 요구사항

Network SizeRecommended QuorumRationale
1 member1개발·테스트
2–4 members2단순 과반
5+ members⌈(n/2) + 1⌉BFT 관점 안전성
프로덕션 환경에서는 과반 또는 2/3 이상 쿼럼 구성이 권장됩니다.

​
멤버 버전 관리

memberVersion은 멤버 변경 시 증가하며, 이전 버전에서 생성된 제안의 실행을 차단하여 재생 공격을 방지합니다.

​
제안 제한

maxProposals는 동시 제안 수를 제한하여 거버넌스 DoS를 방지합니다.

​
시스템 컨트랙트와의 통합

RelationshipStorage/Code LocationPurpose
GovMasterMinter → Slot 0x0statedb.GetState(nca, 0x0)Master minter 검증
GovMinter → Slot 0x1_minters[address]민터 승인 확인
GovMinter → Slot 0x2_minterAllowed[address]allowance 확인
NativeCoinAdapter → PrecompileNative balance update잔액 수정
Genesis → StorageInjectGovMasterMinter()초기 상태 설정

​
요약

2단계 민팅 거버넌스 아키텍처는 다음을 보장합니다:
FeatureBenefit
승인·실행 분리권한 집중 방지
다중 승인단일 주체 오남용 차단
확장성다양한 민터 유형 수용
투명성모든 작업 온체인 기록
보안성allowance 기반 발행 한도 통제
이 설계는 StableNet이 1:1 법정화폐 페그를 유지하면서도, 프로토콜 수준의 탈중앙화와 운영 통제를 동시에 달성하도록 합니다.