fix(platform-wallet)!: persist chain truncations so a stored wallet follows a reorg

CHANGELOG.md

@@ -63,8 +63,18 @@
   [rust-dashcore#1183](https://github.com/dashpay/rust-dashcore/pull/1183)
   runs the storage writer only between start and stop.
 - **platform-wallet:** a chain reorganization reported by key-wallet
-  (`WalletEvent::ChainTruncated`) updates the in-memory balance but is not yet
-  mirrored to persisted wallet state
+  (`WalletEvent::ChainTruncated`) now reaches persisted wallet state as
+  `CoreChangeSet::truncations`. The SQLite backend and the Swift and Kotlin
+  persistence handlers remove the transactions of the dropped blocks and their
+  coins, keep InstantSend-locked ones as unconfirmed, restore the coins the
+  removed ones spent and lower the stored sync heights to the fork, so a
+  restart after a reorg loads the same wallet as no restart. FFI hosts receive
+  truncations through the size-negotiated
+  `on_persist_wallet_changeset_truncations_fn` extension callback, Kotlin
+  bridges through `onWalletChangesetChainTruncated`. A persister attests
+  support with the new
+  `PersistenceCapabilities::CORE_CHAIN_TRUNCATION` bit; one that does not is
+  not handed the truncation and keeps the replaced branch until it rescans
   ([#5380](https://github.com/dashpay/platform/issues/5380)).
 - **platform-wallet:** the SPV broadcast-readiness wait (`SpvRuntime::wait_until_ready`)
   wakes when the client starts or dash-spv reports a peer update, instead of

packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/ffi/NativePersistenceBridge.kt

@@ -99,6 +99,13 @@ abstract class NativePersistenceBridge {
          * it, so the declaration and the mirror can never drift apart.
          */
         const val CAPABILITY_CORE_SWEEP_REMOVAL: Long = 0x800
+
+        /**
+         * `PersistenceCapabilities::CORE_CHAIN_TRUNCATION` (bit 15,
+         * `0x8000`; bit 14 is reserved for Core history restore). The one Kotlin
+         * home of this bit, like [CAPABILITY_CORE_SWEEP_REMOVAL].
+         */
+        const val CAPABILITY_CORE_CHAIN_TRUNCATION: Long = 0x8000
     }
 
     /**
@@ -421,6 +428,47 @@ abstract class NativePersistenceBridge {
         winnerMinedHeight: Int,
     ): Int = 0
 
+    /**
+     * One chain truncation: a fork replaced the chain above [height] and
+     * the wallet dropped what it recorded from the blocks above it.
+     * Descriptor `([BI[BI[BI[BI)I`.
+     *
+     * [txids] packs [txidCount] raw 32-byte txids of removed transactions,
+     * [unconfirmedTxids] packs [unconfirmedTxidCount] txids of
+     * InstantSend-locked transactions kept as unconfirmed, and
+     * [restoredOutpoints] packs [restoredOutpointCount] 36-byte outpoint
+     * keys (raw txid followed by a little-endian vout) of coins the removed
+     * transactions spent.
+     *
+     * Fired before every other core callback of the round, once per
+     * truncation and in order: the rest of the round describes the wallet
+     * after the last one, so a removed transaction can be stored again, in
+     * its new block, by the callbacks that follow. Applying one means
+     * deleting every UTXO a removed transaction created for this wallet,
+     * and the transaction itself unless another wallet of the same store
+     * still has a part in it, keeping each unconfirmed one in the
+     * InstantSend context with no block and this wallet's outputs of it
+     * unconfirmed and InstantSend-locked, marking each restored outpoint
+     * unspent, and lowering a stored sync height above [height] to it. A
+     * transaction or outpoint never stored is a no-op.
+     *
+     * The JNI layer wires the slot only when the concrete bridge OVERRIDES
+     * this method, and Rust attests the capability only for slot present
+     * AND [CAPABILITY_CORE_CHAIN_TRUNCATION] declared through
+     * [persistenceCapabilitiesBits]. Without that, native never sends a
+     * truncation, so this default is never reached for a wired slot.
+     */
+    open fun onWalletChangesetChainTruncated(
+        walletId: ByteArray,
+        height: Int,
+        txids: ByteArray,
+        txidCount: Int,
+        unconfirmedTxids: ByteArray,
+        unconfirmedTxidCount: Int,
+        restoredOutpoints: ByteArray,
+        restoredOutpointCount: Int,
+    ): Int = 0
+
     /**
      * The round's numeric chainlock height, fired on every round whose
      * changeset carries a chainlock, after the changeset callback and

packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/persistence/PlatformWalletPersistenceHandler.kt

@@ -154,7 +154,8 @@ class PlatformWalletPersistenceHandler(
             CAPABILITY_WALLET_RESTORE or
             CAPABILITY_DPNS_NAME_STATES or
             CAPABILITY_TRACKED_ASSET_LOCKS or
-            CAPABILITY_CORE_SWEEP_REMOVAL
+            CAPABILITY_CORE_SWEEP_REMOVAL or
+            CAPABILITY_CORE_CHAIN_TRUNCATION
 
     /**
      * The single-thread executor created when no [dispatcher] is injected.
@@ -1282,6 +1283,85 @@ class PlatformWalletPersistenceHandler(
         return !chainlockOverIsLock
     }
 
+    // ── Chain truncations ─────────────────────────────────────────────
+
+    /** One chain truncation, unpacked from the JNI trampoline's flat arrays at the callback. */
+    private class ChainTruncation(
+        val height: Int,
+        val removedTxids: List<ByteArray>,
+        val unconfirmedTxids: List<ByteArray>,
+        val restoredOutpoints: List<ByteArray>,
+    )
+
+    /**
+     * Stage one chain truncation. Native fires this before the round's
+     * other core callbacks and the round replays its ops in order, so the
+     * truncation lands first and a transaction it removes can be stored
+     * again, in its new block, by the slices that follow. Outside a round
+     * it runs in its own transaction.
+     */
+    override fun onWalletChangesetChainTruncated(
+        walletId: ByteArray,
+        height: Int,
+        txids: ByteArray,
+        txidCount: Int,
+        unconfirmedTxids: ByteArray,
+        unconfirmedTxidCount: Int,
+        restoredOutpoints: ByteArray,
+        restoredOutpointCount: Int,
+    ): Int = guarded {
+        require(height >= 0) { "truncation height must not be negative" }
+        val truncation = ChainTruncation(
+            height = height,
+            removedTxids = unpackFixed(txids, txidCount, 32, "truncated txids"),
+            unconfirmedTxids = unpackFixed(unconfirmedTxids, unconfirmedTxidCount, 32, "unconfirmed txids"),
+            restoredOutpoints = unpackFixed(restoredOutpoints, restoredOutpointCount, 36, "restored outpoints"),
+        )
+        stage(walletId) { db -> applyChainTruncation(db, walletId, truncation) }
+        0
+    }
+
+    /**
+     * Cut the store back the way the wallet cut itself back when a fork
+     * replaced the chain above [ChainTruncation.height] — the Room mirror
+     * of the SQLite store's `apply_truncation`.
+     *
+     * Everything but the transaction row is this wallet's own. The row is
+     * shared across wallets and each wallet's round commits on its own, so
+     * another wallet may already have stored a removed transaction again,
+     * in its new block, by the time this truncation arrives: its coins are
+     * not this truncation's to take, and the row goes only once nothing
+     * references it. The row's block columns are the one thing wallets
+     * share; between two wallets' rounds they can show the branch the other
+     * wallet last wrote.
+     *
+     * A restored coin needs no veto from stored claims, unlike a sweep's
+     * release: its spender was confirmed, and no block the fork keeps can
+     * hold a second spend of it.
+     */
+    private suspend fun applyChainTruncation(db: DashDatabase, walletId: ByteArray, truncation: ChainTruncation) {
+        // Drop stale post-deletion callbacks (can't resurrect a wallet).
+        if (db.walletDao().getByWalletId(walletId) == null) return
+        // Removed: this wallet's coins, links, claims and involvement
+        // first, then the rows nothing references any more.
+        chunked(truncation.removedTxids) { db.txoDao().deleteWalletTxosByTxids(it, walletId) }
+        chunked(truncation.removedTxids) { db.txoDao().detachWalletSpenders(it, walletId) }
+        chunked(truncation.removedTxids) { db.documentDao().deleteWalletClaimsBySpenders(walletId, it) }
+        chunked(truncation.removedTxids) { db.transactionDao().deleteWalletInvolvements(it, walletId) }
+        chunked(truncation.removedTxids) { db.transactionDao().deleteUnreferencedByTxids(it) }
+        // Kept: InstantSend-locked, so mined again. Stored until then the
+        // way a locked transaction no block holds yet is; the coins they
+        // spent stay spent.
+        chunked(truncation.unconfirmedTxids) { db.transactionDao().unconfirmByTxids(it) }
+        chunked(truncation.unconfirmedTxids) { db.txoDao().unconfirmInstantLockedByTxids(it, walletId) }
+        // Restored: this wallet's coins the removed transactions spent.
+        chunked(truncation.restoredOutpoints) { db.txoDao().releaseByOutpoints(it, walletId) }
+        chunked(truncation.restoredOutpoints) {
+            db.documentDao().deleteWalletSweptTombstonesByOutpoints(walletId, it)
+        }
+        db.walletDao().lowerSyncedHeight(walletId, truncation.height, System.currentTimeMillis())
+    }
+
     // ── Sweeps ────────────────────────────────────────────────────────
 
     /** One sweep batch, unpacked from the JNI trampoline's flat arrays at the callback. */
@@ -4120,6 +4200,8 @@ class PlatformWalletPersistenceHandler(
 
         internal const val CAPABILITY_CORE_SWEEP_REMOVAL: Long =
             NativePersistenceBridge.CAPABILITY_CORE_SWEEP_REMOVAL
+        internal const val CAPABILITY_CORE_CHAIN_TRUNCATION: Long =
+            NativePersistenceBridge.CAPABILITY_CORE_CHAIN_TRUNCATION
 
         private const val TAG = "DashPersistence"
 

packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/persistence/dao/DocumentDao.kt

@@ -254,6 +254,18 @@ interface DocumentDao {
     )
     suspend fun deleteWalletSweptTombstonesByOutpoints(walletId: ByteArray, outpoints: List<ByteArray>)
 
+    /**
+     * Delete [walletId]'s ordinary claims made by one of [spendingTxids] —
+     * its spend-before-funding rows for transactions a chain truncation
+     * removed. Tombstones are not claims of the removed transaction and
+     * stay. Chunked by the caller.
+     */
+    @Query(
+        "DELETE FROM pending_inputs WHERE walletId = :walletId AND isSweptTombstone = 0 " +
+            "AND spendingTransactionTxid IN (:spendingTxids)",
+    )
+    suspend fun deleteWalletClaimsBySpenders(walletId: ByteArray, spendingTxids: List<ByteArray>)
+
     /** Bulk insert of freshly minted tombstones; Room binds one row at a time. */
     @Insert
     suspend fun insertPendingInputs(rows: List<PendingInputEntity>)

packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/persistence/dao/TransactionDao.kt

@@ -111,6 +111,46 @@ interface TransactionDao {
     @Query("DELETE FROM transactions WHERE txid IN (:txids)")
     suspend fun deleteByTxids(txids: List<ByteArray>)
 
+    /**
+     * Drop [walletId]'s accounts' involvement in [txids] — its part in
+     * transactions a chain truncation removed. Chunked by the caller.
+     */
+    @Query(
+        "DELETE FROM transaction_account_involvements WHERE transactionTxid IN (:txids) " +
+            "AND accountId IN (SELECT id FROM accounts WHERE walletId = :walletId)"
+    )
+    suspend fun deleteWalletInvolvements(txids: List<ByteArray>, walletId: ByteArray)
+
+    /**
+     * Delete those of [txids] nothing references any more — the same test
+     * as [deleteOrphanTransactions], limited to the transactions one chain
+     * truncation removed. A row another wallet still has a coin, a spend,
+     * a claim or an involvement in stays. Chunked by the caller.
+     */
+    @Query(
+        "DELETE FROM transactions WHERE txid IN (:txids) " +
+            "AND txid NOT IN (SELECT txid FROM txos WHERE txid IS NOT NULL) " +
+            "AND txid NOT IN (SELECT spendingTxid FROM txos WHERE spendingTxid IS NOT NULL) " +
+            "AND txid NOT IN " +
+            "(SELECT spendingTransactionTxid FROM pending_inputs " +
+            "WHERE spendingTransactionTxid IS NOT NULL) " +
+            "AND txid NOT IN (SELECT transactionTxid FROM transaction_account_involvements)"
+    )
+    suspend fun deleteUnreferencedByTxids(txids: List<ByteArray>)
+
+    /**
+     * Keep [txids] as unconfirmed and InstantSend-locked: a chain
+     * truncation dropped their block, and it keeps no other kind. Sets the
+     * InstantSend context, clears the block columns and touches nothing
+     * else. Chunked by the caller.
+     */
+    @Query(
+        "UPDATE transactions SET context = 1, blockHeight = 0, blockHash = NULL, " +
+            "blockTimestamp = 0, blockPosition = 0, hasBlockPosition = 0 " +
+            "WHERE txid IN (:txids)"
+    )
+    suspend fun unconfirmByTxids(txids: List<ByteArray>)
+
     /**
      * Orphan sweep run after a wallet wipe (Swift `deleteWalletData`'s
      * post-delete pass): drop transactions no longer referenced by any

packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/persistence/dao/TxoDao.kt

@@ -166,6 +166,39 @@ interface TxoDao {
     @Query("DELETE FROM txos WHERE txid IN (:txids)")
     suspend fun deleteByTxids(txids: List<ByteArray>)
 
+    /**
+     * Delete [walletId]'s TXOs created by one of [txids] — its own coins
+     * from transactions a chain truncation removed. Another wallet's coins
+     * from the same transactions are not this wallet's truncation to take:
+     * that wallet's round may already have stored them again, in their new
+     * block. Chunked by the caller.
+     */
+    @Query("DELETE FROM txos WHERE txid IN (:txids) AND walletId = :walletId")
+    suspend fun deleteWalletTxosByTxids(txids: List<ByteArray>, walletId: ByteArray)
+
+    /**
+     * Drop [walletId]'s links to one of [spendingTxids] — the wallet-scoped
+     * form of [detachSpenders], for a chain truncation. Chunked by the
+     * caller.
+     */
+    @Query(
+        "UPDATE txos SET spendingTxid = NULL, spendingInputIndex = NULL " +
+            "WHERE spendingTxid IN (:spendingTxids) AND walletId = :walletId",
+    )
+    suspend fun detachWalletSpenders(spendingTxids: List<ByteArray>, walletId: ByteArray)
+
+    /**
+     * Mark [walletId]'s TXOs created by one of [txids] unconfirmed and
+     * InstantSend-locked — its outputs of transactions a chain truncation
+     * kept after dropping their block. Spend state is not touched, nor are
+     * another wallet's outputs. Chunked by the caller.
+     */
+    @Query(
+        "UPDATE txos SET isConfirmed = 0, isInstantLocked = 1, height = 0 " +
+            "WHERE txid IN (:txids) AND walletId = :walletId",
+    )
+    suspend fun unconfirmInstantLockedByTxids(txids: List<ByteArray>, walletId: ByteArray)
+
     /**
      * Delete the rows at [outpoints] outright — outputs of a transaction
      * swept in this round that some loser claimed or some release named.

packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/persistence/dao/WalletDao.kt

@@ -78,6 +78,21 @@ interface WalletDao {
     )
     suspend fun advanceChainLockHeight(walletId: ByteArray, height: Int, nowMillis: Long): Int
 
+    /**
+     * Lower the stored synced height to [height] when it is above it — a
+     * chain truncation at [height]. Never raises it, and a narrow column
+     * write for the same reason as [advanceChainLockHeight].
+     *
+     * @param nowMillis epoch millis for the `lastUpdated` stamp.
+     * @return number of rows updated (0 when the wallet row is gone or its
+     *   height is already at or below [height]).
+     */
+    @Query(
+        "UPDATE wallets SET syncedHeight = :height, lastUpdated = :nowMillis " +
+            "WHERE walletId = :walletId AND syncedHeight > :height"
+    )
+    suspend fun lowerSyncedHeight(walletId: ByteArray, height: Int, nowMillis: Long): Int
+
     @Delete
     suspend fun delete(wallet: WalletEntity)
 

packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/wallet/PlatformWalletManager.kt

@@ -77,6 +77,13 @@ data class PlatformWalletPersistenceCapabilities(
          * is deliberately absent: Android never attests it).
          */
         const val CORE_SWEEP_REMOVAL: Long = NativePersistenceBridge.CAPABILITY_CORE_SWEEP_REMOVAL
+        /**
+         * A stored core changeset's chain truncations are durably applied
+         * before the rest of their round. Mirrors
+         * `PersistenceCapabilities::CORE_CHAIN_TRUNCATION`; aliased to the
+         * bridge's declaration like [CORE_SWEEP_REMOVAL].
+         */
+        const val CORE_CHAIN_TRUNCATION: Long = NativePersistenceBridge.CAPABILITY_CORE_CHAIN_TRUNCATION
     }
 }