@@ -76,14 +76,14 @@ pub struct CoreAddressEntryFFI {
     pub pool_type_tag: u8,
     /// Derivation index within this pool.
     pub address_index: u32,
-    /// Whether funds had been seen at this address at emit time, i.e.
-    /// `AddressInfo.state == AddressState::Used`.
+    /// Whether the address must not be handed out again: funds were seen
+    /// at it (`AddressState::Used`), or it is reserved
+    /// (`AddressState::Reserved`).
     ///
-    /// This schema has no slot for a reservation, so an
-    /// `AddressState::Reserved` entry necessarily flattens to `false`
-    /// and reloads as `Available`. Nothing in platform reserves
-    /// addresses today, so that lossy case is unreachable; adding a
-    /// reserving caller requires a schema decision here first (see
+    /// This schema has no slot for a reservation, and the row is a reuse
+    /// guard, so a reservation is stored as `true` and reloads as `Used`.
+    /// Releasing it stores `false` again. The one reserving caller is the
+    /// two-step DashPay contact payment (see
     /// `persistence::build_core_address_entry_ffi`).
     pub is_used: bool,
     /// Cached balance in duffs from `AddressInfo.balance`.
 
@@ -1656,6 +1656,109 @@ mod tests {
         );
     }
 
+    /// Prepare rejects each null required pointer with `ErrorNullPointer`
+    /// before any wallet lookup, and publishes no payment handle.
+    #[test]
+    fn prepare_dashpay_payment_null_pointers_are_rejected() {
+        let id = [0u8; 32];
+        let dummy_signer = std::ptr::dangling_mut::<MnemonicResolverHandle>();
+        let mut payment: Handle = 0x5EED;
+        let mut fee: u64 = 0;
+        let mut total: u64 = 0;
+        let cases: [(*mut MnemonicResolverHandle, *mut Handle, *mut u64, *mut u64); 4] = [
+            (std::ptr::null_mut(), &mut payment, &mut fee, &mut total),
+            (dummy_signer, std::ptr::null_mut(), &mut fee, &mut total),
+            (dummy_signer, &mut payment, std::ptr::null_mut(), &mut total),
+            (dummy_signer, &mut payment, &mut fee, std::ptr::null_mut()),
+        ];
+        for (signer, out_payment, out_fee, out_total) in cases {
+            let r = unsafe {
+                platform_wallet_prepare_dashpay_payment(
+                    1,
+                    id.as_ptr(),
+                    id.as_ptr(),
+                    1_000,
+                    std::ptr::null(),
+                    signer,
+                    out_payment,
+                    out_fee,
+                    out_total,
+                )
+            };
+            assert_eq!(r.code, PlatformWalletFFIResultCode::ErrorNullPointer);
+        }
+        assert_eq!(payment, 0x5EED, "no handle is written on a pointer failure");
+    }
+
+    /// An unknown wallet fails the prepare and leaves `*out_payment` at the
+    /// null handle, so a caller can never mistake a failure for a payment.
+    #[test]
+    fn prepare_dashpay_payment_unknown_wallet_publishes_no_handle() {
+        let id = [0u8; 32];
+        let dummy_signer = std::ptr::dangling_mut::<MnemonicResolverHandle>();
+        let mut payment: Handle = 0x5EED;
+        let mut fee: u64 = 7;
+        let mut total: u64 = 7;
+        let r = unsafe {
+            platform_wallet_prepare_dashpay_payment(
+                0xDEAD_BEEF,
+                id.as_ptr(),
+                id.as_ptr(),
+                1_000,
+                std::ptr::null(),
+                dummy_signer,
+                &mut payment,
+                &mut fee,
+                &mut total,
+            )
+        };
+        assert_eq!(r.code, PlatformWalletFFIResultCode::NotFound);
+        assert_eq!(payment, NULL_HANDLE);
+        assert_eq!(
+            (fee, total),
+            (7, 7),
+            "fee and total are written only on success"
+        );
+    }
+
+    /// Send, abandon and free with a payment handle that is not (or no
+    /// longer) held: send and abandon report `NotFound` without touching the
+    /// outputs, and free stays a no-op however often it is called.
+    #[test]
+    fn prepared_payment_unknown_handle_is_consumed_nowhere() {
+        let mut txid = [0xAAu8; 32];
+        let mut fee: u64 = 7;
+        let r = unsafe {
+            platform_wallet_send_prepared_dashpay_payment(
+                0xDEAD_BEEF,
+                0xDEAD_BEEF,
+                &mut txid,
+                &mut fee,
+            )
+        };
+        assert_eq!(r.code, PlatformWalletFFIResultCode::NotFound);
+        assert_eq!(txid, [0xAAu8; 32]);
+        assert_eq!(fee, 7);
+
+        // A null `out_txid` with a handle that is not held is still a lookup
+        // miss: nothing to abandon, nothing written.
+        let r = unsafe {
+            platform_wallet_send_prepared_dashpay_payment(
+                0xDEAD_BEEF,
+                0xDEAD_BEEF,
+                std::ptr::null_mut(),
+                std::ptr::null_mut(),
+            )
+        };
+        assert_eq!(r.code, PlatformWalletFFIResultCode::NotFound);
+
+        for _ in 0..2 {
+            let r = platform_wallet_abandon_prepared_dashpay_payment(0xDEAD_BEEF);
+            assert_eq!(r.code, PlatformWalletFFIResultCode::NotFound);
+            platform_wallet_prepared_dashpay_payment_free(0xDEAD_BEEF);
+        }
+    }
+
     /// A null `out_count` is rejected with `ErrorNullPointer` (the `check_ptr!`
     /// contract) before any wallet lookup.
     #[test]
 
