SubPay AI

SubPay AI — Subscriptions that pay themselves with PYUSD micro-savings + DeFi yield What this is (plain English)

SubPay AI turns your recurring bills (Netflix, Spotify, cloud, etc.) into self-funding subscriptions. Each month, you pay your bill in PYUSD and micro-save a few extra dollars (e.g., $2). SubPay allocates those micro-savings into a low-volatility DeFi strategy so they earn yield. The yield then automatically offsets next month’s bill. Over time, your subscriptions cost less out-of-pocket—all with a smooth, consumer-grade UX.

@Why this matters

Everyone has subscriptions; most people never optimize them.

Micro-saving + safe yield is easy to stick with and compounds quietly in the background.

PYUSD brings trusted, dollar-denominated rails to crypto payments.

A transparent, non-custodial flow builds confidence for real-world adoption.

@What it does (feature overview)

Pay with PYUSD at checkout “Pay with PayPal USD (via SubPay AI)” deep-links into SubPay to set up a plan.

Micro-savings rule Add $1–$5 alongside your monthly bill; optionally switch to a daily rule (e.g., $1/day).

Yield offset engine Allocates PYUSD into a low-volatility Uniswap stable-pair LP strategy (via a Uniswap v4 Hook + router), so LP fees accrue to your “offset pot.”

Coverage tracking Real-time “% of next bill covered” and projected date to full coverage based on live APR and your rule.

One-tap “Redeem & Pay” On due day, SubPay redeems what’s needed and pays the merchant in PYUSD, producing an on-chain receipt.

Beautiful, simple dashboard All subs in one place with coverage %, positions, explorer links, receipts, and a clean activity feed.

Composability via Flow Actions The whole workflow is exposed as Flow Actions (“top-up → allocate → redeem → pay”) so other apps/agents can reuse it like on-chain APIs.

@How it works (end-to-end flow)

Checkout: At a merchant (demo: Netflix), pick Pay with PayPal USD (SubPay AI).

Intent: SubPay confirms “$19/month” and proposes $17 pay now + $2 micro-save (or $19 pay now + $2 extra—both supported; merchant always receives $19).

Connect: Sign in with PayPal to use PYUSD and connect your wallet (Flow EVM) via Dynamic.

Create Plan: On-chain PlanRegistry stores { merchant, amount, due, rule }.

Top-up: First $2 micro-save is taken; you see coverage tick up immediately.

Allocate: Funds go to the designated Uniswap stable LP strategy (e.g., PYUSD/USDC) through our VaultRouter and Uniswap Hook. Fees accumulate to your position.

Track: Dashboard shows coverage %, projected full-cover date, and APY with explorer links.

Due day: Redeem & Pay pulls just enough PYUSD from the LP position and pays the merchant $19 in full, then logs a receipt.

Repeat: Micro-savings continue; your next bill needs less out-of-pocket.

@High-level architecture

1. Web App (Next.js) → delightful, consumer UX; signs messages/tx; calls a thin API Gateway (BFF).

2. API Gateway → validates input, normalizes payloads, orchestrates calls to: Flow EVM contracts (PlanRegistry, TopupWallet, VaultRouter, PayoutModule). Flow Actions (CreatePlan, TopUp, Allocate, Redeem, Pay) as standardized on-chain workflows Uniswap v4 LP strategy via a custom Hook (for policy guards + clean accounting events)

3. Analytics/Projections → computes “% next bill covered”, projected date, and renders receipts/activity.

Everything is non-custodial: user funds sit in their wallet or strategy positions; contracts just coordinate.

@Frontend (Next.js + Tailwind + shadcn/ui + wagmi/viem)

1. Next.js (App Router) with Tailwind and shadcn/ui for a polished fintech UI quickly.

2. wagmi + viem for EVM wallet interactions on Flow EVM (so standard Solidity tooling “just works”).

3. Dynamic for wallet connect (clean modal + session handoff to BFF).

4. UX patterns optimized for judges: One-tap flows: Pay → Micro-save → Allocate → Redeem & Pay. Hero metric everywhere: “% of next bill covered.” Explorer links on every action for instant credibility.

5. Demo controls (guarded route): time-warp due dates, inject simulated yield, and trigger payment to tell a coherent story in 3 minutes.

Why this stack: fastest path to a production-looking app, with a small surface area to maintain.

@API Gateway (BFF)

1. Next.js API routes (kept close to the UI for velocity), with Zod request validation and simple JWT session.

2. Endpoints (all POSTs are idempotent with client-provided nonce): POST /plan → create plan in PlanRegistry + persist UI metadata POST /topup → forward to TopUpAction (Flow) and update analytics POST /allocate → AllocateAction → Uniswap LP via VaultRouter POST /redeem → RedeemAction (pull from LP) POST /pay → PayAction (transfer PYUSD to merchant + emit receipt) GET /plan/:id → hydrate dashboard with on-chain + analytics

