Skip to content

WALLET_INTEGRATION.md

Latest commit

 

History

History
405 lines (313 loc) · 13 KB

WALLET_INTEGRATION.md

File metadata and controls

405 lines (313 loc) · 13 KB

WALLET INTEGRATION GUIDE

⚠️ IMPORTANT UPDATE (2025-12-30): XAH Payroll now exclusively supports Xaman wallet for production use. GemWallet and Crossmark support has been removed to streamline the user experience and focus on the most robust wallet integration.

SUPPORTED WALLETS

XAMAN (XUMM) - PRIMARY WALLET

STATUS: ✅ PRODUCTION SUPPORTED - RECOMMENDED FOR ALL USERS

  • TYPE: MOBILE & DESKTOP APP (IOS, ANDROID, WINDOWS, MAC, LINUX)
  • CONNECTION METHOD: QR CODE SCANNING + DEEP LINKING + PUSH NOTIFICATIONS
  • DOWNLOAD: https://xaman.app
  • FEATURES:
    • ✅ MOST SECURE OPTION (PRIVATE KEYS NEVER LEAVE DEVICE)
    • ✅ WORKS ON ANY DEVICE WITH CAMERA (QR CODE)
    • ✅ DEEP LINKING FOR SEAMLESS MOBILE EXPERIENCE
    • ✅ PUSH NOTIFICATIONS FOR TRANSACTION REQUESTS
    • ✅ NO BROWSER EXTENSION REQUIRED
    • ✅ BEST FOR MOBILE-FIRST AND DESKTOP WORKFLOWS
    • ✅ ENTERPRISE-GRADE SECURITY
    • ✅ OFFICIAL XRPL FOUNDATION SUPPORTED

HOW TO CONNECT:

MOBILE USERS (RECOMMENDED):

  1. INSTALL XAMAN APP ON YOUR MOBILE DEVICE (IOS/ANDROID)
  2. CREATE OR IMPORT YOUR WALLET IN XAMAN
  3. OPEN XAH PAYROLL IN YOUR MOBILE BROWSER
  4. CLICK "CONNECT WALLET" → SELECT "XAMAN (XUMM)"
  5. TAP "OPEN XAMAN APP" BUTTON (AUTOMATICALLY LAUNCHES XAMAN)
  6. APPROVE THE SIGN-IN REQUEST IN XAMAN
  7. ✅ CONNECTED - READY TO USE XAH PAYROLL

DESKTOP USERS:

  1. INSTALL XAMAN APP ON YOUR MOBILE DEVICE OR DESKTOP
  2. CREATE OR IMPORT YOUR WALLET IN XAMAN
  3. CLICK "CONNECT WALLET" ON XAH PAYROLL WEBSITE
  4. OPTION A (MOBILE APP): SCAN THE QR CODE WITH YOUR XAMAN MOBILE APP
  5. OPTION B (DESKTOP APP): CLICK "OPEN XAMAN IN NEW TAB" TO USE DEEP LINK
  6. APPROVE THE SIGN-IN REQUEST IN XAMAN
  7. ✅ CONNECTED - READY TO USE XAH PAYROLL

MANUAL MODE - TESTING ONLY

STATUS: ⚠️ DEVELOPMENT/TESTING ONLY - NOT RECOMMENDED FOR PRODUCTION

  • TYPE: DIRECT WALLET ADDRESS/SEED INPUT
  • CONNECTION METHOD: MANUAL ENTRY
  • USE CASE: DEVELOPMENT, TESTING, DEBUGGING
  • FEATURES:
    • ⚠️ REQUIRES MANUAL SEED/ADDRESS INPUT
    • ⚠️ LESS SECURE THAN XAMAN (SEED EXPOSURE RISK)
    • ⚠️ NO QR CODE OR MOBILE APP
    • ⚠️ MANUAL TRANSACTION SIGNING
    • ⚠️ INTENDED FOR DEVELOPERS ONLY

SECURITY WARNING: 🚨 NEVER USE MANUAL MODE WITH REAL FUNDS OR PRODUCTION MAINNET WALLETS 🚨 ONLY FOR TESTNET DEVELOPMENT AND DEBUGGING

