Quipay

Autonomous Payroll Infrastructure on Stellar

Features • Architecture • Quick Start • Documentation • Contributing

---

📖 Overview

Quipay is a decentralized payroll protocol enabling continuous salary streaming, automated treasury management, and AI-powered payroll operations on the Stellar blockchain. Built for the future of work, Quipay eliminates traditional payroll friction through programmable smart contracts and intelligent automation.

Why Quipay?

• 🌍 Global - Borderless payments in any Stellar asset
• ⚡ Real-Time - Workers access earnings continuously, not monthly
• 🤖 Autonomous - AI agents handle scheduling and optimization
• 🔒 Secure - Treasury solvency enforced on-chain
• 📊 Transparent - All transactions verifiable and auditable

---

✨ Features

For Employers

• Continuous Payment Streams - Set up recurring salaries that accrue per second
• Treasury Solvency Management - Automatic balance verification prevents overspending
• Multi-Token Support - Pay in XLM, USDC, or any Stellar asset
• AI Automation - Intelligent agents handle payroll scheduling and treasury optimization
• Compliance Ready - Built-in audit trails and payment verification

For Workers

• Instant Access - Withdraw earned salary anytime, no waiting for payday
• Real-Time Earnings - See your balance grow every second
• Flexible Withdrawals - Partial or full payouts on demand
• Multi-Stream Support - Manage multiple income sources in one place
• Payment History - Complete transaction transparency

---

🏗️ Architecture

Quipay uses a modular smart contract architecture for security, scalability, and maintainability:

Smart Contracts

Contract	Purpose	Status
PayrollStream	Continuous salary streaming & accrual calculation	🚧 In Development
TreasuryVault	Employer fund custody with liability accounting	✅ Base Complete
WorkforceRegistry	Worker profiles & payment preferences	📋 Planned
AutomationGateway	AI agent authorization & execution routing	📋 Planned

Technology Stack

┌─────────────────────────────────────────────┐
│           Frontend (Vite + React)           │
│   • Wallet Integration (Freighter)         │
│   • Real-time Earnings Display             │
│   • Dashboard & Analytics                  │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│      Smart Contracts (Soroban/Rust)        │
│   • PayrollStream                          │
│   • TreasuryVault                          │
│   • WorkforceRegistry                      │
│   • AutomationGateway                      │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│         Stellar Blockchain                  │
│   • Asset Transfers                        │
│   • Ledger State                           │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│       AI Treasury Agent (Node.js)           │
│   • Payroll Scheduling                     │
│   • Solvency Monitoring                    │
│   • Risk Detection                         │
└─────────────────────────────────────────────┘

---

🚀 Quick Start

Prerequisites

• Rust 1.79+ (Install)
• Node.js 22+ (Install)
• Stellar CLI (Install Guide)
• Scaffold Stellar CLI (Install)

Installation

# Clone the repository
git clone https://github.com/LFGBanditLabs/Quipay.git
cd Quipay

# Install dependencies
npm install

# Start development server
npm start

The development server will:

1. ✅ Compile Soroban smart contracts
2. ✅ Deploy to local Stellar sandbox
3. ✅ Generate TypeScript client bindings
4. ✅ Launch frontend at http://localhost:5173

Running Tests

# Test all contracts
cargo test

# Test specific contract
cd contracts/payroll_vault
cargo test

# Frontend tests
npm test

PR Preview Deployments (Frontend)

This repository includes an optional Frontend Preview Deploy GitHub Action that builds the Vite dApp and deploys each pull request to Cloudflare Pages using Soroban Testnet defaults.

To enable preview deployments:

1. Create a Cloudflare Pages project for the Quipay frontend (build command npm run build, output directory dist).
2. Add the following repository secrets in GitHub:
   • CLOUDFLARE_API_TOKEN – API token with “Cloudflare Pages — Edit” permission.
   • CLOUDFLARE_ACCOUNT_ID – your Cloudflare account ID.
   • CLOUDFLARE_PAGES_PROJECT – the Cloudflare Pages project name.
