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

Installation

Add this to your Cargo.toml:

[dependencies]
ai-agent-bitcoin-escrow = "0.1"

Quick Start

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 (buyer, seller, arbiter)
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)  // 2-of-3 multisig
    .participant(buyer)
    .participant(seller)
    .participant(arbiter)
    .description("AI agent bounty payment")
    .condition(
        ConditionBuilder::new()
            .timelock(chrono::Utc::now() + chrono::Duration::days(7))
            .build_all()
    )
    .build()
    .unwrap();

// Initialize the multisig wallet
contract.initialize_multisig().unwrap();
let escrow_address = contract.escrow_address().unwrap();
println!("Send funds to: {}", escrow_address);

Architecture

The library is organized into several modules:

`escrow` - Main escrow contract management

EscrowContract - Represents an escrow contract
EscrowManager - Manages multiple contracts with audit logging
EscrowBuilder - Builder pattern for creating contracts

`multisig` - Multisignature wallet operations

MultisigWallet - Multisig wallet with participant keys
MultisigPSBT - Partially signed transaction coordination
create_participant() - Helper to create participants with generated keys

`conditions` - Release condition evaluation

ConditionEvaluator - Trait for evaluating conditions
StandardEvaluator - Built-in evaluator with oracle/AI support
ConditionBuilder - Builder for compound conditions

`audit` - Immutable audit logging

AuditLogger - Append-only log with integrity chain
AuditEntry - Individual log entries
Integrity verification for audit trail

`oracle` - External oracle integration

HTTPOracle - HTTP-based oracle implementation
OracleRegistry - Registry of known oracles
Predefined oracle configurations for common use cases

`types` - Common types and structures

EscrowId, AgentId, OracleId - Identifiers
EscrowRole, EscrowStatus - Enums for contract state
ReleaseCondition - Condition types for fund release

Condition Types

AI Decision

Trigger release based on an AI agent's decision:

use ai_agent_bitcoin_escrow::conditions::ConditionBuilder;

let condition = ConditionBuilder::new()
    .ai_decision("agent-001", "decision_hash_abc123")
    .build_single()
    .unwrap();

Oracle Trigger

Release based on external data (e.g., price feeds):

let condition = ConditionBuilder::new()
    .oracle("btc_price", "btc_usd", "50000")
    .build_single()
    .unwrap();

Timelock

Release after a specific time:

let condition = ConditionBuilder::new()
    .timelock(chrono::Utc::now() + chrono::Duration::days(30))
    .build_single()
    .unwrap();

Compound Conditions (AND/OR)

// All conditions must be satisfied (AND)
let condition = ConditionBuilder::new()
    .ai_decision("agent-001", "hash123")
    .timelock(future_time)
    .build_all();

// Any condition can be satisfied (OR)
let condition = ConditionBuilder::new()
    .oracle("price", "btc", "50000")
    .timelock(expiry_time)
    .build_any();

Audit Logging

All operations are logged with an immutable chain for transparency:

// Export audit log
let json = manager.export_audit().unwrap();
println!("Audit log: {}", json);

// Verify integrity
let logger = manager.audit();
assert!(logger.verify_integrity().unwrap());

AI Agent Autonomy

This library is designed to support AI agent autonomy:

Self-Custody: AI agents generate and 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 autonomous actions

Security Considerations

Private Keys: Store securely (consider HSM integration for production)
Audit Log: Provides verifiable record of all actions
Multisig: No single party can unilaterally control funds
Timelocks: Safety mechanism for dispute resolution

Testing

Run the test suite:

cargo test

Run with verbose output:

cargo test -- --nocapture

Documentation

Generate documentation:

cargo doc --open

Examples

See the examples/ directory for more usage examples:

basic_escrow.rs - Basic escrow creation and management
oracle_integration.rs - Using oracles for condition triggers
ai_decision.rs - AI agent decision-based releases

Roadmap

Taproot support (MuSig2)
Lightning Network integration
Hardware Security Module (HSM) integration
Zero-knowledge proof conditions
Cross-chain support

Contributing

Contributions are welcome! Please read our contributing guidelines.

License

Dual-licensed under:

MIT License (LICENSE-MIT)
Apache License, Version 2.0 (LICENSE-APACHE)

Acknowledgments

This library is built on:

Built for the AI Union bounty program. Enabling AI agents to participate in the Bitcoin economy autonomously.

ai-agent-bitcoin-escrow 0.1.0