Skip to content

PRD.md

Latest commit

 

History

History
217 lines (193 loc) · 29.2 KB

PRD.md

File metadata and controls

217 lines (193 loc) · 29.2 KB

FundWise - Product Requirements Document

Owner: Sarthi Status: Draft v0.3 Last updated: 2026-05-18

Problem Statement

Shared-expense apps solve the bookkeeping problem, but not the settlement problem. Friends can see who owes whom, yet they still have to chase each other across messaging apps and payment rails to actually get paid. Crypto users face an extra layer of friction: balances may sit on the wrong chain, wallet UX is confusing for newcomers, and a settlement flow becomes fragile if it asks users to choose assets, chains, or custom amounts at the moment of payment.

FundWise should make shared expenses feel familiar while adding actual settlement finality. The MVP needs to make one thing work extremely well: a private Group where Members log Expenses, see live Balances, and settle exact USDC amounts on Solana with a clean Receipt. Members should be able to enter an Expense in the currency that was actually paid, while FundWise converts it into a stable USD/USDC ledger value before Balance and Settlement math runs.

The competitive category is crowded. Splitwise, Venmo Groups, Spliit, tricount, Kittysplit, and multiple crypto-native bill splitters already train users to expect Groups, balances, receipt support, and debt simplification. FundWise should not depend on "crypto bill splitting" novelty. It should win on verified USDC Settlement for real Groups, live Settlement Request Links, Receipt integrity, cross-chain recovery only when needed, and later scoped agent access over the same wallet-bound ledger.

The broader company frame is FundLabs: the financial layer for groups, human or AI. FundWise is the first product in that stack. It starts with the familiar shared-expense wedge, then moves durable Groups toward shared Treasuries, governed spending, proof, and eventually productive idle money. Fundy is already live as the Telegram-native agent and MCP server with Zerion-backed wallet analysis/readiness/verification; Receipt Endpoint is the sibling developer surface for structured, verifiable receipts.

Solution

FundWise is a web app with wallet-native identity and two product modes:

  • Split Mode is the primary MVP path. Members create a Group, join by invite link or QR, log Expenses with familiar split methods, compute live net Balances, and settle with on-chain USDC transfers on Solana. Source Currency entry and Expense Proof are future-only for the current public demo.
  • Fund Mode is the hero product direction. Members pool USDC into a shared Treasury and spend through Proposal and approval flows. Split Mode remains the shipped wedge and public proof, but the next product sprint should accelerate Fund Mode toward an invite-only beta with Proposals, proof, integrations, and execution.

Within the FundLabs product family, FundWise owns the shared-finance web product. Fundy owns Telegram and personal-agent distribution and is live on Railway as a separate service. Receipt Endpoint owns the developer surface for structured, verifiable agent-payment receipts. These products should share language, auth boundaries, Spending Policies, and Receipt semantics, while public claims must keep each product's shipped state separate.

For the MVP, the source of truth is the web app and the default settlement asset is USDC. LI.FI is the inbound multi-chain rail (paired with Circle CCTP) that lets EVM-first users route funds into Solana USDC during Settlement through Route funds for Settlement language instead of bridge jargon. Zerion can help with wallet analysis, reminders, and agent flows. Neither should complicate the primary user journey:

Group -> Expense -> Balance -> Settlement -> Receipt

