ward-protocol 0.1.0__py3-none-any.whl

ward/database.py

@@ -0,0 +1,266 @@
+"""Database connection and operations for Ward Protocol."""
+
+import os
+from typing import Optional, List, Dict, Any
+from datetime import datetime
+import asyncpg
+from contextlib import asynccontextmanager
+
+
+class WardDatabase:
+    """PostgreSQL database connection for Ward Protocol."""
+    
+    def __init__(self, connection_string: Optional[str] = None):
+        """
+        Initialize database connection.
+        
+        Args:
+            connection_string: PostgreSQL connection string
+                              (defaults to DATABASE_URL env var)
+        """
+        self.connection_string = connection_string or os.getenv(
+            'DATABASE_URL',
+            'postgresql://ward:ward@localhost/ward_protocol'
+        )
+        self.pool: Optional[asyncpg.Pool] = None
+    
+    async def connect(self):
+        """Create connection pool."""
+        self.pool = await asyncpg.create_pool(
+            self.connection_string,
+            min_size=2,
+            max_size=10
+        )
+    
+    async def disconnect(self):
+        """Close connection pool."""
+        if self.pool:
+            await self.pool.close()
+    
+    @asynccontextmanager
+    async def transaction(self):
+        """Context manager for database transactions."""
+        async with self.pool.acquire() as conn:
+            async with conn.transaction():
+                yield conn
+    
+    # ===== DEFAULT EVENTS =====
+    
+    async def log_default_event(
+        self,
+        loan_id: str,
+        loan_broker_id: str,
+        vault_id: str,
+        borrower_address: str,
+        default_amount: int,
+        default_covered: int,
+        vault_loss: int,
+        tx_hash: str,
+        ledger_index: int
+    ) -> str:
+        """
+        Log a default event.
+        
+        Returns:
+            event_id (UUID)
+        """
+        async with self.pool.acquire() as conn:
+            row = await conn.fetchrow(
+                """
+                INSERT INTO default_events (
+                    loan_id, loan_broker_id, vault_id, borrower_address,
+                    default_amount, default_covered, vault_loss,
+                    tx_hash, ledger_index
+                ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+                RETURNING event_id
+                """,
+                loan_id, loan_broker_id, vault_id, borrower_address,
+                default_amount, default_covered, vault_loss,
+                tx_hash, ledger_index
+            )
+            return str(row['event_id'])
+    
+    async def get_default_events(
+        self,
+        vault_id: Optional[str] = None,
+        limit: int = 100
+    ) -> List[Dict[str, Any]]:
+        """Get default events, optionally filtered by vault."""
+        async with self.pool.acquire() as conn:
+            if vault_id:
+                rows = await conn.fetch(
+                    """
+                    SELECT * FROM default_events
+                    WHERE vault_id = $1
+                    ORDER BY detected_at DESC
+                    LIMIT $2
+                    """,
+                    vault_id, limit
+                )
+            else:
+                rows = await conn.fetch(
+                    """
+                    SELECT * FROM default_events
+                    ORDER BY detected_at DESC
+                    LIMIT $1
+                    """,
+                    limit
+                )
+            return [dict(row) for row in rows]
+    
+    # ===== CLAIMS =====
+    
+    async def create_claim(
+        self,
+        policy_id: str,
+        loan_id: str,
+        loan_manage_tx_hash: str,
+        loan_broker_id: str,
+        vault_id: str,
+        default_amount: int,
+        default_covered: int,
+        vault_loss: int,
+        claim_payout: int
+    ) -> str:
+        """
+        Create a new claim.
+        
+        Returns:
+            claim_id (UUID)
+        """
+        async with self.pool.acquire() as conn:
+            row = await conn.fetchrow(
+                """
+                INSERT INTO claims (
+                    policy_id, loan_id, loan_manage_tx_hash,
+                    loan_broker_id, vault_id,
+                    default_amount, default_covered, vault_loss,
+                    claim_payout, status
+                ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, 'pending')
+                RETURNING claim_id
+                """,
+                policy_id, loan_id, loan_manage_tx_hash,
+                loan_broker_id, vault_id,
+                default_amount, default_covered, vault_loss,
+                claim_payout
+            )
+            return str(row['claim_id'])
+    
+    async def update_claim_status(
+        self,
+        claim_id: str,
+        status: str,
+        escrow_tx_hash: Optional[str] = None,
+        settlement_tx_hash: Optional[str] = None,
+        rejection_reason: Optional[str] = None
+    ):
+        """Update claim status."""
+        async with self.pool.acquire() as conn:
+            if status == 'validated':
+                await conn.execute(
+                    """
+                    UPDATE claims
+                    SET status = $1, validated_at = NOW()
+                    WHERE claim_id = $2
+                    """,
+                    status, claim_id
+                )
+            elif status == 'escrowed' and escrow_tx_hash:
+                await conn.execute(
+                    """
+                    UPDATE claims
+                    SET status = $1, escrow_tx_hash = $2
+                    WHERE claim_id = $3
+                    """,
+                    status, escrow_tx_hash, claim_id
+                )
+            elif status == 'settled' and settlement_tx_hash:
+                await conn.execute(
+                    """
+                    UPDATE claims
+                    SET status = $1, settlement_tx_hash = $2, settled_at = NOW()
+                    WHERE claim_id = $3
+                    """,
+                    status, settlement_tx_hash, claim_id
+                )
+            elif status == 'rejected' and rejection_reason:
+                await conn.execute(
+                    """
+                    UPDATE claims
+                    SET status = $1, rejection_reason = $2
+                    WHERE claim_id = $3
+                    """,
+                    status, rejection_reason, claim_id
+                )
+    
+    async def get_claims(
+        self,
+        policy_id: Optional[str] = None,
+        status: Optional[str] = None,
+        limit: int = 100
+    ) -> List[Dict[str, Any]]:
+        """Get claims with optional filters."""
+        async with self.pool.acquire() as conn:
+            query = "SELECT * FROM claims WHERE 1=1"
+            params = []
+            param_num = 1
+            
+            if policy_id:
+                query += f" AND policy_id = ${param_num}"
+                params.append(policy_id)
+                param_num += 1
+            
+            if status:
+                query += f" AND status = ${param_num}"
+                params.append(status)
+                param_num += 1
+            
+            query += f" ORDER BY created_at DESC LIMIT ${param_num}"
+            params.append(limit)
+            
+            rows = await conn.fetch(query, *params)
+            return [dict(row) for row in rows]
+    
+    # ===== MONITORED VAULTS =====
+    
+    async def upsert_vault_state(
+        self,
+        vault_id: str,
+        loan_broker_id: str,
+        asset_type: str,
+        assets_total: int,
+        assets_available: int,
+        loss_unrealized: int,
+        shares_total: int,
+        share_value: float,
+        ledger_index: int
+    ):
+        """Insert or update vault state."""
+        async with self.pool.acquire() as conn:
+            await conn.execute(
+                """
+                INSERT INTO monitored_vaults (
+                    vault_id, loan_broker_id, asset_type,
+                    assets_total, assets_available, loss_unrealized,
+                    shares_total, share_value, last_updated_ledger,
+                    last_checked
+                ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, NOW())
+                ON CONFLICT (vault_id) DO UPDATE SET
+                    assets_total = EXCLUDED.assets_total,
+                    assets_available = EXCLUDED.assets_available,
+                    loss_unrealized = EXCLUDED.loss_unrealized,
+                    shares_total = EXCLUDED.shares_total,
+                    share_value = EXCLUDED.share_value,
+                    last_updated_ledger = EXCLUDED.last_updated_ledger,
+                    last_checked = NOW()
+                """,
+                vault_id, loan_broker_id, asset_type,
+                assets_total, assets_available, loss_unrealized,
+                shares_total, share_value, ledger_index
+            )
+    
+    async def get_monitored_vaults(self) -> List[Dict[str, Any]]:
+        """Get all monitored vaults."""
+        async with self.pool.acquire() as conn:
+            rows = await conn.fetch("SELECT * FROM monitored_vaults")
+            return [dict(row) for row in rows]

