PYPay

Problem Statement

PyPay is a payment gateway enabling merchants to accept PYUSD with zero blockchain friction. The platform abstracts wallet management, gas fees, and chain complexity through ERC-4337 account abstraction and cross-chain routing (ETH Sepolia and ARB Sepolia supported).Traditional crypto payments require users to manage MetaMask wallets, backup seed phrases, purchase native tokens for gas, manually bridge assets, and sign repeated transaction prompts. Merchants are locked to single wallet addresses with no unified payment tracking. These barriers prevent mainstream adoption.PyPay addresses these issues with a dual-authentication system. Customers pay using device biometrics (Face ID/Touch ID) without needing wallets or seed phrases. Gas fees are automatically sponsored, eliminating the need for ETH. Cross-chain payments allow users to choose the lowest-cost chain and bridge funds if needed.Merchants connect existing wallets and receive PYUSD directly to their addresses. The system provides real-time gas cost comparisons and unified payment tracking across multiple merchant accounts.

Solution

Technical ArchitecturePyPay implements a three-tier architecture with smart contracts, off-chain services, and frontend applications communicating via REST APIs and blockchain events.Smart Contract InfrastructureThe contract layer uses Solidity 0.8.27 deployed on chain and tested in forked network via Foundry. All contracts leverage Solady for gas-optimized ERC-4337, EIP-712, and ERC-1271 implementations.TapKitAccountExtends Solady's ERC4337 with session key validation. Session keys are client-generated ECDSA keypairs with 64-byte public keys hashed on-chain. Guardian authorization occurs via EIP-191 signatures verified through SignatureCheckerLib supporting both EOA and contract signers. The validateUserOp function decodes session signatures, recovers signers via ecrecover, and validates against stored hashes with time-based expiration enforcement.AccountFactoryCreates deterministic accounts via CREATE2 with salted deployments following ERC-4337 counterfactual patterns. Minimal proxy clones reference a singleton implementation reducing deployment gas costs per account.CheckoutHandles invoice settlement through two-step verification. First validates merchant status via MerchantRegistry staticcall preventing state modifications. Second processes PYUSD transfers using SafeERC20 handling non-standard implementations. Emits PaymentComplete events with invoice IDs, merchant addresses, and amounts for off-chain indexing.TapKitPaymasterImplements IPaymaster with policy-based sponsorship. validatePaymasterUserOp decodes calldata extracting function selectors and invoice parameters, verifies Checkout.settle targets, queries MerchantRegistry for merchant status, validates expiration timestamps and payment limits, and checks invoice paid status. Maintains EntryPoint deposits for atomic gas accounting.BridgeEscrowManages cross-chain transfers via lock-release mechanism. lockForBridge transfers PYUSD to escrow emitting BridgeLocked events with bridge IDs, amounts, destination chains, and recipients. releaseForBridge verifies relayer authorization, checks release status, and transfers from bridge inventory. Bridge IDs are deterministic hashes preventing replay attacks.MerchantRegistryMaintains merchant mappings with payout addresses, fee basis points, and active flags. Owner-restricted registration enforces centralized onboarding. Exposes view functions for paymaster validation and checkout payout routing.Backend ServicesIndexerRuns Fastify with Prisma providing REST APIs for invoices, payments, and bridges. Implements viem watchContractEvent establishing WebSocket connections to Alchemy for real-time event streaming. Extracts PaymentComplete events, queries transaction receipts, and persists to PostgreSQL via Prisma ORM.RelayerHandles session key enablement and UserOperation submission. Receives public keys, hashes via keccak256, constructs EIP-712 messages, signs with guardian key, and submits enableSessionKey transactions. For payments, receives partial UserOperations, queries gas prices, adds paymaster data with time bounds and signatures, and submits to EntryPoint. Maintains per-account nonce tracking preventing conflicts.Cost EngineCalculates gas costs via eth_gasPrice RPC calls and historical consumption data for both Arbitrum Sepolia and Ethereum Sepolia chains. Exposes /costs/quotes returning USD costs per chain with fifteen-second polling updates.Bridge CoordinationImplements four-step flow: user creates lockForBridge UserOperation submitted via relayer, indexer detects BridgeLocked storing metadata, relayer verifies finality and constructs releaseForBridge, relayer submits release transaction paying gas reimbursed through fees. PYUSD inventory maintained on both chains with periodic owner-controlled rebalancing.Frontend ImplementationNext.js 15 App RouterUses Next.js 15 app router with server components. Wallet integration via wagmi v2 and RainbowKit v2 supporting MetaMask, WalletConnect, Coinbase Wallet, and injected providers.Passkey AuthenticationUses SimpleWebAuthn wrapping WebAuthn APIs. Registration invokes navigator.credentials.create with ES256, extracts 64-byte ECDSA public keys from attestation responses, and sends to relayer for account initialization. Authentication uses navigator.credentials.get for signature verification before UserOperation construction.Session KeysEphemeral ECDSA keypairs stored in sessionStorage, generated via viem's privateKeyToAccount. Private keys sign UserOperation hashes per EIP-4337 getUserOpHash including chainId and entryPoint preventing replay attacks.Technology StackContracts:Solidity 0.8.27, Foundry, Solady, OpenZeppelin.Backend:TypeScript, Node.js 20, Fastify, Prisma, viem, PostgreSQL.Frontend:Next.js 15, React 18, wagmi, RainbowKit, SimpleWebAuthn, Tailwind CSS, Playwright.Infrastructure:Alchemy RPC, Turbo monorepo, pnpm.