spark_rust/signer/

default_signer.rs

use super::traits::derivation_path::SparkSignerDerivationPath;
use super::traits::ecdsa::SparkSignerEcdsa;
use super::traits::ecies::SparkSignerEcies;
use super::traits::frost::SparkSignerFrost;
use super::traits::frost_signing::SparkSignerFrostSigning;
use super::traits::secp256k1::SparkSignerSecp256k1;
use super::traits::shamir::SparkSignerShamir;
use super::traits::SparkSigner;
use crate::common_types::types::frost::FrostNonce;
use crate::common_types::types::frost::FrostNonceCommitment;
use crate::common_types::types::frost::FrostSigningCommitments;
use crate::common_types::types::frost::FrostSigningNonces;
use crate::common_types::types::hex_decode;
use crate::common_types::types::hex_encode;
use crate::common_types::types::HashbrownMap;
use crate::common_types::types::RwLock;
use crate::common_types::types::Secp256k1;
use crate::common_types::types::Secp256k1Message;
use crate::common_types::types::SparkRange;
use crate::common_types::types::Transaction;
use crate::common_types::types::Uuid;
use crate::common_types::types::{PublicKey, SecretKey};
use crate::constants::spark::frost::FROST_USER_IDENTIFIER;
use crate::constants::spark::frost::FROST_USER_KEY_PACKAGE_MIN_SIGNERS;
use crate::constants::spark::frost::FROST_USER_SIGNING_ROLE;
use crate::error::{CryptoError, SparkSdkError, ValidationError};
use crate::wallet::internal_handlers::traits::create_tree::DepositAddressTree;
use crate::wallet::internal_handlers::traits::transfer::LeafKeyTweak;
use crate::wallet::internal_handlers::traits::transfer::LeafRefundSigningData;
use crate::wallet::utils::bitcoin::bitcoin_tx_from_bytes;
use crate::wallet::utils::bitcoin::serialize_bitcoin_transaction;
use crate::wallet::utils::bitcoin::sighash_from_tx;
use crate::wallet::utils::bitcoin::sighash_from_tx_new;
use crate::wallet::utils::sequence::next_sequence;
use crate::wallet::utils::transaction::ephemeral_anchor_output;
use crate::SparkNetwork;
use bitcoin::bip32::Xpriv;
use bitcoin::key::Keypair;
use bitcoin::secp256k1::ecdsa::Signature;
use bitcoin::secp256k1::All;
use bitcoin::Network;
use spark_cryptography::derivation_path::derive_spark_key;
use spark_cryptography::derivation_path::get_derivation_path_with_key_type;
use spark_cryptography::derivation_path::get_secret_key_with_key_type;
use spark_cryptography::derivation_path::SparkDerivationPath;
use spark_cryptography::derivation_path::SparkKeyType;
use spark_cryptography::secp::subtract_secret_keys;
use spark_cryptography::secret_sharing::from_bytes_to_k256_scalar;
use spark_cryptography::secret_sharing::split_secret_with_proofs;
use spark_cryptography::secret_sharing::VerifiableSecretShare;
use spark_cryptography::signing::aggregate_frost;
use spark_cryptography::signing::sign_frost;
use spark_protos::common::SigningCommitment as SparkOperatorCommitment;
use spark_protos::common::SigningCommitment;
use spark_protos::frost::AggregateFrostRequest;
use spark_protos::frost::AggregateFrostResponse;
use spark_protos::frost::FrostSigningJob;
use spark_protos::frost::SignFrostRequest;
use spark_protos::frost::SignFrostResponse;
use spark_protos::spark::LeafRefundTxSigningResult;
use spark_protos::spark::NodeSignatures;
use spark_protos::spark::RequestedSigningCommitments;
use spark_protos::spark::SigningKeyshare;
use spark_protos::spark::SigningResult;
use std::collections::HashMap;
use std::sync::Arc;
use tonic::async_trait;

/// A default, in-memory signer for Spark v1.
///
/// - This signer keeps a `master_seed` and derives keypairs to carry out signing operations.
/// - Keys are held in memory and not persisted unless a future update is made
///   to store them to disk.
/// - Nonce commitments for each signing round remain ephemeral in memory,
///   which is typically sufficient for short-lived signing sessions.
#[derive(Clone)]
pub struct DefaultSigner {
    /// The master seed for the signer.
    master_seed: Vec<u8>,

    /// A map of references to nonce commitments, stored as strings. These are used
    /// per signing round and can remain in memory until the round completes.
    pub nonce_commitments: Arc<RwLock<HashbrownMap<String, String>>>,

    /// A map from public keys to secret keys, stored in memory only. Keys can always be reconstructed
    /// from the master seed and the derivation path.
    pub public_keys_to_secret_keys: Arc<RwLock<HashbrownMap<PublicKey, SecretKey>>>,

    /// The network that the signer is operating on.
    pub network: SparkNetwork,

    secp: Secp256k1<All>,
}

impl SparkSignerDerivationPath for DefaultSigner {
    fn get_deposit_signing_key(&self, network: Network) -> Result<PublicKey, SparkSdkError> {
        let secret_key = get_secret_key_with_key_type(
            &self.master_seed,
            0,
            network,
            SparkKeyType::Deposit,
            &self.secp,
        )
        .map_err(|e| SparkSdkError::from(CryptoError::SparkCryptographyError(e)))?;

        let public_key = secret_key.public_key(&self.secp);

        self.insert_to_keypair_map(&public_key, &secret_key)?;

        Ok(public_key)
    }

    fn derive_spark_key(
        &self,
        leaf_id: String,
        account: u32,
        key_type: SparkKeyType,
        network: Network,
    ) -> Result<Keypair, SparkSdkError> {
        let secret_key =
            derive_spark_key(Some(leaf_id), account, &self.master_seed, key_type, network)
                .map_err(|e| SparkSdkError::from(CryptoError::SparkCryptographyError(e)))?;

        let keypair = Keypair::from_secret_key(&self.secp, &secret_key);
        self.insert_to_keypair_map(&keypair.public_key(), &secret_key)?;

        Ok(keypair)
    }

    fn get_identity_derivation_path(
        account_index: u32,
    ) -> Result<SparkDerivationPath, SparkSdkError> {
        get_derivation_path_with_key_type(account_index, SparkKeyType::Identity)
            .map_err(|e| SparkSdkError::from(CryptoError::SparkCryptographyError(e)))
    }
}

impl SparkSignerSecp256k1 for DefaultSigner {
    #[cfg_attr(feature = "telemetry", tracing::instrument(skip_all))]
    fn get_identity_public_key(
        &self,
        account_index: u32,
        network: Network,
    ) -> Result<PublicKey, SparkSdkError> {
        let seed_bytes = self.load_master_seed()?;
        let seed = match Xpriv::new_master(network, &seed_bytes) {
            Ok(seed) => seed,
            Err(_) => return Err(SparkSdkError::from(CryptoError::InvalidSeed)),
        };

        let identity_derivation_path = Self::get_identity_derivation_path(account_index)?;

        let identity_key = seed
            .derive_priv(&self.secp, &*identity_derivation_path)
            .map_err(|_| {
                SparkSdkError::from(CryptoError::ChildKeyDerivationError {
                    derivation_path: format!("{:?}", identity_derivation_path),
                })
            })?;

        let identity_key = identity_key.private_key.public_key(&self.secp);

        Ok(identity_key)
    }

    #[cfg_attr(feature = "telemetry", tracing::instrument(skip_all))]
    fn insert_secp256k1_keypair_from_secret_key(
        &self,
        secret_key: &SecretKey,
    ) -> Result<PublicKey, SparkSdkError> {
        let public_key = PublicKey::from_secret_key(&self.secp, secret_key);

        self.insert_to_keypair_map(&public_key, secret_key)?;

        Ok(public_key)
    }

    #[cfg_attr(feature = "telemetry", tracing::instrument(skip_all))]
    fn new_ephemeral_keypair(&self) -> Result<PublicKey, SparkSdkError> {
        let secret_key = SecretKey::new(&mut SparkRange);
        let public_key = secret_key.public_key(&self.secp);

        self.insert_to_keypair_map(&public_key, &secret_key)?;

        Ok(public_key)
    }

