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    /// ```no_run
111    /// # use spark_rust::signer::default_signer::DefaultSigner;
112    /// # use spark_rust::SparkNetwork;
113    /// # use spark_rust::error::SparkSdkError;
114    /// # async fn example() -> Result<(), SparkSdkError> {
115    /// let mnemonic = "abandon ability able about above absent absorb abstract absurd abuse access accident";
116    /// let signer = DefaultSigner::from_mnemonic(mnemonic, SparkNetwork::Regtest).await?;
117    /// # Ok(())
118    /// # }
119    /// ```
120    #[cfg(feature = "self-signing")]
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    #[cfg(feature = "self-signing")]
138    async fn from_master_seed(
139        master_seed: &[u8],
140        network: SparkNetwork,
141    ) -> Result<Self::WrappedSigner, SparkSdkError>;
142
143    /// Creates a new signer instance connected to a remote signing service.
144    ///
145    /// This method initializes a signer that communicates with a remote service
146    /// for signing operations rather than managing keys locally. This can be used
147    /// for integration with hardware security modules or enterprise key management systems.
148    ///
149    /// # Arguments
150    /// * `signer_url` - The URL of the remote signing service
151    /// * `wallet_id` - An identifier for the wallet on the remote service
152    /// * `user_public_key_hex` - The user's public key in hexadecimal format
153    ///
154    /// # Returns
155    /// A wrapped signer instance or an error if connection fails
156    ///
157    /// # Note
158    /// This method is only available when the "self-signing" feature is disabled.
159    #[cfg(not(feature = "self-signing"))]
160    async fn new_remote(
161        signer_url: &str,
162        wallet_id: &str,
163        user_public_key_hex: &str,
164    ) -> Result<Self::WrappedSigner, SparkSdkError>;
165}
spark_rust/signer/traits/mod.rs

spark_rust/signer/traits/
mod.rs
