Skip to main content

​
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.
For validator management and consensus details, refer to the 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.
PropertyValue
Contract Address0x0000000000000000000000000000000000001000
Deployment MethodGenesis injection via InjectContracts
Upgrade MechanismHard fork only
OwnerNone (system contract)
Standard ComplianceERC20, 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 TypePurposeStorage Location
Allowancesmapping(address => mapping(address => uint256))Contract storage trie
Minter AllowancesPer-minter mint/burn limitsContract storage trie
MetadataCurrency name, symbol, decimalsContract storage trie
BalancesNOT STORED – directly references native balanceAccount 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.
OperationStorage AccessState Modification
approveWRITESet allowance
increaseAllowanceREAD → WRITEIncrease allowance
decreaseAllowanceREAD → WRITEDecrease allowance
transferFromREAD (+ WRITE)Deduct allowance and transfer
allowanceREADRead-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.
EventTrigger
TransferAny balance movement
ApprovalAllowance change
MintMinting
BurnBurning
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 StateExtra FlagEffect
Blacklisted0x8000000000000000Transfers and receipts blocked
Authorized0x4000000000000000Exempt from governance-enforced gasTip
Normal (default)0x0Governance 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

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: 
{
  "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.