diff --git a/Cargo.lock b/Cargo.lock index 3dd3b403830..aeb07e29ee7 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -5292,6 +5292,7 @@ dependencies = [ "image", "key-wallet", "key-wallet-manager", + "libc", "log", "platform-encryption", "rand 0.8.6", diff --git a/packages/rs-platform-wallet-ffi/src/shielded_send.rs b/packages/rs-platform-wallet-ffi/src/shielded_send.rs index 1b7628baedb..a34ad0b8c7c 100644 --- a/packages/rs-platform-wallet-ffi/src/shielded_send.rs +++ b/packages/rs-platform-wallet-ffi/src/shielded_send.rs @@ -32,9 +32,10 @@ //! crosses the FFI boundary. //! //! Feature-gated behind `shielded`. The accompanying -//! [`platform_wallet_shielded_warm_up_prover`] entry-point is -//! also defined here so hosts can pre-build the Halo 2 proving -//! key on a background thread at app startup. +//! [`platform_wallet_shielded_warm_up_prover`] (fire-and-forget) and +//! [`platform_wallet_shielded_prepare_prover`] (blocks until ready) +//! entry-points are also defined here so hosts can pre-build the +//! Halo 2 proving key at app startup. //! //! [`ShieldedWallet`]: platform_wallet::wallet::shielded::ShieldedWallet //! [`ShieldedWallet::shield`]: platform_wallet::wallet::shielded::ShieldedWallet::shield @@ -136,28 +137,62 @@ unsafe fn parse_required_platform_address( } } -/// Kick off the Halo 2 proving-key build on a background tokio -/// worker if it hasn't been built yet. Returns immediately — -/// hosts can call this at app startup without blocking the UI -/// thread. Subsequent calls are cheap no-ops once the key is -/// cached. The first shielded send still pays the ~30 s build -/// cost only if it fires before the warm-up worker finishes; -/// `platform_wallet_shielded_prover_is_ready` reports whether -/// that's the case. -/// -/// Independent of any manager — the cache is a process-global -/// `OnceLock`. +/// Kick off the Halo 2 proving-key build in the background if it +/// hasn't been built yet. Returns immediately — hosts can call this +/// at app startup without blocking the UI thread. Subsequent calls +/// are cheap no-ops once the key is cached. +/// +/// The build runs on the runtime's blocking pool and is shared with +/// every other preparation: a shielded send (or +/// [`platform_wallet_shielded_prepare_prover`]) that starts while it +/// is running waits only for the remaining build time. +/// `platform_wallet_shielded_prover_is_ready` reports whether it has +/// finished. +/// +/// Independent of any manager — the cache is process-global. #[no_mangle] pub unsafe extern "C" fn platform_wallet_shielded_warm_up_prover() { - runtime().spawn_blocking(|| CachedOrchardProver::new().warm_up()); + runtime().spawn(async { + // A failed build leaves the cache empty; the next preparation + // (or send) retries and reports the error. + let _ = CachedOrchardProver::prepare().await; + }); +} + +/// Block the calling thread until the Halo 2 proving key is built, +/// starting the build if nobody has yet. Returns immediately if the key +/// is already cached. +/// +/// Shares the single process-wide build with +/// [`platform_wallet_shielded_warm_up_prover`] and with shielded sends, +/// so calling it while a warm-up is running waits only for the +/// remainder. The build runs on the runtime's blocking pool; the calling +/// thread just parks. Call it off the main thread (e.g. from a +/// background dispatch queue) to learn when the prover is ready. +/// +/// Returns an error only if the build panicked or the runtime is +/// shutting down; the cache then stays empty and a later call retries. +#[no_mangle] +pub unsafe extern "C" fn platform_wallet_shielded_prepare_prover() -> PlatformWalletFFIResult { + // Preparation spends nothing, so a panic in the runtime bridge is a + // definitive failure rather than an ambiguous spend outcome. + catch_panic_to_code( + "shielded prover preparation", + PlatformWalletFFIResultCode::ErrorWalletOperation, + "No spend was broadcast.", + || match block_on_worker(CachedOrchardProver::prepare()) { + Ok(()) => PlatformWalletFFIResult::ok(), + Err(e) => e.into(), + }, + ) } /// Whether the Halo 2 proving key has already been built. /// /// Useful as a UI indicator ("preparing prover…") before the /// first shielded send. `false` doesn't mean shielded sends will -/// fail — it just means the next one will pay the ~30s build -/// cost up front. +/// fail — it just means the next one will wait for the build to +/// finish first. #[no_mangle] pub unsafe extern "C" fn platform_wallet_shielded_prover_is_ready() -> bool { CachedOrchardProver::new().is_ready() @@ -2294,6 +2329,26 @@ mod tests { use platform_wallet::wallet::shielded::store::PendingRedrive; use platform_wallet::wallet::shielded::{FileBackedShieldedStore, ShieldedStore, SubwalletId}; + /// The blocking prepare entry point returns only once the real key is + /// cached, and joins a warm-up already in flight. Builds the real Halo 2 + /// key (~30 s debug, ~1-3 s release), so ignored by default. + #[test] + #[ignore = "builds the real Halo 2 proving key"] + fn prepare_prover_blocks_until_the_key_is_ready() { + unsafe { + platform_wallet_shielded_warm_up_prover(); + let start = std::time::Instant::now(); + let result = platform_wallet_shielded_prepare_prover(); + assert_eq!(result.code, PlatformWalletFFIResultCode::Success); + assert!(platform_wallet_shielded_prover_is_ready()); + eprintln!("prepare_prover waited {:?}", start.elapsed()); + // Ready: repeated preparation succeeds and preserves readiness. + let result = platform_wallet_shielded_prepare_prover(); + assert_eq!(result.code, PlatformWalletFFIResultCode::Success); + assert!(platform_wallet_shielded_prover_is_ready()); + } + } + #[test] fn encode_memo_text_none_is_empty() { let bytes = encode_memo_text(None).expect("None must encode"); diff --git a/packages/rs-platform-wallet/Cargo.toml b/packages/rs-platform-wallet/Cargo.toml index d3da739bcba..4e9996ff90e 100644 --- a/packages/rs-platform-wallet/Cargo.toml +++ b/packages/rs-platform-wallet/Cargo.toml @@ -73,6 +73,15 @@ zip32 = { version = "0.2.0", default-features = false, optional = true } # Same version as `dash-sdk` so the lockfile resolves a single copy. futures = { version = "0.3.30", optional = true } +# Apple targets only (shielded feature): the Orchard prover runs key builds +# and proofs on a dedicated rayon pool whose threads request the +# user-initiated QoS class (`pthread_set_qos_class_self_np`), so a build +# started from a background-QoS host thread is never throttled. Same rayon +# major as the one halo2 already pulls in, so the lockfile keeps one copy. +[target.'cfg(target_vendor = "apple")'.dependencies] +rayon = { version = "1.10", optional = true } +libc = { version = "0.2", optional = true } + # Networked, opt-in example binaries. Each one performs real network I/O # against a live devnet, so they are examples (compiled, never run by # `cargo test`) rather than `#[ignore]`d tests. They are crate-gated on the @@ -130,7 +139,7 @@ default = ["bls", "eddsa"] test-utils = ["key-wallet/test-utils"] bls = ["key-wallet/bls", "key-wallet-manager/bls"] eddsa = ["key-wallet/eddsa", "key-wallet-manager/eddsa"] -shielded = ["dep:grovedb-commitment-tree", "dep:rusqlite", "dep:zip32", "dep:futures", "dash-sdk/shielded", "dpp/shielded-client"] +shielded = ["dep:grovedb-commitment-tree", "dep:rusqlite", "dep:zip32", "dep:futures", "dep:rayon", "dep:libc", "dash-sdk/shielded", "dpp/shielded-client"] # Opt-in serde derives on the changeset types in `src/changeset/` plus # the per-identity / DashPay scalar types those changesets carry. # Activates `key-wallet/serde` (which transitively activates diff --git a/packages/rs-platform-wallet/src/wallet/platform_wallet.rs b/packages/rs-platform-wallet/src/wallet/platform_wallet.rs index 7cbe111776d..5babcbae56b 100644 --- a/packages/rs-platform-wallet/src/wallet/platform_wallet.rs +++ b/packages/rs-platform-wallet/src/wallet/platform_wallet.rs @@ -1327,7 +1327,7 @@ impl PlatformWallet { &self, seed: &[u8], account: u32, - ) -> Result { + ) -> Result, PlatformWalletError> { use super::shielded::OrchardKeySet; let bound_fvk = { let guard = self.shielded_keys.read().await; @@ -1347,7 +1347,9 @@ impl PlatformWallet { "seed does not derive the bound viewing key for shielded account {account}" ))); } - Ok(keyset) + // `Arc` so the spend proof can move the keyset onto a blocking + // thread without copying the spend authority. + Ok(Arc::new(keyset)) } /// Send a private shielded → shielded transfer from `account`'s @@ -1357,20 +1359,21 @@ impl PlatformWallet { /// `coordinator` supplies the shared, network-scoped /// commitment-tree store; `seed` supplies the spend authority — /// the full `OrchardKeySet` (with the `SpendAuthorizingKey`) is - /// re-derived from it for this call only and dropped on return. + /// re-derived from it for this call only and dropped on return (if + /// the call is cancelled mid-proof, once the in-flight proof on the + /// blocking pool finishes, which holds it by `Arc`). /// Privilege separation: the ASK never crosses to the /// coordinator — the spend free function takes the keyset by /// reference at call time. /// - /// The prover is consumed by value rather than borrowed - /// because `OrchardProver` is impl'd on - /// `&CachedOrchardProver` (the reference type), not on the - /// bare struct. Callers pass `&CachedOrchardProver::new()` - /// and we forward it down to the spend free function's - /// `&P` parameter. + /// `prover` is any [`ShieldedProver`](crate::wallet::shielded::ShieldedProver) + /// — in practice `CachedOrchardProver` or `&CachedOrchardProver`. + /// The spend awaits the prover's shared, off-runtime key + /// preparation and then generates the proof on tokio's blocking + /// pool, so no async worker is held for the multi-second build. #[cfg(feature = "shielded")] #[allow(clippy::too_many_arguments)] - pub async fn shielded_transfer_to( + pub async fn shielded_transfer_to( &self, coordinator: &Arc, seed: &[u8], @@ -1412,7 +1415,7 @@ impl PlatformWallet { /// the transient spend authority (see /// [`shielded_transfer_to`](Self::shielded_transfer_to)). #[cfg(feature = "shielded")] - pub async fn shielded_unshield_to( + pub async fn shielded_unshield_to( &self, coordinator: &Arc, seed: &[u8], @@ -1450,7 +1453,7 @@ impl PlatformWallet { /// spent notes on top. `seed` supplies the transient spend authority (see /// [`shielded_transfer_to`](Self::shielded_transfer_to)). #[cfg(feature = "shielded")] - pub async fn shielded_identity_top_up_from_pool( + pub async fn shielded_identity_top_up_from_pool( &self, coordinator: &Arc, seed: &[u8], @@ -1510,7 +1513,7 @@ impl PlatformWallet { /// [`shielded_transfer_to`](Self::shielded_transfer_to)). #[cfg(feature = "shielded")] #[allow(clippy::too_many_arguments)] - pub async fn shielded_withdraw_to( + pub async fn shielded_withdraw_to( &self, coordinator: &Arc, seed: &[u8], @@ -1584,7 +1587,7 @@ impl PlatformWallet { prover: P, ) -> Result where - P: dpp::shielded::builder::OrchardProver, + P: crate::wallet::shielded::ShieldedProver, IS: dpp::identity::signer::Signer + Send + Sync, { let (identity_id, identity) = { @@ -1760,7 +1763,7 @@ impl PlatformWallet { ) -> Result<(), PlatformWalletError> where S: dpp::identity::signer::Signer + Send + Sync, - P: dpp::shielded::builder::OrchardProver, + P: crate::wallet::shielded::ShieldedProver, { self.shielded_shield_from_account_impl( coordinator, @@ -1811,7 +1814,7 @@ impl PlatformWallet { ) -> Result<(), PlatformWalletError> where S: dpp::identity::signer::Signer + Send + Sync, - P: dpp::shielded::builder::OrchardProver, + P: crate::wallet::shielded::ShieldedProver, { let recipient = Option::::from( grovedb_commitment_tree::PaymentAddress::from_raw_address_bytes(recipient_raw_43), @@ -1851,7 +1854,7 @@ impl PlatformWallet { ) -> Result<(), PlatformWalletError> where S: dpp::identity::signer::Signer + Send + Sync, - P: dpp::shielded::builder::OrchardProver, + P: crate::wallet::shielded::ShieldedProver, { // Preserve the boundary behavior for non-Swift hosts and avoid taking // the single-flight/account locks for a request that can never build. @@ -1966,7 +1969,7 @@ impl PlatformWallet { ) -> Result where S: dpp::identity::signer::Signer + Send + Sync, - P: dpp::shielded::builder::OrchardProver, + P: crate::wallet::shielded::ShieldedProver, { self.shielded_shield_from_identity_impl( coordinator, @@ -2001,7 +2004,7 @@ impl PlatformWallet { ) -> Result where S: dpp::identity::signer::Signer + Send + Sync, - P: dpp::shielded::builder::OrchardProver, + P: crate::wallet::shielded::ShieldedProver, { let recipient = Option::::from( grovedb_commitment_tree::PaymentAddress::from_raw_address_bytes(recipient_raw_43), @@ -2039,7 +2042,7 @@ impl PlatformWallet { ) -> Result where S: dpp::identity::signer::Signer + Send + Sync, - P: dpp::shielded::builder::OrchardProver, + P: crate::wallet::shielded::ShieldedProver, { if amount == 0 { return Err(PlatformWalletError::ShieldedBuildError( diff --git a/packages/rs-platform-wallet/src/wallet/shielded/mod.rs b/packages/rs-platform-wallet/src/wallet/shielded/mod.rs index df2b4fa1ddc..b0a31bf3124 100644 --- a/packages/rs-platform-wallet/src/wallet/shielded/mod.rs +++ b/packages/rs-platform-wallet/src/wallet/shielded/mod.rs @@ -22,7 +22,8 @@ //! [`FileBackedShieldedStore`] — storage abstraction; the //! shared commitment tree lives here. Per-subwallet notes are //! scoped by [`SubwalletId`] inside the store. -//! - [`CachedOrchardProver`] — lazy-init proving key cache. +//! - [`CachedOrchardProver`] — lazy-init proving key cache with a +//! shared, off-runtime async preparation ([`ShieldedProver`]). //! - Sync / spend operations live as free functions in the //! [`sync`] and [`operations`] submodules and take //! `(sdk, store, persister, wallet_id, keys, …)` explicitly. @@ -61,7 +62,7 @@ pub use balance::{ pub use coordinator::NetworkShieldedCoordinator; pub use file_store::{FileBackedShieldedStore, FileShieldedStoreError}; pub use keys::{AccountViewingKeys, OrchardKeySet}; -pub use prover::CachedOrchardProver; +pub use prover::{CachedOrchardProver, ReadyOrchardProver, ShieldedProver}; pub use seed_pool::{SeedPoolOutcome, SeedPoolProgress, DEFAULT_SEED_POOL_TARGET_NOTES}; pub use store::{ IdentityDebitRecoveryRecord, IdentityDebitRecoveryStatus, InMemoryShieldedStore, ShieldedNote, diff --git a/packages/rs-platform-wallet/src/wallet/shielded/operations.rs b/packages/rs-platform-wallet/src/wallet/shielded/operations.rs index e7509b85389..40f1ba0e5e1 100644 --- a/packages/rs-platform-wallet/src/wallet/shielded/operations.rs +++ b/packages/rs-platform-wallet/src/wallet/shielded/operations.rs @@ -27,6 +27,7 @@ use super::keys::{AccountViewingKeys, OrchardKeySet}; use super::note_selection::{ select_notes_for_denomination, select_notes_with_fee, ShieldedFeeKind, }; +use super::prover::{prove_on_blocking_thread, ShieldedProver}; use super::store::{PendingRedrive, ShieldedNote, ShieldedStore, SubwalletId}; use crate::broadcast_outcome::{broadcast_definitely_failed, carries_consensus_rejection}; use crate::changeset::{PlatformWalletChangeSet, ShieldedChangeSet}; @@ -61,7 +62,7 @@ use dpp::shielded::builder::{ build_identity_create_from_shielded_pool_transition, build_identity_top_up_from_shielded_pool_transition, build_shield_from_identity_transition, build_shield_transition, build_shielded_transfer_transition, - build_shielded_withdrawal_transition, build_unshield_transition, OrchardProver, SpendableNote, + build_shielded_withdrawal_transition, build_unshield_transition, SpendableNote, }; use dpp::shielded::compute_minimum_shielded_fee; use dpp::state_transition::proof_result::StateTransitionProofResult; @@ -528,7 +529,7 @@ fn resolve_shield_recipient( /// Self-shield front for [`shield_to`], preserving the pre-recipient /// signature for existing callers. #[allow(clippy::too_many_arguments)] -pub async fn shield, P: OrchardProver>( +pub async fn shield, P: ShieldedProver>( sdk: &Arc, store: &Arc>, persister: Option<&WalletPersister>, @@ -559,7 +560,7 @@ pub async fn shield, P: OrchardPr /// the send from chain data and the live and scan-derived activity ids /// line up. #[allow(clippy::too_many_arguments)] -pub async fn shield_to, P: OrchardProver>( +pub async fn shield_to, P: ShieldedProver>( sdk: &Arc, store: &Arc>, persister: Option<&WalletPersister>, @@ -640,6 +641,9 @@ pub async fn shield_to, P: Orchar let claimed_inputs = inputs_with_nonce.clone(); + // Await the shared, off-runtime proving-key preparation rather than + // blocking this worker on the key build. + let prover = prover.ready().await?; let state_transition = build_shield_transition( &recipient_addr, amount, @@ -647,7 +651,7 @@ pub async fn shield_to, P: Orchar fee_strategy, signer, 0, // user_fee_increase - prover, + &prover, memo, // Encrypt the output under the account's own OVK so the wallet's // shielded sync can recover this send (recipient, value, memo) @@ -924,7 +928,7 @@ async fn arm_identity_shield_redrive( pub(in crate::wallet) async fn shield_from_identity_to< S: ShieldedStore, Sig: Signer, - P: OrchardProver, + P: ShieldedProver, >( sdk: &Arc, store: &Arc>, @@ -988,6 +992,9 @@ pub(in crate::wallet) async fn shield_from_identity_to< "ShieldFromIdentity: building proof" ); + // Await the shared, off-runtime proving-key preparation rather than + // blocking this worker on the key build. + let prover = prover.ready().await?; let state_transition = build_shield_from_identity_transition( identity, &recipient_addr, @@ -996,7 +1003,7 @@ pub(in crate::wallet) async fn shield_from_identity_to< signer, None, 0, // user_fee_increase - prover, + &prover, memo, Some(keys.outgoing_viewing_key.clone()), sdk.version(), @@ -1352,12 +1359,12 @@ mod shield_from_identity_build_error_tests { /// unexpected shape, which is logged). The caller persists it for a managed /// identity (`PlatformWallet::shielded_identity_top_up_from_pool`). #[allow(clippy::too_many_arguments)] -pub async fn identity_top_up_from_pool( +pub async fn identity_top_up_from_pool( sdk: &Arc, store: &Arc>, persister: Option<&WalletPersister>, wallet_id: WalletId, - keys: &OrchardKeySet, + keys: &Arc, account: u32, identity_id: Identifier, amount: u64, @@ -1381,13 +1388,13 @@ pub async fn identity_top_up_from_pool( #[allow(clippy::too_many_arguments)] pub(in crate::wallet) async fn identity_top_up_from_pool_with_metadata< S: ShieldedStore, - P: OrchardProver, + P: ShieldedProver, >( sdk: &Arc, store: &Arc>, persister: Option<&WalletPersister>, wallet_id: WalletId, - keys: &OrchardKeySet, + keys: &Arc, account: u32, identity_id: Identifier, amount: u64, @@ -1415,18 +1422,27 @@ pub(in crate::wallet) async fn identity_top_up_from_pool_with_metadata< let (spends, anchor) = extract_spends_and_anchor(sdk, store, &selected_notes).await?; let anchor_bytes = anchor.to_bytes(); - let (state_transition, fee_used) = build_identity_top_up_from_shielded_pool_transition( - spends, - identity_id, - amount, - &change_addr, - &keys.full_viewing_key, - &keys.spend_auth_key, - anchor, - prover, - [0u8; 36], - sdk.version(), - ) + // Proof generation runs on the blocking pool (see `prove_on_blocking_thread`); + // the keyset moves in by `Arc`, so the spend authority is not copied. + let (state_transition, fee_used) = { + let keys = Arc::clone(keys); + let platform_version: &'static PlatformVersion = sdk.version(); + prove_on_blocking_thread(prover, move |prover| { + build_identity_top_up_from_shielded_pool_transition( + spends, + identity_id, + amount, + &change_addr, + &keys.full_viewing_key, + &keys.spend_auth_key, + anchor, + prover, + [0u8; 36], + platform_version, + ) + }) + .await? + } .map_err(|e| PlatformWalletError::ShieldedBuildError(e.to_string()))?; debug_assert_eq!( fee_used, exact_fee, @@ -1563,12 +1579,12 @@ pub(in crate::wallet) async fn identity_top_up_from_pool_with_metadata< /// Unshield funds from `account`'s shielded notes to a /// transparent platform address. #[allow(clippy::too_many_arguments)] -pub async fn unshield( +pub async fn unshield( sdk: &Arc, store: &Arc>, persister: Option<&WalletPersister>, wallet_id: WalletId, - keys: &OrchardKeySet, + keys: &Arc, account: u32, to_address: &PlatformAddress, amount: u64, @@ -1617,18 +1633,28 @@ pub async fn unshield( // The builder computes and returns the fee authoritatively; `exact_fee` (== the // minimum) was already used above for note reservation. - let (state_transition, fee_used) = build_unshield_transition( - spends, - *to_address, - amount, - &change_addr, - &keys.full_viewing_key, - &keys.spend_auth_key, - anchor, - prover, - [0u8; 36], - sdk.version(), - ) + // Proof generation runs on the blocking pool (see `prove_on_blocking_thread`); + // the keyset moves in by `Arc`, so the spend authority is not copied. + let (state_transition, fee_used) = { + let keys = Arc::clone(keys); + let to_address = *to_address; + let platform_version: &'static PlatformVersion = sdk.version(); + prove_on_blocking_thread(prover, move |prover| { + build_unshield_transition( + spends, + to_address, + amount, + &change_addr, + &keys.full_viewing_key, + &keys.spend_auth_key, + anchor, + prover, + [0u8; 36], + platform_version, + ) + }) + .await? + } .map_err(|e| PlatformWalletError::ShieldedBuildError(e.to_string()))?; // The builder's fee and the wallet's reserved `exact_fee` both come from // compute_shielded_unshield_fee with the same action count; lock that they agree. @@ -1755,12 +1781,12 @@ pub async fn unshield( /// Transfer funds privately from `account`'s shielded notes to /// another Orchard payment address. #[allow(clippy::too_many_arguments)] -pub async fn transfer( +pub async fn transfer( sdk: &Arc, store: &Arc>, persister: Option<&WalletPersister>, wallet_id: WalletId, - keys: &OrchardKeySet, + keys: &Arc, account: u32, to_address: &PaymentAddress, amount: u64, @@ -1796,18 +1822,27 @@ pub async fn transfer( // The builder computes and returns the fee authoritatively; `exact_fee` (== the // minimum) was already used above for note reservation. - let (state_transition, fee_used) = build_shielded_transfer_transition( - spends, - &recipient_addr, - amount, - &change_addr, - &keys.full_viewing_key, - &keys.spend_auth_key, - anchor, - prover, - memo, - sdk.version(), - ) + // Proof generation runs on the blocking pool (see `prove_on_blocking_thread`); + // the keyset moves in by `Arc`, so the spend authority is not copied. + let (state_transition, fee_used) = { + let keys = Arc::clone(keys); + let platform_version: &'static PlatformVersion = sdk.version(); + prove_on_blocking_thread(prover, move |prover| { + build_shielded_transfer_transition( + spends, + &recipient_addr, + amount, + &change_addr, + &keys.full_viewing_key, + &keys.spend_auth_key, + anchor, + prover, + memo, + platform_version, + ) + }) + .await? + } .map_err(|e| PlatformWalletError::ShieldedBuildError(e.to_string()))?; // The builder's fee and the wallet's reserved `exact_fee` both come from // compute_minimum_shielded_fee with the same action count; lock that they agree. @@ -1911,12 +1946,12 @@ pub async fn transfer( /// Withdraw funds from `account`'s shielded notes to a Core L1 address. #[allow(clippy::too_many_arguments)] -pub async fn withdraw( +pub async fn withdraw( sdk: &Arc, store: &Arc>, persister: Option<&WalletPersister>, wallet_id: WalletId, - keys: &OrchardKeySet, + keys: &Arc, account: u32, to_address: &dashcore::Address, amount: u64, @@ -1963,21 +1998,30 @@ pub async fn withdraw( // The builder computes and returns the fee authoritatively; `exact_fee` (== the // minimum) was already used above for note reservation. - let (state_transition, fee_used) = build_shielded_withdrawal_transition( - spends, - amount, - output_script, - core_fee_per_byte, - // Consensus pins shielded-withdrawal pooling to Never (validate_structure). - Pooling::Never, - &change_addr, - &keys.full_viewing_key, - &keys.spend_auth_key, - anchor, - prover, - [0u8; 36], - sdk.version(), - ) + // Proof generation runs on the blocking pool (see `prove_on_blocking_thread`); + // the keyset moves in by `Arc`, so the spend authority is not copied. + let (state_transition, fee_used) = { + let keys = Arc::clone(keys); + let platform_version: &'static PlatformVersion = sdk.version(); + prove_on_blocking_thread(prover, move |prover| { + build_shielded_withdrawal_transition( + spends, + amount, + output_script, + core_fee_per_byte, + // Consensus pins shielded-withdrawal pooling to Never (validate_structure). + Pooling::Never, + &change_addr, + &keys.full_viewing_key, + &keys.spend_auth_key, + anchor, + prover, + [0u8; 36], + platform_version, + ) + }) + .await? + } .map_err(|e| PlatformWalletError::ShieldedBuildError(e.to_string()))?; // The builder's fee and the wallet's reserved `exact_fee` both come from // compute_shielded_withdrawal_fee with the same action count; lock that they agree. @@ -2112,7 +2156,7 @@ pub async fn identity_create_from_shielded_pool( ) -> Result<(Identifier, Identity), PlatformWalletError> where S: ShieldedStore, - P: OrchardProver, + P: ShieldedProver, IS: Signer, { if public_keys.is_empty() { @@ -2167,6 +2211,10 @@ where // this anchor is pruned from Platform's recorded set. let anchor_bytes = anchor.to_bytes(); + // Await the shared proving-key preparation instead of blocking a worker + // on the key build. The proof itself still runs inside the builder here: + // it interleaves proving with the host identity signer. + let prover = prover.ready().await?; let build = build_identity_create_from_shielded_pool_transition( public_keys, denomination, @@ -2176,7 +2224,7 @@ where &keys.full_viewing_key, &keys.spend_auth_key, anchor, - prover, + &prover, identity_signer, [0u8; 36], sdk.version(), diff --git a/packages/rs-platform-wallet/src/wallet/shielded/prover.rs b/packages/rs-platform-wallet/src/wallet/shielded/prover.rs index e57e922d43c..9db4dc53f39 100644 --- a/packages/rs-platform-wallet/src/wallet/shielded/prover.rs +++ b/packages/rs-platform-wallet/src/wallet/shielded/prover.rs @@ -1,46 +1,293 @@ //! Cached Orchard prover for zero-knowledge proof generation. //! -//! The Halo 2 proving key takes ~30 seconds to build on first use. This -//! module provides [`CachedOrchardProver`] which lazily builds the key -//! once (via `OnceLock`) and caches it for the process lifetime. +//! The Halo 2 proving key takes ~30 seconds to build in debug builds +//! (~1-3 s in release). This module builds it once per process and +//! caches it for the process lifetime. //! -//! Callers should invoke [`CachedOrchardProver::warm_up`] on a background -//! thread during app startup so the first shielded operation does not block. +//! # Preparation +//! +//! [`CachedOrchardProver::prepare`] is the awaitable entry point: every +//! concurrent caller shares ONE build, which runs on tokio's blocking +//! pool (never on an async worker), and the call returns once the key is +//! ready. The shielded send operations await the same shared +//! preparation (through [`ShieldedProver::ready`]) before proving, so a +//! send that arrives while a warm-up is still running waits only for the +//! remaining build time and parks no async worker while it does. +//! +//! [`CachedOrchardProver::warm_up`] is the legacy blocking entry point; +//! it joins the same build (a concurrent async preparation and a +//! blocking warm-up never build the key twice). +//! +//! # Proving off the async runtime +//! +//! Proof generation itself is CPU-bound for seconds. +//! [`prove_on_blocking_thread`] waits for the prover to be ready and +//! then hands the proving closure to a tokio blocking-pool thread, so the +//! async workers stay free for networking and shielded sync. On Apple +//! targets that blocking thread only waits: the closure itself runs on a +//! dedicated user-initiated-QoS rayon pool (see `on_proving_threads`); +//! elsewhere it runs on the blocking thread. use std::sync::OnceLock; +use async_trait::async_trait; use dpp::shielded::builder::OrchardProver; use grovedb_commitment_tree::ProvingKey; +use crate::error::PlatformWalletError; + +/// A lazily-built, process-lifetime value whose build is expensive and +/// blocking, with a shared async preparation path. +/// +/// Exactly one build ever runs, no matter how many sync +/// ([`get_or_build_blocking`](Self::get_or_build_blocking)) and async +/// ([`prepare`](Self::prepare)) callers race: the value lives in a +/// `std::sync::OnceLock`, whose initializer runs at most once while every +/// other caller waits for it. Async callers additionally coalesce on a +/// `tokio::sync::OnceCell`, so concurrent `prepare` calls park as tasks +/// on one blocking-pool job instead of each occupying a thread. +/// +/// The build function is a parameter so tests can count builds and +/// control their duration without paying for the real Halo 2 key; so is +/// the runner that executes it (the real key builds on the proving threads, +/// see [`on_proving_threads`]; test cells build inline so they never queue +/// behind a real key build in the same test binary). +pub(crate) struct ProvingKeyCell { + value: OnceLock, + async_init: tokio::sync::OnceCell<()>, + build: fn() -> K, + run: fn(fn() -> K) -> K, +} + +impl ProvingKeyCell { + pub(crate) const fn new(build: fn() -> K, run: fn(fn() -> K) -> K) -> Self { + Self { + value: OnceLock::new(), + async_init: tokio::sync::OnceCell::const_new(), + build, + run, + } + } + + /// The value, if it has already been built. + pub(crate) fn get(&self) -> Option<&K> { + self.value.get() + } + + /// The value, building it if necessary. Blocks the calling thread for + /// the whole build (or until a build already running elsewhere + /// finishes). + /// + /// Invariant: never call this from an async context, and never from a + /// rayon worker (of the proving pool or the global pool) while the + /// value is unbuilt. Such a worker waiting inside the build can steal + /// another job that also waits on this cell from the same thread — a + /// deadlock. Proving code therefore always awaits + /// [`ShieldedProver::ready`] before entering the proving pool, and the + /// ready prover never touches this cell. + pub(crate) fn get_or_build_blocking(&self) -> &K { + if let Some(value) = self.value.get() { + return value; + } + #[cfg(target_vendor = "apple")] + debug_assert!( + !apple_qos::on_proving_pool_thread(), + "the proving key must be prepared before proving on the proving pool" + ); + let (build, run) = (self.build, self.run); + self.value.get_or_init(|| run(build)) + } + + /// Wait until the value is built, building it on tokio's blocking + /// pool if nobody has started yet. Concurrent callers share one + /// build. Returns immediately once the value exists. + /// + /// Outside a tokio runtime there is no blocking pool to hand the + /// build to, so the calling thread blocks for it (as in + /// [`get_or_build_blocking`](Self::get_or_build_blocking)). + /// + /// Errors only if the build panicked or the runtime is shutting down; + /// the cell then stays empty and a later call retries. Note the retry + /// granularity (`OnceCell::get_or_try_init` semantics): a persistently + /// failing build is re-attempted once by each waiter queued behind the + /// failed attempt, one after another. (A build panic is only + /// recoverable where panics unwind, not under `panic = "abort"`.) + pub(crate) async fn prepare(&'static self) -> Result<&'static K, PlatformWalletError> { + if let Some(value) = self.value.get() { + return Ok(value); + } + if tokio::runtime::Handle::try_current().is_err() { + // Same panic-to-error contract as the blocking-pool path below. + return std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| { + self.get_or_build_blocking() + })) + .map_err(|_| { + PlatformWalletError::ShieldedBuildError( + "Orchard proving key preparation failed: the build panicked".to_string(), + ) + }); + } + self.async_init + .get_or_try_init(|| async move { + // If this future is dropped mid-build, the next waiter + // re-runs this initializer: its blocking job then waits on + // the `OnceLock` behind the first job instead of building a + // second key. + tokio::task::spawn_blocking(move || { + self.get_or_build_blocking(); + }) + .await + .map_err(|e| { + let reason = if e.is_panic() { + "the build panicked" + } else { + "the build task was cancelled" + }; + PlatformWalletError::ShieldedBuildError(format!( + "Orchard proving key preparation failed: {reason}" + )) + }) + }) + .await?; + Ok(self + .value + .get() + .expect("the shared preparation completed, so the value is built")) + } +} + +/// Run CPU-heavy Orchard work (the proving-key build or a proof) on the +/// threads reserved for it, blocking the caller until it finishes. +/// +/// On Apple targets this is a dedicated rayon pool whose threads request +/// the `USER_INITIATED` QoS class at start-up and have the same 8 MiB stack +/// as the FFI runtime's threads (Halo 2 circuit synthesis recurses deeply). +/// Darwin threads otherwise inherit the QoS of whichever thread created +/// them — tokio blocking-pool threads are spawned lazily by whatever thread +/// first needs one, and the process-global rayon pool (which halo2 uses for +/// its parallel FFTs/MSMs, and which dash-spv also uses) by whatever thread +/// first touches rayon — so a warm-up kicked off from a background-priority +/// host task could otherwise leave the build, and every later proof's +/// parallel work, throttled at background QoS. Running inside +/// `ThreadPool::install` also makes halo2's nested rayon parallelism use +/// this pool rather than the global one. +/// +/// Top-level jobs enter the pool one at a time. A single proof (or key +/// build) already saturates the pool; letting two in at once would let a +/// worker that is blocked in a `join` inside proof A steal proof B's whole +/// top-level job and run it on A's stack, so A would finish only after +/// A + B and both would share one 8 MiB stack. A call made from a pool +/// thread is already on the proving threads and runs inline (taking the +/// gate again would deadlock). +/// +/// Elsewhere (and if the pool cannot be created) the work runs inline. +/// +/// Private on purpose: callers must have the proving key built first (see +/// [`ProvingKeyCell::get_or_build_blocking`]'s invariant), which +/// [`prove_on_blocking_thread`] guarantees by awaiting `ready()`. +fn on_proving_threads(work: impl FnOnce() -> T + Send) -> T { + #[cfg(target_vendor = "apple")] + { + if apple_qos::on_proving_pool_thread() { + return work(); + } + if let Some(pool) = apple_qos::proving_pool() { + let _one_job_at_a_time = apple_qos::PROVING_GATE + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner); + return pool.install(work); + } + } + work() +} + +#[cfg(target_vendor = "apple")] +mod apple_qos { + use std::sync::{Mutex, OnceLock}; + + /// Serializes top-level jobs entering the proving pool (see + /// `on_proving_threads`). + pub(super) static PROVING_GATE: Mutex<()> = Mutex::new(()); + + /// Same stack as the FFI runtime's workers (`WORKER_STACK_BYTES`). + const PROVING_THREAD_STACK_BYTES: usize = 8 * 1024 * 1024; + + static POOL: OnceLock> = OnceLock::new(); + + pub(super) fn proving_pool() -> Option<&'static rayon::ThreadPool> { + POOL.get_or_init(|| { + rayon::ThreadPoolBuilder::new() + .thread_name(|i| format!("orchard-prover-{i}")) + .stack_size(PROVING_THREAD_STACK_BYTES) + .start_handler(|_| request_user_initiated_qos()) + .build() + .ok() + }) + .as_ref() + } + + /// Whether the current thread is one of the proving pool's (without + /// creating the pool). + pub(super) fn on_proving_pool_thread() -> bool { + POOL.get() + .and_then(Option::as_ref) + .is_some_and(|pool| pool.current_thread_index().is_some()) + } + + /// Request the user-initiated QoS class for the current thread. Best + /// effort: failure leaves the thread at its inherited QoS. + fn request_user_initiated_qos() { + // SAFETY: plain FFI call on the current thread with a valid class. + unsafe { + libc::pthread_set_qos_class_self_np(libc::qos_class_t::QOS_CLASS_USER_INITIATED, 0); + } + } +} + /// Global proving key cache — built once, shared for the process lifetime. -static PROVING_KEY: OnceLock = OnceLock::new(); +static PROVING_KEY: ProvingKeyCell = + ProvingKeyCell::new(ProvingKey::build, on_proving_threads); /// A cached Orchard prover that lazily builds and caches the Halo 2 /// proving key. /// -/// This struct is zero-sized — all state lives in the `OnceLock` static. +/// This struct is zero-sized — all state lives in a process-global cell. /// Multiple `CachedOrchardProver` instances share the same cached key. /// -/// Implements `OrchardProver` (via a `&CachedOrchardProver` reference) -/// so it can be passed directly to DPP's `build_*_transition()` builders. +/// Implements [`OrchardProver`] (via a `&CachedOrchardProver` reference) so +/// it can be passed directly to DPP's `build_*_transition()` builders, and +/// [`ShieldedProver`] so the wallet's send operations can await the +/// shared preparation and prove off the async runtime. +#[derive(Debug, Clone, Copy, Default)] pub struct CachedOrchardProver; impl CachedOrchardProver { /// Create a new prover handle. /// - /// This does **not** build the proving key — call [`warm_up`](Self::warm_up) - /// or wait for the first proof generation to trigger the build. + /// This does **not** build the proving key — call + /// [`prepare`](Self::prepare) / [`warm_up`](Self::warm_up) or wait for + /// the first proof generation to trigger the build. pub fn new() -> Self { CachedOrchardProver } + /// Wait until the proving key is built, building it on tokio's + /// blocking pool if no build is running yet. Concurrent callers (and + /// a concurrent blocking [`warm_up`](Self::warm_up)) share one build; + /// no async worker is blocked while waiting. Returns immediately once + /// the key is cached. + pub async fn prepare() -> Result<(), PlatformWalletError> { + PROVING_KEY.prepare().await.map(|_| ()) + } + /// Build the proving key if it hasn't been built yet. /// - /// This is a blocking operation (~30 seconds on first call). Subsequent - /// calls return immediately. Call this on a background thread during - /// app startup. + /// This is a blocking operation (up to ~30 seconds on first call). + /// Subsequent calls return immediately. Call this on a background + /// thread, never on an async worker — async code should await + /// [`prepare`](Self::prepare) instead. pub fn warm_up(&self) { - let _ = PROVING_KEY.get_or_init(ProvingKey::build); + let _ = PROVING_KEY.get_or_build_blocking(); } /// Whether the proving key has already been built and cached. @@ -50,33 +297,483 @@ impl CachedOrchardProver { /// Get a reference to the cached proving key, building it if necessary. fn get_or_build(&self) -> &'static ProvingKey { - PROVING_KEY.get_or_init(ProvingKey::build) + PROVING_KEY.get_or_build_blocking() } } -impl Default for CachedOrchardProver { - fn default() -> Self { - Self::new() +impl OrchardProver for &CachedOrchardProver { + fn proving_key(&self) -> &ProvingKey { + self.get_or_build() } } -impl OrchardProver for &CachedOrchardProver { +/// An [`OrchardProver`] whose proving key is already built. +/// +/// `Copy + Send + Sync + 'static`, so it can move into a blocking-pool +/// closure. Obtained from [`ShieldedProver::ready`]. +#[derive(Clone, Copy)] +pub struct ReadyOrchardProver(&'static ProvingKey); + +impl OrchardProver for ReadyOrchardProver { fn proving_key(&self) -> &ProvingKey { - self.get_or_build() + self.0 + } +} + +/// Source of a ready-to-use Orchard prover for the wallet's shielded +/// send operations. +/// +/// The operations await [`ready`](Self::ready) — which for +/// [`CachedOrchardProver`] is the shared, off-runtime proving-key +/// preparation — and then move the returned prover onto a blocking +/// thread for proof generation (see [`prove_on_blocking_thread`]). +#[async_trait] +pub trait ShieldedProver: Send + Sync { + /// The prover handed to the DPP builders once the key is ready. + type Ready: OrchardProver + Send + Sync + 'static; + + /// Wait until the prover is ready (building its key if necessary, + /// without blocking an async worker) and return it. + async fn ready(&self) -> Result; +} + +#[async_trait] +impl ShieldedProver for CachedOrchardProver { + type Ready = ReadyOrchardProver; + + async fn ready(&self) -> Result { + PROVING_KEY.prepare().await.map(ReadyOrchardProver) + } +} + +#[async_trait] +impl ShieldedProver for &T { + type Ready = T::Ready; + + async fn ready(&self) -> Result { + (**self).ready().await + } +} + +/// Wait for `prover` to be ready, then run `prove` with it off the async +/// runtime: a tokio blocking-pool thread hands it to the proving threads +/// (see [`on_proving_threads`]) and waits. +/// +/// Everything `prove` needs must be moved in (`Send + 'static`); it gets +/// the ready prover by reference, matching the DPP builders' `&P`. A panic +/// in `prove` is re-raised to the caller. +pub(crate) async fn prove_on_blocking_thread( + prover: &P, + prove: F, +) -> Result +where + P: ShieldedProver + ?Sized, + F: FnOnce(&P::Ready) -> T + Send + 'static, + T: Send + 'static, +{ + // `ready()` first: the key must be built before any work enters the + // proving pool (a lazy build from a pool worker could deadlock, see + // `ProvingKeyCell::get_or_build_blocking`). + let ready = prover.ready().await?; + let work = move || on_proving_threads(move || prove(&ready)); + // Outside a tokio runtime there is no blocking pool: run synchronously. + if tokio::runtime::Handle::try_current().is_err() { + return Ok(work()); + } + match tokio::task::spawn_blocking(work).await { + Ok(value) => Ok(value), + // Re-raise a proving panic exactly as if it had run on this thread. + Err(e) if e.is_panic() => std::panic::resume_unwind(e.into_panic()), + Err(_) => Err(PlatformWalletError::ShieldedBuildError( + "proof generation was cancelled (runtime shutting down)".to_string(), + )), } } #[cfg(test)] mod tests { use super::*; + use std::sync::atomic::{AtomicUsize, Ordering}; + use std::time::{Duration, Instant}; #[test] fn test_prover_starts_not_ready() { // Note: if another test already warmed up the key in this process, // this will pass trivially. That's fine — we just verify the API works. let prover = CachedOrchardProver::new(); - // is_ready may be true or false depending on test execution order. - // Just verify the method doesn't panic. let _ = prover.is_ready(); } + + /// Test cells build on the calling thread, never on the shared proving + /// pool, so their timing can't queue behind a real key build running in + /// another test of this binary. + fn run_inline(build: fn() -> K) -> K { + build() + } + + /// Each test owns its own static cell + counter so tests can run in + /// parallel without sharing build state. + macro_rules! test_cell { + ($cell:ident, $builds:ident, $millis:expr) => { + static $builds: AtomicUsize = AtomicUsize::new(0); + static $cell: ProvingKeyCell = ProvingKeyCell::new( + || { + $builds.fetch_add(1, Ordering::SeqCst); + std::thread::sleep(Duration::from_millis($millis)); + 42 + }, + run_inline, + ); + }; + } + + /// A cell whose build blocks until the test sets `$release`, so tests + /// can observe "build in flight" deterministically instead of racing + /// wall-clock sleeps (CI machines are noisy). The deadline only turns + /// a broken test into a failure instead of a hang. + macro_rules! gated_cell { + ($cell:ident, $builds:ident, $release:ident) => { + static $builds: AtomicUsize = AtomicUsize::new(0); + static $release: std::sync::atomic::AtomicBool = + std::sync::atomic::AtomicBool::new(false); + static $cell: ProvingKeyCell = ProvingKeyCell::new( + || { + $builds.fetch_add(1, Ordering::SeqCst); + let deadline = Instant::now() + HANG_GUARD; + while !$release.load(Ordering::SeqCst) { + assert!(Instant::now() < deadline, "build never released"); + std::thread::sleep(Duration::from_millis(1)); + } + 42 + }, + run_inline, + ); + }; + } + + /// Upper bound for "this must eventually happen"; never a latency + /// threshold. + const HANG_GUARD: Duration = Duration::from_secs(120); + + /// Yield to the runtime until `cond` holds (bounded by `HANG_GUARD`). + async fn wait_until(cond: impl Fn() -> bool) { + let deadline = Instant::now() + HANG_GUARD; + while !cond() { + assert!(Instant::now() < deadline, "condition never became true"); + tokio::time::sleep(Duration::from_millis(1)).await; + } + } + + #[tokio::test(flavor = "multi_thread", worker_threads = 4)] + async fn concurrent_prepare_callers_share_one_build() { + test_cell!(CELL, BUILDS, 200); + let handles: Vec<_> = (0..32) + .map(|_| tokio::spawn(async { CELL.prepare().await.map(|v| v as *const u64 as usize) })) + .collect(); + let mut ptrs = Vec::new(); + for h in handles { + ptrs.push(h.await.unwrap().unwrap()); + } + assert_eq!(BUILDS.load(Ordering::SeqCst), 1, "exactly one build"); + assert!( + ptrs.windows(2).all(|w| w[0] == w[1]), + "all callers see one value" + ); + // A later call reuses the cached value. + assert_eq!(*CELL.prepare().await.unwrap(), 42); + assert_eq!(BUILDS.load(Ordering::SeqCst), 1); + } + + #[tokio::test(flavor = "multi_thread", worker_threads = 2)] + async fn blocking_warm_up_and_async_prepare_share_one_build() { + test_cell!(CELL, BUILDS, 300); + // Legacy warm-up: a plain thread blocking in the sync path. + let warm = std::thread::spawn(|| *CELL.get_or_build_blocking()); + tokio::time::sleep(Duration::from_millis(50)).await; + let prepared = CELL.prepare().await.unwrap(); + assert_eq!(*prepared, 42); + assert_eq!(warm.join().unwrap(), 42); + assert_eq!(BUILDS.load(Ordering::SeqCst), 1); + } + + /// The FFI runtime is multi-threaded, but the wallet may be driven + /// from a current-thread runtime (tests, other hosts). There the + /// single runtime thread must keep polling other tasks while the key + /// builds — i.e. the build must not run on the runtime thread. If it + /// did, the runtime could never get back to this test body to release + /// the build, and the build's hang guard would fail the test. + #[tokio::test(flavor = "current_thread")] + async fn prepare_on_current_thread_runtime_keeps_runtime_responsive() { + gated_cell!(CELL, BUILDS, RELEASE); + let prepare = tokio::spawn(CELL.prepare()); + wait_until(|| BUILDS.load(Ordering::SeqCst) == 1).await; + // The build is in flight and the runtime thread is still free. + for _ in 0..3 { + tokio::task::yield_now().await; + } + RELEASE.store(true, Ordering::SeqCst); + assert_eq!(*prepare.await.unwrap().unwrap(), 42); + assert_eq!(BUILDS.load(Ordering::SeqCst), 1); + } + + /// A send that arrives while a warm-up is building joins that build: + /// it does not start another, and it completes as soon as the build + /// does (it only waits for the remainder). + #[tokio::test(flavor = "multi_thread", worker_threads = 2)] + async fn send_started_mid_warm_up_waits_for_the_in_flight_build() { + gated_cell!(CELL, BUILDS, RELEASE); + let warm = tokio::spawn(CELL.prepare()); + wait_until(|| BUILDS.load(Ordering::SeqCst) == 1).await; + let send = tokio::spawn(CELL.prepare()); + tokio::time::sleep(Duration::from_millis(20)).await; + assert!(!send.is_finished(), "the send must wait for the key"); + let released = Instant::now(); + RELEASE.store(true, Ordering::SeqCst); + assert_eq!(*send.await.unwrap().unwrap(), 42); + eprintln!( + "send completed {:?} after the in-flight build finished", + released.elapsed() + ); + warm.await.unwrap().unwrap(); + assert_eq!(BUILDS.load(Ordering::SeqCst), 1); + } + + /// Aborting the waiter that started the build must not start a second + /// build: the next waiter re-runs the async initializer, whose blocking + /// job just waits on the `OnceLock` behind the first one. + #[tokio::test(flavor = "multi_thread", worker_threads = 2)] + async fn aborted_prepare_waiter_does_not_cause_a_second_build() { + gated_cell!(CELL, BUILDS, RELEASE); + let first = tokio::spawn(CELL.prepare()); + wait_until(|| BUILDS.load(Ordering::SeqCst) == 1).await; + first.abort(); + assert!(first.await.unwrap_err().is_cancelled()); + let second = tokio::spawn(CELL.prepare()); + tokio::time::sleep(Duration::from_millis(20)).await; + RELEASE.store(true, Ordering::SeqCst); + assert_eq!(*second.await.unwrap().unwrap(), 42); + assert_eq!(*CELL.prepare().await.unwrap(), 42); + assert_eq!(BUILDS.load(Ordering::SeqCst), 1); + } + + #[tokio::test(flavor = "multi_thread", worker_threads = 2)] + async fn panicking_build_reports_error_and_a_later_call_retries() { + static ATTEMPTS: AtomicUsize = AtomicUsize::new(0); + static CELL: ProvingKeyCell = ProvingKeyCell::new( + || { + if ATTEMPTS.fetch_add(1, Ordering::SeqCst) == 0 { + panic!("first build fails"); + } + 7 + }, + run_inline, + ); + let err = CELL.prepare().await.unwrap_err(); + assert!(err.to_string().contains("panicked"), "{err}"); + assert!(CELL.get().is_none()); + assert_eq!(*CELL.prepare().await.unwrap(), 7); + assert_eq!(ATTEMPTS.load(Ordering::SeqCst), 2); + } + + #[test] + fn prepare_without_runtime_builds_on_the_calling_thread() { + test_cell!(CELL, BUILDS, 10); + let value = futures::executor::block_on(CELL.prepare()).unwrap(); + assert_eq!(*value, 42); + assert_eq!(BUILDS.load(Ordering::SeqCst), 1); + } + + #[test] + fn panicking_build_without_runtime_reports_error_and_a_later_call_retries() { + static ATTEMPTS: AtomicUsize = AtomicUsize::new(0); + static CELL: ProvingKeyCell = ProvingKeyCell::new( + || { + if ATTEMPTS.fetch_add(1, Ordering::SeqCst) == 0 { + panic!("first build fails"); + } + 7 + }, + run_inline, + ); + let err = futures::executor::block_on(CELL.prepare()).unwrap_err(); + assert!(err.to_string().contains("panicked"), "{err}"); + assert!(CELL.get().is_none()); + assert_eq!(*futures::executor::block_on(CELL.prepare()).unwrap(), 7); + assert_eq!(ATTEMPTS.load(Ordering::SeqCst), 2); + } + + /// Test double for the send path: a `ShieldedProver` backed by a test + /// cell. Its `Ready` reuses the real key type only nominally — the + /// closures under test never touch the key. + struct CountingProver(&'static ProvingKeyCell); + + #[derive(Clone, Copy)] + struct CountingReady(&'static u64); + + impl OrchardProver for CountingReady { + fn proving_key(&self) -> &ProvingKey { + unreachable!("send-path tests never prove for real") + } + } + + #[async_trait] + impl ShieldedProver for CountingProver { + type Ready = CountingReady; + async fn ready(&self) -> Result { + self.0.prepare().await.map(CountingReady) + } + } + + #[tokio::test(flavor = "multi_thread", worker_threads = 2)] + async fn send_path_awaits_the_shared_preparation() { + test_cell!(CELL, BUILDS, 300); + let prover = CountingProver(&CELL); + let warm = tokio::spawn(CELL.prepare()); + let sends: Vec<_> = (0..4) + .map(|i| { + let prover = CountingProver(&CELL); + tokio::spawn(async move { + prove_on_blocking_thread(&prover, move |ready| *ready.0 + i) + .await + .unwrap() + }) + }) + .collect(); + let direct = prove_on_blocking_thread(&&prover, |ready| *ready.0) + .await + .unwrap(); + assert_eq!(direct, 42); + for (i, s) in sends.into_iter().enumerate() { + assert_eq!(s.await.unwrap(), 42 + i as u64); + } + warm.await.unwrap().unwrap(); + assert_eq!(BUILDS.load(Ordering::SeqCst), 1); + } + + /// On a current-thread runtime, the runtime keeps running other tasks + /// while a proof is in progress: the "proof" only finishes once a task + /// on the same runtime has ticked. Inline proving (the pre-change + /// behavior) would block the runtime thread, the ticker would never + /// run, and the proof would report the timeout. No latency thresholds; + /// see the ignored real-proof test for measurements. + #[tokio::test(flavor = "current_thread")] + async fn proving_off_runtime_keeps_runtime_responsive() { + test_cell!(CELL, BUILDS, 0); + CELL.prepare().await.unwrap(); + let prover = CountingProver(&CELL); + let (ticked_tx, ticked_rx) = std::sync::mpsc::channel::<()>(); + let ticker = async move { + for _ in 0..3 { + tokio::time::sleep(Duration::from_millis(1)).await; + } + ticked_tx.send(()).unwrap(); + }; + let proof = + prove_on_blocking_thread(&prover, move |_| ticked_rx.recv_timeout(HANG_GUARD).is_ok()); + let ((), runtime_ticked_during_proof) = tokio::join!(ticker, proof); + assert!(runtime_ticked_during_proof.unwrap()); + } + + #[tokio::test(flavor = "multi_thread", worker_threads = 2)] + async fn panic_while_proving_propagates() { + test_cell!(CELL, BUILDS, 0); + let prover = CountingProver(&CELL); + let joined = tokio::spawn(async move { + prove_on_blocking_thread(&prover, |_| -> u8 { panic!("prover bug") }).await + }) + .await; + assert!(joined.unwrap_err().is_panic()); + } + + /// Real proving key: concurrent `prepare` callers share one build and + /// the key is usable afterwards. Slow (~30 s debug, ~1-3 s release), + /// so ignored by default: + /// `cargo test -p platform-wallet --features shielded --release -- --ignored real_proving_key` + #[tokio::test(flavor = "multi_thread", worker_threads = 2)] + #[ignore = "builds the real Halo 2 proving key"] + async fn real_proving_key_prepare_is_shared_and_timed() { + let start = Instant::now(); + let handles: Vec<_> = (0..8) + .map(|_| tokio::spawn(CachedOrchardProver::prepare())) + .collect(); + for h in handles { + h.await.unwrap().unwrap(); + } + let built = start.elapsed(); + assert!(CachedOrchardProver::new().is_ready()); + let ready = CachedOrchardProver.ready().await.unwrap(); + let _ = ready.proving_key(); + eprintln!("real proving key prepared in {built:?} (8 concurrent callers)"); + } + + /// Darwin QoS: even when the build is requested from a + /// background-QoS thread, the build and its nested rayon work run at + /// user-initiated QoS on the dedicated proving pool. + #[cfg(target_vendor = "apple")] + #[test] + fn proving_work_runs_at_user_initiated_qos_on_apple() { + fn current_qos() -> u32 { + let mut class: u32 = 0; + let mut relative: libc::c_int = 0; + // SAFETY: valid out-pointers; `qos_class_t` is a `u32` enum and + // is read back as a raw `u32` so no unknown discriminant is + // ever materialized as the enum. + unsafe { + libc::pthread_get_qos_class_np( + libc::pthread_self(), + &mut class as *mut u32 as *mut libc::qos_class_t, + &mut relative, + ); + } + class + } + const BACKGROUND: u32 = libc::qos_class_t::QOS_CLASS_BACKGROUND as u32; + const USER_INITIATED: u32 = libc::qos_class_t::QOS_CLASS_USER_INITIATED as u32; + + let observed = std::thread::spawn(|| { + // SAFETY: plain FFI call on the current thread. + unsafe { + libc::pthread_set_qos_class_self_np(libc::qos_class_t::QOS_CLASS_BACKGROUND, 0); + } + assert_eq!(current_qos(), BACKGROUND); + let (outer, nested) = on_proving_threads(|| { + let (a, b) = rayon::join(current_qos, current_qos); + assert!(rayon::current_thread_index().is_some()); + (current_qos(), [a, b]) + }); + // The caller's own QoS is untouched. + assert_eq!(current_qos(), BACKGROUND); + (outer, nested) + }) + .join() + .unwrap(); + assert_eq!(observed.0, USER_INITIATED); + assert_eq!(observed.1, [USER_INITIATED, USER_INITIATED]); + } + + /// Top-level jobs enter the Apple proving pool one at a time, and a + /// nested call from a pool thread runs inline instead of deadlocking + /// on the gate. + #[cfg(target_vendor = "apple")] + #[test] + fn proving_pool_runs_one_top_level_job_at_a_time() { + static IN_FLIGHT: AtomicUsize = AtomicUsize::new(0); + static MAX_IN_FLIGHT: AtomicUsize = AtomicUsize::new(0); + let job = || { + on_proving_threads(|| { + let now = IN_FLIGHT.fetch_add(1, Ordering::SeqCst) + 1; + MAX_IN_FLIGHT.fetch_max(now, Ordering::SeqCst); + // Nested parallel work, as halo2 does, plus a re-entrant call. + let (a, b) = rayon::join(|| 1, || on_proving_threads(|| 2)); + std::thread::sleep(Duration::from_millis(20)); + IN_FLIGHT.fetch_sub(1, Ordering::SeqCst); + a + b + }) + }; + let threads: Vec<_> = (0..4).map(|_| std::thread::spawn(job)).collect(); + for t in threads { + assert_eq!(t.join().unwrap(), 3); + } + assert_eq!(MAX_IN_FLIGHT.load(Ordering::SeqCst), 1); + } } diff --git a/packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/PlatformWalletManagerShieldedSync.swift b/packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/PlatformWalletManagerShieldedSync.swift index 97d86c8dfb9..f55c09bc1db 100644 --- a/packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/PlatformWalletManagerShieldedSync.swift +++ b/packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/PlatformWalletManagerShieldedSync.swift @@ -575,22 +575,62 @@ extension PlatformWalletManager { return present ? Data(bytes) : nil } - /// Build the Halo 2 proving key on a background thread so the - /// first shielded send doesn't pay the ~30 s build cost - /// inline. Idempotent and safe to call from any thread; later - /// calls return immediately. Independent of any wallet — the - /// cache is process-global on the Rust side. - public static func warmUpShieldedProver() async { + /// Start building the Halo 2 proving key in the background so + /// the first shielded send doesn't pay the build cost inline. + /// Fire-and-forget: this returns as soon as the build has been + /// scheduled, NOT when the key is ready — await + /// `prepareShieldedProver()` (or poll `isShieldedProverReady`) for + /// that. The build runs at user-initiated QoS on Rust-owned threads + /// even though this task is background priority, so a send that + /// arrives mid-build is not left waiting on a throttled build. + /// Idempotent and safe to call from any thread. Independent of any wallet — the cache + /// is process-global on the Rust side. + nonisolated public static func warmUpShieldedProver() async { await Task.detached(priority: .background) { platform_wallet_shielded_warm_up_prover() }.value } + /// Suspend until the Halo 2 proving key is built, starting the + /// build if nothing has yet; returns immediately once it is + /// cached. Shares the single process-wide build with + /// `warmUpShieldedProver()` and with shielded sends, so awaiting + /// it during a warm-up waits only for the remainder. + /// + /// The blocking FFI wait runs on a global dispatch queue, not on + /// the Swift cooperative pool, so awaiting this never pins a + /// cooperative thread for the build. The build itself runs on + /// Rust-owned threads at user-initiated QoS regardless of the + /// caller's priority (the same holds for `warmUpShieldedProver()`). Sends do not need to call + /// this first — they await the same preparation internally; use + /// it to drive a "preparing…" UI state or to warm up with a + /// completion signal. + /// + /// Throws only if the build failed (a panic on the Rust side or + /// runtime shutdown); a later call retries. + /// + /// Ignores task cancellation: the build cannot be interrupted, so a + /// cancelled caller still resumes only once the key is ready (or the + /// build failed). `nonisolated`, so awaiting it from the main actor + /// does not hop back to the main actor for the wait. + nonisolated public static func prepareShieldedProver() async throws { + try await withCheckedThrowingContinuation { (continuation: CheckedContinuation) in + DispatchQueue.global(qos: .userInitiated).async { + do { + try platform_wallet_shielded_prepare_prover().check() + continuation.resume() + } catch { + continuation.resume(throwing: error) + } + } + } + } + /// Whether the Halo 2 proving key has been built yet. Useful /// for a "preparing prover…" UI affordance — `false` doesn't /// mean shielded sends will fail, just that the next one - /// pays the build cost. - public static var isShieldedProverReady: Bool { + /// waits for the build to finish first. + nonisolated public static var isShieldedProverReady: Bool { platform_wallet_shielded_prover_is_ready() }