Product Principles

  • Web app first. Telegram, wallet mini dapp, native mobile, and other distribution surfaces come later as clients of the same core product engine.
  • Wallet-native identity first. The connected Solana wallet is the Member identity key.
  • Preserve intent after wallet connect. Connect should return the user to the exact Group, Settlement Request, or create flow they came for.
  • One settlement asset. USDC is the only stablecoin in the MVP.
  • Multi-currency Expense entry, single-currency ledger. Members may enter what was paid in another currency, but the saved Expense must include the converted USD/USDC ledger amount and exchange-rate snapshot used for Balance math.
  • Off-chain metadata, on-chain money. Expenses and Group state live off-chain; Settlements and Contributions move money on-chain.
  • Current state over stale links. Settlement links resolve against the debtor's current Balance when opened.
  • Exact settlement over flexible settlement. The primary flow is settle the exact owed amount in one go.
  • Hide routing complexity. Users should think in terms of Settle first and Route funds for Settlement only when needed, not bridge selection and multi-step route logic.
  • Keep friend repayment free at launch. Split Mode should acquire Groups through free shared-expense tracking and normal USDC Settlements; paid surfaces come later through Fund Mode, Fundy, and partner rails.
  • Activity feed, not chat. The Group timeline should explain the ledger without becoming a general messaging product. If Fund Mode needs discussion later, prefer Proposal-scoped comments over full Group chat.
  • Sponsor integrations must support the main flow, not redefine it.
  • Settlement Request Links are the primary growth loop. They should take a debtor from a shared intent into the current live Balance, then through wallet-confirmed USDC Settlement and Receipt without stale amounts or automatic sending.
  • Position FundWise under FundLabs, not as a standalone "crypto Splitwise." Split Mode is the entry hook; Fund Mode is the durable product surface; Fundy and Receipt Endpoint expand the same financial layer into chat, agents, and receipts.
  • Distribution expansion should reuse the same wallet-native ledger model across web, FundWise Agent, Telegram, wallet-mini-app, and native-mobile surfaces instead of inventing separate product rules per channel.
  • Fundy is live beside Fund Mode and creates distribution where Groups already coordinate. It turns FundWise ledger data into reminders, draft Expenses, wallet-readiness checks, personal-finance workflows, and later tax guidance, but it does not block the invite-only Fund Mode mainnet closed beta sprint.
  • The long-range end state is a stablecoin-first product where gas, fees, and bridging are abstracted away as much as possible for the end user, while the core ledger still stays wallet-verifiable underneath.
  • Roll out by audience and surface in sequence: Split Mode mainnet for crypto-native Groups, Fund Mode mainnet invite-only closed beta, Seeker app, Telegram bot + Telegram mini app in parallel with Seeker, full multi-chain funding/wallet support, then non-crypto users through embedded wallets, Bridge.xyz, and Visa/card payments.