    #[cfg_attr(feature = "telemetry", tracing::instrument(skip_all))]
    fn subtract_secret_keys_given_pubkeys(
        &self,
        target_pubkey: &PublicKey,
        source_pubkey: &PublicKey,
        save_new_key: bool,
    ) -> Result<PublicKey, SparkSdkError> {
        if target_pubkey == source_pubkey {
            return Err(SparkSdkError::from(ValidationError::InvalidInput {
                field: "Target and source public keys are the same".to_string(),
            }));
        }

        let target_secret_key = &self.get_secret_key_from_pubkey(target_pubkey)?;
        let source_secret_key = &self.get_secret_key_from_pubkey(source_pubkey)?;

        let result_secret_key = subtract_secret_keys(target_secret_key, source_secret_key)
            .map_err(|e| SparkSdkError::from(CryptoError::Secp256k1(e)))?;

        let result_public_key = PublicKey::from_secret_key(&self.secp, &result_secret_key);

        if save_new_key {
            self.insert_to_keypair_map(&result_public_key, &result_secret_key)?;
        }

        Ok(result_public_key)
    }

    #[cfg_attr(feature = "telemetry", tracing::instrument(skip_all))]
    fn sensitive_expose_secret_key_from_pubkey(
        &self,
        public_key: &PublicKey,
        delete_after_exposing: bool,
    ) -> Result<SecretKey, SparkSdkError> {
        let secret_key = self.get_secret_key_from_pubkey(public_key)?;

        if delete_after_exposing {
            self.evict_from_keypair_map(public_key)?;
        }

        Ok(secret_key)
    }
}

#[cfg(test)]
mod default_signer_secp256k1_tests {
    use super::*;
    use crate::error::SparkSdkError;

    use bip32::Language;

    type WrappedSigner = Arc<DefaultSigner>;

    const TEST_NETWORK: SparkNetwork = SparkNetwork::Regtest;

    // Helper function to create a DefaultSigner for testing secp256k1 operations.
    async fn create_default_signer() -> Result<WrappedSigner, SparkSdkError> {
        let rng = SparkRange;
        let mnemonic = bip32::Mnemonic::random(rng, Language::English);
        let master_seed = mnemonic.to_seed("").as_bytes().to_vec();
        let signer = DefaultSigner::from_master_seed(&master_seed, TEST_NETWORK).await?;

        Ok(signer)
    }

    #[tokio::test]
    async fn test_get_identity_public_key() -> Result<(), SparkSdkError> {
        let signer = create_default_signer().await?;
        signer
            .get_identity_public_key(0, Network::Regtest)
            .expect("failed to get identity pk");

        Ok(())
    }

    #[tokio::test]
    async fn test_new_secp256k1_keypair() -> Result<(), SparkSdkError> {
        let signer = create_default_signer().await?;

        let leaf_id = Uuid::new_v4().to_string();
        let account_index = 0;
        let key_type = SparkKeyType::BaseSigning;
        let network = Network::Regtest;

        let keypair = signer.derive_spark_key(leaf_id, account_index, key_type, network)?;
        let pk = keypair.public_key();
        let pubkey_bytes = pk.serialize().to_vec();
        assert_eq!(pubkey_bytes.len(), 33);

        let identity_pubkey = signer.get_identity_public_key(0, Network::Regtest)?;
        assert_ne!(identity_pubkey, pk);

        Ok(())
    }

    #[tokio::test]
    async fn test_insert_secp256k1_keypair_from_secret_key() -> Result<(), SparkSdkError> {
        let signer = create_default_signer().await?;
        // generate a random secret key to insert
        let secret_key = SecretKey::new(&mut SparkRange);
        let pubkey = signer.insert_secp256k1_keypair_from_secret_key(&secret_key)?;

        // verify that the secret key exists in the signer space
        let retrieved_secret_key =
            signer.sensitive_expose_secret_key_from_pubkey(&pubkey, false)?;
        assert_eq!(retrieved_secret_key, secret_key);

        Ok(())
    }

    #[tokio::test]
    async fn test_subtract_secret_keys_given_pubkeys() -> Result<(), SparkSdkError> {
        let account_index = 0;
        let key_type = SparkKeyType::BaseSigning;
        let network = Network::Regtest;

        let leaf_id_1 = Uuid::new_v4().to_string();
        let leaf_id_2 = Uuid::new_v4().to_string();

        let signer = create_default_signer().await?;

        // create two new keypairs
        let keypair1 = signer.derive_spark_key(leaf_id_1, account_index, key_type, network)?;
        let keypair2 = signer.derive_spark_key(leaf_id_2, account_index, key_type, network)?;

        let pk1 = keypair1.public_key();
        let pk2 = keypair2.public_key();

        // do subtraction
        let new_pubkey = signer.subtract_secret_keys_given_pubkeys(&pk1, &pk2, true)?;

        // try exposing the new key's secret key
        let _ = signer.sensitive_expose_secret_key_from_pubkey(&new_pubkey, false)?;

        Ok(())
    }
}

const SPLIT_SECRET_ERROR: &str = "Failed to split secret: ";
#[async_trait]
impl SparkSignerShamir for DefaultSigner {
    fn split_with_verifiable_secret_sharing(
        &self,
        message_bytes: Vec<u8>,
        threshold: usize,
        num_shares: usize,
    ) -> Result<Vec<VerifiableSecretShare>, SparkSdkError> {
        // Get the shares
        let message_as_scalar = from_bytes_to_k256_scalar(&message_bytes).map_err(|e| {
            SparkSdkError::from(CryptoError::InvalidInput {
                field: format!("{} {}", SPLIT_SECRET_ERROR, e),
            })
        })?;
        let shares =
            split_secret_with_proofs(&message_as_scalar, threshold, num_shares).map_err(|e| {
                SparkSdkError::from(ValidationError::InvalidInput {
                    field: format!("{} {}", SPLIT_SECRET_ERROR, e),
                })
            })?;

        Ok(shares)
    }

    fn split_from_public_key_with_verifiable_secret_sharing(
        &self,
        public_key: &PublicKey,
        threshold: usize,
        num_shares: usize,
    ) -> Result<Vec<VerifiableSecretShare>, SparkSdkError> {
        let secret_key = self.get_secret_key_from_pubkey(public_key)?;
        let shares = self.split_with_verifiable_secret_sharing(
            secret_key.secret_bytes().to_vec(),
            threshold,
            num_shares,
        )?;
        Ok(shares)
    }
}

#[cfg(test)]
mod default_signer_shamir_tests {
    use super::*;
    use crate::error::SparkSdkError;
    use bip32::Language;
    use rand::rngs::OsRng;
    use std::sync::Arc;

    type WrappedSigner = Arc<DefaultSigner>;

    const TEST_NETWORK: SparkNetwork = SparkNetwork::Regtest;

    // Helper function to create a DefaultSigner for testing Shamir.
    async fn create_shamir_test_signer() -> Result<WrappedSigner, SparkSdkError> {
        let rng = OsRng;
        let mnemonic = bip32::Mnemonic::random(rng, Language::English);
        let master_seed = mnemonic.to_seed("").as_bytes().to_vec();
        let signer = DefaultSigner::from_master_seed(&master_seed, TEST_NETWORK).await?;
        Ok(signer)
    }

    #[tokio::test]
    #[ignore]
    async fn test_split_with_verifiable_secret_sharing() -> Result<(), SparkSdkError> {
        let signer = create_shamir_test_signer().await?;
        let message = b"hello world".to_vec();

        // For demonstration: 2-of-3 threshold scheme.
        let threshold = 2;
        let num_shares = 3;

        // Attempt to split the secret.
        let shares = signer.split_with_verifiable_secret_sharing(message, threshold, num_shares)?;

        // We expect exactly 'num_shares' shares.
        assert_eq!(shares.len(), num_shares);

        Ok(())
    }
}

