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

## Purpose and Scope

This document provides technical documentation for the NativeCoinAdapter system contract in StableNet.\
NativeCoinAdapter exposes the chain’s native coin (used for gas fees) through the standard ERC-20 interface, enabling seamless integration with existing DApps and services that expect ERC-20 tokens.

For an overview of the governance system and mint/burn control mechanisms, see [System Contracts Overview](/en/governance-system/5.1-system-contracts-overview).\
For validator management and consensus details, refer to the [Anzeon WBFT Consensus Protocol](/en/consensus-and-block-production/4.1-anzeon-wbft-consensus-protocol).

## Contract Deployment and Identification

NativeCoinAdapter is a genesis system contract deployed at a fixed address and initialized during chain bootstrap.\
Unlike user-deployed contracts, it has no owner and can only be upgraded via a hard fork, preserving decentralization guarantees.

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

The contract is initialized during genesis block creation with parameters including currency name, symbol, decimals, and the initial master minter configuration.

## Architecture and Design Principles

### Dual-Nature Balance Model

NativeCoinAdapter implements a unique dual-nature balance model with the following properties:

1. **No Redundant Storage**: The adapter does not store balances in its own storage slots. All balance queries directly reference the native balance field in account state.
2. **Direct State Mutation**: Transfers executed via the adapter modify the same native balances that are affected by gas fee payments, ensuring consistency across all balance mutation paths.
3. **Allowance Isolation**: Only allowance mappings (used by `approve()` / `transferFrom()`) are stored in the contract storage trie.
4. **Unified Balance View**: `NativeCoinAdapter.balanceOf(address)` always returns exactly the same value as the account’s native balance used for gas accounting.

## Storage Layout and State Management

### Contract Storage Slots

NativeCoinAdapter maintains minimal storage, tracking only data that cannot be derived from native account state:

| 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** – directly references native balance | Account state         |

By limiting storage to mappings that cannot be inferred from native state, the adapter minimizes storage overhead while preserving full ERC20 functionality.

## Core Transfer Operations

### Direct Transfer Flow

Transfers via NativeCoinAdapter are processed in the following order:

1. **Blacklist Validation**: Check blacklist flags for both sender and recipient in the account Extra field.
2. **Balance Check**: Read the sender’s native balance.
3. **Balance Mutation**: Atomically update the native balances of both accounts.
4. **Journaling**: All state changes are journaled to support reversion.
5. **Event Emission**: Emit the `Transfer(from, to, amount)` event.

### Allowance-Based transferFrom

`transferFrom()` follows the standard ERC20 delegated transfer pattern:

1. Read the allowance from contract storage.
2. Decrease the allowance if sufficient.
3. Perform the actual balance transfer by directly mutating native balances.
4. Emit a `Transfer` event.

## Allowance System Implementation

Allowances cannot be derived from native state and therefore require dedicated contract storage.

| Operation           | Storage Access | State Modification            |
| ------------------- | -------------- | ----------------------------- |
| `approve`           | WRITE          | Set allowance                 |
| `increaseAllowance` | READ → WRITE   | Increase allowance            |
| `decreaseAllowance` | READ → WRITE   | Decrease allowance            |
| `transferFrom`      | READ (+ WRITE) | Deduct allowance and transfer |
| `allowance`         | READ           | Read-only                     |

Allowance storage follows the Solidity nested mapping layout and uses keccak256-based slot computation.

## Minting and Burning Integration

NativeCoinAdapter is the **sole minting and burning interface** for the native coin.\
These operations are restricted to addresses approved by GovMinter and GovMasterMinter.

### Mint/Burn Constraints

1. All minting and burning must occur via `mint()` / `burn()`.
2. Only approved minters may call these functions.
3. Per-minter maximum allowances are enforced.
4. Standard `Transfer` events and dedicated `Mint` / `Burn` events are emitted.
5. Native balances are modified directly.

## Event Emission and Auditability

NativeCoinAdapter emits events for all native coin movements, providing full traceability.

| Event      | Trigger              |
| ---------- | -------------------- |
| `Transfer` | Any balance movement |
| `Approval` | Allowance change     |
| `Mint`     | Minting              |
| `Burn`     | Burning              |

This ensures that all base coin movements can be indexed, audited, and displayed in frontends.

## Blacklist and Authorization Flags

NativeCoinAdapter integrates with flags stored in the account Extra field.

| Account State    | Extra Flag           | Effect                                 |
| ---------------- | -------------------- | -------------------------------------- |
| Blacklisted      | `0x8000000000000000` | Transfers and receipts blocked         |
| Authorized       | `0x4000000000000000` | Exempt from governance-enforced gasTip |
| Normal (default) | `0x0`                | Governance gasTip enforcement applies  |

## ERC20 and FiatToken Extension Compliance

NativeCoinAdapter implements both the standard ERC20 interface and the FiatTokenV2\_2 extensions, ensuring compatibility with existing USDC-based stablecoin infrastructure.

## StateDB Integration

NativeCoinAdapter integrates directly with StateDB:

1. Balance reads → direct native balance access
2. Balance updates → `AddBalance` / `SubBalance`
3. Journaling → supports transaction reversion
4. Flag checks → Extra field access
5. Event logging → included in receipts

### StateObject Structure

```text theme={null}
stateObject {
  address
  data {
    Nonce
    Balance   // native balance
    CodeHash
    Root
    Extra     // blacklist / authorized flags
  }
  trie        // contract storage
}
```

## Genesis Initialization

NativeCoinAdapter is initialized at genesis with the following parameters:

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

Initialization results:

* Contract exists at genesis block
* Initial minters and allowances configured
* Token metadata finalized
* Any future changes require a hard fork

## Summary

NativeCoinAdapter achieves the following:

1. **Zero-storage-overhead ERC20**
2. **Event-level traceability for all native coin movements**
3. **Governance-controlled minting and burning**
4. **Full compatibility with existing stablecoin ecosystems**
5. **Protocol-level security and policy enforcement**

Through this design, StableNet naturally exposes its native gas token as a standard ERC20 stablecoin.