WHY XAMAN-ONLY?

Decision Rationale (2025-12-30):

  1. SECURITY EXCELLENCE:

    • Xaman provides enterprise-grade key management
    • Hardware security module (HSM) support
    • Biometric authentication (Face ID, Touch ID, fingerprint)
    • No private key exposure

  2. OFFICIAL XRPL SUPPORT:

    • Maintained by XRPL Labs (official XRPL Foundation partner)
    • Regular security audits
    • Active development and updates
    • Direct access to XRPL core team support

  3. SUPERIOR USER EXPERIENCE:

    • QR code scanning for instant connection
    • Deep linking for seamless desktop experience
    • Push notifications for transaction requests
    • In-app transaction approval with detailed review
    • Multi-platform support (iOS, Android, Windows, Mac, Linux)

  4. REDUCED COMPLEXITY:

    • Single wallet integration = easier maintenance
    • Consistent user experience across all platforms
    • Faster bug fixes and feature development
    • Better testing coverage

  5. PRODUCTION RELIABILITY:

    • Proven track record with enterprise clients
    • 99.9%+ uptime SLA
    • Robust error handling
    • Comprehensive logging and debugging

TECHNICAL IMPLEMENTATION

FRONTEND INTEGRATION

THE FRONTEND USES A UNIFIED WALLETCONTEXT THAT HANDLES XAMAN WALLET OPERATIONS:

// Wallet providers supported
type WalletProvider = 'xaman' | 'manual'  // Manual for testing only

// Connection flow
const { connectWallet, disconnectWallet, walletAddress, balance } = useWallet()

// Connect to Xaman wallet (Production)
await connectWallet('xaman')  // QR code + deep linking flow

// Manual mode (Testing only - DO NOT USE IN PRODUCTION)
await connectWallet('manual')  // Direct seed/address input

WALLET DETECTION

THE APP AUTOMATICALLY HANDLES XAMAN WALLET AVAILABILITY:

  • XAMAN: ALWAYS AVAILABLE (USES QR CODE, NO INSTALLATION CHECK NEEDED)
  • QR CODE FALLBACK: WORKS ON ANY DEVICE EVEN WITHOUT XAMAN INSTALLED
  • DEEP LINKING: AUTOMATICALLY OPENS XAMAN APP ON MOBILE DEVICES
  • PUSH NOTIFICATIONS: SENDS TRANSACTION REQUESTS DIRECTLY TO XAMAN APP

DEPENDENCIES

{
  "xrpl": "^3.0.0",           // Core XRPL library
  "xumm-sdk": "^1.11.2"       // Xaman (XUMM) SDK for wallet integration
}

XAMAN WALLET FLOWS

SIGN-IN FLOW:

User clicks "Connect Wallet"
     ↓
Frontend: POST /api/xaman/create-signin
     ↓
Backend: Create Xaman sign-in payload
     ↓
Frontend: Display QR code + deep link
     ↓
User: Scan QR or click deep link
     ↓
Xaman App: User approves sign-in
     ↓
Frontend: Poll /api/xaman/payload/:uuid
     ↓
Backend: Verify signature from Xaman
     ↓
Frontend: Extract wallet address + create session
     ↓
✅ AUTHENTICATED

TRANSACTION SIGNING FLOW (Payment Channel Creation/Closure):

User initiates transaction (Create/Close Channel)
     ↓
Frontend: Prepare XRPL transaction
     ↓
Frontend: POST /api/xaman/create-payload
     ↓
Backend: Create Xaman payload with transaction
     ↓
Frontend: Display QR code + deep link
     ↓
User: Scan QR or click deep link
     ↓
Xaman App: Review transaction details
     ↓
Xaman App: User approves transaction
     ↓
Frontend: Poll /api/xaman/payload/:uuid
     ↓
Backend: Receive signed transaction
     ↓
Frontend: Submit to XRPL ledger
     ↓
✅ TRANSACTION CONFIRMED

USER PROFILE & AUTHENTICATION

