141 lines
9.4 KiB
Markdown
141 lines
9.4 KiB
Markdown
# 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.
|