impl SparkSignerEcdsa for DefaultSigner {
    fn sign_message_ecdsa_with_identity_key<T: AsRef<[u8]>>(
        &self,
        message: T,
        apply_hashing: bool,
        network: Network,
    ) -> Result<Signature, SparkSdkError> {
        // Create a SHA256 hash of the payload
        // Using SHA256::digest gives us the hash directly, similar to Go's sha256.Sum256
        let payload_hash = if apply_hashing {
            sha256::digest(message.as_ref())
        } else {
            hex::encode(message.as_ref())
        };

        let hash_bytes = hex::decode(&payload_hash).unwrap();
        let message = Secp256k1Message::from_digest_slice(&hash_bytes)?;

        // Get the identity secret key
        let identity_secret_key = self.get_identity_secret_key(0, network)?;

        Ok(self.secp.sign_ecdsa(&message, &identity_secret_key))
    }

    fn sign_message_ecdsa_with_key<T: AsRef<[u8]>>(
        &self,
        message: T,
        public_key_for_signing_key: &PublicKey,
        apply_hashing: bool,
    ) -> Result<Signature, SparkSdkError> {
        let payload_hash = if apply_hashing {
            sha256::digest(message.as_ref())
        } else {
            hex::encode(message.as_ref())
        };

        let secret_key = self.get_secret_key_from_pubkey(public_key_for_signing_key)?;

        let message = Secp256k1Message::from_digest_slice(&hex::decode(&payload_hash).unwrap())?;

        Ok(self.secp.sign_ecdsa(&message, &secret_key))
    }
}

#[cfg(test)]
mod default_signer_ecdsa_tests {
    use super::*;
    use crate::common_types::types::Digest;
    use crate::common_types::types::Secp256k1Message;
    use crate::common_types::types::Sha256;
    use bip32::Language;

    type WrappedSigner = Arc<DefaultSigner>;

    const TEST_NETWORK: SparkNetwork = SparkNetwork::Regtest;

    // Helper function to create a DefaultSigner for testing ECDSA operations.
    async fn create_ecdsa_test_signer() -> Result<WrappedSigner, SparkSdkError> {
        let rng = SparkRange;
        let mnemonic = bip32::Mnemonic::random(rng, Language::English);
        let master_seed = mnemonic.to_seed("").as_bytes().to_vec();
        let signer = DefaultSigner::from_master_seed(&master_seed, TEST_NETWORK).await?;
        Ok(signer)
    }

    #[tokio::test]
    async fn test_sign_message_ecdsa_with_identity_key() -> Result<(), SparkSdkError> {
        let signer = create_ecdsa_test_signer().await?;

        // prepare and sign message
        let message = b"this is a test message";
        let signature =
            signer.sign_message_ecdsa_with_identity_key(message, true, Network::Regtest)?;

        // verify the signature externally
        let identity_pk = signer.get_identity_public_key(0, Network::Regtest)?;
        let msg_hash = Sha256::digest(message);
        let message_for_verify = Secp256k1Message::from_digest_slice(&msg_hash).map_err(|e| {
            SparkSdkError::from(CryptoError::InvalidInput {
                field: format!("Failed to parse message: {e}"),
            })
        })?;

        // perform verification
        let ctx = Secp256k1::verification_only();
        ctx.verify_ecdsa(&message_for_verify, &signature, &identity_pk)
            .map_err(|_e| {
                SparkSdkError::from(CryptoError::InvalidInput {
                    field: "Signature verification failed".to_string(),
                })
            })?;

        Ok(())
    }

    #[tokio::test]
    async fn test_sign_message_ecdsa_with_key() -> Result<(), SparkSdkError> {
        use rand::thread_rng;

        // Generate a new keypair
        let secp = Secp256k1::new();
        let mut rng = thread_rng();
        let keypair = bitcoin::secp256k1::Keypair::new(&secp, &mut rng);

        // Create the signer
        let signer = create_ecdsa_test_signer().await?;

        // Add the keypair to the signer
        signer.insert_to_keypair_map(&keypair.public_key(), &keypair.secret_key())?;

        let message = b"this is a test message";
        let _ = signer.sign_message_ecdsa_with_key(message, &keypair.public_key(), true)?;

        Ok(())
    }
}

impl SparkSignerEcies for DefaultSigner {
    fn encrypt_secret_key_with_ecies(
        &self,
        receiver_public_key: &PublicKey,
        message: &PublicKey,
    ) -> Result<Vec<u8>, SparkSdkError> {
        let secret_key = self.get_secret_key_from_pubkey(message)?;

        let message = spark_cryptography::ecies::encrypt_ecies(
            receiver_public_key,
            &secret_key.secret_bytes(),
        )?;

        Ok(message)
    }

    fn decrypt_secret_key_with_ecies<T>(
        &self,
        ciphertext: T,
        network: Network,
    ) -> Result<SecretKey, SparkSdkError>
    where
        T: AsRef<[u8]>,
    {
        let secret_key = self.get_identity_secret_key(0, network)?;
        let message = spark_cryptography::ecies::decrypt_ecies(secret_key, ciphertext.as_ref())?;

        let secret_key = SecretKey::from_slice(&message).unwrap();
        Ok(secret_key)
    }
}

#[cfg(test)]
mod default_signer_ecies_tests {
    use super::*;
    use crate::error::SparkSdkError;
    use bip32::Language;
    use rand::rngs::OsRng;
    use std::sync::Arc;

    type WrappedSigner = Arc<DefaultSigner>;

    const TEST_NETWORK: SparkNetwork = SparkNetwork::Regtest;

    // Helper function to create a DefaultSigner for testing ECIES operations.
    async fn create_ecies_test_signer() -> Result<WrappedSigner, SparkSdkError> {
        let mnemonic = bip32::Mnemonic::random(OsRng, Language::English);
        let master_seed = mnemonic.to_seed("").as_bytes().to_vec();
        let signer = DefaultSigner::from_master_seed(&master_seed, TEST_NETWORK).await?;
        Ok(signer)
    }

    #[tokio::test]
    async fn test_ecies_encrypt_decrypt_round_trip() -> Result<(), SparkSdkError> {
        let signer = create_ecies_test_signer().await?;

        // prepare keys
        let secp = Secp256k1::new();
        let message_as_secret_key = SecretKey::new(&mut OsRng);
        let message_as_pubkey = PublicKey::from_secret_key(&secp, &message_as_secret_key);
        signer.insert_to_keypair_map(&message_as_pubkey, &message_as_secret_key)?;

        let receiver_public_key = signer.get_identity_public_key(0, Network::Regtest)?;

        // encrypt then decrypt the ephemeral secret key
        let ciphertext =
            signer.encrypt_secret_key_with_ecies(&receiver_public_key, &message_as_pubkey)?;
        let decrypted_key = signer.decrypt_secret_key_with_ecies(&ciphertext, Network::Regtest)?;

        // verify the decrypted key matches the original ephemeral secret key
        assert_eq!(
            decrypted_key, message_as_secret_key,
            "Decrypted key did not match the original"
        );

        Ok(())
    }
}

#[async_trait]
impl SparkSignerFrost for DefaultSigner {
    fn generate_frost_signing_commitments(&self) -> Result<FrostSigningCommitments, SparkSdkError> {
        let mut rng = SparkRange;
        let binding_sk = SecretKey::new(&mut rng);
        let hiding_sk = SecretKey::new(&mut rng);

        let binding = FrostNonce::deserialize(&binding_sk.secret_bytes()).unwrap();
        let hiding = FrostNonce::deserialize(&hiding_sk.secret_bytes()).unwrap();

        let nonces =
            frost_secp256k1_tr_unofficial::round1::SigningNonces::from_nonces(hiding, binding);
        let commitments = nonces.commitments();

        let nonces_bytes = nonces.serialize().unwrap();
        let commitment_bytes = commitments.serialize().unwrap();

        self.insert_to_noncepair_map(commitment_bytes, nonces_bytes)?;

        Ok(*commitments)
    }

