nick-doc/.taskmaster/docs/prd-telegram-native-app-bot-wallet.md

PRD: Telegram-Native App, Bot, and Wallet Experience

Scope

Create a separate delivery track for making Amanat usable from inside Telegram through a bot plus Telegram Mini App. The goal is not only notifications, but a native-feeling Telegram surface that can cover buyer, seller, escrow, chat, dispute, payment, release/refund, and support workflows.

This track should remain separate from the current security remediation and Request Network migration backlog, but it depends on those foundations for any money movement or high-risk actions.

Platform assumptions checked May 24, 2026

• Telegram Mini Apps provide a full JavaScript web interface inside Telegram and can be launched from bot profile, menu button, inline buttons, direct links, inline mode, and selected attachment-menu contexts.
• Mini Apps must validate Telegram.WebApp.initData on the backend before trusting Telegram user identity. initDataUnsafe is not trusted.
• Bot API payments support invoices, invoice links, pre-checkout handling, successful payment events, Telegram Stars, and refund/subscription management for Stars.
• TON Connect is the standard wallet connection protocol for TON dApps and Telegram Mini Apps. It lets apps request wallet connection, signatures, and transactions without controlling user keys.
• TON Pay SDK and Wallet Pay are possible payment paths for TON/jetton/Telegram-wallet-style crypto payments, but they must be evaluated against escrow ledger, webhook, jurisdiction, KYC, fee, refund, and reconciliation requirements before production use.

Reference docs:

• Telegram Mini Apps: https://core.telegram.org/bots/webapps
• Telegram Bot API payments: https://core.telegram.org/bots/api#payments
• TON Connect: https://docs.ton.org/applications/ton-connect/overview
• TON Pay SDK: https://docs.ton.org/applications/ton-pay/overview
• Wallet Pay API: https://docs.wallet.tg/pay/

Product goal

Users should be able to complete the practical Amanat journey without leaving Telegram:

• Register or link an Amanat account from Telegram.
• Browse and create purchase requests.
• Receive seller offers and buyer decisions.
• Chat around a request with structured context.
• Start escrow payment from Telegram.
• See payment, delivery, dispute, and release state.
• Submit evidence for delivery or dispute.
• Confirm delivery, request refund, or approve release when eligible.
• Receive actionable notifications and reminders.
• Use wallet/payments options that are safe for escrow accounting.

Non-goals

• Do not bypass the canonical backend authorization, funds ledger, or escrow state machine.
• Do not treat Telegram chat messages as the source of truth for financial state.
• Do not release funds based only on bot callback data or client-side Mini App state.
• Do not store Telegram bot tokens, Wallet Pay keys, or TON private keys in frontend code.
• Do not make Telegram the only supported channel unless a later product decision explicitly says so.

Architecture principles

• The Mini App is a client surface. The backend remains the authority for identity, authorization, payment state, escrow state, disputes, and audit logs.
• Telegram identity maps to an Amanat user through a verified link table keyed by Telegram user ID and Amanat user ID.
• Every Telegram-originated command, callback, webhook, and Mini App request is authenticated and rate-limited.
• Telegram callbacks must be idempotent and replay-safe.
• Payment events flow into the same provider-neutral payment adapter, ledger, and reconciliation pipeline as web checkout.
• High-risk actions such as release, refund, payout address change, dispute resolution, and admin override require step-up confirmation or explicit backend policy.

Task set

Task 1: Define Telegram product surface and flow map

Document which Amanat workflows live in bot messages, which live in the Mini App, and which remain web/admin-only for the first release.

Acceptance criteria:

• Buyer, seller, admin/support, unauthenticated, linked-user, and unlinked-user journeys are mapped.
• Deep-link entry points are specified for request details, offer review, payment, dispute, delivery evidence, and account linking.
• First-release scope separates must-have flows from later enhancements.
• Every Telegram action maps to an existing or planned backend API/state transition.

Task 2: Build Telegram identity linking and session model

Implement secure account linking between Telegram users and Amanat accounts.

Acceptance criteria:

• Backend verifies Mini App initData before creating a Telegram session.
• Telegram user IDs are linked to Amanat users through an auditable association table.
• Account linking supports existing users, new users, unlinking, blocked accounts, and duplicate Telegram-account attempts.
• Session expiry, replay protection, rate limits, and audit logging are defined.

