ward-protocol 0.1.0__py3-none-any.whl

ward/models/loan.py

@@ -0,0 +1,81 @@
+"""Loan state model for XLS-66 loans."""
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Optional
+
+
+@dataclass
+class Loan:
+    """
+    Represents an XLS-66 Loan ledger object.
+    
+    Tracks loan state including outstanding amounts, payment schedule,
+    and default status.
+    """
+    loan_id: str
+    loan_broker_id: str
+    borrower: str
+    principal_outstanding: int
+    total_value_outstanding: int
+    interest_outstanding: int
+    management_fee_outstanding: int
+    next_payment_due_date: Optional[datetime]
+    grace_period: int  # seconds
+    flags: int
+    ledger_index: int
+    
+    # Flags from XLS-66 spec
+    LSF_LOAN_DEFAULT = 0x00010000
+    LSF_LOAN_IMPAIRED = 0x00020000
+    LSF_LOAN_OVERPAYMENT = 0x00040000
+    
+    @property
+    def is_defaulted(self) -> bool:
+        """Check if loan has defaulted."""
+        return bool(self.flags & self.LSF_LOAN_DEFAULT)
+    
+    @property
+    def is_impaired(self) -> bool:
+        """Check if loan is impaired (early warning signal)."""
+        return bool(self.flags & self.LSF_LOAN_IMPAIRED)
+    
+    @property
+    def allows_overpayment(self) -> bool:
+        """Check if loan allows overpayment."""
+        return bool(self.flags & self.LSF_LOAN_OVERPAYMENT)
+    
+    @classmethod
+    def from_ledger_entry(cls, ledger_entry: dict) -> 'Loan':
+        """
+        Create Loan instance from XRPL ledger_entry response.
+        
+        Args:
+            ledger_entry: Response from ledger_entry RPC call
+        
+        Returns:
+            Loan instance
+        """
+        node = ledger_entry.get('node', ledger_entry)
+        
+        # Parse payment due date if present
+        next_payment_due = None
+        if 'NextPaymentDueDate' in node:
+            # Convert Ripple epoch to datetime
+            ripple_epoch = node['NextPaymentDueDate']
+            unix_epoch = ripple_epoch + 946684800  # Ripple epoch offset
+            next_payment_due = datetime.utcfromtimestamp(unix_epoch)
+        
+        return cls(
+            loan_id=node.get('index', ''),
+            loan_broker_id=node.get('LoanBrokerID', ''),
+            borrower=node.get('Borrower', ''),
+            principal_outstanding=int(node.get('PrincipalOutstanding', 0)),
+            total_value_outstanding=int(node.get('TotalValueOutstanding', 0)),
+            interest_outstanding=int(node.get('InterestOutstanding', 0)),
+            management_fee_outstanding=int(node.get('ManagementFeeOutstanding', 0)),
+            next_payment_due_date=next_payment_due,
+            grace_period=int(node.get('GracePeriod', 0)),
+            flags=int(node.get('Flags', 0)),
+            ledger_index=int(ledger_entry.get('ledger_index', 0))
+        )

ward/models/loan_broker.py