    fn sensitive_expose_nonces_from_commitments<T>(
        &self,
        signing_commitments: &T,
    ) -> Result<FrostSigningNonces, SparkSdkError>
    where
        T: AsRef<[u8]>,
    {
        let signing_commitment_hex = hex_encode(signing_commitments.as_ref());
        let signing_nonces = self
            .nonce_commitments
            .read()
            .get(&signing_commitment_hex)
            .cloned()
            .ok_or_else(|| {
                SparkSdkError::from(ValidationError::InvalidInput {
                    field: "Nonce commitments not found".to_string(),
                })
            })?;

        let signing_nonces_bytes = hex_decode(signing_nonces).unwrap();
        let signing_nonces = FrostSigningNonces::deserialize(&signing_nonces_bytes).unwrap(); // This is a safe unwrap
        Ok(signing_nonces)
    }
}

impl SparkSignerFrostSigning for DefaultSigner {
    fn sign_frost(
        &self,
        signing_jobs: Vec<FrostSigningJob>,
    ) -> Result<SignFrostResponse, SparkSdkError> {
        sign_frost(&SignFrostRequest {
            signing_jobs,
            role: FROST_USER_SIGNING_ROLE,
        })
        .map_err(|e| {
            SparkSdkError::from(CryptoError::FrostSigning {
                job_id: e.to_string(),
            })
        })
    }

    fn aggregate_frost(
        &self,
        request: AggregateFrostRequest,
    ) -> Result<AggregateFrostResponse, SparkSdkError> {
        aggregate_frost(&request).map_err(|_| SparkSdkError::from(CryptoError::FrostAggregation))
    }

    fn sign_created_tree_in_bfs_order(
        &self,
        tx: Transaction,
        vout: u32,
        internal_tree_root: Arc<RwLock<DepositAddressTree>>,
        request_tree_root: spark_protos::spark::CreationNode,
        creation_result_tree_root: spark_protos::spark::CreationResponseNode,
    ) -> Result<(Vec<NodeSignatures>, Vec<Vec<u8>>), SparkSdkError> {
        #[derive(Clone)]
        struct QueueItem {
            parent_tx: Transaction,
            vout: u32,
            internal_node: Arc<RwLock<DepositAddressTree>>,
            creation_node: spark_protos::spark::CreationNode,
            creation_response_node: spark_protos::spark::CreationResponseNode,
        }

        let mut queue = std::collections::VecDeque::new();
        let mut node_signatures = vec![];

        queue.push_back(QueueItem {
            parent_tx: tx,
            vout,
            internal_node: internal_tree_root,
            creation_node: request_tree_root,
            creation_response_node: creation_result_tree_root,
        });

        let mut signing_public_keys = vec![];

        while let Some(current) = queue.pop_front() {
            let node_prevout_index = current.vout as usize;
            let node_signing_input_index = 0;

            // prepare sign data
            let internal_node = current.internal_node.read().clone();
            let creation_node = current.creation_node.clone();
            let node_signing_job = creation_node.node_tx_signing_job.clone().unwrap();
            let serialized_node_transaction = node_signing_job.raw_tx;
            let user_node_commitments = node_signing_job.signing_nonce_commitment.clone().unwrap();
            let (spark_node_signature_shares, spark_node_public_shares, _, spark_node_commitments) =
                get_signature_data_from_signing_result(
                    &current.creation_response_node.node_tx_signing_result,
                )?;

            let signing_job = self.prepare_frost_signing_job(
                internal_node.signing_public_key.clone(),
                Some(serialize_marshalized_frost_commitments(
                    &user_node_commitments,
                )?),
                spark_node_commitments.clone(),
                serialized_node_transaction.clone(),
                node_prevout_index,
                node_signing_input_index,
                &current.parent_tx.clone(),
                vec![],
                internal_node.verification_key.clone().unwrap(),
            )?;

            // sign
            let node_signature = self.sign_frost(vec![signing_job.clone()]).unwrap();
            let user_node_signature_share = node_signature.results[&signing_job.job_id]
                .signature_share
                .clone();

            let aggregate_response = self
                .aggregate_frost(spark_protos::frost::AggregateFrostRequest {
                    message: signing_job.message,
                    signature_shares: spark_node_signature_shares,
                    public_shares: spark_node_public_shares,
                    verifying_key: signing_job.verifying_key.clone(),
                    commitments: spark_node_commitments,
                    user_commitments: signing_job.user_commitments,
                    user_public_key: signing_job.verifying_key,
                    user_signature_share: user_node_signature_share,
                    adaptor_public_key: vec![],
                })
                .unwrap();

            let mut node_signature = spark_protos::spark::NodeSignatures {
                node_id: current.creation_response_node.node_id.clone(),
                node_tx_signature: aggregate_response.signature,
                ..Default::default()
            };

            // Handle refund transaction if present
            if let Some(refund_signing_job) = current.creation_node.refund_tx_signing_job {
                // these are constants for tree creation
                let refund_prevout_index = 0;
                let refund_signing_input_index = 0_usize;

                // prepare signing data
                let serialized_refund_transaction = refund_signing_job.raw_tx;
                let user_refund_commitments = refund_signing_job.signing_nonce_commitment.unwrap();
                let (
                    spark_refund_signature_shares,
                    spark_refund_public_shares,
                    _,
                    spark_refund_commitments,
                ) = get_signature_data_from_signing_result(
                    &current.creation_response_node.refund_tx_signing_result,
                )?;

                let refund_signing_job = self.prepare_frost_signing_job(
                    internal_node.signing_public_key,
                    Some(serialize_marshalized_frost_commitments(
                        &user_refund_commitments,
                    )?),
                    spark_refund_commitments.clone(),
                    serialized_refund_transaction,
                    refund_prevout_index,
                    refund_signing_input_index,
                    &bitcoin_tx_from_bytes(&serialized_node_transaction)?,
                    vec![],
                    internal_node.verification_key.clone().unwrap(),
                )?;

                let refund_signature = self.sign_frost(vec![refund_signing_job.clone()])?;
                let user_refund_signature_share = refund_signature.results
                    [&refund_signing_job.job_id]
                    .signature_share
                    .clone();

                let aggregate_response = self
                    .aggregate_frost(spark_protos::frost::AggregateFrostRequest {
                        message: refund_signing_job.message,
                        signature_shares: spark_refund_signature_shares,
                        public_shares: spark_refund_public_shares,
                        verifying_key: refund_signing_job.verifying_key.clone(),
                        commitments: spark_refund_commitments,
                        user_commitments: refund_signing_job.user_commitments,
                        user_public_key: refund_signing_job.verifying_key,
                        user_signature_share: user_refund_signature_share,
                        adaptor_public_key: vec![],
                    })
                    .unwrap();

                node_signature.refund_tx_signature = aggregate_response.signature;
            }
            node_signatures.push(node_signature);

            // Push children to queue maintaining BFS order
            for (i, child) in current.creation_node.children.into_iter().enumerate() {
                queue.push_back(QueueItem {
                    parent_tx: bitcoin_tx_from_bytes(&serialized_node_transaction)?,
                    vout: i as u32,
                    internal_node: current.internal_node.read().children[i].clone(),
                    creation_node: child,
                    creation_response_node: current.creation_response_node.children[i].clone(),
                });
            }

            signing_public_keys.push(current.internal_node.read().signing_public_key.clone());
        }

        Ok((node_signatures, signing_public_keys))
    }

