You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
virt/web/docs/usdt-native-payment.md

76 lines
3.0 KiB
Markdown

# Native TRC20 USDT payment
The panel creates and settles TRC20 USDT orders without another payment
application. The browser still receives an address, an exact six
decimal USDT amount, an expiry time, and displays the existing QR dialog.
## Database
Import the incremental schema before opening the feature:
```bash
mysql -u USER -p DATABASE < sql/usdt_native_payment.sql
```
Fresh installations already include the same three tables in `sql/ss.sql`:
- `usdt_wallets`: public receiving address pool and scanner state
- `usdt_payment_orders`: balance recharge payment orders
- `usdt_chain_transactions`: detected transfer evidence and settlement state
The incremental schema permanently removes the retired gateway order tables
and configuration entries. It does not remove `paylist` or user balance data.
## Admin configuration
Open `/admin/usdt` and configure:
1. One or more public TRON addresses. Never place a private key or seed phrase
in the panel.
2. The CNY value of one USDT. This is a manual settlement rate and should be
reviewed regularly.
3. Order expiry, late-payment grace, and the HTTPS TRON API endpoint.
4. An optional TronGrid API Key. Without a key, the public endpoint is used and
may be subject to stricter rate limits.
When an API Key is saved in the admin page, set `USDT_CREDENTIAL_KEY` in the
PHP-FPM and CLI environments. It must be either 32-byte Base64 or 64 hexadecimal
characters. Both environments must use the same value.
The token contract is fixed in code to Tether's TRON USDT contract
`TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t`; it cannot be changed in the admin page.
## Cron scanner
Run one scanner every minute from the project directory:
```cron
* * * * * cd /YOUR/VIRT-CLOUD/web && /usr/bin/php xcat usdtScanJob >> storage/logs/usdt-scan.log 2>&1
```
The command has its own non-blocking file lock. It requests only confirmed
TRC20 transfers sent to addresses that currently have payable orders, then
matches the fixed contract, destination address, exact atomic amount, and order
time window. Database transactions and unique event/transaction indexes prevent
duplicate balance credit. Paid registration has been removed.
The scanner uses the confirmed-transfer semantics documented by TRON:
- https://developers.tron.network/reference/get-trc20-transaction-info-by-account-address
- https://developers.tron.network/docs/confirmation-semantics
Tether's supported-protocol page lists the fixed TRON contract:
- https://tether.to/en/supported-protocols/
## Operations
- Keep the feature in test mode until a small real transfer reaches the correct
account and the order changes to `paid`.
- Alert on nonzero `errors` in the cron output and on wallet `last_error` values
shown in `/admin/usdt`.
- Transfers with no exact order match are retained as `unmatched`; they are not
automatically credited.
- The application stores public addresses only. Asset consolidation and wallet
signing should run in a separate, more strongly isolated wallet system.