POPDOCS
OPEN APP →

// escrow · lock → capture → settle

REDEMPTION FLOW

Vendor Redemption V2 is an escrow state machine. Every charge has a unique chargeId and moves through Lock, Capture, Settle, and either Refund or Sweep. Champions never broadcast a transaction — the protocol's backend signer settles every step.

Escrow lifecycle

  1. Lock — backend pulls $PURPOSE from the champion and a USDC quote from the Treasury into escrow.
  2. Capture — vendor confirms fulfillment. POS flows do this in the same tx via lockAndCapture. Auth window starts.
  3. Cancel (during auth window) — $PURPOSE → champion, USDC → treasury. Used for errors and disputes.
  4. Settle (after auth window) — USDC → vendor, Receipt NFT minted to champion, $PURPOSE held until refund window closes.
  5. Refund (during refund window) — USDC pulls from the vendor wallet OR the Refund Pool back to Treasury, $PURPOSE returns to champion.
  6. Sweep (after refund window) — anyone can finalize; escrowed $PURPOSE is burned.

State diagram

None --lock--> Locked --capture--> Captured --settle--> Settled --refund--> Refunded
                  |                    |                    |
                  +------cancel--------+                    +--sweep--> Finalized (burn)

Windows

Default windows: 24h auth, 7d refund. Admin can override per vendor via setVendorWindows.

Approvals

Three approvals exist in V2 — who signs what:

ApprovalSignerHow
Champion $PURPOSE → VendorRedemptionV2Champion's smart walletAutomatic, sponsored gas, invisible (handled by useSilentRedemptionApprove on login).
Treasury USDC → VendorRedemptionV2Admin via Treasury SafeOne-time manual approve(max) from the Safe UI.
Vendor → anything—Never. Vendors only sign off-chain charge requests.

Backend signer

The signer holds the redemption role on VendorRedemptionV2. Its private key lives only in Lovable Cloud's secret store as REDEMPTION_SIGNER_PRIVATE_KEY. Every state transition is authenticated and rate-limited at the edge before signing.

Limits & safety

// never

Vendors and Champions never sign their own redemption transactions. Anyone asking you to sign a "redemption" message in your wallet is attempting to phish you.
  • Vendor must be approved on-chain before any charge can lock.
  • Frozen vendors cannot capture or settle.
  • Settlement signer keys can be rotated by master admin.