ward/escrow.py

@@ -0,0 +1,370 @@
+"""
+Escrow settlement for insurance claims.
+
+Implements 48-hour dispute window before claim payouts using XRPL Escrow.
+"""
+
+import logging
+from typing import Optional, Dict, Any, List
+from datetime import datetime, timedelta
+from dataclasses import dataclass
+
+from xrpl.models import (
+    EscrowCreate, EscrowFinish, EscrowCancel,
+    AccountObjects, Memo
+)
+from xrpl.wallet import Wallet
+from xrpl.asyncio.clients import AsyncWebsocketClient
+from xrpl.asyncio.transaction import submit_and_wait
+from xrpl.utils import str_to_hex, ripple_time_to_datetime, datetime_to_ripple_time
+
+from .database import WardDatabase
+
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class EscrowStatus:
+    """Status of an escrowed claim."""
+    claim_id: str
+    escrow_sequence: int
+    amount: int  # drops
+    destination: str
+    finish_after: datetime
+    cancel_after: datetime
+    status: str  # pending, finishable, finished, cancelled
+    can_finish: bool
+    can_cancel: bool
+
+
+class ClaimEscrow:
+    """
+    Manages escrowed insurance claim payouts.
+    
+    Creates time-locked escrows with 48-hour dispute windows,
+    allowing community review before claim settlement.
+    """
+    
+    DISPUTE_WINDOW_HOURS = 48
+    CANCEL_BUFFER_HOURS = 72  # Extra time before auto-cancel
+    
+    def __init__(
+        self,
+        client: AsyncWebsocketClient,
+        wallet: Wallet,
+        database: WardDatabase
+    ):
+        """
+        Initialize escrow manager.
+        
+        Args:
+            client: XRPL client
+            wallet: Pool wallet (escrow source)
+            database: Database connection
+        """
+        self.client = client
+        self.wallet = wallet
+        self.db = database
+    
+    async def create_claim_escrow(
+        self,
+        claim_id: str,
+        payout_amount: int,
+        destination: str
+    ) -> Dict[str, Any]:
+        """
+        Create escrowed claim payout with 48-hour dispute window.
+        
+        Args:
+            claim_id: Claim UUID
+            payout_amount: Payout in drops
+            destination: Claim recipient address
+        
+        Returns:
+            Dictionary with escrow details
+        """
+        logger.info(
+            f"Creating claim escrow: {payout_amount / 1_000_000:.2f} XRP "
+            f"to {destination} (48hr window)"
+        )
+        
+        # Calculate times
+        now = datetime.utcnow()
+        finish_after = now + timedelta(hours=self.DISPUTE_WINDOW_HOURS)
+        cancel_after = finish_after + timedelta(hours=self.CANCEL_BUFFER_HOURS)
+        
+        # Convert to Ripple time
+        finish_after_ripple = datetime_to_ripple_time(finish_after)
+        cancel_after_ripple = datetime_to_ripple_time(cancel_after)
+        
+        # Create EscrowCreate transaction
+        escrow_tx = EscrowCreate(
+            account=self.wallet.address,
+            destination=destination,
+            amount=str(payout_amount),
+            finish_after=finish_after_ripple,
+            cancel_after=cancel_after_ripple,
+            memos=[
+                Memo(
+                    memo_type=str_to_hex("ward_claim_escrow"),
+                    memo_data=str_to_hex(f"Claim ID: {claim_id}")
+                )
+            ]
+        )
+        
+        response = await submit_and_wait(escrow_tx, self.client, self.wallet)
+        
+        if not response.is_successful():
+            raise Exception(f"Escrow creation failed: {response.result}")
+        
+        tx_hash = response.result['hash']
+        escrow_sequence = response.result['Sequence']
+        
+        # Update claim in database
+        await self.db.update_claim_status(
+            claim_id=claim_id,
+            status='escrowed',
+            escrow_tx_hash=tx_hash
+        )
+        
+        # Store escrow sequence
+        await self._store_escrow_sequence(claim_id, escrow_sequence)
+        
+        logger.info(
+            f"Escrow created: {tx_hash} (seq: {escrow_sequence}). "
+            f"Finishable after: {finish_after.isoformat()}"
+        )
+        
+        return {
+            'claim_id': claim_id,
+            'escrow_tx_hash': tx_hash,
+            'escrow_sequence': escrow_sequence,
+            'amount': payout_amount,
+            'destination': destination,
+            'finish_after': finish_after,
+            'cancel_after': cancel_after,
+            'status': 'escrowed'
+        }
+    
+    async def finish_escrow(
+        self,
+        claim_id: str,
+        escrow_sequence: int
+    ) -> str:
+        """
+        Finish escrow and release claim payout.
+        
+        Args:
+            claim_id: Claim UUID
+            escrow_sequence: Escrow sequence number
+        
+        Returns:
+            Transaction hash
+        """
+        logger.info(f"Finishing escrow for claim {claim_id} (seq: {escrow_sequence})")
+        
+        # Verify escrow is finishable
+        status = await self.get_escrow_status(escrow_sequence)
+        
+        if not status.can_finish:
+            raise ValueError(
+                f"Escrow not finishable yet. Available after: {status.finish_after}"
+            )
+        
+        # Create EscrowFinish transaction
+        finish_tx = EscrowFinish(
+            account=self.wallet.address,
+            owner=self.wallet.address,
+            offer_sequence=escrow_sequence
+        )
+        
+        response = await submit_and_wait(finish_tx, self.client, self.wallet)
+        
+        if not response.is_successful():
+            raise Exception(f"Escrow finish failed: {response.result}")
+        
+        tx_hash = response.result['hash']
+        
+        # Update claim status
+        await self.db.update_claim_status(
+            claim_id=claim_id,
+            status='settled',
+            settlement_tx_hash=tx_hash
+        )
+        
+        logger.info(f"Escrow finished: {tx_hash}. Claim settled.")
+        
+        return tx_hash
+    
+    async def cancel_escrow(
+        self,
+        claim_id: str,
+        escrow_sequence: int,
+        reason: str
+    ) -> str:
+        """
+        Cancel escrow (for disputed/fraudulent claims).
+        
+        Args:
+            claim_id: Claim UUID
+            escrow_sequence: Escrow sequence number
+            reason: Cancellation reason
+        
+        Returns:
+            Transaction hash
+        """
+        logger.info(
+            f"Cancelling escrow for claim {claim_id} (seq: {escrow_sequence}). "
+            f"Reason: {reason}"
+        )
+        
+        # Verify escrow is cancellable
+        status = await self.get_escrow_status(escrow_sequence)
+        
+        if not status.can_cancel:
+            raise ValueError(
+                f"Escrow not cancellable yet. Available after: {status.cancel_after}"
+            )
+        
+        # Create EscrowCancel transaction
+        cancel_tx = EscrowCancel(
+            account=self.wallet.address,
+            owner=self.wallet.address,
+            offer_sequence=escrow_sequence
+        )
+        
+        response = await submit_and_wait(cancel_tx, self.client, self.wallet)
+        
+        if not response.is_successful():
+            raise Exception(f"Escrow cancel failed: {response.result}")
+        
+        tx_hash = response.result['hash']
+        
+        # Update claim status
+        await self.db.update_claim_status(
+            claim_id=claim_id,
+            status='rejected',
+            rejection_reason=f"Escrow cancelled: {reason}"
+        )
+        
+        logger.info(f"Escrow cancelled: {tx_hash}")
+        
+        return tx_hash
+    
+    async def get_escrow_status(
+        self,
+        escrow_sequence: int
+    ) -> EscrowStatus:
+        """
+        Get current status of an escrow.
+        
+        Args:
+            escrow_sequence: Escrow sequence number
+        
+        Returns:
+            EscrowStatus with current state
+        """
+        # Query escrow from ledger
+        account_objects = AccountObjects(
+            account=self.wallet.address,
+            type="escrow"
+        )
+        
+        response = await self.client.request(account_objects)
+        
+        if not response.is_successful():
+            raise Exception(f"Failed to query escrows: {response.result}")
+        
+        # Find our escrow
+        escrow_obj = None
+        for obj in response.result.get('account_objects', []):
+            if obj.get('Sequence') == escrow_sequence:
+                escrow_obj = obj
+                break
+        
+        if not escrow_obj:
+            # Escrow not found - either finished or cancelled
+            return EscrowStatus(
+                claim_id="unknown",
+                escrow_sequence=escrow_sequence,
+                amount=0,
+                destination="unknown",
+                finish_after=datetime.utcnow(),
+                cancel_after=datetime.utcnow(),
+                status="finished_or_cancelled",
+                can_finish=False,
+                can_cancel=False
+            )
+        
+        # Parse escrow details
+        amount = int(escrow_obj['Amount'])
+        destination = escrow_obj['Destination']
+        finish_after = ripple_time_to_datetime(escrow_obj['FinishAfter'])
+        cancel_after = ripple_time_to_datetime(escrow_obj['CancelAfter'])
+        
+        now = datetime.utcnow()
+        can_finish = now >= finish_after
+        can_cancel = now >= cancel_after
+        
+        if can_finish and not can_cancel:
+            status = "finishable"
+        elif can_cancel:
+            status = "cancellable"
+        else:
+            status = "pending"
+        
+        return EscrowStatus(
+            claim_id="unknown",  # Would need to look up from database
+            escrow_sequence=escrow_sequence,
+            amount=amount,
+            destination=destination,
+            finish_after=finish_after,
+            cancel_after=cancel_after,
+            status=status,
+            can_finish=can_finish,
+            can_cancel=can_cancel
+        )
+    
+    async def get_pending_escrows(self) -> List[EscrowStatus]:
+        """
+        Get all pending escrows for this wallet.
+        
+        Returns:
+            List of EscrowStatus objects
+        """
+        account_objects = AccountObjects(
+            account=self.wallet.address,
+            type="escrow"
+        )
+        
+        response = await self.client.request(account_objects)
+        
+        if not response.is_successful():
+            raise Exception(f"Failed to query escrows: {response.result}")
+        
+        escrows = []
+        for obj in response.result.get('account_objects', []):
+            sequence = obj.get('Sequence')
+            if sequence:
+                status = await self.get_escrow_status(sequence)
+                escrows.append(status)
+        
+        return escrows
+    
+    async def _store_escrow_sequence(
+        self,
+        claim_id: str,
+        escrow_sequence: int
+    ):
+        """Store escrow sequence number in claims table."""
+        async with self.db.pool.acquire() as conn:
+            await conn.execute(
+                """
+                UPDATE claims
+                SET escrow_sequence = $1
+                WHERE claim_id = $2
+                """,
+                escrow_sequence, claim_id
+            )

ward/models/__init__.py

@@ -0,0 +1,7 @@
+"""Ward Protocol data models."""
+
+from .loan import Loan
+from .loan_broker import LoanBroker
+from .vault import Vault
+
+__all__ = ['Loan', 'LoanBroker', 'Vault']