3. Open or update a pull request that touches the frontend. The Frontend Preview Deploy workflow will:
   • Build the dApp with PUBLIC_STELLAR_* env vars set to Testnet endpoints.
   • Deploy a per-PR preview to Cloudflare Pages.
   • Comment on the PR with the preview URL so reviewers can visually test the changes.

---

📁 Project Structure

Quipay/
├── contracts/              # Soroban smart contracts
│   ├── payroll_stream/    # Streaming payment logic
│   ├── payroll_vault/     # Treasury management
│   ├── workforce_registry/ # Worker profiles (planned)
│   └── automation_gateway/ # AI authorization (planned)
├── src/                   # React frontend application
│   ├── components/        # Reusable UI components
│   ├── pages/             # Application pages
│   ├── contracts/         # Generated contract clients
│   └── hooks/             # Custom React hooks
├── backend/               # Node.js AI agent (planned)
├── packages/              # Generated TypeScript bindings
├── docs/                  # Documentation
│   ├── PRD.md            # Product Requirements
│   └── design.md         # Technical design
└── environments.toml      # Network configurations

---

📚 Documentation

• Product Requirements (PRD) - Complete product specification
• DAO Treasury Setup Guide - Multisig configuration for DAOs and enterprise clients
• Implementation Plan - Technical architecture & roadmap
• Design Document - System design overview
• GitHub Issues - Development tasks & progress

---

💼 Use Cases

DAOs & Protocol Teams Transparent contributor compensation with automated scheduling and multi-sig control. See DAO Setup Guide →	Remote-First Companies Global payroll without intermediaries, supporting 100+ countries and multiple currencies
Web3 Startups Compliant contractor payments with built-in audit trails and flexible payment terms	Freelance Platforms Enable workers to access earnings instantly as they complete work milestones

---

🛠️ Development Status

Current Phase: MVP Development (Phase 1)

Completed ✅

• Project initialization with Scaffold Stellar
• Basic PayrollVault contract (deposit/payout)
• Comprehensive PRD and technical documentation
• 40+ GitHub issues with detailed specifications
• Development environment setup

In Progress 🚧

• PayrollStream contract (streaming logic)
• Treasury liability tracking
• Frontend wallet integration
• Real-time earnings calculator

Planned 📋

• AI automation gateway
• Worker registry
• Analytics dashboard
• Testnet deployment
• Security audit

Track our progress: View Task Board

---

🔐 Security

Security is paramount for payroll infrastructure. Quipay implements:

• ✅ Solvency Invariants - Treasury balance ≥ liabilities enforced on-chain
• ✅ Authorization Checks - Strict access control on all fund movements
• ✅ Multisig Support - Treasury Vault supports multi-signature Stellar accounts for decentralized governance
• ✅ Double-Withdrawal Prevention - Safe accounting prevents duplicate payouts
• ✅ Timestamp Validation - Protection against manipulation attacks
• ✅ Formal Auditing - Pre-mainnet security review (planned Phase 4)

Found a vulnerability? See our Security Policy

---

🤝 Contributing

We welcome contributions! Quipay is building the future of payroll infrastructure.

Ways to Contribute

• 🐛 Report Bugs - Open an issue
• 💡 Suggest Features - Share your ideas
• 📝 Improve Documentation - Help others understand Quipay
• 💻 Submit PRs - Check our good first issues

See our Contributing Guide and Code of Conduct

---

📊 Roadmap

Phase	Milestone	Timeline	Status
Phase 1	Core Protocol (Streaming + Treasury)	Q1 2026	🚧 In Progress
Phase 2	AI Automation Integration	Q2 2026	📋 Planned
Phase 3	Compliance & Reporting	Q3 2026	📋 Planned
Phase 4	Enterprise Features	Q4 2026	📋 Planned

---

📜 License

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

---

🔗 Links

---

Built with ❤️ on Stellar

Empowering the future of work, one stream at a time

⭐ Star us on GitHub • 🐦 Follow updates • 💬 Join our community