✅ All contracts successfully deployed and verified!

Purpose: Trustless payment escrow system with platform fees

• Create payments with recipient, amount, and token
• Accept payments to release funds to recipient
• Cancel payments to refund sender
• Platform fee: 1% (100 basis points) on all transactions
• Fee recipient: Configurable owner address
• Gas optimized: 63% reduction from original design

Purpose: Platform utility and governance token

• Total Supply: 1,000,000 ENGI tokens
• Standard ERC20 with transfer, approve, allowance
• Initial distribution to deployer address
• Future use: Staking rewards, governance, fee discounts

Purpose: Facilitates cross-chain atomic swaps

• Initiate swaps between BTC and STRK
• Track swap state (Pending, Confirmed, Completed, Failed, Refunded)
• Platform fee: 1% on swap amounts
• Swap timeout: 24 hours (86400 seconds)
• Refund mechanism for failed/expired swaps

EngiPay is a comprehensive DeFi super-app that bridges traditional finance with decentralized finance, making crypto accessible to everyone. We combine:

✅ Instant Payments - Send crypto as easily as sending a text
✅ Cross-Chain Swaps - Seamless BTC ↔ STRK atomic swaps via Atomiq
✅ Privacy Payments - ElGamal encrypted transactions via Tongo SDK
✅ Escrow Protection - Trustless payment protection with accept/reject
✅ DeFi Integration - Lending, staking, and yield farming in one place
✅ Multi-Chain Support - Starknet, Bitcoin, and more coming soon

"EngiPay is the Venmo of Web3 - but better. We make DeFi as simple as traditional banking while adding privacy, cross-chain capabilities, and earning opportunities. Send payments, swap Bitcoin, earn yield, all in one beautiful app."

┌─────────────────────────────────────────────────────────────────────┐
│                         ENGIPAY PLATFORM                             │
└─────────────────────────────────────────────────────────────────────┘
                                    │
        ┌───────────────────────────┼───────────────────────────┐
        │                           │                           │
        ▼                           ▼                           ▼
┌──────────────┐          ┌──────────────┐          ┌──────────────┐
│   FRONTEND   │          │   BACKEND    │          │  BLOCKCHAIN  │
│   Next.js    │◄────────►│   Node.js    │◄────────►│   Starknet   │
│   React 18   │   REST   │   Express    │   RPC    │   Sepolia    │
│  TypeScript  │   API    │  PostgreSQL  │          │              │
└──────────────┘          └──────────────┘          └──────────────┘
        │                           │                           │
        │                           │                           │
        ▼                           ▼                           ▼
┌──────────────┐          ┌──────────────┐          ┌──────────────┐
│   WALLETS    │          │   SERVICES   │          │ SMART        │
│              │          │              │          │ CONTRACTS    │
│ • ArgentX    │          │ • Atomiq SDK │          │              │
│ • Braavos    │          │ • Tongo SDK  │          │ • EscrowTiny │
│ • Xverse(BTC)│          │ • ChipiPay   │          │ • EngiToken  │
│              │          │ • Vesu API   │          │ • AtomiqAdapt│
└──────────────┘          └──────────────┘          └──────────────┘
        │                           │                           │
        └───────────────────────────┴───────────────────────────┘
                                    │
                                    ▼
                        ┌──────────────────────┐
                        │   EXTERNAL SERVICES  │
                        │                      │
                        │ • Atomiq Protocol    │
                        │ • Tongo Privacy      │
                        │ • Vesu Lending       │
                        │ • Trove Staking      │
                        │ • Price Oracles      │
                        └──────────────────────┘

User Initiates BTC → STRK Swap
         │
         ▼
Frontend validates input
         │
         ▼
Backend calls Atomiq SDK
         │
         ▼
Atomiq returns quote + Bitcoin address
         │
         ▼
User sends BTC to address
         │
         ▼
Atomiq detects BTC transaction
         │
         ▼
AtomiqAdapter contract called
         │
         ▼
STRK released to user's wallet
         │
         ▼
Transaction recorded in database
         │
         ▼
Frontend shows success + explorer link

Send crypto as easily as sending a text message

• ✅ Support for STRK, ETH, USDC
• ✅ Real-time balance updates
• ✅ Transaction history with filters
• ✅ QR code generation for easy receiving
• ✅ Payment requests with expiry
• ✅ Merchant payment links

How it works:

1. Connect your Starknet wallet (ArgentX/Braavos)
2. Enter recipient address and amount
3. Sign transaction in wallet
4. Payment confirmed on blockchain in seconds

