ai_agent_bitcoin_escrow/

lib.rs

//! # AI Agent Bitcoin Escrow Library
//!
//! A Rust library that enables AI agents to create, manage, and execute Bitcoin
//! escrow contracts using multisig. The library supports condition-based fund
//! releases triggered by AI agent decisions or external oracles, with full
//! audit logging for all actions.
//!
//! ## Features
//!
//! - **Multisig Support**: 2-of-3 (or n-of-m) multisig escrow contracts
//! - **Condition-Based Release**: AI decisions, oracle triggers, timelocks
//! - **Audit Logging**: Immutable, chained audit log for all operations
//! - **Oracle Integration**: HTTP-based oracle support for real-world data
//! - **AI Agent Autonomy**: Designed for autonomous AI agent economic activities
//!
//! ## Quick Start
//!
//! ```rust,no_run
//! use ai_agent_bitcoin_escrow::{
//!     escrow::{EscrowBuilder, EscrowManager},
//!     multisig::create_participant,
//!     conditions::ConditionBuilder,
//!     audit::AuditLogger,
//!     types::{EscrowConfig, EscrowRole},
//! };
//! use bitcoin::Network;
//!
//! // Create an escrow manager with audit logging
//! let audit = AuditLogger::new("/tmp/audit.log").unwrap();
//! let mut manager = EscrowManager::new(audit);
//!
//! // Create participants
//! let (buyer, _buyer_key) = create_participant(
//!     EscrowRole::Buyer, 
//!     "buyer-1".to_string(), 
//!     Network::Testnet
//! ).unwrap();
//! let (seller, _seller_key) = create_participant(
//!     EscrowRole::Seller, 
//!     "seller-1".to_string(), 
//!     Network::Testnet
//! ).unwrap();
//! let (arbiter, _arbiter_key) = create_participant(
//!     EscrowRole::Arbiter, 
//!     "arbiter-1".to_string(), 
//!     Network::Testnet
//! ).unwrap();
//!
//! // Build an escrow contract
//! let contract = EscrowBuilder::new()
//!     .network(Network::Testnet)
//!     .threshold(2)
//!     .participant(buyer)
//!     .participant(seller)
//!     .participant(arbiter)
//!     .description("AI agent bounty payment")
//!     .build()
//!     .unwrap();
//!
//! println!("Escrow contract created: {}", contract.id);
//! ```
//!
//! ## Architecture
//!
//! The library is organized into several modules:
//!
//! - [`escrow`] - Main escrow contract management
//! - [`multisig`] - Multisignature wallet operations
//! - [`conditions`] - Release condition evaluation
//! - [`audit`] - Immutable audit logging
//! - [`oracle`] - External oracle integration
//! - [`types`] - Common types and structures
//! - [`error`] - Error handling
//!
//! ## AI Agent Integration
//!
//! This library is designed to be used by AI agents for autonomous economic
//! activities. Key features for AI agent autonomy:
//!
//! - **Self-Custody**: AI agents control their own keys
//! - **Verifiable Actions**: All operations are logged in an immutable audit log
//! - **Conditional Releases**: Funds can be released based on AI decisions
//! - **Oracle Integration**: Real-world data can trigger releases
//!
//! ## Security Considerations
//!
//! - All private keys should be securely stored
//! - The audit log provides a verifiable record of all actions
//! - Multisig ensures no single party can unilaterally control funds
//! - Timelocks provide a safety mechanism for dispute resolution
//!
//! ## License
//!
//! Dual-licensed under MIT or Apache-2.0.

pub mod audit;
pub mod conditions;
pub mod error;
pub mod escrow;
pub mod multisig;
pub mod oracle;
pub mod types;

// Re-export commonly used types at the crate root
pub use error::{EscrowError, Result};
pub use escrow::{EscrowBuilder, EscrowContract, EscrowManager};
pub use types::{
    AgentId, ConditionResult, EscrowConfig, EscrowId, EscrowParticipant,
    EscrowRole, EscrowStatus, OracleId, ReleaseCondition,
};

/// Library version.
pub const VERSION: &str = env!("CARGO_PKG_VERSION");

/// Library name.
pub const NAME: &str = env!("CARGO_PKG_NAME");

#[cfg(test)]
mod tests {
    use super::*;
    use audit::AuditLogger;
    use bitcoin::Network;
    use escrow::EscrowBuilder;
    use multisig::create_participant;
    use types::EscrowRole;

    #[test]
    fn test_library_version() {
        assert!(!VERSION.is_empty());
        assert_eq!(NAME, "ai-agent-bitcoin-escrow");
    }

    #[test]
    fn test_full_escrow_workflow() {
        // Create participants
        let (buyer, _) = create_participant(EscrowRole::Buyer, "buyer-1".to_string(), Network::Testnet).unwrap();
        let (seller, _) = create_participant(EscrowRole::Seller, "seller-1".to_string(), Network::Testnet).unwrap();
        let (arbiter, _) = create_participant(EscrowRole::Arbiter, "arbiter-1".to_string(), Network::Testnet).unwrap();

        // Build escrow
        let contract = EscrowBuilder::new()
            .network(Network::Testnet)
            .threshold(2)
            .participant(buyer)
            .participant(seller)
            .participant(arbiter)
            .description("Test bounty payment")
            .build()
            .unwrap();

        // Verify contract
        assert_eq!(contract.status, EscrowStatus::Created);
        assert_eq!(contract.participants.len(), 3);
        assert_eq!(contract.config.threshold, 2);

        // Initialize multisig
        let mut contract = contract;
        contract.initialize_multisig().unwrap();
        assert!(contract.multisig.is_some());

        // Get escrow address
        let address = contract.escrow_address().unwrap();
        assert!(!address.to_string().is_empty());
    }

    #[tokio::test]
    async fn test_escrow_manager_workflow() {
        let audit = AuditLogger::in_memory();
        let mut manager = EscrowManager::new(audit);

        // Create contract
        let contract = manager
            .create_contract(
                EscrowConfig::default(),
                Some("Test escrow".to_string()),
                "test-agent".to_string(),
            )
            .unwrap();

        let contract_id = contract.id.clone();

        // Add participants
        let (buyer, _) = create_participant(EscrowRole::Buyer, "buyer-1".to_string(), Network::Testnet).unwrap();
        let (seller, _) = create_participant(EscrowRole::Seller, "seller-1".to_string(), Network::Testnet).unwrap();
        let (arbiter, _) = create_participant(EscrowRole::Arbiter, "arbiter-1".to_string(), Network::Testnet).unwrap();

        manager
            .add_participant(&contract_id, buyer, "test-agent".to_string())
            .unwrap();
        manager
            .add_participant(&contract_id, seller, "test-agent".to_string())
            .unwrap();
        manager
            .add_participant(&contract_id, arbiter, "test-agent".to_string())
            .unwrap();

        // Initialize multisig
        let address = manager.initialize_multisig(&contract_id).unwrap();
        assert!(!address.to_string().is_empty());

        // Verify audit log
        let entries = manager.audit().get_entries(&contract_id);
        assert!(entries.len() >= 4); // Created + 3 participants
    }
}