# 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.