🛡️ SafeX — Zero-Trust, Non-Custodial Multi-Chain Web3 Wallet

SafeX is an enterprise-grade, 100% non-custodial Web3 crypto wallet built from fundamental cryptographic primitives. It provides client-side zero-trust security, multi-chain HD address derivation (EVM + Bitcoin Native SegWit), offline EIP-1559 transaction construction, and direct decentralized blockchain node interaction—with zero central database storing your keys or balances.

High-resolution technical diagrams located in /notes/infographics:

• Seed Phrase to Multi-Chain Address Pipeline
• Complete EIP-1559 Transaction Lifecycle
• Offline ECDSA Signing & Public Key Recovery Tuple $(r, s, v)$
• Sender Address Extraction from Raw Byte Stream
• Resilient Multi-Tier JSON-RPC Architecture
• EIP-1559 Transaction Anatomy Breakdown

All cryptographic operations occur on-device. The only external traffic is raw blockchain JSON-RPC calls.

┌────────────────────────────────────────────────────────────────────────────────────────┐
│                               CLIENT BROWSER SANDBOX                                   │
│                                                                                        │
│   [ Entropy (CSPRNG) ] ──► [ BIP-39 Mnemonic ] ──► [ PBKDF2 ] ──► [ 512-bit Root Seed ]│
│                                                                          │             │
│                 ┌────────────────────────────────────────────────────────┴──────┐      │
│                 ▼ (BIP-44: m/44'/60'/0'/0/0)        ▼ (BIP-84: m/84'/0'/0'/0/0) │      │
│         [ EVM Private Key ]                 [ BTC Private Key ]                 │      │
│                 │                                   │                           │      │
│         [ Secp256k1 Point Mult ]            [ Secp256k1 Point Mult ]            │      │
│                 │                                   │                           │      │
│         [ Keccak-256 + EIP-55 ]             [ HASH160 + Bech32 Encoding ]       │      │
│                 ▼                                   ▼                           │      │
│        Ethereum (0x5de9...Ac)              Bitcoin Native SegWit (bc1q...3x)    │      │
│                                                                                        │
│   ┌────────────────────────────────────────────────────────────────────────────────┐   │
│   │ Client-Side Vault Security (Zero Server Knowledge):                            │   │
│   │ • Master Password ──► Argon2id KDF (64MB RAM, 3 iterations) ──► 256-bit Key     │   │
│   │ • Plaintext Mnemonic ──► AES-256-GCM Authenticated Encryption ──► IndexedDB    │   │
│   │ • Tab Session Cache: Ephemeral sessionStorage with 10-min rolling timer         │   │
│   │ • Memory Protection: buffer.fill(0) active RAM zeroization on lock/timeout     │   │
│   └────────────────────────────────────────────────────────────────────────────────┘   │
│                                                                                        │
│   ┌────────────────────────────────────────────────────────────────────────────────┐   │
│   │ Offline Transaction Signing (secp256k1):                                       │   │
│   │ [ Unsigned EIP-1559 Tx ] ──► [ Sign with PrivKey in RAM ] ──► [ Signed Hex ]    │   │
│   └──────────────────────────────────────┬─────────────────────────────────────────┘   │
└──────────────────────────────────────────┼─────────────────────────────────────────────┘
                                           │ Direct JSON-RPC (eth_sendRawTransaction)
                                           ▼
┌────────────────────────────────────────────────────────────────────────────────────────┐
│                        DECENTRALIZED BLOCKCHAIN NODES                                  │
│                                                                                        │
│   ┌─────────────────────────────┐               ┌──────────────────────────────────┐   │
│   │ Ethereum Mainnet / Sepolia  │               │ Bitcoin SegWit Network           │   │
│   │ • Viem JSON-RPC Multi-Pool  │               │ • Blockstream / Mempool.space    │   │
│   │ • Gas Oracle & Nonce Sync   │               │ • UTXO Tracking & Fee Estimator  │   │
│   └─────────────────────────────┘               └──────────────────────────────────┘   │
└────────────────────────────────────────────────────────────────────────────────────────┘

