feat(wallet-storage)!: restore complete Core wallet snapshots from SQLite

CHANGELOG.md

@@ -48,6 +48,11 @@
   `serialization::dashcore::bls_pubkey` Serde adapter remains a deprecated alias.
   Serialized encodings and consensus rules are unchanged. See [#5320](https://github.com/dashpay/platform/pull/5320).
 
+- **Breaking (Rust API):** `platform_wallet_storage::LoadSite` gains
+  `PoolRowBeyondDerivationBudget` and `UnrestoredPoolReservation` and is now
+  `#[non_exhaustive]`; code that matches it exhaustively needs a wildcard arm.
+  Persisted data, FFI layouts and capability bits are unchanged.
+
 ## [5.0.0-beta.2](https://github.com/dashpay/platform/compare/v5.0.0-beta.1...v5.0.0-beta.2) (2026-10-06)
 
 

packages/rs-platform-wallet-storage/src/sqlite/load_ctx.rs

@@ -40,7 +40,13 @@ use crate::sqlite::error::WalletStorageError;
 /// for the same site — the two are deliberately separate: a UI layer wants
 /// the prose, a log consumer wants the tag, and neither should have to
 /// derive one from the other.
+///
+/// `#[non_exhaustive]`: a new kind of inconsistency gets its own variant, so
+/// a match outside this crate needs a wildcard arm and keeps compiling when
+/// one is added. Inside the crate [`as_str`](Self::as_str) and
+/// [`explanation`](Self::explanation) still match every variant by name.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+#[non_exhaustive]
 pub enum LoadSite {
     /// `core_sync_state.last_applied_chain_lock` failed to decode.
     ChainLockBlob,
@@ -72,6 +78,13 @@ pub enum LoadSite {
     UndecodableAddressScript,
     /// One used address resolves to two different owning accounts.
     UsedAddressOwnerConflict,
+    /// A stored address-pool row sits further above the rest of its pool
+    /// than the load will derive to check it, so it is not restored.
+    PoolRowBeyondDerivationBudget,
+    /// A stored address reservation was taken back by no restored pool: its
+    /// row matches no account of the wallet, or was left out above. Counted
+    /// per reservation.
+    UnrestoredPoolReservation,
     /// An `identity_keys` row was unreadable or contradicted its columns.
     IdentityKeyRow,
     /// A `contacts` row was unreadable or contradicted its columns.
@@ -122,6 +135,8 @@ impl LoadSite {
             Self::UnresolvedUtxoAddress => "unresolved_utxo_address",
             Self::UndecodableAddressScript => "undecodable_address_script",
             Self::UsedAddressOwnerConflict => "used_address_owner_conflict",
+            Self::PoolRowBeyondDerivationBudget => "pool_row_beyond_derivation_budget",
+            Self::UnrestoredPoolReservation => "unrestored_pool_reservation",
             Self::MissingIdentityOwner => "missing_identity_owner",
             Self::UnownedIdentityHasRegistrationIndex => "unowned_identity_has_registration_index",
             Self::IdentityIndexCollision => "identity_index_collision",
@@ -160,16 +175,22 @@ impl LoadSite {
             Self::WalletRehydration => {
                 "recovery mode: dropping one wallet that could not be rebuilt, keeping the rest of the file"
             }
-            // The only two sites `note_degraded` ever reaches (see its
-            // callers) — never-fatal in either policy, so their prose
-            // describes an accepted-as-is degradation rather than a
-            // tolerated inconsistency.
+            // The sites `note_degraded` reaches (see its callers) —
+            // never-fatal in either policy, so their prose describes an
+            // accepted-as-is degradation rather than a tolerated
+            // inconsistency.
             Self::OrphanedUtxoOwner => {
                 "load degraded: routing addresses from an unavailable owner to the first funds account"
             }
             Self::UnresolvedUtxoAddress => {
                 "load degraded: deferring addresses that did not resolve against the account xpub"
             }
+            Self::PoolRowBeyondDerivationBudget => {
+                "load degraded: leaving out address-pool rows too far above their pool to be checked"
+            }
+            Self::UnrestoredPoolReservation => {
+                "load degraded: stored address reservations that no restored pool took back"
+            }
             // Sites whose site tag plus the logged error already say
             // everything a reader needs, so they share the generic line.
             Self::ChainLockBlob
@@ -305,6 +326,10 @@ pub(crate) struct SiteCoords<'a> {
     pub detail: Option<&'a dyn fmt::Debug>,
 }
 
+/// The per-site counts of a [`LoadCtx`] at one moment; see
+/// [`LoadCtx::counts_checkpoint`].
+pub(crate) struct CountsCheckpoint(BTreeMap<LoadSite, u32>);
+
 /// Per-`load()` policy + counters, created on the loading thread's stack.
 ///
 /// Not stored on the persister (which keeps only the resulting
@@ -438,6 +463,22 @@ impl LoadCtx {
         )
     }
 
+    /// The per-site counts as they stand, to come back to with
+    /// [`rewind_counts`](Self::rewind_counts).
+    pub(crate) fn counts_checkpoint(&self) -> CountsCheckpoint {
+        CountsCheckpoint(self.counts.borrow().clone())
+    }
+
+    /// Forget what was counted since `checkpoint`.
+    ///
+    /// For a reader whose result is thrown away and built again: the second
+    /// pass meets the same rows, and what the first tolerated is not in the
+    /// state the load returns, so keeping both would report every incident
+    /// twice. Only the counts go back; the log keeps both passes.
+    pub(crate) fn rewind_counts(&self, checkpoint: CountsCheckpoint) {
+        *self.counts.borrow_mut() = checkpoint.0;
+    }
+
     /// Attribute a whole-wallet loss to the wallet it belongs to.
     ///
     /// Separate from [`tolerate_at`](Self::tolerate_at), which counts the

packages/rs-platform-wallet-storage/src/sqlite/persister.rs

@@ -1310,11 +1310,10 @@ impl PlatformWalletPersistence for SqlitePersister {
         // transaction. The current schema also has lossless token balances,
         // invitations, account pools, tracked asset locks, and
         // deferred-contact-crypto queue rows.
-        // Do NOT attest WALLET_RESTORE (and therefore not provider restore):
-        // token balances and the DashPay overlay have no load readers, so a
-        // full restore remains lossy. Shielded viewing keys are native when
-        // compiled in; notes, nullifiers, and sync state use ShieldedStore.
+        // WALLET_RESTORE covers the Core snapshot; auxiliary token, profile,
+        // invitation, and deferred-contact readback remains separate.
         let capabilities = PersistenceCapabilities::ATOMIC_CHANGESETS
+            .union(PersistenceCapabilities::WALLET_RESTORE)
             .union(PersistenceCapabilities::INVITATIONS)
             .union(PersistenceCapabilities::ASSET_LOCK_FUNDING_INDICES)
             .union(PersistenceCapabilities::UNSIGNED_TOKEN_STORAGE)
@@ -1691,10 +1690,15 @@ fn load_one_wallet(
     let tx = rusqlite::Transaction::new_unchecked(conn, rusqlite::TransactionBehavior::Immediate)
         .map_err(WalletStorageError::from)
         .map_err(PersistenceError::from)?;
+    let counted_before = ctx.counts_checkpoint();
     let (mut state, sweeps) = load_wallet_snapshot(&tx, wallet_id, ctx)?;
     if !sweeps.is_empty() {
         schema::core_state::apply_replay_sweeps(&tx, &wallet_id, sweeps)
             .map_err(PersistenceError::from)?;
+        // The snapshot above is thrown away, and what it tolerated with it:
+        // the rebuild meets the same rows and counts them for the state that
+        // is returned.
+        ctx.rewind_counts(counted_before);
         // Rebuild from the repaired projection, including released materialized inputs.
         let (repaired, remaining) = load_wallet_snapshot(&tx, wallet_id, ctx)?;
         if !remaining.is_empty() {
@@ -1847,12 +1851,7 @@ fn load_wallet_snapshot(
             key_wallet::account::account_collection::AccountCollection::new(),
         )
     } else {
-        build_wallet(network, wallet_id, &account_manifest).map_err(|e| {
-            PersistenceError::backend(format!(
-                "watch-only wallet rebuild failed for {}: {e}",
-                hex::encode(wallet_id)
-            ))
-        })?
+        build_wallet(network, wallet_id, &account_manifest).map_err(PersistenceError::from)?
     };
     // TODO(insert-wallet-id-recompute): confirm whether key_wallet's
     // insert_wallet recomputes wallet_id — see PR's existing Deferred
@@ -1864,9 +1863,23 @@ fn load_wallet_snapshot(
         &wallet,
         birth_height,
     );
+    // Pools come back first, so the used-address projection below marks the
+    // restored entries too: a stored row can still say "available" for an
+    // address that has since been funded. The platform-node reader stays
+    // ahead of `restore_pools` because it rewrites its entries' state from
+    // `used` alone, and `restore_pools` overlays their reservations.
+    if account_manifest
+        .provider
+        .iter()
+        .any(|entry| entry.account_type == key_wallet::account::AccountType::ProviderPlatformKeys)
+    {
+        restore_provider_platform_node_pool(&mut wallet_info, conn, &wallet_id, network, ctx)
+            .map_err(PersistenceError::from)?;
+    }
+    schema::core_pool::restore_pools(conn, &wallet_id, &wallet, &mut wallet_info, ctx)
+        .map_err(PersistenceError::from)?;
     // Provider key-material accounts hold no funds, so only the ECDSA
-    // half feeds the UTXO/balance projection here. The platform-node
-    // pre-derived-key pool is restored separately below.
+    // half feeds the UTXO/balance projection here.
     apply_persisted_core_state(
         &mut wallet_info,
         &account_manifest.ecdsa,
@@ -1875,25 +1888,7 @@ fn load_wallet_snapshot(
         &used_core_addresses,
         ctx,
     )
-    .map_err(|e| {
-        PersistenceError::backend(format!(
-            "core-state rehydration failed for {}: {e}",
-            hex::encode(wallet_id)
-        ))
-    })?;
-    if account_manifest
-        .provider
-        .iter()
-        .any(|entry| entry.account_type == key_wallet::account::AccountType::ProviderPlatformKeys)
-    {
-        restore_provider_platform_node_pool(&mut wallet_info, conn, &wallet_id, network, ctx)
-            .map_err(|e| {
-                PersistenceError::backend(format!(
-                    "platform-node pool rehydration failed for {}: {e}",
-                    hex::encode(wallet_id)
-                ))
-            })?;
-    }
+    .map_err(PersistenceError::from)?;
     let mut wallet = wallet;
     let sweeps = restore_recorded_transactions(
         &mut wallet_info,
@@ -1946,7 +1941,17 @@ fn record_wallet_degradation(
             wallet_id,
             cause: original.to_string(),
         },
-    )?;
+    )
+    // Strict: the caller propagates its original error, and a typed cause
+    // rarely names the wallet it came from, so this is where it is named.
+    .inspect_err(|_| {
+        tracing::error!(
+            wallet_id = %hex::encode(wallet_id),
+            error_kind = cause,
+            error = %original,
+            "strict load: a wallet could not be rebuilt, so the load fails"
+        );
+    })?;
     ctx.note_wallet_degraded(wallet_id, cause);
     Ok(())
 }

packages/rs-platform-wallet-storage/src/sqlite/rehydrate.rs

@@ -112,8 +112,8 @@ pub(crate) fn restore_provider_platform_node_pool(
         return Ok(());
     }
 
-    // TODO(#4188): `reserved_at` is persisted but deliberately not consumed here;
-    // restoring it requires widening `provider_accounts::insert_platform_node_pool_entry`.
+    // `reserved_at` is not consumed here: `core_pool::restore_pools` runs next
+    // and overlays each row's reservation state on the entries inserted below.
     for (index, script_bytes, public_key, used) in entries {
         let PublicKeyType::EdDSA(public_key) = public_key else {
             return Err(WalletStorageError::blob_decode(
@@ -1032,7 +1032,7 @@ fn owning_account_of(account: &ManagedCoreFundsAccount) -> OwningAccount {
 /// rescan to re-warm — generous enough to cover any realistic per-account
 /// derivation depth. The common (single funds account) path terminates at
 /// the true high-water mark well before this and never reaches the cap.
-const MAX_REHYDRATION_DERIVATION_INDEX: u32 = 10_000;
+pub(crate) const MAX_REHYDRATION_DERIVATION_INDEX: u32 = 10_000;
 
 /// Soft threshold past which a single chain's discovery scan is treated as
 /// abnormally deep and worth a `tracing::warn!`. Real funds chains anchor
@@ -1293,16 +1293,24 @@ fn extend_pools_for_restored_addresses(
         // reaches 50 and derives idx 45). A single mark-then-refill pass
         // would leave that address in the pool with `used = false`, handing
         // a previously-used address back out as fresh. Terminates: each
-        // round marks at least one new address from the finite restored set
-        // (`mark_used` returns `true` only on an unused→used flip).
+        // round after the first marks at least one new address from the
+        // finite restored set (`mark_used` returns `true` only on an
+        // unused→used flip).
+        //
+        // A pool restored from its stored rows enters with those entries
+        // already used, so no flip announces them. Its window is refilled
+        // once regardless, or the addresses past the stored rows would stay
+        // underived: unobserved, and a funded one among them never marked.
+        let mut restored_used = pool.highest_used.is_some();
         loop {
             let mut marked_any = false;
             for addr in restored_addresses {
                 if pool.mark_used(addr) {
                     marked_any = true;
                 }
             }
-            if !marked_any {
+            let refill_restored = std::mem::take(&mut restored_used);
+            if !marked_any && !refill_restored {
                 break;
             }
             // Refill the gap window past the deepest used index (needs the