From 641334a2e538a2d3694f8ad4c9ab1aa4d4455aca Mon Sep 17 00:00:00 2001 From: Siavash Sameni Date: Sat, 6 Jun 2026 08:20:55 +0400 Subject: [PATCH] =?UTF-8?q?docs:=20sync=20from=20backend=203e9a2f2=20?= =?UTF-8?q?=E2=80=94=20BSC=20Testnet=20tUSDT=20rail?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 04 - Flows/Payment Flow - Scanner.md | 8 +++++--- 08 - Operations/Scanner Operations.md | 8 ++++++++ 09 - Audits/Activity Log.md | 10 ++++++++++ 3 files changed, 23 insertions(+), 3 deletions(-) diff --git a/04 - Flows/Payment Flow - Scanner.md b/04 - Flows/Payment Flow - Scanner.md index 9a735f5..e484f7e 100644 --- a/04 - Flows/Payment Flow - Scanner.md +++ b/04 - Flows/Payment Flow - Scanner.md @@ -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. diff --git a/08 - Operations/Scanner Operations.md b/08 - Operations/Scanner Operations.md index bcc0ffb..c552db3 100644 --- a/08 - Operations/Scanner Operations.md +++ b/08 - Operations/Scanner Operations.md @@ -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 diff --git a/09 - Audits/Activity Log.md b/09 - Audits/Activity Log.md index 3d9173c..79d7a5a 100644 --- a/09 - Audits/Activity Log.md +++ b/09 - Audits/Activity Log.md @@ -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`