DECENTRALIZED HOURLY PAYROLL ON XAHAU
DOCUMENTATION • FAQ • QUICKSTART • ARCHITECTURE • SECURITY
IF YOU FIND XAH PAYROLL USEFUL, PLEASE STAR THE REPOSITORY TO HELP OTHERS DISCOVER IT!
XAH PAYROLL IS AN OPEN SOURCE DECENTRALIZED PAYROLL SYSTEM BUILT ON XAHAU (AN XRPL SIDECHAIN).
- Website: https://xahpayroll.xyz or https://xahpayroll.netlify.app
XAHAU CONTEST JUDGES: FOR QUICK TESTING, PLEASE SEE JUDGES.md
HOW IT WORKS: NGOS/EMPLOYERS CREATE PAYMENT CHANNELS WITH ESCROW FUNDS. WORKERS CLOCK IN/OUT TO TRACK HOURS. EARNINGS ACCUMULATE OFF-CHAIN IN THE DATABASE. WORKERS OR NGOS REQUEST CHANNEL CLOSURE. NGOS APPROVE REQUESTS AND EXECUTE PAYMENTCHANNELCLAIM TRANSACTION. WORKERS RECEIVE ALL ACCUMULATED EARNINGS IN A SINGLE ON-CHAIN PAYMENT. SETTLEDELAY PROTECTS WORKERS DURING CLOSURE TRANSITION.
WHO IT'S FOR: NGOS, EMPLOYERS, AND WORKERS (USING XRPL) WHO NEED TRANSPARENT, DECENTRALIZED WAGE TRACKING WITH MINIMAL TRANSACTION FEES OR THIRD PARTY RISKS.
- ⏱️ HOURLY WAGE TRACKING: AUTOMATIC CALCULATION OF WORKER EARNINGS WITH CLOCK IN/OUT TRACKING
- 💰 PAYMENT CHANNELS: SECURE XRPL PAYMENT CHANNELS WITH ON-CHAIN ESCROW PROTECTION
- 🎯 SINGLE TRANSACTION SETTLEMENT: ALL ACCUMULATED EARNINGS PAID IN ONE TRANSACTION WHEN CHANNEL CLOSES
- 🏢 MULTI-ORGANIZATION SUPPORT: WORKERS CAN WORK FOR MULTIPLE NGOS WITH SEPARATE PAYMENT CHANNELS
- 📱 XAMAN WALLET INTEGRATION: MOBILE-FIRST AUTHENTICATION WITH QR CODE SCANNING (DESKTOP) AND DEEP LINKING (MOBILE/DESKTOP) FOR SEAMLESS WALLET CONNECTIVITY
- 📊 REAL-TIME MONITORING: LIVE TRACKING OF WORK HOURS, ACCUMULATED BALANCE, AND ESCROW STATUS
- 📄 DATA EXPORT (PDF): WORKERS AND NGOS CAN EXPORT COMPLETE PAYMENT HISTORY, WORK SESSIONS, AND CHANNEL DETAILS AS PDF REPORTS FOR RECORD-KEEPING
# CLONE REPOSITORY
git clone https://github.com/Ghostrayu/xahpayroll.git
cd xahpayroll
# INSTALL ALL DEPENDENCIES (ROOT, FRONTEND, BACKEND)
npm run install:all
# CONFIGURE ENVIRONMENT VARIABLES
cp frontend/.env.example frontend/.env
cp backend/.env.example backend/.env
# EDIT .env FILES WITH YOUR CONFIGURATION
# INITIALIZE DATABASE
cd backend && npm run init-db
# START DEVELOPMENT SERVERS (BACKEND :3001, FRONTEND :3000)
npm run devDETAILED SETUP: SEE QUICKSTART.md FOR COMPLETE SETUP INSTRUCTIONS INCLUDING DATABASE CONFIGURATION, NETWORK SWITCHING, AND XAMAN API SETUP.
FRONTEND
- REACT 18 + TYPESCRIPT + VITE
- TAILWINDCSS FOR STYLING
- REACT ROUTER V6 FOR NAVIGATION
- CONTEXT API FOR STATE MANAGEMENT
BACKEND
- NODE.JS + EXPRESS
- POSTGRESQL 14+ DATABASE
- XRPL SDK FOR LEDGER OPERATIONS
- JWT AUTHENTICATION
BLOCKCHAIN
- XAHAU (XRPL SIDECHAIN) INTEGRATION
- XRPL PAYMENT CHANNELS FOR ESCROW
- XAMAN WALLET (PRODUCTION)
- TESTNET AND MAINNET SUPPORT
- FAQ.md - FREQUENTLY ASKED QUESTIONS, USE CASES, AND KNOWN LIMITATIONS
- ARCHITECTURE.md - SYSTEM DESIGN, PAYMENT FLOW, DATABASE SCHEMA (500+ LINES)
- QUICKSTART.md - DETAILED SETUP GUIDE AND CONFIGURATION
- DATABASE_SETUP.md - DATABASE CONFIGURATION AND MIGRATION
- NETWORK_CONFIG.md - TESTNET/MAINNET SWITCHING GUIDE
- WALLET_INTEGRATION.md - XAMAN WALLET INTEGRATION DETAILS
- NETLIFY_DEPLOYMENT.md - NETLIFY FRONTEND DEPLOYMENT (COMPLETE GUIDE)
- SUPABASE_RENDER_DEPLOYMENT.md - RENDER BACKEND DEPLOYMENT WITH SUPABASE
- EVERNODE.md - DECENTRALIZED HOSTING ON EVERNODE (MINIMALISTIC CHECKLIST)
- CONTRIBUTING.md - CONTRIBUTION GUIDELINES AND PULL REQUEST PROCESS
- SECURITY.md - SECURITY POLICY AND VULNERABILITY REPORTING
- CLAUDE.md - AI-ASSISTED DEVELOPMENT GUIDANCE
- CODE_OF_CONDUCT.md - COMMUNITY STANDARDS
- CHANGELOG.md - VERSION HISTORY AND RELEASE NOTES
- claudedocs/RELEASE_NOTES_v1.0.0.md - V1.0.0 RELEASE DETAILS
MANAGE WORKERS, CREATE PAYMENT CHANNELS, AND MONITOR ACTIVE CHANNELS
REAL-TIME TRACKING OF ESCROW, ACCUMULATED BALANCES, AND CHANNEL STATUS
.jpg)
SELECT WORKER, SET HOURLY RATE, AND CONFIGURE JOB DETAILS
.jpg)
CONFIGURE ESCROW AMOUNT AND PAYMENT CHANNEL SETTINGS
WORKERS TRACK HOURS, VIEW ACCUMULATED EARNINGS, AND MANAGE WORK SESSIONS
# START DEVELOPMENT (BOTH SERVERS)
npm run dev
# START SERVERS INDIVIDUALLY
npm run dev:backend # BACKEND ONLY (:3001)
npm run dev:frontend # FRONTEND ONLY (:3000)
# BUILD FRONTEND FOR PRODUCTION
npm run build
# RUN LINTER
npm run lint
# TEST DATABASE CONNECTION
cd backend && npm run test:db
# INITIALIZE DATABASE SCHEMA
cd backend && npm run init-db# DEPLOY TO PRODUCTION (NETLIFY)
npm run deploy
# DEPLOY PREVIEW
npm run deploy:previewDEPLOYMENT GUIDES:
- NETLIFY_DEPLOYMENT.md - COMPLETE NETLIFY FRONTEND DEPLOYMENT GUIDE
- SUPABASE_RENDER_DEPLOYMENT.md - RENDER BACKEND DEPLOYMENT WITH SUPABASE
- QUICKSTART.md - GENERAL PRODUCTION DEPLOYMENT INSTRUCTIONS
VULNERABILITY REPORTING: EMAIL admin@xahpayroll.xyz WITH DETAILS. DO NOT CREATE PUBLIC GITHUB ISSUES FOR SECURITY VULNERABILITIES.
SECURITY POLICY: SEE SECURITY.md FOR FULL SECURITY POLICY, BEST PRACTICES, AND RESPONSIBLE DISCLOSURE GUIDELINES.
KEY SECURITY FEATURES:
- NON-CUSTODIAL WALLET INTEGRATION (USERS CONTROL PRIVATE KEYS)
- PAYMENT CHANNEL ESCROW PROTECTION WITH SETTLEDELAY
- AUTOMATED DEPENDENCY VULNERABILITY SCANNING
- DATABASE ENCRYPTION AND SECURE SESSION MANAGEMENT
THIS PROJECT IS LICENSED UNDER THE MIT LICENSE - SEE LICENSE FILE FOR DETAILS.
DEPENDENCIES: ALL 368 PRODUCTION DEPENDENCIES USE PERMISSIVE LICENSES (MIT, ISC, BSD, APACHE-2.0). NO GPL OR COPYLEFT DEPENDENCIES.
WE WELCOME CONTRIBUTIONS! PLEASE SEE CONTRIBUTING.md FOR:
- PULL REQUEST PROCESS
- CODE STYLE GUIDELINES
- DEVELOPMENT WORKFLOW
- COMMIT MESSAGE CONVENTIONS
QUICK CONTRIBUTION STEPS:
- FORK THE REPOSITORY
- CREATE A FEATURE BRANCH (
git checkout -b feature/amazing-feature) - COMMIT YOUR CHANGES (
git commit -m 'ADD AMAZING FEATURE') - PUSH TO YOUR FORK (
git push origin feature/amazing-feature) - OPEN A PULL REQUEST
EMAIL: admin@xahpayroll.xyz
- GENERAL INQUIRIES
- SECURITY REPORTS
- TECHNICAL SUPPORT
GITHUB: https://github.com/Ghostrayu/xahpayroll/issues
- BUG REPORTS
- FEATURE REQUESTS
- TECHNICAL QUESTIONS
CODE OF CONDUCT: CODE_OF_CONDUCT.md
BUILT WITH ❤️ FOR THE XAHAU ECOSYSTEM
GOOD MONEY COLLECTIVE DONATION XRPL ADDRESS: r3pgsajrrWoFaTajo1wBEEvYzL1RAxjXMe
📖 FAQ • ⭐ STAR THIS PROJECT • 🐛 REPORT BUG • 💡 REQUEST FEATURE