spark_rust/wallet/config/

spark.rs

use crate::constants::spark::connection::DEFAULT_COORDINATOR_INDEX;
use crate::constants::spark::LIGHTSPARK_SSP_ENDPOINT;
use crate::constants::spark::LIGHTSPARK_SSP_IDENTITY_PUBLIC_KEY;
use crate::error::CryptoError;
use crate::error::{NetworkError, SparkSdkError, ValidationError};
use crate::rpc::connections::connection::SparkConnection;
use crate::rpc::SparkRpcClient;
use crate::SparkNetwork;
use bitcoin::secp256k1::PublicKey;
use frost_secp256k1_tr_unofficial::Identifier;
use hashbrown::HashMap;
use parking_lot::RwLock;
use spark_cryptography::signing::identifier_to_hex_string;
use spark_protos::spark::spark_service_client::SparkServiceClient;
use std::str::FromStr;
use std::sync::Arc;
use tonic::transport::Channel;
use tonic::transport::Uri;

use crate::constants::spark::connection::SPARK_REGTEST_OPERATORS;
use crate::constants::spark::SPARK_REGTEST_SIGNING_THRESHOLD;

use crate::rpc::traits::SparkRpcConnection;

/// Configuration for the Spark wallet
#[derive(Clone)]
pub(crate) struct SparkConfig {
    /// Network to use for the wallet (mainnet, testnet, etc.)
    pub(crate) network: SparkNetwork,

    /// Map of signing operator identifiers to their configurations
    pub(crate) spark_operators: Vec<SparkOperator>,

    /// SSP endpoint
    pub(crate) ssp_endpoint: String,

    /// SSP identity public key
    pub(crate) ssp_identity_public_key: PublicKey,

    /// Index of the coordinator signing operator
    pub(crate) coordinator_index: u32,

    /// The threshold constant used for signing
    pub(crate) threshold: u32,

    /// gRPC client used for Spark Operator RPC calls
    spark_clients: Arc<RwLock<HashMap<u32, SparkRpcClient>>>,
}

/// Configuration for a signing operator
#[derive(Debug, Clone)]
pub(crate) struct SparkOperator {
    /// The index of the signing operator.
    pub(crate) id: u32,

    /// Identifier is the FROST identifier of the signing operator, which will be index + 1 in 32 bytes big endian hex string.
    /// Used as shamir secret share identifier in DKG key shares.
    pub(crate) frost_identifier: Identifier,

    /// Address of the signing operator
    pub(crate) address: Uri,

    /// Public key of the signing operator
    pub(crate) identity_public_key: PublicKey,
}

impl SparkOperator {
    // Parse an operator specified as a string (in the format <pubkey>@<address>) into a
    // [`SparkOperator`].
    pub(crate) fn parse(id: u32, op: &str) -> Result<Self, SparkSdkError> {
        let parts: Vec<&str> = op.split('@').collect();
        if parts.len() != 2 {
            return Err(SparkSdkError::from(ValidationError::InvalidArgument {
                argument: format!(
                    "Invalid operator string format {} (should be <pubkey>@<address>)",
                    op
                ),
            }));
        }

        let identity_public_key = PublicKey::from_str(parts[0]).map_err(|err| {
            SparkSdkError::from(ValidationError::InvalidArgument {
                argument: format!("Invalid public key for operator {}: {}", parts[0], err),
            })
        })?;

        let address = Uri::from_str(parts[1])
            .map_err(|err| SparkSdkError::from(NetworkError::InvalidUri(err)))?;

        let frost_identifier = Identifier::try_from(id as u16 + 1).map_err(|err| {
            SparkSdkError::from(ValidationError::InvalidArgument {
                argument: format!(
                    "Invalid frost identifier for operator {}: {}",
                    parts[0], err
                ),
            })
        })?;

        Ok(SparkOperator {
            id,
            frost_identifier,
            address,
            identity_public_key,
        })
    }

