# How people actually reach Parley: journeys, integration decisions, and roadmap
Written 2026-10-17. **DECIDED** marks what is built.

## The question: "Will the user use this page, or some other button?"
**Both, by design: one product with one home and several doors.** The **panel** (the web page) is the *home*: your whole inbox, history and settings live there. Every other surface is a *door* that opens the same panel already pointed at the right conversation. Nobody has to learn a new place first.

| Door | Who uses it | What they see | Install | Status |
|---|---|---|---|---|
| **1. PayBox agent plugin** | A person talking to Claude/ChatGPT with PayBox | Agent says "I sent your private message / payment request"; tool returns a **link** that opens the panel on that thread; PayBox shows its own approval screen for any money action. A PayBox wallet is linked once (`/?link=<wallet>` → `register_key`), then its inbox opens in the panel | Install the plugin once in PayBox | **Built** (9 tools, deep links, PayBox link flow) |
| **2. Merchant widget** | Payers on a merchant's invoice/checkout page | A floating "Questions about this invoice?" button → panel slides in inside the page, thread bound to that invoice | Merchant pastes one `<script>` tag | **Built** (`/widget.js`, demo at `/demo.html`) |
| **3. Browser extension** | Users on MoonPay/Helio/PayBox pages we don't control | Same floating button, injected; reads the pay-link/charge/tx id from the URL | Optional; user installs once | **Built (MV3 draft, untested in a store)** |
| **4. Links in what already exists** | Anyone who got an email, receipt, PDF invoice or webhook-driven message | A link or **QR code** `…/?ctx=invoice:INV-1001&to=0xMerchant` | Nothing | **Built** (deep links and QR) |
| **5. Direct** | Power users | Open the panel, press **New**, paste a wallet or a tx hash | Nothing | **Built** |

**DECIDED:** the *agent path* is the primary integration for the hackathon (it is a PayBox plugin), the *widget* is the path that shows MoonPay-ecosystem value (merchants), and the *panel* is where everything converges. Users never have to "use only the page" or "only a button".

### Typical journeys
1. **Merchant ↔ payer (Merchant Tools).** Merchant creates an invoice (Commerce pay link/Stripe/PDF) and includes the Parley link or QR. Payer scans, asks a question privately, merchant replies with a **payment request card**; payer presses **Pay with my wallet** (or tells their PayBox agent to pay); a sealed **receipt** goes back and the thread shows **PAID ✓**, verified on-chain.
2. **Human ↔ their agent (PayBox).** Agent explains *why* it wants to spend, in a sealed thread tied to the PayBox `request_id`; the user approves in PayBox. Persistent, wallet-attributed memory for a stateless sandbox.
3. **Wallet ↔ wallet.** Any tx hash is a room. Two humans who just transacted can talk without exchanging any other contact detail.
4. **Guest / concierge (judges and first-time users).** One click on **Try the 1-minute demo**: no wallet, no install. A throwaway wallet is created in the browser, a reply and payment card arrive, **Pay** auto-fetches test money, and the concierge verifies the payment on-chain.

## Friction and the "external URL" concern (MoonPay may not want users leaving their product)
Honest answer: **yes, sending a user to another site is friction, and a payments company may refuse it.** What Parley does about it:
- **Nobody has to leave their context by default.** The agent path stays inside the chat (PayBox shows its own approval screen). The widget opens the panel **inside the merchant's page** (an in-page overlay, no navigation). A link is only the fallback.
- **The cost for a first-time user is small and fixed:** one click to connect, one free signature, no gas, no install, no account. Every later message is one click.
- **For MoonPay itself the intended end state is not "our website".** The panel is a static, embeddable app and the protocol is open: MoonPay can host the same panel under their own domain/white label, load it as an iframe/component in their checkout and dashboards with *their* wallet session (no extra signature prompt), or call the protocol headlessly through an SDK and build native UI. The hackathon demo uses our URL only because we have no access to MoonPay's surfaces.
- **If an external URL is unacceptable,** the `<script>` widget can be served from the partner's own origin, and the contract + relay can be run by the partner.
Phase 2 below therefore includes: a headless SDK, a React/web component, and a white-label build.

## What is built vs. what is NOT (honest)
Built and tested: contracts (48 tests), plugin (9 tools, 21 end-to-end checks), PayBox-wallet link flow, cross-chain payment cards, panel (health strip, 61-entry error catalog, pay-with-wallet, receipts, public rooms, share/QR), relay + concierge (live on Base Sepolia, on-chain payment verification), widget, extension draft.
Not built: mainnet deployment; notifications; group UI (contract supports groups); attachments; Solana; ENS/Basenames.

## Next small features (each a few hours)
- **Base mainnet instance**: one deploy plus config; the plugin already lists Base first.
- **Content-free notifications**: "New private message on invoice INV-1001" by email or push, opt-in; content never leaves the chain.
- **Message requests (accept/block)**: the contract already has it (first message free, then a request fee); needs UI.
- **Basenames/ENS** for readable recipients.
- **Context on the PayBox approval screen**: the payment proposal summary links the thread, so the approver reads why before approving (works today through tool text).
- **Device management**: list, add and revoke a wallet's keys (the contract supports up to 5 per wallet).

