Developer Guide

How Stackr works under the hood — 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	10781234567500
4	Enter PIN	10781234567500*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, info="stackr-wallet-{phone}")
    │
    ▼
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

Users never hold or acquire XLM

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. Check idempotency key in Redis (prevents double-send)
4. Build XDR payment operation
5. Sign with sender's key
6. Wrap in fee bump transaction (signed by fee payer)
7. Submit to Stellar Horizon
8. Set idempotency key (1-hour TTL)

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 — platform pays all fees

Anchor Integration (SEP-24)

Deposits and withdrawals use the Stellar SEP-24 protocol with any compliant anchor.

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.