    pub(crate) fn frost_identifier_str(&self) -> String {
        identifier_to_hex_string(&self.frost_identifier)
    }
}

impl SparkConfig {
    /// Try and get operators from environment variables. Each operator should be in a separate
    /// environment variable in the format `SPARK_OPERATOR_<index>`.
    ///
    /// Returns `None` if operators are not specified as environmental variables. Otherwise,
    /// returns Ok with the parsed operators, or an error if parsing operators fails.
    fn operators_from_env() -> Option<Result<Vec<SparkOperator>, SparkSdkError>> {
        // If the first operator is not set, assume the rest aren't set either.
        if std::env::var("SPARK_OPERATOR_0").is_err() {
            return None;
        }

        let mut operators = vec![];
        for i in 0..10 {
            let variable = format!("SPARK_OPERATOR_{}", i);
            let operator = std::env::var(&variable);
            let operator = match operator {
                Ok(operator) => operator,
                Err(_) => break,
            };

            match SparkOperator::parse(i as u32, &operator) {
                Ok(operator) => operators.push(operator),
                Err(err) => {
                    return Some(Err(SparkSdkError::from(ValidationError::InvalidArgument {
                        argument: format!("Unable to parse operator {}: {}", variable, err),
                    })))
                }
            }
        }

        Some(Ok(operators))
    }

    /// Try to get the operators from the environment first. Otherwise, parse the defaults from
    /// [`SPARK_REGTEST_OPERATORS`].
    fn operators() -> Result<Vec<SparkOperator>, SparkSdkError> {
        if let Some(operators) = Self::operators_from_env() {
            return operators;
        }

        let mut spark_operators = vec![];
        for (i, operator) in SPARK_REGTEST_OPERATORS.iter().enumerate() {
            // TODO: Add environment
            let address = Uri::from_str(operator.0)
                .map_err(|err| SparkSdkError::from(NetworkError::InvalidUri(err)))?;

            let identity_public_key = PublicKey::from_str(operator.1).map_err(|err| {
                SparkSdkError::from(ValidationError::InvalidArgument {
                    argument: format!("Invalid public key for operator {}: {}", operator.1, err),
                })
            })?;

            let frost_identifier = Identifier::try_from(i as u16 + 1).map_err(|err| {
                SparkSdkError::from(ValidationError::InvalidArgument {
                    argument: format!(
                        "Invalid frost identifier for operator {}: {}",
                        operator.1, err
                    ),
                })
            })?;

            spark_operators.push(SparkOperator {
                id: i as u32,
                frost_identifier,
                address,
                identity_public_key,
            });
        }

        Ok(spark_operators)
    }

    /// Creates a new wallet configuration with the specified network.
    ///
    /// This function:
    /// 1. Creates a vector of 5 Spark operators with their configurations
    /// 2. Sets up gRPC connections to each operator
    /// 3. Initializes the wallet configuration with default values
    ///
    /// # Arguments
    ///
    /// * `network` - The Spark network to use (mainnet, testnet, regtest)
    ///
    /// # Returns
    ///
    /// Returns a Result containing either:
    /// * The initialized SparkConfig struct on success
    /// * A [`SparkSdkError`] on failure (e.g. connection errors, invalid URLs)
    ///
    /// # Errors
    ///
    /// This function will return an error if:
    /// * Failed to establish gRPC connections to operators
    /// * Failed to parse operator URLs
    /// * Failed to decode operator public keys
    pub async fn new(network: SparkNetwork) -> Result<Self, SparkSdkError> {
        // set the threshold
        let threshold = SPARK_REGTEST_SIGNING_THRESHOLD;

        // set the default coordinator index
        let coordinator_index = DEFAULT_COORDINATOR_INDEX;

        // set the operators
        let spark_operators = Self::operators()?;

        // set the connection pool for operators
        let mut spark_clients = HashMap::new();
        for operator in &spark_operators {
            // establish the secure connection
            // since this uses rustls, self-signed certificates will fail
            let spark_rpc_client =
                SparkConnection::establish_connection(operator.address.clone()).await?;
            spark_clients.insert(operator.id, spark_rpc_client);
        }

        // Create the wallet configuration
        let ssp_identity_public_key = PublicKey::from_str(LIGHTSPARK_SSP_IDENTITY_PUBLIC_KEY)
            .map_err(|err| SparkSdkError::from(CryptoError::Secp256k1(err)))?;

        #[cfg(feature = "telemetry")]
        tracing::info!(
            ssp_identity_public_key = ssp_identity_public_key.to_string(),
            "ssp public key"
        );
        let wallet_config = Self {
            network,
            spark_operators,
            coordinator_index,
            threshold,
            spark_clients: Arc::new(RwLock::new(spark_clients)),
            ssp_endpoint: LIGHTSPARK_SSP_ENDPOINT.to_string(),
            ssp_identity_public_key,
        };

        Ok(wallet_config)
    }