User Stories

  1. As a group organizer, I want to create a private Group in Split Mode, so that my friends and I can track shared expenses in one place.
  2. As a new Member, I want to join a Group from an invite link or QR after connecting my wallet, so that joining is fast and does not require manual wallet entry by someone else.
  3. As a Member, I want one profile display name reused across Groups, so that other people can recognize me without changing wallet-native identity.
  4. As a Member, I want to edit my global profile display name later, so that I can fix or improve how I appear in the app.
  5. As a Member, I want to log an Expense for a Group, so that the Group ledger reflects what happened.
  6. As a Member, I want to mark any Group Member as the payer on an Expense, so that the ledger matches reality even if someone else is entering the record.
  7. As a Member, I want to choose familiar split methods, so that the app feels flexible without requiring new mental models.
  8. As a Member, I want to split an Expense equally, so that common cases are fast.
  9. As a Member, I want to split an Expense by exact amounts, so that uneven bills can be recorded precisely.
  10. As a Member, I want to split an Expense by percentage, so that proportional splits are supported.
  11. As a Member, I want to split an Expense by shares, so that non-equal participation can still be entered naturally.
  12. As a Member, I want to see my live Balance in the Group, so that I know whether I owe USDC or am owed USDC.
  13. As a Member, I want to see who owes whom across the Group, so that the current state of the ledger is obvious.
  14. As a debtor Member, I want to settle my current net Balance in one action, so that I can clear what I owe without thinking about individual Expenses.
  15. As a creditor Member, I want to receive a clear Receipt when someone pays me, so that I can trust the settlement happened.
  16. As any Member, I want to share a Settlement Request Link that deep-links into the Group, so that the debtor can open the Group in the correct settlement state.
  17. As a debtor Member, I want the Settlement screen to use my current live Balance, so that I do not overpay or underpay from a stale link.
  18. As a debtor Member, I want to pay in USDC on Solana with a normal wallet confirmation, so that the main flow stays simple and reliable.
  19. As a debtor Member, I want the app to auto-create the creditor's USDC token account when needed, so that my settlement does not fail on first receipt.
  20. As a debtor Member, I want the app to tell me clearly if I lack USDC or SOL, so that I understand why settlement cannot proceed.
  21. As a debtor Member with funds on another chain, I want the Settlement flow to route funds when needed, so that I can recover from insufficient funds without learning the underlying bridge mechanics or changing the main settlement model.
  22. As a Member, I want the Group Activity Feed to show Expenses, edit markers, Settlements, and Receipts, so that the ledger stays understandable without a full chat product.
  23. As an Expense creator, I want to edit or delete my own Expense before later Settlements make that unsafe, so that I can fix mistakes without corrupting the ledger.
  24. As a Member, I want to leave a Group only when my Balance is zero, so that the Group ledger does not end up with orphaned debts.
  25. As a group organizer, I want the product to work on mobile web, so that people can join and settle from their phones during real shared-spending moments.
  26. As a future user with funds on another chain, I want CCTP and LI.FI to help me arrive at Solana USDC, so that cross-chain funds do not block settlement.
  27. As a future user, I want partner integrations to reduce friction around funding and discovery, so that the app becomes easier to use without changing its core ledger model.
  28. As a Fund Mode organizer, I want to create a Treasury-based Group later, so that a shared budget can be pooled before spending.
  29. As a Fund Mode Member, I want to make Contributions and approve Proposals later, so that pooled spending stays collaborative and auditable.
  30. As a disconnected visitor on /groups, I want one obvious wallet connect action, so that I can unlock the app without reading through extra marketing copy.
  31. As a visitor who connected from an invite link, I want to return to that exact Group with a clear Join {GroupName} action, so that I can confirm membership without navigating again.
  32. As a debtor who connected from a Settlement Request Link, I want to land directly in the live settlement-ready state with the current amount, ledger context, and history, so that I can review before signing.
  33. As a first-time connected user with no existing Groups, I want Group creation to open immediately with Split Mode preselected, so that I can start quickly without an extra tap.
  34. As a Group creator, I want to switch the create flow from Split Mode to Fund Mode per Group, so that I can choose the right Group type without changing the whole app.
  35. As a Member, I want to enter an Expense in the currency that was actually paid, so that I do not have to manually convert real-world spending before logging it.
  36. As a Member, I want FundWise to convert that Expense into the USD/USDC ledger value using a current exchange-rate quote, so that Balances and Settlements stay comparable across currencies.
  37. As a Member, I want the exchange rate used for an Expense to be saved with the Expense, so that historical Balances do not change unexpectedly when market rates move later.
  38. As a Member, I want to upload a receipt photo or proof file when I create an Expense, so that other Members can verify what was paid.
  39. As a Member, I want the later FundWise Agent to work from Telegram and other assistant surfaces, so that I can draft Expenses, attach proof, get reminders, and review Group state without creating a separate ledger.
  40. As a user with a personal AI agent, I want my agent to curl the FundWise Agent Skill Endpoint and discover what it can do, so that it can integrate with my FundWise data without manual configuration.
  41. As a user with a personal AI agent, I want my agent to read my Group Balances and upcoming Settlements through Scoped Agent Access, so that I can get proactive financial summaries and reminders from my existing assistant.
  42. As a user with a personal AI agent, I want money-moving actions to still require my direct wallet confirmation even when my agent initiates them, so that autonomous agents can help but not execute financial transactions on their own.
  43. As a Telegram user, I want to authenticate my Telegram account against my FundWise wallet through Fundy, so that I can interact with my Groups from Telegram without managing a separate identity.
  44. As a Telegram user, I want Fundy to show me my Group Balances, recent Expenses, and pending Settlements, so that I can stay on top of shared expenses without opening the web app.
  45. As a Telegram user, I want Fundy to draft Expenses for me in a Group, so that I can quickly log shared spending from the chat where the spending happens.
  46. As a Telegram user in a group chat, I want Fundy to be usable by multiple Members, so that everyone in the Telegram group can interact with the linked FundWise Group through the same bot.
  47. As a Telegram user, I want Fundy to run Zerion-backed /analyze and /readiness, so that I can see wallet readiness and settlement context without leaving the chat.
  48. As a Telegram user, I want Fundy to support /verify against on-chain history, so that I can confirm a Settlement or counterparty payment when coordinating in a group.
  49. As a user with a personal AI agent, I want to mint and revoke scoped agent tokens from my FundWise profile, so that I can control what my agent can do without sharing my browser session.
  50. As a user with a payment-aware personal agent, I want the agent to receive a Payable Settlement Request for an exact Group Balance, so that it can prepare or complete settlement through a machine-readable payment flow when I have explicitly allowed that.
  51. As a user delegating payment authority to an agent, I want hard limits by Group, asset, amount, counterparty, and expiry, so that agent-paid settlement cannot become broad wallet control.
  52. As a creditor Member, I want agent-paid settlement to produce the same FundWise Receipt as a human wallet-confirmed Settlement, so that the final record stays consistent.
  53. As a Member, I want to set Spending Policies for each payment-aware agent, so that small Settlements can be automated while larger Settlements fall back to my wallet confirmation.
  54. As a Group owner, I want ownership to be transferable and mostly administrative, so that a disappeared owner does not trap the Group or gain financial power over other Members.

