# Migration Backend → Spring Boot – Feasibility (Refonte) This document lists **all current backend functionalities** and confirms that each can be implemented in **Spring Boot** without losing any capability. No code has been modified; this is an assurance before any refonte (migration). --- ## 1. Current Stack Summary - **Runtime**: Node.js (Express + TypeScript) - **Database**: PostgreSQL (same schema can be kept) - **Auth**: JWT (access + refresh), Argon2/bcrypt, TOTP (2FA) - **Blockchain**: TRON (TronWeb), Polygon (ethers.js), BIP39/HD (bip39 + ethers + TronWeb) --- ## 2. Functionality Checklist → Spring Boot Equivalents ### 2.1 Authentication & Users | Current (Node) | Spring Boot / Java Equivalent | Possible? | |----------------|------------------------------|-----------| | Register (email + password, email hashed for lookup, encrypted at rest) | Spring Security + custom UserDetailsService; JPA entities; AES-GCM via `javax.crypto` or Spring Security Crypto | ✅ Yes | | Login (rate-limited) | Spring Security form/login or custom filter; Bucket4j or Spring rate-limiter | ✅ Yes | | JWT access + refresh tokens | `jjwt` (io.jsonwebtoken) or Spring Security OAuth2 Resource Server; refresh stored in DB | ✅ Yes | | Password hashing (Argon2 / bcrypt) | Spring Security `PasswordEncoder` (Argon2PasswordEncoder, BCryptPasswordEncoder) | ✅ Yes | | 2FA TOTP (setup: generate secret, QR code) | e.g. `com.eatthepath:java-otp` + ZXing or similar for QR | ✅ Yes | | 2FA enable (verify 6-digit code) | Same TOTP lib to verify code | ✅ Yes | | Email/phone encrypted storage, email_hash for index | Same schema; encryption with AES-256-GCM in Java | ✅ Yes | ### 2.2 Wallet & Ledger (API) | Current (Node) | Spring Boot / Java Equivalent | Possible? | |----------------|------------------------------|-----------| | GET /wallet-types | Spring Data JPA `WalletType` repository; same table | ✅ Yes | | GET /balances | Service that reads `ledger_accounts` (or view) per user; same schema | ✅ Yes | | GET /deposit-address/:walletType | HD derivation (see 2.4) → return address; store in `user_wallets` | ✅ Yes | | GET /transactions | JPA `Transaction` repository, filter by user, pagination | ✅ Yes | ### 2.3 Internal Transfer | Current (Node) | Spring Boot / Java Equivalent | Possible? | |----------------|------------------------------|-----------| | POST /transfer (toEmail, walletType, amount, totpCode) | Service: verify TOTP, lookup user by email_hash, debit/credit in one `@Transactional` method, create 2 transaction rows | ✅ Yes | | Ledger: transferBetweenAccounts (debit sender, credit receiver, ledger_entries with reference_id UUID) | Same logic in a single transaction; JPA or raw JDBC | ✅ Yes | ### 2.4 Withdrawals | Current (Node) | Spring Boot / Java Equivalent | Possible? | |----------------|------------------------------|-----------| | Lock balance, create withdrawal transaction & lock record | Service with `@Transactional`; same tables | ✅ Yes | | Sign and broadcast TRON (TRX or TRC20) | HTTP to TronGrid API or Java TRON client (e.g. tron4j / TronGrid HTTP) | ✅ Yes | | Sign and broadcast Polygon (ERC-20 USDC) | **web3j** for Ethereum-compatible chains (Polygon) | ✅ Yes | | Hot wallet private key decryption | AES-GCM in Java (same as encrypting email/TOTP) | ✅ Yes | | Unlock balance on success/failure, update tx status | Same business logic in service layer | ✅ Yes | ### 2.5 Deposit Monitoring (Background Job) | Current (Node) | Spring Boot / Java Equivalent | Possible? | |----------------|------------------------------|-----------| | Periodic poll (e.g. every 60s) | `@Scheduled(fixedDelay = 60000)` or Quartz | ✅ Yes | | TRON: get TRX transfers to user addresses | TronGrid HTTP API (same as TronWeb uses) or Java TRON client | ✅ Yes | | TRON: get TRC20 (USDT) transfers to user addresses | Same; TRC20 contract calls / events via TronGrid | ✅ Yes | | Polygon: get ERC-20 (USDC) transfers to user addresses | **web3j** + contract events (Transfer) or logs | ✅ Yes | | Confirmations logic (time-based or block-based) | Same logic in Java | ✅ Yes | | Credit ledger, create transaction, update scanner state | JPA repositories; same schema | ✅ Yes | | Idempotency (blockchain_tx_id) | Same unique constraint and checks | ✅ Yes | ### 2.6 HD Wallet & Keys | Current (Node) | Spring Boot / Java Equivalent | Possible? | |----------------|------------------------------|-----------| | BIP39 mnemonic (generate, mnemonicToSeed) | **bitcoinj** or **BIP39 library for Java** (e.g. `org.bitcoinj:bitcoinj-core` or dedicated BIP39 lib) | ✅ Yes | | Derive TRON path m/44'/195'/0'/0/n | TRON uses same derivation as some Java libs; or call TronGrid “create account” / derive via their API; or use a small TRON key-derivation lib in Java | ✅ Yes | | Derive Ethereum/Polygon path m/44'/60'/0'/0/n | **web3j** or **bitcoinj** BIP44 for ETH | ✅ Yes | | Encrypt/decrypt private keys (AES-256-GCM) | `javax.crypto.Cipher` with AES/GCM/NoPadding | ✅ Yes | | Seed hot wallets (script) | Same logic as service; runnable as `CommandLineRunner` or separate script with Spring context | ✅ Yes | ### 2.7 Database & Schema | Current (Node) | Spring Boot / Java Equivalent | Possible? | |----------------|------------------------------|-----------| | PostgreSQL | Spring Data JPA + same PostgreSQL; no schema change required | ✅ Yes | | Migrations (schema.sql / migrate) | Flyway or Liquibase; reuse same SQL or generate from JPA (careful with existing data) | ✅ Yes | | All tables (users, roles, refresh_tokens, wallet_types, user_wallets, hot_wallets, ledger_accounts, ledger_entries, transactions, withdrawal_locks, deposit_scanner_state, audit_logs, exchange_funding) | Same schema; map to JPA entities or keep raw SQL where needed (e.g. complex ledger updates) | ✅ Yes | ### 2.8 Security & Middleware | Current (Node) | Spring Boot / Java Equivalent | Possible? | |----------------|------------------------------|-----------| | CORS (origin, credentials) | `WebMvcConfigurer` or `@CrossOrigin` | ✅ Yes | | Helmet-like (security headers) | Spring Security headers | ✅ Yes | | Rate limiting (API + stricter login) | Bucket4j, or Spring Cloud Gateway, or custom filter with in-memory/Redis | ✅ Yes | | JWT auth middleware | Spring Security JWT filter or OAuth2 Resource Server | ✅ Yes | | Audit log (sensitive actions) | `@Aspect` or filter/interceptor writing to `audit_logs` table | ✅ Yes | ### 2.9 Configuration & Environment | Current (Node) | Spring Boot / Java Equivalent | Possible? | |----------------|------------------------------|-----------| | .env / ENV_FILE (DATABASE_URL, JWT_SECRET, TRON_*, POLYGON_*, etc.) | `application.yml` / `application-{profile}.yml` and `spring.config.additional-location` or env vars | ✅ Yes | | Config (port, apiPrefix, blockchain, rateLimit, withdrawal limits) | `@ConfigurationProperties` classes | ✅ Yes | ### 2.10 Scripts & Operations | Current (Node) | Spring Boot / Java Equivalent | Possible? | |----------------|------------------------------|-----------| | seed-hot-wallets (mnemonic → derive & store hot wallets) | `CommandLineRunner` or standalone Spring app / script using same services | ✅ Yes | | migrate (run schema) | Flyway/Liquibase on startup or Maven/Gradle task | ✅ Yes | | Health check GET /health | Spring Boot Actuator `management.endpoints.web.exposure.include=health` | ✅ Yes | --- ## 3. External / Blockchain Dependencies - **TRON**: TronWeb is JavaScript. In Java you use: - **TronGrid HTTP API** (same backend TronWeb calls), or - A Java TRON SDK (e.g. **tron4j**, or official grpc-client if available). - **Polygon (EVM)**: **web3j** is the standard Java library for Ethereum and EVM chains (Polygon). - **BIP39 / HD**: Java libs (bitcoinj, or dedicated BIP39) cover mnemonic and derivation; TRON path 195' may need a small adapter or a lib that supports custom curves/paths. None of these block the migration; they only require choosing the right Java libraries and possibly a thin adapter layer for TRON (HTTP or SDK). --- ## 4. Conclusion - **All functionalities** listed above (auth, wallet, balances, deposit addresses, transactions, internal transfer, withdrawals, deposit monitoring, HD wallet, encryption, rate limiting, audit, config, scripts) **can be implemented in Spring Boot** without losing any of the behaviour you defined at the beginning. - The **same PostgreSQL schema** can be kept; the **same API contract** (paths, request/response bodies) can be preserved so the **Flutter app does not need to change** (only the base URL if needed). - The only “translation” is from Node/TS libraries to Java equivalents (TronWeb → TronGrid HTTP or Java TRON SDK; ethers → web3j; bip39/ethers → Java BIP39/bitcoinj/web3j). --- ## 5. Suggested Migration Phases (When You Decide to Proceed) 1. **Phase 1**: New Spring Boot project; DB connection; Flyway with current schema; implement auth (register, login, refresh, 2FA) and wallet API (wallet-types, balances, deposit-address, transactions). Keep Node backend running in parallel until parity. 2. **Phase 2**: Internal transfer + withdrawal (with HD/hot wallet and TRON/Polygon in Java). 3. **Phase 3**: Deposit monitor as scheduled job; seed-hot-wallets script; rate limiting and audit. 4. **Phase 4**: Switch Flutter to new base URL; retire Node backend after tests. If you want to proceed with the refonte, the next step is Phase 1 (scaffold Spring Boot and replicate auth + wallet APIs) while keeping your current backend unchanged until the new one is validated.