State machines · sourced from spec v2

User flows

How Klaro actually works.

Every money flow is a state machine. These are the canonical journeys with their states, on-screen timelines, and stuck-state handling. Sourced from Klaro_Final_Testnet_Complete_Full_Flow_Design_v2.md.

  1. §11

    Invoice creation

    Vendor drafts an invoice, picks settlement assets, and shares a hosted link. Buyer acceptance hash is prepared at creation time so the receipt can later prove both sides.

    live testnet
    RolesVendor
    States
    DraftOpenPaymentStartedPartiallyFundedFundedScreeningHeldReleasedSettledRefundedExpiredDisputedCancelledRejectedVoided
    On-screen timeline
    1. Created
    2. Shared
    3. Viewed
    4. Payment started
    5. Paid
    6. Screening
    7. Released
    8. Receipt ready
    Stuck-state handling
    Invoice open, not viewed
    Send first reminder via copy-link / WhatsApp / email.
    Viewed, not paid
    Send payment nudge with hosted link.
    Invoice expired
    Suggest creating a fresh invoice.
  2. §12

    Customer invoice payment

    Customer opens the hosted invoice, reviews who is asking for money, accepts the invoice in plain language (EIP-712 for wallets, magic-link for email payers), and pays in USDC on Arc or any supported chain.

    live testnet
    RolesBuyerVendor
    States
    ReviewingAcceptedPayingPartiallyFundedFundedSettledRefunded
    On-screen timeline
    1. Preparing payment
    2. Waiting for wallet
    3. Moving funds
    4. Confirming on Arc
    5. Payment received
    6. Receipt ready
    Stuck-state handling
    Wrong chain
    Switch chain or use cross-chain payment route.
    Insufficient gas
    Explain Arc uses USDC for gas and show how to fund.
    Underpaid
    Show remaining amount and pay-remainder action.
    Overpaid
    Auto-refund excess; admin only if auto-refund fails.
  3. §13

    Cross-chain receive

    Customer has USDC on another chain. App Kit unified balance or CCTP V2 route the funds to Arc without making the buyer learn bridge mechanics.

    simulated
    RolesBuyer
    States
    InitiatedRoutedSettledFailed
    On-screen timeline
    1. Detect source chain & balance
    2. Pick unified balance or CCTP
    3. Customer confirms
    4. USDC made spendable on Arc
    5. Escrow Funded
  4. §20·§21

    Cashout quote → order

    Vendor opens Partner Cashout, picks INR, sees a 60–120s rate quote (rate · LP spread · Klaro fee · expiry), then locks the order. LP fills off-platform and submits proof.

    simulated
    RolesVendorLP
    States
    RequestedQuotedLockedLPAssignedPayoutSentProofSubmittedVerifyingWaitingVendorConfirmationReleasedRefundedDisputedExpiredCancelled
    On-screen timeline
    1. Quote created
    2. USDC locked
    3. LP assigned
    4. Payout sent
    5. Proof submitted
    6. Vendor confirms / proof verified
    7. USDC released to LP
    Stuck-state handling
    No LP assigned
    Show "Looking for LP"; let vendor cancel before lock.
    LP late on proof
    Surface support case with SLA and case ID.
    Proof rejected
    LP resubmits; vendor sees state change.
    Amount / name mismatch
    Freeze and escalate to admin/risk review.
  5. §25

    Cashout dispute

    Either party opens a dispute from a fixed reason list. The order freezes, USDC stays in escrow, and an admin case opens with a deadline and an evidence checklist.

    simulated
    RolesVendorLPOperator
    States
    OpenedEvidenceRequestedEvidenceSubmittedUnderReviewDecidedReleasedRefundedSlashed
    On-screen timeline
    1. Opened with reason code
    2. Evidence requested
    3. Evidence submitted
    4. Under admin review
    5. Decision made
    6. Funds released / refunded / slashed
    Stuck-state handling
    Awaiting evidence
    Show deadline countdown + missing-evidence checklist.
    Admin review delayed
    Surface SLA and case ID; both sides notified.
  6. §14·§15

    Screening & receipt mint

    On funding, Klaro runs screening against the buyer wallet and payment trail. On pass, the escrow releases to vendor and a Stenn-Proof receipt is minted with hashes of invoice + buyer acceptance + screening result.

    live testnet
    RolesSystemOperator
    States
    PendingPassedHeldReleasedMintedVerified
    On-screen timeline
    1. Screen wallet + chain trail
    2. Pass → release to vendor
    3. Mint receipt with proof bundle
    4. Anchor on Arc
    5. Public receipt page live
  7. §22

    LP onboarding

    LPs are invite-only. Application → review → stake deposit → activation. Designed to feel like partner onboarding, not consumer signup.

    simulated
    RolesLPOperator
    States
    InvitedApplicationStartedSubmittedUnderReviewApprovedRejectedStakeRequiredActiveSuspended
    On-screen timeline
    1. Invite received
    2. Application + docs submitted
    3. Review (wallet risk, payout proof, source-of-funds)
    4. Approval + stake required
    5. Stake deposited → active
User flows · Klaro