Implementation Decisions

  • The product has two modes, but the immediate MVP path is Split Mode.
  • The web app is the only required first-class surface for the MVP.
  • Post-MVP distribution expands in layers: web app first, Fundy already live in Telegram, then Seeker app, Telegram mini app, wallet mini dapp, and finally a native mobile app.
  • Identity is Solana wallet address in the MVP. No FundWise email/password and no separate “app account” tied to email as the primary key.
  • Telegram auth, if added later, should be a convenience and routing layer around existing Groups, not a replacement for wallet-native Member identity.
  • Telegram surfaces should be described as FundWise Agent channels. They may handle read-only, draft-safe, comment, proof upload, reminder, and history actions. On-chain money movement, Squads-backed Proposal review, and on-chain execution steps must bounce back into the app for wallet confirmation.
  • One Telegram account should map to one active wallet at a time. If relinking is allowed later, it should be an explicit flow, not an implicit multi-wallet identity model.
  • One Telegram group chat should map to one FundWise Group at a time. If multi-Group switching is allowed later, it should be an explicit chat-level flow rather than the default.
  • Any Group Member may add the bot to a Telegram chat, but each person must authenticate one-on-one with the bot in DM before the bot reads or drafts on their behalf.
  • Agent access should not rely on broad raw API keys. Later agent surfaces should use scoped capabilities tied to the Member wallet, Group, and action type.
  • The Agent Skill Endpoint (/skill.md) is a public URL at https://fundwise.fun/skill.md that returns a machine-readable markdown document describing FundWise capabilities, supported actions, authentication flow, and explicit guardrails (what not to call). Fetching the document does not require authentication and the document must not expose private Member data.
  • Scoped Agent Access is the permission model for autonomous agents. Agents receive scoped capabilities tied to the Member wallet, specific Group, and action type. Money-moving actions (Settlement execution, Contribution execution, Proposal execution) still require direct wallet confirmation from the Member, even when an agent initiates the intent.
  • Payable Settlement Requests are a post-MVP research direction for x402 / MPP-style agent payment flows. They must be separate from normal Settlement Request Links, must resolve the live Group Balance, must be idempotent, and must never create a Receipt until payment verification succeeds.
  • Spending Policies are required before an agent can pay a Payable Settlement Request. The backend must enforce caps and scopes; the LLM or agent prompt is not an authorization source.
  • Group ownership is administrative metadata, not financial authority. The owner may later manage metadata or transfer ownership, but must not bypass Member checks, Expense creator checks, Settlement verification, or Receipt rules.
  • Fundy is the live hosted Telegram agent that runs the FundWise Agent and exposes MCP tools for external agents. It is a FundLabs product and FundWise distribution surface. Users authenticate by linking their Telegram account to their FundWise wallet address via short-lived codes issued from the authenticated web app (/link FW-… in DM with Fundy).
  • Fundy v1 is command-based (fixed commands); the end goal is an LLM-backed assistant (e.g. OpenRouter) with the same underlying tools. Fundy runs on Railway as a separate service from the Next.js app and lives in a separate repository per ADR-0022. It calls FundWise through the same HTTP API as other clients, using service-to-service auth and later Scoped Agent Access, not ad-hoc direct Supabase access from the bot.
  • Fundy supports read-only views (Balances, Expenses, Settlements, Receipts), draft-safe actions (draft Expense, upload proof), comments, and history. Squads-backed Proposal approve/reject and on-chain Settlement, Contribution, and Proposal execution bounce the Member to the web app with Settlement Request Links used for settle intents where applicable.
  • Fundy integrates Zerion CLI for /analyze, /readiness, and /verify (wallet + transaction history). This integration is live in Fundy. Prefer ZERION_API_KEY (free dev tier) for v1; optional x402 pay-per-call on Solana later.
  • Mini-games and prediction-market-like mechanics are out of scope for FundWise. They are not Split Mode scope, Fund Mode beta scope, or launch scope.
  • Scoped Agent Access includes user-generated agent tokens managed from /profile/agents (rotate, delete, renew, scopes) plus optional wallet-signed agent authentication for agents that can sign Solana messages.
  • The Agent Skill document lives at https://fundwise.fun/skill.md and is the shipped public discovery baseline. Scoped tokens, agent payment authority, and agent-paid Settlement execution remain planned.
  • Later onboarding work should help web2 users reach stablecoin balances with far less friction through embedded wallets, Bridge.xyz bank rails, and Visa/card payments, but only after the crypto-native core flow, Seeker, Telegram distribution, and full multi-chain funding/wallet support are reliable.
  • A Member is keyed by wallet address and labeled with a global profile display name.
  • Optional: Phantom Connect (Google/Apple + embedded or extension via Phantom) may be offered in addition to @solana/wallet-adapter-*, with Phantom Portal configuration. It does not replace the adapter for users who use Solflare, Backpack, or other wallets. See CONTEXT.md and docs/adr/0014-optional-phantom-connect-alongside-wallet-adapter.md.
  • /groups is the wallet-first app entry. Its primary job for disconnected users is to get them connected, then restore their intended next action.
  • If a disconnected user connects from plain /groups and has no existing Groups, Group creation should open immediately.
  • If a disconnected user connects from plain /groups and already has existing Groups, the app should keep them on the Group list.
  • Group creation defaults to Split Mode; the public create flow keeps Fund Mode visible as an invite-only beta rather than a generally available option.
  • Group join is self-serve through invite link or QR.
  • Invite links should restore the exact Group context after connect and present an explicit Join {GroupName} action; the app should not silently join on wallet connect.
  • Creator approval, Group roles, and membership workflows beyond simple join/leave are out of the MVP.
  • The MVP settlement asset is USDC only.
  • Expense entry may support multiple Source Currencies in a future release, but this does not change the settlement asset. Every saved Expense must have a USD/USDC ledger amount.
  • Exchange-rate conversion should use a current quote at Expense create or edit time, then store an Exchange Rate Snapshot. Historical Balance math must use the stored snapshot instead of continuously repricing old Expenses. See docs/adr/0017-snapshot-source-currency-expenses-into-usdc-ledger.md.
  • Mainnet-beta is the product target. Devnet is the test and rehearsal environment.
  • SOL remains necessary for gas in the MVP.
  • Expenses are off-chain records stored in the app data layer.
  • Expense Proof uploads are future-only off-chain metadata attached to Expenses. They may be images, PDFs, or external proof links, and should not be confused with Settlement Receipts.
  • Settlements are on-chain Solana USDC transfers.
  • The Group ledger is netted at the Group level, not at the individual Expense level.
  • Members settle current net Balance, not a custom amount and not an Expense-by-Expense bill.
  • Only debtor Members can sign their own Settlements.
  • Any Member can prompt a settlement or share a deep link, but no Member can authorize payment for someone else.
  • Settlement links must resolve live state when opened.
  • Settlement Request Links should restore the debtor directly into the live settlement-ready state after connect, including relevant ledger context and the current amount due.
  • Settlement Request Links must never auto-send the transaction after connect.
  • The simplified settlement graph is the source for suggested transfer edges.
  • Each suggested edge maps to one debtor-to-creditor transfer and one Receipt.
  • The primary flow settles the exact owed amount in one go.
  • Any Member can create an Expense, and the payer can be any Member in the Group.
  • Only the Expense creator can edit or delete the Expense.
  • Expense edits update in place with a lightweight "edited" signal in the Activity Feed.
  • Expense changes are blocked when later Settlements would make the ledger unsafe.
  • The Group timeline is an Activity Feed, not a chat system.
  • Fund Mode may add Proposal-scoped comments plus lightweight proof attachments later, but not a general Group-wide chat system in the MVP shape.
  • The core modules to deepen are profile identity and join flow, Group and membership ledger, Expense entry and split validation, Source Currency conversion and Exchange Rate Snapshots, Expense Proof storage, balance computation and simplified settlement graph, settlement orchestration and receipt generation, and sponsor integration adapters for LI.FI and Zerion.
  • LI.FI is the primary sponsor support adapter after Split Mode hardening, focused on routing a debtor's funds during Settlement through hidden-route Route funds for Settlement UX.
  • Direct cross-chain creditor settlement is out of scope for the MVP.
  • Zerion is a secondary intelligence layer via Zerion CLI and related analysis, not a user-facing “connect with Zerion” wallet SDK for the core app.
  • Fund Mode keeps Treasury, Contribution, and Proposal concepts separate from Split Mode Settlement concepts.

