Document telegram-native task 5 foundation

2026-05-24 13:19:54 +04:00
parent 6a451040d9
commit 7651d69811
11 changed files with 883 additions and 16 deletions
--- a/Strategy.md
+++ b/Strategy.md
@@ -0,0 +1,105 @@
+---
+title: Task 5.5 Telegram Payment and Wallet Strategy
+tags: [taskmaster, telegram, payment, wallet, provider-adapter]
+created: 2026-05-24
+status: draft
+---
+
+# Task 5.5 Telegram Payment and Wallet Strategy
+
+Source: `/.taskmaster/docs/prd-telegram-native-app-bot-wallet.md`
+
+## 1) Strategy principle for this track
+
+For first release, Telegram-native payment initiation must feed the existing canonical payment system and must **not** bypass
+ledger-led state transitions. This means:
+
+- payment proof and funds movement remain authorized by
+  [`Funds Ledger and Escrow State Machine Specification`](Funds%20Ledger%20and%20Escrow%20State%20Machine%20Specification.md),
+- release/refund actions remain governed by service-layer guards and dispute holds,
+- Telegram provider adapters are optional extensions, not a hard dependency.
+
+In practice: Telegram can open payment flows through one canonical path first, and optional providers are layered later.
+
+## 2) Option comparison
+
+| Option | Fit for Telegram UX | Funds correctness risk | Regulatory / abuse risk | Complexity | Decision |
+|---|---|---|---|---|---|
+| Bot API Payments / Telegram Stars | Moderate | High (revenue and settlement mapping differs from existing ledger assumptions) | Medium | Medium | Deferred |
+| Wallet Pay | Moderate | Medium-High (token-specific proof path) | High | High | Deferred |
+| TON Pay | Medium | Medium-High (provider proof consistency + chain mapping) | High | High | Deferred |
+| TON Connect + direct wallet pay | Medium | Medium if proven; requires strict recipient+amount+memo checks | High | High | Deferred |
+| Request Network links | High (already introduced) | Low-Medium (existing adapter/service contract) | Medium | Low | **Primary for phase 1** |
+| Existing Web3/crypto checkout path | High | Medium (requires recipient/amount/network proof hardening) | High | Medium | Keep as fallback only |
+
+## 3) Selected phase-1 path
+
+### Primary phase-1 strategy
+
+- Telegram bot/Mini App starts the payment by invoking the same canonical payment intent creation API used for web flows.
+- Payment provider is written as metadata; provider-neutral adapter remains optional and feature-flagged.
+- Telegram identity metadata is persisted with the intent:
+  - `provider` (e.g., `request_network` or `shkeeper`)
+  - `telegramUserId`
+  - `telegramChatId` (if available)
+  - `launchSource` (`bot`, `mini_app`, `web_fallback`)
+  - `paymentReference`
+  - `invoiceId` / `orderId` / `requestId`
+  - `currency`, `amount`, `expiresAt`
+  - idempotency key (request-scoped)
+
+### Optional providers
+
+- Wallet Pay / TON Pay / TON Connect paths are documented as optional and must be implemented behind explicit
+  feature flags and dedicated adapter configuration only when:
+  - replay-safe proofs are standardized,
+  - canonical refund/release reconciliation supports provider-native evidence,
+  - monitoring/reporting has parity with existing paths.
+- Until that date, these options are not required to merge for Task 5.1-5.9 handoff.
+
+## 4) Data integrity requirements for any Telegram payment/Wallet path
+
+Before any pay-in is accepted into escrow, enforce:
+
+1. recipient validation (exact canonical recipient for the active escrow policy),
+2. asset validation (supported chain + token),
+3. amount validation against payment intent and currency precision,
+4. memo/reference validation (idempotent and tamper-evident),
+5. confirmation proof validation (`confirmed`, `on-chain`, or provider webhook),
+6. canonical reconciliation step before mark-complete,
+7. invariant re-check with ledger balances before release/refund operations.
+
+These map directly to:
+
+- [`Webhook Security Spec`](Webhook%20Security%20Spec.md)
+- [`Payment Provider Adapter Spec`](Payment%20Provider%20Adapter%20Spec.md) (if optional provider is enabled)
+- [`Funds Ledger and Escrow State Machine Specification`](Funds%20Ledger%20and%20Escrow%20State%20Machine%20Specification.md) (all financial state transitions).
+
+## 5) Anti-divergence record model
+
+Every Telegram payment intent should write a small canonical trace record with:
+
+- canonical `paymentId`
+- `canonicalSourceChannel = telegram`
+- `telegramContext` payload hash
+- `provider` and `providerReference`
+- `idempotencyKey`
+- `createdFrom` deep-link/command/callback identifier
+- reconciliation status (`created`, `started`, `confirmed`, `failed`, `reconciled`)
+
+This avoids duplicate checkout creation and makes Telegram callback replay and callback mismatch explainable in operations.
+
+## 6) Refund/release compatibility
+
+Refund/release logic remains unchanged from the canonical engine:
+
+- cannot release funds not in releasable state,
+- no release/release-amount mutation from Telegram without canonical precondition checks,
+- disputed states block direct payout operations,
+- release/refund events are only reflected after ledger updates succeed.
+
+## 7) Open follow-up decisions
+
+1. Decide whether to onboard `Wallet Pay` as phase-2 provider once adapter-level proof validation and reconciliation parity are met.
+2. Decide whether to expose optional "wallet direct top-up" button in Mini App from day one or keep explicit link-first flow.
+3. Finalize provider timeout and retry policy for Telegram-triggered intents under slow-network conditions.