dashpay · Claudius-Maginificent · Jun 9, 2026 · Jun 9, 2026 · Jun 10, 2026 · Jun 10, 2026
@@ -62,7 +62,7 @@ erDiagram
 
     ACCOUNT_REGISTRATIONS {
         BLOB wallet_id PK
-        TEXT account_type PK "standard | coinjoin | identity_registration | ..."
+        TEXT account_type PK "standard_bip44 | standard_bip32 | coinjoin | identity_registration | ..."
         INTEGER account_index PK
         BLOB account_xpub_bytes "bincode-encoded AccountRegistrationEntry"
     }
@@ -105,9 +105,10 @@ erDiagram
     CORE_DERIVED_ADDRESSES {
         BLOB wallet_id PK
         TEXT account_type PK
-        TEXT address PK "bech32 / Base58 address string"
-        INTEGER account_index
-        TEXT derivation_path "pool_type/derivation_index"
+        INTEGER account_index PK "owning account; also the value the read returns"
+        TEXT pool_type PK "external | internal | absent | absent_hardened"
+        INTEGER derivation_index PK
+        TEXT address UK "bech32 / Base58 address string"
         INTEGER used "0 | 1"
     }
 
@@ -403,12 +404,47 @@ finalized. Rows are removed when the transaction becomes confirmed.
 
 ### `core_derived_addresses`
 
-Address-to-account-index map. Written before UTXOs in the same
-transaction so the UTXO writer can resolve `account_index` by address.
-
-- PK: `(wallet_id, account_type, address)`.
+A live-fed indexed read-cache the UTXO writer joins to resolve a UTXO's
+`account_index` by address. The authoritative manifest is
+`account_address_pools` (kept complete and in-band by the
+`core_bridge` emitter); this table is the fast B-tree probe in front of it.
+Fed by exactly one source:
+
+- **Live `addresses_derived` events** — written before UTXOs in the same
+  transaction so the writer sees fresh rows.
+
+UTXO resolution for an unspent UTXO:
+
+1. **Cache hit** — resolve from this table.
+2. **Cache miss, manifest hit** — fall back to `account_address_pools`
+   (the in-band snapshot is applied earlier in the same tx). Resolved.
+3. **Miss in both** — a genuinely undeclared address (not ours, or an SPV
+   gap-limit edge). The writer **skips** it (with a `warn`) so one
+   unresolvable row never aborts a whole flush; its balance re-warms once
+   the address is later derived.
+
+(The spent-only synthetic-row path is exempt: a spent row uses an inert
+`account_index` placeholder and is excluded from reads.)
+
+A live `addresses_derived` entry whose address is absent from the manifest
+is a **fatal** `DerivedIndexInvariantViolated` — the emitter must attach
+the pool snapshot in-band with every derivation, so this can only fire on
+an emitter bug, never on a benign gap.
+
+> The non-ECDSA pool gap (BLS/EdDSA addresses are dropped from the event
+> projection, so they never produce an `addresses_derived` entry) cannot
+> manifest here: only ECDSA Standard/CoinJoin External/Internal addresses
+> are ever classified `Received`/`Change`, so a non-ECDSA address can never
+> be a `new_utxos` UTXO address. This is an upstream classifier property
+> (`key-wallet` `account_checker`), not enforceable at the storage layer.
+
+- PK: `(wallet_id, account_type, account_index, pool_type, derivation_index)` — the BIP32
+  leaf identity (one row per derived address).
+- `UNIQUE(wallet_id, address)` — the read-index invariant (one
+  account_index per address); its index also backs the address lookup, so
+  no separate index is needed. `address` is a derived attribute, never a
+  key, so every collision surfaces loud.
 - FK: `wallet_id → wallets(wallet_id) ON DELETE CASCADE`.
-- Index: `idx_core_derived_addresses_addr(wallet_id, address)`.
 
 ### `core_sync_state`
 
@@ -590,7 +626,7 @@ before the address exists.
 
 ## Enum-domain CHECK constraints
 
-Seven TEXT columns carry a `CHECK (col IN (...))` across five enum
+Eight TEXT columns carry a `CHECK (col IN (...))` across five enum
 domains — `account_type` is reused in three tables. The IN-list is built
 at migration time from `pub(crate) const *_LABELS` arrays declared next
 to each writer function. Four domains mirror an upstream Rust enum; the
@@ -604,6 +640,7 @@ fifth (`contacts.state`) is a synthetic lifecycle label naming which
 | `account_address_pools` | `account_type` | `sqlite::schema::accounts::ACCOUNT_TYPE_LABELS` |
 | `account_address_pools` | `pool_type` | `sqlite::schema::accounts::POOL_TYPE_LABELS` |
 | `core_derived_addresses` | `account_type` | `sqlite::schema::accounts::ACCOUNT_TYPE_LABELS` |