Seamlessly swap Bitcoin ↔ Starknet tokens

• ✅ BTC → STRK atomic swaps
• ✅ STRK → BTC atomic swaps
• ✅ Real-time pricing from Atomiq
• ✅ No wrapped tokens - real Bitcoin
• ✅ Automatic settlement
• ✅ Claim/refund mechanisms
• ✅ Complete swap history

How it works:

1. Select swap direction (BTC→STRK or STRK→BTC)
2. Enter amount and get instant quote
3. For BTC→STRK: Send BTC to provided address
4. For STRK→BTC: Approve and execute on Starknet
5. Atomiq handles the atomic swap
6. Receive funds automatically

Powered by: Atomiq Protocol

Send payments with encrypted amounts using ElGamal encryption

• ✅ Shield tokens (convert public → private)
• ✅ Private transfers with hidden amounts
• ✅ Unshield tokens (convert private → public)
• ✅ Generate viewing keys for selective disclosure
• ✅ Encrypted balance viewing
• ✅ Support for ETH, STRK, USDC

How it works:

1. Shield your tokens to make them private
2. Send private payments - amounts are encrypted
3. Recipients see encrypted balances
4. Use viewing keys to decrypt when needed
5. Unshield to convert back to public tokens

Powered by: Tongo SDK

Trustless payment protection with smart contracts

• ✅ Create payment requests with expiry
• ✅ Recipients can accept or reject
• ✅ Automatic refunds on rejection/expiry
• ✅ Platform fee: 1% on completed payments
• ✅ Generate payment links and QR codes
• ✅ Track escrow status in real-time

How it works:

1. Sender creates escrow payment request
2. Funds locked in EscrowTiny contract
3. Recipient reviews and accepts/rejects
4. On accept: Funds released (minus 1% fee)
5. On reject/expiry: Automatic refund to sender

Smart Contract: EscrowTiny on Sepolia

Access multiple DeFi protocols in one place

• Supply assets and earn interest
• Borrow against collateral
• Real-time APY calculations
• Multiple asset pools

• Stake STRK tokens
• Earn staking rewards
• Flexible lock periods
• Auto-compounding options

• Farm across multiple pools
• Maximize returns
• Auto-harvest rewards
• Portfolio tracking

How it works:

1. Navigate to DeFi section
2. Choose protocol (Vesu/Trove/Farming)
3. Connect wallet and approve tokens
4. Supply, stake, or farm
5. Track earnings in dashboard

Scan and pay instantly

• ✅ Camera-based QR scanning
• ✅ Parse payment requests
• ✅ Pre-fill payment forms
• ✅ One-tap payment confirmation

Complete transaction management

• ✅ View all transactions
• ✅ Filter by type (payment, swap, escrow, private)
• ✅ Filter by status (pending, completed, failed)
• ✅ Search by address or hash
• ✅ Date range filtering
• ✅ Export to CSV
• ✅ Real-time updates

1. Escrow Fees (1%)

   • Applied to all completed escrow payments
   • Collected by EscrowTiny contract
   • Sent to fee_recipient address

2. Swap Fees (1%)

   • Applied to cross-chain swap amounts
   • Collected by AtomiqAdapter contract
   • Covers operational costs

3. Future Revenue

   • Premium features (coming soon)
   • Enterprise API access
   • White-label solutions
   • ENGI token staking rewards

User Payment: 100 STRK
├─ Platform Fee (1%): 1 STRK → EngiPay Treasury
└─ Net Amount (99%): 99 STRK → Recipient

• Real implementation with Tongo SDK and ElGamal encryption
• Working privacy features - shield, transfer, unshield
• Selective disclosure via viewing keys
• Most competitors: No privacy or just marketing claims

• Atomic swaps with real Bitcoin (not wrapped)
• Atomiq Protocol integration for trustless swaps
• No bridge risks - direct chain-to-chain
• Most competitors: Wrapped tokens or centralized bridges

• Payments + Swaps + DeFi in single app
• Unified experience - no jumping between dApps
• One wallet for everything
• Most competitors: Single-purpose apps

• 32 working API endpoints
• Zero mock data in production
• Real blockchain integration
• Professional UI/UX
• Most competitors: Demo-quality or incomplete

• 1% platform fee vs 2-5% competitors
• Free privacy transactions
• Free P2P payments
• Transparent pricing

• Low gas fees compared to Ethereum
• Fast finality (seconds, not minutes)
• Native ZK technology for future privacy
• Scalable infrastructure

• Banking app quality interface
• Smooth animations and transitions
• Mobile responsive design
• Intuitive privacy controls
• Real-time updates

