This fork is a BlueWallet Android build that can use a fully self-hosted GroundControl server. Goal: self-hosted push notifications + maximum privacy/control (no dependency on official BlueWallet backends).
Self-hosted push pipeline (unconfirmed/received/confirmed) confirmed working with our GroundControl fork.
For reproducible Android builds and release workflow see:
π docs/RELEASE.md
- Android app (this repo): React Native build
- GroundControl (server repo): Node.js/TypeScript + MariaDB
- Firebase (FCM): own Firebase project + service account key (server-side)
This app is designed to work with a self-hosted GroundControl server:
GroundControl fork (server): https://github.com/Alex71btc/GroundControl
The fork adds:
- Fully self-hosted push notifications (FCM)
- Separate push tags for:
- unconfirmed
- received
- confirmed transactions
- Token auto-cleanup for uninstalled apps
The repository contains full documentation on how to build, configure and run your own GroundControl instance, including:
- Installation & build instructions
- Environment variables
- Database setup
- Firebase service account (server-side FCM)
- Push notification flow
- Token lifecycle & cleanup
π Start here:
https://github.com/Alex71btc/GroundControl/tree/master/docs
The documentation is intentionally kept in the server repository to clearly separate app-side and server-side responsibilities.
- Ubuntu 24.04
- Android SDK / platform-tools (
adb) - JDK 17 (recommended for modern AGP)
- Node.js + yarn/npm as required by the repo
Push notifications use Firebase Cloud Messaging (FCM).
To build the Android app with your own Firebase project you must provide a local google-services.json.
-
Create / open your Firebase project in the Firebase Console.
-
Add an Android app to the project:
- Package name must match the app's
applicationId(seeandroid/app/build.gradle). - (Optional) Add SHA-1 / SHA-256 fingerprints if you use features that require it.
- Package name must match the app's
-
Download google-services.json from Firebase and place it here:
android/app/google-services.json -
Never commit this file. It must stay local. This repo ignores it via
.gitignore:android/app/google-services.jsonandroid/app/google-services.json.local
Notes:
google-services.jsoncontains project identifiers and API keys. Treat it as sensitive and keep it out of Git history.- Server-side FCM for GroundControl is configured separately (Firebase service account key on the server).
In the app:
- Settings β Network β Notifications (GroundControl)
- Tap the hidden βMajor Tomβ text 10Γ (Developer section appears)
- Enter your GroundControl URL (example:
http://<LAN-IP>:3000) and Save
This repo supports local release signing via Gradle properties.
Keystore (example path):
~/.keystores/bluewallet-gc.jks
Gradle properties (local, do NOT commit):
~/.gradle/gradle.properties
RELEASE_STORE_FILE=/home/<user>/.keystores/bluewallet-gc.jks
RELEASE_STORE_PASSWORD=...
RELEASE_KEY_ALIAS=bluewallet-gc
RELEASE_KEY_PASSWORD=...
Build:
cd android
./gradlew clean
./gradlew assembleRelease
ls -la app/build/outputs/apk/release/
Install:
adb devices -l
adb install -r android/app/build/outputs/apk/release/app-release.apk
Notes
Keep secrets out of git (google-services.json, keystore, Gradle props, .env).
Push notifications are expected to work with a self-hosted GroundControl when the server is configured with your Firebase service account.
# BlueWallet - A Bitcoin & Lightning Wallet
[](https://github.com/BlueWallet/BlueWallet)
[](https://circleci.com/gh/BlueWallet/BlueWallet)
[](https://github.com/prettier/prettier)
Thin Bitcoin Wallet.
Built with React Native and Electrum.
[](https://itunes.apple.com/us/app/bluewallet-bitcoin-wallet/id1376878040?l=ru&ls=1&mt=8)
[](https://play.google.com/store/apps/details?id=io.bluewallet.bluewallet)
Website: [bluewallet.io](https://bluewallet.io)
Community: [telegram group](https://t.me/bluewallet)
* Private keys never leave your device
* Lightning Network supported
* SegWit-first. Replace-By-Fee support
* Encryption. Plausible deniability
* And many more [features...](https://bluewallet.io/features)
<img src="https://i.imgur.com/hHYJnMj.png" width="100%">
## BUILD & RUN IT
Please refer to the engines field in package.json file for the minimum required versions of Node and npm. It is preferred that you use an even-numbered version of Node as these are LTS versions.
To view the version of Node and npm in your environment, run the following in your console:
node --version && npm --version
* In your console:
git clone https://github.com/BlueWallet/BlueWallet.git cd BlueWallet npm install
Please make sure that your console is running the most stable versions of npm and node (even-numbered versions).
* To run on Android:
You will now need to either connect an Android device to your computer or run an emulated Android device using AVD Manager which comes shipped with Android Studio. To run an emulator using AVD Manager:
1. Download and run Android Studio
2. Click on "Open an existing Android Studio Project"
3. Open `build.gradle` file under `BlueWallet/android/` folder
4. Android Studio will take some time to set things up. Once everything is set up, go to `Tools` -> `AVD Manager`.
* π This option [may take some time to appear in the menu](https://stackoverflow.com/questions/47173708/why-avd-manager-options-are-not-showing-in-android-studio) if you're opening the project in a freshly-installed version of Android Studio.
5. Click on "Create Virtual Device..." and go through the steps to create a virtual device
6. Launch your newly created virtual device by clicking the `Play` button under `Actions` column
Once you connected an Android device or launched an emulator, run this:
npx react-native run-android
The above command will build the app and install it. Once you launch the app it will take some time for all of the dependencies to load. Once everything loads up, you should have the built app running.
* To run on iOS:
npx pod-install npm start
In another terminal window within the BlueWallet folder:
npx react-native run-ios
**To debug BlueWallet on the iOS Simulator, you must choose a Rosetta-compatible iOS Simulator. This can be done by navigating to the Product menu in Xcode, selecting Destination Architectures, and then opting for "Show Both." This action will reveal the simulators that support Rosetta.
**
* To run on macOS using Mac Catalyst:
npx pod-install npm start
Open ios/BlueWallet.xcworkspace. Once the project loads, select the scheme/target BlueWallet. Click Run.
## TESTS
```bash
npm run test
MIT
Grab an issue from the backlog, try to start or submit a PR, any doubts we will try to guide you. Contributors have a private telegram group, request access by email bluewallet@bluewallet.io
We accept translations via Transifex
To participate you need to:
- Sign up to Transifex
- Find BlueWallet project
- Send join request
- After we accept your request you will be able to start translating! That's it!
Please note the values in curly braces should not be translated. These are the names of the variables that will be inserted into the translated string. For example, the original string "{number} of {total}" in Russian will be "{number} ΠΈΠ· {total}".
Transifex automatically creates Pull Request when language reaches 100% translation. We also trigger this by hand before each release, so don't worry if you can't translate everything, every word counts.
Builds automated and tested with BrowserStack
Bugs reported via BugSnag
Found critical bugs/vulnerabilities? Please email them bluewallet@bluewallet.io Thanks!