+| `core_derived_addresses` | `pool_type` | `sqlite::schema::accounts::POOL_TYPE_LABELS` |
 | `asset_locks` | `status` | `sqlite::schema::asset_locks::ASSET_LOCK_STATUS_LABELS` |
 | `contacts` | `state` | `sqlite::schema::contacts::CONTACT_STATE_LABELS` |
 

@@ -51,7 +51,6 @@ pub fn migration() -> String {
     let network_check = build_check_in(crate::sqlite::schema::wallets::NETWORK_LABELS);
     let account_type_check =
         build_check_in(crate::sqlite::schema::accounts::ACCOUNT_TYPE_LABELS);
-    let pool_type_check = build_check_in(crate::sqlite::schema::accounts::POOL_TYPE_LABELS);
     let asset_lock_status_check =
         build_check_in(crate::sqlite::schema::asset_locks::ASSET_LOCK_STATUS_LABELS);
     let contact_state_check =
@@ -82,16 +81,6 @@ CREATE TABLE account_registrations (
     FOREIGN KEY (wallet_id) REFERENCES wallets(wallet_id) ON DELETE CASCADE
 );
 
-CREATE TABLE account_address_pools (
-    wallet_id BLOB NOT NULL,
-    account_type TEXT NOT NULL CHECK (account_type IN {account_type_check}),
-    account_index INTEGER NOT NULL,
-    pool_type TEXT NOT NULL CHECK (pool_type IN {pool_type_check}),
-    snapshot_blob BLOB NOT NULL,
-    PRIMARY KEY (wallet_id, account_type, account_index, pool_type),
-    FOREIGN KEY (wallet_id) REFERENCES wallets(wallet_id) ON DELETE CASCADE
-);
-
 CREATE TABLE core_transactions (
     wallet_id BLOB NOT NULL,
     txid BLOB NOT NULL,
@@ -143,19 +132,6 @@ CREATE TABLE core_instant_locks (
     FOREIGN KEY (wallet_id) REFERENCES wallets(wallet_id) ON DELETE CASCADE
 );
 
-CREATE TABLE core_derived_addresses (
-    wallet_id BLOB NOT NULL,
-    account_type TEXT NOT NULL CHECK (account_type IN {account_type_check}),
-    account_index INTEGER NOT NULL,
-    address TEXT NOT NULL,
-    derivation_path TEXT NOT NULL,
-    used INTEGER NOT NULL,
-    PRIMARY KEY (wallet_id, account_type, address),
-    FOREIGN KEY (wallet_id) REFERENCES wallets(wallet_id) ON DELETE CASCADE
-);
-
-CREATE INDEX idx_core_derived_addresses_addr ON core_derived_addresses(wallet_id, address);
-
 CREATE TABLE core_sync_state (
     wallet_id BLOB NOT NULL PRIMARY KEY,
     last_processed_height INTEGER,

@@ -218,13 +218,6 @@ pub enum WalletStorageError {
         limit_bytes: usize,
     },
 
-    /// An unspent UTXO named an address absent from
-    /// `core_derived_addresses`, so its account index can't be resolved;
-    /// persisting it would mis-file live funds, so the write is refused.
-    /// Spent-only placeholder rows tolerate a missing mapping.
-    #[error("unspent utxo address {address} is not in core_derived_addresses")]
-    UtxoAddressNotDerived { address: String },
-
     /// `PRAGMA foreign_keys = ON` was issued on open but the read-back
     /// reported the constraint enforcement is still off — the linked
     /// SQLite build silently ignores the pragma (no FK support compiled
@@ -372,7 +365,6 @@ impl WalletStorageError {
             | Self::IdentityEntryIdMismatch
             | Self::AssetLockEntryMismatch { .. }
             | Self::BlobTooLarge { .. }
-            | Self::UtxoAddressNotDerived { .. }
             | Self::IntegerOverflow { .. } => false,
         }
     }
@@ -449,7 +441,6 @@ impl WalletStorageError {
             Self::IdentityEntryIdMismatch => "identity_entry_id_mismatch",
             Self::AssetLockEntryMismatch { .. } => "asset_lock_entry_mismatch",
             Self::BlobTooLarge { .. } => "blob_too_large",
-            Self::UtxoAddressNotDerived { .. } => "utxo_address_not_derived",
             Self::IntegerOverflow { .. } => "integer_overflow",
         }
     }

@@ -1053,9 +1053,10 @@ fn apply_changeset_to_tx(
     if !cs.account_registrations.is_empty() {
         schema::accounts::apply_registrations(tx, wallet_id, &cs.account_registrations)?;
     }
-    if !cs.account_address_pools.is_empty() {
-        schema::accounts::apply_pools(tx, wallet_id, &cs.account_address_pools)?;
-    }
+    // `account_address_pools` is intentionally NOT applied: UTXO attribution
+    // is hardcoded to the default account (index 0) in `core_state`, so the
+    // pool snapshot is no longer a storage input. The changeset field is kept
+    // for API stability and still feeds non-storage consumers.
     if let Some(core) = cs.core.as_ref() {
         schema::core_state::apply(tx, wallet_id, core)?;
     }