Developer Guide

How Stackr works under the hood, including the USSD protocol, wallet system, and Stellar integration.

USSD Protocol

Stackr uses the Africa's Talking USSD API. The protocol is text-based: Africa's Talking sends a POST request for each user interaction, and Stackr responds with menu text.

Request Format

Africa's Talking sends POST /ussd/callback with application/x-www-form-urlencoded:

FieldDescription
sessionIdUnique session identifier
phoneNumberUser's phone in E.164 format (+250781234567)
serviceCodeUSSD shortcode (*384#)
textCumulative user input separated by *

Cumulative Text Protocol

The text field accumulates all user inputs:

StepUser actiontext value
0Dial *384#(empty)
1Select "1" (Send Money)1
2Enter phone1*0781234567
3Enter amount1*0781234567*500
4Enter PIN1*0781234567*500*1234

Response Format

Responses are plain text prefixed with:

  • CON : session continues, show menu and wait for input
  • END : session ends, show final message

Wallet System

Key Derivation

Each phone number deterministically maps to a Stellar keypair. The same master seed + phone always produces the same wallet.

master_seed (env: WALLET_MASTER_SEED)
    │
    ▼
HKDF-SHA256(ikm=master_seed, salt=phone, info="stackr-stellar-wallet-v1")
    │
    ▼
32 bytes → ed25519 signing key → Stellar keypair

Security Layers

Encryption at rest

AES-256-GCM with 12-byte random nonce per record

PIN hashing

Argon2id: memory-hard, GPU/ASIC resistant

Key derivation

HKDF-SHA256 from master seed + phone

Fee payer

New accounts receive starting XLM; user wallets currently pay transaction fees

Critical Warning

WALLET_MASTER_SEED derives every user wallet. Losing it means losing access to all user funds. There is no recovery mechanism. Back it up with the same care as a root CA private key.

Stellar Integration

Transfer Flow

  1. 1. Look up sender's encrypted keypair from Postgres
  2. 2. Decrypt with AES-256-GCM
  3. 3. Claim the stable payment key in Postgres and atomically reserve daily spend
  4. 4. Build XDR payment operation
  5. 5. Sign with sender's key
  6. 6. Persist signed XDR and its deterministic transaction hash before sending
  7. 7. Submit to Stellar Horizon
  8. 8. Confirm settlement or keep it pending; background recovery reuses the original signed bytes

Transaction Types

  • payment: USDC transfers between accounts
  • create_account: fund new accounts with starting XLM
  • change_trust: add USDC trustline during registration
  • path_payment_strict_send: DEX swaps with path finding
  • fee_bump: sponsorship helper available; regular user payments currently pay their own fees

Anchor Integration (SEP-24)

Deposits and withdrawals use configured SEP-24 anchors. Validate corridor and asset support with the provider. SEP-10 challenges are checked before signing; withdrawal payments preserve the anchor’s memo type and value.

Order Lifecycle

pending → processing → completed
                    → error
                    → expired

Once an order reaches a terminal state, its status is immutable. This prevents duplicate webhook callbacks from double-crediting users.