Skip to content

docs: real SECURITY.md + restructured README for external visitors #251

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kcw-grunt merged 3 commits into from
Jul 22, 2026
Merged

docs: real SECURITY.md + restructured README for external visitors #251

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c0e42f9
docs: add SECURITY.md with a real vulnerability disclosure process
claude Jul 22, 2026
5a9e355
docs: restructure README with a real front page for new visitors/cont…
claude Jul 22, 2026
0ec44e8
updated the README.md
kcw-grunt Jul 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
132 changes: 86 additions & 46 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,32 +1,80 @@

# Brainwallet: Android
The open source code of Brainwallet Android

## CI/CD Status
**main**: [![CircleCI](https://dl.circleci.com/status-badge/img/gh/gruntsoftware/android/tree/main.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/gruntsoftware/android/tree/main)
**Brainwallet** is a free, open-source, self-custodial [Litecoin](https://litecoin.org) wallet for Android. Your seed phrase and keys stay on your device — Brainwallet never has custody of your funds.

[![CircleCI](https://dl.circleci.com/status-badge/img/gh/gruntsoftware/android/tree/main.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/gruntsoftware/android/tree/main)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Website](https://img.shields.io/badge/website-brainwallet.co-blue)](https://brainwallet.co)

**CI status** — [main](https://dl.circleci.com/status-badge/redirect/gh/gruntsoftware/android/tree/main) · [develop](https://dl.circleci.com/status-badge/redirect/gh/gruntsoftware/android/tree/develop)

## Download

- **Play Store**: [ltd.grunt.brainwallet](https://play.google.com/store/apps/details?id=ltd.grunt.brainwallet)
- **iOS**: [gruntsoftware/ios](https://github.com/gruntsoftware/ios)
- **Website**: [brainwallet.co](https://brainwallet.co)
- **Support**: [brainwallet.co/support](https://www.brainwallet.co/support)

## Features

- Self-custodial Litecoin wallet — your seed phrase never leaves your device
- Send/receive LTC with real-time fee estimation and fiat conversion
- Games to help you memorize your seed phrase (Check out Fallinmoji!)
- PIN app lock
- Buy/sell LTC and gift cards via in-app widgets
- Modern Jetpack Compose UI, with a legacy Java/UIKit-era codebase still being progressively migrated

## Auditing code

### Prerequisites
- Android Studio (current stable) with SDK 36 installed, NDK `25.1.8937393`, CMake `3.22.1`
- `minSdk 29`, `targetSdk 35`

## Architecture

- **Language/UI**: Kotlin, Jetpack Compose (legacy screens still in Java/`View`-based UIKit-era code under `presenter/`, being migrated incrementally)
- **DI**: [Koin](https://insert-koin.io/)
- **Concurrency**: Kotlin Coroutines & `StateFlow`
- **Wallet core**: native C/C++ (`app/src/main/jni/core`), elliptic curve crypto via [`secp256k1`](https://github.com/bitcoin-core/secp256k1)
- **Modules**: `app` (main app), `bw-gdlib` (mini-games, LibGDX, composite build), `modules/private-general-purpose` (in-app purchases + general-purpose features), `android-build-logic` (shared Gradle convention plugins)

## Testing

Unit tests live under `app/src/test/{java,kotlin}`. Run them with `./gradlew test`, or a specific variant with `./gradlew testBrainwalletDebugUnitTest`. CI runs on CircleCI (`.circleci/config.yml`).

**develop**: [![CircleCI](https://dl.circleci.com/status-badge/img/gh/gruntsoftware/android/tree/develop.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/gruntsoftware/android/tree/develop)
## Security

Found a security vulnerability? Please **do not** open a public issue — see [SECURITY.md](SECURITY.md) for how to report it privately.


## License

Brainwallet Android is released under the [MIT License](LICENSE).

---

## Release Notes

For the full, up-to-date changelog see [GitHub Releases](https://github.com/gruntsoftware/android/releases) and the [compare view](https://github.com/gruntsoftware/android/compare). Highlights from recent versions:

# 🚀 Brainwallet Android — Release Notes
### v4.9.0

### ✨ New Features
#### ✨ New Features

#### 📋 Copy Transaction Details to Clipboard
##### 📋 Copy Transaction Details to Clipboard
Transaction details can now be copied directly to the clipboard from the transaction detail view. A new `BRClipboardManager.putDetailsClipboard()` method handles the copy action with full analytics tracking, making it easy to share or reference transaction information outside the app.

#### 📊 Analytics Tracking for Key Interactions
##### 📊 Analytics Tracking for Key Interactions
Firebase analytics events are now fired for core user interactions — fiat/LTC toggle, balance visibility toggle, and transaction detail copy — giving the team better insight into how users engage with the wallet's main screens.

---

### 🎨 UI / Design System
#### 🎨 UI / Design System

#### 🧱 Unified `bentoSurface` Design System
A new `bentoSurface()` modifier in `BentoModifiers.kt` consolidates gradient and border styling across the entire bento UI. Previously hardcoded values like `1.dp` borders are now driven by shared constants (`bentoBorderWidth`, `bentoCornerRadius`, `bentoCornerRadius`, `bentoSpacer`, `transactionActionHt`, `transactionDetailHt`), making the visual system consistent and easy to maintain going forward.
##### 🧱 Unified `bentoSurface` Design System
A new `bentoSurface()` modifier in `BentoModifiers.kt` consolidates gradient and border styling across the entire bento UI. Previously hardcoded values like `1.dp` borders are now driven by shared constants (`bentoBorderWidth`, `bentoCornerRadius`, `bentoSpacer`, `transactionActionHt`, `transactionDetailHt`), making the visual system consistent and easy to maintain going forward.

#### 🃏 Bento Section Refactors
##### 🃏 Bento Section Refactors
- **GameHub** — migrated from `Card` to `Box` with `bentoSurface()`, with a `clickable` modifier added
- **Favourites** — refactored to `bentoSurface()` with improved `Spacer` layout
- **LTC Picker** — label repositioned to top, spacing and item heights adjusted
Expand All @@ -35,66 +83,58 @@ A new `bentoSurface()` modifier in `BentoModifiers.kt` consolidates gradient and

---

### 🔧 Technical Changes
#### 🔧 Technical Changes
- `MainScreen`, `MainScreenEvent`, and `MainViewModel` updated for new event handling and state management
- `NoWifiBalanceAlertScreen` and `ReceiveDialog` border widths replaced with `bentoBorderWidth` constant
- `strings.xml` updated with new/updated string resources
- `gradle/libs.versions.toml` and `app/build.gradle.kts` dependencies updated
- `detekt-app-baseline.xml` baseline updated
- Version bumped: **v4.8.4 (202506314) → v4.9.0 (202506315)**
- Version bumped: **v4.8.4 (202506314) → v4.9.0 (202506315)**
- Release/v4.7.2 202506296 by @kcw-grunt in https://github.com/gruntsoftware/android/pull/134
- Release/v4.8.0 by @kcw-grunt in https://github.com/gruntsoftware/android/pull/145

**Full Changelog**: https://github.com/gruntsoftware/android/compare/v4.7.2...v4.9.0

### v4.8.3

## ✨ New UI — Favourites & Tutorials Bento Sections
#### ✨ New UI — Favourites & Tutorials Bento Sections
**PR [#191](https://github.com/gruntsoftware/android/pull/191)**
The main screen now features two new purpose-built bento panels replacing the generic placeholder container. The **Favourites** panel displays a set of coloured circular indicators using the app's design theme colours (affirm, info, warn, error) with full dark/light mode support. The **Tutorials** panel shows a "Coming Soon" placeholder consistent with the broader bento design language. The old `HomeBentoContainer` has been removed. String resources for both sections have been translated across 19 locales including Arabic, Chinese (Traditional & Simplified), French, German, Farsi, Hindi, Indonesian, Italian, Japanese, Korean, Polish, Punjabi, Brazilian Portuguese, Russian, Spanish, Swedish, Turkish, and Ukrainian.

## 🔧 Send Screen Overhaul & Financial Precision
#### 🔧 Send Screen Overhaul & Financial Precision
**PR [#182](https://github.com/gruntsoftware/android/pull/182)**
The send transaction flow has been fully redesigned as a multi-step paged screen (Pre-send → Confirm → Authenticate). All monetary values have been migrated from `Float` to `BigDecimal` with explicit rounding modes, eliminating floating-point precision issues in fiat/LTC conversions. Transaction fees are now calculated dynamically using `getFeePerKb()` rather than a static default. The pre-send composable has been broken into focused sub-components (`PreSendAddressRow`, `PreSendAmountRow`, `PreSendMemoRow`), and passcode UI components have been extracted into a dedicated package. QR code scanning is now wired into the send flow via an `EventBus` event. A `BWSender` class handles transaction preparation with proper error handling and activity context management.

## 🧪 Test Coverage Expanded to 309 Tests
#### 🧪 Test Coverage Expanded to 309 Tests
**PR [#182](https://github.com/gruntsoftware/android/pull/182)**

Unit test coverage has been significantly expanded alongside the send screen work, bringing the total suite to **309 tests**. New test classes include `AppModuleTest`, `SendStateTest`, and `BrainwalletAppTest`, covering the Koin DI module wiring, send state logic, and core app initialisation paths.



### v3.9.0 - v3.9.1 Latest
Update README for improved description by @kcw-grunt in #78
Beta Release [ 🚀 ] Merge Develop into Main by @kcw-grunt in #81

#### Fixes and Changes:
### v3.9.0 – v3.9.1
- Update README for improved description by @kcw-grunt in #78
- Beta Release [ 🚀 ] Merge Develop into Main by @kcw-grunt in #81
- Current fiat preference from Settings needs to be reset if set in the TickerBento
- Localizations are covered to 100%
- Mini game FALLINMOJI is present in the Welcome and Game Hub
- When setting the theme from the Settings and the Lock Screen and the Main screen is not consistently applied
- In general the fonts in the app are not consistent and need to be managed properly for consistency
- Mini game sounds set a nominal level
- Layout for iPhone 8 - iPhone 17 Pro Max is set for: Welcome Screen
- Support.brainwallet.co link is fixed

### v3.6.0 Latest

#### What's Changed
🚀[Release v3.5.0] Merge into Main by @kcw-grunt in #51
Full Changelog: v3.4.2...v3.6.0\

#### Updates:
- using bundle exec fastlane single_unit_test_all
- downgrade firebase to 11.12.0
- polsih ci config
- Theme applied from Settings/Lock Screen/Main screen made consistent
- Fonts made consistent across the app
- Mini game sounds set to a nominal level
- Layout fixes for iPhone 8 – iPhone 17 Pro Max on the Welcome Screen
- Support.brainwallet.co link fixed

### v3.6.0
- 🚀 [Release v3.5.0] merged into Main by @kcw-grunt in #51
- Full Changelog: v3.4.2...v3.6.0
- Switched to `bundle exec fastlane single_unit_test_all`
- Downgraded Firebase to 11.12.0
- CI config polish
- 🦾 Chore/migrate ready onboarding
- Fix/login view crash
- 🧰 fix: Removed the thread blocking seen in the lock screen trx. loading
- 🧰 Fix: removed thread blocking in the lock screen transaction loading
- Epic/settings migration (#50)
- Chore/refactor firebase analytics
- Chore/refactor Firebase analytics
- Chore/activate test coverage

### v3.3.1
- Added locale filter
- Made improvements to UI
- Fixes
- UI improvements
- Various fixes
68 changes: 68 additions & 0 deletions SECURITY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# Security Policy

Brainwallet is a self-custodial Litecoin wallet. A vulnerability here can put
users' funds or seed phrases at direct risk, so we treat security reports
with priority and ask that they be disclosed to us privately first.

## Reporting a Vulnerability

**Please do not open a public GitHub issue for security vulnerabilities.**
Public issues are indexed and searchable, and a wallet vulnerability
disclosed that way can be exploited before we're able to ship a fix.

To report a vulnerability, contact us at [brainwallet.co/support](https://www.brainwallet.co/support)
and clearly mark your message as a **security report**.

When reporting, please include:
- A description of the vulnerability and its potential impact
- Steps to reproduce, or a proof of concept if you have one
- The affected version (or commit hash) and platform (Android/iOS)
- Any suggested severity or CVSS score, if you have one

**What to expect:**
- We aim to acknowledge new reports within a few business days.
- We'll work with you to confirm the issue, keep you updated as we
investigate and remediate it, and let you know once a fix has shipped.
- With your permission, we're happy to credit you for the report once it's
resolved.

## Scope

**In scope:**
- The Brainwallet Android app in this repository — key management,
transaction signing and broadcast, wallet backup/recovery (seed phrase),
PIN/biometric authentication, and secure local storage
(`app/src/main/jni/core`, `app/src/main/secp/secp256k1`)
- Companion modules pulled in as git submodules: `bw-gdlib`,
`android-private-general-purpose`, `android-build-logic`

**Out of scope:**
- Vulnerabilities in third-party dependencies with their own upstream
disclosure process — please report to the upstream project (we'd
appreciate a copy of the report too, but it isn't required)
- Social engineering, phishing, or attacks requiring physical access to an
unlocked device
- Issues that only reproduce on a rooted/jailbroken device or a device
already compromised by other malware
- Denial-of-service against our backend/infrastructure rather than the app
itself
- Missing security best-practices with no demonstrated, concrete impact

## Supported Versions

Brainwallet ships continuously through the Play Store, and we only support
the most recently published release — please make sure you can reproduce an
issue on the latest version before reporting it.

| Version | Supported |
| -------------- | :-------: |
| Latest release | ✅ |
| Older releases | ❌ |

## Safe Harbor

We consider security research conducted in good faith and in line with this
policy to be authorized. We will not pursue legal action against researchers
who make a genuine effort to avoid privacy violations, data destruction, and
service disruption, and who report vulnerabilities to us privately as
described above before any public disclosure.