qudag_exchange/

lib.rs

//! # QuDAG Exchange
//!
//! A modular, quantum-secure, multi-agent resource exchange protocol that enables
//! trustless computational resource trading through rUv (Resource Utilization Voucher) tokens.
//!
//! ## Overview
//!
//! QuDAG Exchange provides a decentralized marketplace for computational resources,
//! allowing providers to offer CPU, GPU, memory, storage, and bandwidth in exchange
//! for rUv tokens. The system uses post-quantum cryptography to ensure long-term
//! security and integrates with QuDAG's DAG-based consensus for fast transaction finality.
//!
//! ## Features
//!
//! - **Quantum-Resistant Security**: Uses ML-DSA signatures and ML-KEM encryption
//! - **Resource Trading**: Trade computational resources for rUv tokens
//! - **DAG Consensus**: Fast finality with QR-Avalanche consensus
//! - **Cross-Platform**: Native, WASM, and API support
//! - **Secure Vault**: Encrypted key storage with QuDAG Vault integration
//!
//! ## Quick Start
//!
//! ```rust
//! use qudag_exchange::{Exchange, Account, Transaction};
//!
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! // Create exchange instance
//! let exchange = Exchange::new("mainnet").await?;
//!
//! // Create account
//! let account = exchange.create_account("alice", "secure_password").await?;
//!
//! // Transfer tokens
//! let tx = Transaction::builder()
//!     .from(&account)
//!     .to("qd1recipient...")
//!     .amount(100.0)
//!     .memo("Payment for resources")
//!     .build()?;
//!
//! let result = exchange.submit_transaction(tx).await?;
//! # Ok(())
//! # }
//! ```

#![warn(missing_docs)]
#![warn(rustdoc::missing_crate_level_docs)]

use std::collections::HashMap;
use std::sync::Arc;

pub mod error;

// Re-export from core
pub use error::{ExchangeError as Error, Result};
pub use qudag_exchange_core::*;

/// The main exchange interface for interacting with the QuDAG Exchange network.
///
/// The `Exchange` struct provides methods for account management, transaction submission,
/// resource trading, and network interaction. It handles all the complexity of
/// quantum-resistant cryptography, consensus participation, and P2P networking.
///
/// # Examples
///
/// ## Creating an Exchange Instance
///
/// ```rust
/// use qudag_exchange::Exchange;
///
/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
/// // Connect to mainnet
/// let exchange = Exchange::new("mainnet").await?;
///
/// // Connect to testnet with custom config
/// let config = ExchangeConfig {
///     network: "testnet".to_string(),
///     data_dir: Some("/custom/path".into()),
///     ..Default::default()
/// };
/// let exchange = Exchange::with_config(config).await?;
/// # Ok(())
/// # }
/// ```
#[derive(Clone)]
pub struct Exchange {
    inner: Arc<ExchangeInner>,
}

struct ExchangeInner {
    network: String,
    consensus: ConsensusAdapter,
    ledger: Ledger,
    config: ExchangeConfig,
}

impl Exchange {
    /// Creates a new Exchange instance connected to the specified network.
    ///
    /// # Arguments
    ///
    /// * `network` - The network to connect to ("mainnet", "testnet", or "local")
    ///
    /// # Returns
    ///
    /// Returns a new `Exchange` instance or an error if initialization fails.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use qudag_exchange::Exchange;
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// let exchange = Exchange::new("mainnet").await?;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn new(network: &str) -> Result<Self> {
        let config = ExchangeConfig {
            network: network.to_string(),
            ..Default::default()
        };