• Argon2id Memory-Hard KDF: Replaces legacy PBKDF2/SHA-256 password hashing with Argon2id ($m=65,536\text{ KB}$, $t=3$, $p=1$) using @noble/hashes. By demanding 64 MB of dedicated RAM per hash attempt, brute-forcing master passwords on GPUs or ASICs is computationally infeasible.
• Authenticated Symmetric Encryption (AES-256-GCM): Plaintext recovery phrases are encrypted with a 12-byte random CSPRNG initialization vector (iv) and sealed with a 16-byte Galois Field authentication tag (authTag). Any bit corruption or tampering immediately invalidates decryption.
• Ephemeral Session Persistence: Uses an in-memory / sessionStorage hybrid cache. Survives page reloads (F5) in the active tab, but automatically self-destructs the moment the browser tab is closed.
• Active RAM Zeroization: Decrypted private keys exist only in volatile JavaScript memory while unlocked. When locked or after a 10-minute inactivity timeout, buffers are actively scrubbed using .fill(0).

• BIP-39 Mnemonic Standards: Cryptographically secure entropy collection supporting 128-bit (12 words) and 256-bit (24 words) recovery phrases with SHA-256 checksum bits.
• BIP-32 / BIP-44 Hierarchical Deterministic (HD) Paths:
  • Ethereum / EVM: Path m/44'/60'/0'/0/0 $\rightarrow$ Uncompressed public key $\rightarrow$ Keccak-256 hashing of $(X, Y)$ coordinates $\rightarrow$ Drop first 12 bytes $\rightarrow$ EIP-55 mixed-case checksum.
  • Bitcoin Native SegWit (BIP-84): Path m/84'/0'/0'/0/0 $\rightarrow$ Compressed public key (33 bytes) $\rightarrow$ HASH160 (SHA-256 + RIPEMD-160) $\rightarrow$ Witness program version 0 with 5-bit Bech32 encoding (bc1q...).

• Type-2 Envelope Serialization: Constructs and encodes native EIP-1559 transactions: $$\text{Payload} = \text{0x02} \mathbin{\Vert} \text{RLP}\left([ \text{chainId}, \text{nonce}, \text{maxPriorityFeePerGas}, \text{maxFeePerGas}, \text{gasLimit}, \text{to}, \text{value}, \text{data}, \text{accessList} ]\right)$$
• Base Fee Burn & Priority Tip: $$\text{Total Fee} = \text{Gas Units} \times (\text{Base Fee} + \text{Priority Fee})$$
• Client-Side ECDSA Offline Signing: Uses curve secp256k1 to compute the signature tuple $(r, s, v)$ completely in the browser before broadcasting the signed hex bytecode to the blockchain mempool.
• Sender Address Extraction: Demonstrates mathematically how EVM miners recover the originating from address from $(r, s, v)$ without transmitting the sender's public key across the wire.

• EVM Calldata Construction: Manual calculation of 4-byte function selectors (0xa9059cbb for transfer(address,uint256)) and 32-byte left-padded hex encoding.
• Fixed-Point Arithmetic (BigInt): Eliminates JavaScript IEEE-754 floating-point inaccuracies when handling token transfers with different decimal precisions (e.g. 6 decimals for USDC/USDT vs. 18 decimals for ETH/DAI).
• Multi-Chain Verified Registry: Seamlessly handles testnet assets (Sepolia USDC, LINK, WETH) and Ethereum Mainnet assets (native ETH, USDC, USDT, WBTC, DAI).
• Custom Token Dynamic Import: Paste any verified ERC-20 contract address to query name(), symbol(), decimals(), and balanceOf(address) directly from the blockchain state.

• Constant-Product Market Maker ($x \cdot y = k$): Executes on-chain token swaps with exact fee-adjusted output formulas: $$\Delta y = \frac{y \cdot 997 \cdot \Delta x}{1000 \cdot x + 997 \cdot \Delta x}$$
• Canonical Multi-Hop Routing: Automatically constructs multi-hop routes across Wrapped Ether ([tokenIn, WETH, tokenOut]) when direct liquidity pairs do not exist on the Uniswap V2 Factory.
• Two-Step Non-Custodial Authorization:
  1. Allowance Check: Queries on-chain ERC-20 allowance(owner, router). If insufficient, prompts an atomic one-click approve() transaction.
  2. Router Execution: Encodes 4-byte calldata for swapExactETHForTokens, swapExactTokensForETH, or swapExactTokensForTokens.