    /// Gets a connection to a Spark operator service.
    ///
    /// This function manages connections to Spark operators, creating new connections if needed
    /// and reusing existing ones. It handles both connecting to a specific operator or defaulting
    /// to the coordinator.
    ///
    /// # Arguments
    ///
    /// * `operator_id` - Optional ID of the specific operator to connect to. If None, connects to
    ///                   the default coordinator.
    ///
    /// # Returns
    ///
    /// * [`Result<SparkServiceClient<Channel>, SparkSdkError>`] - A client for the Spark service on success,
    ///    or an error if the connection fails
    ///
    /// # Errors
    ///
    /// Returns [`SparkSdkError::InvalidArgument`] if:
    /// * The operator_id is out of bounds for the available operators
    ///
    /// May also return errors from:
    /// * Channel creation/connection
    /// * URI parsing
    #[cfg_attr(feature = "telemetry", tracing::instrument(skip_all))]
    pub(crate) async fn get_spark_connection(
        &self,
        operator_id: Option<u32>,
    ) -> Result<SparkServiceClient<Channel>, SparkSdkError> {
        let operator_id = operator_id.unwrap_or(self.coordinator_index);

        // if doesn't exist, create the connection for the operator
        if !self.spark_clients.read().contains_key(&operator_id) {
            let spark_operators = self.spark_operators.clone();
            if operator_id >= spark_operators.len() as u32 {
                drop(spark_operators);
                return Err(SparkSdkError::from(ValidationError::InvalidArgument {
                    argument: format!("Operator index {} is out of bounds", operator_id),
                }));
            }

            let uri = spark_operators[operator_id as usize].address.clone();
            let spark_rpc_instance = SparkConnection::establish_connection(uri).await?;
            self.spark_clients
                .write()
                .insert(operator_id, spark_rpc_instance);
        }

        // get the connection
        let client = self.spark_clients.read().get(&operator_id).unwrap().clone();
        let spark_client = client.get_new_spark_service_connection()?;

        Ok(spark_client)
    }
}

#[cfg(test)]
mod test {
    use super::SparkOperator;

    #[test]
    fn test_parse_spark_operator() {
        let operator = SparkOperator::parse(
            0,
            "0322ca18fc489ae25418a0e768273c2c61cabb823edfb14feb891e9bec62016510@http://localhost:8535",
        )
        .unwrap();

        assert_eq!(operator.id, 0);
        assert_eq!(
            operator.frost_identifier_str(),
            "0000000000000000000000000000000000000000000000000000000000000001"
        );
        assert_eq!(operator.address.to_string(), "http://localhost:8535/");
        assert_eq!(
            operator.identity_public_key.to_string(),
            "0322ca18fc489ae25418a0e768273c2c61cabb823edfb14feb891e9bec62016510"
        );
    }
}