Crate spark_rust

Spark Wallet SDK

A Rust implementation of the Spark protocol wallet, providing secure Bitcoin and Lightning Network operations through the Spark Service Provider (SSP).

This crate forms a complete wallet with all necessary Spark utilities, built on secure cryptographic primitives from the spark-cryptography crate.

Overview

Spark is a protocol that allows secure, non-custodial Bitcoin and Lightning Network operations, with all critical cryptographic operations performed client-side while leveraging Spark Service Providers for efficient network operations. This implementation provides:

• Complete Bitcoin wallet functionality
• Lightning Network payments (send and receive)
• Funds transfers between Spark users
• Deposit and withdrawal capabilities
• Comprehensive key management and signing utilities

Architecture

The Spark Wallet SDK comprises five main components:

• config: Configuration settings for the Spark wallet
• handlers: User-facing APIs for wallet operations
• internal_handlers: Service handlers for signing processes and RPC communications
• rpc: Client for establishing secure connections to Spark nodes
• signer: Key management, storage, and signing capabilities

Quick Start

use spark_rust::SparkSdk;
use spark_rust::SparkNetwork;
use spark_rust::signer::default_signer::DefaultSigner;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize the default signer with a mnemonic phrase
    let mnemonic = "abandon ability able about above absent absorb abstract absurd abuse access accident";
    let network = SparkNetwork::Regtest;
    let default_signer = DefaultSigner::from_mnemonic(mnemonic, network).await?;
     
    // Create a new SDK instance
    let sdk = SparkSdk::new(network, default_signer).await?;
     
    // Generate a deposit address
    let deposit_address = sdk.generate_deposit_address().await?;
    println!("Deposit address: {}", deposit_address.deposit_address);
     
    // Query pending transfers
    let pending = sdk.query_pending_transfers().await?;
    println!("You have {} pending transfers", pending.len());
     
    // Claim all pending transfers
    sdk.claim_transfers().await?;
     
    // Get your wallet balance
    let balance = sdk.get_bitcoin_balance();
    println!("Your balance is {} satoshis", balance);
     
    Ok(())
}

Security Model

Spark operates with a security model that ensures users always maintain control of their funds:

• All critical keys are managed client-side
• Threshold signing with FROST ensures security with multiple participants
• Transactions require both user and Spark operator signatures
• The user always initiates the signing process

Fee Structure

Unlike traditional Bitcoin wallets, Spark uses a service fee model where:

• Fees are charged by the Spark Service Provider (SSP) for operations they perform
• You don’t directly pay Bitcoin mining fees (these are handled by the SSP)
• Fee estimation methods help you determine costs before performing operations

Common fee operations include:

• Lightning payments (sending and receiving)
• Leaves swaps (optimizing wallet structure)
• Cooperative exits (withdrawing to on-chain Bitcoin)

Custom Signers

While the SDK provides a default in-memory signer implementation, advanced users can implement their own signers for specialized use cases by implementing the SparkSigner trait and its associated sub-traits.

use spark_rust::signer::traits::SparkSigner;
use spark_rust::SparkNetwork;

// Example of using a custom signer (implementation details omitted)
#[tokio::main]
async fn main() {
    // my_custom_signer implements the SparkSigner trait
    let my_custom_signer = create_custom_signer().await.unwrap();
    let sdk = SparkSdk::new(SparkNetwork::Regtest, my_custom_signer).await.unwrap();
    // ...
}

Modules

error

Error handling for the Spark Wallet SDK

rpc

RPC client implementation for connecting to Spark Operators

signer

This module contains the signer implementation for the Spark Wallet SDK. To implement a new signer, you need to implement the traits::Signer trait. The default signer is implemented in the default_signer module.

spark_test_utils

Macros

with_handler_lock

Macro to wrap handler functions with a global lock

Structs

CompleteCoopExitInput

Input for completing a cooperative exit

RequestCoopExitInput

Input for requesting a cooperative exit

SparkSdk

The main interface for the Spark wallet SDK

Enums

SparkNetwork

Spark Network. This is the network of the Spark Operators that the user chooses to connect to.