games_app/TESTING.md
2026-06-29 15:01:23 +02:00

272 lines
17 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Testing Deposit and Withdraw
This guide explains how to test deposits and withdrawals **without real crypto** first, then how to test with **real crypto from Binance** (or any exchange) once you’re confident.
---
## Part 1: Test with no real coin (testnet)
Use **testnets** so you never spend real money. The app stays the same; only the **backend** is pointed at test networks.
### 1.1 Switch the backend to testnet
In your backend `.env` (or a copy like `.env.testnet`), set:
```env
# TRON Shasta testnet (test TRX and USDT)
TRON_NODE_URL=https://api.shasta.trongrid.io
TRON_CONFIRMATIONS=20
# Shasta testnet USDT (TRC20) contract – required to detect USDT deposits on testnet
USDT_TRC20_CONTRACT=TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs
# Polygon Amoy testnet (test USDC)
POLYGON_RPC_URL=https://rpc-amoy.polygon.technology
USDC_POLYGON_CONTRACT=0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582
POLYGON_CONFIRMATIONS=64
```
- Keep your existing `DATABASE_URL`, `JWT_SECRET`, `ENCRYPTION_KEY`, `PLATFORM_MNEMONIC` (this mnemonic is only for testnet; use a **new** one for mainnet later).
**Use the testnet env file when running the backend:**
Put your testnet variables in **`.env.testnet`** in the **repo root** (same folder as `backend/`). From the **backend** directory, run:
```bash
npm run dev:testnet
```
This loads `../.env.testnet` so the backend uses Shasta/Amoy and your testnet contract settings. For mainnet, use `npm run dev` (loads `.env` from the backend directory).
If you prefer to keep `.env.testnet` inside `backend/`, use `ENV_FILE=.env.testnet npm run dev` instead (from the backend directory).
### 1.2 Get test tokens from faucets
Your “app deposit address” is the one shown in the app: **Deposit** → choose **TRX** or **USDC** → copy the address (or scan QR). Paste it into the faucet (or send it to the bot) as the recipient.
**TRX (TRON Shasta)** — try in this order if one is unavailable:
1. **Official TRON Shasta faucet (recommended):**
[https://shasta.tronex.io/join/getJoinPage](https://shasta.tronex.io/join/getJoinPage)
Paste your app TRX deposit address, complete the reCAPTCHA, click **Obtain**. Limit: once per address per 24 hours.
2. **Telegram / Discord bot (reliable backup):**
Join [TRON Developer Group (Telegram)](https://t.me/TronOfficialDevelopersGroupEn) or [TRON Discord](https://discord.com/invite/hqKvyAM). In the chat, type:
`!shasta YOUR_TRX_ADDRESS`
(e.g. `!shasta TEoXicFpDSFCdYAkCiHDdS1Tx7gN81iQXu`).
The bot sends 5,000 Shasta TRX to that address (max once per 24 hours per address). Type `!help` for other commands.
3. **Other faucets:**
[Triangle Shasta](https://faucet.triangleplatform.com/tron/shasta) — sometimes shows “Faucet is unavailable”; try again later or use the options above.
**USDT (TRON Shasta)** — test USDT on the same Shasta testnet:
1. **Telegram / Discord bot (recommended):**
In the same [TRON Developer Group (Telegram)](https://t.me/TronOfficialDevelopersGroupEn) or [TRON Discord](https://discord.com/invite/hqKvyAM), type:
`!shasta_usdt YOUR_TRON_ADDRESS`
(e.g. `!shasta_usdt TEoXicFpDSFCdYAkCiHDdS1Tx7gN81iQXu`).
The bot sends **5,000 test USDT** (Shasta TRC20) to that address. Use your app’s **USDT deposit address** from **Deposit → USDT (TRC20)**.
2. **Same TRON address:** Your app’s TRX and USDT (TRC20) on Shasta use the **same TRON address**; the backend credits the correct wallet (TRX vs USDT) based on the token.
3. **Bot limit:** The Telegram/Discord bot applies a **24h limit per requester** (your Telegram or Discord account), not per recipient address. So “You have requested 5000 coins (shasta) in the last 24 hours” means *you* have already used your allowance (e.g. with `!shasta` for one address). Creating another app account and using its address does **not** bypass the limit—the bot still sees the same requester. You must **wait ~24 hours** from your first request, or use a different Telegram/Discord account to request for another address. For testing both TRX and USDT on the same app account, request **USDT first** (`!shasta_usdt`) then TRX (`!shasta`) if the bot allows both within the limit.
**USDC (Polygon Amoy):**
- [Circle faucet](https://faucet.circle.com) — choose **Polygon Amoy**, then use your app’s USDC (Polygon) deposit address.
### 1.3 Test deposit (no real coin)
1. In the app: **Deposit** → choose **TRX**, **USDT (TRC20)**, or **USDC** (Polygon Amoy).
2. Copy the address (or use the QR code). For TRX and USDT on Shasta, the **same TRON address** is used; the backend detects which token was sent.
3. Get test tokens:
- **TRX:** faucet or `!shasta YOUR_ADDRESS` in Telegram/Discord.
- **USDT:** `!shasta_usdt YOUR_ADDRESS` in Telegram/Discord (see 1.2).
- **USDC:** Circle faucet (Polygon Amoy).
4. Wait 1–2 minutes. The backend’s deposit monitor runs about every 60 seconds and will credit your balance after confirmations.
5. Open **Wallet** (or pull to refresh); your balance should increase.
6. In **Wallet** → **See more** (transactions), you should see the deposit with status **completed**.
### 1.4 Test withdraw (no real coin) — TRX, USDT, USDC
Withdrawals are sent from the backend’s **hot wallet**. You must create hot wallets and fund them on the **same testnet** (Shasta for TRX/USDT, Amoy for USDC) before withdrawals will succeed.
#### Step 1: Create hot wallets (one-time)
From the **backend** directory, run:
```bash
npm run seed-hot-wallets:testnet
```
This derives one TRON address (used for both TRX and USDT) and one Polygon address (for USDC) from your `PLATFORM_MNEMONIC`, saves them in the database, and prints the addresses. If hot wallets already exist, it skips and still prints the addresses.
#### Step 2: Fund the hot wallet addresses on testnet
You must send **test** tokens to these addresses so the backend can pay out withdrawals.
| Asset | Network | Hot wallet address (printed by script) | How to fund |
|-------|--------|----------------------------------------|-------------|
| **TRX** | Shasta | Same TRON address for TRX & USDT | `!shasta HOT_WALLET_TRON_ADDRESS` in Telegram/Discord, or [shasta.tronex.io](https://shasta.tronex.io/join/getJoinPage). |
| **USDT** | Shasta | Same TRON address as TRX | `!shasta_usdt HOT_WALLET_TRON_ADDRESS` (need TRX on that address for gas). So fund TRX first, then USDT. |
| **USDC** | Amoy | Polygon (0x...) address | [Circle faucet](https://faucet.circle.com) → choose **Polygon Amoy** → paste the hot wallet’s Polygon address. |
- **TRX:** The hot wallet needs TRX to send both TRX and USDT withdrawals (TRX pays for gas on Shasta).
- **USDT:** Send test USDT to the **same** TRON hot wallet address; ensure it already has some TRX for gas.
- **USDC:** Send test USDC to the hot wallet’s **Polygon** address on Amoy.
#### Step 3: Get a destination address (where you want to receive the withdrawal)
Use a **different** address from the hot wallet — e.g. your own wallet on the same testnet:
- **TRX & USDT:** A TRON Shasta address (e.g. create a second address in TronLink set to Shasta, or use a friend’s Shasta address).
- **USDC:** A Polygon Amoy address (e.g. MetaMask connected to Amoy; copy the “receive” address).
You can also use the **first user’s app deposit address** as the destination (e.g. withdraw from user 2 to user 1’s TRX address) to verify the flow.
#### Step 4: Withdraw in the app
1. **Backend** must be running with testnet: `npm run dev:testnet` (from backend).
2. In the **app**: log in as a user that has test balance (from earlier deposits).
3. Go to **Withdraw** → choose **TRX**, **USDT**, or **USDC**.
4. Paste the **destination address** (from Step 3). Ensure the **network** matches (TRX → TRON, USDT → TRC20/Shasta, USDC → Polygon Amoy).
5. Enter **amount** (e.g. a small amount ≤ your balance).
6. Enter your **2FA code** (TOTP) — see [How to get the 2FA code](#how-to-get-the-2fa-code) below if you haven’t set it up yet.
7. Submit. The backend sends from the hot wallet to that address.
8. Check the destination wallet or a block explorer (e.g. [Shasta Tronscan](https://shasta.tronscan.org), [Amoy on Oklink](https://www.oklink.com/amoy)) to confirm the tx.
**If withdrawal fails:**
- **“Withdrawal temporarily unavailable”** → No active hot wallet for that asset. Run `npm run seed-hot-wallets:testnet` and ensure the DB has a row per wallet type.
- **Transaction fails on chain** → Hot wallet has insufficient balance or gas. Fund the hot wallet (Step 2) and try again.
When testnet deposit and withdraw work for all three assets, you’re ready for real crypto (Part 2).
---
### 1.5 Withdraw to “exchange” (testnet, no real coin) — TRX, USDT, USDC
This is the same as [1.4](#14-test-withdraw-no-real-coin--trx-usdt-usdc) but framed as **“user withdraws from your platform to an exchange”**. On testnet there is no real exchange; you use **your own testnet address** (or a second wallet) as the “exchange” destination. No real money is used.
#### Checklist (all three: TRX, USDT, USDC)
| Step | What to do |
|------|------------|
| **1. Backend on testnet** | Run backend with testnet env: `npm run dev:testnet` (from `backend/`). Ensure `.env.testnet` has Shasta + Amoy URLs and contracts (see [1.1](#11-switch-the-backend-to-testnet)). |
| **2. Seed hot wallets** | One-time: from `backend/`, run `npm run seed-hot-wallets:testnet`. Note the two printed addresses: **TRX & USDT (Shasta)** and **USDC (Polygon Amoy)**. |
| **3. Fund hot wallets** | Send **test** tokens to those addresses so the platform can pay withdrawals. See table below. |
| **4. User has balance** | In the app, the user must have balance (e.g. from [1.3](#13-test-deposit-no-real-coin) deposits or from **Transfer** from another user). |
| **5. Destination address** | For “withdraw to exchange” you need a **destination address on the same testnet**. Use e.g. a second TRON/Polygon wallet you control (TronLink Shasta, MetaMask Amoy), or the app’s own deposit address for another user. **Do not** use the hot wallet address. |
| **6. Withdraw in app** | App → **Withdraw** → choose **TRX**, **USDT**, or **USDC** → paste destination address → amount → 2FA → submit. |
| **7. Verify** | Check the destination on a block explorer (Shasta: [shasta.tronscan.org](https://shasta.tronscan.org), Amoy: [amoy.polygonscan.com](https://amoy.polygonscan.com)) to see the incoming tx. |
#### How to fund hot wallets (testnet, no real coin)
| Asset | Network | Hot wallet is… | How to fund (test only) |
|-------|--------|----------------|--------------------------|
| **TRX** | Shasta | Same TRON address for TRX & USDT | `!shasta HOT_WALLET_TRON_ADDRESS` in [Telegram](https://t.me/TronOfficialDevelopersGroupEn) or Discord, or [shasta.tronex.io](https://shasta.tronex.io/join/getJoinPage). |
| **USDT** | Shasta | Same TRON address as TRX | `!shasta_usdt HOT_WALLET_TRON_ADDRESS` in Telegram/Discord. That address must already have some TRX for gas. |
| **USDC** | Amoy | Polygon `0x…` address | [Circle faucet](https://faucet.circle.com) → **Polygon Amoy** → paste hot wallet’s Polygon address. |
#### Example: end-to-end test for each asset
**TRX (Shasta)**
1. Fund TRX hot wallet: `!shasta <TRON_HOT_ADDRESS>`.
2. In app: get TRX balance (deposit to your app TRX address from faucet, or use Transfer).
3. Get a destination: e.g. create a second Shasta address in TronLink, or use a friend’s.
4. App → Withdraw → TRX → paste destination → amount (e.g. 100) → 2FA → submit.
5. Check [shasta.tronscan.org](https://shasta.tronscan.org) for that destination address.
**USDT (Shasta)**
1. Fund TRX hot wallet first (TRX pays gas). Then fund USDT: `!shasta_usdt <TRON_HOT_ADDRESS>`.
2. In app: get USDT balance (deposit or Transfer).
3. Same TRON destination as above (Shasta).
4. App → Withdraw → USDT (TRC20) → paste destination → amount → 2FA → submit.
5. Check Shasta Tronscan for the USDT transfer to the destination.
**USDC (Polygon Amoy)**
1. Fund USDC hot wallet: Circle faucet → Polygon Amoy → hot wallet’s Polygon address.
2. In app: get USDC balance (deposit from Circle faucet to your app USDC address, or Transfer).
3. Get a destination: e.g. MetaMask on Amoy → copy “receive” address.
4. App → Withdraw → USDC (Polygon) → paste destination → amount → 2FA → submit.
5. Check [amoy.polygonscan.com](https://amoy.polygonscan.com) for the destination address.
**Important:** On testnet, “exchange” is just any valid address on that network. For real withdrawals to Binance (or another exchange), use the exchange’s **mainnet** deposit address and switch the backend to mainnet (Part 2).
---
#### How to get the 2FA code
The app uses **TOTP** (time-based one-time password). You need to **enable 2FA once**, then use an **authenticator app** to get the 6-digit code each time you withdraw (or log in, if enabled).
1. **Enable 2FA (one-time)**
In the app: open **Account** (bottom tab) → tap **Two-factor authentication (2FA)**.
The app shows a **QR code**. Open an authenticator app on your phone (e.g. **Google Authenticator** or **Microsoft Authenticator**), add a new account by scanning that QR code, then enter the **6-digit code** the authenticator shows and tap **Enable 2FA**.
2. **Get the code when withdrawing**
When you are on the **Withdraw** screen, open the same authenticator app, find the entry for this app, and type the **current 6-digit code** (it changes about every 30 seconds). Enter that code in the “2FA Code” field and submit.
**Troubleshooting: I see deposits on Shasta Tronscan but the app shows 0 balance**
1. **Confirm the backend is using Shasta**
When you start the backend you should see: `TRON node: https://api.shasta.trongrid.io`.
If it shows `https://api.trongrid.io`, the backend is on **mainnet** and will not see Shasta transactions. Fix your `.env`: set `TRON_NODE_URL=https://api.shasta.trongrid.io` and restart.
2. **Restart the backend**
After changing `.env`, restart the backend so it loads Shasta. The deposit monitor runs about every 60 seconds; after one or two runs, balances should update.
3. **Scanner state after switching network**
If you previously ran the backend on mainnet, the deposit scanner may have saved a mainnet block number. The code now resets the scan range when that would be ahead of the current chain, so after pulling the latest backend and restarting, Shasta deposits should be picked up.
---
## Part 2: Test with real crypto (e.g. from Binance)
Only do this **after** testnet tests succeed. Use **small amounts** first.
### 2.1 Switch the backend back to mainnet
In `.env`, use mainnet values:
```env
TRON_NODE_URL=https://api.trongrid.io
POLYGON_RPC_URL=https://polygon-rpc.com
USDC_POLYGON_CONTRACT=0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359
# Leave USDT_TRC20_CONTRACT unset (mainnet USDT uses DB/default)
```
Restart the backend. For production you should also use a **new** `PLATFORM_MNEMONIC` (do not reuse the one used on testnet).
### 2.2 Deposit real crypto from Binance
1. In the **app**: **Deposit** → choose **TRX**, **USDT**, or **USDC**.
2. Copy the **exact** deposit address (and note the **network** shown: TRON, TRON (TRC20), or Polygon).
3. In **Binance**:
- **Withdraw** → select the **same asset** (TRX, USDT, or USDC).
- Select the **same network** as in the app:
- **TRX** → **TRON**
- **USDT** → **TRON (TRC20)** — do **not** use ERC20 or other networks.
- **USDC** → **Polygon** — do **not** use Ethereum or other networks.
- Paste your **app deposit address** (no memo needed for these).
- Send a **small amount** first (e.g. minimum or a few dollars).
4. Wait for confirmations. The backend will credit your balance (usually within a few minutes for TRON; Polygon can take longer).
5. Check **Wallet** and **Transactions** in the app to confirm the deposit.
**Important:** Wrong network (e.g. USDT on ERC20 instead of TRC20) can lead to permanent loss. Always double-check network in the app and in Binance.
### 2.3 Withdraw real crypto (e.g. back to Binance)
1. In **Binance**: **Deposit** for the asset (e.g. TRX or USDT) → choose the **same network** (TRON / TRC20) → copy the **deposit address** (and memo if Binance shows one for that asset).
2. In the **app**: **Withdraw** → choose the same asset → paste the **Binance deposit address** → enter amount → enter **2FA** → confirm.
3. The backend sends from its hot wallet to that address. Check Binance deposit history and the app’s transaction list.
For production, withdrawals require the backend’s **hot wallet** to be funded and configured (see main [README](README.md#hot-wallet)).
---
## Quick reference
| Goal | Backend env | Where to get funds | Where to send (deposit) / receive (withdraw) |
|-----------------------------|-----------------|---------------------------|----------------------------------------------|
| Test **no real coin** | Testnet URLs | Faucets (Shasta, Amoy) | App deposit address / your testnet wallet |
| Test **real crypto** | Mainnet URLs | Binance (or other exchange) | App deposit address / Binance deposit address |
Always match **asset + network** between the app and the exchange (TRX→TRON, USDT→TRC20, USDC→Polygon).