spark_rust/signer/traits/

frost_signing.rs

//! # FROST threshold signing operations for Spark wallet
//!
//! This module defines the FROST (Flexible Round-Optimized Schnorr Threshold) signing
//! capabilities for the Spark wallet. FROST is the threshold signature scheme used by
//! Spark to enable secure multi-party signing, where both the user and Spark Operators
//! participate in creating signatures without revealing their private keys.
//!
//! The module supports:
//! - Creating and verifying FROST signature shares
//! - Aggregating signature shares into complete signatures
//! - Specialized signing methods for various Spark operations
//!
//! In Spark's security model, threshold signing is critical because it ensures that:
//! 1. Neither the user nor Spark Operators alone can spend funds
//! 2. Signatures appear as standard Schnorr signatures on-chain
//! 3. The user maintains control of their portion of the signing key
//!
//! This implementation is customized to support Taproot tweaking, enabling
//! compatibility with Bitcoin's Taproot script system.

// use std::cell::RefCell;
use std::collections::HashMap;
use std::sync::Arc;

use bitcoin::secp256k1::PublicKey;
use frost_secp256k1_tr_unofficial::round1::SigningCommitments;
use parking_lot::RwLock;
use spark_protos::common::SigningCommitment;
use spark_protos::frost::AggregateFrostRequest;
use spark_protos::frost::AggregateFrostResponse;
use spark_protos::frost::FrostSigningJob;
use spark_protos::frost::SignFrostResponse;
use spark_protos::spark::LeafRefundTxSigningResult;
use spark_protos::spark::NodeSignatures;
use spark_protos::spark::RequestedSigningCommitments;

use crate::error::SparkSdkError;
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;

/// Trait for FROST threshold signing operations in the Spark wallet.
///
/// This trait provides methods for performing threshold signing using the FROST
/// (Flexible Round-Optimized Schnorr Threshold) protocol. FROST enables multiple
/// parties (the user and Spark Operators) to jointly sign a message without revealing
/// their private keys.
///
/// In the Spark protocol, FROST signing is used for:
/// - Signing Bitcoin transactions on leaves (UTXOs)
/// - Creating refund transactions for security guarantees
/// - Facilitating Lightning Network operations
/// - Supporting deposit address creation
///
/// The implementation is customized to support Taproot tweaking, allowing
/// compatibility with Bitcoin's Taproot script system while maintaining the
/// security properties of threshold signatures.
pub trait SparkSignerFrostSigning {
    /// Signs messages using the FROST threshold signature scheme.
    ///
    /// This method generates signature shares for a set of signing jobs.
    /// Each job represents a distinct message to be signed with a specific
    /// key and set of participants.
    ///
    /// # Arguments
    /// * `signing_jobs` - A vector of `FrostSigningJob` objects, each containing:
    ///   - The message to sign
    ///   - The key package (containing signing material)
    ///   - The verifying key
    ///   - Nonce commitments from all participants
    ///   - Optional adaptor public key for adaptor signatures
    ///
    /// # Returns
    /// * `Ok(SignFrostResponse)` - Contains the generated signature shares for each job
    /// * `Err(SparkSdkError)` - If signing fails for any reason
    ///
    /// # Security Considerations
    /// The security of FROST depends on proper nonce generation. The implementation
    /// should ensure nonces are never reused for different messages.
    fn sign_frost(
        &self,
        signing_jobs: Vec<FrostSigningJob>,
    ) -> Result<SignFrostResponse, SparkSdkError>;

    /// Aggregates multiple FROST signature shares into a complete signature.
    ///
    /// This method combines signature shares from all participants (the user and
    /// Spark Operators) into a single signature that can be verified using the
    /// threshold public key.
    ///
    /// # Arguments
    /// * `request` - An `AggregateFrostRequest` containing:
    ///   - The message that was signed
    ///   - Signature shares from all participants
    ///   - Public key shares from all participants
    ///   - The verifying key (threshold public key)
    ///   - Nonce commitments from all participants
    ///   - Optional adaptor public key for adaptor signatures
    ///
    /// # Returns
    /// * `Ok(AggregateFrostResponse)` - Contains the aggregated signature
    /// * `Err(SparkSdkError)` - If aggregation fails
    ///
    /// # Security Considerations
    /// The aggregation process must verify that all signature shares are valid
    /// before combining them to prevent rogue key attacks.
    fn aggregate_frost(
        &self,
        request: AggregateFrostRequest,
    ) -> Result<AggregateFrostResponse, SparkSdkError>;

