StreamPay

StreamPay: Real-Time Wage Streaming Protocol What It Is StreamPay is a blockchain-based payroll system that pays employees every second they work instead of waiting for bi-weekly or monthly paychecks. Workers can withdraw their earned wages instantly, getting paid in real-time as they clock in and out.

The Problem We Solve Traditional payroll creates cash flow problems for workers who live paycheck-to-paycheck. If you work Monday but payday is Friday, you can't access that money for 4 days. StreamPay eliminates this wait - you earn $10/hour, you get paid every second, withdraw anytime.

How It Works (3 User Roles)

1. Employer Dashboard

Deposits PYUSD (stablecoin) into the smart contract vault Adds employees with annual salaries (e.g., $50,000/year = ~$0.0016 per second) Manages employee access 2. Employee Dashboard

Clicks "Clock In" to start earning Watches balance increase in real-time every 2 seconds Clicks "Withdraw" to instantly receive 70% of earned wages 30% goes to escrow (explained below) Clicks "Clock Out" when done working 3. Manager Dashboard

Reviews employee work history Approves escrow releases (the held 30%) Acts as fraud protection layer The 70/30 Split System When you withdraw, you get:

70% immediately - instant cash to your wallet 30% held in escrow - released after manager approval This protects employers from timesheet fraud while giving workers instant access to most of their earnings.

Sponsor Technologies Used

1. PYUSD (PayPal USD Stablecoin) Why: Workers need stable value, not volatile crypto How Used: All wages paid in PYUSD (1 PYUSD = $1 USD always) Contract Address: 0xCaC524BcA292aaade2DF8A05cC58F0a65B1B3bB9 on Sepolia Technical Detail: PYUSD uses 6 decimals (not 18 like ETH), so $50 = 50,000,000 units Integration: Every deposit, withdrawal, and escrow release transfers PYUSD tokens through our smart contract
2. Pyth Network (Real-Time Oracle Price Feeds) Why: Workers in different countries need to see wages in local currency How Used: Converts PYUSD → USD → PHP in real-time Feeds Used: PYUSD/USD price feed (ensures $1 peg accuracy) USD/PHP price feed (Philippine Peso conversion) Technical Detail: Queries Pyth Hermes API every 5 seconds, calculates cross-rate multiplication for multi-currency display User Experience: Employee sees "$5.23 (₱290.15)" updating live as they work
3. EVVM (Ethereum Virtual Machine - Nonce System) Why: Enables future "pre-signed" withdrawals (sign once, withdraw 52 times) How Used: Built into smart contract with NonceState tracking system Security Feature: Each nonce (1, 2, 3...) can only be used once - prevents replay attacks Future Vision: Employee signs nonces 1-52 in January, can withdraw weekly without MetaMask prompts each time Current Status: Infrastructure ready in contract, not yet activated in UI (will be Phase 2 feature) Technical Detail: Mapping tracks usedNonces per employee, with preSignedHashes for authorized withdrawals Key Innovation: Per-Second Streaming Most payroll systems batch payments (hourly, daily, weekly). StreamPay calculates wages per second:

Work 1 hour = 3,600 seconds × salary rate Math example: $50k/year ÷ 31,536,000 seconds = $0.001585 per second Smart contract tracks lastClockIn timestamp, multiplies elapsed time by rate Balance updates happen on blockchain automatically, UI polls every 2 seconds for display Security & Fraud Prevention Clock-in verification: Can't withdraw without active clock-in Manager approval layer: 30% escrow requires human review Nonce system: Prevents duplicate withdrawals (EVVM) Emergency pause: Owner can freeze contract if exploit detected Active employee checks: Removed employees can't clock in or withdraw Technical Architecture Blockchain: Ethereum Sepolia Testnet (will be mainnet for production) Smart Contract: Solidity 0.8.20, deployed at 0xc63d7425d5f3960EdAB8A28AdF2468c89d3BBE3c Frontend: Next.js 14 + TypeScript + TailwindCSS (deployed on Vercel) Wallet Connection: RainbowKit + Wagmi hooks Price Oracle: Pyth Network Hermes API Stablecoin: PYUSD (6-decimal ERC-20 token) Real-World Use Case Maria the Construction Worker:

Clocks in Monday 8am By 12pm, earned $40 (4 hours × $10/hr) Withdraws $28 immediately (70%), $12 held in escrow Uses $28 for lunch and groceries same day Friday, manager approves escrow, Maria gets remaining $12 Total: No waiting for Friday paycheck, instant financial flexibility Impact For Workers: Eliminates 2-week cash flow gaps, reduces payday loan dependency For Employers: Reduces payroll processing costs, blockchain transparency prevents disputes For Global Workforce: PYUSD + Pyth enables cross-border payments without expensive wire transfers Why This Matters 2.5 billion people globally live paycheck-to-paycheck. StreamPay transforms wages from delayed batches into continuous streams - workers control their money the instant they earn it.

How StreamPay Was Built Architecture Overview StreamPay is a full-stack Web3 application combining Solidity smart contracts with a Next.js frontend, orchestrating real-time wage calculations on-chain with live price feeds and stablecoin payments.

Smart Contract Layer (Solidity) Core Innovation: Per-Second Math The trickiest part was calculating wages per second without overflow errors or precision loss. We convert annual salaries to per-second rates: $50,000/year ÷ 31,536,000 seconds = 0.001585 PYUSD/second In Solidity (6 decimals): 50000000000 ÷ 31536000 = 1585 units/second

Time-Based Accrual System Every clock-in stores block.timestamp. When withdrawing, we calculate: earned = (current_timestamp - lastClockIn) × salaryPerSecond This runs on-chain, making wage accrual trustless and verifiable.

The 70/30 Split Hack When withdrawing $100 (which is 70% of total), we reverse-engineer the full amount:

Available: $100 (user gets this) Total earned: $100 ÷ 0.7 = $142.86 Escrow: $142.86 - $100 = $42.86 (held for manager approval) This math ensures precise splitting without rounding errors in Solidity's integer arithmetic.

PYUSD Integration (PayPal USD) 6-Decimal Challenge Most ERC-20 tokens use 18 decimals (like ETH). PYUSD uses 6 decimals, which broke everything initially.

The Fix: Every transaction uses parseUnits(amount, 6) instead of the standard parseUnits(amount, 18):

Wrong: 50 PYUSD = 50000000000000000000 units Right: 50 PYUSD = 50000000 units We built a custom hook useContract.ts that wraps all PYUSD operations with correct decimal handling: // Approve PYUSD spending await pyusdContract.approve(vaultAddress, parseUnits(amount, 6))

// Deposit into vault await vaultContract.deposit(parseUnits(amount, 6))

// Read balance const balance = await pyusdContract.balanceOf(address) const formatted = formatUnits(balance, 6) // "50.123456"

How StreamPay Was Built Architecture Overview StreamPay is a full-stack Web3 application combining Solidity smart contracts with a Next.js frontend, orchestrating real-time wage calculations on-chain with live price feeds and stablecoin payments.

Smart Contract Layer (Solidity) Core Innovation: Per-Second Math The trickiest part was calculating wages per second without overflow errors or precision loss. We convert annual salaries to per-second rates:

In Solidity (6 decimals): 50000000000 ÷ 31536000 = 1585 units/second

Time-Based Accrual System Every clock-in stores block.timestamp. When withdrawing, we calculate:

This runs on-chain, making wage accrual trustless and verifiable.

The 70/30 Split Hack When withdrawing $100 (which is 70% of total), we reverse-engineer the full amount:

Available: $100 (user gets this) Total earned: $100 ÷ 0.7 = $142.86 Escrow: $142.86 - $100 = $42.86 (held for manager approval) This math ensures precise splitting without rounding errors in Solidity's integer arithmetic.

