💸 Jerico — Blockchain-Native Invoicing & Payments Platform

Instant, peer-to-peer invoice settlement with zero custody.

Built for freelancers, businesses, and global payments — powered by PYUSD and Ethereum smart contracts.

---

🚀 Executive Summary

Jerico is a mobile-first, blockchain-native invoicing and payment platform that enables instant invoice settlement using on-chain smart contracts and PYUSD.
Freelancers and businesses can create, share, and get paid directly — no middlemen, no custody, no delays.

🌟 Core Value Proposition

• ⚡ Instant settlement — no multi-day bank delays
• 💰 Ultra-low fees — direct token transfers
• 🔍 Transparent & auditable ledger
• 📱 Mobile-first UX — QR codes & deep links
• 🔐 Zero custody risk — funds move wallet-to-wallet

---

🧩 High-Level User Flows

A. Invoice Creation

1. Issuer fills invoice details (client, amount, due date, etc.)
2. Metadata uploaded to IPFS/Arweave (optional)
3. InvoiceFactory.createInvoice() is called on-chain
4. Returns invoiceId, payment link & QR code

B. Client Payment

1. Client scans QR / opens payment link
2. DApp fetches invoice & token details (PYUSD)
3. Payer approves (ERC20 approve or permit)
4. Executes payInvoice(invoiceId) → transfers directly from payer → issuer
5. Emits InvoicePaid event

C. Visibility & Notifications

• Indexer or The Graph monitors events
• WebSocket / Push notifications update UIs in real-time

---

⚙️ Smart Contract Architecture

Contracts

• InvoiceFactory — main registry & payment processor
• Emits: InvoiceCreated, InvoicePaid, InvoiceCanceled, InvoiceExpired
• Uses SafeERC20, ReentrancyGuard, Ownable

struct Invoice {
  address issuer;
  address payer;
  address token;
  uint96 amount;      // PYUSD (6 decimals)
  uint32 dueDate;
  uint32 createdAt;
  uint8 status;       // 0=Pending,1=Paid,2=Expired,3=Canceled
  bytes32 metadata;   // IPFS hash or metadata keccak256
}

🏗️ How It’s Made

⚛️ Frontend Stack

Built with a modern, type-safe, and lightning-fast Web3 frontend stack:

Layer	Technology
🧩 Framework	React 19 + TypeScript
⚡ Build Tool	Vite 7.x
🎨 Styling	TailwindCSS 4.x + Framer Motion
🌈 Web3 Stack	Wagmi 2.x, RainbowKit, Viem 2.x, TanStack Query

---

🧠 Custom Hooks

Reusable, composable hooks for interacting with contracts and blockchain data:

Hook	Purpose
useInvoiceContract()	Handles all write operations to the smart contract
useInvoiceDetails()	Reads and fetches invoice data from chain/IPFS
usePYUSDContract()	Manages token approvals & balance reads
usePaymentValidation()	Performs unified pre-checks for balance and allowance

---

✨ Technical Highlights

✅ Real-time polling — Payments every 5s, balances every 10s
✅ Smooth mobile animations — Responsive, PWA-ready UX
✅ QR code payments — Instant wallet scan & pay
✅ BigInt-safe PYUSD handling — Precise 6-decimal token math
✅ Fully typed — End-to-end TypeScript safety

---

🧠 Hackathon Highlights

🏁 Delivered a full-stack Web3 invoicing platform within hackathon constraints:

✅ Achievements	Description
🔄 Real-time state sync	Live updates between blockchain & UI
💸 Zero-custody settlement	Direct PYUSD transfers wallet-to-wallet
🧩 Type safety	100% TypeScript coverage
⛽ Gas optimization	Struct packing, minimal writes, and efficient events
🎨 Clean UX	Wallet connect, QR payments, real-time status updates

---

“Jerico bridges design, crypto, and finance — with speed, transparency, and zero custody.”