Testing Decisions

  • Good tests should validate observable behavior, not implementation details.
  • The highest-value tests are the ones that prove the ledger stays correct when users do normal and error-prone actions.
  • Priority unit tests should cover split validation, balance computation, rounding behavior, and simplified settlement graph outputs.
  • Priority conversion tests should cover Source Currency conversion, Exchange Rate Snapshot persistence, rounding, and the rule that historical Expenses do not reprice automatically.
  • Priority integration tests should cover Expense create/edit/delete guards, Settlement orchestration, Receipt generation, and leave-Group zero-balance enforcement.
  • Sponsor integration tests should mock LI.FI and Zerion boundaries and assert the app's decisions, not vendor SDK internals.
  • Wallet and token transfer tests should cover insufficient-USDC, insufficient-SOL, and recipient token-account creation decisions.
  • Mobile-focused smoke tests should cover join-from-link, settle-from-link, post-connect intent restoration, zero-state create flow, and receipt rendering on common narrow viewports.
  • The current codebase has limited formal test coverage; ongoing work should start by extracting pure modules and testing those first.

Out of Scope

  • Fundy on-chain execution as a first-class money-movement surface in the MVP
  • Scoped Agent Access and agent-paid use of the Agent Skill Endpoint in the MVP
  • Scoped Agent Access API in the MVP
  • New Telegram bot implementation inside the FundWise web repo
  • Telegram mini app as a first-class product surface in the MVP
  • Wallet-embedded mini dapp as a first-class product surface in the MVP
  • Native mobile app as a first-class product surface in the MVP
  • Real-time Group-wide chat
  • AI bill parsing beyond basic receipt-photo upload
  • Natural-language Expense entry beyond draft-safe FundWise Agent flows
  • Email-centric or non-wallet identity as the primary onboarding path
  • Mandatory embedded-only wallets (all users must use a single vendor embedded wallet) in the MVP
  • Gasless settlement in the MVP
  • Gas abstraction in the MVP
  • Multi-stablecoin settlement in the MVP
  • Direct cross-chain Settlement to the creditor in the MVP
  • Partial settlements
  • Installment or escrow-based settlements
  • Rewards, loyalty systems, or NFT reputation
  • Fund Mode mini-games or prediction-market-like mechanics in FundWise
  • Creator approval for Group joins
  • Advanced Group roles and permissions
  • Public Groups or Group discovery

