dashpay · Claudius-Maginificent · Jun 9, 2026 · Jun 9, 2026 · Jun 10, 2026 · Jun 10, 2026
@@ -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"
+        TEXT pool_type PK "external | internal | absent | absent_hardened"
+        INTEGER derivation_index PK
+        INTEGER account_index "account-level context; the value the read returns"
+        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, 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`
 
@@ -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` |
 

@@ -147,15 +147,20 @@ 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,
+    pool_type TEXT NOT NULL CHECK (pool_type IN {pool_type_check}),
+    derivation_index INTEGER NOT NULL,
     address TEXT NOT NULL,
-    derivation_path TEXT NOT NULL,
     used INTEGER NOT NULL,
-    PRIMARY KEY (wallet_id, account_type, address),
+    -- PK is the BIP32 leaf identity. `address` is a derived attribute, not
+    -- a key, so every collision (within- or cross-pool) trips
+    -- UNIQUE(address) loud. `account_index` is account-level context (the
+    -- value the read returns), not a uniqueness discriminator. The UNIQUE
+    -- index also backs ACCOUNT_INDEX_BY_ADDRESS_SQL.
+    PRIMARY KEY (wallet_id, account_type, pool_type, derivation_index),
+    UNIQUE (wallet_id, 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,

@@ -219,12 +219,27 @@ pub enum WalletStorageError {
     },
 
     /// 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.
+    /// `core_derived_addresses`, so its account index can't be resolved.
+    /// Retained as a fatal-classified typed marker; the apply path no
+    /// longer raises it — it skips such a UTXO (logged) so one
+    /// unresolvable row never aborts a whole flush, and the balance
+    /// re-warms when the address later derives.
     #[error("unspent utxo address {address} is not in core_derived_addresses")]
     UtxoAddressNotDerived { address: String },
 
+    /// A live `addresses_derived` entry arrived without its address in the
+    /// wallet's `account_address_pools` manifest. The emitter must attach a
+    /// full pool snapshot in-band with every derivation, so a derived
+    /// address absent from the manifest means the emitter contract is
+    /// broken — a logic regression, not a benign SPV gap. Failing loud at
+    /// the storage trust boundary surfaces it instead of persisting a row
+    /// the manifest can't vouch for.
+    #[error(
+        "emitter contract violated: derived address {address} is absent from the \
+         account_address_pools manifest (pool snapshot not emitted in-band)"
+    )]
+    DerivedIndexInvariantViolated { 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
@@ -373,6 +388,7 @@ impl WalletStorageError {
             | Self::AssetLockEntryMismatch { .. }
             | Self::BlobTooLarge { .. }
             | Self::UtxoAddressNotDerived { .. }
+            | Self::DerivedIndexInvariantViolated { .. }
             | Self::IntegerOverflow { .. } => false,
         }
     }
@@ -450,6 +466,7 @@ impl WalletStorageError {
             Self::AssetLockEntryMismatch { .. } => "asset_lock_entry_mismatch",
             Self::BlobTooLarge { .. } => "blob_too_large",
             Self::UtxoAddressNotDerived { .. } => "utxo_address_not_derived",
+            Self::DerivedIndexInvariantViolated { .. } => "derived_index_invariant_violated",
             Self::IntegerOverflow { .. } => "integer_overflow",
         }
     }