Fix fresh-DB migration order for candle_predict_auto_settings, fail loudly on migrate errors, honor DATABASE_URL from .env, add Docker DNS resolver for nginx upstreams, and document VPS deploy steps. Co-authored-by: Cursor <cursoragent@cursor.com>
266 lines
11 KiB
Markdown
266 lines
11 KiB
Markdown
# Prediqo
|
||
|
||
**Prediqo** is an online prediction games platform (web + mobile) where players use **cryptocurrencies** as the payment method. The stack includes a crypto wallet layer (**USDT TRC20**, **TRX**, **USDC Polygon**) managed by the platform, ready for game integration.
|
||
|
||
## Monorepo layout
|
||
|
||
| Folder | Role |
|
||
|--------|------|
|
||
| `backend/` | Node.js API (auth, wallet, ledger, admin, games-ready) |
|
||
| `prediqo_mobile/` | Flutter mobile app (play + wallet) |
|
||
| `prediqo_web/` | React web app (platform admin + player experience) |
|
||
|
||
## Architecture
|
||
|
||
- **Mobile**: Flutter (`prediqo_mobile`) — clean architecture, BLoC, Dio, secure storage
|
||
- **Web**: React + Vite (`prediqo_web`) — admin modules today; player/games modules planned
|
||
- **Backend**: Node.js + TypeScript + Express
|
||
- **Database**: PostgreSQL (users, wallets, ledger, transactions, audit logs)
|
||
|
||
### Features
|
||
|
||
- **User management**: Registration, login, JWT + refresh tokens, 2FA (TOTP)
|
||
- **HD wallet**: BIP39/BIP44; unique deposit address per user per asset
|
||
- **Ledger**: Internal ledger as source of truth; blockchain used for confirmation only
|
||
- **Deposits**: Monitoring with configurable confirmations (TRON: 20, Polygon: 64)
|
||
- **Withdrawals**: Hot wallet signing, balance lock, optional 2FA
|
||
- **Security**: AES-256 for private keys, rate limiting, audit logs
|
||
|
||
---
|
||
|
||
## Backend
|
||
|
||
### Prerequisites
|
||
|
||
- Node.js 18+
|
||
- PostgreSQL
|
||
|
||
### Setup (local)
|
||
|
||
```bash
|
||
cd backend
|
||
cp .env.example .env
|
||
# Edit .env: DATABASE_URL, JWT_SECRET, ENCRYPTION_KEY (32-byte hex), PLATFORM_MNEMONIC (24-word BIP39)
|
||
npm install
|
||
npm run migrate
|
||
npm run dev
|
||
```
|
||
|
||
**Important:** The `.env` file can be in `backend/` or the repo root; both are loaded. `DATABASE_URL` must match your PostgreSQL user and password.
|
||
|
||
**If you get "password authentication failed" (local PostgreSQL):**
|
||
- Use the same user/password you use to log in to PostgreSQL (often user `postgres` and the password you set during install).
|
||
- If your password contains special characters (`@`, `#`, `%`, `:`, `/`), URL-encode them in `DATABASE_URL` (e.g. `@` → `%40`, `#` → `%23`).
|
||
- Test the connection: `npm run db:test` (from `backend/`). Then try: `psql -U postgres -d crypto_wallet -h localhost` and enter your password to confirm it works.
|
||
|
||
Example `backend/.env`:
|
||
|
||
```
|
||
DATABASE_URL=postgresql://user:password@localhost:5432/crypto_wallet
|
||
JWT_SECRET=your-super-secret-jwt-key-min-32-chars
|
||
ENCRYPTION_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
|
||
PLATFORM_MNEMONIC=your twenty four word mnemonic phrase here ...
|
||
```
|
||
|
||
**PLATFORM_MNEMONIC:** Must be a valid BIP39 phrase (12 or 24 words from the [BIP39 English wordlist](https://github.com/bitcoin/bips/blob/master/bip-0039/english.txt)). Do not use the placeholder; generate one once and keep it secret. Example (from project root): `cd backend && node -e "console.log(require('bip39').generateMnemonic(256))"` — then put the output in `.env` as `PLATFORM_MNEMONIC=word1 word2 ... word24`.
|
||
|
||
API runs at `http://localhost:4000`. Prefix: `/api/v1`.
|
||
|
||
### Environment
|
||
|
||
| Variable | Description |
|
||
|--------|-------------|
|
||
| `DATABASE_URL` | PostgreSQL connection string |
|
||
| `JWT_SECRET` | Secret for JWT (min 32 chars) |
|
||
| `ENCRYPTION_KEY` | 32-byte hex (64 chars) for AES-256 |
|
||
| `PLATFORM_MNEMONIC` | BIP39 mnemonic (12 or 24 words) for HD wallet; must be from the standard wordlist (see below) |
|
||
| `TRON_NODE_URL` | TronGrid API URL |
|
||
| `POLYGON_RPC_URL` | Polygon RPC URL |
|
||
| `USDC_POLYGON_CONTRACT` | USDC contract on Polygon |
|
||
| `USDT_TRC20_CONTRACT` | Optional override for USDT TRC20 (e.g. testnet token) |
|
||
|
||
### Testing with testnets (no real crypto)
|
||
|
||
You can run the backend against **testnets** to test deposits and withdrawals with free test tokens, then switch back to mainnet for real crypto.
|
||
|
||
1. **Use a separate `.env` (e.g. copy to `.env.testnet`) or override these in your current `.env`:**
|
||
- **TRON (Shasta testnet):**
|
||
`TRON_NODE_URL=https://api.shasta.trongrid.io`
|
||
Optionally set `USDT_TRC20_CONTRACT` to a Shasta test USDT token address if you use one (otherwise you can test TRX only).
|
||
- **Polygon (Amoy testnet):**
|
||
`POLYGON_RPC_URL=https://rpc-amoy.polygon.technology`
|
||
`USDC_POLYGON_CONTRACT=0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582`
|
||
(Official Circle USDC on Polygon Amoy; see [Circle USDC contract addresses](https://developers.circle.com/stablecoins/usdc-contract-addresses).)
|
||
2. **Get test tokens from faucets:**
|
||
- **TRON Shasta (test TRX):** e.g. [shasta.tronex.io](https://shasta.tronex.io/) or [faucet.triangleplatform.com/tron/shasta](https://faucet.triangleplatform.com/tron/shasta). Send your app’s TRON deposit address (from the Deposit screen) to receive test TRX.
|
||
- **Polygon Amoy (test USDC):** e.g. [faucet.circle.com](https://faucet.circle.com) (Circle) or other Amoy faucets. Use your app’s Polygon deposit address.
|
||
3. **Run the backend** with the testnet env; use the app to deposit (send test tokens to the shown address) and wait for the deposit monitor to credit the ledger. Then test withdrawals.
|
||
4. **When ready for production:** switch `.env` back to mainnet values (`TRON_NODE_URL=https://api.trongrid.io`, `POLYGON_RPC_URL=https://polygon-rpc.com`, `USDC_POLYGON_CONTRACT=0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359`, and remove or leave `USDT_TRC20_CONTRACT` unset). Use a **new** `PLATFORM_MNEMONIC` for production (do not reuse testnet mnemonic with real funds).
|
||
|
||
#### How to test deposit (exchange/wallet → platform)
|
||
|
||
1. **Get your platform deposit address**
|
||
- In the app: log in → **Deposit** → choose asset (e.g. TRX or USDC).
|
||
- Copy the address (and optionally use the QR code).
|
||
|
||
2. **Send funds to that address**
|
||
- **From an exchange:** In the exchange’s withdraw flow, choose the same network (e.g. TRON or Polygon), paste your **platform deposit address**, enter amount, confirm. (Use testnet on the exchange if it supports it; otherwise use mainnet with a small amount.)
|
||
- **From a wallet (e.g. TronLink, MetaMask):** Send the same asset on the same network to the **platform deposit address**.
|
||
- **Testnet only:** Use a faucet (see above) and enter your **platform deposit address** as the recipient; the faucet sends test tokens to your platform.
|
||
|
||
3. **Wait for the platform to credit the balance**
|
||
- The backend runs a **deposit monitor** every **60 seconds** (first run ~10 s after startup). It scans the chain for incoming transfers to your deposit address and credits your in-app balance once the required confirmations are met (e.g. 20 for TRON, 64 for Polygon).
|
||
- Refresh or reopen the dashboard; your balance should update after the next monitor run.
|
||
|
||
4. **Check the transaction**
|
||
- **Transactions** in the app should show the deposit with status **completed**.
|
||
|
||
#### How to test withdrawal (platform → exchange/wallet)
|
||
|
||
1. **Have balance and a hot wallet**
|
||
- Your in-app balance must be > 0 (from a prior deposit or a manual ledger credit for testing).
|
||
- Withdrawals are paid from a **hot wallet**. Ensure one is configured per asset (see [Hot wallet](#hot-wallet)).
|
||
|
||
2. **Get the destination address**
|
||
- **Exchange:** In the exchange, use “Deposit” for the same asset/network and copy the **deposit address** (and optional memo/tag if required).
|
||
- **Your own wallet:** Use the receiving address from TronLink, MetaMask, etc., on the same network.
|
||
|
||
3. **Withdraw in the app**
|
||
- In the app: **Withdraw** → choose asset → paste **destination address** → enter amount → enter **2FA code** → submit.
|
||
- The backend locks balance, sends from the hot wallet to that address, then marks the withdrawal completed.
|
||
|
||
4. **Confirm on chain**
|
||
- Check the destination wallet or exchange deposit history; the funds should appear after network confirmations. You can also look up the transaction ID (if shown in the app or logs) on a block explorer (e.g. Tronscan, Polygonscan).
|
||
|
||
In production, “exchange” is the same idea: **deposit** = user withdraws from exchange to the app’s deposit address; **withdraw** = user enters the exchange’s deposit address and the app sends from the platform to the exchange.
|
||
|
||
### Hot wallet
|
||
|
||
To enable withdrawals, insert a hot wallet per asset (e.g. via script or admin):
|
||
|
||
- Derive key from `PLATFORM_MNEMONIC` at a dedicated index (e.g. 0 for hot).
|
||
- Encrypt private key with app encryption.
|
||
- Insert into `hot_wallets` (wallet_type_id, address, encrypted_private_key).
|
||
|
||
---
|
||
|
||
## Docker deployment (VPS)
|
||
|
||
**Guide complet (français) :** [docs/DEPLOY-VPS.md](docs/DEPLOY-VPS.md)
|
||
|
||
Résumé — depuis la racine du dépôt :
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
# Éditer .env (secrets, PostgreSQL, domaine, SMTP, INITIAL_SETUP_TOKEN)
|
||
|
||
# HTTPS (Let's Encrypt DNS, ports 9080/9443) :
|
||
npm run ssl:dns-init # une fois — validation TXT DNS
|
||
npm run phase-b:up:https # build + démarrage
|
||
|
||
# Premier admin : https://prediqo.redirectme.net:9443/setup
|
||
```
|
||
|
||
Commandes : `npm run phase-b:status` · `phase-b:logs` · `phase-b:restart` · `phase-b:down`
|
||
|
||
### Run with Docker Compose (legacy / local)
|
||
|
||
```bash
|
||
cd backend
|
||
docker build -t crypto-wallet-api .
|
||
```
|
||
|
||
### Local migrate when using Docker Postgres
|
||
|
||
If Postgres is running in Docker and you run migrations from the host:
|
||
|
||
```bash
|
||
cd backend
|
||
# In .env use: DATABASE_URL=postgresql://cryptouser:cryptopass@localhost:5432/crypto_wallet
|
||
npm run migrate
|
||
```
|
||
|
||
---
|
||
|
||
## Prediqo Mobile (Flutter)
|
||
|
||
### Setup
|
||
|
||
```bash
|
||
cd prediqo_mobile
|
||
flutter pub get
|
||
```
|
||
|
||
Configure API base URL:
|
||
|
||
- Default: `http://10.0.2.2:4000` (Android emulator).
|
||
- For iOS simulator: `http://127.0.0.1:4000`.
|
||
- Run with: `flutter run --dart-define=API_BASE_URL=http://YOUR_IP:4000`
|
||
|
||
### Structure
|
||
|
||
- **core**: API client (Dio + auth interceptor), secure storage, theme
|
||
- **data**: Models, repository implementations
|
||
- **features**: auth (login, register, 2FA), wallet (dashboard, deposit, withdraw)
|
||
- **BLoC**: AuthBloc, WalletBloc
|
||
|
||
### Screens
|
||
|
||
- Login / Register
|
||
- Dashboard (balances, recent transactions, deposit/withdraw entry)
|
||
- Deposit (QR + copy address per asset)
|
||
- Withdraw (asset, address, amount, 2FA code)
|
||
- 2FA setup (QR for TOTP)
|
||
|
||
---
|
||
|
||
## Prediqo Web (React)
|
||
|
||
### Setup
|
||
|
||
```bash
|
||
cd prediqo_web
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
Configure API: copy `prediqo_web/.env.example` → `.env` with `VITE_API_BASE_URL=http://localhost:4000`.
|
||
|
||
**Modules (current & planned):**
|
||
- **Platform** — user management, settings, overview (implemented)
|
||
- **Player** — wallet + prediction games UI (to mirror mobile)
|
||
|
||
---
|
||
|
||
## Deposit flow
|
||
|
||
1. User opens Deposit for an asset; app shows unique address (and QR).
|
||
2. User sends crypto to that address from an exchange or external wallet.
|
||
3. Backend deposit monitor polls blockchain; after required confirmations, ledger is credited and a transaction record is created.
|
||
|
||
## Withdrawal flow
|
||
|
||
1. User enters amount, destination address, and 2FA code.
|
||
2. Backend checks balance, locks amount, signs from hot wallet, broadcasts tx.
|
||
3. Ledger is updated after processing; user sees status in app.
|
||
|
||
---
|
||
|
||
## Security
|
||
|
||
- Passwords hashed with Argon2.
|
||
- Private keys encrypted with AES-256 (key from env).
|
||
- 2FA (TOTP) for withdrawals and sensitive actions.
|
||
- Rate limiting on login and API.
|
||
- Audit log for login, deposits, withdrawals, admin actions.
|
||
|
||
---
|
||
|
||
## Future upgrades (from spec)
|
||
|
||
- MPC/HSM instead of single HD wallet
|
||
- Multi-sig or MPC for hot wallet
|
||
- Policy engine for withdrawal approvals
|
||
- Real-time monitoring and anomaly detection
|
||
- Double-entry accounting and fraud detection
|