Further Notes

  • The main product story should stay simple: private Group creation, structured Expense entry, live Balance view, one-click USDC settlement, and a clear Receipt. Source Currency and Expense Proof should be discussed only as future improvements unless implemented end to end.
  • Do not claim an empty market. The correct positioning is not "the first crypto Splitwise"; it is "wallet-native Group settlement with live USDC finality and verifiable Receipts."
  • Multi-chain and wallet-readiness layers are supporting features. CCTP and LI.FI help when a debtor's funds are not already on Solana in USDC. Zerion helps with wallet analysis, reminders, and future agent functionality.
  • Fund Mode is the north-star product and should be documented as Treasury plus Proposal functionality. It should not be claimed as complete until Proposal creation, approval/rejection, proof/history, and execution are implemented end to end.
  • Treat live yield, automatic Settlement, any-chain / any-currency Settlement, gasless UX, Fundy on-chain execution, and agent-paid money movement as future claims unless they are implemented end to end and reclassified in docs/shipped-vs-planned.md.
  • Longer-term roadmap candidates include Seeker, Telegram mini app, embedded wallets, Bridge.xyz, Visa/card payments, social login, gas abstraction, full multi-chain funding/wallet support, and broader mobile surfaces, but those should be added only after the core Group ledger and settlement experience is genuinely reliable.