NATIVE WALLET: THE SOVEREIGN EVM TERMINAL

Technical Whitepaper & Architectural Reference Guide

1. MANIFESTO & PHILOSOPHICAL FOUNDATION

1.1. The Compromised Vision of Web3 and the "Parasitic Wallet" Monopoly

Cryptographic networks were designed to dismantle intermediaries, eliminate
custodial gatekeepers, and hand absolute sovereign authority back to the
individual. However, the dominant browser extensions acting as entry points to
the decentralized web have systematically betrayed this core philosophy.

Over time, incumbent Web3 wallets transformed into parasitic middleware,
inserting themselves between user intention and consensus execution:

  - Invisible Extraction (The Rent-Seeking Tax): Built-in swap aggregators
    routinely inject hidden, mandatory router fees (often up to 0.875% per
    trade), rerouting swaps through complex pathing that inflates gas
    consumption and silently siphons user capital.
  - Surveillance, Telemetry, and De-anonymization: By routing RPC lookups,
    balance queries, and dApp handshakes through centralized logging proxies
    (Infura, Alchemy, Google Analytics, Mixpanel, and Sentry), corporate
    extensions record user IP addresses, physical locations, and transaction
    habits, directly compromising pseudonymous on-chain privacy.
  - Manufactured Friction and Control Deprivation: Bloated by marketing banners,
    sponsored token pushes, and nested interface mazes, popular wallets
    obfuscate critical cryptographic actions. Obscure confirmation modals and
    unchecked "infinite approval" prompts have directly contributed to billions
    of dollars in compromised assets.

1.2. The Native Wallet Directive: Zero-Parasite, Zero-Telemetry, Absolute Sovereignty

Native Wallet is engineered as an unapologetic rejection of this extractive
paradigm. It adheres to an uncompromising principle: The wallet must never
position itself as an intermediary between user will and the EVM state machine.

  - Zero Telemetry, Zero Outbound Logging: There is not a single line of
    tracking code, remote analytics, or telemetry ping. The extension
    communicates strictly with the selected RPC endpoints and local browser
    storage.
  - Zero Added Fees: Native Wallet adds exactly 0.00% in protocol or execution
    fees. Swaps, batch payments, and transfers interact directly with on-chain
    contracts without intermediary router cuts.
  - Kinetic Execution Transparency: Every transaction decomposes into raw
    calldata, gas limits, and base fees before signature. The kinetic 3-2-1
    countdown verifies state changes before broadcast, ensuring complete
    situational awareness.
  - Lightweight Core: Powered strictly by viem, hardware Web Crypto primitives,
    and a reactive Svelte 5 engine. It boots instantaneously, consumes minimal
    memory, and runs hostless without external runtime dependencies.

2. CRYPTOGRAPHIC VAULT & SECURITY ARCHITECTURE

┌─────────────────────────────────────────────────────────────────────────┐
│                    NATIVE VAULT SECURITY SUBSYSTEM                      │
├────────────────────────┬─────────────────────────┬──────────────────────┤
│  Master Password       │  PBKDF2 (100k Rounds)   │  AES-256-GCM         │
│  (User Entropy)        │  SHA-256 Key Derivation │  Authenticated Cipher│
├────────────────────────┴─────────────────────────┴──────────────────────┤
│  Volatile Memory: chrome.storage.session (RAM Only - Zero Disk Leaks)   │
│  Cold Storage   : chrome.storage.local   (Authenticated Ciphertext Only)│
└─────────────────────────────────────────────────────────────────────────┘

2.1. Dual-Stage Cryptographic Armor: PBKDF2 + AES-256-GCM

The Native Vault (VaultData) enforces strict cryptographic guarantees:

1.  Key Derivation (KDF): The user's master password is never stored or cached
    directly. The plaintext password is bound to a 16-byte cryptographically
    secure random salt and processed through PBKDF2 (HMAC-SHA256) for 100,000
    iterations, yielding a high-entropy 256-bit symmetric CryptoKey.
2.  Authenticated Encryption (AES-256-GCM): The key encrypts the serialized
    vault using AES-GCM (Galois/Counter Mode) with a fresh 12-byte
    initialization vector (IV) per write operation. The GCM authentication tag
    guarantees both confidentiality and ciphertext integrity, making tampering
    instantly detectable upon decryption.
3.  Payload Specification: The persistent payload adheres to this format:
    {
      "format": "NATIVE_VAULT_V1",
      "salt": "0x...",
      "iv": "0x...",
      "data": "0x..."
    }

2.2. RAM-Only Session Isolation (Zero Disk Leaks)

Upon unlocking, decrypted private keys and mnemonic roots remain isolated:

  - Unencrypted secrets reside exclusively in chrome.storage.session (volatile
    process memory).
  - Secrets are never written to localStorage or chrome.storage.local. When the
    browser session closes, volatile memory is automatically purged by the OS,
    leaving zero plaintext footprint on disk.

