feat(platform-wallet)!: report a freshly built asset lock's outpoint to the caller

packages/rs-platform-wallet-ffi/src/asset_lock/built_callback.rs

@@ -0,0 +1,109 @@
+//! C callback that reports the outpoint of a newly built asset lock.
+
+use std::os::raw::c_void;
+
+use dashcore::OutPoint;
+use platform_wallet::wallet::asset_lock::AssetLockBuiltObserver;
+
+use crate::asset_lock_persistence::outpoint_to_bytes;
+
+/// Receives the outpoint of an asset lock that a funding call has just
+/// built, before the lock's row is persisted or the lock is broadcast.
+///
+/// `out_point_36` points to 36 bytes (32-byte raw txid followed by the
+/// 4-byte little-endian vout, the layout of `AssetLockEntryFFI.out_point`)
+/// and is valid only for the duration of the call. The callback runs
+/// synchronously on the funding call's worker thread, at most once per
+/// call, and must return promptly without calling back into the wallet.
+/// Record the outpoint before returning: the lock's row is persisted right
+/// after. The funding call's result then tells what happened to the lock:
+/// `ErrorTransactionBroadcastRejected` (26) means it was removed again; any
+/// other failure leaves it tracked and resumable by this outpoint.
+/// `NULL` means no callback.
+pub type AssetLockBuiltFn =
+    Option<unsafe extern "C" fn(context: *mut c_void, out_point_36: *const u8)>;
+
+/// A caller-supplied [`AssetLockBuiltFn`] with its opaque context.
+///
+/// The context is held as `usize` so the funding future that captures it
+/// stays `Send + 'static`; the caller's contract keeps it valid for the
+/// whole (blocking) FFI call.
+#[derive(Clone, Copy)]
+pub(crate) struct AssetLockBuiltCallback {
+    func: unsafe extern "C" fn(context: *mut c_void, out_point_36: *const u8),
+    context: usize,
+}
+
+impl AssetLockBuiltCallback {
+    /// `None` when the caller passed no callback.
+    pub(crate) fn new(func: AssetLockBuiltFn, context: *mut c_void) -> Option<Self> {
+        func.map(|func| Self {
+            func,
+            context: context as usize,
+        })
+    }
+
+    /// The callback as the observer the funding paths take.
+    pub(crate) fn into_observer(self) -> impl Fn(OutPoint) + Send + Sync {
+        move |out_point| self.notify(out_point)
+    }
+
+    fn notify(&self, out_point: OutPoint) {
+        let bytes = outpoint_to_bytes(&out_point);
+        // SAFETY: the caller guarantees `func` and `context` stay valid for
+        // the duration of the FFI call this callback belongs to, and `bytes`
+        // outlives the call below.
+        unsafe { (self.func)(self.context as *mut c_void, bytes.as_ptr()) }
+    }
+}
+
+/// `on_built` as the optional observer reference the funding paths take.
+pub(crate) fn observer_ref<F>(on_built: &Option<F>) -> Option<&AssetLockBuiltObserver<'_>>
+where
+    F: Fn(OutPoint) + Send + Sync,
+{
+    on_built
+        .as_ref()
+        .map(|notify| notify as &AssetLockBuiltObserver<'_>)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use dashcore::hashes::Hash;
+    use dashcore::Txid;
+    use std::sync::Mutex;
+
+    /// Appends the reported outpoint to the `Mutex<Vec<[u8; 36]>>` the
+    /// context points to.
+    unsafe extern "C" fn record(context: *mut c_void, out_point_36: *const u8) {
+        let received = &*(context as *const Mutex<Vec<[u8; 36]>>);
+        let mut bytes = [0u8; 36];
+        std::ptr::copy_nonoverlapping(out_point_36, bytes.as_mut_ptr(), 36);
+        received.lock().unwrap().push(bytes);
+    }
+
+    #[test]
+    fn should_yield_no_callback_for_an_absent_function() {
+        assert!(AssetLockBuiltCallback::new(None, std::ptr::null_mut()).is_none());
+    }
+
+    #[test]
+    fn should_pass_the_context_and_the_entry_layout_outpoint() {
+        let received = Mutex::new(Vec::new());
+        let out_point = OutPoint::new(Txid::from_byte_array([7; 32]), 3);
+        let callback = AssetLockBuiltCallback::new(
+            Some(record),
+            &received as *const Mutex<Vec<[u8; 36]>> as *mut c_void,
+        )
+        .expect("callback present");
+
+        let on_built = Some(callback.into_observer());
+        observer_ref(&on_built).expect("observer present")(out_point);
+
+        assert_eq!(
+            received.into_inner().unwrap(),
+            vec![outpoint_to_bytes(&out_point)]
+        );
+    }
+}

packages/rs-platform-wallet-ffi/src/asset_lock/mod.rs

@@ -3,9 +3,12 @@
 //! Mirrors the structure of `platform_wallet::wallet::asset_lock`.
 
 mod build;
+mod built_callback;
 mod manager;
 mod sync;
 
 pub use build::*;
+pub use built_callback::AssetLockBuiltFn;
+pub(crate) use built_callback::{observer_ref, AssetLockBuiltCallback};
 pub use manager::*;
 pub use sync::*;

packages/rs-platform-wallet-ffi/src/platform_addresses/fund_from_asset_lock.rs

@@ -15,12 +15,14 @@
 //! resuming a tracked asset lock by outpoint (crash-recovery shape).
 
 use std::collections::BTreeMap;
+use std::os::raw::c_void;
 
 use dashcore::hashes::Hash;
 use dpp::address_funds::PlatformAddress;
 use platform_wallet::wallet::asset_lock::AssetLockFunding;
 use rs_sdk_ffi::{MnemonicResolverCoreSigner, MnemonicResolverHandle, SignerHandle, VTableSigner};
 
+use crate::asset_lock::{observer_ref, AssetLockBuiltCallback, AssetLockBuiltFn};
 use crate::check_ptr;
 use crate::core_wallet_types::OutPointFFI;
 use crate::error::*;
@@ -65,6 +67,10 @@ use crate::{unwrap_option_or_return, unwrap_result_or_return};
 ///   `*mut MnemonicResolverHandle` produced by
 ///   [`crate::dash_sdk_mnemonic_resolver_create`]. The caller retains
 ///   ownership.
+/// - `on_asset_lock_built`, when non-null, must be a valid C function
+///   pointer for the duration of the call; `on_asset_lock_built_context`
+///   is passed to it opaquely and must remain valid for the duration of the
+///   call (or be null). See [`AssetLockBuiltFn`] for its contract.
 #[no_mangle]
 #[allow(clippy::too_many_arguments)]
 pub unsafe extern "C" fn platform_address_wallet_fund_from_asset_lock_signer(
@@ -79,6 +85,8 @@ pub unsafe extern "C" fn platform_address_wallet_fund_from_asset_lock_signer(
     signer_address_handle: *mut SignerHandle,
     core_signer_handle: *mut MnemonicResolverHandle,
     out_changeset: *mut PlatformAddressChangeSetFFI,
+    on_asset_lock_built: AssetLockBuiltFn,
+    on_asset_lock_built_context: *mut c_void,
 ) -> PlatformWalletFFIResult {
     check_ptr!(out_changeset);
     // Sentinel first: address decoding, the wallet lookup, and the async
@@ -98,6 +106,8 @@ pub unsafe extern "C" fn platform_address_wallet_fund_from_asset_lock_signer(
     // capture is `Send + 'static` (raw pointers are `!Send`).
     let signer_addr = signer_address_handle as usize;
     let core_signer_addr = core_signer_handle as usize;
+    let built_callback =
+        AssetLockBuiltCallback::new(on_asset_lock_built, on_asset_lock_built_context);
 
     let option = PLATFORM_ADDRESS_WALLET_STORAGE.with_item(handle, |wallet| {
         let wallet_clone = wallet.clone();
@@ -117,6 +127,7 @@ pub unsafe extern "C" fn platform_address_wallet_fund_from_asset_lock_signer(
                     network,
                 )
             };
+            let on_built = built_callback.map(AssetLockBuiltCallback::into_observer);
             wallet_clone
                 .fund_from_asset_lock(
                     AssetLockFunding::FromWalletBalance {
@@ -132,6 +143,7 @@ pub unsafe extern "C" fn platform_address_wallet_fund_from_asset_lock_signer(
                     address_signer,
                     &asset_lock_signer,
                     None,
+                    observer_ref(&on_built),
                 )
                 .await
         })
@@ -242,6 +254,8 @@ pub unsafe extern "C" fn platform_address_wallet_resume_fund_from_asset_lock_sig
                     address_signer,
                     &asset_lock_signer,
                     None,
+                    // A resume builds no new lock.
+                    None,
                 )
                 .await
         })
@@ -365,6 +379,10 @@ pub(super) unsafe fn decode_funding_addresses(
 /// - `handle` must be a live `PlatformAddressWallet` handle; a stale or
 ///   already-destroyed one is rejected by the handle table rather than
 ///   dereferenced.
+/// - `on_asset_lock_built`, when non-null, must be a valid C function
+///   pointer for the duration of the call; `on_asset_lock_built_context`
+///   is passed to it opaquely and must remain valid for the duration of the
+///   call (or be null). See [`AssetLockBuiltFn`] for its contract.
 #[no_mangle]
 #[allow(clippy::too_many_arguments)]
 pub unsafe extern "C" fn platform_address_wallet_fund_from_asset_lock_external_signer(
@@ -379,6 +397,8 @@ pub unsafe extern "C" fn platform_address_wallet_fund_from_asset_lock_external_s
     signer_address_handle: *mut SignerHandle,
     core_signer_handle: *mut MnemonicResolverHandle,
     out_changeset: *mut PlatformAddressChangeSetFFI,
+    on_asset_lock_built: AssetLockBuiltFn,
+    on_asset_lock_built_context: *mut c_void,
 ) -> PlatformWalletFFIResult {
     check_ptr!(out_changeset);
     // Sentinel first — see `platform_address_wallet_fund_from_asset_lock_signer`.
@@ -394,6 +414,8 @@ pub unsafe extern "C" fn platform_address_wallet_fund_from_asset_lock_external_s
 
     let signer_addr = signer_address_handle as usize;
     let core_signer_addr = core_signer_handle as usize;
+    let built_callback =
+        AssetLockBuiltCallback::new(on_asset_lock_built, on_asset_lock_built_context);
 
     let option = PLATFORM_ADDRESS_WALLET_STORAGE.with_item(handle, |wallet| {
         let wallet_clone = wallet.clone();
@@ -410,6 +432,7 @@ pub unsafe extern "C" fn platform_address_wallet_fund_from_asset_lock_external_s
                     network,
                 )
             };
+            let on_built = built_callback.map(AssetLockBuiltCallback::into_observer);
             wallet_clone
                 .fund_from_asset_lock_external(
                     AssetLockFunding::FromWalletBalance {
@@ -421,6 +444,7 @@ pub unsafe extern "C" fn platform_address_wallet_fund_from_asset_lock_external_s
                     address_signer,
                     &asset_lock_signer,
                     None,
+                    observer_ref(&on_built),
                 )
                 .await
         })
@@ -573,6 +597,8 @@ pub unsafe extern "C" fn platform_address_wallet_resume_fund_from_asset_lock_ext
                     address_signer,
                     &asset_lock_signer,
                     None,
+                    // A resume builds no new lock.
+                    None,
                 )
                 .await
         })