A mobile Bitcoin Lightning wallet built with Expo/React Native, connecting via Nostr Wallet Connect (NWC) with Nostr social features.
- Connect any Lightning wallet via NWC (Nostr Wallet Connect)
- On-chain Bitcoin wallets (watch-only via xpub, or hot wallets via mnemonic)
- Transfer funds between wallets (LN-to-LN, LN-to-on-chain, on-chain-to-LN, on-chain-to-on-chain)
- Send payments by scanning QR codes or pasting invoices
- Send to lightning addresses (user@domain) via LNURL-pay
- Send to on-chain addresses (BIP-21 URI support with amount)
- NIP-57 zaps to Nostr contacts
- Receive payments with QR code generation (optional amount for BIP-21)
- Real-time balance display with fiat conversion
- Transaction history
- Nostr identity login (nsec or Amber signer on Android)
- Friends tab with Nostr contacts and phone contacts
- Follow/unfollow Nostr contacts (kind 3 event publishing)
- Add friends by pasting npub or scanning QR code
- Contact profile cards with deep linking to Nostr apps
- QR code sharing for npub and Lightning address
- Secure credential storage (expo-secure-store)
Lightning Piggy Mobile implements the following open standards. See docs/STANDARDS.adoc for usage details and source references.
| Standard | Name |
|---|---|
| BIP-21 | URI Scheme (bitcoin: with ?amount=) |
| BIP-32 | Hierarchical Deterministic Wallets |
| BIP-39 | Mnemonic Seed Phrases |
| BIP-84 | Native SegWit HD Wallets (bc1q...) |
| BIP-327 | MuSig2 Schnorr Key Aggregation |
| BIP-340 | Schnorr Signatures |
| BIP-341 | Taproot (SegWit v1) |
| Standard | Name |
|---|---|
| NIP-01 | Basic Protocol (relays, events, subscriptions) |
| NIP-04 | Encrypted Direct Messages |
| NIP-05 | DNS Identity Verification |
| NIP-14 | Subject Tag (used as group-chat name) |
| NIP-17 | Private Direct Messages (sealed + multi-recipient group chat) |
| NIP-19 | Bech32-encoded Entities (npub, nsec) |
| NIP-20 | Command Results (OK messages) |
| NIP-21 | nostr: URI Scheme |
| NIP-44 | Encrypted Payloads v2 (used by NIP-17 sealing) |
| NIP-47 | Nostr Wallet Connect (NWC) |
| NIP-55 | Android Signer (Amber) |
| NIP-57 | Lightning Zaps |
| NIP-59 | Gift Wrap (used by NIP-17 to mask sender + metadata) |
| NIP-65 | Relay List Metadata |
| NIP-94 | File Metadata |
Group state for client-side group chat is propagated via a parameterised-replaceable
kind:30200 event (custom to this client; receivers reconcile by groupId + created_at).
Not a NIP — see src/services/nostrService.ts (GROUP_STATE_KIND) for the schema.
| Standard | Name |
|---|---|
| BOLT-11 | Lightning Invoice Encoding |
| LNURL / LUD-16 | Lightning Address Protocol (user@domain) |
On top of these, Lightning Piggy Mobile uses the Boltz v2 submarine swap API for trustless Lightning ↔ on-chain transfers.
- Node.js (v18+)
- Expo CLI
- An Android device or emulator
- A Lightning wallet that supports NWC (e.g. Alby, LNbits)
git clone https://github.com/BenGWeeks/lightning-piggy-mobile
cd lightning-piggy-mobile
npm installThis project uses custom native modules (Amber signer), so it requires a dev client build rather than Expo Go.
# First time: build and install the dev client
npx expo run:android
# Subsequent runs: start Metro (connects to the dev client)
npm start
# Press 'a' to open on a connected Android deviceNote: Always use
npm start(notnpx expo start) — the start script includes--dev-clientwhich is required for custom native modules. Usingnpx expo startdirectly will launch in Expo Go mode and show "Something went wrong".
Optional keys are read from .env at the repo root (gitignored) and inlined into the bundle at build time via app.config.ts / Metro's EXPO_PUBLIC_* handling.
| Variable | Used by | Notes |
|---|---|---|
EXPO_PUBLIC_GIPHY_API_KEY |
In-conversation GIF picker | Free key from developers.giphy.com/dashboard. Restrict it to the Android package / iOS bundle ID in the GIPHY dashboard — keys are public by design, not a secret. When unset, the "Send GIF" row is hidden from the attach menu and nothing else breaks. |
After changing .env, restart Metro (npm start) so the new value gets inlined. No native rebuild is required for EXPO_PUBLIC_* changes.
# Generate the native Android project
npx expo prebuild --platform android
# Build the APK
cd android && ./gradlew assembleRelease
# Install on connected device
adb install app/build/outputs/apk/release/app-release.apknpm install -g eas-cli
eas login
eas build --platform android --profile previewsrc/
components/ # Reusable UI components (SendSheet, ContactProfileSheet, etc.)
contexts/ # React contexts (WalletContext, NostrContext)
navigation/ # React Navigation setup
screens/ # App screens (Home, Earn, Learn, Friends, Account)
services/ # Business logic (NWC, LNURL, Nostr, contacts)
styles/ # Theme and shared styles
types/ # TypeScript type definitions
assets/ # Images and icons
modules/ # Custom native Expo modules (Amber signer)
plugins/ # Expo config plugins
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.