• Smart contract escrow protection
• Non-custodial - you control your keys
• Auditable transactions
• Open source code

🎯 5-Minute Demo Path:

1. Visit Live Demo → [Your URL]
2. Connect Wallet → ArgentX or Braavos (Sepolia testnet)
3. Try Cross-Chain Swap → BTC ↔ STRK (our killer feature!)
4. Send Payment → Real blockchain transaction
5. Check Contracts → View on Starkscan (links above)

Node.js 18+
PostgreSQL 14+
Git

# 1. Clone repository
git clone <your-repo-url>
cd engipay

# 2. Install dependencies
npm install
cd backend && npm install && cd ..

# 3. Setup environment variables
cp .env.example .env.local
cp backend/.env.example backend/.env

# Edit .env files with your configuration

# 4. Setup database
cd backend
npm run db:setup

# 5. Start development servers
# Terminal 1 - Backend
cd backend
npm run dev

# Terminal 2 - Frontend
npm run dev

• Frontend: http://localhost:3000
• Backend API: http://localhost:3001
• API Docs: http://localhost:3001/api-docs

POST   /api/payments/v2/send              # Send standard payment
POST   /api/payments/v2/private-send      # Send private payment (Tongo)
POST   /api/payments/v2/shield            # Shield tokens (public → private)
POST   /api/payments/v2/unshield          # Unshield tokens (private → public)
POST   /api/payments/v2/execute           # Execute signed transaction
POST   /api/payments/v2/request           # Create payment request
GET    /api/payments/v2/balance           # Get wallet balance
GET    /api/payments/v2/encrypted-balance # Get encrypted balance (Tongo)
POST   /api/payments/v2/generate-key      # Generate viewing key
GET    /api/payments/v2/supported-tokens  # List supported tokens

POST   /api/escrow/create                 # Create escrow request
POST   /api/escrow/accept                 # Accept payment
POST   /api/escrow/reject                 # Reject payment
POST   /api/escrow/cancel                 # Cancel request
POST   /api/escrow/execute                # Execute payment
GET    /api/escrow/requests               # Get all requests
GET    /api/escrow/requests/pending       # Get pending requests
GET    /api/escrow/request/:id            # Get specific request

POST   /api/swap/atomiq/quote             # Get swap quote
POST   /api/swap/atomiq/initiate          # Initiate swap
POST   /api/swap/atomiq/:id/execute       # Execute swap
GET    /api/swap/atomiq/status/:id        # Get swap status
GET    /api/swap/atomiq/limits            # Get swap limits
GET    /api/swap/atomiq/history           # Get swap history
GET    /api/swap/atomiq/claimable         # Get claimable swaps
GET    /api/swap/atomiq/refundable        # Get refundable swaps
POST   /api/swap/atomiq/:id/claim         # Claim completed swap
POST   /api/swap/atomiq/:id/refund        # Refund failed swap

GET    /api/defi/vesu/pools               # Get Vesu lending pools
POST   /api/defi/vesu/supply              # Supply to Vesu
POST   /api/defi/vesu/borrow              # Borrow from Vesu
GET    /api/defi/staking/pools            # Get staking pools

📚 Full API Documentation: API_DOCS.md

• Framework: Next.js 14 (App Router)
• Language: TypeScript
• Styling: Tailwind CSS
• UI Components: Radix UI (40+ components)
• State Management: React Context + Hooks
• Blockchain: StarkNet.js, Sats-connect (Bitcoin)
• Privacy: Tongo SDK
• Animations: Framer Motion

• Runtime: Node.js 18+
• Framework: Express.js
• Database: PostgreSQL 14+ with Sequelize ORM
• Authentication: JWT
• APIs: RESTful
• Integrations: Atomiq SDK, Tongo SDK, ChipiPay SDK

• Primary Chain: Starknet (Sepolia Testnet)
• Cross-Chain: Bitcoin (via Atomiq)
• Smart Contracts: Cairo 2.0
• Wallets: ArgentX, Braavos, Xverse

• Version Control: Git
• Package Manager: npm
• Environment: dotenv
• Testing: Jest, React Testing Library

