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:
| Field | Description |
|---|---|
sessionId | Unique session identifier |
phoneNumber | User's phone in E.164 format (+250781234567) |
serviceCode | USSD shortcode (*384#) |
text | Cumulative user input separated by * |
Cumulative Text Protocol
The text field accumulates all user inputs:
| Step | User action | text value |
|---|---|---|
| 0 | Dial *384# | (empty) |
| 1 | Select "1" (Send Money) | 1 |
| 2 | Enter phone | 1*0781234567 |
| 3 | Enter amount | 1*0781234567*500 |
| 4 | Enter PIN | 1*0781234567*500*1234 |
Response Format
Responses are plain text prefixed with:
CON: session continues, show menu and wait for inputEND: 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 keypairSecurity 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. Look up sender's encrypted keypair from Postgres
- 2. Decrypt with AES-256-GCM
- 3. Claim the stable payment key in Postgres and atomically reserve daily spend
- 4. Build XDR payment operation
- 5. Sign with sender's key
- 6. Persist signed XDR and its deterministic transaction hash before sending
- 7. Submit to Stellar Horizon
- 8. Confirm settlement or keep it pending; background recovery reuses the original signed bytes
Transaction Types
payment: USDC transfers between accountscreate_account: fund new accounts with starting XLMchange_trust: add USDC trustline during registrationpath_payment_strict_send: DEX swaps with path findingfee_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
→ expiredOnce an order reaches a terminal state, its status is immutable. This prevents duplicate webhook callbacks from double-crediting users.