Skip to main content

How It Works

Signup Flow​

When a new user signs up, three things happen automatically before the account is created in PostgreSQL:

  1. A Stellar keypair is generated for the user
  2. The distribution account funds the new Stellar account with 20 XLM to activate it on the testnet
  3. A trustline is established between the user's account and the FUC asset issuer

This means every registered user has a fully operational Stellar wallet from the moment they sign up. No separate setup is required.

POST /api/users/signup
        |
        v
Generate Stellar keypair
        |
        v
Fund new account with 20 XLM (from distribution account)
        |
        v
Establish FUC trustline
        |
        v
Save user to PostgreSQL (with stellarPublicKey + stellarSecretKey)

Funding Flow​

To fund their wallet, a user initiates a Paystack payment in Naira:

POST /api/paystack/create-payment-intent
        |
        v
User redirected to Paystack checkout
        |
        v
Payment completed → Paystack redirects to /api/paystack/callback
        |
        v
Payment verified → FUC tokens minted to user's Stellar wallet
        |
        v
HTML success page served to user

The amount paid in Naira maps directly to FUC tokens (1 FUC = 1 NGN). Duplicate payment references are tracked in memory to prevent double-minting.

Transfer Flow​

POST /api/stellar/transfer
        |
        v
Sender's Stellar secret key loaded from DB
        |
        v
Stellar payment transaction built + signed
        |
        v
Transaction submitted to Horizon testnet
        |
        v
Transaction record saved to PostgreSQL

Token Architecture​

FUO Wallet uses two Stellar accounts to manage the FUC token:

AccountRole
Issuing accountCreates and issues FUC tokens
Distribution accountHolds the token supply and funds new user accounts

When a user's wallet is funded, tokens flow from the distribution account to the user's Stellar wallet. When a user transfers tokens to another user, the transfer happens directly between their Stellar wallets. The distribution account is not involved.