engipay/
├── app/                              # Next.js App Router
│   ├── dashboard/                    # Main dashboard
│   ├── payments-swaps/               # Payments & swaps page
│   ├── defi/                         # DeFi features
│   ├── profile-page/                 # User profile
│   └── api/                          # API routes (if any)
│
├── components/                       # React components
│   ├── payments/                     # Payment components
│   │   ├── SendPayment.tsx           # Send payment form
│   │   ├── EscrowPayments.tsx        # Escrow system
│   │   ├── BtcSwap.tsx               # Cross-chain swaps
│   │   ├── SwapHistory.tsx           # Swap history
│   │   ├── QRScanner.tsx             # QR code scanner
│   │   └── TransactionHistory.tsx    # Transaction list
│   ├── dashboard/                    # Dashboard components
│   ├── defi/                         # DeFi components
│   └── ui/                           # UI primitives (40+)
│
├── backend/                          # Backend API
│   ├── routes/                       # API routes
│   │   ├── payments-v2.js            # Payment endpoints
│   │   ├── escrow.js                 # Escrow endpoints
│   │   └── swaps-atomiq.js           # Swap endpoints
│   ├── services/                     # Business logic
│   │   ├── atomiqService.js          # Atomiq integration
│   │   ├── escrowService.js          # Escrow logic
│   │   ├── blockchainService.js      # Blockchain interactions
│   │   └── paymentService.js         # Payment logic
│   ├── models/                       # Database models (25+)
│   ├── middleware/                   # Express middleware
│   └── server.js                     # Entry point
│
├── smart-contracts/                  # Smart contracts
│   ├── src/                          # Cairo source files
│   │   ├── EscrowTiny.cairo          # Escrow contract
│   │   ├── EngiTokenSimple.cairo     # Token contract
│   │   ├── AtomiqAdapterSimple.cairo # Swap adapter
│   │   ├── interfaces/               # Contract interfaces
│   │   └── libraries/                # Shared libraries
│   ├── scripts/                      # Deployment scripts
│   └── target/                       # Compiled contracts
│
├── contexts/                         # React contexts
│   ├── WalletContext.tsx             # Wallet management
│   └── ChipiPayContext.tsx           # ChipiPay integration
│
├── lib/                              # Utility functions
├── public/                           # Static assets
└── docs/                             # Documentation

• Total Lines of Code: 50,000+
• API Endpoints: 32
• React Components: 100+
• Smart Contracts: 3 (deployed)
• Database Tables: 25+
• Development Time: 5 days intensive
• Team Size: 1 (Full-stack + Smart Contracts)

• ✅ Zero mock data in production
• ✅ Real blockchain integration
• ✅ Production-ready code quality
• ✅ Comprehensive error handling
• ✅ Security best practices
• ✅ Mobile responsive design
• ✅ Real-time updates
• ✅ Multi-wallet support

• ✅ Core payment system
• ✅ Smart contract development
• ✅ Frontend UI/UX
• ✅ Backend API
• ✅ Database setup

• ✅ Tongo privacy integration
• ✅ Atomiq cross-chain swaps
• ✅ DeFi protocol integration
• ✅ Multi-wallet support
• ✅ Contract deployment

• 🚧 Advanced analytics
• 🚧 Mobile app (React Native)
• 🚧 Additional DeFi protocols
• 🚧 More token support
• 🚧 Fiat on/off ramps

• 📅 Mainnet deployment
• 📅 Security audits
• 📅 Marketing campaign
• 📅 Partnership integrations
• 📅 Community building

• ✅ Reentrancy protection
• ✅ Access control
• ✅ Input validation
• ✅ Safe math operations
• ✅ Event logging
• 📅 Professional audit (planned)

• ✅ JWT authentication
• ✅ Rate limiting
• ✅ Input sanitization
• ✅ CORS protection
• ✅ Environment variables
• ✅ Secure key storage

• Non-custodial architecture
• Client-side transaction signing
• Encrypted sensitive data
• Regular security updates
• Open source transparency

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

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

• HACKATHON_READY_FEATURES.md - Complete feature list
• COMPLETE_SYSTEM_DOCUMENTATION.md - Full system docs
• SMART_CONTRACTS_GUIDE.md - Contract details
• PRIVACY_FEATURES_GUIDE.md - Privacy implementation
• API_DOCS.md - API reference

• Starknet - L2 blockchain infrastructure
• Tongo - Privacy SDK with ElGamal encryption
• Atomiq - Cross-chain swap protocol
• Vesu - Lending protocol
• Trove - Staking protocol

• Next.js - React framework
• Tailwind CSS - CSS framework
• Radix UI - Component primitives
• StarkNet.js - Starknet library

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

• Team Lead & Product Manager: [Your Name]
• GitHub: [Your GitHub]
• Email: [email protected]
• Twitter: @EngiPay

• Discord: Join our community
• Telegram: Join discussion
• Documentation: docs.engipay.com