📖 Documentation: NextGen GitBook Docs
Honest status: this is a working Stellar testnet application, not a bank. Fiat on/off-ramps and identity verification (KYC) are not implemented — no provider is plugged in, the app is hard-gated from ever claiming otherwise, and several features that need a fiat rail are paused, not faked. See
/docs/fiat-kyc-gap.mdfor the full, unvarnished picture.
PayFlex is a non-custodial payments app on Stellar: every user is a Stellar account. The keypair is generated on-device, the secret seed never leaves the phone, and every payment is built, signed, and submitted from the device.
Contents: Stellar is the only rail · What works today · What is paused · The fiat/KYC gap · Documentation · Architecture · Getting started · Verification status · Engineering rules
There is no secondary settlement system, no treasury account, no parallel banking layer. The architecture:
- Non-custodial by design. The Stellar secret key lives in the platform
keychain/keystore (
flutter_secure_storage); only public keys and signatures ever leave the device. Accepted trade-off: lose the device and the seed, lose the account — there is no support-restore path. Seedocs/stellar/accounts-and-keys.md. - The backend never signs. PayFlex's NestJS backend (
backend/src/stellar/) is a thin, read-only companion: account lookups, transaction-history verification for recorded transfers, and read-only Soroban contract reads. It has no deposit, withdraw, or send endpoint. - The app talks to Horizon directly using the official
stellar_flutter_sdk(mobile) and@stellar/stellar-sdk(backend verification). Login is a challenge signed with the user's own Ed25519 key and verified against the registered public key — no passwords. - Every recorded payment is verified on-chain. When the app reports a
transfer, the backend pulls the real transaction from Horizon and checks it
matches every claimed field before storing anything —
docs/stellar/payments-lifecycle.mdwalks the full path.
| Feature | How |
|---|---|
| Transfers / PayTag / QR Pay | resolve → PIN → build → sign on-device → submit → record (verified) |
| Standing plans | scheduler marks payments DUE; paying is the normal on-device flow (no delegated debit exists on Stellar, and the app refuses to fake one) |
| Safebox group savings | a real Soroban escrow contract (backend/contracts/safebox): owner/admin-only withdrawal and the 3-admin cap enforced on-chain; contributions/withdrawals in the contract's own ledger, visible to all members |
| Send via link | non-custodial on-chain claimable balances — escrowed by the chain, never by PayFlex (links) |
| Split bills | orchestration only; each contributor pays the creator with an independent on-device payment |
| Offline Reserve / optical QR | two-device offline handoff signed by an independent device key; redemption settles as a real Stellar payment on reconnect (how it works) |
| Admin | server-gated (AdminGuard); shows Stellar accounts, verified transfers, and Safebox (Soroban) state |
What is paused, honestly — not hidden
These features had no function without a fiat rail. They are gated at the
architecture level (the backend's GatedModule and hard-gate flags), and the
UI shows clearly-labeled "coming soon" states rather than fake flows:
- Virtual cards — Stellar has no card-issuing capability; needs a processor partner.
- Agent cash-in/cash-out network — existed to bridge physical cash to fiat balances.
- Betting page funding — moved fiat to licensed betting providers.
- Loans / savings goals — no treasury to disburse from, no KYC'd history to score.
Attempting to reach the gated backend endpoints fails closed — see
backend/src/gated/ and backend/test/gated-features.e2e-spec.ts.
Two clean, unimplemented interfaces mark the seam where a real provider plugs in later — docstrings only, no fake implementations, no placeholder credentials:
backend/src/providers/identity-verification-provider.ts(KYC; SEP-12-shaped)backend/src/providers/fiat-rail-provider.ts(deposit/withdraw fiat ↔ Stellar asset; SEP-6/24-shaped)
The full analysis — what a real implementation would look like, and every
feature paused because of the gap — is in
docs/fiat-kyc-gap.md.
identityVerified and fiatCapable default to false on every account and
no code path can set them true until a real provider exists. Reference
options for later (a real anchor such as LINK/NGNC, or another regulated
partner) are discussed without commitment in /docs/fiat-kyc-gap.md.
- GitBook Documentation: https://nextgen-4.gitbook.io/nextgen-docs/backend
- In-repo docs:
docs/README.mdis the index; the map below says what each document answers.
| Document | Answers the question… |
|---|---|
docs/architecture.md |
How is the system put together, and why can't the backend move money? |
docs/deploy.md |
How do I deploy the backend (Railway / Render / Fly.io) and point the app at it? |
docs/fiat-kyc-gap.md |
What can this app not do, and where would a real fiat/KYC provider plug in? |
docs/stellar/README.md |
Index of the Stellar deep dives: accounts & keys, SEP-10 login, payments lifecycle, Safebox (Soroban), the offline protocol, testnet vs mainnet. |
docs/scf-application/README.md |
Stellar Community Fund submission drafts (project-specific, not engineering docs). |
app/ Flutter mobile app (iOS + Android) — non-custodial Stellar wallet
backend/ NestJS service: directory, verification, orchestration (never signs)
contracts/ backend/contracts/safebox — the Soroban escrow contract
docs/ this documentation set — start at docs/README.md
Two hard boundaries hold it together:
- The Flutter app talks to the backend AND to Horizon directly. The backend orchestrates and verifies; it can never move funds.
- Key material lives in exactly two places on-device: the Stellar key
(
StellarKeyService, platform keychain) that owns the account, and the offline-protocol device key (DeviceKeyService) that signs optical handoffs. Both are PIN-gated at the point of use.
cd backend
npm install
cp .env.example .env
docker compose up -d # Postgres + Redis for local dev
npx prisma migrate dev # creates the schema (first run only)
npm run start:dev # http://localhost:3000
npm test # e2e suites (includes the hard-gate test)cd backend/contracts/safebox
cargo build --target wasm32v1-none --release # or: stellar contract build
cargo test # on-chain enforcement testsDeploy from the app or CLI, then register the contract id with the backend (the backend verifies on-chain that the caller really is the contract owner before accepting the registration).
cd app
flutter pub get
flutter run --dart-define=BACKEND_BASE_URL=http://10.0.2.2:3000
flutter analyze
flutter testOnboarding: create account → set PIN (generates the Stellar keypair on-device, registers the public key) → Friendbot funds the account on testnet. On mainnet, activation requires a real minimum-reserve payment from an already-funded account — the app deliberately does not automate holding or paying out that reserve.
cd backend
npm run stellar:testnet-walkthrough # two accounts, XLM + issued-asset payments, history
npm run verify:offline # offline protocol primitives- Backend:
tsc --noEmitclean; e2e suites green (transfers, standing plans, links, QR, and the hard gate); the Stellar rail is verified against the live testnet by the walkthrough script. - Flutter:
flutter analyze/flutter testfor the offline protocol and Stellar models; the full end-to-end app flow needs a device/emulator. - Not production-ready by design while the fiat/KYC gate is closed: see the
honest-status note at the top and
/docs/fiat-kyc-gap.md.
- No key generation, storage, or signing outside
StellarKeyService/DeviceKeyService/WalletService— never inline in a screen. - The local user id is persisted on first creation (device + backend) — a user is never recreated on relaunch.
- Every route requires a valid access token by default (
AuthGuard); a route opts out explicitly with@Public(), never implicitly. - Every money-movement screen uses the shared confirmation flow
(
signAndSubmitTransfer+showPfConfirmation). - All monetary formatting goes through the shared money utilities, never inline conversions.
- The docs must never call this app production-ready or launch-ready while the fiat/KYC gate is closed.
PayFlex includes algorithmic components under open-source licenses — see THIRD_PARTY_NOTICES.md (the Decimen Optical Transfer offline-QR transport, MIT).
