# Multi-Network Bitcoin Wallet Manager API Documentation

## Overview

Production-ready Bitcoin wallet manager supporting mainnet, testnet, and regtest networks with comprehensive security validation and error handling.

## Quick Start

```python
from multi_network_wallet import MultiNetworkWalletManager, BitcoinNetwork

# Initialize for specific network
manager = MultiNetworkWalletManager(BitcoinNetwork.TESTNET)

# Connect to Bitcoin Core
result = manager.simulate_connection("rpc_user", "secure_password")
if result['success']:
    # Create secure wallet
    wallet = manager.create_wallet("my_wallet", "strong_passphrase")
    print(f"Receive Address: {wallet['addresses']['receiving']}")
```

## API Reference

### MultiNetworkWalletManager

#### Constructor
```python
MultiNetworkWalletManager(network: BitcoinNetwork = BitcoinNetwork.MAINNET)
```

**Parameters:**
- `network`: Bitcoin network to operate on

**Example:**
```python
manager = MultiNetworkWalletManager(BitcoinNetwork.MAINNET)
```

#### simulate_connection()
```python
simulate_connection(rpc_user: str, rpc_pass: str) -> Dict[str, Any]
```

Simulate Bitcoin Core RPC connection with security validation.

**Parameters:**
- `rpc_user`: RPC username (min 8 chars)
- `rpc_pass`: RPC password (min 16 chars, strong complexity)

**Returns:**
```json
{
    "success": true,
    "network": "mainnet",
    "rpc_port": 8332,
    "connection_time": "2026-02-11T19:45:00",
    "server_version": "Bitcoin Core 30.2.0"
}
```

#### create_wallet()
```python
create_wallet(wallet_name: str, passphrase: Optional[str] = None) -> Dict[str, Any]
```

Create new wallet with optional encryption.

**Parameters:**
- `wallet_name`: Wallet name (1-100 chars, no special chars)
- `passphrase`: Optional encryption passphrase (min 8 chars if provided)

**Returns:**
```json
{
    "success": true,
    "wallet_name": "demo_wallet",
    "network": "mainnet",
    "created_at": "2026-02-11T19:45:00",
    "encrypted": true,
    "addresses": {
        "receiving": "1abc123...",
        "change": "1def456..."
    }
}
```

#### import_private_key()
```python
import_private_key(private_key: str, label: Optional[str] = None) -> Dict[str, Any]
```

Import WIF private key with security validation.

**Parameters:**
- `private_key`: WIF format private key
- `label`: Optional label for the imported key

**Returns:**
```json
{
    "success": true,
    "address": "1xyz789...",
    "label": "imported_20260211",
    "network": "testnet",
    "import_time": "2026-02-11T19:45:00"
}
```

#### switch_network()
```python
switch_network(new_network: BitcoinNetwork) -> Dict[str, Any]
```

Switch to different Bitcoin network (must be disconnected).

**Parameters:**
- `new_network`: Target network to switch to

**Returns:**
```json
{
    "success": true,
    "from_network": "testnet",
    "to_network": "mainnet",
    "switch_time": "2026-02-11T19:45:00"
}
```

#### get_network_info()
```python
get_network_info() -> Dict[str, Any]
```

Get detailed network configuration information.

**Returns:**
```json
{
    "network": "mainnet",
    "config": {
        "rpc_port": 8332,
        "default_port": 8333,
        "magic_bytes": "f9beb4d9",
        "address_prefix": "00",
        "script_prefix": "05"
    },
    "connected": true,
    "supported_features": [
        "multi_wallet",
        "rpc_encryption",
        "bip39_mnemonic",
        "bech32_addresses"
    ]
}
```

## Network Constants

### BitcoinNetwork Enum
```python
class BitcoinNetwork(Enum):
    MAINNET = "mainnet"    # Production network
    TESTNET = "testnet"    # Test network
    REGTEST = "regtest"    # Regression testing
```

### Network Configurations