    fn sign_transfer_refunds(
        &self,
        leaf_data_map: &HashMap<String, LeafRefundSigningData>,
        operator_signing_results: &Vec<LeafRefundTxSigningResult>,
        adaptor_public_key: Vec<u8>,
    ) -> Result<Vec<spark_protos::spark::NodeSignatures>, SparkSdkError> {
        let mut user_signing_jobs = Vec::new();
        let mut job_to_aggregate_request_map = HashMap::new();
        let mut job_to_leaf_map = HashMap::new();

        for operator_result in operator_signing_results {
            let signing_input_index = 0;
            let prevout_to_use = 0;

            // TODO: this is an internal error if not found -- change the error to a client-side internal error
            let leaf_data = leaf_data_map.get(&operator_result.leaf_id).ok_or_else(|| {
                SparkSdkError::from(ValidationError::InvalidInput {
                    field: "Leaf data not found".to_string(),
                })
            })?;

            // prepare signing data
            let refund_tx_ = leaf_data.refund_tx.as_ref().unwrap();
            let serialized_refund_tx = serialize_bitcoin_transaction(refund_tx_)?;

            let (
                spark_refund_signature_shares,
                spark_refund_public_shares,
                _,
                spark_refund_commitments,
            ) = get_signature_data_from_signing_result(&operator_result.refund_tx_signing_result)?;

            let commitment_hiding = leaf_data.commitment.hiding.clone();
            let commitment_binding = leaf_data.commitment.binding.clone();
            let signing_commitments =
                frost_secp256k1_tr_unofficial::round1::SigningCommitments::new(
                    FrostNonceCommitment::deserialize(&commitment_hiding).unwrap(),
                    FrostNonceCommitment::deserialize(&commitment_binding).unwrap(),
                );

            // Calculate refund transaction sighash
            let signing_job = self.prepare_frost_signing_job(
                leaf_data.signing_public_key.serialize(),
                Some(signing_commitments.serialize().unwrap()),
                spark_refund_commitments.clone(),
                serialized_refund_tx,
                prevout_to_use,
                signing_input_index,
                &leaf_data.tx,
                adaptor_public_key.clone(),
                operator_result.verifying_key.clone(),
            )?;
            let signing_job_id = signing_job.job_id.clone();
            user_signing_jobs.push(signing_job.clone());

            job_to_leaf_map.insert(signing_job_id.clone(), operator_result.leaf_id.clone());

            // TODO: structure
            job_to_aggregate_request_map.insert(
                signing_job_id.clone(),
                AggregateFrostRequest {
                    message: signing_job.message,
                    signature_shares: spark_refund_signature_shares,
                    public_shares: spark_refund_public_shares,
                    verifying_key: operator_result.verifying_key.clone(),
                    commitments: spark_refund_commitments,
                    user_commitments: signing_job.user_commitments,
                    user_public_key: leaf_data.signing_public_key.serialize().to_vec(),
                    user_signature_share: vec![],
                    adaptor_public_key: vec![],
                },
            );
        }

        // Get user signatures
        let user_signatures = self.sign_frost(user_signing_jobs)?;

        // Process signatures and create node signatures
        let mut node_signatures = Vec::new();
        for (job_id, user_signature) in user_signatures.results {
            let mut request = job_to_aggregate_request_map
                .remove(&job_id)
                .ok_or_else(|| {
                    SparkSdkError::from(ValidationError::InvalidInput {
                        field: "Job ID not found".to_string(),
                    })
                })?;

            request.user_signature_share = user_signature.signature_share;

            let response = match self.aggregate_frost(request) {
                Ok(response) => response,
                Err(e) => {
                    return Err(SparkSdkError::from(CryptoError::InvalidInput {
                        field: format!("Failed to aggregate refund: {}", e).to_string(),
                    }));
                }
            };

            node_signatures.push(spark_protos::spark::NodeSignatures {
                node_id: job_to_leaf_map[&job_id].clone(),
                refund_tx_signature: response.signature,
                node_tx_signature: Vec::new(), // Empty byte array
            });
        }

        Ok(node_signatures)
    }

    fn sign_for_lightning_swap(
        &self,
        leaves: &Vec<LeafKeyTweak>,
        signing_commitments: &Vec<RequestedSigningCommitments>,
        receiver_identity_pubkey: PublicKey,
    ) -> Result<
        (
            SignFrostResponse,
            Vec<Vec<u8>>,
            Vec<ProtoSigningCommitments>,
        ),
        SparkSdkError,
    > {
        let mut signing_jobs = Vec::new();
        let mut refund_txs = vec![];

        let mut user_commitments = Vec::with_capacity(leaves.len());

        for (i, leaf) in leaves.iter().enumerate() {
            let node_tx = bitcoin_tx_from_bytes(&leaf.leaf.node_tx)?;

            let node_outpoint = bitcoin::OutPoint {
                txid: node_tx.compute_txid(),
                vout: 0,
            };

            let current_refund_tx = bitcoin_tx_from_bytes(&leaf.leaf.refund_tx)?;

            let next_sequence = next_sequence(current_refund_tx.input[0].sequence.0);

            let amount_sats = node_tx.output[0].value;

            let refund_tx = create_refund_tx(
                next_sequence,
                node_outpoint,
                amount_sats,
                &receiver_identity_pubkey,
                self.network.to_bitcoin_network(),
                &self.secp,
            )?;

            let refund_tx_buf = serialize_bitcoin_transaction(&refund_tx)?;
            refund_txs.push(refund_tx_buf);

            let sighash = sighash_from_tx(&refund_tx, 0, &node_tx.output[0])?;

            let user_commitment = self.generate_frost_signing_commitments()?;
            let user_nonce = self
                .sensitive_expose_nonces_from_commitments(&user_commitment.serialize().unwrap())?;

            let marshalized_frost_nonces = marshal_frost_nonces(&user_nonce)?;
            let marshalized_frost_commitments = marshal_frost_commitments(&user_commitment)?;

            user_commitments.push(marshalized_frost_commitments.clone());

            let signing_secret_key =
                self.sensitive_expose_secret_key_from_pubkey(&leaf.new_signing_public_key, false)?;
            let key_package = create_user_key_package(&signing_secret_key.secret_bytes());

            signing_jobs.push(FrostSigningJob {
                job_id: leaf.leaf.id.clone(),
                message: sighash.to_vec(),
                key_package: Some(key_package),
                verifying_key: leaf.leaf.verifying_public_key.clone(),
                nonce: Some(marshalized_frost_nonces),
                user_commitments: Some(marshalized_frost_commitments),
                commitments: signing_commitments[i].signing_nonce_commitments.clone(),
                adaptor_public_key: vec![],
            });
        }

        // sign
        let signing_results = self.sign_frost(signing_jobs)?;

        Ok((signing_results, refund_txs, user_commitments))
    }