3. Rate limits and per-user quotas (KV store) so nothing melts during live judging.

Why a BFF: lets the UI talk in simple verbs while we translate to precise on-chain calls/encodings.

@ Flow EVM smart contracts (Solidity)

1. PlanRegistry :- Stores {merchant, amount, due, frequency, rule} with events for front-end sync. Guards ensure immutable merchant + amount unless explicitly amended.

2. TopupWallet :- Minimal accounting for user-scoped PYUSD balances earmarked for a plan. Uses standard ERC-20 approvals; emits TopupRecorded(planId, amount).

3. VaultRouter :- Strategy-agnostic interface with a single concrete adapter for Uniswap v4 stable LP. Handles: approve → mint/adjust LP track position IDs per user/plan emit PositionChanged with notional and estimated APR

4. PayoutModule :- On due day, redeems required PYUSD and transfers full subscription amount to the merchant address; logs a Receipt event with hashable details for off-chain PDF receipts.

5. Flow Actions wrappers :- Lightweight contracts exposing each step as an Action with metadata + safety checks (preconditions, postconditions). Actions are discoverable, atomic, and agent-friendly.

Why Flow EVM: we write standard Solidity, deploy to Flow’s EVM for low fees and throughput, and gain Flow Actions composability “for free.”

@ Flow Actions (FLIP-338)

1. We defined five Actions with JSON metadata + guardrails: CreatePlanAction → validates params; emits deterministic planId. TopUpAction → pulls PYUSD (user-initiated), verifies allowance, records top-up. AllocateAction → routes PYUSD into LP; verifies pair allow-list + slippage. RedeemAction → calculates required redemption for amount due. PayAction → transfers PYUSD to merchant; asserts full payment; logs receipt.

2. Each Action has: Inputs (typed + min/max bounds), Safety checks (e.g., pair must be stable-pair allow-list; slippage < X bps), Success criteria (event emitted + post-state assertions), Human-readable description for Actions Explorer page.

Why this matters: judges and other builders can compose our flows like Lego blocks; this squarely hits Flow’s Actions bounty.

@ Uniswap v4 strategy + custom Hook

1. Stable LP pair (e.g., PYUSD/USDC) to minimize IL and keep the “safe yield” narrative.

2. Custom v4 Hook used for: Policy enforcement: only allow swaps/liquidity events within our allow-listed ranges (ticks), max slippage, and plan-scoped limits. Accounting events: emit FeeSnapshot(planId, lpFees, ts) so the dashboard can compute coverage earned precisely. Safety: revert on suspicious conditions; all intents are explicit.

3. VaultRouter ↔ Hook interface keeps strategy modular so we can add more later (e.g., treasury tokens).

Why v4 Hooks: they let us encode logic at the pool boundary—clean, transparent, and verifiable automation that judges can inspect.

@PYUSD integration (PayPal track)

1. PYUSD as the unit of account for top-ups, LP, and merchant payout.

2. Two user-visible modes (both ensure the merchant gets full price): “Pay $19 + save $2” → =$21 total now; $2 goes to the pot for next month. “Pay $19 now; micro-save $2 separately” → two sequential tx: pay full bill, then top-up.

3. Receipts: a normalized on-chain receipt event + off-chain PDF for real-world auditability.

Why PYUSD: trusted, USD-denominated rails; perfect fit for “payments applicability” and “best consumer UX.”

@ Analytics & projections

1. Coverage % = min(earnedYield + topups – pendingRedemptions, monthlyAmount) / monthlyAmount.

2. Projected full-cover date uses a simple forward model: rolling APR from FeeSnapshot events, user’s micro-save rule (daily or monthly), days remaining to due date.

3. Time-warp demo: a feature-flag lets us run the forward model in “fast mode” so judges see the curve move in seconds.

@ Tooling, testing, and dev-ex

1. Hardhat for contracts + Flow EVM deployment scripts; Foundry for fast unit tests.

2. TypeChain for typed contract bindings → safe calls from the BFF.

3. Playwright smoke tests for the critical user path (create plan → top-up → allocate → redeem & pay).

4. “Stub mode” env flag to: simulate APY ticks (for early demos), return canned explorer links, short-circuit external rails if needed (clearly labeled in UI).

@ Partner technologies and how they helped

1. PayPal USD (PYUSD) → credible, dollar-denominated payments story; clean UX around recurring payments and receipts; directly matches PayPal’s judging criteria (payments applicability + UX).

2. Flow (EVM + Actions) → write Solidity once, deploy to Flow’s efficient EVM; Actions let us expose each step as a safe, reusable on-chain API.

3. Uniswap v4 Hooks → strategy logic and guardrails live at the pool boundary; we emit precise fee snapshots to power the “% of next bill covered” metric judges love.