spark_rust/signer/traits/
mod.rs

1//! # Signer Traits for the Spark Wallet SDK
2//!
3//! This module defines the trait interfaces for the signing system in Spark.
4//! The signing system is a critical component that handles all cryptographic
5//! operations including key management, ECDSA signing, FROST threshold signing,
6//! and secure key derivation.
7//!
8//! ## Trait Architecture
9//!
10//! The signer follows a modular trait-based design:
11//!
12//! - [`SparkSigner`] - The main trait that composes all sub-traits
13//! - [`SparkSignerDerivationPath`] - Key derivation path handling using Spark's custom path scheme
14//! - [`SparkSignerEcdsa`] - ECDSA signature operations for identity verification
15//! - [`SparkSignerEcies`] - Encryption/decryption of secret keys between parties
16//! - [`SparkSignerFrost`] - FROST nonce and commitment management for threshold signing
17//! - [`SparkSignerFrostSigning`] - FROST threshold signature operations
18//! - [`SparkSignerSecp256k1`] - Secp256k1 keypair management
19//! - [`SparkSignerShamir`] - Verifiable secret sharing for secure key distribution
20//!
21//! This design allows for flexible implementation of different signing backends
22//! while ensuring all required cryptographic operations are supported.
23//!
24//! ## Implementation
25//!
26//! The SDK provides a default implementation [`DefaultSigner`](crate::signer::default_signer::DefaultSigner)
27//! that manages keys in memory. Users can implement custom signers for specialized
28//! needs such as hardware security modules or remote signing services.
29
30use crate::error::SparkSdkError;
31
32// Signer traits
33use crate::signer::traits::derivation_path::SparkSignerDerivationPath;
34use crate::signer::traits::ecdsa::SparkSignerEcdsa;
35use crate::signer::traits::ecies::SparkSignerEcies;
36use crate::signer::traits::frost::SparkSignerFrost;
37use crate::signer::traits::frost_signing::SparkSignerFrostSigning;
38use crate::signer::traits::secp256k1::SparkSignerSecp256k1;
39use crate::signer::traits::shamir::SparkSignerShamir;
40
41use crate::SparkNetwork;
42
43use tonic::async_trait;
44
45pub mod derivation_path;
46pub mod ecdsa;
47pub mod ecies;
48pub mod frost;
49pub mod frost_signing;
50pub mod secp256k1;
51pub mod shamir;
52
53/// The main signer trait that aggregates all cryptographic capabilities required
54/// for the Spark wallet.
55///
56/// This trait is the primary interface for implementing a signer for the Spark Wallet SDK.
57/// It combines all the specialized sub-traits that handle different aspects of the
58/// cryptographic operations needed in the Spark protocol.
59///
60/// Implementors must provide all the functionality defined in each sub-trait:
61///
62/// - [`SparkSignerShamir`]: Verifiable secret sharing operations
63/// - [`SparkSignerEcdsa`]: ECDSA signature operations
64/// - [`SparkSignerEcies`]: Encryption/decryption of secret keys
65/// - [`SparkSignerFrost`]: FROST nonce and commitment management
66/// - [`SparkSignerSecp256k1`]: Secp256k1 keypair operations
67/// - [`SparkSignerFrostSigning`]: FROST threshold signing operations
68/// - [`SparkSignerDerivationPath`]: Key derivation path handling
69///
70/// # Security Considerations
71///
72/// The signer implementation is responsible for securely managing private keys
73/// and other sensitive cryptographic material. Implementors should:
74///
75/// - Ensure proper isolation of private key material
76/// - Implement secure storage if keys are persisted
77/// - Follow best practices for cryptographic operations
78/// - Maintain Spark's specific derivation path scheme for compatibility
79#[async_trait]
80pub trait SparkSigner:
81    SparkSignerShamir
82    + SparkSignerEcdsa
83    + SparkSignerEcies
84    + SparkSignerFrost
85    + SparkSignerSecp256k1
86    + SparkSignerFrostSigning
87    + SparkSignerDerivationPath
88{
89    /// The constructed signer type, wrapped in a thread-safe reference-counted container.
90    ///
91    /// This associated type allows implementors to define their own wrapped signer type,
92    /// which typically is an `Arc<parking_lot::RwLock<Self>>` to enable thread-safe
93    /// access and mutation of the signer state.
94    type WrappedSigner: Sized;
95
96    /// Creates a new signer instance from a BIP-39 mnemonic phrase.
97    ///
98    /// This method initializes a signer using a mnemonic phrase, which is converted
99    /// to a seed for deriving all necessary keys. This is the recommended way to
100    /// create a signer for most applications.
101    ///
102    /// # Arguments
103    /// * `mnemonic` - The BIP-39 mnemonic phrase to derive keys from
104    /// * `network` - The Spark network to use (affects key derivation)
105    ///
106    /// # Returns
107    /// A wrapped signer instance or an error if initialization fails
108    ///
109    /// # Example
110    /// ```
111    /// # use spark_rust::signer::default_signer::DefaultSigner;
112    /// # use spark_rust::SparkNetwork;
113    /// # use spark_rust::error::SparkSdkError;
114    /// # use spark_rust::signer::traits::SparkSigner;
115    /// # async fn example() -> Result<(), SparkSdkError> {
116    ///     let mnemonic = "abandon ability able about above absent absorb abstract absurd abuse access accident";
117    ///     let signer = DefaultSigner::from_mnemonic(mnemonic, SparkNetwork::Regtest).await?;
118    /// #   Ok(())
119    /// # }
120    /// ```
121    async fn from_mnemonic(
122        mnemonic: &str,
123        network: SparkNetwork,
124    ) -> Result<Self::WrappedSigner, SparkSdkError>;
125
126    /// Creates a new signer instance from a raw seed.
127    ///
128    /// This method initializes a signer using a raw seed byte array for deriving keys.
129    /// This is an alternative to using a mnemonic phrase when the seed is already available.
130    ///
131    /// # Arguments
132    /// * `master_seed` - The seed bytes to derive keys from
133    /// * `network` - The Spark network to use (affects key derivation)
134    ///
135    /// # Returns
136    /// A wrapped signer instance or an error if initialization fails
137    async fn from_master_seed(
138        master_seed: &[u8],
139        network: SparkNetwork,
140    ) -> Result<Self::WrappedSigner, SparkSdkError>;
141}
spark_rust/signer/traits/mod.rs

spark_rust/signer/traits/
mod.rs