• Slippage Bounds & Liquidity Protection: $$\text{minAmountOut} = \text{expectedAmountOut} \times (1 - \text{slippageTolerance})$$ Enforces strictly on-chain slippage boundaries with zero fabricated math, alerting users to high price impact in low-depth pools.
• Network Support: Configured for Ethereum Mainnet (Chain ID 1 via official Uniswap Router 0x7a25...488D with ETH, WETH, USDC, USDT, WBTC, DAI) and Sepolia Testnet (Chain ID 11155111).

• Zero-Downtime Fallback Transports: Configures multi-node resilient fallback pools:
  • Sepolia Testnet: PublicNode, dRPC, and Ethereum Foundation (rpc.sepolia.org).
  • Ethereum Mainnet: LlamaRPC, Ankr, Cloudflare, with plug-and-play support for dedicated Alchemy or Infura nodes.
• Automatic Node Failover: Network rate limits (HTTP 429) or node timeouts trigger instantaneous switching to healthy secondary RPC endpoints.

SafeX---Crypto-Wallet/
├── apps/
│   ├── web/                        # Next.js 14 Client-Side Wallet Application
│   │   ├── app/                    # Next.js App Router (Dashboard, Send, Receive, Swap, History, Status)
│   │   ├── components/             # Shared UI (ChainSelector, BackToDashboard, VaultGate, QR)
│   │   ├── core/                   # Core cryptography (BIP-39, HD Keys, Vault, EIP-1559, oRPC client, utils)
│   │   └── features/               # Feature-driven modules (swap, send, receive, tokens, history, dashboard)
│   └── server/                     # Lightweight Blockchain Helper & Broadcast Node
│       └── src/
│           ├── core/               # Blockchain RPC fallback clients, gas estimation, base oRPC server
│           └── features/           # Modular backend feature routers (swap, tokens, prices, history, health, wallet)
├── notes/                          # Deep Technical Handbooks (Phases 1–5), Math Proofs, Infographics
└── Plan/                           # Project Roadmap & Implementation Tracker

• Node.js >= 20.0.0
• npm >= 10.0.0

git clone https://github.com/Sandipxg/SafeX---Crypto-Wallet.git
cd SafeX---Crypto-Wallet
npm install

1. Frontend Web (apps/web/.env.local):

   cp apps/web/.env.example apps/web/.env.local

   Pre-configured defaults:

   NEXT_PUBLIC_API_URL=http://localhost:4000
   NEXT_PUBLIC_SEPOLIA_RPC_URL=https://ethereum-sepolia-rpc.publicnode.com
   NEXT_PUBLIC_MAINNET_RPC_URL=https://eth.llamarpc.com

2. Backend Server (apps/server/.env):

   cp apps/server/.env.example apps/server/.env

Launch the web wallet application:

npm run dev

Open your browser to:

• 🌐 SafeX Web Application: http://localhost:3000
• 🩺 System Status & RPC Health: http://localhost:3000/status

Run the full monorepo test suite or individual workspace tests:

# Execute all unit tests across the entire monorepo (15 test suites)
npm test

# Frontend unit tests (BIP-39, HD keys, AES-GCM vault, token encoder, format & explorer)
npm --prefix apps/web test

# Backend unit tests (swap services, wallet services, tokens, prices, history, health)
npm --prefix apps/server test

Note: SafeX is a progressive learning platform. While Phases 1–5 implement a pure zero-trust self-custodial wallet, upcoming phases demonstrate centralized exchange mechanics:

• Phase 6: Exchange Custody & Deposit Sweeper: Hot/cold wallet segregation, auto-forwarding user deposits.
• Phase 7: Double-Entry Ledger (PostgreSQL): Immutable debits/credits accounting ledger preventing balance drift.
• Phase 8: High-Throughput Matching Engine: In-memory limit order book (LOB) matching FIFO bids/asks.
• Phase 9: Proof of Reserves (PoR): Cryptographic Merkle tree reserve audits allowing users to verify solvency.

Distributed under the MIT License. See LICENSE for full details.