WALLET-BASED AUTHENTICATION

  • NO PASSWORDS REQUIRED - AUTHENTICATION IS DONE VIA XAMAN WALLET SIGNATURES
  • WALLET ADDRESS = USER ID - EACH WALLET ADDRESS IS UNIQUE
  • PROFILE PERSISTENCE - USER PROFILES ARE STORED IN POSTGRESQL DATABASE
  • SIGNATURE VERIFICATION - XAMAN PROVIDES CRYPTOGRAPHIC PROOF OF OWNERSHIP

ACCOUNT TYPE RESTRICTIONS

⚠️ IMPORTANT: A WALLET ADDRESS CAN ONLY BE REGISTERED AS ONE ACCOUNT TYPE:

  • EMPLOYEE ACCOUNT: FOR WORKERS WHO LOG HOURS AND RECEIVE PAYMENTS
  • NGO/EMPLOYER ACCOUNT: FOR ORGANIZATIONS THAT MANAGE WORKERS AND FUND ESCROW

WHY THIS RESTRICTION?

  • PREVENTS CONFLICTS IN PAYMENT FLOWS
  • ENSURES CLEAR ROLE SEPARATION
  • MAINTAINS AUDIT TRAIL INTEGRITY
  • SIMPLIFIES DATABASE SCHEMA AND QUERIES

SOLUTION: USE DIFFERENT WALLET ADDRESSES FOR DIFFERENT ROLES.

PROFILE SETUP FLOW

FIRST-TIME USERS

  1. CONNECT WALLET → CLICK "CONNECT WITH XAMAN"
  2. SCAN QR CODE → USE XAMAN APP TO SCAN QR CODE (OR CLICK DEEP LINK ON MOBILE)
  3. APPROVE SIGN-IN → APPROVE IN XAMAN APP
  4. PROFILE CHECK → SYSTEM CHECKS IF PROFILE EXISTS
  5. PROFILE SETUP → IF NEW USER, COMPLETE PROFILE FORM:
    • DISPLAY NAME
    • ORGANIZATION NAME (FOR NGO/EMPLOYER ONLY)
    • EMAIL (OPTIONAL)
    • PHONE NUMBER (OPTIONAL)
    • ACCOUNT TYPE (EMPLOYEE OR NGO/EMPLOYER)
  6. TERMS OF SERVICE → ACCEPT TERMS
  7. DASHBOARD ACCESS → REDIRECTED TO APPROPRIATE DASHBOARD

RETURNING USERS

  1. CONNECT WALLET → CLICK "CONNECT WITH XAMAN"
  2. SCAN QR CODE → USE XAMAN APP TO SCAN QR CODE
  3. APPROVE SIGN-IN → APPROVE IN XAMAN APP
  4. AUTO-LOGIN → SYSTEM RETRIEVES EXISTING PROFILE
  5. DASHBOARD ACCESS → AUTOMATICALLY REDIRECTED TO DASHBOARD

SECURITY CONSIDERATIONS

PRIVATE KEY MANAGEMENT

  • NON-CUSTODIAL: XAH PAYROLL NEVER HAS ACCESS TO PRIVATE KEYS
  • XAMAN-CONTROLLED: ALL PRIVATE KEYS MANAGED BY XAMAN APP
  • NO KEY STORAGE: PRIVATE KEYS REMAIN IN XAMAN APP (NEVER ON SERVER OR BROWSER)
  • HARDWARE SECURITY: XAMAN SUPPORTS HARDWARE WALLETS AND HSM
  • BIOMETRIC PROTECTION: OPTIONAL FACE ID/TOUCH ID/FINGERPRINT LOCKS

TRANSACTION SIGNING

ALL TRANSACTIONS ARE SIGNED BY XAMAN WALLET:

  1. APP PREPARES XRPL TRANSACTION
  2. SENDS TO XAMAN VIA XUMM SDK
  3. XAMAN DISPLAYS TRANSACTION DETAILS TO USER
  4. USER REVIEWS AND APPROVES IN XAMAN APP
  5. XAMAN SIGNS TRANSACTION WITH PRIVATE KEY
  6. SIGNED TRANSACTION RETURNED TO APP
  7. APP SUBMITS TO XRPL LEDGER
  8. CONFIRMATION RECEIVED FROM LEDGER