        Self::with_config(config).await
    }

    /// Creates a new Exchange instance with custom configuration.
    ///
    /// # Arguments
    ///
    /// * `config` - Custom configuration for the exchange
    ///
    /// # Returns
    ///
    /// Returns a configured `Exchange` instance or an error if initialization fails.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use qudag_exchange::{Exchange, ExchangeConfig};
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// let config = ExchangeConfig {
    ///     network: "testnet".to_string(),
    ///     bootstrap_peers: vec!["/ip4/1.2.3.4/tcp/8080".to_string()],
    ///     consensus_config: ConsensusConfig {
    ///         sample_size: 20,
    ///         quorum_size: 14,
    ///         ..Default::default()
    ///     },
    ///     ..Default::default()
    /// };
    ///
    /// let exchange = Exchange::with_config(config).await?;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn with_config(config: ExchangeConfig) -> Result<Self> {
        // Implementation details...
        todo!()
    }

    /// Creates a new account with quantum-resistant keys.
    ///
    /// This method generates a new ML-DSA key pair, creates an account,
    /// and securely stores the private key in the QuDAG Vault.
    ///
    /// # Arguments
    ///
    /// * `name` - A human-readable name for the account
    /// * `password` - The password to encrypt the private key
    ///
    /// # Returns
    ///
    /// Returns the newly created `Account` or an error if creation fails.
    ///
    /// # Security
    ///
    /// The password is used to derive an encryption key using Argon2id.
    /// The private key is encrypted with ChaCha20-Poly1305 before storage.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use qudag_exchange::Exchange;
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let exchange = Exchange::new("testnet").await?;
    /// let account = exchange.create_account("alice", "secure_password").await?;
    /// println!("Account address: {}", account.address());
    /// # Ok(())
    /// # }
    /// ```
    pub async fn create_account(&self, name: &str, password: &str) -> Result<Account> {
        // Implementation details...
        todo!()
    }

    /// Retrieves the current balance for an account.
    ///
    /// # Arguments
    ///
    /// * `account` - The account ID or address to query
    ///
    /// # Returns
    ///
    /// Returns the current `Balance` including available, staked, and pending amounts.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use qudag_exchange::Exchange;
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let exchange = Exchange::new("testnet").await?;
    /// # let account = exchange.create_account("alice", "password").await?;
    /// let balance = exchange.get_balance(&account).await?;
    /// println!("Available: {} rUv", balance.available);
    /// println!("Staked: {} rUv", balance.staked);
    /// # Ok(())
    /// # }
    /// ```
    pub async fn get_balance<A: Into<AccountId>>(&self, account: A) -> Result<Balance> {
        // Implementation details...
        todo!()
    }

    /// Submits a transaction to the network.
    ///
    /// The transaction is validated, signed (if not already signed),
    /// and submitted to the consensus layer for processing.
    ///
    /// # Arguments
    ///
    /// * `transaction` - The transaction to submit
    ///
    /// # Returns
    ///
    /// Returns a `TransactionResult` containing the transaction ID and initial status.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - The transaction is invalid (missing fields, invalid signature)
    /// - The sender has insufficient balance
    /// - Network submission fails
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use qudag_exchange::{Exchange, Transaction};
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let exchange = Exchange::new("testnet").await?;
    /// # let account = exchange.create_account("alice", "password").await?;
    /// let tx = Transaction::builder()
    ///     .from(&account)
    ///     .to("qd1recipient...")
    ///     .amount(50.0)
    ///     .build()?;
    ///
    /// let result = exchange.submit_transaction(tx).await?;
    /// println!("Transaction ID: {}", result.transaction_id);
    /// # Ok(())
    /// # }
    /// ```
    pub async fn submit_transaction(&self, transaction: Transaction) -> Result<TransactionResult> {
        // Implementation details...
        todo!()
    }

    /// Waits for a transaction to be confirmed.
    ///
    /// This method blocks until the transaction reaches the specified
    /// number of confirmations or times out.
    ///
    /// # Arguments
    ///
    /// * `tx_id` - The transaction ID to monitor
    /// * `confirmations` - Number of confirmations required (default: 6)
    ///
    /// # Returns
    ///
    /// Returns the final `TransactionStatus` or an error if timeout/rejection occurs.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use qudag_exchange::Exchange;
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let exchange = Exchange::new("testnet").await?;
    /// # let tx_id = TransactionId::from("tx_123");
    /// // Wait for 6 confirmations (default)
    /// let status = exchange.wait_for_confirmation(&tx_id, None).await?;
    ///
    /// // Wait for 1 confirmation (faster but less secure)
    /// let status = exchange.wait_for_confirmation(&tx_id, Some(1)).await?;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn wait_for_confirmation(
        &self,
        tx_id: &TransactionId,
        confirmations: Option<u32>,
    ) -> Result<TransactionStatus> {
        // Implementation details...
        todo!()
    }
}

/// Configuration options for the Exchange.
///
/// # Examples
///
/// ```rust
/// use qudag_exchange::{ExchangeConfig, ConsensusConfig};
///
/// let config = ExchangeConfig {
///     network: "mainnet".to_string(),
///     data_dir: Some("/var/lib/qudag".into()),
///     bootstrap_peers: vec![
///         "/ip4/1.2.3.4/tcp/8080".to_string(),
///         "/ip4/5.6.7.8/tcp/8080".to_string(),
///     ],
///     consensus_config: ConsensusConfig {
///         sample_size: 20,
///         quorum_size: 14,
///         decision_threshold: 20,
///         ..Default::default()
///     },
///     ..Default::default()
/// };
/// ```
#[derive(Clone, Debug)]
pub struct ExchangeConfig {
    /// Network to connect to ("mainnet", "testnet", "local")
    pub network: String,

