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

# NativeCoinAdapter 컨트랙트

## 목적 및 범위

이 문서는 StableNet의 NativeCoinAdapter 시스템 컨트랙트에 대한 기술 문서를 제공합니다.\
NativeCoinAdapter는 체인의 네이티브 코인(가스 수수료에 사용됨)을 표준 ERC-20 인터페이스로 노출하여, ERC-20 토큰을 기대하는 기존 DApp·서비스와의 통합을 담당합니다.

거버넌스 시스템 전반과 민팅/소각 제어 방식은 [시스템 컨트랙트 개요](/ko/governance-system/5.1-system-contracts-overview)를, 검증자 관리 및 합의 세부사항은 [Anzeon WBFT 합의 프로토콜](/ko/consensus-and-block-production/4.1-anzeon-wbft-consensus-protocol)을 참고하세요.

## 컨트랙트 배포 및 식별

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는 다음과 같은 고유한 이중 성격 잔액 모델을 구현합니다:

1. **중복 저장소 없음**: 어댑터는 자체 저장소 슬롯에 잔액을 저장하지 않습니다. 모든 잔액 조회는 계정 상태의 네이티브 잔액 필드를 직접 참조합니다.
2. **직접 상태 수정**: 어댑터를 통한 전송 작업은 가스 수수료 지불이 수정하는 것과 동일한 네이티브 잔액을 수정하여 모든 잔액 변경 경로에서 일관성을 유지합니다.
3. **Allowance 격리**: Allowance 매핑(`approve()`/`transferFrom()`용)만 컨트랙트 저장소 trie에 저장됩니다.
4. **통합 잔액 뷰**: `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         |

어댑터 저장소는 네이티브 상태에서 추론할 수 없는 매핑만 포함하여, 전체 ERC20 기능을 유지하면서 저장소 오버헤드를 최소화합니다.

## 핵심 전송 작업

### 직접 전송 흐름

NativeCoinAdapter를 통한 전송은 다음 순서로 처리됩니다:

1. **블랙리스트 검증**: 발신자와 수신자 모두 계정 Extra 필드의 블랙리스트 플래그를 확인합니다.
2. **잔액 확인**: 발신자의 네이티브 잔액을 조회합니다.
3. **잔액 수정**: 두 계정의 네이티브 잔액을 원자적으로 수정합니다.
4. **저널 기록**: 모든 상태 변경은 되돌리기를 위해 저널링됩니다.
5. **이벤트 발생**: `Transfer(from, to, amount)` 이벤트가 발생합니다.

### Allowance 기반 transferFrom

`transferFrom()`은 표준 ERC20 위임 전송 패턴을 따릅니다:

1. Allowance를 컨트랙트 저장소에서 조회합니다.
2. 충분한 allowance가 있으면 감소시킵니다.
3. 실제 잔액 전송은 네이티브 잔액을 직접 수정합니다.
4. `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           | 조회만 수행             |

Allowance 저장소는 Solidity 중첩 매핑 레이아웃을 따르며 keccak256 기반 슬롯 계산을 사용합니다.

## 민팅 및 소각 통합

NativeCoinAdapter는 네이티브 코인의 **유일한 민팅·소각 인터페이스**입니다. 이 기능은 GovMinter 및 GovMasterMinter가 승인한 주소로 제한됩니다.

### 민팅/소각 제약

1. 모든 민팅·소각은 `mint()` / `burn()`을 통해서만 수행됩니다.
2. 승인된 민터만 호출할 수 있습니다.
3. 민터별 최대 allowance가 적용됩니다.
4. 표준 `Transfer` 이벤트와 전용 `Mint` / `Burn` 이벤트가 발생합니다.
5. 네이티브 잔액이 직접 수정됩니다.

## 이벤트 발생 및 감사 가능성

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와 직접 통합됩니다:

1. 잔액 조회 → 네이티브 잔액 직접 조회
2. 잔액 수정 → AddBalance / SubBalance
3. 저널링 → 트랜잭션 되돌리기 지원
4. 플래그 확인 → Extra 필드 조회
5. 이벤트 기록 → 영수증에 포함

### StateObject 구조

```text theme={null}
stateObject {
  address
  data {
    Nonce
    Balance   // 네이티브 잔액
    CodeHash
    Root
    Extra     // blacklist / authorized 플래그
  }
  trie        // 컨트랙트 저장소
}
```

## 제네시스 초기화

NativeCoinAdapter는 제네시스에서 다음 파라미터로 초기화됩니다:

```json theme={null}
{
  "currency": "KRW",
  "decimals": "18",
  "name": "WKRC",
  "symbol": "WKRC",
  "masterMinter": "0x...1002",
  "minterAllowed": "10000000000000000000000000000",
  "minters": "0x...1003"
}
```

초기화 결과:

* 제네시스 블록에 컨트랙트 존재
* 초기 민터 및 allowance 설정
* 토큰 메타데이터 확정
* 이후 변경은 하드 포크만 가능

## 요약

NativeCoinAdapter는 다음을 실현합니다:

1. **제로 저장소 오버헤드 ERC20**
2. **모든 네이티브 코인 이동의 이벤트 추적**
3. **거버넌스 기반 민팅·소각**
4. **기존 스테이블코인 생태계와 완전 호환**
5. **프로토콜 수준 보안 및 정책 강제**

이를 통해 StableNet은 네이티브 가스 토큰을 표준 ERC20 스테이블코인으로 자연스럽게 노출합니다.