2025

SafeX — Crypto Wallet

100% non-custodial, multi-chain crypto wallet built from fundamental cryptographic primitives.

Project Notes Architecture Infographics Roadmap & Plan View Source Code

100% Non-CustodialCustody

Argon2id (64MB)KDF Engine

EVM + BitcoinChains

Zero TrustServer DB

Zero-Trust Cryptographic Vault•Non-Custodial Multi-Chain

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

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.

TypeScript 5.4Next.js 14.2 (App Router)EVM Engine: Viem 2.xKDF: Argon2id (64MB)Cipher: AES-256-GCMEVM Standard: EIP-1559License: MIT

🔒 The Zero-Trust Guarantee (Why No Central Database?)

True self-custody means zero server trust. In authentic Web3 architecture, storing private keys, seed phrases, or user wallet balances in a centralized database (such as PostgreSQL or MongoDB) is a major anti-pattern and a critical security vulnerability.

No Server Database

SafeX never records private keys, mnemonics, or balances to a server database.

Client-Side Sandbox

100% of entropy, key derivation, and transaction signing occurs exclusively on-device.

Direct Node Calls

Signed raw bytecode broadcasts directly to decentralized Ethereum and Bitcoin RPC nodes.

📚 Deep-Dive Technical Handbooks & Architecture Guides

Comprehensive architectural teardowns, mathematical proofs, and implementation guides located in the repo.

Explore all notes

Phase / Topic	Technical Focus & Engineering Scope	Handbook Link
Phase 1	CSPRNG Entropy, BIP-39 Mnemonics, PBKDF2, Argon2id KDF, AES-256-GCM Vault, RAM Zeroization	📘 Phase 1 Handbook
Phase 2	EIP-1559 Transaction Anatomy, Gas Base Fee Burn, Priority Tips, ECDSA Secp256k1 Offline Signing	📘 Phase 2 Handbook
Phase 3	Nonce Management, Mempool Race Conditions, Replacement & Cancellation, Block Confirmations	📘 Phase 3 Handbook
Phase 4	Smart Contracts, 4-Byte EVM Calldata Selectors, ERC-20 Standard, Fixed-Point Arithmetic	📘 Phase 4 Handbook
Phase 5	On-Chain Swapping (DEX / AMM), Uniswap V2 Router & Factory, Multi-Hop Routing, Slippage Bounds	📘 Phase 5 Handbook
Math & Curves	Secp256k1 Elliptic Curve Algebra, Discrete Logarithm Problem, Point Multiplication (P = k × G)	📘 Elliptic Curve Math
Fundamentals	Consensus Algorithms, Cryptographic Hashes, Peer-to-Peer Networks, Block Structures	📘 Blockchain Core

🖼️ Featured Architecture Infographics

View infographics directory

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

🏛️ System Architecture: Pure Non-Custodial Flow

All Operations In-Browser

┌────────────────────────────────────────────────────────────────────────────────────────┐
│                               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  │   │
│   └─────────────────────────────┘               └──────────────────────────────────┘   │
└────────────────────────────────────────────────────────────────────────────────────────┘

← Swipe horizontally to explore architecture diagram →

⚡ Core Engineering & Cryptographic Deep Dives

1. Zero-Trust Cryptographic Vault & Key Derivation

Argon2id Memory-Hard KDF: Replaced legacy PBKDF2 with Argon2id (m=65536 KB, t=3, p=1) via @noble/hashes. Demanding 64 MB dedicated RAM per hash makes GPU/ASIC brute-forcing computationally infeasible.
AES-256-GCM Cipher: Mnemonic encrypted with 12-byte CSPRNG IV and sealed with a 16-byte Galois Field authTag. Any bit corruption immediately invalidates decryption.
Ephemeral Session Cache: Hybrid memory/sessionStorage cache survives F5 reloads but self-destructs instantly on tab closure.
Active RAM Zeroization: Plaintext keys exist only in volatile RAM; on lock or 10-minute inactivity timeout, buffers are scrubbed using buffer.fill(0).

2. Multi-Chain Address Derivation (EVM + Bitcoin)