SESSION MANAGEMENT

  • WALLET-BASED SESSIONS: NO TRADITIONAL PASSWORDS
  • JWT TOKENS: SHORT-LIVED TOKENS FOR API AUTHENTICATION
  • AUTO-LOGOUT: SESSIONS EXPIRE ON WALLET DISCONNECTION
  • RE-AUTHENTICATION: REQUIRES XAMAN SIGNATURE FOR SENSITIVE OPERATIONS
  • SESSION TIMEOUT: 24-HOUR SESSION EXPIRATION FOR SECURITY

TROUBLESHOOTING

XAMAN CONNECTION ISSUES

QR CODE NOT WORKING:

  • ✅ ENSURE XAMAN APP IS INSTALLED ON MOBILE DEVICE
  • ✅ CHECK CAMERA PERMISSIONS
  • ✅ TRY GENERATING A NEW QR CODE (REFRESH PAGE)
  • ✅ ENSURE MOBILE DEVICE HAS INTERNET CONNECTION
  • ✅ CHECK IF XAMAN APP IS UP TO DATE

DEEP LINK NOT OPENING XAMAN:

  • ✅ ENSURE XAMAN APP IS INSTALLED
  • ✅ TRY MANUALLY OPENING XAMAN AND CHECKING "EVENTS" TAB
  • ✅ CHECK IF XAMAN IS SET AS DEFAULT HANDLER FOR XUMM:// LINKS
  • ✅ RESTART XAMAN APP

"PAYLOAD EXPIRED" ERROR:

  • ⏰ XAMAN PAYLOADS EXPIRE AFTER 5 MINUTES
  • ✅ REFRESH THE PAGE AND TRY AGAIN
  • ✅ COMPLETE THE APPROVAL FASTER NEXT TIME

"CONNECTION TIMEOUT" ERROR:

  • 🌐 CHECK YOUR INTERNET CONNECTION
  • ✅ ENSURE XAMAN APP HAS INTERNET ACCESS
  • ✅ TRY SWITCHING BETWEEN WIFI AND MOBILE DATA
  • ✅ CHECK FIREWALL/VPN SETTINGS

ACCOUNT ISSUES

"ACCOUNT NOT FOUND" ERROR:

  • ℹ️ THIS IS NORMAL FOR NEW TESTNET ACCOUNTS
  • ✅ ACCOUNT WILL BE CREATED AFTER FIRST TRANSACTION
  • ✅ BALANCE WILL SHOW AS 0 UNTIL FUNDED
  • ✅ FOR MAINNET: ENSURE ACCOUNT HAS MINIMUM 10 XAH RESERVE

"ACCOUNT NOT ACTIVATED" ERROR (PAYMENT CHANNEL CREATION):

  • ⚠️ WORKER WALLET MUST BE ACTIVATED ON LEDGER BEFORE CREATING PAYMENT CHANNEL
  • ✅ SEND 10-20 XAH TO WORKER WALLET TO ACTIVATE
  • ✅ WAIT FOR LEDGER CONFIRMATION (3-5 SECONDS)
  • ✅ TRY CREATING PAYMENT CHANNEL AGAIN

"CONNECTION REJECTED":

  • 🚫 USER DECLINED CONNECTION IN XAMAN APP
  • ✅ TRY CONNECTING AGAIN AND APPROVE THE REQUEST
  • ✅ CHECK XAMAN "EVENTS" TAB FOR PENDING REQUESTS

PROFILE ISSUES

"WALLET ALREADY REGISTERED AS [TYPE]":

  • ⚠️ THIS WALLET IS ALREADY USED FOR A DIFFERENT ACCOUNT TYPE
  • ✅ USE A DIFFERENT WALLET ADDRESS
  • ❌ CANNOT SWITCH BETWEEN EMPLOYEE AND NGO/EMPLOYER TYPES
  • 💡 SOLUTION: CREATE A NEW WALLET IN XAMAN FOR THE OTHER ROLE

