upleb.uk

Public git repos — served from a NIP-34 GRASP relay at git.upleb.uk

summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorbitflash <dev@bitflash.network>2026-08-19 11:20:55 -0300
committerbitflash <dev@bitflash.network>2026-08-19 11:20:55 -0300
commit4c24a86a8aa01b02874e5bdb7856beed6e4cf6b6 (patch)
treeba90a774e80d12041369aaca2a4671de593cb30d /docs
parent5f453dd2964f070b6c296d1aec0ac5d4405bef8d (diff)
wallet/docs: SQLite is the default backend, not experimental
Drop the "experimental" label from the wallet code and docs now that SQLite is the default backend for new wallets, is coin-proven, and carries encrypt, backup, atomic seed writes, and the storage diagnostics. - main_gui.cpp: -help text, the unknown-backend error (SQLite is no longer "experimental" and Berkeley DB is no longer "the default"), and the startup banner ("Wallet backend: SQLite"). - walletcmd.h: the export command comment. - docs/storage.md: rewrite the SQLite section from staging-only ("runtime still opens Berkeley DB", "no runtime backend flag exists yet") to the shipped state -- default backend, conversion wizard, per-backend ops -- and reframe the migration order as shipped in v1.2.20.
Diffstat (limited to 'docs')
-rw-r--r--docs/storage.md67
1 files changed, 32 insertions, 35 deletions
diff --git a/docs/storage.md b/docs/storage.md
index 08c4a01..b52a955 100644
--- a/docs/storage.md
+++ b/docs/storage.md
@@ -85,10 +85,11 @@ A future wallet backend must keep these properties:
85 - recovery phrase encrypted and locked, requiring unlock before coverage can 85 - recovery phrase encrypted and locked, requiring unlock before coverage can
86 be audited. 86 be audited.
87 87
88## Experimental SQLite Wallet Store 88## SQLite Wallet Store
89 89
90The SQLite wallet path starts as a byte-preserving record store, not as a new 90Since v1.2.20 SQLite is the default wallet backend. It is a byte-preserving
91wallet format: 91record store, not a new wallet format -- the same serialized `CDataStream` bytes
92`wallet.dat` uses:
92 93
93```sql 94```sql
94CREATE TABLE wallet_records ( 95CREATE TABLE wallet_records (
@@ -98,32 +99,26 @@ CREATE TABLE wallet_records (
98PRAGMA user_version=1; 99PRAGMA user_version=1;
99``` 100```
100 101
101Keys and values are the same serialized `CDataStream` bytes used by `wallet.dat`. 102A fresh data directory starts on `wallet.sqlite`. An existing `wallet.dat` keeps
102The first implementation is exercised only by `-selftest=wallet-sqlite`; the 103running on Berkeley DB until it is converted: the GUI offers a one-click
103runtime wallet still opens Berkeley DB. The purpose is to prove schema creation, 104conversion on first run, and `-walletbackend=sqlite` / `-walletbackend=bdb`
104raw record write/read, close/reopen behavior, and value preservation before any 105(recorded in a plain-text `wallet-backend` marker file in the datadir) select a
105BDB-to-SQLite migration or runtime backend flag exists. 106backend explicitly. Conversion never modifies `wallet.dat`; it stays as a
106 107fallback, and the change takes effect on restart.
107`-walletsqliteexport=FILE` is the next staging tool. It streams every raw 108
108`wallet.dat` record through `ScanWalletRecords()` and writes those same key and 109Every wallet operation runs on either backend: read, write, erase, key-pool and
109value bytes into the SQLite table inside one transaction. It refuses to 110HD-seed writes (the two halves of the seed bracketed in one SQLite transaction),
110overwrite an existing export and still does not change the runtime wallet 111`-backupwallet` (checkpoint then copy the self-contained file), `-encryptwallet`
111backend. `CWalletDBSQLite::ScanRecords()` can stream those exported records back 112(an atomic rebuild-and-swap in one transaction), and the `-walletstorageaudit` /
112through the same visitor shape, so tests can compare BDB and SQLite record 113`-walletstoragecheck` diagnostics, which read the active backend's file.
113streams without introducing a SQLite runtime wallet loader yet. 114
114`-walletsqliteverify=FILE` compares the current `wallet.dat` stream with a 115The migration tooling remains available for scripted use. `-walletsqliteexport=FILE`
115SQLite export and prints only record counts and mismatch counts. 116streams every raw `wallet.dat` record through `ScanWalletRecords()` into a SQLite
116`-walletsqliterestore=FILE` rebuilds `wallet.dat` from a SQLite export only in 117file in one transaction, refusing to overwrite. `-walletsqliteverify=FILE`
117an empty data directory, then the verifier can prove the restored BDB file still 118compares the two streams and prints only counts. `-walletsqliteloadcheck=FILE`
118matches the export byte-for-byte. Failed exports remove the incomplete SQLite 119parses an export with the same record types the loader uses.
119file and failed restores remove the incomplete `wallet.dat`. 120`-walletsqliterestore=FILE` rebuilds a `wallet.dat` from an export in an empty
120`-walletsqliteloadcheck=FILE` parses a SQLite export using the same record 121data directory. Failed exports and restores remove their incomplete output.
121types the wallet loader understands, so a migration can prove the export is not
122just byte-preserving but loader-compatible before runtime activation.
123`-walletsqlite=FILE` is the first runtime staging flag: it loads a SQLite export
124through the startup wallet path, initializes the in-memory wallet state, reports
125success, and exits before network, mining, GUI, or wallet mutation begins. It is
126deliberately read-only until the write path is routed to SQLite as well.
127 122
128## `blkindex.dat` 123## `blkindex.dat`
129 124
@@ -150,12 +145,14 @@ conversion path.
150The old IP address database (`addr.dat`) has been removed. Peer discovery is 145The old IP address database (`addr.dat`) has been removed. Peer discovery is
151handled by Nostr, `.btf`, rendezvous relays, and direct onion peers. 146handled by Nostr, `.btf`, rendezvous relays, and direct onion peers.
152 147
153## Recommended Migration Order 148## Migration Order (shipped in v1.2.20)
154 149
1551. Keep adding storage self-tests around current BDB behavior. 1501. Storage self-tests were added around Berkeley DB behavior first.
1562. Add an experimental wallet backend behind an explicit flag. 1512. The SQLite backend landed behind an explicit flag, then behind a
1573. Implement BDB-to-new-wallet migration as a one-way copy with a backup. 152 `wallet-backend` marker and a GUI conversion wizard.
1584. Make the new wallet backend default only after cross-version restore, 1533. BDB-to-SQLite migration is a one-way copy that leaves `wallet.dat` as a backup.
159 encryption, backup, and recovery-audit tests pass. 1544. SQLite became the default for new wallets only after cross-version restore,
155 encryption, backup, and recovery-audit tests passed -- and a live coin-proof
156 of receive, spend, restart, and encrypt on real mainnet funds.
1605. Treat `blkindex.dat` separately; it is safer to rebuild than to migrate under 1575. Treat `blkindex.dat` separately; it is safer to rebuild than to migrate under
161 pressure. 158 pressure.