From cafef04a75dff7b6b08baa9ec6d5049579dfd1e2 Mon Sep 17 00:00:00 2001 From: Siavash Sameni Date: Sat, 6 Jun 2026 07:36:32 +0400 Subject: [PATCH] =?UTF-8?q?docs:=20sync=20from=20backend=20810098f=20?= =?UTF-8?q?=E2=80=94=20BSC=20Testnet=20scanner=20rail?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 04 - Flows/Payment Flow - Scanner.md | 20 +++++++++++++++++++- 07 - Development/Environment Variables.md | 3 +++ 09 - Audits/Activity Log.md | 11 ++++++++++- 3 files changed, 32 insertions(+), 2 deletions(-) diff --git a/04 - Flows/Payment Flow - Scanner.md b/04 - Flows/Payment Flow - Scanner.md index 04289c1..9a735f5 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-05 — documented backend/frontend `2.8.79` and scanner `0.1.8` direct-address balance checks and balance watches. +> **Last updated:** 2026-06-06 — documented backend/frontend `2.8.115` and scanner `0.1.10` BSC Testnet rail alignment. 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. @@ -67,6 +67,24 @@ Authorization: Bearer The scanner responds with a `checkoutBlock` that the backend passes to the frontend. +#### BSC Testnet test rail + +For dev end-to-end testing, backend and scanner must keep the chain 97 registry in sync: + +| Field | Value | +|---|---| +| 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` | +| 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. + +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. + ### Step 2 — Frontend shows checkout The `checkoutBlock` contains everything the frontend needs to build the `ERC20FeeProxy.transferWithReferenceAndFee` calldata: diff --git a/07 - Development/Environment Variables.md b/07 - Development/Environment Variables.md index 9803ae1..34e2ca4 100644 --- a/07 - Development/Environment Variables.md +++ b/07 - Development/Environment Variables.md @@ -126,6 +126,8 @@ Request Network is the current primary payment provider. See [[PRD - Request Net | `TRANSACTION_SAFETY_REQUIRE_TX_HASH` | backend | optional | `true` | `true` | Blocks completion when provider evidence does not include a transaction hash. | | `TRANSACTION_SAFETY_REQUIRE_TRANSFER_MATCH` | backend | optional | `true` | `true` | Requires on-chain token/recipient/amount evidence to match the expected payment. | | `TRANSACTION_SAFETY_MIN_CONFIRMATIONS` | backend | optional | `12` | chain floor | Fallback minimum confirmations for unknown chains. Known chains use built-in acceptance floors unless a higher admin-configured value exists. | +| `RPC_URL_CHAIN_97` | backend | optional | `https://bsc-testnet-rpc.publicnode.com` | `https://bsc-testnet-rpc.publicnode.com` | Overrides the backend verifier RPC for BSC Testnet (`bsc-testnet`, `bnb-testnet`, numeric `97`). | +| `BSC_TESTNET_RPC_URL` / `BNB_TESTNET_RPC_URL` | backend | optional | `RPC_URL_CHAIN_97` fallback | `https://...` | Alternate BSC Testnet RPC override names consumed by the legacy verifier path. | | `TRANSACTION_SAFETY_AML_PROVIDER` | backend | optional | `none` | `none` | AML/sanctions provider adapter name. Non-`none` values should block until implemented/configured. | | `PAYMENT_LEDGER_ENFORCEMENT` | backend | optional | `false` | `true` | Enforce ledger gates for release/refund | | `PAYMENT_RECONCILIATION_ENABLED` | backend | optional | `false` | `true` | Enable scheduled provider reconciliation jobs | @@ -154,6 +156,7 @@ Scanner service settings: | `DB_PATH` | scanner | optional | `./scanner.db` | `/data/scanner.db` | SQLite state path for intents, checkpoints, and balance watches. | | `CHAINS_JSON_PATH` | scanner | optional | `./supported-chains.json` | `/app/supported-chains.json` | Chain registry path. | | `TOKENS_JSON_PATH` | scanner | optional | `./tokens.json` | `/app/tokens.json` | Token registry path used for `token`/`tokenSymbol` balance requests. | +| `SCANNER_ENABLED_CHAINS` | scanner | optional | all configured chains | `56,1,97` | Restricts scanner startup to selected chain ids; dev includes chain 97 for BSC Testnet testing. | | `RPC_BSC` / `RPC_ETH` / `RPC_POLYGON` / `RPC_ARB` / `RPC_BASE` | scanner | optional | chain config | provider URL | EVM RPC overrides used by intent scanners and `balanceOf` reads. | Direct-address balance checks and watches currently support EVM ERC-20 only. Backend code should use `checkScannerTokenBalance`, `createScannerBalanceWatch`, and `stopScannerBalanceWatch` from `amnPayAdapter.ts`. diff --git a/09 - Audits/Activity Log.md b/09 - Audits/Activity Log.md index ecc15b0..3d9173c 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@810098f, frontend@5ccc15c, scanner@6897195 — BSC Testnet scanner rail aligned + +**Commits:** `810098f` `5ccc15c` `6897195` +**Touched:** backend `src/services/payment/requestNetwork/tokens.json`, `src/services/payment/decentralizedPaymentService.ts`, `src/services/payment/safety/confirmationThresholdService.ts`, `scripts/smoke/{rn-intent.sh,bsc-testnet-payment-registry.sh}`, payment tests; frontend `package.json`, `Dockerfile`, Telegram WebApp typing; scanner `tokens.json`, `VERSION`. +**Why:** Dev BSC Testnet payments could create/scan against mismatched USDT contracts and wait for the mainnet-style 200 confirmation floor. Backend and scanner now agree on chain 97 USDT `0x337610d27c682E347C9cD60BD4b3b107C9d34dDd`, BSC Testnet verifier aliases/RPCs are first-class, and the chain 97 default confirmation floor is 5 for test flow confirmation. +**Verification:** backend `npm test -- --runTestsByPath __tests__/rn-in-house-checkout.test.ts __tests__/decentralized-payment-verifier.test.ts __tests__/confirmation-threshold-service.test.ts --runInBand`, `npm run typecheck`, `BASE_URL=http://127.0.0.1:5001 ./scripts/smoke/bsc-testnet-payment-registry.sh`; frontend `npx tsc --noEmit --ignoreDeprecations 6.0`; scanner `go test ./...`. Woodpecker deploy pending at time of doc sync. +**Linked docs updated:** [[04 - Flows/Payment Flow - Scanner]], [[07 - Development/Environment Variables]] + +--- + ### 2026-06-05 — backend@v2.8.94 — Log email verification code when no real SMTP (codes weren't reaching inboxes) **Commits:** backend v2.8.94 @@ -98,7 +108,6 @@ entries on top. Maintained by agents per the rule in `../AGENTS.md`. **Touched:** `sections/telegram/view/telegram-new-request-view.tsx` **Why:** The web new-request form lets a buyer choose preferred sellers to invite, but the Mini App form only had title/description/category/budget/urgency — the `field_seller_*` locale strings existed but nothing rendered them. Added an optional multi-select chip list of sellers (from `useTelegramShops` / `getTemplateSellers`) between budget and urgency; tapping toggles a seller, and `preferredSellerIds` is included in the create payload only when non-empty. **Verification:** frontend `npx tsc --noEmit --ignoreDeprecations 6.0` + eslint clean. After deploy: the «درخواست امانت جدید» form shows a «فروشنده‌های منتخب» section; selected sellers are sent with the request so they're invited to bid. - --- ### 2026-06-05 — backend@v2.8.84, frontend@v2.8.101 — Notifications wired end-to-end (id-seam normalize + Mini App joins user room)