    /// Data directory for storage (defaults to platform-specific location)
    pub data_dir: Option<std::path::PathBuf>,

    /// Bootstrap peer addresses for initial connection
    pub bootstrap_peers: Vec<String>,

    /// Maximum number of peer connections
    pub max_peers: usize,

    /// Consensus configuration
    pub consensus_config: ConsensusConfig,

    /// Enable debug logging
    pub debug: bool,
}

impl Default for ExchangeConfig {
    fn default() -> Self {
        Self {
            network: "mainnet".to_string(),
            data_dir: None,
            bootstrap_peers: vec![],
            max_peers: 50,
            consensus_config: ConsensusConfig::default(),
            debug: false,
        }
    }
}

/// Consensus configuration parameters.
///
/// These parameters control the behavior of the QR-Avalanche consensus protocol.
///
/// # Examples
///
/// ```rust
/// use qudag_exchange::ConsensusConfig;
/// use std::time::Duration;
///
/// let config = ConsensusConfig {
///     sample_size: 20,        // Query 20 validators
///     quorum_size: 14,        // Need 14 positive responses
///     decision_threshold: 20,  // 20 consecutive successes to decide
///     query_timeout: Duration::from_millis(500),
///     ..Default::default()
/// };
/// ```
#[derive(Clone, Debug)]
pub struct ConsensusConfig {
    /// Number of validators to query (k parameter)
    pub sample_size: usize,

    /// Quorum threshold for positive responses (α parameter)
    pub quorum_size: usize,

    /// Consecutive successes needed for decision (β parameter)
    pub decision_threshold: u32,

    /// Timeout for each query round
    pub query_timeout: std::time::Duration,

    /// Maximum time to wait for consensus
    pub max_consensus_time: std::time::Duration,
}

impl Default for ConsensusConfig {
    fn default() -> Self {
        Self {
            sample_size: 20,
            quorum_size: 14,
            decision_threshold: 20,
            query_timeout: std::time::Duration::from_millis(500),
            max_consensus_time: std::time::Duration::from_secs(30),
        }
    }
}

/// Result of a transaction submission.
///
/// Contains the transaction ID and initial status information.
///
/// # Examples
///
/// ```rust
/// # use qudag_exchange::{Exchange, Transaction, TransactionResult};
/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
/// # let exchange = Exchange::new("testnet").await?;
/// # let tx = Transaction::test_transaction();
/// let result: TransactionResult = exchange.submit_transaction(tx).await?;
///
/// println!("Transaction ID: {}", result.transaction_id);
/// println!("Initial status: {:?}", result.status);
///
/// if let Some(fee) = result.estimated_fee {
///     println!("Estimated fee: {} rUv", fee);
/// }
/// # Ok(())
/// # }
/// ```
#[derive(Debug, Clone)]
pub struct TransactionResult {
    /// Unique identifier for the transaction
    pub transaction_id: TransactionId,

    /// Initial status of the transaction
    pub status: TransactionStatus,

    /// Estimated fee (if calculable)
    pub estimated_fee: Option<f64>,

    /// Estimated confirmation time
    pub estimated_confirmation_time: Option<std::time::Duration>,
}

/// Resource provider interface for offering computational resources.
///
/// The `Provider` struct manages resource offerings, pricing, and job execution
/// for nodes that want to contribute resources to the network.
///
/// # Examples
///
/// ```rust
/// use qudag_exchange::{Provider};
///
/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
/// # let exchange = Exchange::new("testnet").await?;
/// # let account = exchange.create_account("provider", "password").await?;
/// let provider = Provider::builder()
///     .account(&account)
///     .build()?;
///
/// // Start providing resources
/// provider.start().await?;
/// # Ok(())
/// # }
/// ```
pub struct Provider {
    inner: Arc<ProviderInner>,
}

struct ProviderInner {
    account: Account,
    // TODO: Add resource specification types
    // resources: Vec<ResourceSpec>,
    // pricing: PricingStrategy,
}

impl Provider {
    /// Creates a new provider builder.
    ///
    /// # Returns
    ///
    /// Returns a `ProviderBuilder` for configuring the provider.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use qudag_exchange::Provider;
    /// let builder = Provider::builder();
    /// ```
    pub fn builder() -> ProviderBuilder {
        ProviderBuilder::new()
    }

