Skip to content

PI_WALLET_ACTIVATION_IMPLEMENTATION.md

Latest commit

 

History

History
178 lines (139 loc) · 5.92 KB

PI_WALLET_ACTIVATION_IMPLEMENTATION.md

File metadata and controls

178 lines (139 loc) · 5.92 KB

Pi Bridge Wallet Activation - Implementation Summary

Overview

Successfully implemented Pi bridge support for wallet activation in the ACBU backend. The system now automatically switches between Pi and Stellar XLM for wallet activation based on configuration.

Branch Information

Changes Made

1. Configuration (src/config/env.ts)

Added Pi network configuration with the following environment variables:

pi: {
  enabled: boolean,              // PI_BRIDGE_ENABLED
  secretKey: string,             // PI_SECRET_KEY
  apiUrl: string,                // PI_API_URL
  minBalancePi: number,          // WALLET_ACTIVATION_PI or PI_MIN_BALANCE
  network: "testnet" | "mainnet" // PI_NETWORK
}

2. New Services Created

a. Pi Client Service (src/services/pi/client.ts)

  • Implements Pi blockchain interactions
  • Supports creating accounts and transferring Pi
  • Includes retry logic and error handling
  • Methods:
    • sendPiToActivate(): Send Pi to activate wallet
    • getTransactionStatus(): Check transaction status
    • getBalance(): Get account balance
    • isEnabled(): Check if Pi bridge is enabled

b. Pi Activation Service (src/services/pi/activationService.ts)

  • Wrapper for Pi activation operations
  • Handles Pi-specific activation logic
  • Uses the Pi client for transactions

c. Pi Services Index (src/services/pi/index.ts)

  • Exports Pi services and types for easy importing

3. Modified Services

a. Wallet Activation Service (src/services/wallet/walletActivationService.ts)

Key Changes:

  • Added new sendCryptoToActivate() function that automatically selects between Pi and Stellar
  • Retained sendXlmToActivate() for backward compatibility
  • Automatic chain selection:
    • If PI_BRIDGE_ENABLED=true → Use Pi
    • Otherwise → Use Stellar XLM (default)
  • Updated documentation to mention Pi support

b. Wallet Activation Job (src/jobs/walletActivationJob.ts)

  • Updated to use sendCryptoToActivate() instead of sendXlmToActivate()
  • Now supports both Pi and Stellar transparently
  • Updated documentation to explain chain selection

c. Wallet Services Index (src/services/wallet/index.ts)

  • Exported new activation functions for external use

Environment Variables

To enable Pi bridge for wallet activation, set these variables in your .env:

# Enable Pi bridge
PI_BRIDGE_ENABLED=true

# Pi Network Configuration
PI_SECRET_KEY=your_pi_secret_key_here
PI_API_URL=https://api.pi.network.com  # or testnet URL
PI_NETWORK=testnet                      # or mainnet
PI_MIN_BALANCE=0.1                      # Minimum Pi for activation
WALLET_ACTIVATION_PI=0.1                # Alternative: WALLET_ACTIVATION_PI

# Keep Stellar config for fallback
STELLAR_NETWORK=testnet
STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org
STELLAR_SECRET_KEY=your_stellar_secret_here
WALLET_ACTIVATION_XLM=1                 # XLM amount for activation (used as fallback)

Behavior

Default Behavior (Pi Disabled)

KYC Fee Paid → Queue WALLET_ACTIVATION message → sendCryptoToActivate() → sendXlmToActivate() → Send 1 XLM to Stellar address

Pi Enabled Behavior

KYC Fee Paid → Queue WALLET_ACTIVATION message → sendCryptoToActivate() → sendPiToActivate() → Send 0.1 Pi to address

Feature Flow

  1. User completes KYC and pays fee
  2. createApplication() in KYC service enqueues wallet activation
  3. startWalletActivationConsumer() processes the queue message
  4. sendCryptoToActivate() is called with the user's address
  5. Chain selection happens:
    • If Pi enabled: Uses Pi client to send Pi tokens
    • If Pi disabled: Uses Stellar client to send XLM (backward compatible)
  6. Transaction hash is logged and stored

Error Handling

Both implementations handle:

  • Account already exists scenarios
  • Transaction failures
  • Network errors
  • Invalid addresses
  • Configuration errors (logged with helpful messages)

Testing Recommendations

  1. Test Stellar activation (default):

    PI_BRIDGE_ENABLED=false npm run dev
# KYC flow should activate wallet with XLM as before

  2. Test Pi activation:

    PI_BRIDGE_ENABLED=true
PI_SECRET_KEY=test_key
PI_API_URL=https://testnet-api.pi.network.com
npm run dev
# KYC flow should activate wallet with Pi

  3. Test fallback behavior:

    • Start with Pi enabled but invalid credentials
    • Should fail appropriately with clear error messages

Files Modified

  • src/config/env.ts - Added Pi configuration
  • src/services/wallet/walletActivationService.ts - Added multi-chain support
  • src/jobs/walletActivationJob.ts - Updated to use new function
  • src/services/wallet/index.ts - Exported new functions

Files Created

  • src/services/pi/client.ts - Pi network client
  • src/services/pi/activationService.ts - Pi activation logic
  • src/services/pi/index.ts - Service exports

Backward Compatibility

✅ Fully backward compatible

  • Default behavior unchanged (uses Stellar/XLM)
  • Pi is opt-in via environment variable
  • Existing deployments work without changes
  • Can switch between chains by updating environment variable

Creating a Pull Request

Your branch is ready! You can create a PR from: https://github.com/coderolisa/acbu-backend/pull/new/feature/pi-wallet-activation

Or use:

git push origin feature/pi-wallet-activation

Then visit GitHub to create the PR from feature/pi-wallet-activation to main.

Next Steps (Optional Enhancements)

  1. Add testnet/mainnet network detection to wallet class
  2. Support user-specific chain preferences
  3. Add monitoring and alerting for wallet activation failures
  4. Add API endpoint to check wallet activation status
  5. Support multiple chains in parallel (activate on both Pi and Stellar)