@@ -0,0 +1,82 @@
+"""LoanBroker state model for XLS-66 lending."""
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class LoanBroker:
+    """
+    Represents an XLS-66 LoanBroker ledger object.
+    
+    Tracks lending activity, first-loss capital, and coverage ratios.
+    """
+    loan_broker_id: str
+    owner: str
+    vault_id: str
+    debt_total: int
+    debt_maximum: int
+    cover_available: int
+    cover_rate_minimum: float  # Basis points / 10000
+    cover_rate_liquidation: float  # Basis points / 10000
+    management_fee_rate: int
+    owner_count: int
+    ledger_index: int
+    
+    @property
+    def minimum_cover_required(self) -> int:
+        """Calculate minimum first-loss capital required."""
+        return int(self.debt_total * self.cover_rate_minimum)
+    
+    @property
+    def max_liquidation_coverage(self) -> int:
+        """Calculate maximum coverage on liquidation."""
+        return int(self.minimum_cover_required * self.cover_rate_liquidation)
+    
+    @property
+    def is_adequately_covered(self) -> bool:
+        """Check if first-loss capital meets minimum requirements."""
+        return self.cover_available >= self.minimum_cover_required
+    
+    @property
+    def coverage_ratio(self) -> float:
+        """
+        Calculate coverage ratio.
+        
+        Returns:
+            Ratio of available cover to minimum required (e.g., 1.5 = 150%)
+        """
+        if self.minimum_cover_required == 0:
+            return float('inf')
+        return self.cover_available / self.minimum_cover_required
+    
+    @classmethod
+    def from_ledger_entry(cls, ledger_entry: dict) -> 'LoanBroker':
+        """
+        Create LoanBroker instance from XRPL ledger_entry response.
+        
+        Args:
+            ledger_entry: Response from ledger_entry RPC call
+        
+        Returns:
+            LoanBroker instance
+        """
+        node = ledger_entry.get('node', ledger_entry)
+        
+        # Convert basis points to decimal
+        cover_rate_min = int(node.get('CoverRateMinimum', 0)) / 10000
+        cover_rate_liq = int(node.get('CoverRateLiquidation', 0)) / 10000
+        
+        return cls(
+            loan_broker_id=node.get('index', ''),
+            owner=node.get('Owner', ''),
+            vault_id=node.get('VaultID', ''),
+            debt_total=int(node.get('DebtTotal', 0)),
+            debt_maximum=int(node.get('DebtMaximum', 0)),
+            cover_available=int(node.get('CoverAvailable', 0)),
+            cover_rate_minimum=cover_rate_min,
+            cover_rate_liquidation=cover_rate_liq,
+            management_fee_rate=int(node.get('ManagementFeeRate', 0)),
+            owner_count=int(node.get('OwnerCount', 0)),
+            ledger_index=int(ledger_entry.get('ledger_index', 0))
+        )

ward/models/vault.py

@@ -0,0 +1,104 @@
+"""Vault state model for XLS-65 vaults."""
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class Vault:
+    """
+    Represents an XLS-65 Vault ledger object.
+    
+    Tracks pooled depositor funds and loss exposure.
+    """
+    vault_id: str
+    owner: str
+    account: str  # Pseudo-account address
+    asset: dict  # Asset type (XRP, IOU, or MPT)
+    assets_total: int
+    assets_available: int
+    loss_unrealized: int
+    shares_total: int
+    share_mpt_id: str
+    ledger_index: int
+    
+    @property
+    def real_vault_value(self) -> int:
+        """
+        Calculate real vault value accounting for unrealized losses.
+        
+        Returns:
+            AssetsTotal - LossUnrealized (in drops)
+        """
+        return self.assets_total - self.loss_unrealized
+    
+    @property
+    def share_value(self) -> float:
+        """
+        Calculate current share value.
+        
+        Uses XLS-65 formula:
+        ShareValue = (AssetsTotal - LossUnrealized) / SharesTotal
+        
+        Returns:
+            Share value in XRP (or asset units)
+        """
+        if self.shares_total == 0:
+            return 0.0
+        
+        DROPS_PER_XRP = 1_000_000
+        value_drops = self.real_vault_value / self.shares_total
+        return value_drops / DROPS_PER_XRP
+    
+    @property
+    def utilization_rate(self) -> float:
+        """
+        Calculate vault utilization rate.
+        
+        Returns:
+            (AssetsTotal - AssetsAvailable) / AssetsTotal
+        """
+        if self.assets_total == 0:
+            return 0.0
+        
+        deployed = self.assets_total - self.assets_available
+        return deployed / self.assets_total
+    
+    @property
+    def impairment_ratio(self) -> float:
+        """
+        Calculate impairment ratio.
+        
+        Returns:
+            LossUnrealized / AssetsTotal
+        """
+        if self.assets_total == 0:
+            return 0.0
+        
+        return self.loss_unrealized / self.assets_total
+    
+    @classmethod
+    def from_ledger_entry(cls, ledger_entry: dict) -> 'Vault':
+        """
+        Create Vault instance from XRPL ledger_entry response.
+        
+        Args:
+            ledger_entry: Response from ledger_entry RPC call
+        
+        Returns:
+            Vault instance
+        """
+        node = ledger_entry.get('node', ledger_entry)
+        
+        return cls(
+            vault_id=node.get('index', ''),
+            owner=node.get('Owner', ''),
+            account=node.get('Account', ''),
+            asset=node.get('Asset', {}),
+            assets_total=int(node.get('AssetsTotal', 0)),
+            assets_available=int(node.get('AssetsAvailable', 0)),
+            loss_unrealized=int(node.get('LossUnrealized', 0)),
+            shares_total=int(node.get('SharesTotal', 0)),
+            share_mpt_id=node.get('ShareMPTID', ''),
+            ledger_index=int(ledger_entry.get('ledger_index', 0))
+        )

