164 lines
9.7 KiB
Markdown
164 lines
9.7 KiB
Markdown
# 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.
|