nick/nick-doc
3
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: sync from backend 3e9a2f2 — BSC Testnet tUSDT rail

Browse Source
This commit is contained in:
Siavash Sameni
2026-06-06 08:20:55 +04:00
parent cafef04a75
commit 641334a2e5
3 changed files with 23 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
04 - Flows/Payment Flow - Scanner.md
View File

@@ -6,7 +6,7 @@ created: 2026-05-30
# Payment Flow — AMN Pay Scanner (In-House)
> **Last updated:** 2026-06-06 — documented backend/frontend `2.8.115` and scanner `0.1.10` BSC Testnet rail alignment.
> **Last updated:** 2026-06-06 — documented backend/frontend `2.8.116` and scanner BSC Testnet tUSDT rail correction.
End-to-end payment flow using the in-house AMN Pay Scanner, replacing the Request Network integration. The scanner is a separate microservice; the backend talks to it over an internal HTTP API.
@@ -76,12 +76,14 @@ For dev end-to-end testing, backend and scanner must keep the chain 97 registry
| Chain id | `97` |
| Network aliases | `bsc-testnet`, `bnb-testnet`, `bsctest`, `bsc_testnet`, `binance-testnet`, `bnbt`, numeric string `97` |
| RPC fallback | `https://bsc-testnet-rpc.publicnode.com` |
| USDT test token | `0x337610d27c682E347C9cD60BD4b3b107C9d34dDd` |
| USDT test token | `0x109F54Dab34426D5477986b0460aE5dFBA65f022` |
| USDC test token | `0x64544969ed7EBf5f083679233325356EbE738930` |
| Token decimals | `18` for USDT and USDC |
| Default confirmation floor | `5` |
Backend `2.8.115+` uses this same token address in both the Request Network/scanner intent registry and the legacy `BSCTransactionVerifier` path. This matters because `/api/payment/request-network/intents` resolves the buyer's selected chain/token before asking scanner to watch, while older wallet-direct verification endpoints call `BSCTransactionVerifier.verifyTransfer()` directly. A mismatch between these two registries will either create scanner intents for a token that the buyer does not pay, or verify the wrong ERC-20 contract after payment.
Backend `2.8.116+` uses this same token address in both the Request Network/scanner intent registry and the legacy `BSCTransactionVerifier` path. This matters because `/api/payment/request-network/intents` resolves the buyer's selected chain/token before asking scanner to watch, while older wallet-direct verification endpoints call `BSCTransactionVerifier.verifyTransfer()` directly. A mismatch between these two registries will either create scanner intents for a token that the buyer does not pay, or verify the wrong ERC-20 contract after payment.
Backend `2.8.116+` also passes an explicit `scannerContext` (`paymentId`, `chainId`, `tokenSymbol`, `tokenAddress`, `destination`) into AMN scanner intent registration. This prevents PG-only or partially hydrated payment reads from falling back to the global merchant reference and creating mainnet/default-style scanner intents such as `undefined-c56-USDC`.
If a live dev stack still waits for `200` confirmations on chain 97, check the admin runtime setting `confirmation_threshold:97`. Built-in default is now `5`, but a previously persisted admin value above the floor still wins until updated.

8
08 - Operations/Scanner Operations.md
View File

@@ -151,6 +151,14 @@ Edit `tokens.json`. Each entry:
Token registry is used only for populating `tokenSymbol` and `decimals` in the `checkoutBlock` response. Omitting a token does not break scanning — it just leaves those fields empty.
For dev BSC Testnet, chain `97` symbol `USDT` must point at the deployed tUSDT contract:
```json
{ "chainId": 97, "address": "0x109F54Dab34426D5477986b0460aE5dFBA65f022", "symbol": "USDT", "decimals": 18, "name": "Test USDT (BSC Testnet)" }
```
After a registry change, restart/redeploy the scanner and verify through `POST /balances/check` by symbol, not only by explicit `tokenAddress`.
---
## 7. Manual webhook retry

10
09 - Audits/Activity Log.md
View File

@@ -11,6 +11,16 @@ entries on top. Maintained by agents per the rule in `../AGENTS.md`.
---
### 2026-06-06 — backend@3e9a2f2, frontend@e4fa4de, scanner@1911c3a — BSC Testnet tUSDT contract corrected
**Commits:** `3e9a2f2` `e4fa4de` `e235286` `1911c3a`
**Touched:** backend `src/services/payment/requestNetwork/tokens.json`, `src/services/payment/requestNetwork/supportedChains.json`, `src/services/payment/decentralizedPaymentService.ts`, `src/services/payment/adapters/amnPayAdapter.ts`, `src/services/payment/amnScanner/amnScannerPayInService.ts`, `scripts/smoke/bsc-testnet-payment-registry.sh`, BSC Testnet payment tests, version files; frontend `package.json`; scanner `tokens.json`, `supported-chains.json`, `contracts/testnet/USDT.sol`.
**Why:** The funded dev wallet held Test USDT at `0x109F54Dab34426D5477986b0460aE5dFBA65f022`, while backend/scanner still resolved chain 97 `USDT` to `0x337610...`. Scanner `/balances/check` returned zero for symbol `USDT` until the registry was pointed at the actual tUSDT contract. The backend adapter now also passes explicit `scannerContext` into scanner intent creation so BSC Testnet pay-ins do not fall back to mainnet/global merchant-reference defaults (`undefined-c56-USDC`).
**Verification:** backend `npm test -- --runTestsByPath __tests__/rn-in-house-checkout.test.ts __tests__/decentralized-payment-verifier.test.ts __tests__/amn-pay-adapter-intent.test.ts --runInBand`, `BASE_URL=https://dev.amn.gg bash scripts/smoke/bsc-testnet-payment-registry.sh`, `git diff --check`; scanner `go test ./...`, `git diff --check`; frontend package version sanity check. Post-deploy scanner balance check pending.
**Linked docs updated:** [[04 - Flows/Payment Flow - Scanner]], [[08 - Operations/Scanner Operations]]
---
### 2026-06-06 — backend@810098f, frontend@5ccc15c, scanner@6897195 — BSC Testnet scanner rail aligned
**Commits:** `810098f` `5ccc15c` `6897195`