@@ -4452,26 +4452,15 @@ fn build_core_address_entry_ffi(
         pool_type_tag,
         address_index: info.index,
         // `CoreAddressEntryFFI` carries a single `is_used` bool with no
-        // slot for a reservation, so `Reserved` can only flatten to
-        // `false` and would reload as `Available` — silently returning a
-        // handed-out address to the pool. Nothing in platform reserves
-        // addresses (no caller of `next_receive_address_and_reserve` /
-        // `next_unused_and_reserve` in the workspace), so that arm is
-        // unreachable today. It is spelled out rather than folded into a
-        // catch-all so the first reserving caller shows up as an explicit
-        // schema decision instead of losing state on the next reload.
+        // slot for a reservation. The row is a reuse guard, so `Reserved`
+        // flattens to `true`: a handed-out address must not be handed out
+        // again after a reload. Its release is a later `Available` row,
+        // stored as `false`, which the host applies as written. The one
+        // reserving caller is the two-step DashPay contact payment, which
+        // reserves the contact address for the length of its send.
         is_used: match info.state {
-            AddressState::Used => true,
+            AddressState::Used | AddressState::Reserved { .. } => true,
             AddressState::Available => false,
-            AddressState::Reserved { .. } => {
-                tracing::warn!(
-                    index = info.index,
-                    "persist: address pool entry is reserved, but the persisted \
-                     address schema cannot represent a reservation; it will \
-                     reload as available and may be handed out again"
-                );
-                false
-            }
         },
         balance: info.balance,
         address_base58: address_ptr,
@@ -4569,8 +4558,8 @@ unsafe fn address_info_from_ffi(
         index: entry.address_index,
         path,
         // The persisted entry only carries `is_used`, so state round-trips
-        // to `Used`/`Available`; a `Reserved` entry is not representable —
-        // see `build_core_address_entry_ffi`.
+        // to `Used`/`Available`; a `Reserved` entry is stored as used and
+        // reloads `Used` — see `build_core_address_entry_ffi`.
         state: if entry.is_used {
             AddressState::Used
         } else {
@@ -9608,21 +9597,19 @@ mod tests {
 
     /// Pin what the persisted address row does to `AddressState`.
     /// `CoreAddressEntryFFI` carries a single `is_used` bool, so only
-    /// `Used` and `Available` survive a save/load cycle intact;
-    /// `Reserved { .. }` has no representation and comes back
-    /// `Available`, i.e. a reload silently frees a handed-out address.
-    /// Nothing in platform reserves addresses today, so this records the
-    /// boundary rather than a live bug: if a reserving caller is ever
-    /// added, this test is where the schema decision (a dedicated
-    /// reservation field on the row) has to be made.
+    /// `Used` and `Available` survive a save/load cycle intact.
+    /// `Reserved { .. }` flattens to used: the row is a reuse guard, and a
+    /// reload must never hand out an address that was handed out (the
+    /// two-step DashPay contact payment reserves its address across the
+    /// broadcast). A released reservation is stored as `Available`.
     #[test]
     fn address_state_round_trip_keeps_used_and_flattens_reserved() {
         for (state, expected) in [
             (AddressState::Available, AddressState::Available),
             (AddressState::Used, AddressState::Used),
             (
                 AddressState::Reserved { at: 1_700_000_000 },
-                AddressState::Available,
+                AddressState::Used,
             ),
         ] {
             let mut info = typed_key_test_address_info(11, None);
 
@@ -351,6 +351,86 @@ fn used_address_cannot_regain_reservation_from_stale_snapshot() {
     assert_eq!(state, (1, None));
 }
 
+/// A reservation is a claim the backend can take back: storing the address
+/// available again clears it, while storing it used makes it final. This is
+/// what a two-step contact payment relies on to release the address of a
+/// send that never reached the network, which a `used` flag (monotonic, MAX)
+/// could not express.
+#[test]
+fn reservation_can_be_released_or_promoted_to_used() {
+    let (persister, _tmp, _path) = fresh_persister();
+    let w: WalletId = wid(0xB3);
+    ensure_wallet_meta(&persister, &w);
+    let account_type = AccountType::Standard {
+        index: 0,
+        standard_account_type: StandardAccountType::BIP44Account,
+    };
+    let mut infos = external_infos(0xB3);
+    infos.truncate(2);
+    let store = |infos: Vec<AddressInfo>| {
+        persister
+            .store(
+                w,
+                PlatformWalletChangeSet {
+                    account_address_pools: vec![pool_entry(
+                        account_type,
+                        AddressPoolType::External,
+                        infos,
+                    )],
+                    ..Default::default()
+                },
+            )
+            .unwrap();
+    };
+
+    // Both reserved, as a send stores them before its broadcast.
+    for info in &mut infos {
+        info.state = AddressState::Reserved { at: 1_752_528_625 };
+    }
+    store(infos.clone());
+    // Index 0: rejected — released. Index 1: sent — used.
+    infos[0].state = AddressState::Available;
+    infos[1].state = AddressState::Used;
+    let (released, sent) = (infos[0].address.clone(), infos[1].address.clone());
+    store(infos);
+
+    // What a reload restores as used — the loader `load()` rehydrates the
+    // pool from: the sent address, never the released one.
+    {
+        let conn = persister.lock_conn_for_test();
+        let reloaded: Vec<_> = core_pool::load_used_addresses(&conn, &w, Network::Testnet)
+            .unwrap()
+            .into_iter()
+            .map(|(address, _)| address)
+            .collect();
+        assert_eq!(
+            reloaded,
+            vec![sent],
+            "released {released} must reload available"
+        );
+    }
+
+    let conn = persister.lock_conn_for_test();
+    let mut stmt = conn
+        .prepare(
+            "SELECT used, reserved_at FROM core_address_pool \
+             WHERE wallet_id = ?1 ORDER BY address_index",
+        )
+        .unwrap();
+    let rows = stmt
+        .query_map(rusqlite::params![w.as_slice()], |row| {
+            Ok((row.get::<_, i64>(0)?, row.get::<_, Option<i64>>(1)?))
+        })
+        .unwrap()
+        .collect::<Result<Vec<_>, _>>()
+        .unwrap();
+    assert_eq!(
+        rows,
+        vec![(0, None), (1, None)],
+        "the released address is available on disk, the sent one used"
+    );
+}
+
 /// UTXOs resolve to their pool-declared account during reads.
 #[test]
 fn account_index_is_resolved_from_pool() {