PYUSD Integration (PayPal USD) 6-Decimal Challenge Most ERC-20 tokens use 18 decimals (like ETH). PYUSD uses 6 decimals, which broke everything initially.

The Fix: Every transaction uses parseUnits(amount, 6) instead of the standard parseUnits(amount, 18):

Wrong: 50 PYUSD = 50000000000000000000 units ❌ Right: 50 PYUSD = 50000000 units ✅ We built a custom hook useContract.ts that wraps all PYUSD operations with correct decimal handling:

Why PYUSD Benefits Us:

Stability: Workers don't lose purchasing power to crypto volatility Compliance: PayPal's regulatory backing makes this enterprise-ready Familiarity: "PayPal USD" is easier to explain to non-crypto users than "DAI" or "USDC" Pyth Network Integration (Oracle Price Feeds) The Multi-Currency Problem Filipino workers earning PYUSD need to see their balance in Philippine Pesos (PHP) to understand purchasing power.

Solution: Cross-Rate Calculation Pyth doesn't have a direct PYUSD/PHP feed, so we chain two feeds:

Fetch PYUSD/USD price (should be ~$1.00) Fetch USD/PHP price (e.g., ₱56.50) Multiply: PYUSD → PHP = PYUSD/USD × USD/PHP The Hacky Part: 5-Second Polling Pyth feeds update sub-second, but querying every second hammered the API. We built React hooks with 5-second intervals: useEffect(() => { const interval = setInterval(fetchPrice, 5000) return () => clearInterval(interval) }, []) This gives "live" feel without rate-limiting issues.

Why Pyth Benefits Us:

Real-time accuracy: Prices update within seconds, not minutes (unlike Chainlink's longer intervals) Free testnet access: Hermes API doesn't require on-chain payment for Sepolia Cross-chain ready: Same feeds work on Ethereum, Solana, Arbitrum for future expansion EVVM Nonce System (Ethereum Virtual Machine) The Gasless Withdrawal Vision Problem: Employees withdrawing weekly pay 52 gas fees/year. At $5/tx, that's $260 in fees.

Solution: Pre-Signed Nonces Built into the smart contract but not yet activated in UI:

January 1st: Employee signs nonces 1-52 in one transaction Every week: Backend triggers withdrawal using next nonce (no employee signature needed) Security: Each nonce can only be used once, stored in mapping(uint256 => bool) usedNonces The Data Structure: struct NonceState { uint256 currentNonce; // Which number we're on mapping(uint256 => bool) usedNonces; // Prevents replay attacks mapping(uint256 => bytes32) preSignedHashes; // Authorized tx hashes }

How StreamPay Was Built Architecture Overview StreamPay is a full-stack Web3 application combining Solidity smart contracts with a Next.js frontend, orchestrating real-time wage calculations on-chain with live price feeds and stablecoin payments.

Smart Contract Layer (Solidity) Core Innovation: Per-Second Math The trickiest part was calculating wages per second without overflow errors or precision loss. We convert annual salaries to per-second rates:

In Solidity (6 decimals): 50000000000 ÷ 31536000 = 1585 units/second

Time-Based Accrual System Every clock-in stores block.timestamp. When withdrawing, we calculate:

This runs on-chain, making wage accrual trustless and verifiable.

The 70/30 Split Hack When withdrawing $100 (which is 70% of total), we reverse-engineer the full amount:

Available: $100 (user gets this) Total earned: $100 ÷ 0.7 = $142.86 Escrow: $142.86 - $100 = $42.86 (held for manager approval) This math ensures precise splitting without rounding errors in Solidity's integer arithmetic.

PYUSD Integration (PayPal USD) 6-Decimal Challenge Most ERC-20 tokens use 18 decimals (like ETH). PYUSD uses 6 decimals, which broke everything initially.

The Fix: Every transaction uses parseUnits(amount, 6) instead of the standard parseUnits(amount, 18):

Wrong: 50 PYUSD = 50000000000000000000 units ❌ Right: 50 PYUSD = 50000000 units ✅ We built a custom hook useContract.ts that wraps all PYUSD operations with correct decimal handling:

Why PYUSD Benefits Us:

Stability: Workers don't lose purchasing power to crypto volatility Compliance: PayPal's regulatory backing makes this enterprise-ready Familiarity: "PayPal USD" is easier to explain to non-crypto users than "DAI" or "USDC" Pyth Network Integration (Oracle Price Feeds) The Multi-Currency Problem Filipino workers earning PYUSD need to see their balance in Philippine Pesos (PHP) to understand purchasing power.

Solution: Cross-Rate Calculation Pyth doesn't have a direct PYUSD/PHP feed, so we chain two feeds:

Fetch PYUSD/USD price (should be ~$1.00) Fetch USD/PHP price (e.g., ₱56.50) Multiply: PYUSD → PHP = PYUSD/USD × USD/PHP Implementation in pyth.ts:

The Hacky Part: 5-Second Polling Pyth feeds update sub-second, but querying every second hammered the API. We built React hooks with 5-second intervals:

This gives "live" feel without rate-limiting issues.

Why Pyth Benefits Us:

Real-time accuracy: Prices update within seconds, not minutes (unlike Chainlink's longer intervals) Free testnet access: Hermes API doesn't require on-chain payment for Sepolia Cross-chain ready: Same feeds work on Ethereum, Solana, Arbitrum for future expansion EVVM Nonce System (Ethereum Virtual Machine) The Gasless Withdrawal Vision Problem: Employees withdrawing weekly pay 52 gas fees/year. At $5/tx, that's $260 in fees.

Solution: Pre-Signed Nonces Built into the smart contract but not yet activated in UI:

January 1st: Employee signs nonces 1-52 in one transaction Every week: Backend triggers withdrawal using next nonce (no employee signature needed) Security: Each nonce can only be used once, stored in mapping(uint256 => bool) usedNonces The Data Structure:

How It Works:

Why We Built But Didn't Activate:

Contract infrastructure is ready (future-proof) Requires backend relayer service (out of hackathon scope) Current UI uses standard withdraw() function (requires MetaMask each time) Phase 2 will add relayer + activate nonce system Why EVVM Benefits Us:

Gas savings: 52 withdrawals → 1 pre-sign transaction UX improvement: No MetaMask popup every payday Security: Nonce tracking prevents double-spending even if signature leaks Frontend Architecture (Next.js) Tech Stack:

Next.js 14 (App Router) TypeScript (type safety for Web3 interactions) Wagmi + RainbowKit (wallet connection) Ethers.js v6 (blockchain reads/writes) TailwindCSS (glassmorphism UI) The Real-Time Streaming Hack Challenge: Show balance increasing every second while employee is clocked in. useEffect(() => { if (isClockedIn) { const interval = setInterval(() => { fetchEmployeeBalances() // Hits smart contract }, 2000) // 2 seconds return () => clearInterval(interval) } }, [isClockedIn]) Deployment & Verification Smart Contract:

Deployed to Sepolia: 0xc63d7425d5f3960EdAB8A28AdF2468c89d3BBE3c Verified on Etherscan (public source code) PYUSD token: 0xCaC524BcA292aaade2DF8A05cC58F0a65B1B3bB9 Frontend:

Deployed on Vercel (auto-deploy from GitHub) Environment variables for contract addresses Production build with TypeScript strict mode What We'd Improve With More Time Activate EVVM nonces - Build relayer service for gasless withdrawals Mobile app - React Native with WalletConnect Biometric clock-in - GPS + face recognition to prevent fraud Multi-currency support - Add EUR, INR, BRL price feeds L2 deployment - Move to Arbitrum/Optimism for cheaper gas