    /// Starts the resource provider.
    ///
    /// This method begins advertising resources and accepting jobs.
    ///
    /// # Returns
    ///
    /// Returns `Ok(())` on successful start or an error if startup fails.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use qudag_exchange::Provider;
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let provider = Provider::builder().build()?;
    /// provider.start().await?;
    /// println!("Provider started, ready to accept jobs");
    /// # Ok(())
    /// # }
    /// ```
    pub async fn start(&self) -> Result<()> {
        // Implementation details...
        todo!()
    }

    /// Stops the resource provider gracefully.
    ///
    /// This method stops accepting new jobs and waits for active jobs to complete.
    ///
    /// # Arguments
    ///
    /// * `force` - If true, forcefully stops all jobs immediately
    ///
    /// # Returns
    ///
    /// Returns `Ok(())` when stopped or an error if shutdown fails.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use qudag_exchange::Provider;
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let provider = Provider::builder().build()?;
    /// // Graceful shutdown
    /// provider.stop(false).await?;
    ///
    /// // Force shutdown
    /// provider.stop(true).await?;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn stop(&self, force: bool) -> Result<()> {
        // Implementation details...
        todo!()
    }

    /// Gets current provider statistics.
    ///
    /// # Returns
    ///
    /// Returns `ProviderStats` with performance metrics and earnings.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use qudag_exchange::Provider;
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let provider = Provider::builder().build()?;
    /// let stats = provider.get_stats().await?;
    /// println!("Jobs completed: {}", stats.jobs_completed);
    /// println!("Total earned: {} rUv", stats.total_earned);
    /// println!("Uptime: {:?}", stats.uptime);
    /// # Ok(())
    /// # }
    /// ```
    pub async fn get_stats(&self) -> Result<ProviderStats> {
        // Implementation details...
        todo!()
    }
}

/// Builder for creating a Provider instance.
///
/// # Examples
///
/// ```rust
/// # use qudag_exchange::{Provider, ProviderBuilder, ResourceSpec, PricingStrategy};
/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
/// # let account = Account::test_account();
/// let provider = Provider::builder()
///     .account(&account)
///     .add_resource(ResourceSpec::cpu(16))
///     .add_resource(ResourceSpec::gpu("A100", 4))
///     .pricing_strategy(PricingStrategy::fixed(50.0))
///     .min_job_duration(std::time::Duration::from_secs(3600))
///     .build()?;
/// # Ok(())
/// # }
/// ```
pub struct ProviderBuilder {
    account: Option<Account>,
    // TODO: Add resource specification types
    // resources: Vec<ResourceSpec>,
    // pricing: Option<PricingStrategy>,
    min_job_duration: Option<std::time::Duration>,
}

impl ProviderBuilder {
    /// Creates a new provider builder.
    pub fn new() -> Self {
        Self {
            account: None,
            // resources: vec![],
            // pricing: None,
            min_job_duration: None,
        }
    }

    /// Sets the account for the provider.
    ///
    /// # Arguments
    ///
    /// * `account` - The account that will receive payments
    ///
    /// # Returns
    ///
    /// Returns the builder for chaining.
    pub fn account(mut self, account: &Account) -> Self {
        self.account = Some(account.clone());
        self
    }

    // TODO: Re-enable when ResourceSpec is implemented
    // /// Adds a resource to offer.
    // ///
    // /// # Arguments
    // ///
    // /// * `resource` - The resource specification to add
    // ///
    // /// # Returns
    // ///
    // /// Returns the builder for chaining.
    // pub fn add_resource(mut self, resource: ResourceSpec) -> Self {
    //     self.resources.push(resource);
    //     self
    // }

    // TODO: Re-enable when PricingStrategy is implemented
    // /// Sets the pricing strategy.
    // ///
    // /// # Arguments
    // ///
    // /// * `strategy` - The pricing strategy to use
    // ///
    // /// # Returns
    // ///
    // /// Returns the builder for chaining.
    // pub fn pricing_strategy(mut self, strategy: PricingStrategy) -> Self {
    //     self.pricing = Some(strategy);
    //     self
    // }

    /// Builds the Provider instance.
    ///
    /// # Returns
    ///
    /// Returns the configured `Provider` or an error if configuration is invalid.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - No account is specified
    /// - No resources are configured
    /// - Invalid configuration parameters
    pub fn build(self) -> Result<Provider> {
        // Implementation details...
        todo!()
    }
}