ward/monitor.py

@@ -0,0 +1,342 @@
+"""
+XLS-66 Default Event Monitor.
+
+Real-time monitoring of XLS-66 loans, detecting defaults and calculating
+vault depositor losses.
+"""
+
+import asyncio
+import logging
+from typing import Callable, Optional, Dict, List
+from datetime import datetime
+
+from xrpl.asyncio.clients import AsyncWebsocketClient
+from xrpl.models import Subscribe, LedgerEntry, Tx
+
+from .models import Loan, LoanBroker, Vault
+from .utils.calculations import calculate_vault_loss, calculate_share_value_impact
+from .database import WardDatabase
+
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+class DefaultEvent:
+    """Represents a detected XLS-66 loan default event."""
+    
+    def __init__(
+        self,
+        loan: Loan,
+        loan_broker: LoanBroker,
+        vault: Vault,
+        default_amount: int,
+        default_covered: int,
+        vault_loss: int,
+        tx_hash: str,
+        ledger_index: int
+    ):
+        self.loan = loan
+        self.loan_broker = loan_broker
+        self.vault = vault
+        self.default_amount = default_amount
+        self.default_covered = default_covered
+        self.vault_loss = vault_loss
+        self.tx_hash = tx_hash
+        self.ledger_index = ledger_index
+        self.detected_at = datetime.utcnow()
+    
+    def __repr__(self):
+        return (
+            f"DefaultEvent(loan={self.loan.loan_id[:8]}..., "
+            f"vault_loss={self.vault_loss / 1_000_000:.2f} XRP, "
+            f"tx={self.tx_hash[:8]}...)"
+        )
+
+
+class XLS66Monitor:
+    """
+    Monitor XLS-66 lending protocol for default events.
+    
+    Subscribes to XRPL ledger stream and detects LoanManage transactions
+    with tfLoanDefault flag. Calculates vault losses and triggers callbacks.
+    
+    Example:
+        monitor = XLS66Monitor(
+            "wss://xrplcluster.com",
+            database_url="postgresql://user:pass@localhost/ward"
+        )
+        
+        @monitor.on_default
+        async def handle_default(event: DefaultEvent):
+            print(f"Default detected: {event.vault_loss} drops lost")
+        
+        await monitor.start()
+    """
+    
+    def __init__(
+        self,
+        websocket_url: str = "wss://xrplcluster.com",
+        monitored_loan_brokers: Optional[List[str]] = None,
+        database_url: Optional[str] = None
+    ):
+        """
+        Initialize XLS-66 monitor.
+        
+        Args:
+            websocket_url: XRPL WebSocket endpoint
+            monitored_loan_brokers: List of LoanBroker IDs to monitor
+                                   (None = monitor all)
+            database_url: PostgreSQL connection string (optional)
+        """
+        self.websocket_url = websocket_url
+        self.monitored_loan_brokers = set(monitored_loan_brokers or [])
+        self.client: Optional[AsyncWebsocketClient] = None
+        self.running = False
+        self.default_callbacks: List[Callable] = []
+        
+        # Database connection (optional)
+        self.db = WardDatabase(database_url) if database_url else None
+        
+        # Cache for ledger state
+        self._loan_broker_cache: Dict[str, LoanBroker] = {}
+        self._vault_cache: Dict[str, Vault] = {}
+    
+    def on_default(self, callback: Callable):
+        """
+        Register callback for default events.
+        
+        Decorator usage:
+            @monitor.on_default
+            async def handle(event: DefaultEvent):
+                ...
+        
+        Args:
+            callback: Async function taking DefaultEvent parameter
+        """
+        self.default_callbacks.append(callback)
+        return callback
+    
+    async def start(self):
+        """Start monitoring XLS-66 events."""
+        logger.info(f"Starting XLS-66 monitor on {self.websocket_url}")
+        
+        # Connect to database if configured
+        if self.db:
+            await self.db.connect()
+            logger.info("Connected to PostgreSQL database")
+        
+        self.client = AsyncWebsocketClient(self.websocket_url)
+        await self.client.open()
+        
+        # Subscribe to ledger stream
+        subscribe_request = Subscribe(streams=["ledger", "transactions"])
+        await self.client.send(subscribe_request)
+        
+        logger.info("Subscribed to ledger stream")
+        self.running = True
+        
+        # Process messages
+        async for message in self.client:
+            try:
+                await self._handle_message(message)
+            except Exception as e:
+                logger.error(f"Error processing message: {e}", exc_info=True)
+    
+    async def stop(self):
+        """Stop monitoring."""
+        logger.info("Stopping XLS-66 monitor")
+        self.running = False
+        if self.client and self.client.is_open():
+            await self.client.close()
+        if self.db:
+            await self.db.disconnect()
+            logger.info("Disconnected from database")
+    
+    async def _handle_message(self, message: dict):
+        """Process incoming WebSocket message."""
+        if not isinstance(message, dict):
+            return
+        
+        msg_type = message.get('type')
+        
+        if msg_type == 'transaction':
+            await self._handle_transaction(message)
+    
+    async def _handle_transaction(self, message: dict):
+        """Process transaction message looking for LoanManage defaults."""
+        tx = message.get('transaction', {})
+        meta = message.get('meta', {})
+        
+        # Check if this is a LoanManage transaction
+        if tx.get('TransactionType') != 'LoanManage':
+            return
+        
+        # Check for default flag (0x00010000 = tfLoanDefault)
+        TF_LOAN_DEFAULT = 0x00010000
+        flags = tx.get('Flags', 0)
+        
+        if not (flags & TF_LOAN_DEFAULT):
+            return
+        
+        # This is a default event!
+        loan_id = tx.get('LoanID')
+        tx_hash = tx.get('hash')
+        ledger_index = message.get('ledger_index', 0)
+        
+        logger.info(f"Default detected: Loan {loan_id[:8]}... in tx {tx_hash[:8]}...")
+        
+        try:
+            # Fetch loan, broker, and vault state
+            loan = await self._get_loan(loan_id)
+            loan_broker = await self._get_loan_broker(loan.loan_broker_id)
+            vault = await self._get_vault(loan_broker.vault_id)
+            
+            # Check if we're monitoring this broker
+            if self.monitored_loan_brokers and loan_broker.loan_broker_id not in self.monitored_loan_brokers:
+                logger.debug(f"Skipping unmonitored LoanBroker {loan_broker.loan_broker_id[:8]}...")
+                return
+            
+            # Calculate loss amounts
+            loss_calc = calculate_vault_loss(
+                principal_outstanding=loan.principal_outstanding,
+                interest_outstanding=loan.interest_outstanding,
+                debt_total=loan_broker.debt_total,
+                cover_available=loan_broker.cover_available,
+                cover_rate_minimum=loan_broker.cover_rate_minimum,
+                cover_rate_liquidation=loan_broker.cover_rate_liquidation
+            )
+            
+            # Create default event
+            event = DefaultEvent(
+                loan=loan,
+                loan_broker=loan_broker,
+                vault=vault,
+                default_amount=loss_calc['default_amount'],
+                default_covered=loss_calc['default_covered'],
+                vault_loss=loss_calc['vault_loss'],
+                tx_hash=tx_hash,
+                ledger_index=ledger_index
+            )
+            
+            # Log event details
+            logger.info(
+                f"Default details: "
+                f"Amount={event.default_amount / 1_000_000:.2f} XRP, "
+                f"Covered={event.default_covered / 1_000_000:.2f} XRP, "
+                f"VaultLoss={event.vault_loss / 1_000_000:.2f} XRP"
+            )
+            
+            # Calculate share value impact
+            share_impact = calculate_share_value_impact(
+                assets_total_before=vault.assets_total,
+                loss_unrealized=vault.loss_unrealized,
+                shares_total=vault.shares_total,
+                vault_loss=event.vault_loss
+            )
+            
+            logger.info(
+                f"Share impact: "
+                f"{share_impact['share_value_before']:.6f} XRP → "
+                f"{share_impact['share_value_after']:.6f} XRP "
+                f"({share_impact['loss_percentage']:.2f}% loss)"
+            )
+            
+            # Store event in database
+            if self.db:
+                try:
+                    event_id = await self.db.log_default_event(
+                        loan_id=loan.loan_id,
+                        loan_broker_id=loan_broker.loan_broker_id,
+                        vault_id=vault.vault_id,
+                        borrower_address=loan.borrower,
+                        default_amount=event.default_amount,
+                        default_covered=event.default_covered,
+                        vault_loss=event.vault_loss,
+                        tx_hash=tx_hash,
+                        ledger_index=ledger_index
+                    )
+                    logger.info(f"Logged default event to database: {event_id}")
+                    
+                    # Update vault state
+                    await self.db.upsert_vault_state(
+                        vault_id=vault.vault_id,
+                        loan_broker_id=loan_broker.loan_broker_id,
+                        asset_type="XRP",  # TODO: Parse from vault.asset
+                        assets_total=vault.assets_total - event.vault_loss,
+                        assets_available=vault.assets_available,
+                        loss_unrealized=vault.loss_unrealized,
+                        shares_total=vault.shares_total,
+                        share_value=share_impact['share_value_after'],
+                        ledger_index=ledger_index
+                    )
+                    logger.info("Updated vault state in database")
+                except Exception as db_error:
+                    logger.error(f"Database error: {db_error}")
+            
+            # Trigger callbacks
+            await self._trigger_callbacks(event)
+            
+        except Exception as e:
+            logger.error(f"Error processing default event: {e}", exc_info=True)
+    
+    async def _trigger_callbacks(self, event: DefaultEvent):
+        """Trigger all registered default callbacks."""
+        for callback in self.default_callbacks:
+            try:
+                if asyncio.iscoroutinefunction(callback):
+                    await callback(event)
+                else:
+                    callback(event)
+            except Exception as e:
+                logger.error(f"Error in callback {callback.__name__}: {e}", exc_info=True)
+    
+    async def _get_loan(self, loan_id: str) -> Loan:
+        """Fetch Loan ledger entry."""
+        request = LedgerEntry(loan=loan_id)
+        response = await self.client.request(request)
+        
+        if not response.is_successful():
+            raise ValueError(f"Failed to fetch Loan {loan_id}: {response.result}")
+        
+        return Loan.from_ledger_entry(response.result)
+    
+    async def _get_loan_broker(self, loan_broker_id: str) -> LoanBroker:
+        """Fetch LoanBroker ledger entry (with caching)."""
+        if loan_broker_id in self._loan_broker_cache:
+            return self._loan_broker_cache[loan_broker_id]
+        
+        request = LedgerEntry(loan_broker=loan_broker_id)
+        response = await self.client.request(request)
+        
+        if not response.is_successful():
+            raise ValueError(f"Failed to fetch LoanBroker {loan_broker_id}: {response.result}")
+        
+        broker = LoanBroker.from_ledger_entry(response.result)
+        self._loan_broker_cache[loan_broker_id] = broker
+        return broker
+    
+    async def _get_vault(self, vault_id: str) -> Vault:
+        """Fetch Vault ledger entry (with caching)."""
+        if vault_id in self._vault_cache:
+            return self._vault_cache[vault_id]
+        
+        request = LedgerEntry(vault=vault_id)
+        response = await self.client.request(request)
+        
+        if not response.is_successful():
+            raise ValueError(f"Failed to fetch Vault {vault_id}: {response.result}")
+        
+        vault = Vault.from_ledger_entry(response.result)
+        self._vault_cache[vault_id] = vault
+        return vault
+    
+    def add_loan_broker(self, loan_broker_id: str):
+        """Add a LoanBroker to monitor list."""
+        self.monitored_loan_brokers.add(loan_broker_id)
+        logger.info(f"Now monitoring LoanBroker {loan_broker_id[:8]}...")
+    
+    def remove_loan_broker(self, loan_broker_id: str):
+        """Remove a LoanBroker from monitor list."""
+        self.monitored_loan_brokers.discard(loan_broker_id)
+        logger.info(f"Stopped monitoring LoanBroker {loan_broker_id[:8]}...")