Technical Deck

This page is the scope reference for the MVP build.

Related docs:

• Product flow: Use case
• Product surface area: Features
• Reputation formula: Rating system
• Fees and referrals: Tier system (including referral and app fees)
• Timeline context: Roadmap

MVP scope

Goals for MVP:

• Enable safe P2P deals for stablecoins with off-chain fiat settlement.
• Keep negotiation and audit trails in-app.
• Enforce escrow rules with minimal manual intervention.
• Surface reputation signals to reduce fraud.
• Monetize via tier-based fees and referrals.

In-scope capabilities:

• P2P offer creation and discovery (filters + map)
• In-app chat for coordination
• Escrow-based settlement (one-sided guarantee)
• Reputation signals (PoSFI + deal outcomes)
• Tier-based app fees and referrals

Components

Clients

• Mobile app (iOS, Android)
  • Primary for location discovery, chat, and deal execution.
• Web client
  • Useful for browsing, account management, and future power-user workflows.

Backend platform (core)

Owns most business logic and acts as the “source of truth” for:

• Authentication and sessions.
• User profiles, connected accounts (Telegram/X), and privacy settings.
• Offers, deals, chat messages, and attachments (if enabled).
• Fee logic, referrals, tiers, and score calculation inputs.
• Admin tooling hooks (moderation, disputes, safety actions).

Order matching module

• Index offers for fast discovery.
• Apply filters (asset, side, payment method, limits).
• Apply ranking inputs (location proximity, freshness, maker tier/score).

Escrow module

• Create escrow, accept deposits, and release on completion.
• Enforce timeouts and cancellation rules.
• Emit events for backend reconciliation (indexer/webhooks).

Notifications and alerts

• Push notifications for chat and deal state changes.
• In-app notifications for reminders, timeouts, and safety prompts.

Settlement model (summary)

• Stablecoins are locked in escrow by the stablecoin seller.
• Fiat settlement happens off-chain (cash / bank transfer).
• Escrow releases after the stablecoin seller confirms fiat receipt.

Reference flow: Use case.

Suggested deal state flow (MVP)

Keep the state machine simple and auditable:

1. OfferCreated
2. DealAccepted
3. EscrowFunded
4. FiatSent (buyer claim)
5. FiatConfirmed (seller confirmation)
6. EscrowReleased

Terminal / exception states:

• Cancelled (before funding, or by rule)
• TimedOut (escrow funding timeout / confirmation timeout)
• Disputed (manual review path, if enabled)

Security and compliance notes

• Prefer in-app chat for auditability and disputes.
• Keep immutable audit logs for deal actions and escrow events.
• Add rate limiting and basic abuse controls (spam, fake offers, scraping).
• Privacy controls must not block compliance or safety.

If operating as a VASP, align with the Travel Rule where required:

• High-level: Travel rule
• Practical checklist: VASP

Open questions (to finalize)

Product + policy

• Dispute process and arbitration rules.
• What evidence is acceptable for “fiat sent” / “fiat received”.
• Minimum data retention policy for chat and deal logs.

Protocol + on-chain

• Supported networks per asset (USDT/USDC per chain).
• Escrow timeout rules and who can trigger them.
• Cancellation rules after escrow is funded.

Fees

• Fee basis (stablecoin notional vs fiat equivalent).
• Fee payer defaults (maker-chosen vs fixed per offer type).

Operations

• Support tooling needs for disputes, scams, and chargeback-like situations.
• Monitoring and alert thresholds for stuck escrows and abnormal behavior.

MVP definition of done (product-ready)

Offers (create, edit, expire)

Done when:

• User can create an offer with: side, asset, amount limits, payment method, location mode.
• Offer preview shows all user-visible terms.
• Offer can be edited only while it is not in an active deal.
• Offer can be disabled by the maker.
• Offer expires automatically after its validity window.
• Offer list shows freshness (last updated / bumped).

Edge cases:

• Duplicate offers spam protection (rate limits, cooldowns).
• Asset/network changes are blocked on active offers.
• Location privacy mode still enables discovery (coarse location).

Discovery (filters + map)

Done when:

• User can filter by: side, asset, amount, payment method, distance.
• Map and list results stay consistent for the same filters.
• Ranking is stable and explainable (distance + freshness + safety inputs).
• “No matches” state suggests next action (change filters or create offer).

Edge cases:

• No location permission. Manual location still works.
• Very dense areas. Result limiting does not hide relevant offers.
• Stale offers are hidden or clearly marked.

Chat (coordination and audit trail)

Done when:

• Chat opens only after a deal is accepted, or after explicit contact action.
• Messages are delivered reliably and ordered per conversation.
• Deal terms are visible in chat context (side, amount, payment method).
• User can report and block another user.
• Moderation actions are reflected in-app (mute, ban, message removal).

Edge cases:

• One side goes offline mid-negotiation.
• Spam bursts and link abuse are throttled.
• Deleted accounts keep audit-safe placeholders (do not break history).

Deal creation + escrow

Done when:

• Deal can be created from an offer with clear role labels.
• Escrow deposit address and amount are shown with copy actions.
• Backend tracks escrow status via events (no manual “trust me” toggles).
• “Fiat sent” and “fiat confirmed” steps are explicit.
• Release requires seller confirmation or an explicit dispute policy.
• On completion, both parties can rate each other.

Edge cases:

• Escrow funded late. Deal moves to TimedOut by rule.
• Partial funding. Define behavior (reject or treat as not funded).
• Wrong network deposit. Define user-facing messaging and support path.
• Double-spend attempts. Escrow state must be idempotent.

Timeouts, cancellations, disputes

Done when:

• Funding timeout is enforced (from DealAccepted to EscrowFunded).
• Confirmation timeout is enforced (from FiatSent to FiatConfirmed).
• Cancellation rules are clear in UI before acceptance.
• Dispute entry points exist where policy allows.
• Dispute outcome impacts reputation signals consistently.

Edge cases:

• Both parties claim success. System state stays consistent.
• One party claims “fiat sent” with no evidence. Define defaults.
• Chargeback-like scenarios are documented as unsupported for cash.

Reputation + tiers + fees

Done when:

• Score updates after deal completion.
• Tier updates are visible and explainable (progress to next tier).
• Fee rate applied matches the fee payer’s tier.
• Referral share is calculated and recorded for completed deals.

Edge cases:

• Rollbacks after disputes. Score changes are reversible by admin action.
• New users without X. Default PoSFI multiplier is applied.

Notifications (push + in-app)

Done when:

• Push triggers exist for: new message, escrow funded, timeout warnings, release.
• In-app notifications link to the correct deal/chat.
• Users can opt out of non-critical pushes.

Edge cases:

• User changes devices. Notification tokens rotate cleanly.
• Notification storms are capped (chat spam protection).

Admin / support (minimum set)

Done when:

• Admin can view a deal timeline with key events.
• Admin can freeze a user and disable offers.
• Admin can annotate a case with internal notes.
• Basic safety analytics exist (reports per user, dispute rate).