feat(wallet): implement C09 stellar wallet transactions, integration …

[Fabr-i10]

Closes #31

---

PR title

feat(wallet): implement C09 stellar wallet transactions, integration and tests

---

Description

This PR implements C09 — Stellar wallet: transactions, integration and tests for the Ding Payments mobile client.

It introduces the transaction primitives and wallet infrastructure required before payment execution, including typed transaction builders, fee affordability validation, centralized Horizon access, standardized wallet error mapping, wallet readiness integration, comprehensive regression tests, and architecture documentation.

The implementation completes the work defined in CLI-039 through CLI-044, providing a reusable and well-tested foundation for future payment submission, NFC transport, and higher-level wallet features.

---

Type of change

• New feature (feat)
• Bug fix (fix)
• Refactor / internal improvement
• Documentation
• Tests
• Other

---

Changes made

CLI-039 — Transaction builder

• Added typed payment transaction schema (paymentTx.ts)
• Implemented TransactionBuilder for XLM and USDC payment transactions
• Added canonical Stellar amount validation
• Implemented deterministic stroop conversion
• Applied default transaction timebounds
• Added validation for:
  • destination addresses
  • memo length
  • malformed amounts
  • unsupported assets
  • decimal precision

Shared Horizon infrastructure

• Introduced StellarHorizonClient
• Centralized Horizon server interactions behind a reusable service
• Migrated:
  • AccountService
  • BalanceService
  • TrustlineService
• Removed duplicated Horizon client creation across wallet services

CLI-040 — Fee estimation and reserve validation

• Added FeeService
• Implemented payment affordability validation
• Added shared Stellar reserve utilities (stellarReserve.ts)
• Extended BalanceService with stroop-based helpers
• Reused reserve calculations within TrustlineService

CLI-041 — Wallet error mapping

• Added walletErrors.ts
• Implemented Horizon/SDK → WalletErrorCode translation
• Added localized wallet error messages
• Integrated wallet errors with the toast abstraction
• Added wallet error analytics event definitions
• Preserved user-friendly messaging without exposing Horizon payloads

CLI-042 — Wallet integration

• Updated AuthGuard to require both:
  • authenticated user
  • wallet ready state
• Waits for wallet hydration before redirecting
• Prevents redirect loops during onboarding
• Updated Settings to display the real Stellar public key
• Extended logout flow to:
  • remove Stellar public key
  • remove Stellar secret key
  • clear session metadata
  • reset wallet store

CLI-043 — Tests

Added deterministic Jest coverage for:

• TransactionBuilder
• FeeService
• StellarHorizonClient
• Wallet error mapping
• Stellar reserve calculations
• AuthGuard
• Settings
• Logout cleanup
• Updated AccountService tests
• Updated BalanceService tests
• Updated TrustlineService tests

All wallet tests execute using mocked Horizon and mocked Stellar SDK components without requiring network connectivity.

CLI-044 — Documentation

• Added docs/wallet-flow.md
• Documented wallet onboarding sequence
• Added wallet state machine diagrams
• Documented wallet service ownership
• Documented reserve formulas
• Documented error taxonomy
• Documented secure key model
• Linked wallet documentation from the project README

---

Test plan

• Verified TransactionBuilder builds valid XLM payment transactions
• Verified TransactionBuilder builds valid USDC payment transactions
• Verified amount validation and stroop conversion
• Verified default transaction timebounds
• Verified fee affordability matrix
• Verified reserve validation for XLM and trustlines
• Verified Horizon error mapping into WalletErrorCode
• Verified AuthGuard wallet readiness behavior
• Verified logout removes Stellar credentials and resets wallet state
• Verified Settings displays the correct Stellar public key
• Verified wallet documentation
• Executed deterministic Jest suites using mocked Horizon and Stellar SDK

---

Screenshots / evidence

Test execution

PASS TransactionBuilder.test.ts
PASS FeeService.test.ts
PASS BalanceService.test.ts
PASS TrustlineService.test.ts
PASS StellarHorizonClient.test.ts
PASS walletErrors.test.ts
PASS AccountService.test.ts
PASS AuthGuard.test.tsx
PASS SettingsAuthSection.test.tsx
PASS useAuth.logout.test.tsx

Test Suites: 11 passed
Tests: 127 passed

---

Checklist

• I included Closes #31 with the correct issue number
• Code follows project conventions (src/features/, etc.)
• Wallet services remain decoupled from UI through typed service boundaries
• Wallet transaction logic is covered by deterministic unit tests
• Horizon interactions are mocked (no network dependency)
• Updated documentation (docs/wallet-flow.md)
• Updated README with wallet documentation link
• Wallet implementation is ready for future payment submission and NFC integration