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

docs: sync from backend 810098f — BSC Testnet scanner rail

Browse Source
This commit is contained in:
Siavash Sameni
2026-06-06 07:36:32 +04:00
parent e9bb2211b5
commit cafef04a75
3 changed files with 32 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
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-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 <SCANNER_API_KEY>
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:

3
07 - Development/Environment Variables.md
View File

@@ -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`.

11
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@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)