docs: sync from backend 22ae0bd — scanner balance watches

08 - Operations/Scanner Operations.md

@@ -24,6 +24,8 @@ All configuration via environment variables. See `.env.example` in the scanner r
 | `POLL_INTERVAL_SEC` | `15` | no | Chain poll interval in seconds |
 | `INTENT_TTL_HOURS` | `24` | no | Pending/confirming intents older than this are expired (0 = disabled) |
 | `WEBHOOK_RETRY_HOURS` | `6` | no | Interval between automatic webhook_failed re-delivery passes (0 = disabled) |
+| `BALANCE_WATCH_TICK_SEC` | `60` | no | Scheduler tick for due direct-address balance watches |
+| `BALANCE_WATCH_BATCH_SIZE` | `50` | no | Max due balance watches processed per scheduler tick |
 | `TRONGRID_API_KEY` | _(none)_ | recommended | TronGrid API key; without it rate limits are very low |
 | `TONCENTER_API_KEY` | _(none)_ | recommended | TonCenter API key |
 | `RPC_BSC` | _(chain config)_ | no | Override BSC RPC URL (chain 56) |
@@ -92,6 +94,7 @@ curl -H "Authorization: Bearer $SCANNER_API_KEY" \
 Check:
 - `lag` — should be near 0 for healthy chains (blocks behind for EVM, seconds for TON)
 - `pendingIntents` — number of unresolved intents per chain
+- `activeBalanceWatches` — number of direct-address watches in `watching` status per chain
 - `lastScannedBlock` — should advance each poll
 
 ### Logs
@@ -109,6 +112,11 @@ The scanner uses Go's `log/slog` structured logger with level prefixes. Key log
 | `[webhook] all retries exhausted` | Intent moved to webhook_failed |
 | `[scanner] reconciling confirmed intents` | Startup crash recovery in progress |
 | `[evm] scanner lag` | Chain lag > 100 blocks (investigate RPC) |
+| `[scanner] balance watch scheduler started` | Balance watch polling loop started |
+| `[api] balance watch created` | Backend registered a direct-address watch |
+| `[balance-watch] balance read error` | RPC failed while reading a watched balance |
+| `[balance-watch-webhook] delivered` | Changed-balance webhook POST succeeded |
+| `[balance-watch-webhook] non-2xx response` | Backend rejected changed-balance webhook; scanner will retry the change later |
 
 ---
 
@@ -175,6 +183,15 @@ SELECT chain_id, last_scanned_block, updated_at FROM checkpoints;
 
 # Count by status
 SELECT status, count(*) FROM intents GROUP BY status;
+
+# Check active direct-address watches
+SELECT watch_id, chain_id, token_symbol, address, current_balance, next_check_at, expires_at
+FROM balance_watches
+WHERE status = 'watching'
+ORDER BY next_check_at ASC;
+
+# Count watches by status
+SELECT status, count(*) FROM balance_watches GROUP BY status;
 ```
 
 ---
@@ -206,6 +223,29 @@ SELECT status, count(*) FROM intents GROUP BY status;
 
 The scanner accepts any amount **>=** `intent.Amount`. Overpayments are not flagged. Underpayments result in the intent staying pending until TTL expiry.
 
+### Direct balance watch is not firing
+
+1. Confirm the target chain is EVM. Scanner `0.1.8` direct balance checks use ERC-20 `balanceOf(address)` and do not yet support Tron/TON balance reads.
+2. Check `/scanner/status` for `activeBalanceWatches` on the expected chain.
+3. Inspect `balance_watches.next_check_at`; if it is in the future, the scheduler is waiting according to the decay cadence.
+4. Check logs for `[balance-watch] balance read error`; RPC failures reschedule the watch without notifying backend.
+5. Confirm `callbackUrl` and `callbackSecret` match backend `AMN_SCANNER_WEBHOOK_SECRET`.
+6. If `[balance-watch-webhook] non-2xx response` appears, inspect backend logs for the AMN scanner webhook route. The scanner keeps `current_balance` unchanged and retries the same balance change on the next due check.
+
+### Direct balance watch should stop
+
+Use either stop form:
+
+```bash
+curl -X DELETE -H "Authorization: Bearer $SCANNER_API_KEY" \
+     http://localhost:8080/balance-watches/<watchId>
+
+curl -X POST -H "Authorization: Bearer $SCANNER_API_KEY" \
+     http://localhost:8080/balance-watches/<watchId>/stop
+```
+
+Backend should stop a watch after payment acceptance, cancellation, manual resolution, or when the payment is no longer payable.
+
 ---
 
 ## 10. CI/CD notes