## Planned feature: PayBox-native inbox (no extra step for PayBox users)
**Goal.** A PayBox user who is already onboarded (wallet + passkey approvals) opens their Parley inbox and reads replies **inside the PayBox chat**, with no Parley key, no password manager and no passkey of ours.

**Why it is not in the MVP.** Reading end-to-end-encrypted messages needs a private secret that only the wallet owner can produce. Browser wallets give it to us through one off-chain signature. PayBox plugins can only return transaction, Solana or x402 proposals; there is no message-signing proposal, and a transaction signature cannot be used because it becomes public on-chain. So today a PayBox wallet makes a Parley key once (generated on the device, kept by the password manager, or a passkey) and approves one `register_key` transaction. Everything below removes even that step.

**Track 1: signature proposal in PayBox (preferred; needs PayBox).**
- Parley proposes a typed-data signature (EIP-712) over a fixed, domain-bound text: `Parley inbox key v1 · chain · contract · wallet`. PayBox shows it with the same passkey approval it uses for transactions.
- Parley derives the inbox key from that signature exactly as it does for MetaMask: no new secret, same key on every device, works for the wallet's whole history.
- Requirement on PayBox: deterministic signatures for a given message (RFC 6979, or a deterministic MPC scheme); otherwise fall back to the device-key path. Smart-account wallets sign through ERC-1271, which the contracts already verify.
- What we ship: a `request_inbox_key` tool, a proposal kind (for example `io.paybox/signatureProposal`) written up as a short spec for the PayBox team, and the panel reading the signature from a PayBox deep link.

**Track 2: x402-authenticated key service (works without PayBox changes).**
- At setup, one PayBox transaction registers a Parley key that is generated **inside a hardware enclave** (for example AWS Nitro) and never leaves it; the enclave's code measurement is published so anyone can check what runs.
- To read, the agent calls a `read_sealed` tool; it returns an **x402 proposal** of a fraction of a cent to the key service. The payment authorisation is signed by the wallet, which proves the reader controls it. The enclave decrypts that wallet's threads and returns the text to the agent, so "what did the merchant say?" is answered inside the PayBox chat.
- Trade-off, stated plainly: for wallets that opt in, the service could technically read their messages (like email providers), so it is **opt-in per wallet**. Browser wallets and the device-key path stay end-to-end. Mitigations: enclave attestation, per-wallet rate limits, no plaintext logs, and keys that can be revoked on-chain at any time (`revokeMessagingKey`).
- x402 runs on Base mainnet USDC, so this ships with the mainnet deployment.

**Track 3: reading in the agent conversation.** With either track, `read_room` returns decrypted text for the user's own threads, so the whole merchant loop (question → payment card → `propose_payment_from_thread` → receipt) happens without leaving PayBox.

**Milestones.** (1) Write the signature-proposal spec and share it with the PayBox team. (2) Build the enclave key service and `read_sealed` behind a feature flag on Base Sepolia. (3) Mainnet with x402 reads. (4) Make Track 1 the default once PayBox supports it, and keep Track 2 for wallets that cannot sign deterministically.
**Success measure.** A PayBox user goes from installing the plugin to reading a merchant's encrypted reply in under a minute, with only PayBox approvals.

## Roadmap (after the hackathon)
**Phase 1 (weeks 1–2): production-ready on Base.** Mainnet relay policy: no blanket sponsoring; free first-time setup and a small daily allowance per wallet, merchant-sponsored quotas for their customers (billed per month), and pay-per-message in USDC through x402 for everyone else; PayBox users never need it because they pay gas in their PayBox approval. Mainnet deploy with a multisig owner and timelock; external security review; wallet matrix (MetaMask, Rabby, Coinbase, WalletConnect); device-key management UI (add/revoke up to 5 devices); in-browser signing for smart-contract and MPC wallets through WalletConnect (today they use the PayBox link flow); rate-limit and spam economics (request fee) surfaced in UI.
**Phase 2 (weeks 3–6): MoonPay integration depth.** PayBox-native inbox (above); Commerce/Helio connector: webhook handler that posts a Parley link into receipts; Helio checkout iframe `postMessage` listener to auto-detect the charge; PayBox: richer plugin outputs, `request_id` rooms for agent receipts; x402 paid-service review rooms; opt-in notifications; groups for multi-party deals (contract supports up to 50).
**Phase 3 (months): chain-agnostic.** Inbox-home resolution across chains (the recipient's chain), relay mirroring and receipts, Solana wallets via ed25519-signed attestations, ERC-4337 paymaster instead of a custodial relay, optional dedicated message ledger/app-chain settling to many chains. Encrypted attachments (IPFS), read receipts, search.
**Business model.** Per-message protocol fee (already in the contract, on testnet 1e12 wei), merchant SaaS (branding, retention, exports with consent), sponsored relay as a paid feature, white-label for payment platforms.

## Risks to keep honest
Metadata is public; no forward secrecy; key derived from a wallet signature (phishable if a site asks for the same text); relay is a centralised convenience; testnet only today; hosted PayBox checks are listed in SUBMISSION.md.