BEST PRACTICES

FOR USERS

  1. USE TESTNET FIRST: TEST WITH TESTNET XAH BEFORE USING REAL FUNDS
  2. BACKUP WALLET: ALWAYS BACKUP YOUR XAMAN WALLET SEED/RECOVERY PHRASE
  3. VERIFY TRANSACTIONS: ALWAYS REVIEW TRANSACTION DETAILS IN XAMAN BEFORE APPROVING
  4. SEPARATE WALLETS: USE DIFFERENT XAMAN WALLETS FOR EMPLOYEE VS NGO/EMPLOYER ROLES
  5. KEEP XAMAN UPDATED: REGULARLY UPDATE XAMAN APP FROM OFFICIAL SOURCES
  6. ENABLE BIOMETRICS: USE FACE ID/TOUCH ID FOR ADDED SECURITY
  7. NEVER SHARE SEED: NEVER SHARE YOUR XAMAN SEED PHRASE WITH ANYONE

FOR DEVELOPERS

  1. ERROR HANDLING: ALWAYS HANDLE XAMAN CONNECTION ERRORS GRACEFULLY
  2. USER FEEDBACK: SHOW CLEAR LOADING STATES DURING WALLET OPERATIONS
  3. NETWORK DETECTION: DETECT AND DISPLAY CURRENT NETWORK (TESTNET/MAINNET)
  4. TRANSACTION VALIDATION: VALIDATE TRANSACTIONS BEFORE SENDING TO XAMAN
  5. LOGOUT CLEANUP: PROPERLY DISCONNECT WALLET ON LOGOUT
  6. PAYLOAD EXPIRATION: HANDLE EXPIRED PAYLOADS WITH USER-FRIENDLY MESSAGES
  7. POLLING OPTIMIZATION: USE EFFICIENT POLLING FOR PAYLOAD STATUS
  8. DEEP LINK TESTING: TEST DEEP LINKS ON BOTH MOBILE AND DESKTOP

MIGRATION FROM PREVIOUS WALLET SUPPORT

FOR USERS WHO PREVIOUSLY USED CROSSMARK OR GEMWALLET:

  1. ✅ INSTALL XAMAN APP: DOWNLOAD FROM https://xaman.app
  2. ✅ IMPORT YOUR WALLET: USE YOUR EXISTING WALLET SEED PHRASE TO IMPORT INTO XAMAN
  3. ✅ CONNECT WITH XAMAN: USE THE NEW XAMAN CONNECTION FLOW
  4. ✅ VERIFY PROFILE: YOUR PROFILE IS TIED TO WALLET ADDRESS, SO IT REMAINS THE SAME
  5. ✅ RESUME WORK: ALL PAYMENT CHANNELS, WORK SESSIONS, AND HISTORY ARE PRESERVED

IMPORTANT NOTES:

  • ⚠️ YOUR WALLET ADDRESS STAYS THE SAME (PROFILE, CHANNELS, HISTORY INTACT)
  • ⚠️ ONLY THE CONNECTION METHOD CHANGES (NOW XAMAN INSTEAD OF CROSSMARK/GEMWALLET)
  • ✅ NO DATA LOSS OR MIGRATION REQUIRED
  • ✅ IMPROVED SECURITY WITH XAMAN'S ENTERPRISE-GRADE FEATURES

FEEDBACK & SUPPORT

HAVE QUESTIONS OR ISSUES?

  • 📧 OPEN AN ISSUE ON GITHUB
  • 💬 JOIN OUR COMMUNITY DISCORD
  • 📖 READ XAMAN DOCUMENTATION: https://xumm.readme.io/

FEATURE REQUESTS:

  • WE WELCOME FEEDBACK ON WALLET INTEGRATION
  • SUGGEST IMPROVEMENTS VIA GITHUB ISSUES

RESOURCES

LAST UPDATED: 2026-01-02 VERSION: 2.0.0 BREAKING CHANGE: REMOVED CROSSMARK AND GEMWALLET SUPPORT (AS OF 2025-12-30)