spark_rust/signer/traits/

derivation_path.rs

//! # Key derivation path handling for Spark wallet
//!
//! This module implements the key derivation scheme for the Spark wallet, following
//! BIP43 conventions with a custom purpose identifier. The scheme is structured as:
//!
//! - Identity key: m/8797555'/account'/0'
//! - Base signing key: m/8797555'/account'/1'
//! - Temporary signing key: m/8797555'/account'/2'
//!
//! For leaf keys, an additional index is derived from the leaf ID:
//! - Leaf key: m/8797555'/account'/1'/hash(leaf_id)'
//!
//! The purpose value 8797555 is derived as the last 3 bytes of sha256("spark") in decimal (863d73).
//!
//! All indices use hardened derivation (denoted by the apostrophe) for enhanced security.
//! Account indices should start from 0.
//!
//! ## Security and Compatibility
//!
//! This derivation path scheme is **critical** for compatibility with other Spark wallets.
//! All Spark wallets must follow this exact scheme to ensure interoperability and proper
//! handling of funds within the Spark ecosystem.
//!
//! # WARNING
//!
//! Implementing this trait with non-standard derivation paths will make your wallet
//! incompatible with the Spark ecosystem. Only implement this trait if you fully understand
//! the consequences and are intentionally creating a non-standard wallet.

use crate::error::SparkSdkError;

use bitcoin::{
    bip32::ChildNumber,
    secp256k1::{PublicKey, SecretKey},
    Network,
};

/// Represents a BIP32 derivation path for wallet keys.
///
/// This struct wraps a vector of `ChildNumber` values that define a complete
/// derivation path for HD wallet keys. It provides convenience methods for
/// formatting and accessing the path components.
///
/// # Examples
///
/// ```
/// # use spark_rust::signer::traits::derivation_path::SparkDerivationPath;
/// # use bitcoin::bip32::ChildNumber;
/// # fn example() {
/// // Create a path with purpose, account, key type (identity)
/// let purpose = ChildNumber::from_hardened_idx(8797555).unwrap();
/// let account = ChildNumber::from_hardened_idx(0).unwrap();
/// let key_type = ChildNumber::from_hardened_idx(0).unwrap();
///
/// let path = SparkDerivationPath(vec![purpose, account, key_type]);
///
/// // Format as string: "m/8797555'/0'/0'"
/// let path_str = path.to_string();
/// # }
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SparkDerivationPath(pub(crate) Vec<ChildNumber>);

impl std::ops::Deref for SparkDerivationPath {
    type Target = Vec<ChildNumber>;

    fn deref(&self) -> &Self::Target {
        &self.0
    }
}

impl std::fmt::Display for SparkDerivationPath {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let mut output = String::new();

        // Only add the "m/" prefix for paths with more than one element
        // For single-element paths (like leaf indices), don't add the prefix
        if self.0.len() > 1 {
            output.push('m');
        }

        // Format each child number in the path
        for (i, child_number) in self.0.iter().enumerate() {
            // Only add slash if it's not the first element or if we have the m/ prefix
            if i > 0 || self.0.len() > 1 {
                output.push('/');
            }

            // Get the index value
            let index = match child_number {
                ChildNumber::Hardened { index } => index,
                ChildNumber::Normal { index } => index,
            };

            // Write the index
            output.push_str(&index.to_string());

            // Add apostrophe for hardened indices
            if child_number.is_hardened() {
                output.push('\'');
            }
        }

        write!(f, "{}", output)
    }
}

/// Key types for Spark wallet.
///
/// Each key type corresponds to a specific path in the hierarchical deterministic
/// wallet structure, with the path format: m/8797555'/account'/key_type'
///
/// The key types serve different purposes in the Spark wallet:
/// - Identity key: Used for wallet authentication and identification
/// - Base signing key: Used as the foundation for leaf-specific keys
/// - Temporary signing key: Used for one-time operations like deposits
///
/// These key types are encoded as the third component in the derivation path.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SparkKeyType {
    /// Identity key with path m/8797555'/account'/0'
    ///
    /// This key is used for wallet authentication, identification,
    /// and signature verification with Spark Operators.
    Identity,

    /// Base signing key with path m/8797555'/account'/1'
    ///
    /// This key serves as the foundation for leaf-specific keys,
    /// which are derived by adding a leaf-specific index.
    BaseSigning,

    /// Temporary signing key with path m/8797555'/account'/2'
    ///
    /// This key is used for one-time operations such as
    /// deposit address generation and temporary signing operations.
    TemporarySigning,
}

/// Trait for key derivation operations in the Spark wallet.
///
/// This trait defines the methods required to derive keys according to the
/// Spark-specific derivation path scheme. Implementors must ensure they
/// follow the exact derivation path structure to maintain compatibility
/// with the Spark ecosystem.
///
/// The Spark derivation scheme follows:
/// - m/8797555'/account'/key_type' for main keys
/// - m/8797555'/account'/1'/hash(leaf_id)' for leaf-specific keys
///
/// Where:
/// - 8797555' is the purpose value (derived from "spark")
/// - account' is the account index (starting from 0)
/// - key_type' is the key type (0' for identity, 1' for base signing, 2' for temporary)
/// - hash(leaf_id)' is a hardened index derived from the leaf ID
pub trait SparkSignerDerivationPath {
    /// Derives the deposit signing key for the user.
    ///
    /// In Spark, users always have a single deposit key derived deterministically
    /// from their seed. This method returns the public key corresponding to the
    /// derived deposit signing key.
    ///
    /// The deposit signing key uses the `TemporarySigning` key type (path index 2')
    /// in the derivation path.
    ///
    /// # Arguments
    /// * `network` - The Bitcoin network to use for the key derivation
    ///
    /// # Returns
    /// The public key for deposit operations or an error if derivation fails
    fn get_deposit_signing_key(&self, network: Network) -> Result<PublicKey, SparkSdkError>;

    /// Derives a Spark key for the specified key type, account, and optionally leaf ID.
    ///
    /// This is a core method for the Spark derivation path system. It handles the
    /// derivation of all types of keys used in the Spark wallet, including identity
    /// keys, base signing keys, temporary signing keys, and leaf-specific keys.
    ///
    /// # Arguments
    /// * `leaf_id` - Optional leaf ID for leaf-specific keys. If provided, the key
    ///   will be derived using the leaf-specific path: m/8797555'/account'/1'/hash(leaf_id)'
    /// * `account` - Account index to use in the derivation path
    /// * `seed_bytes` - The seed bytes to derive the key from
    /// * `key_type` - The type of key to derive (Identity, BaseSigning, or TemporarySigning)
    /// * `network` - The Bitcoin network to use for the key derivation
    ///
    /// # Returns
    /// The derived secret key or an error if derivation fails
    fn derive_spark_key(
        leaf_id: Option<String>,
        account: u32,
        seed_bytes: &[u8],
        key_type: SparkKeyType,
        network: Network,
    ) -> Result<SecretKey, SparkSdkError>;

    /// Returns the derivation path for the identity key.
    ///
    /// The identity key has the path: m/8797555'/account'/0'
    /// This method constructs and returns this path for the specified account.
    ///
    /// # Arguments
    /// * `account_index` - The account index to use in the derivation path
    ///
    /// # Returns
    /// A `SparkDerivationPath` containing the identity key path components
    /// or an error if path construction fails
    fn get_identity_derivation_path(
        account_index: u32,
    ) -> Result<SparkDerivationPath, SparkSdkError>;
}