2.3. Hierarchical Deterministic (BIP-39 & BIP-44) Key Derivation

  - Derivation Path Standard: m/44'/60'/0'/0/x (Standard EVM).
  - A single 12 or 24-word seed phrase deterministically derives an arbitrary
    number of sub-accounts.
  - Automated BIP-44 Discovery: When importing an existing seed, Native Wallet
    inspects derivation paths against on-chain transaction nonces and balances
    using a gap limit of 10, automatically discovering and indexing all active
    historic accounts.

3. MULTI-CHAIN TOPOLOGY & THE DISPERSE ENGINE

Native Wallet strictly separates networks into two isolated domains: Mainnets
and Testnets. Testnet networks never pollute production balances, preventing
accidental transactions on incorrect chains.

┌───────────────────────────┬──────────────┬────────┬───────────┬────────────────────────────────────────────┐
│ Network Name              │ Chain ID     │ Symbol │ Type      │ Canonical Disperse Address                 │
├───────────────────────────┼──────────────┼────────┼───────────┼────────────────────────────────────────────┤
│ Ethereum                  │ 1            │ ETH    │ Mainnet   │ 0xD152f549545093347A162Dce210e7293f1452150 │
│ Ethereum Sepolia          │ 11155111     │ ETH    │ Testnet   │ 0xD152f549545093347A162Dce210e7293f1452150 │
│ BNB Smart Chain           │ 56           │ BNB    │ Mainnet   │ 0xD152f549545093347A162Dce210e7293f1452150 │
│ BNB Chain Testnet         │ 97           │ tBNB   │ Testnet   │ 0xD152f549545093347A162Dce210e7293f1452150 │
│ Polygon PoS               │ 137          │ POL    │ Mainnet   │ 0xD152f549545093347A162Dce210e7293f1452150 │
│ Polygon Amoy              │ 80002        │ POL    │ Testnet   │ 0xD152f549545093347A162Dce210e7293f1452150 │
│ Arbitrum One              │ 42161        │ ETH    │ Mainnet   │ 0xD152f549545093347A162Dce210e7293f1452150 │
│ Arbitrum Sepolia          │ 421614       │ ETH    │ Testnet   │ 0xD152f549545093347A162Dce210e7293f1452150 │
│ Optimism (OP Mainnet)     │ 10           │ ETH    │ Mainnet   │ 0xD152f549545093347A162Dce210e7293f1452150 │
│ OP Sepolia                │ 11155420     │ ETH    │ Testnet   │ 0xD152f549545093347A162Dce210e7293f1452150 │
│ Base                      │ 8453         │ ETH    │ Mainnet   │ 0xD152f549545093347A162Dce210e7293f1452150 │
│ Base Sepolia              │ 84532        │ ETH    │ Testnet   │ 0xD152f549545093347A162Dce210e7293f1452150 │
│ Avalanche C-Chain         │ 43114        │ AVAX   │ Mainnet   │ 0xD152f549545093347A162Dce210e7293f1452150 │
│ Avalanche Fuji            │ 43113        │ AVAX   │ Testnet   │ 0xD152f549545093347A162Dce210e7293f1452150 │
│ Monad (EVM L1)            │ 143          │ MON    │ Mainnet   │ 0xD152f549545093347A162Dce210e7293f1452150 │
│ Monad Testnet             │ 10143        │ MON    │ Testnet   │ 0xD152f549545093347A162Dce210e7293f1452150 │
│ HyperEVM (Hyperliquid)    │ 999          │ HYPE   │ Mainnet   │ 0xD152f549545093347A162Dce210e7293f1452150 │
│ HyperEVM Testnet          │ 998          │ HYPE   │ Testnet   │ 0xD152f549545093347A162Dce210e7293f1452150 │
│ Robinhood Chain           │ 4663         │ RHO    │ Mainnet   │ 0xD152f549545093347A162Dce210e7293f1452150 │
└───────────────────────────┴──────────────┴────────┴───────────┴────────────────────────────────────────────┘

4. SUBSYSTEMS & COMPONENT REFERENCE GUIDE

                      ┌────────────────────────┐
                      │      HEADER BAR        │
                      │ [Account] [Network] [⚙]│
                      └───────────┬────────────┘
                                  │
      ┌───────────────┬───────────┴───┬───────────────┐
      ▼               ▼               ▼               ▼
┌───────────┐   ┌───────────┐   ┌───────────┐   ┌───────────┐
│   SEND    │   │   BATCH   │   │  RECEIVE  │   │   SWAP    │
│  (Single) │   │ (Disperse)│   │  (QR URI) │   │ (On-Chain)│
└───────────┘   └───────────┘   └───────────┘   └───────────┘