    fn sign_root_creation(
        &self,
        signing_pubkey_bytes: Vec<u8>,
        verifying_pubkey_bytes: Vec<u8>,
        _root_tx_bytes: Vec<u8>,   // TODO: revisit the need here
        _refund_tx_bytes: Vec<u8>, // TODO: revisit the need here
        root_tx_sighash: Vec<u8>,
        refund_tx_sighash: Vec<u8>,
        root_nonce_commitment: FrostSigningCommitments,
        refund_nonce_commitment: FrostSigningCommitments,
        tree_creation_response: spark_protos::spark::StartTreeCreationResponse,
    ) -> Result<Vec<Vec<u8>>, SparkSdkError> {
        // Parse signatures, commitments, and public keys
        let signature_data = tree_creation_response
            .root_node_signature_shares
            .unwrap()
            .clone();
        let root_signature_data = signature_data.node_tx_signing_result.unwrap();
        let root_signature_shares = root_signature_data.signature_shares.clone();
        let root_nonce_commitments = root_signature_data.signing_nonce_commitments.clone();
        let root_pubkeys = root_signature_data.public_keys.clone();
        let refund_signature_data = signature_data.refund_tx_signing_result.unwrap();
        let refund_signature_shares = refund_signature_data.signature_shares.clone();
        let refund_nonce_commitments = refund_signature_data.signing_nonce_commitments.clone();
        let refund_pubkeys = refund_signature_data.public_keys.clone();

        let signing_key = self.sensitive_expose_secret_key_from_pubkey(
            &PublicKey::from_slice(&signing_pubkey_bytes)?,
            false,
        )?;
        let key_package = create_user_key_package(&signing_key.secret_bytes());

        let root_nonce_commitments_bytes = root_nonce_commitment.serialize().unwrap();
        let refund_nonce_commitments_bytes = refund_nonce_commitment.serialize().unwrap();

        let root_nonce =
            self.sensitive_expose_nonces_from_commitments(&root_nonce_commitments_bytes)?;
        let refund_nonce =
            self.sensitive_expose_nonces_from_commitments(&refund_nonce_commitments_bytes)?;

        // Prepare FROST signing jobs
        let node_job_id = Uuid::now_v7().to_string();
        let node_signing_job = FrostSigningJob {
            job_id: node_job_id.clone(),
            message: root_tx_sighash.clone(),
            commitments: root_nonce_commitments.clone(),
            key_package: Some(key_package.clone()),
            verifying_key: verifying_pubkey_bytes.clone(),
            nonce: Some(marshal_frost_nonces(&root_nonce)?),
            user_commitments: Some(marshal_frost_commitments(&root_nonce_commitment)?),
            adaptor_public_key: vec![],
        };

        let refund_job_id = Uuid::now_v7().to_string();
        let refund_signing_job = FrostSigningJob {
            job_id: refund_job_id.clone(),
            message: refund_tx_sighash.clone(),
            commitments: refund_nonce_commitments.clone(),
            key_package: Some(key_package),
            verifying_key: verifying_pubkey_bytes.clone(),
            nonce: Some(marshal_frost_nonces(&refund_nonce)?),
            user_commitments: Some(marshal_frost_commitments(&refund_nonce_commitment)?),
            adaptor_public_key: vec![],
        };

        let signing_results = self.sign_frost(vec![node_signing_job, refund_signing_job])?;

        // Parse signatures
        let signature_results = signing_results.results;
        let user_root_signature_share = signature_results[&node_job_id].signature_share.clone();
        let user_refund_signature_share = signature_results[&refund_job_id].signature_share.clone();

        let root_aggregation_request = AggregateFrostRequest {
            message: root_tx_sighash,
            signature_shares: root_signature_shares,
            public_shares: root_pubkeys,
            verifying_key: verifying_pubkey_bytes.clone(),
            commitments: root_nonce_commitments,
            user_commitments: Some(marshal_frost_commitments(&root_nonce_commitment)?),
            user_public_key: signing_pubkey_bytes.clone(),
            user_signature_share: user_root_signature_share,
            adaptor_public_key: vec![],
        };
        let refund_aggregation_request = AggregateFrostRequest {
            message: refund_tx_sighash,
            signature_shares: refund_signature_shares,
            public_shares: refund_pubkeys,
            verifying_key: verifying_pubkey_bytes.clone(),
            commitments: refund_nonce_commitments,
            user_commitments: Some(marshal_frost_commitments(&refund_nonce_commitment)?),
            user_public_key: signing_pubkey_bytes,
            user_signature_share: user_refund_signature_share,
            adaptor_public_key: vec![],
        };

        let complete_root_signature = self.aggregate_frost(root_aggregation_request)?;
        let complete_refund_signature = self.aggregate_frost(refund_aggregation_request)?;

        let root_sig = complete_root_signature.signature;
        let refund_sig = complete_refund_signature.signature;

        Ok(vec![root_sig, refund_sig])
    }

    fn sign_frost_new(
        &self,
        message: Vec<u8>,
        private_as_pubkey: Vec<u8>,
        verifying_key: Vec<u8>,
        self_commitment: FrostSigningCommitments,
        spark_commitments: HashMap<String, SigningCommitment>,
        adaptor_public_key: Option<Vec<u8>>,
    ) -> Result<Vec<u8>, SparkSdkError> {
        // get the signing key and the nonce
        let signing_private_key = self.sensitive_expose_secret_key_from_pubkey(
            &PublicKey::from_slice(&private_as_pubkey)?,
            false,
        )?;
        let self_commtiment_bytes = self_commitment.serialize().map_err(|e| {
            SparkSdkError::from(CryptoError::FrostSigning {
                job_id: e.to_string(),
            })
        })?;
        let nonce = self.sensitive_expose_nonces_from_commitments(&self_commtiment_bytes)?;

        // create key package
        let key_package = create_user_key_package(&signing_private_key.secret_bytes());

        // unwrap or use empty vector for the adaptor public key
        let adaptor_public_key = adaptor_public_key.unwrap_or_default();

        // construct the signing job
        let job_id = Uuid::now_v7().to_string();
        let signing_job = FrostSigningJob {
            job_id: job_id.clone(),
            message,
            key_package: Some(key_package),
            verifying_key,
            nonce: Some(marshal_frost_nonces(&nonce)?),
            commitments: spark_commitments,
            user_commitments: Some(marshal_frost_commitments(&self_commitment)?),
            adaptor_public_key,
        };

        let sign_frost_request = SignFrostRequest {
            signing_jobs: vec![signing_job],
            role: FROST_USER_SIGNING_ROLE,
        };

        // sign the message
        let signature = match sign_frost(&sign_frost_request) {
            Ok(signature) => signature,
            Err(e) => {
                return Err(SparkSdkError::from(CryptoError::FrostSigning {
                    job_id: e.to_string(),
                }));
            }
        };

        // expect the signature with the job id
        let signature = signature.results.get(&job_id);
        if signature.is_none() {
            return Err(SparkSdkError::from(CryptoError::FrostSignatureNotFound {
                job_id,
            }));
        }

        Ok(signature.unwrap().signature_share.clone())
    }
}

#[async_trait]
impl SparkSigner for DefaultSigner {
    type WrappedSigner = Arc<Self>;

    /// Creates a new wallet from a mnemonic (BIP-39).
    ///  - Converts the mnemonic to a 64-byte seed
    ///  - Calls `from_seed` to do the rest
    async fn from_mnemonic(
        mnemonic: &str,
        network: SparkNetwork,
    ) -> Result<Self::WrappedSigner, SparkSdkError> {
        // Generate the BIP-39 seed
        let seed_bytes = bip39::Mnemonic::parse(mnemonic)
            .map_err(|e| {
                SparkSdkError::from(CryptoError::InvalidInput {
                    field: e.to_string(),
                })
            })?
            .to_seed("");
        // let seed_bytes = seed.as_bytes().to_vec();

        Self::from_master_seed(&seed_bytes, network).await
    }

    async fn from_master_seed(
        master_seed: &[u8],
        network: SparkNetwork,
    ) -> Result<Self::WrappedSigner, SparkSdkError> {
        let nonce_commitments = HashbrownMap::new();
        let public_keys_to_secret_keys = HashbrownMap::new();

        let commitments_map = Arc::new(RwLock::new(nonce_commitments));
        let public_keys_map = Arc::new(RwLock::new(public_keys_to_secret_keys));

        Ok(Arc::new(Self {
            master_seed: master_seed.to_vec(),
            nonce_commitments: commitments_map,
            public_keys_to_secret_keys: public_keys_map,
            network,
            secp: Secp256k1::new(),
        }))
    }
}

const INVALID_SECRET_KEY_ERROR: &str =
    "Could not find secret key in the signer space. Public key used as the index: ";
impl DefaultSigner {
    /// Loads the master seed from the signer instance.
    ///
    /// # Returns
    /// A clone of the master seed as a byte vector
    ///
    /// # Errors
    /// Returns a `SparkSdkError` if the master seed cannot be loaded
    pub(crate) fn load_master_seed(&self) -> Result<Vec<u8>, SparkSdkError> {
        Ok(self.master_seed.clone())
    }

    /// Retrieves the identity secret key for this signer.
    ///
    /// Derives the identity key from the master seed using the predefined
    /// IDENTITY_KEYPAIR_INDEX.
    ///
    /// # Returns
    /// The identity secret key as a byte vector
    ///
    /// # Errors
    /// Returns a `SparkSdkError` if key derivation fails
    pub(crate) fn get_identity_secret_key(
        &self,
        account_index: u32,
        network: Network,
    ) -> Result<SecretKey, SparkSdkError> {
        let master_seed_bytes = self.load_master_seed()?;
        let master_seed = Xpriv::new_master(network, &master_seed_bytes)
            .map_err(|_| SparkSdkError::from(CryptoError::InvalidSeed))?;

        let identity_derivation_path = Self::get_identity_derivation_path(account_index)?;

        let identity_key = master_seed
            .derive_priv(&self.secp, &*identity_derivation_path)
            .map_err(|_| {
                SparkSdkError::from(CryptoError::ChildKeyDerivationError {
                    derivation_path: format!("{:?}", identity_derivation_path),
                })
            })?;

        Ok(identity_key.private_key)
    }

