PayChain 💰

🏆 ETH Mexico 2025 Hackathon Project

Web3 payment platform connecting ENS identities with Mexican fiscal invoicing (CFDI)

Contract deployed on Scroll Sepolia: https://sepolia.scrollscan.com/address/0x60814008211E98dbc88E08266FB220F41F1b850E#code

PayChain enables businesses and freelancers in Mexico to receive cryptocurrency payments using memorable ENS names while automatically generating legally valid tax receipts (CFDI 4.0).

🎯 Key Features

• 🌐 ENS Integration: Accept payments at yourcompany.eth instead of 0x742d35...
• ⚡ Scroll L2: Fast (<5s) and cheap (<$0.50) transactions
• 📄 Auto-Invoicing: CFDI 4.0 compliant invoices via Facturapi
• 📊 Provider Dashboard: View payments and download invoices
• 📧 Email Notifications: Automatic receipt delivery
• 💱 Multi-Currency: Support for ETH, USDC, USDT with automatic MXN conversion

🏗️ Architecture

┌─────────────────┐
│   Next.js UI    │  Frontend (Vercel)
│   + wagmi/viem  │
└────────┬────────┘
         │ HTTPS
         ▼
┌─────────────────┐       ┌──────────────┐
│  Express API    │◄─────►│ PostgreSQL   │
│  + TypeScript   │       └──────────────┘
└────────┬────────┘       ┌──────────────┐
         │                │    Redis     │
         │                │  (Job Queue) │
         │                └──────────────┘
         ├──► Scroll L2 (Events)
         ├──► Facturapi (Invoices)
         ├──► CoinGecko (Exchange Rates)
         └──► Resend (Emails)

🚀 Quick Start

Prerequisites

• Node.js 20+
• PostgreSQL 15+
• Redis 7+
• Foundry (for smart contracts)
• MetaMask or compatible Web3 wallet

Installation

1. Clone the repository

git clone https://github.com/yourusername/paychain.git
cd paychain

2. Install dependencies

# Smart contracts
cd contracts && forge install && cd ..

# Backend
cd backend && npm install && cd ..

# Frontend
cd frontend && npm install && cd ..

3. Set up environment variables

# Copy example files
cp .env.example .env
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env.local

# Edit each .env file with your actual API keys and configuration

4. Set up the database

# Create database
createdb paychain

# Run migrations
psql paychain < backend/database/schema.sql

Development

Run these commands in separate terminals:

# Terminal 1: Start Redis
redis-server

# Terminal 2: Start Backend API
cd backend && npm run dev

# Terminal 3: Start Background Worker
cd backend && npm run worker

# Terminal 4: Start Frontend
cd frontend && npm run dev

Visit http://localhost:3000 to see the application.

📚 Project Structure

paychain/
├── contracts/              # Solidity smart contracts
│   ├── src/
│   │   └── PayChain.sol   # Main payment contract
│   ├── test/              # Contract tests
│   └── script/            # Deployment scripts
│
├── backend/               # Express.js API
│   ├── src/
│   │   ├── routes/       # API endpoints
│   │   ├── services/     # Business logic
│   │   ├── repositories/ # Database access
│   │   └── workers/      # Background jobs
│   └── database/
│       └── schema.sql    # Database schema
│
├── frontend/             # Next.js application
│   ├── app/             # App router pages
│   ├── components/      # React components
│   ├── lib/            # Utilities
│   └── hooks/          # Custom React hooks
│
└── docs/               # Additional documentation

🧪 Testing

Smart Contracts

cd contracts
forge test -vv

Backend

cd backend
npm test

Frontend

cd frontend
npm test

🚢 Deployment

1. Deploy Smart Contract

cd contracts

# Deploy to Scroll Sepolia
forge script script/Deploy.s.sol \
  --rpc-url $SCROLL_RPC_URL \
  --broadcast \
  --verify

# Update CONTRACT_ADDRESS in .env files

2. Deploy Backend (Railway)

cd backend
railway login
railway init
railway up

3. Deploy Frontend (Vercel)

cd frontend
vercel --prod

🔑 Environment Variables

Required API Keys

1. Facturapi (Mexican invoice generation)

   • Sign up at dashboard.facturapi.io
   • Get your API key and Organization ID

2. Resend (Email service)

   • Sign up at resend.com
   • Get your API key

3. WalletConnect (Optional, for wallet connections)

   • Sign up at cloud.walletconnect.com
   • Get your Project ID

4. CoinGecko (Optional, for exchange rates)

   • Free tier available at coingecko.com

See .env.example files for complete configuration details.

🛠️ Tech Stack

Layer	Technology
Frontend	Next.js 14, TypeScript, Tailwind CSS, shadcn/ui
Smart Contracts	Solidity 0.8.20, Foundry, OpenZeppelin
Backend	Node.js, Express, TypeScript
Database	PostgreSQL, Kysely ORM
Blockchain	Scroll Sepolia L2, ENS
Web3	wagmi, viem, ethers.js
Invoicing	Facturapi API (CFDI 4.0)
Email	Resend
Job Queue	BullMQ + Redis

📖 Documentation

• Architecture Guide - System design and data flow
• Deployment Guide - Production deployment
• Local Setup - Development environment setup
• Contributing - Contribution guidelines
• API Documentation - Backend API reference

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

🔒 Security

• Never commit .env files
• Keep private keys secure
• Use environment variables for all sensitive data
• Report security vulnerabilities to security@paychain.app

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👥 Team

Built with ❤️ by the PayChain Team for ETH Mexico 2025

🙏 Acknowledgments

• ENS - Ethereum Name Service
• Scroll - Layer 2 scaling solution
• Facturapi - Mexican invoice generation
• OpenZeppelin - Smart contract libraries

📞 Support

• 📧 Email: support@paychain.app
• 🐦 Twitter: @paychain
• 💬 Discord: Join our community

---

Made with ❤️ using ENS, Scroll, and Facturapi