4.1. DashboardLayer: Real-Time Valuation & The Sentinel Bridge

A. Valuation & Privacy Masking

  - On-Chain Pricing Engine (OnChainPricingEngine): Native Wallet evaluates user
    holdings without polling centralized pricing APIs. It queries on-chain
    decentralized liquidity pools (e.g., Uniswap V2/V3, PancakeSwap) directly
    via primary RPC nodes, pulling real reserves via getReserves() to calculate
    real-time cross-rates against stable pairs (USDT, USDC, DAI, FDUSD).
  - Privacy Mode (👁️ / 👁️‍🗨️): Toggles an immediate obfuscation mask (••••••)
    across all balances, preventing shoulder-surfing or recording exposure.

B. Active Tab Sentinel Bridge

The Sentinel Bar continuously tracks the active browser tab:

  - Bidirectional EIP-6963 Handshake: Detects the host domain and displays its
    connection status.
  - Instant Session Severance: Users can toggle permissions directly from the
    wallet without navigating third-party dApp settings.

4.2. BatchLayer: Atomic Disperse Transfers

The BatchLayer allows users to distribute native currency or ERC-20 tokens to
dozens of recipient addresses in a single atomic transaction via the canonical
Disperse contract.

Input Data (Plaintext)
0x5e2...3f1, 1.25
0x8b1...9a4, 0.50
        │
        ▼
[Lexer / Parser Engine] ──► Validates EVM Checksums & Recomputes Decimals
        │
        ▼
[Allowance Check]       ──► Prompts One-Time Approval (if ERC-20)
        │
        ▼
[Atomic Execution]      ──► Calls disperseEther() or disperseToken() in 1 Block

  - Input Syntax: Accepts flexible formats (Address, Amount, Address Amount, or
    Address=Amount), one recipient per line.
  - Validation Subsystem: Automatically verifies EVM checksum validity, detects
    format syntax errors, and tallies cumulative transfer sums against available
    balances.
  - Token Allowance Pipeline: If dispersing an ERC-20 token, it checks current
    allowance for 0xD152f549545093347A162Dce210e7293f1452150. If insufficient,
    it automatically queues a one-click max approval prior to distribution.
  - Gas Efficiency: Bypasses multiple 21,000 base gas costs by batching
    execution into an internal contract loop, achieving a 30% to 45% reduction
    in total transaction fees compared to sequential transactions.

4.3. SwapLayer: Direct AMM Routing with Native Market Ticker

The SwapLayer provides decentralized asset trading directly through verified
Automated Market Maker (AMM) router contracts (PancakeSwap, Uniswap, Camelot,
Aerodrome).

A. Direct Pool Routing (Zero Added Surcharge)

  - Computes minimum return amounts using on-chain getAmountsOut() queries.
  - Enforces strict slippage bounds (0.5%, 1.0%, 2.5%) directly inside the
    transaction parameters without passing through third-party rent-seeking
    aggregators.

B. The Global Market Ticker ([ 📊 Markets ▾ ])

Positioned on the header of the swap interface, this dropdown provides
instantaneous reference pricing:

  - Multi-Provider Switch: Allows one-click switching between Binance Public
    API, CoinGecko Simple API, and CoinCap API.
  - Anti-Spam Cooldown: Features an automatic 30-second rate-limiting lock
    between manual updates to prevent client IP blacklisting.
  - Market Tracking: Displays live prices, 24-hour percentage shifts, and
    direction indicators for BTC, ETH, BNB, and SOL.

4.4. SendLayer: Uncompromising Single-Target Security

  - Target Verification Engine: Inspects recipient inputs for burn addresses
    (0x000...000), active account loops (sending to the active account), and
    address book matches.
  - Gas Priority Presets: Fast, Market, and Instant toggles adjust priority fees
    (maxPriorityFeePerGas) dynamically based on real-time mempool pressure.
  - Clipboard Hygiene: Allows one-click pasting from the clipboard with
    automated sanitization.

4.5. ReceiveLayer: Deterministic EIP-681 Payment Request QR Engine

