spark_cryptography

Module derivation_path

Source
Expand description

Spark Cryptography Module

This module provides cryptographic functionality for the Spark wallet system, specifically handling key derivation and management.

§Overview

The Spark wallet uses a hierarchical deterministic (HD) wallet structure based on BIP32, with a custom purpose number (8797555) for Spark-specific keys. The key hierarchy is:

// m/8797555'/account'/key_type'[/leaf_index']

Where:

  • account: The account index (hardened)
  • key_type: The type of key (0’ for identity, 1’ for base signing, 2’ for deposit)
  • leaf_index: Optional leaf-specific index (hardened)

§Key Types

The wallet supports three types of keys:

  1. Identity Key (0’)

    • Used for wallet authentication and identification
    • Used for signature verification with Spark Operators

  2. Base Signing Key (1’)

    • Foundation for leaf-specific keys
    • Used for general signing operations

  3. Deposit Key (2’)

    • Used for deposit transactions. All deposit transactions are signed with this key. However, each deposit address is different. Deposit signing key is static, and it is not to be confused with one-time deposit address.
    • After deposit, leaves are transferred to BaseSigning key

§Usage

use spark_cryptography::derivation_path::{derive_spark_key, SparkKeyType};
use bitcoin::Network;

// Generate a seed (in practice, use a secure random number generator)
let seed_bytes = b"0000000000000000000000000000000000000000000000000000000000000000";

// Derive an identity key
let identity_key = derive_spark_key(
    None,                    // No leaf ID for identity key
    0,                       // Account index
    seed_bytes,             // Seed
    SparkKeyType::Identity, // Key type
    Network::Bitcoin,       // Network
).unwrap();

// Derive a leaf-specific key
let leaf_key = derive_spark_key(
    Some("leaf-uuid".to_string()),
    0,
    seed_bytes,
    SparkKeyType::BaseSigning,
    Network::Bitcoin,
).unwrap();

§Security Considerations

  • All derivation paths use hardened derivation (with ’ suffix)
  • Seeds must be at least 16 bytes long
  • Leaf indices are deterministically derived from leaf IDs
  • Different key types ensure separation of concerns

§Error Handling

The module provides detailed error types for various failure cases:

  • Invalid seeds
  • Invalid derivation paths
  • Invalid leaf indices
  • Invalid key types
  • Network-specific errors

Structs§

SparkDerivationPath
The derivation path for a Spark key.

Enums§

SparkKeyType
Key types for Spark wallet.

Constants§

SPARK_DERIVATION_PATH_PURPOSE

Functions§

derive_spark_key
Derives a Spark key from a seed and derivation path.
get_child_number
Creates a ChildNumber from an index value and hardened flag.
get_derivation_path_with_key_type
Derives the identity derivation path for a given account index.
get_leaf_index
Calculates the derivation path component for a leaf key based on a leaf ID.
get_public_key_with_key_type
Derives the public key for a given account index, network, and key type.
get_secret_key_with_key_type
Derives the secret key for a given account index, network, and key type.