minibits-cashandClaude Opus 4.8
f8ed2d4a71
Two things, in one commit because the test that proves the first needs the second.
Fix the upgrade path (a bug shipped in 2f7a276)
A wallet at db v29 came up with a zero balance. instance.ts ran
createSchemaQueries on EVERY launch, before migrations. `CREATE TABLE IF NOT
EXISTS` skips the tables a device already has — but silently creates the ones it
does not, at TODAY's shape. A device predating a table therefore received it
fully formed, and the migration that adds a column to that table then died on
"duplicate column name". The batch is atomic, so EVERY migration rolled back:
hence the cascade of "no such column: mintId" and a wallet with nothing in it.
Concretely: v29 predates onchain_mint_quotes (v31), so it was built already
carrying the mintId that v33 exists to add.
This is the same replay trap that made v26/v28/v29/v31 freeze their column
lists. I fixed it for migrations sharing live constants and missed that
createSchemaQueries does the same thing, on every existing database.
The fix is strictly either/or. Only dbversion is created unconditionally (reading
the version needs it); then the version decides. Fresh install → build at the
latest shape and record it. Existing database → migrations own every shape
change, so each table is created by ITS migration at THAT version's shape, which
is what keeps the later ALTERs valid.
The gap was structural: every db suite starts from a FRESH in-memory database,
where instance.ts builds the latest schema and seeds the version — so migrations
never run at all. The path every user takes had no coverage. dbUpgradePath.test.ts
closes it via a __seedNextDatabase hook on the op-sqlite mock, covering every
version 26→34 through the real instance.ts and asserting the money, the
derivation counter, the added columns, and that the repos work afterwards.
Reverted to the shipped ordering, 16 of its 17 tests fail.
The v26 fixture is VERIFIED against tag v0.4.3-beta.3 — the last released native
bundle, `_dbVersion = 26`, `rootStoreModelVersion = 32`, which is where even a
brand new install starts today before OTA. Its createSchemaQueries builds exactly
those four tables and its column lists match the fixture one for one. It is frozen
on purpose: a fixture that tracks schema.ts describes a device that never existed.
Master mints in SQLite (Stage 1)
Mints were the last core entity persisted by serializing the whole MST tree.
Since postProcessSnapshot already strips proofs and transactions, mints — with
every keyset's `keys` map — were the largest thing left in it, and
JSON.stringify(snapshot) runs on EVERY MST action anywhere, including every proof
mutation during a send. New tables: mints, and mint_keysets keyed by keysetId
(matching mint_counters; keyset and keys stored as whole JSON so fields like
final_expiry, which feeds NUT-02 v2 id derivation, cannot be dropped by an
enumerated column list).
SQLite is the authority, MST the cache — as for proofs and transactions. Reads
and MobX reactivity are unchanged. Persistence is one onSnapshot observer per
mint rather than a write-through in each of ~20 Mint mutators, where forgetting
one is silent staleness; it is equality-guarded on the PERSISTED payload, so a
proofsCounters change cannot churn the row, and attached only after load.
The rename is now ONE transaction across the mint row and its proofs
(mintsRepo.updateMintUrl). The standalone updateProofsMintUrl is deleted so the
non-atomic path cannot come back. Previously the url lived in MMKV and the proofs
in SQLite, so a crash between the two writes left proofs owned by no mint: the
money vanished from every per-mint balance while still counting in the total, and
could not be spent.
postProcessSnapshot strips mints, so ExportBackup had to change in the same
commit: getSnapshot(mintsStore).mints is now ALWAYS empty, and a backup taken
from it would contain zero mints, raise no error, and reveal the loss only on
restore. The build moved onto the store as a tested `backupSnapshot` view.
ImportBackup persists explicitly, since applySnapshot nodes arrive already-formed
and observers fire only on change.
Two bugs the tests caught before the device could
- types.Date rejects an ISO string, so loading threw on typecheck: every launch
after the migration would have failed to load any mint.
- proofsCounters came back EMPTY, because loading bypasses initKeyset. The
counter hydrate would have had nothing to fill, the counter would be recreated
at 0 on first use, and derivation would reuse blinded secrets the mint had
already signed — the exact fund loss this branch began with, reintroduced by
its own fix. Neither is SQL; no mirror-style test could have found them.
Sabotage-verified: dropping the counter shells, building the backup from
getSnapshot, and skipping the proofs in the rename each fail the suite. The first
of those did NOT fail until the assertion was added, which is why it was checked.
Tests: 503 pass.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Minibits Wallet
Minibits is an ecash and Lightning wallet exploring how ₿-backed ecash can enable instant, cheap, and private value transfer. Ecash is issued by mints and backed by Bitcoin via the Cashu protocol and Lightning Network. Ecash is cash-like yet digital token with cheap and instant transfers and high privacy guarantees.
Disclaimer
⚠️ If you are using this app, please take the following into consideration:
- This wallet should be used for research purposes only.
- The wallet is a beta version with incomplete functionality and both known and unknown bugs.
- Do not use it with large amounts of ecash.
- The ecash stored in the wallet is issued by the mint. You trust the mint to back it with bitcoin until you transfer your holdings to another bitcoin lightning wallet.
- The Cashu protocol that the wallet implements has not yet received extensive review or testing.
Roadmap
Platform support
- Android app - Play Store, Zapstore [✨ New!] , Github
- iOS app - AppStore, Testflight and Freedomstore.io
- Light and dark mode
- i18n support
- EN, PT, ES, SK languange support
Mints
- Multiple currency units issued by mints
- Add multiple mints
- Remove mints
- Block receiving from mint
- Show mint balances grouped by currency units
- Handle mint keys rotation (not tested)
- Mint status and information screen
Receive ecash
- Scan QR code of a ecash token
- Animated QR codes support for large tokens
- Paste ecash token from the clipboard
- Receive Nostr zaps or Lightning payments to minibits.cash address
- Receive ecash from another wallet over NOSTR message sent to minibits.cash address
- Receive ecash in person while being offline, redeem later (MVP version)
- Realtime and encrypted push notifications on receive to minibits.cash lightning address
- Display or send cashu payment requests
Send ecash
- Share ecash token to send through another app
- Show ecash token as a QR code
- Show large ecash token as an animated QR code
- Send ecash to contact (minibits.cash or another NOSTR address)
- Lock ecash to the receiver wallet key (P2PK)
- Set lock expiry to allow recovery of locked ecash after timeout (P2PK)
- Scan and pay cashu payment requests
Top up wallet
- Show QR code with bitcoin Lightning invoice to pay
- Share encoded bitcoin Lightning invoice to pay
- Share lightning invoice with a contact over NOSTR message
- Top up balance with LNURL Withdraw
- Enter transaction amount in fiat currency
Pay / Cash out from wallet
- One click ZAPS - tip users of NOSTR social network
- Pay bitcoin Lightning invoice with your ecash
- Pay lightning invoices received from another contact
- Pay to LNURL Pay static links / codes
- Pay to Lightning address
- Swap ecash between mints / currencies in a single step
Transaction history
- Unified transaction history for all kinds of transactions
- Audit trail of transaction events
- Transaction search and filters [✨ New!]
- Retry after recoverable transaction errors
- Revert pending transaction in 1 click (get back tokens not claimed by receiver)
- Tags and related filtering of transactions
- Delete incomplete and failed transactions from history
Contacts
- Private contacts address book for payments
- Public contacts (followed users on NOSTR social network) for tipping and donations
- Load public contacts from custom NOSTR relay
- Wallet addresses as random public NOSTR addresses (random123@minibits.cash)
- Custom wallet names (myname@minibits.cash)
- Wallet addresses usable as Lightning addresses to receive payments from many Lightning wallets
- Private contacts with other than minibits.cash NOSTR adresses and relays
Backup and recovery
- Local append-only backup of all ecash in a database separate from wallet storage
- Export wallet backup with ecash, mints, contacts and recent transactions
- Recovery of ecash using 12 words menmonic phrase in case of lost device
- Recovery by importing wallet backup
- Move wallet address from another device using the seed phrase
- Recover wallet in case spent ecash remains in the wallet
- Retry transaction after recoverable errors
- Auto-recover funds if wallet failed to receive ecash issued by mint due to network or device failure
Interoperability
- Nostr Wallet Connect - lets you initiate payments from another app, such as Nostr client
- Deeplinks - app reacts to lightning: and cashu: URIs
- NFC - reads Cashu requests or Lightning invoices over the NFC and pays instantly [✨ New!]
- NFC HCE - Android app shares Cashu tokens, requests or invoices over the NFC [✨ New!]
Security and Privacy
- Use device biometry to login
- Connect to the mints on .onion Tor addresses using own Tor daemon [discontinued from v0.1.7]
- Connect to the mints on .onion Tor addresses using Orbot
Self-funding
- Donation for custom wallet name
DevOps
- OTA updates (opt in)
- Automated tests
- Automated release pipelines for both OTA updates and native releases
Architecture
The wallet's design has been crafted to prioritize the following primary quality properties:
- Support both Android and iOS mobile platforms
- Achieve fast UX and startup time (despite using React Native)
- Minimize the risk of data/ecash loss
- Bring ecash UX on par with the current standard of traditional finance (tradfi) mobile apps
As a result, the following architectural constraints are in place:
- Wherever available, use libraries with a fast JSI (JavaScript Interface) to native modules.
- Avoid Expo modules.
- Use fastest available storage for most wallet operations and a separate local database storage to store data that incrementally grows.
- Leverage local SQLite database as persistent storage for ecash notes.
Open architectural concepts that were still open for discussion when the wallet had been released
- Contacts management - identities, sharing contacts, send ecash with the UX of tradfi instant payment while keeping privacy towards mints - Implemented as NOSTR keypairs and NIP05 public sharable names that ecash can be sent to
- Off-device backup strategy - Implemented using @gandlafbtc concept of deterministic secrets + wallet export and import
- UX and naming conventions - ecash is not always intuitive. UX for new users heavily depends on using the right abstractions or terms to describe what is going on. This wallet wants to serve as a means to test what could work. One of the first ideas is to avoid terms such as token or proof and propose the term --coin ++ecash instead.
- Suitable Tor daemon available to replace not maintained react-native-tor. From v0.1.8-beta.33 connection through Orbot in VPN mode is possible.
Download and test
Minibits wallet is in early beta and available as of now only for Android devices. You have the following options to try it out:
- Download it from Google Play
- Join testing program on Google Play to get early releases to test (Submit your email to get an invite on Minibits.cash)
- Download .apk file from Releases page and install it on your phone
- Try on Testflight
- Download from Freedomstore.io (for EU-based users)
- Download from AppStore
Development
Minibits is a bare React Native app written in Typescript. The project structure and code itself are intentionally verbose to support readability. Critical wallet code is reasonably documented. However, there is vast space for existing code improvements, refactoring, and bug fixing. This is an early beta software and the author does not code for a living.
The code is derived from Ignite template, however with many libraries, notably Expo, stripped down to achieve fast startup times. Performance bottleneck on some Android devices is react-native-keychain. To overcome this, it has been patched not to warm-up on startup, caching for wallet operations is in place and its use to encrypt storage is opt-in.
Wallet state is managed by mobx-state-tree and persisted in fast MMKV storage. Only the basic mobx concepts are in place, whole model could be improved. All critical wallet code is in services/walletService.ts and all ecash state changes are in models/ProofsStore.ts. Wallet communication with the mints is in model/Wallet.ts and uses cashu-ts library.
Crypto operations are handled by react-native-quick-crypto, that is fast and does not require awful javascript shims. Transaction history and ecash notes are stored in sqlite, with fast react-native-quick-sqlite driver that enables to run lighter queries synchronously.
Wallet included own Tor daemon using react-native-tor library to connect to the mints over Tor network. However this seems not to be long term approach as this library is not properly maintained and future updates of React native will likely break it. Help with replacement would be appreciated.
In case of breaking state and data model changes, versioning and code is ready to run necessary migrations on wallet startup.
Running in development mode
To run Minibits wallet in dev mode, set up the React Native development environment and the Yarn package manager. Then clone this repository, navigate to the minibits_wallet directory, and run the following:
yarn install
There are post-install patches to some of the libraries that should run automatically and are necessary for a successful run. See the patches directory for more info. After the dependecies are installed, continue to create the following .env file in the root folder:
APP_ENV='DEV'
MINIBITS_SERVER_API_HOST='http://localhost/api/v2'
MINIBITS_NIP05_DOMAIN='@localhost'
MINIBITS_RELAY_URL='ws://localhost/relay'
MINIBITS_MINT_URL='http://localhost/mint'
Local NOSTR address and Lighnting brigde server are not necessary to run the wallet. Then make sure you have the Android device connected by running:
yarn adb
Finally run this and pray:
yarn start
In case of issues, repo includes commits history from the out of the box react native app up until the complete wallet. You can see build.gradle and other changes one by one and hopefully figure out what's wrong.
Building
Create debug .apk:
yarn android:dev
Automated testing
The app has the scaffolding for automated tests; they are yet to be implemented. For functional bugs or suggestions please raise an issue.
Contributing
Contributions are welcome, just start and we will figure out what's next.