Skip to content

README.md

Latest commit

 

History

History
164 lines (125 loc) · 7 KB

README.md

File metadata and controls

164 lines (125 loc) · 7 KB
Raw

Flipcash

Flipcash for Android

Release GitHub License

Flipcash is a self-custodial mobile wallet for instant, global, private payments, built on the open Code Protocol and the Solana blockchain. Its base reserve currency is USDF (a USD stablecoin); on top of it, users create, buy, sell, and share launchpad currencies — custom on-chain tokens backed by USDF reserves (think memecoins backed by USDC). The signature interaction is a device-to-device cash bill: one phone shows an animated circular Kik Code, a second phone scans it, and a peer-to-peer handshake settles the payment.

This repository is the Android client. Keys never leave the device — every transaction is signed locally with Ed25519 keys derived from a BIP39 mnemonic.

Table of contents

Features

  • Self-custodial wallet — on-device keys, no custodian; USDF + launchpad currencies.
  • Device-to-device cash bills — scan a Kik Code to send/receive in person.
  • Launchpad currencies — create a USDF-backed token; buy/sell it against USDF via an on-chain bonding curve.
  • Contact & username sends, remote send via shareable link, and in-app messaging.
  • Funding & withdrawal — Coinbase on-ramp, in-app purchase, and on-chain USDC withdrawals.
  • Verified pricing — every payment carries a cryptographically signed exchange-rate proof.

How it works

  • USDF is the reserve currency. Launchpad currencies are priced in and redeemable for USDF; USDF is locked in each currency's liquidity pool as backing.
  • Two gRPC backends. The Flipcash service (accounts, profiles, chat, activity) and the Open Code Protocol / OCP service (transactions, intents, swaps, exchange rates).
  • Intents over Solana. Money movement is expressed as signed intents submitted over a bidirectional SubmitIntent stream; the client builds and signs the Solana transactions locally, so the backend can verify rates and limits without ever holding the keys.

Architecture

A multi-module Gradle project (100+ modules) with a strictly layered, acyclic dependency graph. UI is Jetpack Compose (dark-mode only); dependencies are wired with Hilt and surfaced to Compose through CompositionLocal.

graph TD
    App["apps/flipcash/app — entry point, navigation host, DI wiring"]
    Features["apps/flipcash/features/* — 26 self-contained screens"]
    Shared["apps/flipcash/shared/* — coordinators / controllers / services"]
    Services["services/* — gRPC wrappers (API → Service → Repository → Controller)"]
    Defs["definitions/* — protobuf sources + generated models"]
    UI["ui/* — Compose components, theme, navigation, scanner"]
    Libs["libs/* — crypto, network, logging, currency (leaf utilities)"]

    App --> Features --> Shared --> Services --> Defs --> Libs
    Features --> UI --> Libs
    Services --> Libs
Loading

The full architecture is documented in docs/architecture/ — 18 topic docs covering modules & boundaries, state & DI, navigation, networking, persistence, payments, the design system, testing, and more.

Tech stack

Area Choice
Language / UI Kotlin, Jetpack Compose (Material 3)
Navigation Jetpack Navigation 3 + a custom CodeNavigator
DI Hilt + CompositionLocal
Async Kotlin Coroutines + Flow (MVI via BaseViewModel<State, Event>)
Networking gRPC + Protobuf; Retrofit/OkHttp for REST
Persistence Room (per-user database) + DataStore
Crypto Ed25519, BIP39 mnemonic/key derivation, Solana
Build Gradle convention plugins, KSP, Java 21

Project structure

apps/flipcash/      Main app + feature (26) and shared modules
services/           gRPC clients: flipcash, opencode (+ Compose wrappers)
definitions/        Protobuf sources and generated models
libs/               Reusable utilities (crypto, network, logging, currency, …)
ui/                 Compose design system, navigation, scanner, biometrics
vendor/             Third-party SDKs (Kik scanner, OpenCV, TipKit)
build-logic/        Convention plugins for consistent module setup
docs/               Architecture documentation

Each service module has its own README: services/flipcash, services/opencode.

Getting started

Prerequisites

  • JDK 21 (Amazon Corretto)
  • Android SDK (compileSdk 37, minSdk 29)
  • google-services.json placed at apps/flipcash/app/src/
  • API keys in local.properties — MIXPANEL_API_KEY, BUGSNAG_API_KEY, COINBASE_ONRAMP_API_KEY, GOOGLE_CLOUD_PROJECT_NUMBER (a missing key won't fail the build, but disables the dependent feature)

Build & run

# Debug APK
./gradlew :apps:flipcash:app:assembleDebug

# Release bundle (AAB)
./gradlew :apps:flipcash:app:bundleRelease

# Unit tests (all modules)
./gradlew test

See docs/architecture/10-build-and-run.md for the full setup, build variants, and CI details.

Testing

Fast JVM unit tests (Robolectric where Android APIs are needed), with :libs:test-utils providing coroutine test helpers and Turbine for flow assertions. CI runs the unit suite via Fastlane (bundle exec fastlane android flipcash_tests). See docs/architecture/12-testing.md.

Documentation

Contributing

Contributions are welcome via pull request.

  • Conventional commits (feat:, fix:, chore:, optional scope e.g. feat(oc):).
  • Default branch: code/cash; open PRs against it.
  • CI runs on every PR (tests via Fastlane); please run ./gradlew test locally first.

Community & support

License

Released under the MIT License — see LICENSE.md.