BIP-39 Mnemonic Standards: CSPRNG entropy collection supporting 128-bit (12 words) and 256-bit (24 words) recovery phrases with SHA-256 checksums.
Ethereum / EVM (BIP-44): Path m/44'/60'/0'/0/0 → Secp256k1 point multiplication → Keccak-256 hash of (X, Y) coordinates → Drop first 12 bytes → EIP-55 mixed-case checksum.
Bitcoin Native SegWit (BIP-84): Path m/84'/0'/0'/0/0 → 33-byte compressed public key → HASH160 (SHA-256 + RIPEMD-160) → Witness v0 with 5-bit Bech32 encoding (bc1q...).

3. EIP-1559 Modern Transaction Architecture

Type-2 Envelope Serialization: Native encoding of EIP-1559 payload: 0x02 || RLP([chainId, nonce, maxPriorityFeePerGas, maxFeePerGas, gasLimit, to, value, data, accessList]).
Base Fee Burn & Priority Tips: Total fee calculated dynamically as Gas × (BaseFee + PriorityFee).
Offline ECDSA Signing: Computes the (r, s, v) signature tuple on-device using curve secp256k1 before broadcasting raw signed hex bytecode.
Sender Address Extraction: Demonstrates mathematically how EVM nodes recover the originating sender from (r, s, v) without transmitting the sender's public key across the network.

4. Smart Contracts & ERC-20 Token Integration

EVM Calldata Construction: Manual calculation of 4-byte function selectors (0xa9059cbb for transfer(address,uint256)) with 32-byte left-padded hex encoding.
Fixed-Point BigInt Arithmetic: Eliminates IEEE-754 floating-point inaccuracies when handling tokens with mismatched decimal precisions (6 decimals for USDC/USDT vs 18 decimals for ETH/DAI).
Custom Token Import: Query name(), symbol(), decimals(), and balanceOf() directly from any verified ERC-20 contract address.

5. On-Chain DEX Swapping & AMM (Uniswap V2)

Constant-Product Market Maker (x · y = k): Executes token swaps using exact fee-adjusted formulas: Δy = (y · 997 · Δx) / (1000 · x + 997 · Δx).
Canonical Multi-Hop Routing: Auto-constructs multi-hop paths across Wrapped Ether ([tokenIn, WETH, tokenOut]) when direct liquidity pairs do not exist.
Two-Step Non-Custodial Flow: Atomic ERC-20 allowance() verification with one-click approve() and subsequent router execution.
Slippage Boundaries: Enforces strict on-chain slippage tolerance limits to protect users from high price impact in low-depth liquidity pools.

6. Resilient Multi-Provider RPC Failover Tier

Zero-Downtime Fallback Pools: Multi-node resilient fallback pools configured across PublicNode, dRPC, Ethereum Foundation (rpc.sepolia.org), LlamaRPC, Ankr, and Cloudflare.
Automatic Failover: Network rate limits (HTTP 429) or node response timeouts trigger instantaneous switching to healthy secondary JSON-RPC endpoints.

💻 Monorepo Codebase & Architecture Structure

Component	Technology Stack	Role in Architecture
Frontend UI	Next.js 14 + React 18 + Tailwind CSS	Client application, responsive dark-mode dashboard
RAM State	Zustand + sessionStorage	Ephemeral in-memory vault state, 10-minute auto-lock
Local Storage	IndexedDB (safex_db)	Encrypted ciphertext storage (salt, iv, authTag, ciphertext)
Blockchain Engine	Viem 2.x + @scure/bip32 + @scure/base	RLP encoding, multi-provider JSON-RPC, Bech32 & EIP-55 formatting
Cryptography	@noble/hashes (Argon2id, Keccak-256, SHA-256)	Zero-trust client-side key derivation and authenticated encryption

🚀 Getting Started & Test Suite Verification

// Run Development Server

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

Web App: http://localhost:3000

// Run Comprehensive Test Suite (15 Suites)

npm test
npm --prefix apps/web test
npm --prefix apps/server test

Validates BIP-39, HD keys, AES-GCM vault & swap services

🔮 Phase 6+ Roadmap: Centralized Exchange (CEX) Infrastructure

SafeX is an evolving architecture. While Phases 1–5 implement a pure zero-trust self-custodial wallet, upcoming modules demonstrate centralized exchange mechanics:

Phase 6

Exchange Custody & Deposit Sweeper

Hot/cold wallet segregation and automated forwarders for 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 and asks with microsecond latency.

Phase 9

Proof of Reserves (PoR)

Cryptographic Merkle tree reserve audits allowing users to independently verify solvency.