> ## 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.

# 민팅 거버넌스 (GovMasterMinter 및 GovMinter)

## 목적 및 범위

StableNet은 기본 스테이블코인의 민팅 및 소각 관리를 위한 2단계 거버넌스 시스템을 구현합니다. 이 아키텍처는 **승인**(누가 민터가 될 수 있는지)과 **실행**(민트/소각 작업 수행)을 명확히 분리합니다:

* **GovMasterMinter**: 민터 엔티티를 승인하고 관리합니다
* **GovMinter**: 집단 투표를 통해 민트/소각 작업을 실행합니다

이 문서는 두 거버넌스 컨트랙트 간의 아키텍처, 책임, 저장소 상호 작용, 실행 흐름을 설명합니다. 민터가 민트/소각 작업을 수행할 때 따르는 운영 프로토콜은 [민팅 및 번 프로토콜](/ko/governance-system/5.6-mint-and-burn-protocol)을 참조하세요. 민팅된 토큰이 체인 상에서 어떻게 표현되는지는 [NativeCoinAdapter 컨트랙트](/ko/governance-system/5.2-nativecoinadapter-contract)를 참조하세요. 모든 시스템 컨트랙트에 대한 개요는 [시스템 컨트랙트 개요](/ko/governance-system/5.1-system-contracts-overview)를 참조하세요.

## 2단계 민팅 아키텍처

민팅 거버넌스는 유연성과 보안을 동시에 만족시키기 위해 **계층적 승인 모델**을 사용합니다. 이 아키텍처는 고정 주소의 두 시스템 컨트랙트와 `NativeCoinAdapter`의 저장소 슬롯을 통해 구현됩니다:

**주요 설계 원칙**:

| Layer         | Contract Address | Members               | Operations                                    |
| ------------- | ---------------- | --------------------- | --------------------------------------------- |
| Authorization | `0x0000...1002`  | Master minter members | `configureMinter()`, `removeMinter()`         |
| Execution     | `0x0000...1003`  | Minter members        | `mint()`, `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` 구조를 통해 제네시스에서 초기화됩니다:

| Parameter            | Type         | Purpose               | Example Value                     | Genesis Location                                      |
| -------------------- | ------------ | --------------------- | --------------------------------- | ----------------------------------------------------- |
| `members`            | address list | Master minter 거버넌스 멤버 | `"0xaa5f...4697"`                 | `params.GovMasterMinter.Params["members"]`            |
| `quorum`             | uint         | 제안 승인에 필요한 최소 투표 수    | `"1"`                             | `params.GovMasterMinter.Params["quorum"]`             |
| `expiry`             | uint         | 제안 만료 시간 (초)          | `"604800"`                        | `params.GovMasterMinter.Params["expiry"]`             |
| `memberVersion`      | uint         | 멤버십 버전                | `"1"`                             | `params.GovMasterMinter.Params["memberVersion"]`      |
| `fiatToken`          | address      | NativeCoinAdapter 주소  | `"0x0000...1000"`                 | `params.GovMasterMinter.Params["fiatToken"]`          |
| `minters`            | address list | 초기 승인 민터 목록           | `"0x0000...1003"`                 | `params.GovMasterMinter.Params["minters"]`            |
| `maxMinterAllowance` | uint256      | 민터당 최대 allowance      | `"10000000000000000000000000000"` | `params.GovMasterMinter.Params["maxMinterAllowance"]` |
| `maxProposals`       | uint         | 동시 활성 제안 수 상한         | `"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
```

**저장소 접근 패턴**:

| Operation          | Slot | Key Derivation      | Value Type |         |           |
| ------------------ | ---- | ------------------- | ---------- | ------- | --------- |
| Read master minter | 0x0  | Direct slot access  | `address`  |         |           |
| Check minter       | 0x1  | \`keccak256(address |            | slot)\` | `bool`    |
| Read allowance     | 0x2  | \`keccak256(address |            | slot)\` | `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` 구조를 통해 제네시스에서 구성됩니다:

| Parameter       | Type         | Purpose              | Example Value     | Genesis Location                           |
| --------------- | ------------ | -------------------- | ----------------- | ------------------------------------------ |
| `members`       | address list | 민터 운영 멤버             | `"0xaa5f...4697"` | `params.GovMinter.Params["members"]`       |
| `quorum`        | uint         | 민트/소각 실행 최소 승인 수     | `"1"`             | `params.GovMinter.Params["quorum"]`        |
| `expiry`        | uint         | 제안 만료 시간             | `"604800"`        | `params.GovMinter.Params["expiry"]`        |
| `memberVersion` | uint         | 멤버 버전                | `"1"`             | `params.GovMinter.Params["memberVersion"]` |
| `fiatToken`     | address      | NativeCoinAdapter 주소 | `"0x0000...1000"` | `params.GovMinter.Params["fiatToken"]`     |
| `maxProposals`  | uint         | 동시 활성 제안 수           | `"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 Size | Recommended Quorum | Rationale  |
| ------------ | ------------------ | ---------- |
| 1 member     | 1                  | 개발·테스트     |
| 2–4 members  | 2                  | 단순 과반      |
| 5+ members   | ⌈(n/2) + 1⌉        | BFT 관점 안전성 |

프로덕션 환경에서는 과반 또는 2/3 이상 쿼럼 구성이 권장됩니다.

### 멤버 버전 관리

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

### 제안 제한

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

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

| Relationship                   | Storage/Code Location        | Purpose          |
| ------------------------------ | ---------------------------- | ---------------- |
| GovMasterMinter → Slot 0x0     | `statedb.GetState(nca, 0x0)` | Master minter 검증 |
| GovMinter → Slot 0x1           | `_minters[address]`          | 민터 승인 확인         |
| GovMinter → Slot 0x2           | `_minterAllowed[address]`    | allowance 확인     |
| NativeCoinAdapter → Precompile | Native balance update        | 잔액 수정            |
| Genesis → Storage              | `InjectGovMasterMinter()`    | 초기 상태 설정         |

## 요약

2단계 민팅 거버넌스 아키텍처는 다음을 보장합니다:

| Feature  | Benefit               |
| -------- | --------------------- |
| 승인·실행 분리 | 권한 집중 방지              |
| 다중 승인    | 단일 주체 오남용 차단          |
| 확장성      | 다양한 민터 유형 수용          |
| 투명성      | 모든 작업 온체인 기록          |
| 보안성      | allowance 기반 발행 한도 통제 |

이 설계는 StableNet이 **1:1 법정화폐 페그**를 유지하면서도, 프로토콜 수준의 탈중앙화와 운영 통제를 동시에 달성하도록 합니다.