Task 3: Implement bot command and notification foundation

Create the Telegram bot backend for commands, inline keyboards, callback queries, deep links, and outbound notifications.

Acceptance criteria:

• Bot supports start/help/link/status/request/offer/payment/dispute/settings basics.
• Callback payloads use short opaque IDs or signed tokens, not raw financial state.
• All incoming updates are idempotently processed and rate-limited.
• Notification preferences and quiet/error states are respected.
• Failed delivery, blocked bot, and retry behavior are observable.

Task 4: Build Telegram Mini App shell for core marketplace workflows

Deliver the mobile-first Mini App that gives users the full Amanat workflow surface inside Telegram.

Acceptance criteria:

• Mini App uses Telegram theme, safe-area, viewport, back button, haptics, and main/bottom button patterns.
• Users can browse requests, create/edit requests, review offers, view escrow/payment state, upload evidence, and manage dispute/delivery actions.
• The Mini App can be launched from bot profile, menu button, inline buttons, and direct links with startapp context.
• UX handles unlinked accounts, expired sessions, unsupported Telegram clients, and fallback web links.

Task 5: Add Telegram payment and wallet strategy

Evaluate and implement safe payment entry points for Telegram-native users without weakening escrow accounting.

Acceptance criteria:

• Compare Bot API payments/Stars, Wallet Pay, TON Pay, TON Connect, Request Network links, and existing crypto checkout for supported use cases.
• Select a first payment path and document rejected options.
• Payment creation stores provider, Telegram user ID, deep-link source, payment reference, invoice/order/request ID, currency, amount, expiration, and idempotency key.
• Wallet/TON flows validate recipient, asset, amount, memo/reference, confirmation status, and reconciliation evidence before crediting escrow.
• Refund/release behavior is explicitly compatible with the canonical ledger and dispute holds.

Task 6: Expose escrow, delivery, dispute, and release actions safely

Make Telegram actions useful for real escrow work while preserving backend state authority.

Acceptance criteria:

• Telegram users can see current escrow state, next allowed actions, and blockers.
• Delivery confirmation, evidence upload, refund request, dispute open/respond, and release approval route through backend precondition checks.
• High-risk actions require fresh confirmation and are audit logged with Telegram context.
• Disputed or held funds cannot be released through Telegram shortcuts.

Task 7: Add admin/support operating surface for Telegram-originated cases

Give support/admin users enough visibility to handle Telegram-originated users and payments.

Acceptance criteria:

• Admin UI/API shows Telegram linked identity, bot notification status, launch source, payment provider, and wallet/payment references.
• Support can resend links, revoke Telegram link, block bot access, and inspect Telegram-originated events.
• Admin overrides require the same step-up/two-person policy as web flows if configured.

Task 8: Security, compliance, and abuse controls for Telegram

Threat-model the Telegram surface and add controls before launch.

Acceptance criteria:

• Threat model covers forged init data, callback replay, deep-link parameter tampering, phishing links, bot token leakage, spam, account takeover, wallet spoofing, fake payment proof, and support impersonation.
• Secrets, bot webhook endpoints, Wallet Pay keys, TON Connect manifest, CORS, CSP, allowed origins, and rate limits are documented.
• Monitoring covers update processing failures, abnormal callbacks, payment mismatches, blocked notifications, and suspicious wallet activity.

Task 9: QA, rollout, analytics, and launch operations

Prepare the Telegram app/bot for controlled release.

Acceptance criteria:

• Test matrix covers Telegram iOS, Android, Desktop, Web, light/dark themes, compact/fullscreen modes, slow network, blocked bot, expired sessions, and payment cancellation.
• Sandbox/test bot and production bot environments are separated.
• Rollout uses feature flags, internal allowlist, beta cohort, and production enablement.
• Analytics measure activation, linked accounts, request creation, offer response, payment start/completion, dispute activity, release approval, and notification opt-outs.
• Runbooks exist for bot outage, Telegram API outage, payment provider outage, stuck payment, duplicate callback, suspicious wallet proof, and compromised bot token.

Dependency guidance

• Tasks involving release/refund/payment crediting should depend on the platform hardening and ledger/payment-provider work.
• Identity, bot navigation, Mini App shell, and notification preferences can start earlier behind feature flags.
• Wallet/TON payment work must not precede the provider-neutral adapter, ledger invariants, and webhook/idempotency contracts.