    /// Signs all nodes in a deposit tree in breadth-first order.
    ///
    /// This method traverses a deposit tree structure and signs each node's transaction
    /// and refund transaction using FROST. The tree represents a hierarchical structure
    /// of UTXOs created during the deposit process.
    ///
    /// # Arguments
    /// * `tx` - The parent transaction for the tree
    /// * `vout` - The output index in the parent transaction
    /// * `internal_tree_root` - The root of the internal tree structure
    /// * `request_tree_root` - The tree creation request data
    /// * `creation_result_tree_root` - The tree creation response data containing operator signatures
    ///
    /// # Returns
    /// * `Ok((Vec<NodeSignatures>, Vec<Vec<u8>>))` - Contains:
    ///   - Signatures for each node in the tree
    ///   - The signing public keys used
    /// * `Err(SparkSdkError)` - If signing fails for any node
    fn sign_created_tree_in_bfs_order(
        &self,
        tx: bitcoin::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>;

    /// Signs refund transactions for transfer leaves.
    ///
    /// This method signs refund transactions that provide security guarantees
    /// during transfers. Refund transactions allow the user to recover funds
    /// in case the transfer process is interrupted.
    ///
    /// # Arguments
    /// * `leaf_data_map` - A map of leaf IDs to their refund signing data
    /// * `operator_signing_results` - Signature shares from Spark Operators
    /// * `adaptor_public_key` - Public key used for adaptor signatures
    ///
    /// # Returns
    /// * `Ok(Vec<NodeSignatures>)` - Signatures for each refund transaction
    /// * `Err(SparkSdkError)` - If signing fails for any refund transaction
    fn sign_transfer_refunds(
        &self,
        leaf_data_map: &HashMap<String, LeafRefundSigningData>,
        operator_signing_results: &Vec<LeafRefundTxSigningResult>,
        adaptor_public_key: Vec<u8>,
    ) -> Result<Vec<NodeSignatures>, SparkSdkError>;

    /// Signs transactions for a Lightning swap operation.
    ///
    /// This method generates signatures for transactions involved in a Lightning
    /// payment, where the user's leaves are swapped with the SSP in exchange for
    /// the Lightning payment execution.
    ///
    /// # Arguments
    /// * `leaves` - The leaves involved in the swap
    /// * `signing_commitments` - Nonce commitments for signing
    /// * `receiver_identity_pubkey` - The identity public key of the receiver
    ///
    /// # Returns
    /// * `Ok((SignFrostResponse, Vec<Vec<u8>>, Vec<SigningCommitment>))` - Contains:
    ///   - The signature shares
    ///   - The refund transaction data
    ///   - The user's signing commitments
    /// * `Err(SparkSdkError)` - If signing fails
    #[allow(clippy::type_complexity)]
    fn sign_for_lightning_swap(
        &self,
        leaves: &Vec<LeafKeyTweak>,
        signing_commitments: &Vec<RequestedSigningCommitments>,
        receiver_identity_pubkey: PublicKey,
    ) -> Result<(SignFrostResponse, Vec<Vec<u8>>, Vec<SigningCommitment>), SparkSdkError>;

    /// Signs root node and refund transactions during tree creation.
    ///
    /// This method signs the root node transaction and its corresponding refund
    /// transaction during the deposit tree creation process.
    ///
    /// # Arguments
    /// * `signing_pubkey_bytes` - The signing public key as bytes
    /// * `verifying_pubkey_bytes` - The verifying public key as bytes
    /// * `root_tx_bytes` - The root transaction bytes
    /// * `refund_tx_bytes` - The refund transaction bytes
    /// * `root_tx_sighash` - The sighash of the root transaction
    /// * `refund_tx_sighash` - The sighash of the refund transaction
    /// * `root_nonce_commitment` - Nonce commitment for the root transaction
    /// * `refund_nonce_commitment` - Nonce commitment for the refund transaction
    /// * `tree_creation_response` - Response from Spark Operators with their signature shares
    ///
    /// # Returns
    /// * `Ok(Vec<Vec<u8>>)` - Signatures for the root and refund transactions
    /// * `Err(SparkSdkError)` - If signing fails
    fn sign_root_creation(
        &self,
        signing_pubkey_bytes: Vec<u8>,
        verifying_pubkey_bytes: Vec<u8>,
        root_tx_bytes: Vec<u8>,
        refund_tx_bytes: Vec<u8>,
        root_tx_sighash: Vec<u8>,
        refund_tx_sighash: Vec<u8>,
        root_nonce_commitment: SigningCommitments,
        refund_nonce_commitment: SigningCommitments,
        tree_creation_response: spark_protos::spark::StartTreeCreationResponse,
    ) -> Result<Vec<Vec<u8>>, SparkSdkError>;

    /// Signs a message using the new FROST signing flow.
    ///
    /// This is an improved signing method that provides a more streamlined
    /// interface for FROST signing operations.
    ///
    /// # Arguments
    /// * `message` - The message to sign
    /// * `private_as_pubkey` - The private key represented as a public key (for lookup)
    /// * `verifying_key` - The verifying key for signature verification
    /// * `self_commitment` - The user's nonce commitment
    /// * `spark_commitments` - Nonce commitments from Spark Operators
    /// * `adaptor_public_key` - Optional adaptor public key for adaptor signatures
    ///
    /// # Returns
    /// * `Ok(Vec<u8>)` - The signature share
    /// * `Err(SparkSdkError)` - If signing fails
    fn sign_frost_new(
        &self,
        message: Vec<u8>,
        private_as_pubkey: Vec<u8>,
        verifying_key: Vec<u8>,
        self_commitment: SigningCommitments,
        spark_commitments: HashMap<String, SigningCommitment>,
        adaptor_public_key: Option<Vec<u8>>,
    ) -> Result<Vec<u8>, SparkSdkError>;
}