| Network | RPC Port | Default Port | Address Prefix |
|---------|----------|---------------|----------------|
| Mainnet | 8332     | 8333          | 1, 3, bc1      |
| Testnet | 18332    | 18333         | m, n, 2        |
| Regtest | 18443    | 18444         | m, n, 2        |

## Security Validation

### Address Validation
```python
from multi_network_wallet import SecurityValidator

validator = SecurityValidator()
is_valid = validator.validate_address_format(address, BitcoinNetwork.MAINNET)
```

### Private Key Security
```python
from security_validator import PrivateKeySecurityValidator

validator = PrivateKeySecurityValidator()
result = validator.validate_private_key_security(private_key)

# Check results
print(f"Valid: {result['valid']}")
print(f"Security Level: {result['security_level']}")
print(f"Entropy Score: {result['entropy_score']}")
```

### Wallet Encryption Strength
```python
result = validator.validate_wallet_encryption(passphrase)
print(f"Strength Score: {result['strength_score']}/100")
print(f"Security Level: {result['security_level']}")
```

## Network Configuration Validation

```python
from network_validator import NetworkConfigValidator

validator = NetworkConfigValidator()
result = validator.validate_complete_config(BitcoinNetwork.MAINNET)

print(f"Configuration Valid: {result.is_valid}")
print(f"Security Score: {result.security_score}/100")
print(f"Issues: {result.errors}")
print(f"Recommendations: {result.recommendations}")
```

## Security Auditing

```python
from security_validator import SecurityAuditor

auditor = SecurityAuditor()

# Audit wallet creation
audit = auditor.audit_wallet_creation(
    "secure_wallet", "StrongPassphrase123!", BitcoinNetwork.MAINNET
)
print(f"Audit Passed: {audit.passed}")
print(f"Security Level: {audit.level}")

# Audit private key operation
key_audit = auditor.audit_private_key_operation(
    "import", private_key, "test_context"
)
```

## Error Handling

All API methods return structured error information:

```json
{
    "success": false,
    "error": "Description of error",
    "issues": ["Additional issue details"]
}
```

Common error scenarios:
- Invalid credentials
- Invalid private key format
- Network connection required
- Invalid wallet name
- Weak passphrase

## Security Best Practices

1. **Always use strong RPC credentials** (min 16 chars with complexity)
2. **Encrypt mainnet wallets** with strong passphrases
3. **Validate private keys** before import operations
4. **Use appropriate networks** for different environments
5. **Monitor security scores** for configurations
6. **Follow audit recommendations** for security improvements

## Integration Examples

### AI Agent Onboarding
```python
def onboard_ai_agent(agent_name: str):
    """Secure onboarding for AI agents"""
    manager = MultiNetworkWalletManager(BitcoinNetwork.TESTNET)
    
    # Generate secure credentials
    secure_pass = PrivateKeySecurityValidator().generate_secure_wallet_passphrase()
    
    # Connect and create wallet
    manager.simulate_connection(f"agent_{agent_name}", secure_pass)
    wallet = manager.create_wallet(f"{agent_name}_wallet", secure_pass)
    
    # Audit the operation
    auditor = SecurityAuditor()
    audit = auditor.audit_wallet_creation(wallet['wallet_name'], secure_pass, BitcoinNetwork.TESTNET)
    
    return {
        "wallet": wallet,
        "security_audit": audit,
        "credentials": {"username": f"agent_{agent_name}", "password": secure_pass}
    }
```

### Network Switching
```python
def switch_to_production(test_manager):
    """Safely switch from testnet to mainnet"""
    # Disconnect first
    test_manager.connected = False
    
    # Switch network
    result = test_manager.switch_network(BitcoinNetwork.MAINNET)
    
    if result['success']:
        # Reconnect with production credentials
        conn = test_manager.simulate_connection("prod_user", "prod_pass")
        return {"switched": True, "connected": conn['success']}
    
    return {"switched": False, "reason": result.get("error")}
```

## Testing

Run the comprehensive test suite:

```bash
python3 test_multinet.py
```

All 13 tests should pass with 100% success rate.