// TODO: Implement pricing strategy types
// /// Pricing strategy for resource offerings.
// #[derive(Clone, Debug)]
// pub enum PricingStrategy {
//     /// Fixed price per resource unit
//     Fixed(f64),
//
//     /// Market-based dynamic pricing
//     MarketBased,
//
//     /// Custom pricing rules
//     Custom(CustomPricing),
// }

/// Statistics for a resource provider.
///
/// Contains performance metrics, earnings, and resource utilization data.
#[derive(Debug, Clone)]
pub struct ProviderStats {
    /// Number of jobs completed
    pub jobs_completed: u64,

    /// Number of jobs failed
    pub jobs_failed: u64,

    /// Total rUv earned
    pub total_earned: f64,

    /// Average job completion time
    pub avg_completion_time: std::time::Duration,

    /// Provider uptime
    pub uptime: std::time::Duration,

    /// Resource utilization percentage
    pub utilization: f64,

    /// Customer satisfaction rating (0-5)
    pub satisfaction_rating: f64,
}

/// Market interface for searching and trading resources.
///
/// The `Market` struct provides methods for discovering available resources,
/// comparing prices, and executing trades.
///
/// # Examples
///
/// ```rust
/// use qudag_exchange::{Market, ResourceQuery};
///
/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
/// # let exchange = Exchange::new("testnet").await?;
/// let market = exchange.market();
///
/// // Search for GPU resources
/// let query = ResourceQuery::new()
///     .resource_type(ResourceType::Gpu)
///     .min_memory_gb(40)
///     .max_price(100.0);
///
/// let offers = market.search(query).await?;
///
/// for offer in offers {
///     println!("Provider: {}", offer.provider);
///     println!("Price: {} rUv/hour", offer.price_per_hour);
/// }
/// # Ok(())
/// # }
/// ```
pub struct Market {
    exchange: Exchange,
}

impl Market {
    // TODO: Implement when ResourceQuery and Offer types are available
    // /// Searches for resource offers matching the query.
    // pub async fn search(&self, query: ResourceQuery) -> Result<Vec<Offer>> {
    //     // Implementation details...
    //     todo!()
    // }

    /// Gets current market statistics.
    ///
    /// # Returns
    ///
    /// Returns `MarketStats` with pricing and availability information.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use qudag_exchange::Market;
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let market = Market::test_market();
    /// let stats = market.get_stats().await?;
    ///
    /// println!("Active offers: {}", stats.active_offers);
    /// println!("24h volume: {} rUv", stats.volume_24h);
    /// println!("Avg GPU price: {} rUv/hour", stats.avg_gpu_price);
    /// # Ok(())
    /// # }
    /// ```
    pub async fn get_stats(&self) -> Result<MarketStats> {
        // Implementation details...
        todo!()
    }

    // TODO: Implement when OfferId and Reservation types are available
    // /// Reserves resources from an offer.
    // pub async fn reserve_resources(
    //     &self,
    //     offer_id: &OfferId,
    //     duration: std::time::Duration,
    // ) -> Result<Reservation> {
    //     // Implementation details...
    //     todo!()
    // }
}

/// Market statistics and metrics.
#[derive(Debug, Clone)]
pub struct MarketStats {
    /// Number of active resource offers
    pub active_offers: u64,

    /// Total providers in the market
    pub total_providers: u64,

    /// 24-hour trading volume in rUv
    pub volume_24h: f64,

    /// Average CPU price per hour
    pub avg_cpu_price: f64,

    /// Average GPU price per hour
    pub avg_gpu_price: f64,

    /// Average storage price per GB per month
    pub avg_storage_price: f64,

    /// Market liquidity score (0-100)
    pub liquidity_score: f64,
}

/// A reservation for computational resources.
#[derive(Debug, Clone)]
pub struct Reservation {
    /// Unique reservation identifier
    pub id: String,

    /// Resource access endpoint
    pub access_endpoint: String,

    /// Authentication credentials
    pub auth_token: String,

    /// Reservation expiration time
    pub expires_at: std::time::SystemTime,

    /// Total cost in rUv
    pub total_cost: f64,
}

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

    #[tokio::test]
    async fn test_exchange_creation() {
        let exchange = Exchange::new("testnet").await.unwrap();
        // Add test assertions
    }

    #[tokio::test]
    async fn test_account_creation() {
        let exchange = Exchange::new("testnet").await.unwrap();
        let account = exchange.create_account("test", "password").await.unwrap();
        assert!(!account.address().is_empty());
    }
}