This repository contains a design document only. There is no source code here.
Everything below describes an intended architecture. Any performance figure, benchmark, latency target, throughput number or Sharpe ratio in this document is a design target that has never been measured, not a result. Installation and usage instructions describe files that do not exist in this repository.
It is published as a specification and planning artefact. For systems that are actually built and tested, see web3-infrastructure.
A comprehensive collection of decentralized neobank implementations — from on-chain savings accounts and crypto debit card systems to yield-bearing checking accounts, fiat on/off ramps, credit scoring, and full-stack digital banking platforms. Built to understand the $3.04B+ crypto neobank ecosystem at the smart contract and application level.
- Overview
- Why Crypto Neobanks?
- Neobank Ecosystem Landscape
- Tech Stack
- Projects
- How Crypto Neobanks Work
- Architecture Diagrams
- Repository Structure
- Getting Started
- Development Workflow
- Testing
- Security
- Compliance & Regulatory
- Deployment
- Key Concepts
- Top Neobank Tokens
- Resources
- Contributing
- License
Crypto neobanks merge traditional banking services with blockchain infrastructure — giving users self-custodial savings accounts that earn DeFi yield, stablecoin-powered payments, on-chain credit scoring, and programmable financial products. No branches, no legacy systems, no middlemen.
What you'll build:
- On-chain bank accounts with multi-currency support (stablecoins, crypto, fiat)
- Yield-bearing savings vaults that route deposits into DeFi protocols
- Crypto debit card payment rails — spend stablecoins at any merchant
- Fiat on-ramp and off-ramp integrations
- On-chain credit scoring and under-collateralized lending
- Recurring payments, direct deposits, and payroll systems
- KYC/AML compliance modules with zero-knowledge proofs
- Multi-signature treasury and corporate banking
- Full-stack mobile banking apps with Web3 backends
Traditional banks are slow, expensive, and exclusionary. Crypto neobanks fix this:
| Traditional Bank | Crypto Neobank |
|---|---|
| 0.01-0.5% savings APY | 3-8%+ yield from DeFi strategies |
| 3-5 business days for transfers | Instant settlement (seconds) |
| $25+ wire transfer fees | Near-zero transaction costs on L2s |
| Requires SSN, credit history | Permissionless or ZK-verified identity |
| Limited to local currency | Multi-currency: USDC, USDT, DAI, EUR stablecoins |
| Business hours only | 24/7/365 always-on banking |
| Opaque fee structures | Transparent, auditable on-chain |
| Fractional reserve | Fully collateralized, verifiable on-chain |
| 1.7B unbanked globally | Anyone with a phone can access |
┌──────────────────────────────────────────────────────────────────────────┐
│ CRYPTO NEOBANK ECOSYSTEM │
│ │
│ ┌────────────────────┐ ┌────────────────────┐ ┌───────────────────┐ │
│ │ Neobank Platforms │ │ Payment Rails │ │ Yield / Savings │ │
│ │ │ │ │ │ │ │
│ │ • Juno │ │ • Gnosis Pay │ │ • DSR (Maker) │ │
│ │ • Hi │ │ • Holyheld │ │ • sDAI │ │
│ │ • Revolut (crypto) │ │ • Visa/MC crypto │ │ • Aave yield │ │
│ │ • Nubank (crypto) │ │ • Flexa (AMP) │ │ • Compound │ │
│ │ • Wirex │ │ • Request Network │ │ • ERC-4626 vaults │ │
│ └────────────────────┘ └────────────────────┘ └───────────────────┘ │
│ │
│ ┌────────────────────┐ ┌────────────────────┐ ┌───────────────────┐ │
│ │ Fiat On/Off Ramps │ │ Identity & KYC │ │ Credit & Lending │ │
│ │ │ │ │ │ │ │
│ │ • MoonPay │ │ • Worldcoin (WLD) │ │ • Goldfinch │ │
│ │ • Transak │ │ • Polygon ID │ │ • Maple Finance │ │
│ │ • Ramp Network │ │ • zkPass │ │ • Centrifuge │ │
│ │ • Unlimit │ │ • Civic │ │ • TrueFi │ │
│ │ • Sardine │ │ • SelfKey │ │ • Credora │ │
│ └────────────────────┘ └────────────────────┘ └───────────────────┘ │
│ │
│ ┌────────────────────┐ ┌────────────────────┐ ┌───────────────────┐ │
│ │ Stablecoins │ │ Payroll / Invoicing│ │ Infrastructure │ │
│ │ │ │ │ │ │ │
│ │ • USDC (Circle) │ │ • Sablier (streams) │ │ • Safe (treasury) │ │
│ │ • USDT (Tether) │ │ • Superfluid │ │ • Gnosis Chain │ │
│ │ • DAI (Maker) │ │ • Request Network │ │ • Account Abstract│ │
│ │ • PYUSD (PayPal) │ │ • Bitwage │ │ • Chainlink CCIP │ │
│ │ • EURC (Circle) │ │ • Franklin │ │ • LayerZero │ │
│ └────────────────────┘ └────────────────────┘ └───────────────────┘ │
└──────────────────────────────────────────────────────────────────────────┘
| Layer | Technology |
|---|---|
| Smart Contracts | Solidity 0.8.x |
| Frameworks | Foundry, Hardhat |
| Account System | ERC-4337 (Account Abstraction), Safe Smart Accounts |
| Vault Standards | ERC-4626 (Tokenized Vaults), ERC-20 |
| Streaming Payments | Sablier, Superfluid |
| Identity | Polygon ID, WorldID, zkPass, Civic |
| Oracles | Chainlink (price feeds, CCIP), API3 |
| Fiat Integration | MoonPay, Transak, Ramp Network APIs |
| Card Issuance | Visa/Mastercard APIs, Gnosis Pay SDK |
| Frontend | Next.js, React Native (mobile), wagmi, viem |
| Backend | Node.js, Express, Prisma |
| Database | PostgreSQL, Redis |
| Real-Time | WebSocket, Server-Sent Events |
| Networks | Ethereum, Base, Arbitrum, Polygon, Gnosis Chain |
| # | Project | Description | Key Concepts |
|---|---|---|---|
| 01 | On-Chain Bank Account | Smart contract account with deposit, withdraw, and balance tracking | Account model, multi-token, events |
| 02 | Multi-Currency Wallet | Hold USDC, USDT, DAI, EURC, and ETH in a single smart account | Token registry, balance aggregation |
| 03 | Transaction History Indexer | Index all account movements — deposits, withdrawals, swaps, fees | The Graph, event parsing, categorization |
| 04 | Account Abstraction Banking | Gasless banking via ERC-4337 — users never need ETH for transactions | Paymaster, bundler, smart account |
| 05 | Programmable Bank Account | Accounts with rules: auto-save %, spending limits, scheduled transfers | Automation, Chainlink Keepers, guards |
| # | Project | Description | Key Concepts |
|---|---|---|---|
| 06 | High-Yield Savings Vault | Deposit stablecoins, earn yield routed to Aave/Compound/Maker DSR | ERC-4626, strategy routing, APY calc |
| 07 | Fixed-Rate Savings (Term Deposits) | Lock funds for 30/90/180 days at guaranteed fixed rates | Timelock, fixed yield, early withdrawal |
| 08 | Round-Up Savings | Auto-round transactions to nearest dollar, deposit difference to savings | Transaction hooks, micro-savings |
| 09 | Goal-Based Savings Jars | Named savings goals (vacation, emergency fund) with progress tracking | Sub-accounts, goal math, visualization |
| 10 | Multi-Strategy Yield Optimizer | Auto-allocate across yield sources based on risk preference and APY | Strategy vault, risk scoring, rebalancing |
| # | Project | Description | Key Concepts |
|---|---|---|---|
| 11 | Stablecoin P2P Transfers | Send USDC to anyone via address, ENS, or phone number instantly | Transfer, ENS resolution, contacts |
| 12 | Recurring Payments (Subscriptions) | Set up auto-pay for rent, subscriptions, and bills with stablecoins | Sablier streams, allowance, scheduling |
| 13 | Payment Streaming (Salary) | Real-time salary streaming — earn every second, withdraw anytime | Superfluid, per-second rate, CFA |
| 14 | Crypto Debit Card System | Virtual/physical card that auto-converts stablecoins to fiat at POS | Card issuance API, fiat conversion, limits |
| 15 | Invoice & Billing System | Create on-chain invoices, track payments, auto-reconcile | Request Network, invoice NFT, receipts |
| 16 | QR Code Payment Gateway | Merchant QR codes for in-store stablecoin payments | QR generation, payment verification |
| # | Project | Description | Key Concepts |
|---|---|---|---|
| 17 | On-Chain Credit Score | Build credit score from on-chain history — repayments, holdings, activity | Scoring algorithm, reputation, SBT |
| 18 | Crypto-Backed Personal Loan | Borrow stablecoins against ETH/BTC collateral with flexible terms | LTV, interest accrual, margin call |
| 19 | Under-Collateralized Lending | Reputation-based loans using on-chain credit score + ZK income proof | Credit delegation, risk tiers, default |
| 20 | Buy Now Pay Later (BNPL) | Split purchases into 4 installments with zero interest | Installment math, payment schedule |
| 21 | Micro-Lending Pool | Community lending pool for small loans — credit circle model | Pool accounting, peer guarantees |
| # | Project | Description | Key Concepts |
|---|---|---|---|
| 22 | ZK-KYC Verification | Verify identity without revealing PII using zero-knowledge proofs | ZK-SNARKs, Polygon ID, credential claims |
| 23 | Transaction Monitoring (AML) | Flag suspicious patterns — large transfers, rapid movements, mixing | Rule engine, risk scoring, alerts |
| 24 | Sanctions Screening Oracle | Check addresses against OFAC/sanctions lists before processing transfers | Blocklist oracle, Chainalysis API |
| 25 | Multi-Jurisdiction Compliance | Enforce different rules based on user jurisdiction (US, EU, UK, etc.) | Geo-fencing, regulatory mapping |
| 26 | Fraud Detection Engine | ML-based anomaly detection on transaction patterns | Pattern matching, velocity checks |
| # | Project | Description | Key Concepts |
|---|---|---|---|
| 27 | Personal Banking App | Full mobile app — accounts, transfers, savings, card, history | React Native, full integration |
| 28 | Business Banking Platform | Multi-user corporate accounts, payroll, expense management, treasury | Role-based access, batch payments, Safe |
| 29 | Remittance Platform | Cross-border transfers — fiat in country A → stablecoin → fiat in B | On/off ramp, FX rates, corridor pricing |
| 30 | Banking-as-a-Service (BaaS) SDK | White-label SDK for any app to embed banking features | API design, SDK, webhooks, multi-tenant |
┌─────────────────────────────────────────────────────────────────────────┐
│ USER LAYER │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────────┐ │
│ │ Mobile App │ │ Web App │ │ Debit Card │ │ API (BaaS) │ │
│ │ (iOS/Andr.) │ │ (Next.js) │ │ (Visa/MC) │ │ (for partners) │ │
│ └──────┬─────┘ └──────┬─────┘ └──────┬─────┘ └──────┬─────────┘ │
└─────────┼───────────────┼───────────────┼───────────────┼───────────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ APPLICATION LAYER │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ Backend API (Node.js / Express) │ │
│ │ ├── Account Service ← smart contract interactions │ │
│ │ ├── Payment Service ← transfer routing, streaming │ │
│ │ ├── Yield Service ← vault deposits, strategy management │ │
│ │ ├── Card Service ← Visa/MC API, fiat conversion │ │
│ │ ├── KYC/AML Service ← identity verification, screening │ │
│ │ ├── Notification Service ← tx alerts, payment reminders │ │
│ │ └── Analytics Service ← spending insights, tax reports │ │
│ └──────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ BLOCKCHAIN LAYER │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │
│ │ Smart Account │ │ Savings Vault│ │ Payment │ │ Credit │ │
│ │ (ERC-4337) │ │ (ERC-4626) │ │ Router │ │ Module │ │
│ │ │ │ │ │ │ │ │ │
│ │ • Deposit │ │ • Deposit │ │ • P2P send │ │ • Score │ │
│ │ • Withdraw │ │ • Yield │ │ • Stream │ │ • Borrow │ │
│ │ • Batch tx │ │ • Compound │ │ • Subscribe │ │ • Repay │ │
│ │ • Gasless │ │ • Withdraw │ │ • Invoice │ │ • Default │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ └────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ DeFi Yield │ │ Stablecoins │ │ Oracles │ │
│ │ (Aave,Maker, │ │ (USDC,DAI, │ │ (Chainlink, │ │
│ │ Compound) │ │ USDT,EURC) │ │ price feeds)│ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ ONBOARD │───►│ DEPOSIT │───►│ EARN │───►│ SPEND │───►│ TRACK │
│ │ │ │ │ │ │ │ │ │
│ Download │ │ Fiat → │ │ Stables │ │ Tap card │ │ View tx │
│ app │ │ stablecoin│ │ deposited │ │ at store │ │ history │
│ │ │ via ramp │ │ into yield│ │ │ │ │
│ ZK-KYC │ │ │ │ vault │ │ Auto-sell │ │ Spending │
│ verify │ │ Or crypto │ │ │ │ USDC → │ │ insights │
│ │ │ transfer │ │ Earn 5%+ │ │ fiat at │ │ │
│ Create │ │ direct │ │ APY │ │ POS │ │ Tax │
│ account │ │ │ │ │ │ │ │ report │
└──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘
User deposits $10,000 USDC into Savings
│
▼
┌─────────────────┐
│ Yield Router │
│ (Strategy Mgr) │
└────────┬────────┘
│
Risk Preference: MEDIUM
│
┌─────────────┼─────────────────┐
│ │ │
▼ ▼ ▼
┌─────────┐ ┌──────────┐ ┌──────────────┐
│ Aave │ │ Maker │ │ Compound │
│ USDC │ │ DSR │ │ USDC │
│ Pool │ │ (sDAI) │ │ Pool │
│ │ │ │ │ │
│ $4,000 │ │ $4,000 │ │ $2,000 │
│ 4.2% │ │ 5.0% │ │ 3.8% │
└─────────┘ └──────────┘ └──────────────┘
Blended APY: (4000×4.2% + 4000×5.0% + 2000×3.8%) / 10000
= (168 + 200 + 76) / 10000
= 4.44% blended APY
Auto-rebalance weekly based on rate changes
┌────────┐ ┌──────────┐ ┌───────────┐ ┌──────────┐ ┌──────────┐
│ User │ │ Card │ │ Payment │ │ Fiat │ │ Merchant │
│ taps │───►│ Network │───►│ Processor │───►│ Off-Ramp │───►│ receives │
│ card │ │ (Visa) │ │ │ │ │ │ USD/EUR │
└────────┘ └──────────┘ └───────────┘ └──────────┘ └──────────┘
│
│ simultaneously:
▼
┌──────────────────┐
│ Smart Contract │
│ │
│ 1. Check balance │
│ 2. Check limits │
│ 3. Debit USDC │
│ 4. Emit event │
│ 5. Update history │
└──────────────────┘
$47.50 coffee purchase
├── USDC deducted: 47.50 USDC
├── FX fee: $0.00 (stablecoin)
├── Network fee: ~$0.001 (L2)
└── Round-up: $0.50 → savings jar
Sender (USA) Blockchain Receiver (India)
│ │ │
├── deposit $500 USD ─────────►│ │
│ (bank transfer / card) │ │
│ │ │
│ ┌─────────────────────┤ │
│ │ Fiat On-Ramp │ │
│ │ (MoonPay/Transak) │ │
│ │ $500 → 499.50 USDC │ │
│ │ (fee: $0.50) │ │
│ └──────────┬──────────┘ │
│ │ │
│ │ Transfer USDC on L2 │
│ │ (instant, ~$0.001 fee) │
│ │ │
│ ┌──────────┴──────────┐ │
│ │ Fiat Off-Ramp │ │
│ │ (local partner) │ │
│ │ 499.50 USDC → │ │
│ │ ₹41,700 INR │ │
│ │ (market rate) │──── UPI / bank transfer ───►│
│ └─────────────────────┘ │
│ │
│ Total fees: ~$1.50 (0.3%) │
│ vs Western Union: ~$25 (5%) │
│ Time: ~2 minutes vs 3-5 days │
┌─────────────────────────────────────────────────────────────────────────────┐
│ FRONTEND LAYER │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────────────┐ │
│ │ Mobile App │ │ Web Dashboard │ │ Admin Panel │ │
│ │ (React Native) │ │ (Next.js) │ │ (Internal tools) │ │
│ │ │ │ │ │ │ │
│ │ • Accounts │ │ • Account mgmt │ │ • User management │ │
│ │ • Send/receive │ │ • Savings │ │ • Transaction monitoring│ │
│ │ • Card controls │ │ • Analytics │ │ • Compliance dashboard │ │
│ │ • Savings goals │ │ • Settings │ │ • Risk alerts │ │
│ │ • Push notifs │ │ │ │ │ │
│ └────────┬─────────┘ └────────┬─────────┘ └────────────┬─────────────┘ │
└───────────┼─────────────────────┼──────────────────────────┼────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ API GATEWAY │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ Rate Limiting │ Auth (JWT/Session) │ Request Routing │ Logging │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────┬──────────────────────────────────────────┘
│
┌──────────────────────────────────┼──────────────────────────────────────────┐
│ MICROSERVICES LAYER │
│ │ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │
│ │ Account │ │ Payment │ │ Yield │ │ Card │ │
│ │ Service │ │ Service │ │ Service │ │ Service │ │
│ ├─────────────┤ ├─────────────┤ ├─────────────┤ ├─────────────────┤ │
│ │ • Create │ │ • P2P │ │ • Deposit │ │ • Issue virtual │ │
│ │ • Balance │ │ • Stream │ │ • Withdraw │ │ • Issue physical│ │
│ │ • History │ │ • Subscribe │ │ • Rebalance │ │ • Set limits │ │
│ │ • Settings │ │ • Invoice │ │ • Harvest │ │ • Freeze/unfreeze│ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────────┘ │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │
│ │ KYC/AML │ │ Credit │ │ Notification│ │ Analytics │ │
│ │ Service │ │ Service │ │ Service │ │ Service │ │
│ ├─────────────┤ ├─────────────┤ ├─────────────┤ ├─────────────────┤ │
│ │ • ZK verify │ │ • Score │ │ • Push │ │ • Spending │ │
│ │ • Sanctions │ │ • Loan orig │ │ • Email │ │ • Yield perf │ │
│ │ • AML rules │ │ • Repayment │ │ • SMS │ │ • Tax export │ │
│ │ • Reporting │ │ • Default │ │ • In-app │ │ • Insights │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────────┘ │
└──────────────────────────────────┬──────────────────────────────────────────┘
│
┌──────────────────────────────────┼──────────────────────────────────────────┐
│ BLOCKCHAIN LAYER │
│ │ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Smart Account │ │ Savings Vault│ │ Payment │ │ Credit Score │ │
│ │ (ERC-4337) │ │ (ERC-4626) │ │ Module │ │ (SBT) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Aave / Maker │ │ USDC / DAI │ │ Chainlink │ │ Paymaster │ │
│ │ (yield) │ │ (stables) │ │ (price feeds)│ │ (gas sponsor)│ │
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
neobank-projects/
├── 01-onchain-bank-account/
│ ├── src/
│ │ ├── BankAccount.sol
│ │ ├── AccountFactory.sol
│ │ └── interfaces/
│ ├── test/
│ │ ├── BankAccount.t.sol
│ │ └── invariant/
│ ├── script/
│ ├── foundry.toml
│ └── README.md
├── 06-high-yield-savings/
│ ├── src/
│ │ ├── SavingsVault.sol
│ │ ├── YieldRouter.sol
│ │ └── strategies/
│ │ ├── AaveStrategy.sol
│ │ ├── MakerDSRStrategy.sol
│ │ └── CompoundStrategy.sol
│ ├── test/
│ │ └── fork/
│ └── README.md
├── 13-payment-streaming/
│ ├── src/
│ │ └── SalaryStream.sol
│ ├── frontend/
│ │ ├── src/
│ │ └── package.json
│ └── README.md
├── 17-onchain-credit-score/
│ ├── src/
│ │ ├── CreditScorer.sol
│ │ ├── CreditSBT.sol
│ │ └── libraries/
│ └── README.md
├── 22-zk-kyc/
│ ├── circuits/ ← ZK circuits
│ ├── src/
│ │ ├── ZKVerifier.sol
│ │ └── KYCGateway.sol
│ └── README.md
├── 27-personal-banking-app/
│ ├── contracts/
│ ├── backend/
│ │ ├── src/
│ │ │ ├── services/
│ │ │ ├── routes/
│ │ │ └── middleware/
│ │ └── package.json
│ ├── mobile/
│ │ ├── src/
│ │ │ ├── screens/
│ │ │ ├── components/
│ │ │ └── hooks/
│ │ └── package.json
│ ├── subgraph/
│ └── README.md
├── lib/ # Shared Solidity dependencies
│ ├── forge-std/
│ ├── openzeppelin-contracts/
│ ├── account-abstraction/
│ └── solmate/
├── interfaces/ # Common neobank interfaces
│ ├── IBankAccount.sol
│ ├── ISavingsVault.sol
│ ├── IPaymentRouter.sol
│ ├── ICreditScore.sol
│ └── IKYCGateway.sol
├── packages/ # Shared TypeScript packages
│ ├── sdk/ # Neobank client SDK
│ ├── compliance/ # KYC/AML utilities
│ └── analytics/ # Transaction categorization
└── README.md
- Foundry —
curl -L https://foundry.paradigm.xyz | bash && foundryup - Node.js >= 18.x
- pnpm (recommended)
- Git
- Docker (for backend services, PostgreSQL)
# Clone the repository
git clone https://github.com/pranay123-stack/neobank-projects.git
cd neobank-projects
# === Smart Contract Projects ===
cd 06-high-yield-savings
forge install
forge build
forge test -vvv
# === Full-Stack Projects ===
cd 27-personal-banking-app
# Start backend
cd backend && pnpm install && pnpm dev
# Start mobile app
cd ../mobile && pnpm install && pnpm startcp .env.example .env# RPC Endpoints
MAINNET_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY
BASE_RPC_URL=https://base-mainnet.g.alchemy.com/v2/YOUR_KEY
ARBITRUM_RPC_URL=https://arb-mainnet.g.alchemy.com/v2/YOUR_KEY
SEPOLIA_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY
# Deployment
PRIVATE_KEY=your_deployer_private_key
ETHERSCAN_API_KEY=your_etherscan_api_key
# ERC-4337
BUNDLER_RPC_URL=https://api.pimlico.io/v2/base/rpc?apikey=YOUR_KEY
PAYMASTER_URL=https://api.pimlico.io/v2/base/rpc?apikey=YOUR_KEY
# Fiat Ramps
MOONPAY_API_KEY=your_moonpay_key
TRANSAK_API_KEY=your_transak_key
# Card Issuance
CARD_ISSUER_API_KEY=your_card_api_key
# KYC Provider
KYC_PROVIDER_API_KEY=your_kyc_key
# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/neobank
REDIS_URL=redis://localhost:6379Never commit API keys or private keys. All projects include
.gitignorewith.envexcluded.
# Compile
forge build
# Run all tests
forge test
# Fork test against live DeFi protocols
forge test --fork-url $MAINNET_RPC_URL --match-path "test/fork/*" -vvv
# Gas report
forge test --gas-report
# Deploy
forge script script/Deploy.s.sol --rpc-url $BASE_RPC_URL --broadcast --verifycd backend
# Install
pnpm install
# Run database migrations
pnpm prisma migrate dev
# Start development server
pnpm dev
# Run tests
pnpm test
# Build for production
pnpm buildcd mobile
# Install
pnpm install
# Start Expo dev server
pnpm start
# Run on iOS simulator
pnpm ios
# Run on Android emulator
pnpm android# Unit Tests — individual banking functions
forge test --match-path "test/unit/*"
# Integration Tests — full deposit-earn-withdraw lifecycle
forge test --match-path "test/integration/*"
# Fuzz Tests — random amounts, edge cases
forge test --match-path "test/fuzz/*"
# Invariant Tests — banking properties that must always hold
forge test --match-path "test/invariant/*"
# Fork Tests — test against live Aave, Compound, Maker
forge test --match-path "test/fork/*" --fork-url $MAINNET_RPC_URL// User balance must always be withdrawable (solvency)
function invariant_alwaysSolvent() public {
uint256 totalDeposits = vault.totalAssets();
uint256 totalAvailable = vault.totalAvailableLiquidity();
// Available >= deposits (yield accrued on top)
assertGe(totalAvailable, totalDeposits);
}
// Deposit and immediate withdraw must return same amount (minus any fees)
function invariant_depositWithdrawIdentity() public {
uint256 amount = 1000e6; // 1000 USDC
uint256 sharesMinted = vault.deposit(amount, user);
uint256 assetsReturned = vault.redeem(sharesMinted, user, user);
assertApproxEqAbs(assetsReturned, amount, 1); // rounding tolerance of 1 wei
}
// Total shares * price per share must equal total assets
function invariant_shareAccounting() public {
uint256 totalShares = vault.totalSupply();
uint256 totalAssets = vault.totalAssets();
if (totalShares > 0) {
uint256 computedAssets = vault.convertToAssets(totalShares);
assertApproxEqRel(computedAssets, totalAssets, 0.0001e18);
}
}
// Spending limit must never be exceeded within a day
function invariant_spendingLimitEnforced() public {
assertLe(account.spentToday(), account.dailySpendLimit());
}
// Credit score must remain within valid bounds
function invariant_creditScoreBounds() public {
uint256 score = creditScorer.getScore(user);
assertGe(score, 300); // minimum score
assertLe(score, 850); // maximum score
}
// Loan health: collateral value must cover outstanding debt
function invariant_loanHealth() public {
if (lending.hasActiveLoan(user)) {
uint256 collateralValue = lending.getCollateralValue(user);
uint256 debtValue = lending.getDebtValue(user);
uint256 minRatio = lending.minimumCollateralRatio();
assertGe(collateralValue * 1e18 / debtValue, minRatio);
}
}| Attack | Description | Mitigation |
|---|---|---|
| Yield Strategy Exploit | Underlying DeFi protocol hacked, savings vault drained | Diversified strategies, withdrawal limits, insurance |
| Oracle Price Manipulation | Manipulate stablecoin price feed to drain collateral | Chainlink, TWAP, circuit breakers |
| Account Takeover | Compromise smart account owner key | Multi-sig, social recovery, session key limits |
| Reentrancy on Withdrawal | Re-enter during withdraw to drain extra funds | CEI pattern, ReentrancyGuard |
| Flash Loan Vault Attack | Flash deposit → inflate share price → drain vault | Virtual shares offset, deposit delay |
| KYC Data Leak | Storing PII that gets compromised | ZK proofs — verify without storing PII |
| Fiat Ramp Fraud | Chargebacks on fiat deposits after crypto received | Hold period, progressive limits, risk scoring |
| Card Skimming / Replay | Stolen card details used for unauthorized transactions | Real-time alerts, freeze controls, 3DS |
| Regulatory Action | Funds frozen by government order on non-compliant platform | Multi-jurisdiction compliance, legal structure |
| Smart Contract Upgrade Attack | Malicious proxy upgrade changes withdrawal logic | Timelock on upgrades, multi-sig governance |
| Dust Attack / Address Poisoning | Sending tiny amounts from look-alike addresses to trick users | Address book, verified contacts, checksum alerts |
| Paymaster Drainage | Exploiting gas sponsorship to drain paymaster funds | Rate limits, per-user caps, stake requirements |
- All user funds in audited smart contracts (not custodial hot wallets)
- ERC-4626 vault follows share accounting best practices (virtual offset)
- Reentrancy guards on all deposit/withdraw/transfer paths
- Yield strategies diversified — no single point of failure
- Oracle feeds validated for staleness and manipulation
- Withdrawal delays for large amounts (timelock)
- Multi-sig or governance for contract upgrades
- KYC data never stored on-chain — ZK proofs only
- Rate limiting on all APIs and smart contract interactions
- Card freezing available instantly via app
- Transaction monitoring for suspicious patterns (AML)
- Emergency pause mechanism with multi-sig trigger
| Jurisdiction | Regulator | Key Requirements | License Needed |
|---|---|---|---|
| USA | FinCEN, SEC | MSB registration, KYC/AML, state money transmitter | State MTL, MSB |
| EU | MiCA | CASP registration, MiCA compliance, GDPR | CASP License |
| UK | FCA | Crypto asset registration, consumer protection | FCA Registration |
| Singapore | MAS | Payment Services Act, AML/CFT | MPI License |
| UAE | VARA, ADGM | Virtual asset service provider rules | VASP License |
┌─────────────────────────────────────────────────────────┐
│ COMPLIANCE LAYER │
│ │
│ ┌──────────────┐ ┌────────────┐ ┌────────────────┐ │
│ │ KYC Engine │ │ AML Rules │ │ Sanctions │ │
│ │ │ │ Engine │ │ Screening │ │
│ │ Tier 1: Email│ │ │ │ │ │
│ │ Tier 2: ID │ │ • Velocity│ │ • OFAC list │ │
│ │ Tier 3: Proof│ │ • Pattern │ │ • EU sanctions│ │
│ │ of address │ │ • Amount │ │ • UN list │ │
│ │ │ │ • Network │ │ • Chainalysis │ │
│ └──────┬───────┘ └─────┬──────┘ └───────┬────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ RISK SCORING ENGINE │ │
│ │ │ │
│ │ Low Risk (score < 30) → Auto-approve │ │
│ │ Medium Risk (30-70) → Enhanced monitoring │ │
│ │ High Risk (> 70) → Manual review │ │
│ │ Critical (> 90) → Block + SAR filing │ │
│ └──────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
| Network | Chain ID | Tx Cost | Why |
|---|---|---|---|
| Base | 8453 | ~$0.005 | Coinbase ecosystem, consumer-friendly, ultra-low fee |
| Arbitrum One | 42161 | ~$0.01 | Fast finality, mature ecosystem, deep DeFi liquidity |
| Polygon PoS | 137 | ~$0.01 | Established, Polygon ID for ZK-KYC |
| Gnosis Chain | 100 | ~$0.001 | Gnosis Pay native, cheapest transactions |
| Optimism | 10 | ~$0.01 | Superchain ecosystem, good stablecoin liquidity |
| Ethereum | 1 | ~$1-5 | Settlement layer for high-value treasury operations |
# 1. Deploy Account Factory (ERC-4337)
forge script script/DeployAccountFactory.s.sol \
--rpc-url $BASE_RPC_URL --broadcast --verify
# 2. Deploy Savings Vault
forge script script/DeploySavingsVault.s.sol \
--rpc-url $BASE_RPC_URL --broadcast --verify
# 3. Deploy Payment Router
forge script script/DeployPaymentRouter.s.sol \
--rpc-url $BASE_RPC_URL --broadcast --verify
# 4. Deploy Credit Score Module
forge script script/DeployCreditScore.s.sol \
--rpc-url $BASE_RPC_URL --broadcast --verify
# 5. Fund Paymaster for gasless banking
cast send $ENTRYPOINT "depositTo(address)" $PAYMASTER \
--value 5ether --rpc-url $BASE_RPC_URL --private-key $PRIVATE_KEY
# 6. Deploy backend
cd backend && pnpm build && pnpm start:prod| Concept | Description |
|---|---|
| Neobank | Digital-only bank operating via apps, no physical branches |
| Stablecoin | Cryptocurrency pegged to fiat currency (USDC = $1, EURC = €1) |
| ERC-4626 | Tokenized vault standard — deposit assets, receive yield-bearing shares |
| DSR (Dai Savings Rate) | MakerDAO's native yield on DAI deposits |
| Yield Routing | Automatically allocating deposits across DeFi protocols for best APY |
| Payment Streaming | Continuous money flow — earn salary every second via Superfluid/Sablier |
| Account Abstraction | Smart contract wallets with gasless transactions, batching, recovery |
| Gasless Banking | Paymaster sponsors gas — users never need ETH to transact |
| ZK-KYC | Verify identity using zero-knowledge proofs without storing personal data |
| On-Chain Credit Score | Reputation built from DeFi history — repayments, holdings, activity |
| Soulbound Token (SBT) | Non-transferable token representing credit score, KYC status, or membership |
| Fiat On-Ramp | Service converting fiat (USD, EUR) to crypto/stablecoins |
| Fiat Off-Ramp | Service converting crypto/stablecoins back to fiat |
| MSB / MTL | Money Services Business / Money Transmitter License (US regulatory) |
| MiCA | Markets in Crypto-Assets (EU regulatory framework) |
| CASP | Crypto-Asset Service Provider (EU license under MiCA) |
| AML/CFT | Anti-Money Laundering / Countering Financing of Terrorism |
| SAR | Suspicious Activity Report — filed with regulators for flagged transactions |
| BaaS | Banking-as-a-Service — white-label banking infrastructure for other apps |
| TVL | Total Value Locked — total deposits in a protocol's smart contracts |
A snapshot of tokens powering the crypto neobank ecosystem:
| Token | Project | Role in Ecosystem |
|---|---|---|
| JUNO | Juno Finance | Crypto checking account, debit card, yield on deposits |
| HI | hi Protocol | Multi-currency neobank, membership token, yield and rewards |
| NEXO | Nexo | Earn interest, borrow against crypto, card payments |
| CRO | Crypto.com | Visa card staking tiers, DeFi yield, exchange ecosystem |
| WIREX | Wirex | Multi-currency accounts, card cashback, X-Accounts |
| AMP | Flexa | Collateral token for instant, fraud-proof crypto payments |
| REQ | Request Network | Invoicing, accounting, and payment infrastructure |
| CELO | Celo | Mobile-first payments, stablecoins (cUSD, cEUR), financial inclusion |
| GNO | Gnosis (Gnosis Pay) | On-chain Visa debit card, Gnosis Chain settlement |
| SAFE | Safe | Multi-sig treasury management for business banking |
Market data as of May 2026. Total neobank sector cap: ~$3.04B.
- Gnosis Pay — On-chain Visa debit card
- Holyheld — Crypto spending card with DeFi yield
- Request Network — Invoicing and payment infrastructure
- Superfluid — Real-time payment streaming
- Sablier — Token streaming for payroll
- Aave V3 Docs — Lending protocol (yield source)
- MakerDAO / Sky — DSR, sDAI (yield source)
- Compound V3 — Lending protocol (yield source)
- ERC-4626 Standard — Tokenized vault standard
- Polygon ID — ZK-based identity verification
- WorldID (Worldcoin) — Proof of personhood
- Civic — Identity verification platform
- Chainalysis — Blockchain analytics and compliance
- Foundry Book
- wagmi Documentation
- Pimlico (AA Infrastructure)
- MoonPay API — Fiat on/off ramp
- Transak API — Fiat on/off ramp
Contributions are welcome! Whether it's a new banking feature, compliance module, or security improvement:
- Fork the repository
- Create a feature branch (
git checkout -b feature/new-banking-module) - Follow the existing project structure
- Include comprehensive tests (unit + fuzz + invariant + fork)
- Add a
README.mdwith architecture, compliance notes, and security analysis - Submit a pull request
High-impact contribution ideas:
- Multi-chain savings vault with cross-chain yield aggregation
- React Native mobile banking template
- ZK-proof income verification for under-collateralized lending
- Tax calculation and export engine
- Real-time spending notifications via push
This repository is licensed under the MIT License.
Banking should be invisible, instant, and accessible to everyone. Build the financial infrastructure the world deserves.