Summary
Add a pre-send address screening step to the send flow that validates address format and network, applies policy lists, detects known-risk destinations and common error conditions (self-send, reuse, invoice mismatch), and surfaces clear, actionable UI guidance before transactions are signed or broadcast.
Problem Statement
Users can accidentally send funds to invalid, wrong-network, or high-risk addresses. Small UX and validation gaps increase the risk of lost funds, scams, and compliance exposure for org-managed wallets. We need an explicit, consistent preflight that reduces human error and enforces policy.
Scope & Requirements
1. Address format & network validation
- Validate Base58 (P2PKH/P2SH) and Bech32/Bech32m (P2WPKH/P2WSH/Taproot) including checksum.
- Detect and block addresses for the wrong network (e.g., testnet on mainnet).
- Report script type (legacy, segwit, taproot) in the preflight panel.
2. Policy lists
- Support user/org-level allowlists and denylists with exact and prefix matching.
- Allowlist entries override denial entries; denylist entries block unless explicitly overridden by an admin.
- When blocked, show the specific reason (policy name, matcher) and link to settings.
3. Risk intelligence (optional/integration)
- Integrate a screening provider or internal heuristics for known scams, mixers, or sanctioned addresses.
- Cache screening results with TTL; surface cache age in logs/telemetry.
- Support fail-open (warn) and fail-closed (block) modes for provider timeouts.
4. Ownership & reuse checks
- Warn if the destination address is derived from or known to belong to the current wallet (self-send).
- Flag address reuse when privacy settings indicate the user wants protection (e.g., privacy mode).
5. Contextual/transactional checks
- Detect invoice address mismatches (when an invoice or previously scanned QR suggests a different destination).
- Flag unusually large sends and first-time recipients; require an extra confirmation step for flagged transactions.
- Allow per-transaction override with an optional justification note (persisted to audit log).
6. UI / UX
- Add an inline preflight panel on the send confirmation screen summarizing:
- Address canonical form and detected network
- Script type
- Policy/risk verdict (Allow / Warn / Block) with short explanation
- Action buttons: Cancel, Confirm, Admin Override (if permitted)
- Provide a “Learn more” link that explains rules and how to manage lists.
- Make messages explicit and non-technical where possible (e.g., “This address appears to be on testnet — transactions from this device will not succeed.”).
7. Telemetry & audit logging (privacy-conscious)
- Log screening outcomes (allow/warn/block), the reasoning code, and cache age — do NOT log full addresses in analytics.
- Persist non-PII audit entries per-transaction for admin review when overrides occur.
- Track screening provider uptime and hit rates/false-positive counts.
8. Settings & admin controls
- Add a “Screening Mode” setting: Strict (blocks high-risk), Warn (alerts but allows), Disabled (no screening).
- Admins can manage org-level lists and set policy precedence.
- Per-transaction override requires admin credentials or justification, depending on org policy.
9. Testing & quality
- Unit tests for checksum validation and network detection.
- Integration tests for allowlist/denylist matching and provider failure modes.
- E2E tests covering preflight UI, override flows, and audit logging.
10. Documentation
- Update user help and admin docs: how screening works, TTLs, overrides, retention, and privacy guarantees.
Acceptance Criteria
- Invalid or wrong-network addresses are blocked with clear, user-friendly messages.
- Policy list behavior is correct (allowlist overrides; denylist blocks; prefix matching works).
- High-risk destinations (if provider enabled and strict mode set) require explicit override to send.
- Screening logs are recorded without leaking full addresses to analytics.
- Provider timeout/failure modes follow configured policy (fail-open vs fail-closed).
- Tests covering validators, policy matching, and override paths are present and passing.
Notes & privacy considerations
- Never send full addresses to third-party analytics. If external screening provider requires address data, encrypt/permit first via policy and document retention.
- Keep default settings conservative: Warn mode by default for personal installs; org installs can opt into Strict.
Checklist
Summary
Add a pre-send address screening step to the send flow that validates address format and network, applies policy lists, detects known-risk destinations and common error conditions (self-send, reuse, invoice mismatch), and surfaces clear, actionable UI guidance before transactions are signed or broadcast.
Problem Statement
Users can accidentally send funds to invalid, wrong-network, or high-risk addresses. Small UX and validation gaps increase the risk of lost funds, scams, and compliance exposure for org-managed wallets. We need an explicit, consistent preflight that reduces human error and enforces policy.
Scope & Requirements
1. Address format & network validation
2. Policy lists
3. Risk intelligence (optional/integration)
4. Ownership & reuse checks
5. Contextual/transactional checks
6. UI / UX
7. Telemetry & audit logging (privacy-conscious)
8. Settings & admin controls
9. Testing & quality
10. Documentation
Acceptance Criteria
Notes & privacy considerations
Checklist