    /// Retrieves a secret key from the in-memory key store by its public key.
    ///
    /// # Arguments
    /// * `public_key` - The public key whose corresponding secret key should be retrieved
    ///
    /// # Returns
    /// The corresponding secret key as a byte vector
    ///
    /// # Errors
    /// Returns a `SparkSdkError` if the public key is not found in the key store
    pub(crate) fn get_secret_key_from_pubkey(
        &self,
        public_key: &PublicKey,
    ) -> Result<SecretKey, SparkSdkError> {
        self.public_keys_to_secret_keys
            .read()
            .get(public_key)
            .cloned()
            .ok_or_else(|| {
                SparkSdkError::from(ValidationError::InvalidInput {
                    field: format!("{} {}", INVALID_SECRET_KEY_ERROR, public_key).to_string(),
                })
            })
    }

    /// Inserts a keypair into the in-memory key store.
    ///
    /// # Arguments
    /// * `public_key` - The public key to store
    /// * `secret_key` - The corresponding secret key to store
    ///
    /// # Returns
    /// `Ok(())` if the insertion was successful
    ///
    /// # Errors
    /// Returns a `SparkSdkError` if the insertion fails
    pub(crate) fn insert_to_keypair_map(
        &self,
        public_key: &PublicKey,
        secret_key: &SecretKey,
    ) -> Result<(), SparkSdkError> {
        self.public_keys_to_secret_keys
            .write()
            .insert(*public_key, *secret_key);

        Ok(())
    }

    /// Removes a keypair from the in-memory key store by its public key.
    ///
    /// # Arguments
    /// * `public_key` - The public key of the keypair to remove
    ///
    /// # Returns
    /// `Ok(())` if the removal was successful or if the key wasn't present
    ///
    /// # Errors
    /// Returns a `SparkSdkError` if the removal fails due to a lock issue
    pub(crate) fn evict_from_keypair_map(
        &self,
        public_key: &PublicKey,
    ) -> Result<(), SparkSdkError> {
        self.public_keys_to_secret_keys.write().remove(public_key);

        Ok(())
    }

    /// Inserts a nonce pair into the in-memory nonce commitment store.
    ///
    /// # Arguments
    /// * `nonce_commitment` - The nonce commitment to store
    /// * `nonce` - The corresponding nonce to store
    ///
    /// # Returns
    /// `Ok(())` if the insertion was successful
    ///
    /// # Errors
    /// Returns a `SparkSdkError` if the insertion fails due to a lock issue
    pub(crate) fn insert_to_noncepair_map<T: AsRef<[u8]>, U: AsRef<[u8]>>(
        &self,
        nonce_commitment: T,
        nonce: U,
    ) -> Result<(), SparkSdkError> {
        let nonce_commitment_hex = hex_encode(nonce_commitment);
        let nonce_hex = hex_encode(nonce);

        self.nonce_commitments
            .write()
            .insert(nonce_commitment_hex.clone(), nonce_hex.clone());

        Ok(())
    }

    /// Prepares a FROST signing job for a node transaction by assembling all required components.
    ///
    /// # Arguments
    /// * `signing_public_key` - The public key corresponding to the secret key that will be used for signing
    /// * `user_frost_commitments` - The user's FROST nonce commitments in serialized form. If user has no commitments at the time, pass in None, and the function will generate them.
    /// * `spark_frost_commitments` - Map of operator IDs to their FROST commitments
    /// * `serialized_bitcoin_tx` - The Bitcoin transaction to be signed in serialized form
    /// * `prevout_to_use` - Index of the previous output being spent
    /// * `signing_input_index` - Index of the input being signed
    /// * `parent_tx` - The parent transaction containing the output being spent
    /// * `adaptor_public_key` - Public key used for adaptor signatures (if any)
    /// * `verifying_key` - The verification key for the FROST signing session
    ///
    /// # Returns
    /// A [`FrostSigningJob`] containing:
    /// - A unique job ID
    /// - The message to be signed (transaction sighash)
    /// - The key package containing signing material
    /// - The verification key
    /// - Marshaled nonces and commitments from both user and operators
    /// - The adaptor public key
    ///
    /// # Errors
    /// Returns [`SparkSdkError`] if:
    /// - Secret key exposure fails
    /// - Nonce exposure fails
    /// - Marshaling of nonces/commitments fails
    /// - Transaction decoding fails
    /// - Sighash calculation fails
    #[allow(clippy::too_many_arguments)]
    fn prepare_frost_signing_job<T: AsRef<[u8]>>(
        &self,
        signing_public_key: T,
        user_frost_commitments: Option<Vec<u8>>,
        spark_frost_commitments: HashMap<String, SparkOperatorCommitment>,
        serialized_bitcoin_tx: Vec<u8>,
        prevout_to_use: usize,
        signing_input_index: usize,
        parent_tx: &Transaction,
        adaptor_public_key: Vec<u8>,
        verifying_key: Vec<u8>,
    ) -> Result<FrostSigningJob, SparkSdkError> {
        let job_id = generate_signing_job_id();

        // expose the secret key, expose and marshal signing nonces
        let signing_secret_key = self.sensitive_expose_secret_key_from_pubkey(
            &PublicKey::from_slice(signing_public_key.as_ref())?,
            false,
        )?;

        // get user frost commitments, if none, generate new ones
        let commitments = if let Some(commitments) = user_frost_commitments.as_deref() {
            commitments.to_vec()
        } else {
            let commitments = self.generate_frost_signing_commitments()?;
            commitments.serialize().unwrap().clone()
        };
        let frost_nonces = self.sensitive_expose_nonces_from_commitments(&commitments)?;

        // marshal the nonces and commitments
        let marshalized_frost_nonces = marshal_frost_nonces(&frost_nonces)?;
        let marshalized_frost_commitments = marshal_frost_commitments(frost_nonces.commitments())?;

        let key_package = create_user_key_package(&signing_secret_key.secret_bytes());
        let transaction = bitcoin_tx_from_bytes(&serialized_bitcoin_tx)?;

        let sighash = sighash_from_tx_new(
            &transaction,
            signing_input_index,
            &parent_tx.output[prevout_to_use],
        )?;
        let message = sighash.to_vec();

        Ok(FrostSigningJob {
            job_id,
            message,
            key_package: Some(key_package),
            verifying_key,
            nonce: Some(marshalized_frost_nonces),
            commitments: spark_frost_commitments,
            user_commitments: Some(marshalized_frost_commitments),
            adaptor_public_key,
        })
    }
}

/// Creates a FROST key package for the user.
///
/// This function constructs a protocol buffer representation of a user's key package
/// using the provided signing secret key.
///
/// # Arguments
/// * `signing_secret_key` - The secret key bytes to use for the key package
///
/// # Returns
/// A protocol buffer KeyPackage containing the user's identity and key information
pub(crate) fn create_user_key_package(
    signing_secret_key: &[u8],
) -> spark_protos::frost::KeyPackage {
    let user_identifier = FROST_USER_IDENTIFIER;
    let secp = Secp256k1::new();
    let secret_key = SecretKey::from_slice(signing_secret_key).unwrap();
    let public_key = PublicKey::from_secret_key(&secp, &secret_key);

    let mut public_shares = HashMap::new();
    public_shares.insert(user_identifier.to_string(), public_key.serialize().to_vec());

    spark_protos::frost::KeyPackage {
        identifier: user_identifier.to_string(),
        secret_share: signing_secret_key.to_vec(),
        public_shares,
        public_key: public_key.serialize().to_vec(),
        min_signers: FROST_USER_KEY_PACKAGE_MIN_SIGNERS,
    }
}

use spark_protos::common::SigningCommitment as ProtoSigningCommitments;
/// Converts FROST signing commitments to the protocol buffer format.
///
/// # Arguments
/// * `commitments` - The FROST signing commitments to convert
///
/// # Returns
/// A `ProtoSigningCommitments` containing the serialized hiding and binding commitments
///
/// # Errors
/// Returns a `SparkSdkError` if marshalling fails
pub(crate) fn marshal_frost_commitments(
    commitments: &FrostSigningCommitments,
) -> Result<ProtoSigningCommitments, SparkSdkError> {
    let hiding = commitments.hiding().serialize().unwrap();
    let binding = commitments.binding().serialize().unwrap();

    Ok(ProtoSigningCommitments { hiding, binding })
}