(WARNING: This Layer doesn't work yet because no a legit qr engine in this version !!!)

  - Pure Vector QR Code Engine: Generates lightweight, crisp SVG QR codes
    locally using an internal numerical matrix generator without loading
    external image dependencies or third-party tracking CDNs.
  - EIP-681 URI Parsing: Formats standard URIs incorporating recipient address,
    target token address, and requested decimal-scaled values
    (ethereum:0x...?value=...).

4.6. NetworksLayer: Strict Mainnet/Testnet Partitioning

  - Dual-State Isolation (networkViewMode): Operates on an isolated toggle
    paradigm:
      - MAINNETS View: Lists verified production settlement environments.
      - TESTNETS View: Restricts exposure strictly to development environments.
  - One-Click Header Toggle ([ 🧪 Testnets ] / [ 🌐 Mainnets ]): Flips context
    instantly across the entire interface without messy, mixed-list confusion.
  - Custom RPC & Explorer Management: Users can add, edit, priority-sort, or
    delete RPC endpoints and block explorers for any custom chain ID.

4.7. TokensLayer: Custom Token Management & Liquidity Pool Binding

  - Automatic Registry Discovery: Automatically scans user balances across
    standard token lists without requiring manual contract imports.
  - Custom Liquidity Pool Binding: Users can manually bind an AMM pair address
    (V2 or V3) to any custom token, enabling real-time valuation and direct
    in-wallet swaps for newly deployed or low-cap assets.
  - Phishing Detection: Warns users if a custom token's ticker matches a
    verified asset but points to an unverified contract address.

4.8. SettingsLayer: Hardened Data Controls & Autonomous Sessions

  - Quick Sessions (Autonomous Firewall): Grants trusted dApps temporary,
    time-bounded auto-signing capabilities (e.g., 30 minutes, 1 hour) for
    routine interactions. The session automatically expires and returns to full
    cryptographic prompt requirements when the timer runs out.
  - Address Book: Stores encrypted, labeled contacts inside the local vault.
  - Air-Gapped Vault Backups: Exports and imports AES-256-GCM encrypted .vault
    archives for offline storage and device migration.
  - Factory Reset: Performs a complete cryptographic wipe of persistent and
    volatile state, erasing all vault keys from the browser.

5. DAPP CONNECTIVITY: THE EIP-6963 INTEGRATION STANDARD

Native Wallet deprecates the legacy, vulnerable window.ethereum global injection
pattern across its execution surface, adopting EIP-6963 (Multi-Injected Provider
Discovery) as its core connectivity standard.

Browser Window                               Native Wallet Extension
      │                                                │
      ├─────── eip6963:requestProvider ───────────────►│
      │                                                │
      │◄────── eip6963:announceProvider ───────────────┤
      │        (Immutable Detail: { Info, Provider })  │
      ▼                                                ▼
dApp initializes isolated connection with zero collision or namespace pollution

5.1. EIP-6963 Execution Lifecycle

1.  Provider Announcement: Upon page initialization, the wallet dispatches
    eip6963:announceProvider carrying its unique metadata:
    const detail = Object.freeze({
      info: {
        uuid: '8f7a2d3e-9b1c-4e5a-8f2a-1c3d5e7f9a1b',
        name: 'Native Wallet',
        icon: 'data:image/svg+xml;utf8,...',
        rdns: 'com.nativewallet.app'
      },
      provider: nativeProvider
    });
2.  Deterministic Discovery: When dApps dispatch eip6963:requestProvider, the
    announcement immediately re-triggers, allowing libraries (Wagmi, RainbowKit,
    Web3Modal) to identify Native Wallet without relying on conflicting global
    properties.

6. TRANSACTION EXECUTION LIFECYCLE (THE 3-2-1 KINETIC ENGINE)

To eliminate blind signing and panic-inducing confirmation delays, Native Wallet
funnels all state-modifying actions through the Kinetic Transaction Lifecycle
Engine:

[ Step 3: Local Preparation ]
  - Calldata decoding and validation
  - Gas calculation and balance checks
  - Private key retrieval from RAM-only session storage
            │
            ▼
[ Step 2: RPC Mempool Broadcast ]
  - Cryptographic payload signing
  - Transmission to primary RPC endpoint
  - Retrieval of transaction hash
            │
            ▼
[ Step 1: Validator Mining / Consensus Confirmation ]
  - Active block confirmation tracking
  - Receipt verification (Status: 0x1)
            │
            ▼
[ Confirmed: Cryptographic Receipt Display ]
  - Terminal receipt generated with gas consumed, block index, and explorer link
  - Automatic balance and portfolio refresh

7. SUMMARY SPECIFICATION SHEET

  - Runtime Target: Google Chrome / Chromium-based browsers (Manifest V3).
  - Architecture: Hostless, fully client-side terminal.
  - Encryption Standards: PBKDF2 (100,000 rounds, SHA-256) + AES-256-GCM.
  - EVM Engine: viem + hardware Web Crypto API.
  - Provider Standard: EIP-6963 (Multi-Injected Provider Discovery) + EIP-1193.
  - Batch Protocol: Canonical Disperse
    (0xD152f549545093347A162Dce210e7293f1452150).
  - Pricing Pipeline: Decentralized On-Chain AMM Reserves (V2/V3) + Multi-API
    Reference Dropdown.
  - Telemetry Policy: Absolute Zero (Zero tracking, zero analytics, zero
    external logging).
