Stellar PocketPay

React Native Expo wallet for Stellar Testnet. The app aims to feel polished and usable for core wallet flows while still evolving as the PocketPay ecosystem matures.

Project Status

• This project is best described as a polished but still-evolving wallet experience rather than a production-ready product.
• Core flows such as wallet creation and import, balance checks, sending and receiving, contacts, and the vault UI are implemented and actively refined.
• The app is intentionally focused on Stellar Testnet for development and experimentation. Testnet XLM has no real monetary value.
• The vault experience is currently mock-backed by default. A real Soroban contract integration can be enabled with configuration, but the default experience remains a safe placeholder.

Documentation

• Architecture Readiness Review - Feature boundaries, duplicated state, SDK integration blockers, security-sensitive areas, and test gaps

• Evaluation-Readiness Index - Central index linking all evaluation-readiness requirements, including payment expectations, tests, CI, and reviewer checklists

• Issue Approval Readiness Checklist - Fast pre-approval gate covering implementation completeness, tests, CI status, acceptance criteria, documentation, and known limitations, plus the reminder that a merged PR does not guarantee payment approval

• Evaluation Readiness Checklist - GrantFox contributor checklist for mobile issues, including tests, CI, screenshots, acceptance criteria, and the reminder that merge does not guarantee payment approval

• Payment-Period Communication Policy - How contributors should communicate during the payment evaluation period: no spam or pressure, self-review before raising payment concerns, and follow the GrantFox evaluation process

• Self-Review Checklist - Quick checklist to run before opening a PR, covering feature completion, tests, CI, screenshots, and device/emulator verification

• Contributor Self-Assessment - Pre-review form for confirming scope, test evidence, CI, documentation, limitations, and acceptance criteria

• Meaningful Change Threshold Guide - Guide explaining what constitutes a meaningful change and how reviewers should assess PR scope and completeness

• Reviewer Evidence Checklist - Maintainer-facing checklist for reviewing whether a PR is complete and evaluation-ready, covering implementation scope, quality, test evidence, CI status, documentation impact, acceptance-criteria verification, and risk

• Storage Guide - SecureStore vs AsyncStorage

• Test-First Contribution Guide - Required test planning, happy-path and negative-path coverage, no-test justification rules, and local verification commands for mobile PRs

• Low-Effort Contribution Examples - Worked examples of superficial changes, partial implementations, missing tests, and failing CI, with why each is insufficient and an improved alternative for each

• Contacts Guide - Contact storage, backup limitations, and future export/import ideas

• Contact Import Design - Design for safe contact import, validation, duplicate handling, privacy boundaries

• Polyfills Guide - React Native polyfills and import order for Stellar SDK

• Vault UI Guidance - How to present the Soroban Savings Vault, Testnet risks, and contract limitations

• Vault Integration Assumptions - Document expected SDK/contract dependencies, placeholder behaviors, and known gaps

• Vault Integration Risks - Assumptions, risks, and integration points between the mobile UI, PocketPay SDK, and Soroban contract

• Mobile Wallet Security FAQ - Local storage, secret handling, reset behaviors, and security guarantees

• Accessibility Checklist - Required mobile accessibility checks and reusable-component review guidance for major screens and every UI state

• UI State Catalogue - Canonical loading, empty, error, success, disabled, and pending behavior for wallet, send, receive, transactions, contacts, vault, settings, and diagnostics

• Scan-to-Pay Review - QR scan → validate → review screen → cancel-before-payment flow (never signs on scan)

• Release Testing Checklist - Manual QA checklist run before every tagged build, covering wallet, payment, vault, errors, and environment verification

⚠️ This app runs on the Stellar Testnet only. Testnet XLM has no real monetary value. Read the Security Guide before storing or sharing any keys.

Features

• Wallet creation and import
• XLM balance and transactions
• Send and receive with QR codes
• Address book contacts
• Soroban vault placeholder

For the expected screen sequence, validation, and UI states behind these features, see Main wallet user flows.

Ecosystem

PocketPay Mobile is part of a broader PocketPay stack:

• PocketPay SDK
• PocketPay Contracts

Documentation

• Screen Inventory - A map of the main screens and routes in the app.
• Screen Test Matrix - Which test types and visual verification each screen requires, and current coverage gaps
• Mobile Onboarding Checklist - Quick-reference setup checklist for new contributors
• Self-Review Checklist - Pre-PR checklist covering feature completion, tests, CI, screenshots, and device/emulator verification
• Evaluation Readiness Checklist - Mobile-issue review checklist for GrantFox contributors before payment evaluation
• UI State Catalogue and Accessibility Checklist - Governance for major-screen states, shared component contracts, and accessible review evidence
• QR Receive Payload Format - The address-only and SEP-0007-based payment-request formats the Receive screen encodes into its QR code
• Test Fixture Framework - Reusable, typed fixtures for wallet, payment, vault, transaction, error, and diagnostics states, and how to use them in a test
• Traceability Table Guide - How to map mobile changes to issue acceptance criteria

Screenshots

📸 Screenshots below are placeholders. To update them, capture each screen from a simulator or device (use dummy/funded Testnet data only — never real keys or mainnet funds) and replace the files in docs/screenshots/.

Wallet	Send	Receive
Balance overview and quick actions	Send XLM to any Stellar address	QR code for your public key

Activity	Contacts	Vault
Transaction history with sent/received indicators	Saved addresses for quick access	Soroban Savings Vault (mock)

Updating screenshots

1. Run the app in a simulator with a funded Testnet account.
2. Navigate to the relevant screen.
3. Take a screenshot and export it at roughly 390 × 844 px (iPhone 14 logical resolution) or equivalent Android size.
4. Save it to docs/screenshots/<screen-name>.png using the filenames shown above.
5. Commit only the image files — never include screenshots that reveal a real secret key or personal data.

Tech Stack

React Native, Expo Router, Zustand, PocketPay SDK, SecureStore, AsyncStorage

// To Start

Quick Start

npm install --legacy-peer-deps
cp .env.example .env
npm start

## Continuous Integration (CI) Standards
All contributions are required to pass automated CI pipelines prior to review and merge. 
Please review the [CI Pass Requirements Guidance](docs/CI_REQUIREMENTS.md) for local reproduction commands and guidelines on resolving failing checks.