use spark_protos::frost::SigningNonce as ProtoSigningNonce;
/// Converts FROST signing nonces to the protocol buffer format.
///
/// # Arguments
/// * `nonce` - The FROST signing nonces to convert
///
/// # Returns
/// A `ProtoSigningNonce` containing the serialized hiding and binding nonces
///
/// # Errors
/// Returns a `SparkSdkError` if marshalling fails
pub(crate) fn marshal_frost_nonces(
    nonce: &FrostSigningNonces,
) -> Result<ProtoSigningNonce, SparkSdkError> {
    let hiding = nonce.hiding().serialize();
    let binding = nonce.binding().serialize();

    Ok(ProtoSigningNonce { hiding, binding })
}

/// Converts protocol buffer signing nonces back to FROST signing nonces.
///
/// # Arguments
/// * `nonce` - The protocol buffer nonces to convert
///
/// # Returns
/// The deserialized `FrostSigningNonces`
///
/// # Errors
/// Returns a `SparkSdkError` if unmarshalling fails
pub(crate) fn _unmarshal_frost_nonces(
    nonce: &ProtoSigningNonce,
) -> Result<FrostSigningNonces, SparkSdkError> {
    let hiding_nonce = FrostNonce::deserialize(&nonce.hiding).unwrap();
    let binding_nonce = FrostNonce::deserialize(&nonce.binding).unwrap();

    Ok(FrostSigningNonces::from_nonces(hiding_nonce, binding_nonce))
}

/// Serializes protocol buffer signing commitments to a byte vector.
///
/// # Arguments
/// * `commitments` - The protocol buffer commitments to serialize
///
/// # Returns
/// A byte vector containing the serialized commitments with a specific prefix format
///
/// # Errors
/// Returns a `SparkSdkError` if serialization fails
fn serialize_marshalized_frost_commitments(
    commitments: &ProtoSigningCommitments,
) -> Result<Vec<u8>, SparkSdkError> {
    let hiding = commitments.hiding.clone();
    let binding = commitments.binding.clone();

    let prefix_hex = "00230f8ab3";
    let hiding_hex = hex_encode(&hiding);
    let binding_hex = hex_encode(&binding);

    let commitments_hex = format!("{}{}{}", prefix_hex, hiding_hex, binding_hex);
    Ok(hex_decode(&commitments_hex).unwrap())
}

/// Generates a unique identifier for a signing job using UUID v7.
///
/// # Returns
/// A string containing a time-ordered UUID v7 for tracking signing jobs
fn generate_signing_job_id() -> String {
    Uuid::now_v7().to_string()
}

/// Map type for storing signature shares keyed by participant identifier.
type SignatureSharesType = HashMap<String, Vec<u8>>;
/// Map type for storing public key shares keyed by participant identifier.
type PublicSharesType = HashMap<String, Vec<u8>>;
/// Optional type for storing signing keyshare data.
type SigningKeyshareType = Option<SigningKeyshare>;
/// Map type for storing operator signing commitments keyed by participant identifier.
type SigningCommitmentsType = HashMap<String, SparkOperatorCommitment>;

/// Extracts signature data components from a FROST signing result.
///
/// # Arguments
/// * `signing_result` - The optional signing result containing signature shares, public keys,
///
/// # Returns
/// A tuple containing:
/// * `SignatureSharesType` - Map of participant IDs to their signature shares
/// * `PublicSharesType` - Map of participant IDs to their public key shares
/// * `SigningKeyshareType` - Optional signing keyshare data
/// * `SigningCommitmentsType` - Map of participant IDs to their signing commitments
///
/// # Errors
/// Returns a `SparkSdkError` if the signing result is `None` or invalid
fn get_signature_data_from_signing_result(
    signing_result: &Option<SigningResult>,
) -> Result<
    (
        SignatureSharesType,
        PublicSharesType,
        SigningKeyshareType,
        SigningCommitmentsType,
    ),
    SparkSdkError,
> {
    let signing_result = signing_result.clone().unwrap();
    let signature_shares = signing_result.signature_shares;
    let public_shares = signing_result.public_keys;
    let signing_keyshare = signing_result.signing_keyshare;
    let commitments = signing_result.signing_nonce_commitments;

    Ok((
        signature_shares,
        public_shares,
        signing_keyshare,
        commitments,
    ))
}

/// Creates a Bitcoin refund transaction.
///
/// This function builds a refund transaction using the specified input parameters
/// and creates appropriate outputs to spend from the specified outpoint.
///
/// # Arguments
/// * `sequence` - The sequence number to use for the transaction input
/// * `node_outpoint` - The outpoint to spend from
/// * `amount_sats` - The amount in satoshis to send to the receiving address
/// * `receiving_pubkey` - The public key that will receive the funds
/// * `network` - The Bitcoin network to use for address encoding
///
/// # Returns
/// A Bitcoin transaction ready to be signed
///
/// # Errors
/// Returns a `SparkSdkError` if transaction creation fails
fn create_refund_tx(
    sequence: u32,
    node_outpoint: bitcoin::OutPoint,
    amount_sats: bitcoin::Amount,
    receiving_pubkey: &bitcoin::secp256k1::PublicKey,
    network: bitcoin::Network,
    secp: &Secp256k1<All>,
) -> Result<bitcoin::Transaction, SparkSdkError> {
    let mut new_refund_tx = bitcoin::Transaction {
        version: bitcoin::transaction::Version::TWO,
        lock_time: bitcoin::absolute::LockTime::ZERO,
        input: vec![],
        output: vec![],
    };

    new_refund_tx.input.push(bitcoin::TxIn {
        previous_output: node_outpoint,
        script_sig: bitcoin::ScriptBuf::default(),
        sequence: bitcoin::Sequence(sequence),
        witness: bitcoin::Witness::default(),
    });

    let addr = bitcoin::Address::p2tr(secp, receiving_pubkey.x_only_public_key().0, None, network);
    let refund_pk_script = addr.script_pubkey();

    new_refund_tx.output.push(bitcoin::TxOut {
        value: amount_sats,
        script_pubkey: refund_pk_script,
    });

    new_refund_tx.output.push(ephemeral_anchor_output());

    Ok(new_refund_tx)
}

#[cfg(test)]
mod frost_to_proto_conversions_test {
    use super::*;

    fn test_unmarshal_frost_commitments(
        commitment: &ProtoSigningCommitments,
    ) -> Result<FrostSigningCommitments, SparkSdkError> {
        let hiding = commitment.hiding.clone();
        let binding = commitment.binding.clone();

        let hiding_nonce = FrostNonceCommitment::deserialize(&hiding).unwrap();
        let binding_nonce = FrostNonceCommitment::deserialize(&binding).unwrap();

        Ok(FrostSigningCommitments::new(hiding_nonce, binding_nonce))
    }

    #[test]
    fn test_frost_to_proto_conversions() {
        let hiding_sk = SecretKey::new(&mut rand::thread_rng());
        let binding_sk = SecretKey::new(&mut rand::thread_rng());
        let hiding_sk_bytes = hiding_sk.secret_bytes().to_vec();
        let binding_sk_bytes = binding_sk.secret_bytes().to_vec();

        let hiding_nonce = FrostNonce::deserialize(&hiding_sk_bytes).unwrap();
        let binding_nonce = FrostNonce::deserialize(&binding_sk_bytes).unwrap();

        // Create nonces and commitments
        let frost_nonces = FrostSigningNonces::from_nonces(hiding_nonce, binding_nonce);
        let frost_commitments = frost_nonces.commitments();

        // Marshal and unmarshal nonces
        let marshalized_nonces = marshal_frost_nonces(&frost_nonces).unwrap();
        let unmarshalized_nonces = _unmarshal_frost_nonces(&marshalized_nonces).unwrap();

        // Marshal and unmarshal commitments
        let marshalized_commitments = marshal_frost_commitments(frost_commitments).unwrap();
        let unmarshalized_commitments =
            test_unmarshal_frost_commitments(&marshalized_commitments).unwrap();

        // Assert that the nonces and commitments are the same
        assert_eq!(frost_nonces, unmarshalized_nonces);
        assert_eq!(frost_commitments, &unmarshalized_commitments);
    }
}