Skip to content

README.md

Latest commit

 

History

History
117 lines (85 loc) · 3.91 KB

README.md

File metadata and controls

117 lines (85 loc) · 3.91 KB
Raw

💸 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.”