Merge branch 'main' into feature/reflexive-core

examples/contract_example.py

@@ -0,0 +1,401 @@
+"""
+FastMCP Contract Management Example
+
+This example demonstrates the inter-agent contract management system with:
+- Contract lifecycle management (draft, propose, sign, revoke)
+- Ed25519 cryptographic signatures for non-repudiation
+- HIPAA compliance support
+- SQLite persistence
+- HTTP API endpoints
+"""
+
+import asyncio
+import json
+from datetime import datetime, timedelta
+
+from fastmcp import FastMCP
+from fastmcp.contracts import ContractEngine, ContractState
+from fastmcp.contracts.contract import (
+    Clause, ContractCreateRequest, ContractProposeRequest,
+    ContractSignRequest, ContractRevokeRequest
+)
+from fastmcp.contracts.crypto import generate_key_pair, Ed25519Signer
+
+
+def create_contract_example():
+    """Create a FastMCP server with contract engine enabled."""
+
+    # Create server
+    server = FastMCP("Contract Management Server")
+
+    # Enable contract engine
+    contract_engine = server.enable_contract_engine()
+
+    # Add a simple tool that demonstrates contract operations
+    @server.tool
+    async def create_sample_contract(title: str, description: str) -> dict:
+        """Create a sample contract for demonstration."""
+
+        # Create sample clauses
+        clauses = [
+            Clause(
+                title="Data Protection",
+                content="All personal data must be protected according to HIPAA regulations.",
+                type="hipaa"
+            ),
+            Clause(
+                title="Access Control",
+                content="Only authorized personnel may access patient data.",
+                type="security"
+            ),
+            Clause(
+                title="Audit Trail",
+                content="All data access must be logged for audit purposes.",
+                type="compliance"
+            )
+        ]
+
+        # Create sample parties
+        parties = [
+            {
+                "id": "provider1",
+                "name": "Healthcare Provider Inc.",
+                "type": "provider",
+                "email": "provider@example.com",
+                "role": "data_controller"
+            },
+            {
+                "id": "patient1",
+                "name": "John Doe",
+                "type": "patient",
+                "email": "patient@example.com",
+                "role": "data_subject"
+            }
+        ]
+
+        # Create contract request
+        contract_request = ContractCreateRequest(
+            title=title,
+            description=description,
+            clauses=clauses,
+            parties=parties,
+            is_hipaa_compliant=True,
+            expires_at=datetime.utcnow() + timedelta(days=365),
+            metadata={
+                "created_by": "system",
+                "purpose": "data_sharing_agreement"
+            }
+        )
+
+        # Create contract
+        contract = await contract_engine.create_contract(contract_request, "system")
+
+        return {
+            "contract_id": str(contract.id),
+            "title": contract.title,
+            "state": contract.state.value,
+            "parties": [party["name"] for party in contract.get_parties()],
+            "clauses": [clause.title for clause in contract.get_clauses()],
+            "is_hipaa_compliant": contract.is_hipaa_compliant
+        }
+
+    return server
+
+
+async def demonstrate_contract_lifecycle():
+    """Demonstrate complete contract lifecycle."""
+
+    server = create_contract_example()
+    contract_engine = server.get_contract_engine()
+    assert contract_engine is not None  # Ensure contract engine is enabled
+
+    print("📋 FastMCP Contract Management Example")
+    print("=" * 50)
+
+    # 1. Create a contract
+    print("\n1️⃣ Creating Contract")
+    print("-" * 30)
+
+    clauses = [
+        Clause(
+            title="Data Sharing Agreement",
+            content="Healthcare provider may share patient data with authorized third parties.",
+            type="hipaa"
+        ),
+        Clause(
+            title="Consent Requirement",
+            content="Patient consent must be obtained before data sharing.",
+            type="consent"
+        )
+    ]
+
+    parties = [
+        {
+            "id": "provider1",
+            "name": "Metro Health System",
+            "type": "provider",
+            "email": "admin@metrohealth.com"
+        },
+        {
+            "id": "patient1",
+            "name": "Jane Smith",
+            "type": "patient",
+            "email": "jane.smith@email.com"
+        }
+    ]
+
+    contract_request = ContractCreateRequest(
+        title="HIPAA Data Sharing Agreement",
+        description="Agreement for sharing patient data between healthcare providers",
+        clauses=clauses,
+        parties=parties,
+        is_hipaa_compliant=True,
+        expires_at=datetime.utcnow() + timedelta(days=365)
+    )
+
+    contract = await contract_engine.create_contract(contract_request, "admin")
+    print(f"✅ Contract created: {contract.title}")
+    print(f"   ID: {contract.id}")
+    print(f"   State: {contract.state.value}")
+    print(f"   Parties: {len(contract.get_parties())}")
+    print(f"   HIPAA Compliant: {contract.is_hipaa_compliant}")
+
+    # 2. Propose the contract
+    print("\n2️⃣ Proposing Contract")
+    print("-" * 30)
+
+    proposal_request = ContractProposeRequest(
+        proposed_to=["provider1", "patient1"],
+        message="Please review and sign this data sharing agreement."
+    )
+
+    contract = await contract_engine.propose_contract(contract.id, proposal_request, "admin")
+    print(f"✅ Contract proposed to: {proposal_request.proposed_to}")
+    print(f"   State: {contract.state.value}")
+    print(f"   Proposed at: {contract.proposed_at}")
+
+    # 3. Sign the contract (Provider)
+    print("\n3️⃣ Signing Contract (Provider)")
+    print("-" * 30)
+
+    # Generate key pair for provider
+    provider_public_key, provider_private_key = generate_key_pair()
+    provider_signer = Ed25519Signer.from_private_key_b64(provider_private_key)
+
+    # Create signing message
+    signing_message = f"{contract.id}:{contract.get_content_hash()}:provider1:provider"
+    provider_signature = provider_signer.sign(signing_message)
+
+    sign_request = ContractSignRequest(
+        signer_id="provider1",
+        signer_type="provider",
+        public_key=provider_public_key,
+        signature=provider_signature
+    )
+
+    contract = await contract_engine.sign_contract(contract.id, sign_request)
+    print(f"✅ Provider signed the contract")
+    print(f"   Signatures: {len(contract.get_signatures())}")
+    print(f"   State: {contract.state.value}")
+
+    # 4. Sign the contract (Patient)
+    print("\n4️⃣ Signing Contract (Patient)")
+    print("-" * 30)
+
+    # Generate key pair for patient
+    patient_public_key, patient_private_key = generate_key_pair()
+    patient_signer = Ed25519Signer.from_private_key_b64(patient_private_key)
+
+    # Create signing message
+    signing_message = f"{contract.id}:{contract.get_content_hash()}:patient1:patient"
+    patient_signature = patient_signer.sign(signing_message)
+
+    sign_request = ContractSignRequest(
+        signer_id="patient1",
+        signer_type="patient",
+        public_key=patient_public_key,
+        signature=patient_signature
+    )
+
+    contract = await contract_engine.sign_contract(contract.id, sign_request)
+    print(f"✅ Patient signed the contract")
+    print(f"   Signatures: {len(contract.get_signatures())}")
+    print(f"   State: {contract.state.value}")
+    print(f"   Fully signed: {contract.is_fully_signed()}")
+
+    # 5. Demonstrate contract verification
+    print("\n5️⃣ Contract Verification")
+    print("-" * 30)
+
+    signatures = contract.get_signatures()
+    for signature in signatures:
+        # Verify signature
+        signing_message = f"{contract.id}:{contract.get_content_hash()}:{signature.signer_id}:{signature.signer_type}"
+        is_valid = provider_signer.verify(signing_message, signature.signature)
+        print(f"   {signature.signer_id} signature: {'✅ Valid' if is_valid else '❌ Invalid'}")
+
+    # 6. Get contract statistics
+    print("\n6️⃣ Contract Statistics")
+    print("-" * 30)
+
+    stats = await contract_engine.get_contract_statistics()
+    print(f"   Total contracts: {stats['total_contracts']}")
+    print(f"   By state: {stats['by_state']}")
+    print(f"   HIPAA compliant: {stats['hipaa_compliant']}")
+    print(f"   Signed contracts: {stats['signed_contracts']}")
+
+    # 7. Demonstrate revocation (optional)
+    print("\n7️⃣ Contract Revocation (Optional)")
+    print("-" * 30)
+
+    revoke_request = ContractRevokeRequest(
+        reason="Patient requested data deletion",
+        revoked_by="admin"
+    )
+
+    contract = await contract_engine.revoke_contract(contract.id, revoke_request)
+    print(f"✅ Contract revoked")
+    print(f"   State: {contract.state.value}")
+    print(f"   Revoked at: {contract.revoked_at}")
+    print(f"   Reason: {revoke_request.reason}")
+
+
+async def demonstrate_hipaa_compliance():
+    """Demonstrate HIPAA compliance features."""
+
+    print("\n🏥 HIPAA Compliance Demonstration")
+    print("=" * 50)
+
+    server = create_contract_example()
+    contract_engine = server.get_contract_engine()
+    assert contract_engine is not None
+
+    # Create HIPAA-compliant contract
+    hipaa_clauses = [
+        Clause(
+            title="HIPAA Privacy Rule",
+            content="All patient data must be handled according to HIPAA Privacy Rule requirements.",
+            type="hipaa",
+            metadata={"regulation": "45 CFR 164.502"}
+        ),
+        Clause(
+            title="Minimum Necessary Standard",
+            content="Only the minimum necessary information may be disclosed.",
+            type="hipaa",
+            metadata={"regulation": "45 CFR 164.502(b)"}
+        ),
+        Clause(
+            title="Business Associate Agreement",
+            content="Third parties must sign a Business Associate Agreement.",
+            type="hipaa",
+            metadata={"regulation": "45 CFR 164.502(e)"}
+        )
+    ]
+
+    hipaa_parties = [
+        {
+            "id": "covered_entity",
+            "name": "Regional Medical Center",
+            "type": "covered_entity",
+            "email": "privacy@regionalmedical.com",
+            "hipaa_role": "covered_entity"
+        },
+        {
+            "id": "business_associate",
+            "name": "HealthTech Solutions",
+            "type": "business_associate",
+            "email": "compliance@healthtech.com",
+            "hipaa_role": "business_associate"
+        }
+    ]
+
+    contract_request = ContractCreateRequest(
+        title="HIPAA Business Associate Agreement",
+        description="Agreement for HIPAA-compliant data processing services",
+        clauses=hipaa_clauses,
+        parties=hipaa_parties,
+        is_hipaa_compliant=True,
+        hipaa_entities=[
+            {
+                "type": "covered_entity",
+                "name": "Regional Medical Center",
+                "hipaa_id": "CE-001"
+            },
+            {
+                "type": "business_associate",
+                "name": "HealthTech Solutions",
+                "hipaa_id": "BA-001"
+            }
+        ],
+        metadata={
+            "hipaa_version": "2023",
+            "compliance_level": "full",
+            "audit_required": True
+        }
+    )
+
+    contract = await contract_engine.create_contract(contract_request, "hipaa_admin")
+    
+    print(f"✅ HIPAA-compliant contract created")
+    print(f"   Title: {contract.title}")
+    print(f"   HIPAA Compliant: {contract.is_hipaa_compliant}")
+    print(f"   HIPAA Entities: {len(contract.get_hipaa_entities())}")
+    print(f"   Clauses: {len(contract.get_clauses())}")
+
+    # Show HIPAA-specific metadata
+    metadata = contract.get_metadata()
+    print(f"   Compliance Level: {metadata.get('compliance_level')}")
+    print(f"   Audit Required: {metadata.get('audit_required')}")
+
+
+def main():
+    """Run the contract management example."""
+
+    async def run_example():
+        # Demonstrate contract lifecycle
+        await demonstrate_contract_lifecycle()
+
+        # Demonstrate HIPAA compliance
+        await demonstrate_hipaa_compliance()
+
+        print("\n🚀 Contract Management Example Complete!")
+        print("\nTo test the HTTP endpoints:")
+        print("1. Run: fastmcp run examples/contract_example.py --transport http")
+        print("2. Available endpoints:")
+        print("   - POST /contracts - Create contract")
+        print("   - GET /contracts - List contracts")
+        print("   - GET /contracts/{id} - Get contract")
+        print("   - POST /contracts/{id}/propose - Propose contract")
+        print("   - POST /contracts/{id}/sign - Sign contract")
+        print("   - POST /contracts/{id}/revoke - Revoke contract")
+        print("   - GET /contracts/statistics - Get statistics")
+        print("\n3. Example contract creation:")
+        print("""
+curl -X POST http://localhost:8000/contracts \\
+  -H "Content-Type: application/json" \\
+  -d '{
+    "title": "Test Contract",
+    "description": "A test contract",
+    "clauses": [
+      {
+        "title": "Test Clause",
+        "content": "This is a test clause",
+        "type": "test"
+      }
+    ],
+    "parties": [
+      {
+        "id": "party1",
+        "name": "Test Party",
+        "type": "provider"
+      }
+    ],
+    "is_hipaa_compliant": false
+  }'
+        """)
+
+    asyncio.run(run_example())
+
+
+if __name__ == "__main__":
+    main()

examples/ledger_example.py

@@ -0,0 +1,208 @@
+"""Example demonstrating the FastMCP Provenance Ledger functionality."""
+
+import asyncio
+from datetime import datetime
+from fastmcp import FastMCP
+from fastmcp.ledger import ProvenanceLedger, LedgerEvent, EventType
+
+
+def create_ledger_server():
+    """Create a FastMCP server with ledger functionality."""
+    server = FastMCP("LedgerExampleServer")
+    
+    # Enable the provenance ledger
+    ledger = server.enable_ledger(database_url="sqlite:///example_ledger.db")
+    
+    @server.tool
+    def log_tool_call(tool_name: str, parameters: dict, result: str) -> str:
+        """Log a tool call to the provenance ledger."""
+        # Create a ledger event
+        event = LedgerEvent(
+            event_type=EventType.TOOL_CALL,
+            actor_id="system",
+            resource_id=f"tool://{tool_name}",
+            action="execute",
+            metadata={
+                "tool_name": tool_name,
+                "parameters": parameters,
+                "result": result,
+                "timestamp": datetime.utcnow().isoformat()
+            }
+        )
+        
+        # Append to ledger
+        entry = ledger.append_event(event)
+        
+        return f"Logged tool call {tool_name} as entry {entry.sequence_number}"
+    
+    @server.tool
+    def log_policy_decision(policy_name: str, decision: str, context: dict) -> str:
+        """Log a policy decision to the provenance ledger."""
+        event = LedgerEvent(
+            event_type=EventType.POLICY_DECISION,
+            actor_id="policy_engine",
+            resource_id=f"policy://{policy_name}",
+            action="evaluate",
+            metadata={
+                "policy_name": policy_name,
+                "decision": decision,
+                "context": context,
+                "timestamp": datetime.utcnow().isoformat()
+            }
+        )
+        
+        entry = ledger.append_event(event)
+        return f"Logged policy decision {policy_name} as entry {entry.sequence_number}"
+    
+    @server.tool
+    def log_data_flow(source: str, destination: str, data_type: str, size: int) -> str:
+        """Log a data flow event to the provenance ledger."""
+        event = LedgerEvent(
+            event_type=EventType.DATA_FLOW,
+            actor_id="data_processor",
+            resource_id=f"data://{source}",
+            action="transfer",
+            metadata={
+                "source": source,
+                "destination": destination,
+                "data_type": data_type,
+                "size_bytes": size,
+                "timestamp": datetime.utcnow().isoformat()
+            }
+        )
+        
+        entry = ledger.append_event(event)
+        return f"Logged data flow from {source} to {destination} as entry {entry.sequence_number}"
+    
+    @server.tool
+    def verify_ledger_integrity() -> dict:
+        """Verify the integrity of the entire ledger."""
+        # Verify chain integrity
+        chain_valid = ledger.verify_chain_integrity()
+        
+        # Get statistics
+        stats = ledger.get_ledger_statistics()
+        
+        return {
+            "chain_integrity": chain_valid,
+            "statistics": stats,
+            "verification_timestamp": datetime.utcnow().isoformat()
+        }
+    
+    @server.tool
+    def get_ledger_entry(sequence_number: int) -> dict:
+        """Get a specific ledger entry."""
+        entry = ledger.get_entry(sequence_number)
+        
+        if not entry:
+            return {"error": f"Entry {sequence_number} not found"}
+        
+        event = entry.get_event()
+        
+        return {
+            "sequence_number": entry.sequence_number,
+            "entry_hash": entry.entry_hash,
+            "previous_hash": entry.previous_hash,
+            "created_at": entry.created_at.isoformat(),
+            "event": {
+                "type": event.event_type,
+                "actor_id": event.actor_id,
+                "action": event.action,
+                "metadata": event.metadata
+            }
+        }
+    
+    return server, ledger
+
+
+async def demonstrate_ledger_functionality():
+    """Demonstrate the ledger functionality."""
+    print("🚀 Creating FastMCP server with Provenance Ledger...")
+    server, ledger = create_ledger_server()
+    
+    print("\n📝 Logging various events to the ledger...")
+    
+    # Log some tool calls
+    print(server._tool_manager.call_tool("log_tool_call", {
+        "tool_name": "file_reader",
+        "parameters": {"path": "/data/file.txt"},
+        "result": "success"
+    }))
+    
+    print(server._tool_manager.call_tool("log_tool_call", {
+        "tool_name": "data_processor",
+        "parameters": {"input": "raw_data", "format": "json"},
+        "result": "processed_data"
+    }))
+    
+    # Log policy decisions
+    print(server._tool_manager.call_tool("log_policy_decision", {
+        "policy_name": "access_control",
+        "decision": "allow",
+        "context": {"user": "alice", "resource": "sensitive_data"}
+    }))
+    
+    print(server._tool_manager.call_tool("log_policy_decision", {
+        "policy_name": "data_retention",
+        "decision": "delete",
+        "context": {"age_days": 365, "type": "logs"}
+    }))
+    
+    # Log data flows
+    print(server._tool_manager.call_tool("log_data_flow", {
+        "source": "database",
+        "destination": "cache",
+        "data_type": "user_profiles",
+        "size": 1024
+    }))
+    
+    print(server._tool_manager.call_tool("log_data_flow", {
+        "source": "api",
+        "destination": "analytics",
+        "data_type": "usage_metrics",
+        "size": 512
+    }))
+    
+    print("\n🔍 Verifying ledger integrity...")
+    integrity_result = server._tool_manager.call_tool("verify_ledger_integrity", {})
+    print(f"Chain integrity: {integrity_result['chain_integrity']}")
+    print(f"Total entries: {integrity_result['statistics']['total_entries']}")
+    print(f"Total blocks: {integrity_result['statistics']['total_blocks']}")
+    
+    print("\n📋 Retrieving specific entries...")
+    for i in range(1, 4):
+        entry = server._tool_manager.call_tool("get_ledger_entry", {"sequence_number": i})
+        if "error" not in entry:
+            print(f"Entry {i}: {entry['event']['type']} - {entry['event']['action']}")
+    
+    print("\n🔗 Demonstrating hash chaining...")
+    entry1 = ledger.get_entry(1)
+    entry2 = ledger.get_entry(2)
+    
+    if entry1 and entry2:
+        print(f"Entry 1 hash: {entry1.entry_hash[:16]}...")
+        print(f"Entry 2 previous hash: {entry2.previous_hash[:16]}...")
+        print(f"Hash chain intact: {entry2.previous_hash == entry1.entry_hash}")
+    
+    print("\n🌳 Demonstrating Merkle tree verification...")
+    # Get the first block
+    block = ledger.get_block(1)
+    if block:
+        print(f"Block 1 Merkle root: {block.merkle_root[:16]}...")
+        print(f"Block 1 entry count: {block.entry_count}")
+        
+        # Verify block integrity
+        block_valid = ledger.verify_block_integrity(1)
+        print(f"Block 1 integrity: {block_valid}")
+    
+    print("\n✅ Ledger demonstration complete!")
+    print("\nThe ledger provides:")
+    print("- Tamper-evident hash chaining between entries")
+    print("- Merkle tree verification for blocks")
+    print("- Cryptographic integrity guarantees")
+    print("- Audit trail for all system events")
+    print("- HTTP API endpoints for external access")
+
+
+if __name__ == "__main__":
+    asyncio.run(demonstrate_ledger_functionality())

src/fastmcp/contracts/__init__.py

@@ -0,0 +1,7 @@
+"""FastMCP Contract Management - Inter-agent contract lifecycle with cryptographic guarantees."""
+
+from .contract import Contract, Clause, Signature, ContractState
+from .engine import ContractEngine
+from .registry import ContractRegistry
+
+__all__ = ["Contract", "Clause", "Signature", "ContractState", "ContractEngine", "ContractRegistry"]

src/fastmcp/contracts/contract.py

@@ -0,0 +1,306 @@
+"""Contract models and schemas for inter-agent contract management."""
+
+import hashlib
+import json
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, List, Optional
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field, validator
+from sqlmodel import SQLModel, Field as SQLField, Relationship
+
+
+class ContractState(str, Enum):
+    """Contract lifecycle states."""
+    DRAFT = "draft"
+    PROPOSED = "proposed"
+    SIGNED = "signed"
+    REVOKED = "revoked"
+    EXPIRED = "expired"
+
+
+class Clause(BaseModel):
+    """A contract clause with structured content."""
+    
+    id: str = Field(default_factory=lambda: str(uuid4()))
+    title: str = Field(..., description="Clause title")
+    content: str = Field(..., description="Clause content")
+    type: str = Field(default="general", description="Clause type (e.g., 'hipaa', 'data_handling')")
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Additional clause metadata")
+    
+    class Config:
+        json_encoders = {
+            datetime: lambda v: v.isoformat()
+        }
+
+
+class Signature(BaseModel):
+    """Cryptographic signature for contract verification."""
+    
+    signer_id: str = Field(..., description="ID of the signing party")
+    signer_type: str = Field(..., description="Type of signer (e.g., 'provider', 'payor', 'patient')")
+    signature: str = Field(..., description="Base64-encoded Ed25519 signature")
+    public_key: str = Field(..., description="Base64-encoded public key")
+    timestamp: datetime = Field(default_factory=datetime.utcnow)
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+    
+    class Config:
+        json_encoders = {
+            datetime: lambda v: v.isoformat()
+        }
+    
+    def model_dump(self, **kwargs):
+        """Override model_dump to handle datetime serialization."""
+        data = super().model_dump(**kwargs)
+        # Convert datetime objects to ISO format strings
+        for key, value in data.items():
+            if isinstance(value, datetime):
+                data[key] = value.isoformat()
+        return data
+
+
+class Contract(SQLModel, table=True):
+    """Contract model with SQLModel persistence."""
+    
+    __tablename__ = "contracts"
+    
+    # Primary fields
+    id: UUID = SQLField(default_factory=uuid4, primary_key=True)
+    title: str = SQLField(..., description="Contract title")
+    description: str = SQLField(..., description="Contract description")
+    
+    # Contract content
+    clauses: str = SQLField(..., description="JSON-encoded clauses")
+    parties: str = SQLField(..., description="JSON-encoded parties")
+    
+    # Lifecycle
+    state: ContractState = SQLField(default=ContractState.DRAFT)
+    created_at: datetime = SQLField(default_factory=datetime.utcnow)
+    proposed_at: Optional[datetime] = SQLField(default=None)
+    signed_at: Optional[datetime] = SQLField(default=None)
+    revoked_at: Optional[datetime] = SQLField(default=None)
+    expires_at: Optional[datetime] = SQLField(default=None)
+    
+    # Signatures
+    signatures: str = SQLField(default="[]", description="JSON-encoded signatures")
+    
+    # HIPAA compliance
+    is_hipaa_compliant: bool = SQLField(default=False)
+    hipaa_entities: str = SQLField(default="[]", description="JSON-encoded HIPAA entities")
+    
+    # Metadata
+    contract_metadata: str = SQLField(default="{}", description="JSON-encoded metadata")
+    version: str = SQLField(default="1.0.0")
+    
+    # Audit trail
+    created_by: str = SQLField(..., description="ID of the creating party")
+    last_modified: datetime = SQLField(default_factory=datetime.utcnow)
+    
+    def get_clauses(self) -> List[Clause]:
+        """Get parsed clauses from JSON."""
+        try:
+            clauses_data = json.loads(self.clauses)
+            return [Clause(**clause) for clause in clauses_data]
+        except (json.JSONDecodeError, ValueError):
+            return []
+    
+    def set_clauses(self, clauses: List[Clause]) -> None:
+        """Set clauses as JSON."""
+        self.clauses = json.dumps([clause.model_dump() for clause in clauses])
+    
+    def get_parties(self) -> List[Dict[str, Any]]:
+        """Get parsed parties from JSON."""
+        try:
+            return json.loads(self.parties)
+        except json.JSONDecodeError:
+            return []
+    
+    def set_parties(self, parties: List[Dict[str, Any]]) -> None:
+        """Set parties as JSON."""
+        self.parties = json.dumps(parties)
+    
+    def get_signatures(self) -> List[Signature]:
+        """Get parsed signatures from JSON."""
+        try:
+            signatures_data = json.loads(self.signatures)
+            return [Signature(**sig) for sig in signatures_data]
+        except (json.JSONDecodeError, ValueError):
+            return []
+    
+    def set_signatures(self, signatures: List[Signature]) -> None:
+        """Set signatures as JSON."""
+        self.signatures = json.dumps([sig.model_dump() for sig in signatures])
+    
+    def get_hipaa_entities(self) -> List[Dict[str, Any]]:
+        """Get parsed HIPAA entities from JSON."""
+        try:
+            return json.loads(self.hipaa_entities)
+        except json.JSONDecodeError:
+            return []
+    
+    def set_hipaa_entities(self, entities: List[Dict[str, Any]]) -> None:
+        """Set HIPAA entities as JSON."""
+        self.hipaa_entities = json.dumps(entities)
+    
+    def get_metadata(self) -> Dict[str, Any]:
+        """Get parsed metadata from JSON."""
+        try:
+            return json.loads(self.contract_metadata)
+        except json.JSONDecodeError:
+            return {}
+    
+    def set_metadata(self, metadata: Dict[str, Any]) -> None:
+        """Set metadata as JSON."""
+        self.contract_metadata = json.dumps(metadata)
+    
+    def get_content_hash(self) -> str:
+        """Get SHA-256 hash of contract content for signing."""
+        content = {
+            "id": str(self.id),
+            "title": self.title,
+            "description": self.description,
+            "clauses": self.clauses,
+            "parties": self.parties,
+            "version": self.version
+        }
+        content_str = json.dumps(content, sort_keys=True)
+        return hashlib.sha256(content_str.encode()).hexdigest()
+    
+    def can_transition_to(self, new_state: ContractState) -> bool:
+        """Check if contract can transition to new state."""
+        valid_transitions = {
+            ContractState.DRAFT: [ContractState.PROPOSED, ContractState.REVOKED],
+            ContractState.PROPOSED: [ContractState.SIGNED, ContractState.REVOKED, ContractState.DRAFT],
+            ContractState.SIGNED: [ContractState.REVOKED],
+            ContractState.REVOKED: [],  # Terminal state
+            ContractState.EXPIRED: []   # Terminal state
+        }
+        return new_state in valid_transitions.get(self.state, [])
+    
+    def is_fully_signed(self) -> bool:
+        """Check if contract is fully signed by all required parties."""
+        parties = self.get_parties()
+        signatures = self.get_signatures()
+        
+        # Check if all parties have signed
+        signed_party_ids = {sig.signer_id for sig in signatures}
+        required_party_ids = {party["id"] for party in parties}
+        
+        return required_party_ids.issubset(signed_party_ids)
+    
+    def get_unsigned_parties(self) -> List[Dict[str, Any]]:
+        """Get parties that haven't signed yet."""
+        parties = self.get_parties()
+        signatures = self.get_signatures()
+        signed_party_ids = {sig.signer_id for sig in signatures}
+        
+        return [party for party in parties if party["id"] not in signed_party_ids]
+
+
+class ContractCreateRequest(BaseModel):
+    """Request model for creating a contract."""
+    
+    title: str = Field(..., description="Contract title")
+    description: str = Field(..., description="Contract description")
+    clauses: List[Clause] = Field(..., description="Contract clauses")
+    parties: List[Dict[str, Any]] = Field(..., description="Contract parties")
+    is_hipaa_compliant: bool = Field(default=False, description="HIPAA compliance flag")
+    hipaa_entities: Optional[List[Dict[str, Any]]] = Field(default=None, description="HIPAA entities")
+    expires_at: Optional[datetime] = Field(default=None, description="Contract expiration")
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
+    version: str = Field(default="1.0.0", description="Contract version")
+
+
+class ContractProposeRequest(BaseModel):
+    """Request model for proposing a contract."""
+    
+    proposed_to: List[str] = Field(..., description="IDs of parties to propose to")
+    message: Optional[str] = Field(default=None, description="Proposal message")
+
+
+class ContractSignRequest(BaseModel):
+    """Request model for signing a contract."""
+    
+    signer_id: str = Field(..., description="ID of the signing party")
+    signer_type: str = Field(..., description="Type of signer")
+    public_key: str = Field(..., description="Base64-encoded public key")
+    signature: str = Field(..., description="Base64-encoded Ed25519 signature")
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Signature metadata")
+
+
+class ContractRevokeRequest(BaseModel):
+    """Request model for revoking a contract."""
+    
+    reason: str = Field(..., description="Reason for revocation")
+    revoked_by: str = Field(..., description="ID of the revoking party")
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Revocation metadata")
+
+
+class ContractResponse(BaseModel):
+    """Response model for contract operations."""
+    
+    id: str
+    title: str
+    description: str
+    clauses: List[Clause]
+    parties: List[Dict[str, Any]]
+    state: ContractState
+    created_at: datetime
+    proposed_at: Optional[datetime]
+    signed_at: Optional[datetime]
+    revoked_at: Optional[datetime]
+    expires_at: Optional[datetime]
+    signatures: List[Dict[str, Any]]
+    is_hipaa_compliant: bool
+    hipaa_entities: List[Dict[str, Any]]
+    contract_metadata: Dict[str, Any]
+    version: str
+    created_by: str
+    last_modified: datetime
+    content_hash: str
+    is_fully_signed: bool
+    unsigned_parties: List[Dict[str, Any]]
+    
+    def model_dump(self, **kwargs):
+        """Override model_dump to handle datetime serialization."""
+        data = super().model_dump(**kwargs)
+        # Convert datetime objects to ISO format strings
+        for key, value in data.items():
+            if isinstance(value, datetime):
+                data[key] = value.isoformat()
+            elif key == "signatures" and isinstance(value, list):
+                # Handle nested Signature objects
+                data[key] = [sig.model_dump() if hasattr(sig, 'model_dump') else sig for sig in value]
+        return data
+    
+    @classmethod
+    def from_contract(cls, contract: Contract) -> "ContractResponse":
+        """Create response from contract model."""
+        # Pre-serialize signatures to handle datetime fields
+        signatures = contract.get_signatures()
+        serialized_signatures = [sig.model_dump() for sig in signatures]
+        
+        return cls(
+            id=str(contract.id),  # Convert UUID to string
+            title=contract.title,
+            description=contract.description,
+            clauses=contract.get_clauses(),
+            parties=contract.get_parties(),
+            state=contract.state,
+            created_at=contract.created_at,
+            proposed_at=contract.proposed_at,
+            signed_at=contract.signed_at,
+            revoked_at=contract.revoked_at,
+            expires_at=contract.expires_at,
+            signatures=serialized_signatures,  # Use pre-serialized signatures
+            is_hipaa_compliant=contract.is_hipaa_compliant,
+            hipaa_entities=contract.get_hipaa_entities(),
+            contract_metadata=contract.get_metadata(),
+            version=contract.version,
+            created_by=contract.created_by,
+            last_modified=contract.last_modified,
+            content_hash=contract.get_content_hash(),
+            is_fully_signed=contract.is_fully_signed(),
+            unsigned_parties=contract.get_unsigned_parties()
+        )

src/fastmcp/contracts/crypto.py

@@ -0,0 +1,230 @@
+"""Cryptographic utilities for contract signing and verification."""
+
+import base64
+from typing import Tuple
+
+import nacl.encoding
+import nacl.signing
+from nacl.exceptions import BadSignatureError
+
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class CryptoError(Exception):
+    """Cryptographic operation error."""
+    pass
+
+
+class Ed25519Signer:
+    """Ed25519 signature operations for contract signing."""
+    
+    def __init__(self, private_key: bytes = None):
+        """Initialize signer with optional private key.
+        
+        Args:
+            private_key: Optional private key bytes. If None, generates new key pair.
+        """
+        if private_key is None:
+            self._signing_key = nacl.signing.SigningKey.generate()
+        else:
+            self._signing_key = nacl.signing.SigningKey(private_key)
+        
+        self._verify_key = self._signing_key.verify_key
+    
+    @classmethod
+    def from_private_key_b64(cls, private_key_b64: str) -> "Ed25519Signer":
+        """Create signer from base64-encoded private key.
+        
+        Args:
+            private_key_b64: Base64-encoded private key
+            
+        Returns:
+            Ed25519Signer instance
+        """
+        try:
+            private_key = base64.b64decode(private_key_b64)
+            return cls(private_key)
+        except Exception as e:
+            raise CryptoError(f"Invalid private key format: {e}")
+    
+    @classmethod
+    def from_public_key_b64(cls, public_key_b64: str) -> "Ed25519Signer":
+        """Create signer from base64-encoded public key (verification only).
+        
+        Args:
+            public_key_b64: Base64-encoded public key
+            
+        Returns:
+            Ed25519Signer instance (verification only)
+        """
+        try:
+            public_key = base64.b64decode(public_key_b64)
+            verify_key = nacl.signing.VerifyKey(public_key)
+            signer = cls.__new__(cls)
+            signer._signing_key = None  # No private key for verification only
+            signer._verify_key = verify_key
+            return signer
+        except Exception as e:
+            raise CryptoError(f"Invalid public key format: {e}")
+    
+    def sign(self, message: str) -> str:
+        """Sign a message.
+        
+        Args:
+            message: Message to sign
+            
+        Returns:
+            Base64-encoded signature
+            
+        Raises:
+            CryptoError: If signing fails
+        """
+        if self._signing_key is None:
+            raise CryptoError("Cannot sign: no private key available")
+        
+        try:
+            message_bytes = message.encode('utf-8')
+            signed = self._signing_key.sign(message_bytes)
+            signature = signed.signature
+            return base64.b64encode(signature).decode('ascii')
+        except Exception as e:
+            raise CryptoError(f"Signing failed: {e}")
+    
+    def verify(self, message: str, signature: str) -> bool:
+        """Verify a signature.
+        
+        Args:
+            message: Original message
+            signature: Base64-encoded signature to verify
+            
+        Returns:
+            True if signature is valid, False otherwise
+        """
+        try:
+            message_bytes = message.encode('utf-8')
+            signature_bytes = base64.b64decode(signature)
+            self._verify_key.verify(message_bytes, signature_bytes)
+            return True
+        except (BadSignatureError, Exception) as e:
+            logger.debug(f"Signature verification failed: {e}")
+            return False
+    
+    def get_public_key_b64(self) -> str:
+        """Get base64-encoded public key.
+        
+        Returns:
+            Base64-encoded public key
+        """
+        return base64.b64encode(self._verify_key.encode()).decode('ascii')
+    
+    def get_private_key_b64(self) -> str:
+        """Get base64-encoded private key.
+        
+        Returns:
+            Base64-encoded private key
+            
+        Raises:
+            CryptoError: If no private key available
+        """
+        if self._signing_key is None:
+            raise CryptoError("No private key available")
+        
+        return base64.b64encode(self._signing_key.encode()).decode('ascii')
+    
+    def get_key_pair_b64(self) -> Tuple[str, str]:
+        """Get both public and private keys as base64 strings.
+        
+        Returns:
+            Tuple of (public_key_b64, private_key_b64)
+            
+        Raises:
+            CryptoError: If no private key available
+        """
+        return self.get_public_key_b64(), self.get_private_key_b64()
+
+
+class ContractSigner:
+    """High-level contract signing operations."""
+    
+    def __init__(self, signer: Ed25519Signer):
+        """Initialize with Ed25519 signer.
+        
+        Args:
+            signer: Ed25519Signer instance
+        """
+        self._signer = signer
+    
+    def sign_contract(self, contract_id: str, content_hash: str, signer_id: str, signer_type: str) -> str:
+        """Sign a contract.
+        
+        Args:
+            contract_id: Contract ID
+            content_hash: SHA-256 hash of contract content
+            signer_id: ID of the signing party
+            signer_type: Type of signer (e.g., 'provider', 'payor', 'patient')
+            
+        Returns:
+            Base64-encoded signature
+            
+        Raises:
+            CryptoError: If signing fails
+        """
+        # Create signing message
+        signing_message = f"{contract_id}:{content_hash}:{signer_id}:{signer_type}"
+        return self._signer.sign(signing_message)
+    
+    def verify_contract_signature(self, contract_id: str, content_hash: str, signer_id: str, 
+                                signer_type: str, signature: str) -> bool:
+        """Verify a contract signature.
+        
+        Args:
+            contract_id: Contract ID
+            content_hash: SHA-256 hash of contract content
+            signer_id: ID of the signing party
+            signer_type: Type of signer
+            signature: Base64-encoded signature to verify
+            
+        Returns:
+            True if signature is valid, False otherwise
+        """
+        # Create signing message
+        signing_message = f"{contract_id}:{content_hash}:{signer_id}:{signer_type}"
+        return self._signer.verify(signing_message, signature)
+    
+    def get_public_key_b64(self) -> str:
+        """Get base64-encoded public key."""
+        return self._signer.get_public_key_b64()
+    
+    def get_private_key_b64(self) -> str:
+        """Get base64-encoded private key."""
+        return self._signer.get_private_key_b64()
+
+
+def generate_key_pair() -> Tuple[str, str]:
+    """Generate a new Ed25519 key pair.
+    
+    Returns:
+        Tuple of (public_key_b64, private_key_b64)
+    """
+    signer = Ed25519Signer()
+    return signer.get_key_pair_b64()
+
+
+def verify_signature(public_key_b64: str, message: str, signature: str) -> bool:
+    """Verify a signature with a public key.
+    
+    Args:
+        public_key_b64: Base64-encoded public key
+        message: Original message
+        signature: Base64-encoded signature
+        
+    Returns:
+        True if signature is valid, False otherwise
+    """
+    try:
+        signer = Ed25519Signer.from_public_key_b64(public_key_b64)
+        return signer.verify(message, signature)
+    except CryptoError:
+        return False

src/fastmcp/contracts/engine.py

@@ -0,0 +1,357 @@
+"""Contract engine for managing contract lifecycle and operations."""
+
+from datetime import datetime
+from typing import List, Optional
+from uuid import UUID
+
+from sqlmodel import Session, create_engine
+
+from fastmcp.utilities.logging import get_logger
+
+from .contract import Contract, ContractState, ContractCreateRequest, ContractProposeRequest, ContractSignRequest, ContractRevokeRequest
+from .crypto import ContractSigner, CryptoError
+from .registry import ContractRegistry
+
+logger = get_logger(__name__)
+
+
+class ContractEngine:
+    """Engine for managing contract lifecycle and operations."""
+    
+    def __init__(self, database_url: str = "sqlite:///contracts.db"):
+        """Initialize contract engine with database connection.
+        
+        Args:
+            database_url: Database connection URL
+        """
+        self.engine = create_engine(database_url, echo=False)
+        self._create_tables()
+    
+    def _create_tables(self):
+        """Create database tables."""
+        try:
+            Contract.metadata.create_all(self.engine)
+            logger.info("Contract database tables created/verified")
+        except Exception as e:
+            logger.error(f"Failed to create contract tables: {e}")
+            raise
+    
+    def get_session(self) -> Session:
+        """Get database session.
+        
+        Returns:
+            SQLModel database session
+        """
+        return Session(self.engine)
+    
+    def get_registry(self) -> ContractRegistry:
+        """Get contract registry.
+        
+        Returns:
+            Contract registry instance
+        """
+        return ContractRegistry(self.get_session())
+    
+    async def create_contract(self, request: ContractCreateRequest, created_by: str) -> Contract:
+        """Create a new contract.
+        
+        Args:
+            request: Contract creation request
+            created_by: ID of the creating party
+            
+        Returns:
+            Created contract instance
+            
+        Raises:
+            ValueError: If contract creation fails
+        """
+        try:
+            registry = self.get_registry()
+            
+            # Convert request to contract data
+            contract_data = {
+                "title": request.title,
+                "description": request.description,
+                "clauses": [clause.model_dump() for clause in request.clauses],
+                "parties": request.parties,
+                "is_hipaa_compliant": request.is_hipaa_compliant,
+                "hipaa_entities": request.hipaa_entities or [],
+                "expires_at": request.expires_at,
+                "metadata": request.metadata,
+                "version": request.version
+            }
+            
+            contract = registry.create_contract(contract_data, created_by)
+            logger.info(f"Created contract {contract.id} by {created_by}")
+            return contract
+            
+        except Exception as e:
+            logger.error(f"Failed to create contract: {e}")
+            raise
+    
+    async def get_contract(self, contract_id: UUID) -> Optional[Contract]:
+        """Get a contract by ID.
+        
+        Args:
+            contract_id: Contract UUID
+            
+        Returns:
+            Contract instance or None if not found
+        """
+        try:
+            registry = self.get_registry()
+            return registry.get_contract(contract_id)
+        except Exception as e:
+            logger.error(f"Failed to get contract {contract_id}: {e}")
+            return None
+    
+    async def list_contracts(self, state: Optional[ContractState] = None, 
+                           created_by: Optional[str] = None) -> List[Contract]:
+        """List contracts with optional filtering.
+        
+        Args:
+            state: Optional state filter
+            created_by: Optional creator filter
+            
+        Returns:
+            List of contract instances
+        """
+        try:
+            registry = self.get_registry()
+            return registry.list_contracts(state, created_by)
+        except Exception as e:
+            logger.error(f"Failed to list contracts: {e}")
+            return []
+    
+    async def propose_contract(self, contract_id: UUID, request: ContractProposeRequest, 
+                              proposed_by: str) -> Optional[Contract]:
+        """Propose a contract to parties.
+        
+        Args:
+            contract_id: Contract UUID
+            request: Proposal request
+            proposed_by: ID of the proposing party
+            
+        Returns:
+            Updated contract instance or None if not found
+            
+        Raises:
+            ValueError: If proposal fails
+        """
+        try:
+            registry = self.get_registry()
+            
+            # Validate contract exists and can be proposed
+            contract = registry.get_contract(contract_id)
+            if not contract:
+                raise ValueError("Contract not found")
+            
+            if contract.state != ContractState.DRAFT:
+                raise ValueError(f"Cannot propose contract in state {contract.state}")
+            
+            # Update metadata with proposal info
+            metadata = {
+                "proposal": {
+                    "proposed_to": request.proposed_to,
+                    "message": request.message,
+                    "proposed_by": proposed_by,
+                    "timestamp": datetime.utcnow().isoformat()
+                }
+            }
+            
+            # Update state to proposed
+            updated_contract = registry.update_contract_state(
+                contract_id, ContractState.PROPOSED, proposed_by, metadata
+            )
+            
+            logger.info(f"Proposed contract {contract_id} to {request.proposed_to} by {proposed_by}")
+            return updated_contract
+            
+        except Exception as e:
+            logger.error(f"Failed to propose contract {contract_id}: {e}")
+            raise
+    
+    async def sign_contract(self, contract_id: UUID, request: ContractSignRequest) -> Optional[Contract]:
+        """Sign a contract.
+        
+        Args:
+            contract_id: Contract UUID
+            request: Signing request
+            
+        Returns:
+            Updated contract instance or None if not found
+            
+        Raises:
+            ValueError: If signing fails
+        """
+        try:
+            registry = self.get_registry()
+            
+            # Validate contract exists and can be signed
+            contract = registry.get_contract(contract_id)
+            if not contract:
+                raise ValueError("Contract not found")
+            
+            if contract.state not in [ContractState.PROPOSED, ContractState.SIGNED]:
+                raise ValueError(f"Cannot sign contract in state {contract.state}")
+            
+            # Check if party is already signed
+            existing_signatures = contract.get_signatures()
+            if any(sig.signer_id == request.signer_id for sig in existing_signatures):
+                raise ValueError("Party has already signed this contract")
+            
+            # Verify signature
+            if not self._verify_contract_signature(contract, request):
+                raise ValueError("Invalid signature")
+            
+            # Create signature object
+            from .contract import Signature
+            signature = Signature(
+                signer_id=request.signer_id,
+                signer_type=request.signer_type,
+                signature=request.signature,
+                public_key=request.public_key,
+                metadata=request.metadata
+            )
+            
+            # Add signature
+            updated_contract = registry.add_signature(contract_id, signature.model_dump())
+            
+            logger.info(f"Signed contract {contract_id} by {request.signer_id}")
+            return updated_contract
+            
+        except Exception as e:
+            logger.error(f"Failed to sign contract {contract_id}: {e}")
+            raise
+    
+    async def revoke_contract(self, contract_id: UUID, request: ContractRevokeRequest) -> Optional[Contract]:
+        """Revoke a contract.
+        
+        Args:
+            contract_id: Contract UUID
+            request: Revocation request
+            
+        Returns:
+            Updated contract instance or None if not found
+            
+        Raises:
+            ValueError: If revocation fails
+        """
+        try:
+            registry = self.get_registry()
+            
+            # Validate contract exists and can be revoked
+            contract = registry.get_contract(contract_id)
+            if not contract:
+                raise ValueError("Contract not found")
+            
+            if contract.state == ContractState.REVOKED:
+                raise ValueError("Contract is already revoked")
+            
+            if contract.state == ContractState.EXPIRED:
+                raise ValueError("Cannot revoke expired contract")
+            
+            # Revoke contract
+            updated_contract = registry.revoke_contract(
+                contract_id, request.reason, request.revoked_by, request.metadata
+            )
+            
+            logger.info(f"Revoked contract {contract_id} by {request.revoked_by}: {request.reason}")
+            return updated_contract
+            
+        except Exception as e:
+            logger.error(f"Failed to revoke contract {contract_id}: {e}")
+            raise
+    
+    def _verify_contract_signature(self, contract: Contract, request: ContractSignRequest) -> bool:
+        """Verify a contract signature.
+        
+        Args:
+            contract: Contract instance
+            request: Signing request
+            
+        Returns:
+            True if signature is valid, False otherwise
+        """
+        try:
+            from .crypto import verify_signature
+            
+            # Create signing message
+            signing_message = f"{contract.id}:{contract.get_content_hash()}:{request.signer_id}:{request.signer_type}"
+            
+            # Verify signature
+            return verify_signature(
+                request.public_key,
+                signing_message,
+                request.signature
+            )
+            
+        except Exception as e:
+            logger.error(f"Signature verification failed: {e}")
+            return False
+    
+    async def get_contracts_by_party(self, party_id: str) -> List[Contract]:
+        """Get contracts involving a specific party.
+        
+        Args:
+            party_id: Party ID to search for
+            
+        Returns:
+            List of contracts involving the party
+        """
+        try:
+            registry = self.get_registry()
+            return registry.get_contracts_by_party(party_id)
+        except Exception as e:
+            logger.error(f"Failed to get contracts for party {party_id}: {e}")
+            return []
+    
+    async def cleanup_expired_contracts(self) -> int:
+        """Mark expired contracts as expired.
+        
+        Returns:
+            Number of contracts marked as expired
+        """
+        try:
+            registry = self.get_registry()
+            count = registry.mark_contracts_expired()
+            logger.info(f"Marked {count} contracts as expired")
+            return count
+        except Exception as e:
+            logger.error(f"Failed to cleanup expired contracts: {e}")
+            return 0
+    
+    async def get_contract_statistics(self) -> dict:
+        """Get contract statistics.
+        
+        Returns:
+            Dictionary with contract statistics
+        """
+        try:
+            registry = self.get_registry()
+            
+            # Get all contracts
+            all_contracts = registry.list_contracts()
+            
+            # Count by state
+            state_counts = {}
+            for state in ContractState:
+                state_counts[state.value] = len([c for c in all_contracts if c.state == state])
+            
+            # Count HIPAA contracts
+            hipaa_count = len([c for c in all_contracts if c.is_hipaa_compliant])
+            
+            # Count signed contracts
+            signed_count = len([c for c in all_contracts if c.state == ContractState.SIGNED])
+            
+            return {
+                "total_contracts": len(all_contracts),
+                "by_state": state_counts,
+                "hipaa_compliant": hipaa_count,
+                "signed_contracts": signed_count,
+                "expired_contracts": len(registry.get_expired_contracts())
+            }
+            
+        except Exception as e:
+            logger.error(f"Failed to get contract statistics: {e}")
+            return {}

src/fastmcp/contracts/registry.py

@@ -0,0 +1,391 @@
+"""Contract registry for managing contract persistence and lifecycle."""
+
+import json
+from datetime import datetime
+from typing import List, Optional
+from uuid import UUID
+
+from sqlmodel import Session, select
+
+from fastmcp.utilities.logging import get_logger
+
+from .contract import Contract, ContractState, Signature
+from .crypto import ContractSigner, CryptoError
+
+logger = get_logger(__name__)
+
+
+class ContractRegistry:
+    """Registry for managing contract persistence and lifecycle operations."""
+    
+    def __init__(self, session: Session):
+        """Initialize registry with database session.
+        
+        Args:
+            session: SQLModel database session
+        """
+        self.session = session
+    
+    def create_contract(self, contract_data: dict, created_by: str) -> Contract:
+        """Create a new contract.
+        
+        Args:
+            contract_data: Contract data dictionary
+            created_by: ID of the creating party
+            
+        Returns:
+            Created contract instance
+            
+        Raises:
+            ValueError: If contract data is invalid
+        """
+        try:
+            # Create contract instance
+            contract = Contract(
+                title=contract_data["title"],
+                description=contract_data["description"],
+                created_by=created_by,
+                is_hipaa_compliant=contract_data.get("is_hipaa_compliant", False),
+                version=contract_data.get("version", "1.0.0")
+            )
+            
+            # Set clauses
+            if "clauses" in contract_data:
+                from .contract import Clause
+                clauses = [Clause(**clause) for clause in contract_data["clauses"]]
+                contract.set_clauses(clauses)
+            
+            # Set parties
+            if "parties" in contract_data:
+                contract.set_parties(contract_data["parties"])
+            
+            # Set HIPAA entities
+            if "hipaa_entities" in contract_data and contract_data["hipaa_entities"]:
+                contract.set_hipaa_entities(contract_data["hipaa_entities"])
+            
+            # Set metadata
+            if "metadata" in contract_data:
+                contract.set_metadata(contract_data["metadata"])
+            
+            # Set expiration
+            if "expires_at" in contract_data and contract_data["expires_at"]:
+                contract.expires_at = contract_data["expires_at"]
+            
+            # Save to database
+            self.session.add(contract)
+            self.session.commit()
+            self.session.refresh(contract)
+            
+            logger.info(f"Created contract {contract.id} by {created_by}")
+            return contract
+            
+        except Exception as e:
+            self.session.rollback()
+            logger.error(f"Failed to create contract: {e}")
+            raise ValueError(f"Contract creation failed: {e}")
+    
+    def get_contract(self, contract_id: UUID) -> Optional[Contract]:
+        """Get a contract by ID.
+        
+        Args:
+            contract_id: Contract UUID
+            
+        Returns:
+            Contract instance or None if not found
+        """
+        try:
+            statement = select(Contract).where(Contract.id == contract_id)
+            return self.session.exec(statement).first()
+        except Exception as e:
+            logger.error(f"Failed to get contract {contract_id}: {e}")
+            return None
+    
+    def list_contracts(self, state: Optional[ContractState] = None, 
+                      created_by: Optional[str] = None) -> List[Contract]:
+        """List contracts with optional filtering.
+        
+        Args:
+            state: Optional state filter
+            created_by: Optional creator filter
+            
+        Returns:
+            List of contract instances
+        """
+        try:
+            statement = select(Contract)
+            
+            if state is not None:
+                statement = statement.where(Contract.state == state)
+            
+            if created_by is not None:
+                statement = statement.where(Contract.created_by == created_by)
+            
+            statement = statement.order_by(Contract.created_at.desc())
+            return list(self.session.exec(statement))
+            
+        except Exception as e:
+            logger.error(f"Failed to list contracts: {e}")
+            return []
+    
+    def update_contract_state(self, contract_id: UUID, new_state: ContractState, 
+                            updated_by: str, metadata: Optional[dict] = None) -> Optional[Contract]:
+        """Update contract state with lifecycle validation.
+        
+        Args:
+            contract_id: Contract UUID
+            new_state: New state to transition to
+            updated_by: ID of the updating party
+            metadata: Optional metadata for the state change
+            
+        Returns:
+            Updated contract instance or None if not found
+            
+        Raises:
+            ValueError: If state transition is invalid
+        """
+        try:
+            contract = self.get_contract(contract_id)
+            if not contract:
+                return None
+            
+            # Validate state transition
+            if not contract.can_transition_to(new_state):
+                raise ValueError(f"Invalid state transition from {contract.state} to {new_state}")
+            
+            # Update state and timestamps
+            old_state = contract.state
+            contract.state = new_state
+            contract.last_modified = datetime.utcnow()
+            
+            # Set state-specific timestamps
+            if new_state == ContractState.PROPOSED and contract.proposed_at is None:
+                contract.proposed_at = datetime.utcnow()
+            elif new_state == ContractState.SIGNED and contract.signed_at is None:
+                contract.signed_at = datetime.utcnow()
+            elif new_state == ContractState.REVOKED and contract.revoked_at is None:
+                contract.revoked_at = datetime.utcnow()
+            
+            # Update metadata if provided
+            if metadata:
+                current_metadata = contract.get_metadata()
+                current_metadata.update(metadata)
+                current_metadata[f"state_change_{new_state}"] = {
+                    "timestamp": datetime.utcnow().isoformat(),
+                    "updated_by": updated_by,
+                    "previous_state": old_state
+                }
+                contract.set_metadata(current_metadata)
+            
+            # Save changes
+            self.session.add(contract)
+            self.session.commit()
+            self.session.refresh(contract)
+            
+            logger.info(f"Updated contract {contract_id} state from {old_state} to {new_state} by {updated_by}")
+            return contract
+            
+        except Exception as e:
+            self.session.rollback()
+            logger.error(f"Failed to update contract {contract_id} state: {e}")
+            raise
+    
+    def add_signature(self, contract_id: UUID, signature_data: dict) -> Optional[Contract]:
+        """Add a signature to a contract.
+        
+        Args:
+            contract_id: Contract UUID
+            signature_data: Signature data dictionary
+            
+        Returns:
+            Updated contract instance or None if not found
+            
+        Raises:
+            ValueError: If signature is invalid or contract not in signable state
+        """
+        try:
+            contract = self.get_contract(contract_id)
+            if not contract:
+                return None
+            
+            # Validate contract state
+            if contract.state not in [ContractState.PROPOSED, ContractState.SIGNED]:
+                raise ValueError(f"Cannot sign contract in state {contract.state}")
+            
+            # Create signature
+            from .contract import Signature
+            signature = Signature(**signature_data)
+            
+            # Verify signature
+            if not self._verify_signature(contract, signature):
+                raise ValueError("Invalid signature")
+            
+            # Add signature
+            signatures = contract.get_signatures()
+            signatures.append(signature)
+            contract.set_signatures(signatures)
+            
+            # Update state if fully signed
+            if contract.is_fully_signed() and contract.state == ContractState.PROPOSED:
+                # Use the proper state transition method
+                contract = self.update_contract_state(contract_id, ContractState.SIGNED, signature.signer_id)
+            
+            contract.last_modified = datetime.utcnow()
+            
+            # Save changes
+            self.session.add(contract)
+            self.session.commit()
+            self.session.refresh(contract)
+            
+            logger.info(f"Added signature to contract {contract_id} by {signature.signer_id}")
+            return contract
+            
+        except Exception as e:
+            self.session.rollback()
+            logger.error(f"Failed to add signature to contract {contract_id}: {e}")
+            raise
+    
+    def _verify_signature(self, contract: Contract, signature: Signature) -> bool:
+        """Verify a contract signature.
+        
+        Args:
+            contract: Contract instance
+            signature: Signature to verify
+            
+        Returns:
+            True if signature is valid, False otherwise
+        """
+        try:
+            from .crypto import verify_signature
+            
+            # Create signing message
+            signing_message = f"{contract.id}:{contract.get_content_hash()}:{signature.signer_id}:{signature.signer_type}"
+            
+            # Verify signature
+            return verify_signature(
+                signature.public_key,
+                signing_message,
+                signature.signature
+            )
+            
+        except Exception as e:
+            logger.error(f"Signature verification failed: {e}")
+            return False
+    
+    def revoke_contract(self, contract_id: UUID, reason: str, revoked_by: str, 
+                       metadata: Optional[dict] = None) -> Optional[Contract]:
+        """Revoke a contract.
+        
+        Args:
+            contract_id: Contract UUID
+            reason: Reason for revocation
+            revoked_by: ID of the revoking party
+            metadata: Optional revocation metadata
+            
+        Returns:
+            Updated contract instance or None if not found
+            
+        Raises:
+            ValueError: If contract cannot be revoked
+        """
+        try:
+            contract = self.get_contract(contract_id)
+            if not contract:
+                return None
+            
+            # Validate revocation
+            if contract.state == ContractState.REVOKED:
+                raise ValueError("Contract is already revoked")
+            
+            if contract.state == ContractState.EXPIRED:
+                raise ValueError("Cannot revoke expired contract")
+            
+            # Update metadata with revocation info
+            current_metadata = contract.get_metadata()
+            current_metadata["revocation"] = {
+                "reason": reason,
+                "revoked_by": revoked_by,
+                "timestamp": datetime.utcnow().isoformat()
+            }
+            if metadata:
+                current_metadata["revocation"].update(metadata)
+            
+            contract.set_metadata(current_metadata)
+            
+            # Update state
+            return self.update_contract_state(contract_id, ContractState.REVOKED, revoked_by)
+            
+        except Exception as e:
+            logger.error(f"Failed to revoke contract {contract_id}: {e}")
+            raise
+    
+    def get_contracts_by_party(self, party_id: str) -> List[Contract]:
+        """Get contracts involving a specific party.
+        
+        Args:
+            party_id: Party ID to search for
+            
+        Returns:
+            List of contracts involving the party
+        """
+        try:
+            statement = select(Contract)
+            contracts = list(self.session.exec(statement))
+            
+            # Filter contracts that involve the party
+            party_contracts = []
+            for contract in contracts:
+                parties = contract.get_parties()
+                if any(party.get("id") == party_id for party in parties):
+                    party_contracts.append(contract)
+            
+            return party_contracts
+            
+        except Exception as e:
+            logger.error(f"Failed to get contracts for party {party_id}: {e}")
+            return []
+    
+    def get_expired_contracts(self) -> List[Contract]:
+        """Get contracts that have expired.
+        
+        Returns:
+            List of expired contracts
+        """
+        try:
+            now = datetime.utcnow()
+            statement = select(Contract).where(
+                Contract.expires_at.isnot(None),
+                Contract.expires_at < now,
+                Contract.state.notin_([ContractState.EXPIRED, ContractState.REVOKED])
+            )
+            return list(self.session.exec(statement))
+            
+        except Exception as e:
+            logger.error(f"Failed to get expired contracts: {e}")
+            return []
+    
+    def mark_contracts_expired(self) -> int:
+        """Mark expired contracts as expired.
+        
+        Returns:
+            Number of contracts marked as expired
+        """
+        try:
+            expired_contracts = self.get_expired_contracts()
+            count = 0
+            
+            for contract in expired_contracts:
+                contract.state = ContractState.EXPIRED
+                contract.last_modified = datetime.utcnow()
+                self.session.add(contract)
+                count += 1
+            
+            if count > 0:
+                self.session.commit()
+                logger.info(f"Marked {count} contracts as expired")
+            
+            return count
+            
+        except Exception as e:
+            self.session.rollback()
+            logger.error(f"Failed to mark contracts as expired: {e}")
+            return 0

src/fastmcp/ledger/__init__.py

@@ -0,0 +1,17 @@
+"""FastMCP Ledger - Tamper-evident provenance ledger for auditability and non-repudiation."""
+
+from .ledger import LedgerEntry, LedgerBlock, ProvenanceLedger, LedgerEvent, EventType
+from .merkle import MerkleTree, MerkleProof
+from .adapter import LedgerAdapter, HyperledgerAdapter
+
+__all__ = [
+    "LedgerEntry", 
+    "LedgerBlock", 
+    "ProvenanceLedger", 
+    "LedgerEvent",
+    "EventType",
+    "MerkleTree", 
+    "MerkleProof",
+    "LedgerAdapter", 
+    "HyperledgerAdapter"
+]

src/fastmcp/ledger/adapter.py

@@ -0,0 +1,384 @@
+"""Ledger adapters for external blockchain backends like Hyperledger/OmniSeal."""
+
+import json
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+from datetime import datetime
+
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class LedgerAdapter(ABC):
+    """Abstract base class for ledger adapters."""
+    
+    @abstractmethod
+    async def submit_block(self, block_data: Dict[str, Any]) -> str:
+        """Submit a block to the external ledger.
+        
+        Args:
+            block_data: The block data to submit
+            
+        Returns:
+            Transaction ID or block hash from the external ledger
+        """
+        pass
+    
+    @abstractmethod
+    async def verify_block(self, block_id: str) -> bool:
+        """Verify a block exists and is valid on the external ledger.
+        
+        Args:
+            block_id: The block ID to verify
+            
+        Returns:
+            True if block is valid, False otherwise
+        """
+        pass
+    
+    @abstractmethod
+    async def get_block_proof(self, block_id: str) -> Optional[Dict[str, Any]]:
+        """Get a proof of block existence from the external ledger.
+        
+        Args:
+            block_id: The block ID to get proof for
+            
+        Returns:
+            Proof data or None if not found
+        """
+        pass
+
+
+class HyperledgerAdapter(LedgerAdapter):
+    """Adapter for Hyperledger Fabric blockchain backend."""
+    
+    def __init__(self, 
+                 network_config: str,
+                 channel_name: str = "mcp-channel",
+                 chaincode_name: str = "provenance-ledger",
+                 peer_endpoint: str = "localhost:7051",
+                 orderer_endpoint: str = "localhost:7050"):
+        """Initialize Hyperledger adapter.
+        
+        Args:
+            network_config: Path to network configuration file
+            channel_name: Name of the Hyperledger channel
+            chaincode_name: Name of the deployed chaincode
+            peer_endpoint: Peer endpoint URL
+            orderer_endpoint: Orderer endpoint URL
+        """
+        self.network_config = network_config
+        self.channel_name = channel_name
+        self.chaincode_name = chaincode_name
+        self.peer_endpoint = peer_endpoint
+        self.orderer_endpoint = orderer_endpoint
+        self._client = None
+        
+    async def _get_client(self):
+        """Get or create Hyperledger client."""
+        if self._client is None:
+            try:
+                # This would import the actual Hyperledger Fabric SDK
+                # from hfc.fabric import Client
+                # self._client = Client(net_profile=self.network_config)
+                logger.info("Hyperledger client initialized (stub implementation)")
+                self._client = "stub_client"
+            except ImportError:
+                logger.warning("Hyperledger Fabric SDK not available, using stub implementation")
+                self._client = "stub_client"
+        return self._client
+    
+    async def submit_block(self, block_data: Dict[str, Any]) -> str:
+        """Submit a block to Hyperledger Fabric.
+        
+        Args:
+            block_data: The block data to submit
+            
+        Returns:
+            Transaction ID from Hyperledger
+        """
+        try:
+            client = await self._get_client()
+            
+            # Prepare transaction data
+            transaction_data = {
+                "block_number": block_data.get("block_number"),
+                "merkle_root": block_data.get("merkle_root"),
+                "entry_count": block_data.get("entry_count"),
+                "timestamp": datetime.utcnow().isoformat(),
+                "entries": block_data.get("entries", [])
+            }
+            
+            # In a real implementation, this would:
+            # 1. Create a transaction proposal
+            # 2. Send it to endorsing peers
+            # 3. Submit to ordering service
+            # 4. Return transaction ID
+            
+            # Stub implementation
+            import hashlib
+            tx_data = json.dumps(transaction_data, sort_keys=True)
+            tx_id = hashlib.sha256(tx_data.encode()).hexdigest()
+            
+            logger.info(f"Submitted block {block_data.get('block_number')} to Hyperledger (tx: {tx_id})")
+            return tx_id
+            
+        except Exception as e:
+            logger.error(f"Failed to submit block to Hyperledger: {e}")
+            raise
+    
+    async def verify_block(self, block_id: str) -> bool:
+        """Verify a block exists on Hyperledger Fabric.
+        
+        Args:
+            block_id: The block ID to verify
+            
+        Returns:
+            True if block is valid, False otherwise
+        """
+        try:
+            client = await self._get_client()
+            
+            # In a real implementation, this would:
+            # 1. Query the blockchain for the block
+            # 2. Verify the block structure
+            # 3. Check block signatures
+            
+            # Stub implementation - always return True for demo
+            logger.info(f"Verified block {block_id} on Hyperledger")
+            return True
+            
+        except Exception as e:
+            logger.error(f"Failed to verify block {block_id}: {e}")
+            return False
+    
+    async def get_block_proof(self, block_id: str) -> Optional[Dict[str, Any]]:
+        """Get a proof of block existence from Hyperledger Fabric.
+        
+        Args:
+            block_id: The block ID to get proof for
+            
+        Returns:
+            Proof data or None if not found
+        """
+        try:
+            client = await self._get_client()
+            
+            # In a real implementation, this would:
+            # 1. Query the blockchain for block details
+            # 2. Get block header and signatures
+            # 3. Return proof data
+            
+            # Stub implementation
+            proof_data = {
+                "block_id": block_id,
+                "block_hash": f"hyperledger_hash_{block_id}",
+                "block_number": int(block_id.split('_')[-1]) if '_' in block_id else 0,
+                "timestamp": datetime.utcnow().isoformat(),
+                "proof_type": "hyperledger_fabric",
+                "signatures": ["peer1_signature", "peer2_signature"],
+                "merkle_root": f"merkle_root_{block_id}"
+            }
+            
+            logger.info(f"Retrieved block proof for {block_id} from Hyperledger")
+            return proof_data
+            
+        except Exception as e:
+            logger.error(f"Failed to get block proof for {block_id}: {e}")
+            return None
+
+
+class OmniSealAdapter(LedgerAdapter):
+    """Adapter for OmniSeal blockchain backend."""
+    
+    def __init__(self, 
+                 api_endpoint: str = "https://api.omniseal.com",
+                 api_key: str = None,
+                 network_id: str = "mainnet"):
+        """Initialize OmniSeal adapter.
+        
+        Args:
+            api_endpoint: OmniSeal API endpoint
+            api_key: API key for authentication
+            network_id: Network ID to use
+        """
+        self.api_endpoint = api_endpoint
+        self.api_key = api_key
+        self.network_id = network_id
+        self._session = None
+    
+    async def _get_session(self):
+        """Get or create HTTP session."""
+        if self._session is None:
+            try:
+                import aiohttp
+                headers = {}
+                if self.api_key:
+                    headers["Authorization"] = f"Bearer {self.api_key}"
+                self._session = aiohttp.ClientSession(
+                    base_url=self.api_endpoint,
+                    headers=headers
+                )
+            except ImportError:
+                logger.warning("aiohttp not available, using stub implementation")
+                self._session = "stub_session"
+        return self._session
+    
+    async def submit_block(self, block_data: Dict[str, Any]) -> str:
+        """Submit a block to OmniSeal.
+        
+        Args:
+            block_data: The block data to submit
+            
+        Returns:
+            Transaction ID from OmniSeal
+        """
+        try:
+            session = await self._get_session()
+            
+            # Prepare submission data
+            submission_data = {
+                "network_id": self.network_id,
+                "block_data": block_data,
+                "timestamp": datetime.utcnow().isoformat()
+            }
+            
+            # In a real implementation, this would:
+            # 1. Send POST request to OmniSeal API
+            # 2. Handle response and errors
+            # 3. Return transaction ID
+            
+            # Stub implementation
+            import hashlib
+            tx_data = json.dumps(submission_data, sort_keys=True)
+            tx_id = hashlib.sha256(tx_data.encode()).hexdigest()
+            
+            logger.info(f"Submitted block {block_data.get('block_number')} to OmniSeal (tx: {tx_id})")
+            return tx_id
+            
+        except Exception as e:
+            logger.error(f"Failed to submit block to OmniSeal: {e}")
+            raise
+    
+    async def verify_block(self, block_id: str) -> bool:
+        """Verify a block exists on OmniSeal.
+        
+        Args:
+            block_id: The block ID to verify
+            
+        Returns:
+            True if block is valid, False otherwise
+        """
+        try:
+            session = await self._get_session()
+            
+            # In a real implementation, this would:
+            # 1. Send GET request to OmniSeal API
+            # 2. Check response status
+            # 3. Verify block data
+            
+            # Stub implementation
+            logger.info(f"Verified block {block_id} on OmniSeal")
+            return True
+            
+        except Exception as e:
+            logger.error(f"Failed to verify block {block_id}: {e}")
+            return False
+    
+    async def get_block_proof(self, block_id: str) -> Optional[Dict[str, Any]]:
+        """Get a proof of block existence from OmniSeal.
+        
+        Args:
+            block_id: The block ID to get proof for
+            
+        Returns:
+            Proof data or None if not found
+        """
+        try:
+            session = await self._get_session()
+            
+            # In a real implementation, this would:
+            # 1. Send GET request to OmniSeal API
+            # 2. Parse response data
+            # 3. Return proof information
+            
+            # Stub implementation
+            proof_data = {
+                "block_id": block_id,
+                "block_hash": f"omniseal_hash_{block_id}",
+                "block_number": int(block_id.split('_')[-1]) if '_' in block_id else 0,
+                "timestamp": datetime.utcnow().isoformat(),
+                "proof_type": "omniseal",
+                "network_id": self.network_id,
+                "merkle_root": f"merkle_root_{block_id}"
+            }
+            
+            logger.info(f"Retrieved block proof for {block_id} from OmniSeal")
+            return proof_data
+            
+        except Exception as e:
+            logger.error(f"Failed to get block proof for {block_id}: {e}")
+            return None
+
+
+class StubAdapter(LedgerAdapter):
+    """Stub adapter for testing and development."""
+    
+    def __init__(self):
+        """Initialize stub adapter."""
+        self.submitted_blocks = {}
+        self.block_proofs = {}
+    
+    async def submit_block(self, block_data: Dict[str, Any]) -> str:
+        """Submit a block to the stub storage.
+        
+        Args:
+            block_data: The block data to submit
+            
+        Returns:
+            Generated block ID
+        """
+        import hashlib
+        block_id = f"stub_block_{len(self.submitted_blocks) + 1}"
+        self.submitted_blocks[block_id] = block_data
+        logger.info(f"Submitted block {block_data.get('block_number')} to stub storage (id: {block_id})")
+        return block_id
+    
+    async def verify_block(self, block_id: str) -> bool:
+        """Verify a block exists in stub storage.
+        
+        Args:
+            block_id: The block ID to verify
+            
+        Returns:
+            True if block exists, False otherwise
+        """
+        exists = block_id in self.submitted_blocks
+        logger.info(f"Verified block {block_id} in stub storage: {exists}")
+        return exists
+    
+    async def get_block_proof(self, block_id: str) -> Optional[Dict[str, Any]]:
+        """Get a proof of block existence from stub storage.
+        
+        Args:
+            block_id: The block ID to get proof for
+            
+        Returns:
+            Proof data or None if not found
+        """
+        if block_id not in self.submitted_blocks:
+            return None
+        
+        block_data = self.submitted_blocks[block_id]
+        proof_data = {
+            "block_id": block_id,
+            "block_hash": f"stub_hash_{block_id}",
+            "block_number": block_data.get("block_number", 0),
+            "timestamp": datetime.utcnow().isoformat(),
+            "proof_type": "stub",
+            "merkle_root": block_data.get("merkle_root", "")
+        }
+        
+        logger.info(f"Retrieved block proof for {block_id} from stub storage")
+        return proof_data

src/fastmcp/ledger/ledger.py

@@ -0,0 +1,504 @@
+"""Core ledger implementation with hash-linked entries and tamper-evident properties."""
+
+import hashlib
+import json
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, List, Optional
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field
+from sqlmodel import SQLModel, Field as SQLField, Relationship
+
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class EventType(str, Enum):
+    """Types of events that can be recorded in the ledger."""
+    TOOL_CALL = "tool_call"
+    POLICY_DECISION = "policy_decision"
+    DATA_FLOW = "data_flow"
+    CONTRACT_ACTION = "contract_action"
+    AUTHENTICATION = "authentication"
+    AUTHORIZATION = "authorization"
+    SYSTEM_EVENT = "system_event"
+
+
+class LedgerEvent(BaseModel):
+    """A ledger event with structured data."""
+    
+    event_type: EventType = Field(..., description="Type of event")
+    actor_id: str = Field(..., description="ID of the actor performing the action")
+    resource_id: Optional[str] = Field(default=None, description="ID of the resource being acted upon")
+    action: str = Field(..., description="Action being performed")
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Additional event metadata")
+    timestamp: datetime = Field(default_factory=datetime.utcnow, description="Event timestamp")
+    data_hash: Optional[str] = Field(default=None, description="Hash of associated data")
+    
+    def get_content_hash(self) -> str:
+        """Get SHA-256 hash of event content for integrity verification."""
+        content = {
+            "event_type": self.event_type,
+            "actor_id": self.actor_id,
+            "resource_id": self.resource_id,
+            "action": self.action,
+            "metadata": self.metadata,
+            "data_hash": self.data_hash
+        }
+        content_str = json.dumps(content, sort_keys=True, default=str)
+        return hashlib.sha256(content_str.encode()).hexdigest()
+
+
+class LedgerEntry(SQLModel, table=True):
+    """A single entry in the provenance ledger with hash chaining."""
+    
+    __tablename__ = "ledger_entries"
+    
+    # Primary fields
+    id: UUID = SQLField(default_factory=uuid4, primary_key=True)
+    sequence_number: int = SQLField(..., index=True, description="Sequential entry number")
+    
+    # Event data
+    event_data: str = SQLField(..., description="JSON-encoded event data")
+    
+    # Hash chaining
+    previous_hash: Optional[str] = SQLField(default=None, description="Hash of previous entry")
+    entry_hash: str = SQLField(..., index=True, description="Hash of this entry")
+    
+    # Block information
+    block_id: Optional[UUID] = SQLField(default=None, foreign_key="ledger_blocks.id", index=True)
+    
+    # Timestamps
+    created_at: datetime = SQLField(default_factory=datetime.utcnow, index=True)
+    
+    # Verification
+    is_verified: bool = SQLField(default=True, description="Whether entry has been verified")
+    verification_timestamp: Optional[datetime] = SQLField(default=None)
+    
+    def get_event(self) -> LedgerEvent:
+        """Get parsed event from JSON."""
+        try:
+            event_data = json.loads(self.event_data)
+            return LedgerEvent(**event_data)
+        except (json.JSONDecodeError, ValueError) as e:
+            logger.error(f"Failed to parse event data: {e}")
+            raise ValueError(f"Invalid event data: {e}")
+    
+    def set_event(self, event: LedgerEvent) -> None:
+        """Set event as JSON."""
+        self.event_data = json.dumps(event.model_dump(), default=str)
+    
+    def calculate_hash(self) -> str:
+        """Calculate hash of this entry including previous hash."""
+        content = {
+            "sequence_number": self.sequence_number,
+            "event_data": self.event_data,
+            "previous_hash": self.previous_hash,
+            "created_at": self.created_at.isoformat()
+        }
+        content_str = json.dumps(content, sort_keys=True, default=str)
+        return hashlib.sha256(content_str.encode()).hexdigest()
+    
+    def verify_integrity(self) -> bool:
+        """Verify that the entry hash matches the calculated hash."""
+        calculated_hash = self.calculate_hash()
+        return calculated_hash == self.entry_hash
+
+
+class LedgerBlock(SQLModel, table=True):
+    """A block of ledger entries with Merkle tree root."""
+    
+    __tablename__ = "ledger_blocks"
+    
+    # Primary fields
+    id: UUID = SQLField(default_factory=uuid4, primary_key=True)
+    block_number: int = SQLField(..., index=True, description="Sequential block number")
+    
+    # Block metadata
+    entry_count: int = SQLField(..., description="Number of entries in this block")
+    first_entry_sequence: int = SQLField(..., description="Sequence number of first entry")
+    last_entry_sequence: int = SQLField(..., description="Sequence number of last entry")
+    
+    # Merkle tree
+    merkle_root: str = SQLField(..., description="Merkle tree root hash")
+    merkle_tree_data: str = SQLField(default="[]", description="JSON-encoded Merkle tree data")
+    
+    # Timestamps
+    created_at: datetime = SQLField(default_factory=datetime.utcnow, index=True)
+    sealed_at: Optional[datetime] = SQLField(default=None, description="When block was sealed")
+    
+    # Verification
+    is_verified: bool = SQLField(default=True, description="Whether block has been verified")
+    verification_timestamp: Optional[datetime] = SQLField(default=None)
+    
+    def get_merkle_tree_data(self) -> List[Dict[str, Any]]:
+        """Get parsed Merkle tree data from JSON."""
+        try:
+            return json.loads(self.merkle_tree_data)
+        except json.JSONDecodeError:
+            return []
+    
+    def set_merkle_tree_data(self, tree_data: List[Dict[str, Any]]) -> None:
+        """Set Merkle tree data as JSON."""
+        self.merkle_tree_data = json.dumps(tree_data)
+    
+    def verify_integrity(self, entries: List[LedgerEntry]) -> bool:
+        """Verify that the Merkle root matches the entries."""
+        if len(entries) != self.entry_count:
+            return False
+        
+        # Calculate Merkle root from entries
+        from .merkle import MerkleTree
+        entry_hashes = [entry.entry_hash for entry in entries]
+        merkle_tree = MerkleTree(entry_hashes)
+        calculated_root = merkle_tree.get_root()
+        
+        return calculated_root == self.merkle_root
+
+
+class ProvenanceLedger:
+    """Main ledger class for managing provenance entries with tamper-evident properties."""
+    
+    def __init__(self, database_url: str = "sqlite:///ledger.db"):
+        """Initialize the provenance ledger.
+        
+        Args:
+            database_url: Database connection URL
+        """
+        from sqlmodel import create_engine, Session
+        self.engine = create_engine(database_url, echo=False)
+        self._create_tables()
+        self._current_sequence = self._get_next_sequence_number()
+        self._current_block = None
+        self._block_size = 100  # Entries per block
+        
+    def _create_tables(self):
+        """Create database tables."""
+        try:
+            LedgerEntry.metadata.create_all(self.engine)
+            LedgerBlock.metadata.create_all(self.engine)
+            logger.info("Ledger database tables created/verified")
+        except Exception as e:
+            logger.error(f"Failed to create ledger tables: {e}")
+            raise
+    
+    def _get_next_sequence_number(self) -> int:
+        """Get the next sequence number for entries."""
+        from sqlmodel import Session, select, func
+        with Session(self.engine) as session:
+            result = session.exec(select(func.max(LedgerEntry.sequence_number))).first()
+            return (result or 0) + 1
+    
+    def _get_next_block_number(self) -> int:
+        """Get the next block number."""
+        from sqlmodel import Session, select, func
+        with Session(self.engine) as session:
+            result = session.exec(select(func.max(LedgerBlock.block_number))).first()
+            return (result or 0) + 1
+    
+    def append_event(self, event: LedgerEvent) -> LedgerEntry:
+        """Append a new event to the ledger.
+        
+        Args:
+            event: The event to append
+            
+        Returns:
+            The created ledger entry
+            
+        Raises:
+            ValueError: If event is invalid
+        """
+        try:
+            from sqlmodel import Session, select
+            
+            with Session(self.engine) as session:
+                # Get previous entry hash
+                previous_hash = None
+                if self._current_sequence > 1:
+                    prev_entry = session.exec(
+                        select(LedgerEntry).where(
+                            LedgerEntry.sequence_number == self._current_sequence - 1
+                        )
+                    ).first()
+                    if prev_entry:
+                        previous_hash = prev_entry.entry_hash
+                
+                # Create new entry
+                entry = LedgerEntry(
+                    sequence_number=self._current_sequence,
+                    previous_hash=previous_hash
+                )
+                entry.set_event(event)
+                entry.entry_hash = entry.calculate_hash()
+                
+                # Add to current block or create new block
+                if self._current_block is None or self._should_seal_block():
+                    self._current_block = self._create_new_block(session)
+                
+                entry.block_id = self._current_block.id
+                
+                # Save entry
+                session.add(entry)
+                session.commit()
+                session.refresh(entry)
+                
+                # Update block entry count
+                self._current_block.entry_count += 1
+                self._current_block.last_entry_sequence = entry.sequence_number
+                session.add(self._current_block)
+                
+                # Check if block should be sealed
+                if self._should_seal_block():
+                    self._seal_block(session)
+                
+                self._current_sequence += 1
+                
+                logger.info(f"Appended event {entry.id} to ledger (sequence: {entry.sequence_number})")
+                return entry
+                
+        except Exception as e:
+            logger.error(f"Failed to append event: {e}")
+            raise ValueError(f"Failed to append event: {e}")
+    
+    def _should_seal_block(self) -> bool:
+        """Check if current block should be sealed."""
+        return (self._current_block and 
+                self._current_block.entry_count >= self._block_size)
+    
+    def _create_new_block(self, session) -> LedgerBlock:
+        """Create a new block."""
+        block_number = self._get_next_block_number()
+        block = LedgerBlock(
+            block_number=block_number,
+            entry_count=0,
+            first_entry_sequence=self._current_sequence,
+            last_entry_sequence=self._current_sequence - 1,
+            merkle_root="",  # Will be set when sealed
+            merkle_tree_data="[]"
+        )
+        session.add(block)
+        session.commit()
+        session.refresh(block)
+        return block
+    
+    def _seal_block(self, session):
+        """Seal the current block with Merkle tree."""
+        if not self._current_block:
+            return
+        
+        from sqlmodel import select
+        
+        # Get all entries in this block
+        entries = session.exec(
+            select(LedgerEntry).where(
+                LedgerEntry.block_id == self._current_block.id
+            ).order_by(LedgerEntry.sequence_number)
+        ).all()
+        
+        if not entries:
+            return
+        
+        # Create Merkle tree
+        from .merkle import MerkleTree
+        entry_hashes = [entry.entry_hash for entry in entries]
+        merkle_tree = MerkleTree(entry_hashes)
+        
+        # Update block with Merkle root
+        self._current_block.merkle_root = merkle_tree.get_root()
+        self._current_block.merkle_tree_data = json.dumps(merkle_tree.get_tree_data())
+        self._current_block.sealed_at = datetime.utcnow()
+        self._current_block.is_verified = True
+        self._current_block.verification_timestamp = datetime.utcnow()
+        
+        session.add(self._current_block)
+        session.commit()
+        
+        logger.info(f"Sealed block {self._current_block.block_number} with {len(entries)} entries")
+        self._current_block = None
+
+    def seal_current_block(self) -> bool:
+        """Manually seal the current block if it exists.
+        
+        Returns:
+            True if block was sealed, False if no current block
+        """
+        if not self._current_block:
+            return False
+        
+        try:
+            from sqlmodel import Session
+            
+            with Session(self.engine) as session:
+                self._seal_block(session)
+            return True
+        except Exception as e:
+            logger.error(f"Failed to seal current block: {e}")
+            return False
+    
+    def get_entry(self, sequence_number: int) -> Optional[LedgerEntry]:
+        """Get a ledger entry by sequence number.
+        
+        Args:
+            sequence_number: The sequence number of the entry
+            
+        Returns:
+            The ledger entry or None if not found
+        """
+        from sqlmodel import Session, select
+        
+        with Session(self.engine) as session:
+            return session.exec(
+                select(LedgerEntry).where(
+                    LedgerEntry.sequence_number == sequence_number
+                )
+            ).first()
+    
+    def get_block(self, block_number: int) -> Optional[LedgerBlock]:
+        """Get a ledger block by block number.
+        
+        Args:
+            block_number: The block number
+            
+        Returns:
+            The ledger block or None if not found
+        """
+        from sqlmodel import Session, select
+        
+        with Session(self.engine) as session:
+            return session.exec(
+                select(LedgerBlock).where(
+                    LedgerBlock.block_number == block_number
+                )
+            ).first()
+    
+    def get_block_entries(self, block_number: int) -> List[LedgerEntry]:
+        """Get all entries in a block.
+        
+        Args:
+            block_number: The block number
+            
+        Returns:
+            List of ledger entries in the block
+        """
+        from sqlmodel import Session, select
+        
+        with Session(self.engine) as session:
+            block = self.get_block(block_number)
+            if not block:
+                return []
+            
+            return session.exec(
+                select(LedgerEntry).where(
+                    LedgerEntry.block_id == block.id
+                ).order_by(LedgerEntry.sequence_number)
+            ).all()
+    
+    def verify_block_integrity(self, block_number: int) -> bool:
+        """Verify the integrity of a block and its entries.
+        
+        Args:
+            block_number: The block number to verify
+            
+        Returns:
+            True if block is valid, False otherwise
+        """
+        try:
+            block = self.get_block(block_number)
+            if not block:
+                return False
+            
+            entries = self.get_block_entries(block_number)
+            if not entries:
+                return False
+            
+            # Verify each entry
+            for entry in entries:
+                if not entry.verify_integrity():
+                    logger.warning(f"Entry {entry.sequence_number} failed integrity check")
+                    return False
+            
+            # Verify block Merkle root
+            if not block.verify_integrity(entries):
+                logger.warning(f"Block {block_number} failed Merkle root verification")
+                return False
+            
+            return True
+            
+        except Exception as e:
+            logger.error(f"Failed to verify block {block_number}: {e}")
+            return False
+    
+    def verify_chain_integrity(self, start_sequence: int = 1, end_sequence: Optional[int] = None) -> bool:
+        """Verify the integrity of the entire chain or a range of entries.
+        
+        Args:
+            start_sequence: Starting sequence number (default: 1)
+            end_sequence: Ending sequence number (default: None for all)
+            
+        Returns:
+            True if chain is valid, False otherwise
+        """
+        try:
+            from sqlmodel import Session, select
+            
+            with Session(self.engine) as session:
+                query = select(LedgerEntry).where(
+                    LedgerEntry.sequence_number >= start_sequence
+                ).order_by(LedgerEntry.sequence_number)
+                
+                if end_sequence:
+                    query = query.where(LedgerEntry.sequence_number <= end_sequence)
+                
+                entries = session.exec(query).all()
+                
+                if not entries:
+                    return True
+                
+                # Verify each entry and hash chain
+                previous_hash = None
+                for entry in entries:
+                    # Verify entry integrity
+                    if not entry.verify_integrity():
+                        logger.warning(f"Entry {entry.sequence_number} failed integrity check")
+                        return False
+                    
+                    # Verify hash chain
+                    if previous_hash and entry.previous_hash != previous_hash:
+                        logger.warning(f"Hash chain broken at entry {entry.sequence_number}")
+                        return False
+                    
+                    previous_hash = entry.entry_hash
+                
+                return True
+                
+        except Exception as e:
+            logger.error(f"Failed to verify chain integrity: {e}")
+            return False
+    
+    def get_ledger_statistics(self) -> Dict[str, Any]:
+        """Get statistics about the ledger.
+        
+        Returns:
+            Dictionary with ledger statistics
+        """
+        from sqlmodel import Session, select, func
+        
+        with Session(self.engine) as session:
+            total_entries = session.exec(select(func.count(LedgerEntry.id))).first() or 0
+            total_blocks = session.exec(select(func.count(LedgerBlock.id))).first() or 0
+            sealed_blocks = session.exec(
+                select(func.count(LedgerBlock.id)).where(
+                    LedgerBlock.sealed_at.isnot(None)
+                )
+            ).first() or 0
+            
+            return {
+                "total_entries": total_entries,
+                "total_blocks": total_blocks,
+                "sealed_blocks": sealed_blocks,
+                "unsealed_blocks": total_blocks - sealed_blocks,
+                "current_sequence": self._current_sequence - 1,
+                "block_size": self._block_size
+            }

src/fastmcp/ledger/merkle.py

@@ -0,0 +1,244 @@
+"""Merkle tree implementation for ledger integrity verification."""
+
+import hashlib
+from typing import List, Dict, Any, Optional
+
+
+class MerkleProof:
+    """A Merkle proof for verifying an entry's inclusion in a Merkle tree."""
+    
+    def __init__(self, leaf_hash: str, path: List[Dict[str, str]], root_hash: str):
+        """Initialize a Merkle proof.
+        
+        Args:
+            leaf_hash: Hash of the leaf node being proven
+            path: List of path elements with 'hash' and 'position' ('left' or 'right')
+            root_hash: The root hash of the Merkle tree
+        """
+        self.leaf_hash = leaf_hash
+        self.path = path
+        self.root_hash = root_hash
+    
+    def verify(self) -> bool:
+        """Verify that this proof is valid.
+        
+        Returns:
+            True if the proof is valid, False otherwise
+        """
+        current_hash = self.leaf_hash
+        
+        for path_element in self.path:
+            sibling_hash = path_element['hash']
+            position = path_element['position']
+            
+            if position == 'left':
+                # Current hash is on the right, sibling on the left
+                combined = sibling_hash + current_hash
+            else:  # position == 'right'
+                # Current hash is on the left, sibling on the right
+                combined = current_hash + sibling_hash
+            
+            current_hash = hashlib.sha256(combined.encode()).hexdigest()
+        
+        return current_hash == self.root_hash
+
+
+class MerkleTree:
+    """A Merkle tree for efficient integrity verification of multiple entries."""
+    
+    def __init__(self, leaf_hashes: List[str]):
+        """Initialize a Merkle tree from a list of leaf hashes.
+        
+        Args:
+            leaf_hashes: List of SHA-256 hashes of the leaf nodes
+        """
+        if not leaf_hashes:
+            raise ValueError("Cannot create Merkle tree with empty leaf list")
+        
+        self.leaf_hashes = leaf_hashes.copy()
+        self.tree_data = []
+        self.root_hash = self._build_tree()
+    
+    def _build_tree(self) -> str:
+        """Build the Merkle tree and return the root hash.
+        
+        Returns:
+            The root hash of the Merkle tree
+        """
+        if len(self.leaf_hashes) == 1:
+            return self.leaf_hashes[0]
+        
+        # Ensure we have an even number of leaves by duplicating the last one if necessary
+        current_level = self.leaf_hashes.copy()
+        tree_levels = [current_level.copy()]
+        
+        while len(current_level) > 1:
+            next_level = []
+            
+            # Process pairs of nodes
+            for i in range(0, len(current_level), 2):
+                left_hash = current_level[i]
+                right_hash = current_level[i + 1] if i + 1 < len(current_level) else current_level[i]
+                
+                # Combine and hash
+                combined = left_hash + right_hash
+                parent_hash = hashlib.sha256(combined.encode()).hexdigest()
+                next_level.append(parent_hash)
+            
+            tree_levels.append(next_level.copy())
+            current_level = next_level
+        
+        # Store tree data for proof generation
+        self.tree_data = tree_levels
+        return current_level[0]
+    
+    def get_root(self) -> str:
+        """Get the root hash of the Merkle tree.
+        
+        Returns:
+            The root hash
+        """
+        return self.root_hash
+    
+    def get_tree_data(self) -> List[List[str]]:
+        """Get the complete tree data structure.
+        
+        Returns:
+            List of levels, where each level is a list of hashes
+        """
+        return self.tree_data
+    
+    def generate_proof(self, leaf_hash: str) -> Optional[MerkleProof]:
+        """Generate a Merkle proof for a specific leaf hash.
+        
+        Args:
+            leaf_hash: The hash of the leaf to prove
+            
+        Returns:
+            A MerkleProof object or None if the leaf is not found
+        """
+        try:
+            leaf_index = self.leaf_hashes.index(leaf_hash)
+        except ValueError:
+            return None
+        
+        if len(self.leaf_hashes) == 1:
+            # Single leaf case
+            return MerkleProof(leaf_hash, [], self.root_hash)
+        
+        path = []
+        current_index = leaf_index
+        
+        # Traverse up the tree
+        for level in range(len(self.tree_data) - 1):
+            current_level = self.tree_data[level]
+            
+            # Find sibling
+            if current_index % 2 == 0:  # Even index, sibling is on the right
+                sibling_index = current_index + 1
+                position = 'right'
+            else:  # Odd index, sibling is on the left
+                sibling_index = current_index - 1
+                position = 'left'
+            
+            # Add sibling to path if it exists
+            if sibling_index < len(current_level):
+                path.append({
+                    'hash': current_level[sibling_index],
+                    'position': position
+                })
+            
+            # Move to parent level
+            current_index = current_index // 2
+        
+        return MerkleProof(leaf_hash, path, self.root_hash)
+    
+    def verify_proof(self, proof: MerkleProof) -> bool:
+        """Verify a Merkle proof.
+        
+        Args:
+            proof: The MerkleProof to verify
+            
+        Returns:
+            True if the proof is valid, False otherwise
+        """
+        return proof.verify()
+    
+    def verify_leaf(self, leaf_hash: str) -> bool:
+        """Verify that a leaf hash is part of this Merkle tree.
+        
+        Args:
+            leaf_hash: The leaf hash to verify
+            
+        Returns:
+            True if the leaf is part of the tree, False otherwise
+        """
+        return leaf_hash in self.leaf_hashes
+    
+    def get_leaf_count(self) -> int:
+        """Get the number of leaf nodes in the tree.
+        
+        Returns:
+            The number of leaf nodes
+        """
+        return len(self.leaf_hashes)
+    
+    def get_leaf_hashes(self) -> List[str]:
+        """Get the list of leaf hashes.
+        
+        Returns:
+            List of leaf hashes
+        """
+        return self.leaf_hashes.copy()
+    
+    def get_tree_height(self) -> int:
+        """Get the height of the Merkle tree.
+        
+        Returns:
+            The height of the tree (number of levels)
+        """
+        return len(self.tree_data) if self.tree_data else 1
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert the Merkle tree to a dictionary representation.
+        
+        Returns:
+            Dictionary representation of the tree
+        """
+        return {
+            "root_hash": self.root_hash,
+            "leaf_count": self.get_leaf_count(),
+            "tree_height": self.get_tree_height(),
+            "tree_data": self.tree_data,
+            "leaf_hashes": self.leaf_hashes
+        }
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "MerkleTree":
+        """Create a MerkleTree from a dictionary representation.
+        
+        Args:
+            data: Dictionary representation of the tree
+            
+        Returns:
+            A MerkleTree instance
+        """
+        tree = cls(data["leaf_hashes"])
+        tree.tree_data = data["tree_data"]
+        tree.root_hash = data["root_hash"]
+        return tree
+
+
+def verify_merkle_proof(leaf_hash: str, proof_path: List[Dict[str, str]], root_hash: str) -> bool:
+    """Verify a Merkle proof without creating a MerkleTree instance.
+    
+    Args:
+        leaf_hash: Hash of the leaf being proven
+        proof_path: List of path elements with 'hash' and 'position'
+        root_hash: The expected root hash
+        
+    Returns:
+        True if the proof is valid, False otherwise
+    """
+    proof = MerkleProof(leaf_hash, proof_path, root_hash)
+    return proof.verify()

src/fastmcp/server/contract_routes.py

@@ -0,0 +1,425 @@
+"""Contract management HTTP routes."""
+
+from typing import Any, Dict, List, Optional
+from uuid import UUID
+
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+from starlette.routing import Route
+
+from fastmcp.contracts import ContractEngine, ContractState
+from fastmcp.contracts.contract import (
+    ContractCreateRequest, ContractProposeRequest, ContractSignRequest, 
+    ContractRevokeRequest, ContractResponse
+)
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+async def create_contract_endpoint(request: Request) -> JSONResponse:
+    """HTTP endpoint for creating contracts.
+    
+    Expected JSON body:
+    {
+        "title": "Contract Title",
+        "description": "Contract Description",
+        "clauses": [...],
+        "parties": [...],
+        "is_hipaa_compliant": false,
+        "expires_at": "2024-12-31T23:59:59Z"
+    }
+    """
+    try:
+        # Parse request body
+        body = await request.json()
+        
+        # Get contract engine from request state
+        contract_engine: ContractEngine = request.app.state.contract_engine
+        
+        # Get creator from headers or body
+        created_by = request.headers.get("X-User-ID") or body.get("created_by", "anonymous")
+        
+        # Create contract request
+        contract_request = ContractCreateRequest(**body)
+        
+        # Create contract
+        contract = await contract_engine.create_contract(contract_request, created_by)
+        
+        # Return contract response
+        response = ContractResponse.from_contract(contract)
+        return JSONResponse(
+            status_code=201,
+            content=response.model_dump()
+        )
+        
+    except Exception as e:
+        logger.error(f"Contract creation error: {e}")
+        return JSONResponse(
+            status_code=400,
+            content={
+                "error": "Contract creation failed",
+                "reason": str(e)
+            }
+        )
+
+
+async def get_contract_endpoint(request: Request) -> JSONResponse:
+    """HTTP endpoint for getting a contract by ID."""
+    try:
+        # Get contract ID from path
+        contract_id = UUID(request.path_params["id"])
+        
+        # Get contract engine from request state
+        contract_engine: ContractEngine = request.app.state.contract_engine
+        
+        # Get contract
+        contract = await contract_engine.get_contract(contract_id)
+        
+        if not contract:
+            return JSONResponse(
+                status_code=404,
+                content={
+                    "error": "Contract not found",
+                    "contract_id": str(contract_id)
+                }
+            )
+        
+        # Return contract response
+        response = ContractResponse.from_contract(contract)
+        return JSONResponse(
+            status_code=200,
+            content=response.model_dump()
+        )
+        
+    except ValueError as e:
+        return JSONResponse(
+            status_code=400,
+            content={
+                "error": "Invalid contract ID",
+                "reason": str(e)
+            }
+        )
+    except Exception as e:
+        logger.error(f"Contract retrieval error: {e}")
+        return JSONResponse(
+            status_code=500,
+            content={
+                "error": "Contract retrieval failed",
+                "reason": str(e)
+            }
+        )
+
+
+async def list_contracts_endpoint(request: Request) -> JSONResponse:
+    """HTTP endpoint for listing contracts."""
+    try:
+        # Get query parameters
+        state = request.query_params.get("state")
+        created_by = request.query_params.get("created_by")
+        
+        # Get contract engine from request state
+        contract_engine: ContractEngine = request.app.state.contract_engine
+        
+        # Parse state if provided
+        contract_state = None
+        if state:
+            try:
+                contract_state = ContractState(state)
+            except ValueError:
+                return JSONResponse(
+                    status_code=400,
+                    content={
+                        "error": "Invalid state",
+                        "valid_states": [s.value for s in ContractState]
+                    }
+                )
+        
+        # List contracts
+        contracts = await contract_engine.list_contracts(contract_state, created_by)
+        
+        # Convert to response format
+        responses = [ContractResponse.from_contract(contract).model_dump() for contract in contracts]
+        
+        return JSONResponse(
+            status_code=200,
+            content={
+                "contracts": responses,
+                "count": len(responses)
+            }
+        )
+        
+    except Exception as e:
+        logger.error(f"Contract listing error: {e}")
+        return JSONResponse(
+            status_code=500,
+            content={
+                "error": "Contract listing failed",
+                "reason": str(e)
+            }
+        )
+
+
+async def propose_contract_endpoint(request: Request) -> JSONResponse:
+    """HTTP endpoint for proposing contracts.
+    
+    Expected JSON body:
+    {
+        "proposed_to": ["party1", "party2"],
+        "message": "Please review and sign this contract"
+    }
+    """
+    try:
+        # Get contract ID from path
+        contract_id = UUID(request.path_params["id"])
+        
+        # Parse request body
+        body = await request.json()
+        
+        # Get contract engine from request state
+        contract_engine: ContractEngine = request.app.state.contract_engine
+        
+        # Get proposer from headers or body
+        proposed_by = request.headers.get("X-User-ID") or body.get("proposed_by", "anonymous")
+        
+        # Create proposal request
+        proposal_request = ContractProposeRequest(**body)
+        
+        # Propose contract
+        contract = await contract_engine.propose_contract(contract_id, proposal_request, proposed_by)
+        
+        if not contract:
+            return JSONResponse(
+                status_code=404,
+                content={
+                    "error": "Contract not found",
+                    "contract_id": str(contract_id)
+                }
+            )
+        
+        # Return contract response
+        response = ContractResponse.from_contract(contract)
+        return JSONResponse(
+            status_code=200,
+            content=response.model_dump()
+        )
+        
+    except ValueError as e:
+        return JSONResponse(
+            status_code=400,
+            content={
+                "error": "Invalid request",
+                "reason": str(e)
+            }
+        )
+    except Exception as e:
+        logger.error(f"Contract proposal error: {e}")
+        return JSONResponse(
+            status_code=500,
+            content={
+                "error": "Contract proposal failed",
+                "reason": str(e)
+            }
+        )
+
+
+async def sign_contract_endpoint(request: Request) -> JSONResponse:
+    """HTTP endpoint for signing contracts.
+    
+    Expected JSON body:
+    {
+        "signer_id": "party1",
+        "signer_type": "provider",
+        "public_key": "base64_public_key",
+        "signature": "base64_signature"
+    }
+    """
+    try:
+        # Get contract ID from path
+        contract_id = UUID(request.path_params["id"])
+        
+        # Parse request body
+        body = await request.json()
+        
+        # Get contract engine from request state
+        contract_engine: ContractEngine = request.app.state.contract_engine
+        
+        # Create signing request
+        sign_request = ContractSignRequest(**body)
+        
+        # Sign contract
+        contract = await contract_engine.sign_contract(contract_id, sign_request)
+        
+        if not contract:
+            return JSONResponse(
+                status_code=404,
+                content={
+                    "error": "Contract not found",
+                    "contract_id": str(contract_id)
+                }
+            )
+        
+        # Return contract response
+        response = ContractResponse.from_contract(contract)
+        return JSONResponse(
+            status_code=200,
+            content=response.model_dump()
+        )
+        
+    except ValueError as e:
+        return JSONResponse(
+            status_code=400,
+            content={
+                "error": "Invalid request",
+                "reason": str(e)
+            }
+        )
+    except Exception as e:
+        logger.error(f"Contract signing error: {e}")
+        return JSONResponse(
+            status_code=500,
+            content={
+                "error": "Contract signing failed",
+                "reason": str(e)
+            }
+        )
+
+
+async def revoke_contract_endpoint(request: Request) -> JSONResponse:
+    """HTTP endpoint for revoking contracts.
+    
+    Expected JSON body:
+    {
+        "reason": "Contract terms violated",
+        "revoked_by": "party1"
+    }
+    """
+    try:
+        # Get contract ID from path
+        contract_id = UUID(request.path_params["id"])
+        
+        # Parse request body
+        body = await request.json()
+        
+        # Get contract engine from request state
+        contract_engine: ContractEngine = request.app.state.contract_engine
+        
+        # Create revocation request
+        revoke_request = ContractRevokeRequest(**body)
+        
+        # Revoke contract
+        contract = await contract_engine.revoke_contract(contract_id, revoke_request)
+        
+        if not contract:
+            return JSONResponse(
+                status_code=404,
+                content={
+                    "error": "Contract not found",
+                    "contract_id": str(contract_id)
+                }
+            )
+        
+        # Return contract response
+        response = ContractResponse.from_contract(contract)
+        return JSONResponse(
+            status_code=200,
+            content=response.model_dump()
+        )
+        
+    except ValueError as e:
+        return JSONResponse(
+            status_code=400,
+            content={
+                "error": "Invalid request",
+                "reason": str(e)
+            }
+        )
+    except Exception as e:
+        logger.error(f"Contract revocation error: {e}")
+        return JSONResponse(
+            status_code=500,
+            content={
+                "error": "Contract revocation failed",
+                "reason": str(e)
+            }
+        )
+
+
+async def get_contract_statistics_endpoint(request: Request) -> JSONResponse:
+    """HTTP endpoint for getting contract statistics."""
+    try:
+        # Get contract engine from request state
+        contract_engine: ContractEngine = request.app.state.contract_engine
+        
+        # Get statistics
+        stats = await contract_engine.get_contract_statistics()
+        
+        return JSONResponse(
+            status_code=200,
+            content=stats
+        )
+        
+    except Exception as e:
+        logger.error(f"Contract statistics error: {e}")
+        return JSONResponse(
+            status_code=500,
+            content={
+                "error": "Contract statistics failed",
+                "reason": str(e)
+            }
+        )
+
+
+def create_contract_routes(contract_engine: ContractEngine) -> List[Route]:
+    """Create contract management routes.
+    
+    Args:
+        contract_engine: The contract engine instance
+        
+    Returns:
+        List of Starlette Route objects for contract management
+    """
+    def endpoint_with_engine(endpoint_func):
+        async def wrapper(request: Request) -> JSONResponse:
+            # Store contract engine in app state for access in endpoint
+            request.app.state.contract_engine = contract_engine
+            return await endpoint_func(request)
+        return wrapper
+    
+    return [
+        Route(
+            path="/contracts",
+            endpoint=endpoint_with_engine(create_contract_endpoint),
+            methods=["POST"]
+        ),
+        Route(
+            path="/contracts",
+            endpoint=endpoint_with_engine(list_contracts_endpoint),
+            methods=["GET"]
+        ),
+        Route(
+            path="/contracts/statistics",
+            endpoint=endpoint_with_engine(get_contract_statistics_endpoint),
+            methods=["GET"]
+        ),
+        Route(
+            path="/contracts/{id}",
+            endpoint=endpoint_with_engine(get_contract_endpoint),
+            methods=["GET"]
+        ),
+        Route(
+            path="/contracts/{id}/propose",
+            endpoint=endpoint_with_engine(propose_contract_endpoint),
+            methods=["POST"]
+        ),
+        Route(
+            path="/contracts/{id}/sign",
+            endpoint=endpoint_with_engine(sign_contract_endpoint),
+            methods=["POST"]
+        ),
+        Route(
+            path="/contracts/{id}/revoke",
+            endpoint=endpoint_with_engine(revoke_contract_endpoint),
+            methods=["POST"]
+        )
+    ]

src/fastmcp/server/ledger_routes.py

@@ -0,0 +1,498 @@
+"""Ledger management HTTP routes."""
+
+from typing import Any, Dict, List, Optional
+from uuid import UUID
+
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+from starlette.routing import Route
+
+from fastmcp.ledger import ProvenanceLedger, LedgerEvent, EventType, MerkleProof, LedgerBlock
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+async def append_event_endpoint(request: Request) -> JSONResponse:
+    """HTTP endpoint for appending events to the ledger.
+    
+    Expected JSON body:
+    {
+        "event_type": "tool_call",
+        "actor_id": "user123",
+        "resource_id": "resource456",
+        "action": "execute_tool",
+        "metadata": {...},
+        "data_hash": "sha256_hash_of_data"
+    }
+    """
+    try:
+        # Parse request body
+        body = await request.json()
+        
+        # Get ledger from request state
+        ledger: ProvenanceLedger = request.app.state.ledger
+        
+        # Create ledger event
+        event = LedgerEvent(**body)
+        
+        # Append to ledger
+        entry = ledger.append_event(event)
+        
+        return JSONResponse(
+            status_code=201,
+            content={
+                "entry_id": str(entry.id),
+                "sequence_number": entry.sequence_number,
+                "entry_hash": entry.entry_hash,
+                "block_id": str(entry.block_id) if entry.block_id else None,
+                "created_at": entry.created_at.isoformat()
+            }
+        )
+        
+    except ValueError as e:
+        logger.error(f"Invalid event data: {e}")
+        return JSONResponse(
+            status_code=400,
+            content={
+                "error": "Invalid event data",
+                "reason": str(e)
+            }
+        )
+    except Exception as e:
+        logger.error(f"Failed to append event: {e}")
+        return JSONResponse(
+            status_code=500,
+            content={
+                "error": "Failed to append event",
+                "reason": str(e)
+            }
+        )
+
+
+async def verify_block_endpoint(request: Request) -> JSONResponse:
+    """HTTP endpoint for verifying block integrity.
+    
+    Path parameter: block_number (int)
+    """
+    try:
+        # Get block number from path
+        block_number = int(request.path_params["block"])
+        
+        # Get ledger from request state
+        ledger: ProvenanceLedger = request.app.state.ledger
+        
+        # Verify block integrity
+        is_valid = ledger.verify_block_integrity(block_number)
+        
+        if not is_valid:
+            return JSONResponse(
+                status_code=400,
+                content={
+                    "block_number": block_number,
+                    "verified": False,
+                    "error": "Block integrity verification failed"
+                }
+            )
+        
+        # Get block details
+        block = ledger.get_block(block_number)
+        entries = ledger.get_block_entries(block_number)
+        
+        return JSONResponse(
+            status_code=200,
+            content={
+                "block_number": block_number,
+                "verified": True,
+                "block_id": str(block.id) if block else None,
+                "entry_count": len(entries),
+                "merkle_root": block.merkle_root if block else None,
+                "sealed_at": block.sealed_at.isoformat() if block and block.sealed_at else None,
+                "verification_timestamp": block.verification_timestamp.isoformat() if block and block.verification_timestamp else None
+            }
+        )
+        
+    except ValueError as e:
+        return JSONResponse(
+            status_code=400,
+            content={
+                "error": "Invalid block number",
+                "reason": str(e)
+            }
+        )
+    except Exception as e:
+        logger.error(f"Failed to verify block: {e}")
+        return JSONResponse(
+            status_code=500,
+            content={
+                "error": "Failed to verify block",
+                "reason": str(e)
+            }
+        )
+
+
+async def get_entry_endpoint(request: Request) -> JSONResponse:
+    """HTTP endpoint for getting a ledger entry by sequence number.
+    
+    Path parameter: sequence_number (int)
+    """
+    try:
+        # Get sequence number from path
+        sequence_number = int(request.path_params["sequence"])
+        
+        # Get ledger from request state
+        ledger: ProvenanceLedger = request.app.state.ledger
+        
+        # Get entry
+        entry = ledger.get_entry(sequence_number)
+        
+        if not entry:
+            return JSONResponse(
+                status_code=404,
+                content={
+                    "error": "Entry not found",
+                    "sequence_number": sequence_number
+                }
+            )
+        
+        # Get event data
+        event = entry.get_event()
+        
+        return JSONResponse(
+            status_code=200,
+            content={
+                "entry_id": str(entry.id),
+                "sequence_number": entry.sequence_number,
+                "entry_hash": entry.entry_hash,
+                "previous_hash": entry.previous_hash,
+                "block_id": str(entry.block_id) if entry.block_id else None,
+                "created_at": entry.created_at.isoformat(),
+                "is_verified": entry.is_verified,
+                "event": {
+                    "event_type": event.event_type,
+                    "actor_id": event.actor_id,
+                    "resource_id": event.resource_id,
+                    "action": event.action,
+                    "metadata": event.metadata,
+                    "timestamp": event.timestamp.isoformat(),
+                    "data_hash": event.data_hash
+                }
+            }
+        )
+        
+    except ValueError as e:
+        return JSONResponse(
+            status_code=400,
+            content={
+                "error": "Invalid sequence number",
+                "reason": str(e)
+            }
+        )
+    except Exception as e:
+        logger.error(f"Failed to get entry: {e}")
+        return JSONResponse(
+            status_code=500,
+            content={
+                "error": "Failed to get entry",
+                "reason": str(e)
+            }
+        )
+
+
+async def get_block_endpoint(request: Request) -> JSONResponse:
+    """HTTP endpoint for getting a ledger block by block number.
+    
+    Path parameter: block_number (int)
+    """
+    try:
+        # Get block number from path
+        block_number = int(request.path_params["block"])
+        
+        # Get ledger from request state
+        ledger: ProvenanceLedger = request.app.state.ledger
+        
+        # Get block
+        block = ledger.get_block(block_number)
+        
+        if not block:
+            return JSONResponse(
+                status_code=404,
+                content={
+                    "error": "Block not found",
+                    "block_number": block_number
+                }
+            )
+        
+        # Get entries in block
+        entries = ledger.get_block_entries(block_number)
+        
+        return JSONResponse(
+            status_code=200,
+            content={
+                "block_id": str(block.id),
+                "block_number": block.block_number,
+                "entry_count": block.entry_count,
+                "first_entry_sequence": block.first_entry_sequence,
+                "last_entry_sequence": block.last_entry_sequence,
+                "merkle_root": block.merkle_root,
+                "created_at": block.created_at.isoformat(),
+                "sealed_at": block.sealed_at.isoformat() if block.sealed_at else None,
+                "is_verified": block.is_verified,
+                "verification_timestamp": block.verification_timestamp.isoformat() if block.verification_timestamp else None,
+                "entries": [
+                    {
+                        "entry_id": str(entry.id),
+                        "sequence_number": entry.sequence_number,
+                        "entry_hash": entry.entry_hash,
+                        "created_at": entry.created_at.isoformat()
+                    }
+                    for entry in entries
+                ]
+            }
+        )
+        
+    except ValueError as e:
+        return JSONResponse(
+            status_code=400,
+            content={
+                "error": "Invalid block number",
+                "reason": str(e)
+            }
+        )
+    except Exception as e:
+        logger.error(f"Failed to get block: {e}")
+        return JSONResponse(
+            status_code=500,
+            content={
+                "error": "Failed to get block",
+                "reason": str(e)
+            }
+        )
+
+
+async def verify_chain_endpoint(request: Request) -> JSONResponse:
+    """HTTP endpoint for verifying chain integrity.
+    
+    Query parameters:
+    - start_sequence (int, optional): Starting sequence number (default: 1)
+    - end_sequence (int, optional): Ending sequence number (default: None)
+    """
+    try:
+        # Get query parameters
+        start_sequence = int(request.query_params.get("start_sequence", 1))
+        end_sequence = request.query_params.get("end_sequence")
+        if end_sequence:
+            end_sequence = int(end_sequence)
+        
+        # Get ledger from request state
+        ledger: ProvenanceLedger = request.app.state.ledger
+        
+        # Verify chain integrity
+        is_valid = ledger.verify_chain_integrity(start_sequence, end_sequence)
+        
+        return JSONResponse(
+            status_code=200,
+            content={
+                "verified": is_valid,
+                "start_sequence": start_sequence,
+                "end_sequence": end_sequence,
+                "verification_timestamp": ledger._get_next_sequence_number() - 1
+            }
+        )
+        
+    except ValueError as e:
+        return JSONResponse(
+            status_code=400,
+            content={
+                "error": "Invalid sequence parameters",
+                "reason": str(e)
+            }
+        )
+    except Exception as e:
+        logger.error(f"Failed to verify chain: {e}")
+        return JSONResponse(
+            status_code=500,
+            content={
+                "error": "Failed to verify chain",
+                "reason": str(e)
+            }
+        )
+
+
+async def get_merkle_proof_endpoint(request: Request) -> JSONResponse:
+    """HTTP endpoint for getting a Merkle proof for an entry.
+    
+    Path parameter: sequence_number (int)
+    """
+    try:
+        # Get sequence number from path
+        sequence_number = int(request.path_params["sequence"])
+        
+        # Get ledger from request state
+        ledger: ProvenanceLedger = request.app.state.ledger
+        
+        # Get entry
+        entry = ledger.get_entry(sequence_number)
+        
+        if not entry:
+            return JSONResponse(
+                status_code=404,
+                content={
+                    "error": "Entry not found",
+                    "sequence_number": sequence_number
+                }
+            )
+        
+        # Get block - we need to find the block number from the entry
+        block = None
+        if entry.block_id:
+            # Find the block by querying for the block that contains this entry
+            from sqlmodel import Session, select
+            with Session(ledger.engine) as session:
+                block_query = session.exec(
+                    select(LedgerBlock).where(LedgerBlock.id == entry.block_id)
+                ).first()
+                if block_query:
+                    block = ledger.get_block(block_query.block_number)
+        
+        if not block:
+            return JSONResponse(
+                status_code=404,
+                content={
+                    "error": "Block not found for entry",
+                    "sequence_number": sequence_number
+                }
+            )
+        
+        # Get all entries in block
+        entries = ledger.get_block_entries(block.block_number)
+        
+        # Create Merkle tree and generate proof
+        from fastmcp.ledger.merkle import MerkleTree
+        entry_hashes = [e.entry_hash for e in entries]
+        merkle_tree = MerkleTree(entry_hashes)
+        
+        proof = merkle_tree.generate_proof(entry.entry_hash)
+        
+        if not proof:
+            return JSONResponse(
+                status_code=500,
+                content={
+                    "error": "Failed to generate Merkle proof",
+                    "sequence_number": sequence_number
+                }
+            )
+        
+        return JSONResponse(
+            status_code=200,
+            content={
+                "sequence_number": sequence_number,
+                "entry_hash": entry.entry_hash,
+                "block_number": block.block_number,
+                "merkle_root": block.merkle_root,
+                "proof": {
+                    "leaf_hash": proof.leaf_hash,
+                    "path": proof.path,
+                    "root_hash": proof.root_hash
+                },
+                "verified": proof.verify()
+            }
+        )
+        
+    except ValueError as e:
+        return JSONResponse(
+            status_code=400,
+            content={
+                "error": "Invalid sequence number",
+                "reason": str(e)
+            }
+        )
+    except Exception as e:
+        logger.error(f"Failed to get Merkle proof: {e}")
+        return JSONResponse(
+            status_code=500,
+            content={
+                "error": "Failed to get Merkle proof",
+                "reason": str(e)
+            }
+        )
+
+
+async def get_ledger_statistics_endpoint(request: Request) -> JSONResponse:
+    """HTTP endpoint for getting ledger statistics."""
+    try:
+        # Get ledger from request state
+        ledger: ProvenanceLedger = request.app.state.ledger
+        
+        # Get statistics
+        stats = ledger.get_ledger_statistics()
+        
+        return JSONResponse(
+            status_code=200,
+            content=stats
+        )
+        
+    except Exception as e:
+        logger.error(f"Failed to get ledger statistics: {e}")
+        return JSONResponse(
+            status_code=500,
+            content={
+                "error": "Failed to get ledger statistics",
+                "reason": str(e)
+            }
+        )
+
+
+def create_ledger_routes(ledger: ProvenanceLedger) -> List[Route]:
+    """Create ledger management routes.
+    
+    Args:
+        ledger: The provenance ledger instance
+        
+    Returns:
+        List of Starlette Route objects for ledger management
+    """
+    def endpoint_with_ledger(endpoint_func):
+        async def wrapper(request: Request) -> JSONResponse:
+            # Store ledger in app state for access in endpoint
+            request.app.state.ledger = ledger
+            return await endpoint_func(request)
+        return wrapper
+    
+    return [
+        Route(
+            path="/ledger/events",
+            endpoint=endpoint_with_ledger(append_event_endpoint),
+            methods=["POST"]
+        ),
+        Route(
+            path="/ledger/verify/{block}",
+            endpoint=endpoint_with_ledger(verify_block_endpoint),
+            methods=["GET"]
+        ),
+        Route(
+            path="/ledger/entries/{sequence}",
+            endpoint=endpoint_with_ledger(get_entry_endpoint),
+            methods=["GET"]
+        ),
+        Route(
+            path="/ledger/blocks/{block}",
+            endpoint=endpoint_with_ledger(get_block_endpoint),
+            methods=["GET"]
+        ),
+        Route(
+            path="/ledger/verify-chain",
+            endpoint=endpoint_with_ledger(verify_chain_endpoint),
+            methods=["GET"]
+        ),
+        Route(
+            path="/ledger/proof/{sequence}",
+            endpoint=endpoint_with_ledger(get_merkle_proof_endpoint),
+            methods=["GET"]
+        ),
+        Route(
+            path="/ledger/statistics",
+            endpoint=endpoint_with_ledger(get_ledger_statistics_endpoint),
+            methods=["GET"]
+        )
+    ]

src/fastmcp/server/server.py

@@ -65,6 +65,8 @@ from fastmcp.tools.tool import FunctionTool, Tool, ToolResult
 from fastmcp.tools.tool_transform import ToolTransformConfig
 from fastmcp.policy import PolicyEngine
 from fastmcp.reflexive import ReflexiveEngine
+from fastmcp.ledger import ProvenanceLedger
+from fastmcp.contracts import ContractEngine
 from fastmcp.utilities.cli import log_server_banner
 from fastmcp.utilities.components import FastMCPComponent
 from fastmcp.utilities.logging import get_logger
@@ -178,6 +180,8 @@ class FastMCP(Generic[LifespanResultT]):
         self._mounted_servers: list[MountedServer] = []
         self._policy_engine: Optional[PolicyEngine] = None
         self._reflexive_engine: Optional[ReflexiveEngine] = None
+        self._ledger: Optional[ProvenanceLedger] = None
+        self._contract_engine: Optional[ContractEngine] = None
         self._tool_manager = ToolManager(
             duplicate_behavior=on_duplicate_tools,
             mask_error_details=mask_error_details,
@@ -516,13 +520,26 @@ class FastMCP(Generic[LifespanResultT]):
             policy_route = create_policy_evaluate_route(self._policy_engine)
             routes.append(policy_route)
 
-
         # Add reflexive core endpoints if reflexive engine is configured
         if self._reflexive_engine is not None:
             from fastmcp.server.reflexive_routes import create_reflexive_routes
             
             reflexive_routes = create_reflexive_routes(self._reflexive_engine)
             routes.extend(reflexive_routes)
+  
+        # Add ledger management endpoints if ledger is configured
+        if self._ledger is not None:
+            from fastmcp.server.ledger_routes import create_ledger_routes
+            
+            ledger_routes = create_ledger_routes(self._ledger)
+            routes.extend(ledger_routes)
+            
+        # Add contract management endpoints if contract engine is configured
+        if self._contract_engine is not None:
+            from fastmcp.server.contract_routes import create_contract_routes
+            
+            contract_routes = create_contract_routes(self._contract_engine)
+            routes.extend(contract_routes)
 
         # Recursively get routes from mounted servers
         for mounted_server in self._mounted_servers:
@@ -554,6 +571,56 @@ class FastMCP(Generic[LifespanResultT]):
             The policy engine instance, or None if not enabled
         """
         return self._policy_engine
+    
+    def enable_ledger(self, ledger: Optional[ProvenanceLedger] = None, database_url: str = "sqlite:///ledger.db") -> ProvenanceLedger:
+        """Enable the provenance ledger for this server.
+        
+        Args:
+            ledger: Optional ledger instance. If None, creates a new one.
+            database_url: Database URL for ledger persistence
+            
+        Returns:
+            The ledger instance
+        """
+        if ledger is None:
+            ledger = ProvenanceLedger(database_url)
+        
+        self._ledger = ledger
+        logger.info("Provenance ledger enabled for server")
+        return ledger
+    
+    def get_ledger(self) -> Optional[ProvenanceLedger]:
+        """Get the provenance ledger instance.
+        
+        Returns:
+            The ledger instance, or None if not enabled
+        """
+        return self._ledger
+
+    def enable_contract_engine(self, contract_engine: Optional[ContractEngine] = None, database_url: str = "sqlite:///contracts.db") -> ContractEngine:
+        """Enable the contract engine for this server.
+        
+        Args:
+            contract_engine: Optional contract engine instance. If None, creates a new one.
+            database_url: Database URL for contract persistence
+            
+        Returns:
+            The contract engine instance
+        """
+        if contract_engine is None:
+            contract_engine = ContractEngine(database_url)
+        
+        self._contract_engine = contract_engine
+        logger.info("Contract engine enabled for server")
+        return contract_engine
+    
+    def get_contract_engine(self) -> Optional[ContractEngine]:
+        """Get the contract engine instance.
+        
+        Returns:
+            The contract engine instance, or None if not enabled
+        """
+        return self._contract_engine
 
 
     def enable_reflexive_core(self, reflexive_engine: Optional[ReflexiveEngine] = None) -> ReflexiveEngine:

tests/contracts/__init__.py

@@ -0,0 +1 @@
+"""Tests for the contract management system."""

tests/contracts/test_contract_engine.py

@@ -0,0 +1,408 @@
+"""Tests for the contract engine."""
+
+import pytest
+from datetime import datetime, timedelta
+from uuid import UUID
+
+from fastmcp.contracts import ContractEngine, ContractState
+from fastmcp.contracts.contract import (
+    Contract, Clause, Signature, ContractCreateRequest, ContractProposeRequest,
+    ContractSignRequest, ContractRevokeRequest
+)
+from fastmcp.contracts.crypto import Ed25519Signer, generate_key_pair
+
+
+class TestContractEngine:
+    """Test the contract engine functionality."""
+
+    @pytest.fixture
+    def contract_engine(self):
+        """Create a contract engine for testing."""
+        return ContractEngine("sqlite:///:memory:")
+
+    @pytest.fixture
+    def sample_clauses(self):
+        """Create sample clauses for testing."""
+        return [
+            Clause(
+                title="Data Handling",
+                content="All data must be handled in accordance with HIPAA regulations.",
+                type="hipaa"
+            ),
+            Clause(
+                title="Access Control",
+                content="Only authorized personnel may access patient data.",
+                type="security"
+            )
+        ]
+
+    @pytest.fixture
+    def sample_parties(self):
+        """Create sample parties for testing."""
+        return [
+            {
+                "id": "provider1",
+                "name": "Healthcare Provider",
+                "type": "provider",
+                "email": "provider@example.com"
+            },
+            {
+                "id": "patient1",
+                "name": "John Doe",
+                "type": "patient",
+                "email": "patient@example.com"
+            }
+        ]
+
+    @pytest.fixture
+    def sample_contract_request(self, sample_clauses, sample_parties):
+        """Create a sample contract creation request."""
+        return ContractCreateRequest(
+            title="HIPAA Data Sharing Agreement",
+            description="Agreement for sharing patient data between healthcare providers",
+            clauses=sample_clauses,
+            parties=sample_parties,
+            is_hipaa_compliant=True,
+            expires_at=datetime.utcnow() + timedelta(days=365)
+        )
+
+    def test_contract_engine_initialization(self, contract_engine):
+        """Test contract engine initialization."""
+        assert contract_engine.engine is not None
+        assert contract_engine.get_registry() is not None
+
+    @pytest.mark.asyncio
+    async def test_create_contract(self, contract_engine, sample_contract_request):
+        """Test contract creation."""
+        created_by = "admin"
+        
+        contract = await contract_engine.create_contract(sample_contract_request, created_by)
+        
+        assert contract is not None
+        assert contract.title == sample_contract_request.title
+        assert contract.description == sample_contract_request.description
+        assert contract.state == ContractState.DRAFT
+        assert contract.created_by == created_by
+        assert contract.is_hipaa_compliant is True
+        assert len(contract.get_clauses()) == 2
+        assert len(contract.get_parties()) == 2
+
+    @pytest.mark.asyncio
+    async def test_get_contract(self, contract_engine, sample_contract_request):
+        """Test getting a contract by ID."""
+        created_by = "admin"
+        contract = await contract_engine.create_contract(sample_contract_request, created_by)
+        
+        retrieved_contract = await contract_engine.get_contract(contract.id)
+        
+        assert retrieved_contract is not None
+        assert retrieved_contract.id == contract.id
+        assert retrieved_contract.title == contract.title
+
+    @pytest.mark.asyncio
+    async def test_get_contract_not_found(self, contract_engine):
+        """Test getting a non-existent contract."""
+        fake_id = UUID("12345678-1234-1234-1234-123456789012")
+        contract = await contract_engine.get_contract(fake_id)
+        
+        assert contract is None
+
+    @pytest.mark.asyncio
+    async def test_list_contracts(self, contract_engine, sample_contract_request):
+        """Test listing contracts."""
+        created_by = "admin"
+        
+        # Create multiple contracts
+        contract1 = await contract_engine.create_contract(sample_contract_request, created_by)
+        contract2 = await contract_engine.create_contract(sample_contract_request, created_by)
+        
+        # List all contracts
+        all_contracts = await contract_engine.list_contracts()
+        assert len(all_contracts) == 2
+        
+        # List contracts by state
+        draft_contracts = await contract_engine.list_contracts(state=ContractState.DRAFT)
+        assert len(draft_contracts) == 2
+        
+        # List contracts by creator
+        admin_contracts = await contract_engine.list_contracts(created_by=created_by)
+        assert len(admin_contracts) == 2
+
+    @pytest.mark.asyncio
+    async def test_propose_contract(self, contract_engine, sample_contract_request):
+        """Test proposing a contract."""
+        created_by = "admin"
+        contract = await contract_engine.create_contract(sample_contract_request, created_by)
+        
+        proposal_request = ContractProposeRequest(
+            proposed_to=["provider1", "patient1"],
+            message="Please review and sign this contract"
+        )
+        
+        proposed_contract = await contract_engine.propose_contract(
+            contract.id, proposal_request, created_by
+        )
+        
+        assert proposed_contract is not None
+        assert proposed_contract.state == ContractState.PROPOSED
+        assert proposed_contract.proposed_at is not None
+
+    @pytest.mark.asyncio
+    async def test_propose_contract_invalid_state(self, contract_engine, sample_contract_request):
+        """Test proposing a contract in invalid state."""
+        created_by = "admin"
+        contract = await contract_engine.create_contract(sample_contract_request, created_by)
+        
+        # First propose the contract
+        proposal_request = ContractProposeRequest(proposed_to=["provider1"])
+        await contract_engine.propose_contract(contract.id, proposal_request, created_by)
+        
+        # Try to propose again (should fail)
+        with pytest.raises(ValueError, match="Cannot propose contract in state ContractState.PROPOSED"):
+            await contract_engine.propose_contract(contract.id, proposal_request, created_by)
+
+    @pytest.mark.asyncio
+    async def test_sign_contract(self, contract_engine, sample_contract_request):
+        """Test signing a contract."""
+        created_by = "admin"
+        contract = await contract_engine.create_contract(sample_contract_request, created_by)
+        
+        # Propose the contract
+        proposal_request = ContractProposeRequest(proposed_to=["provider1"])
+        await contract_engine.propose_contract(contract.id, proposal_request, created_by)
+        
+        # Generate key pair for signing
+        public_key, private_key = generate_key_pair()
+        signer = Ed25519Signer.from_private_key_b64(private_key)
+        
+        # Create signing message
+        signing_message = f"{contract.id}:{contract.get_content_hash()}:provider1:provider"
+        signature = signer.sign(signing_message)
+        
+        # Sign the contract
+        sign_request = ContractSignRequest(
+            signer_id="provider1",
+            signer_type="provider",
+            public_key=public_key,
+            signature=signature
+        )
+        
+        signed_contract = await contract_engine.sign_contract(contract.id, sign_request)
+        
+        assert signed_contract is not None
+        assert len(signed_contract.get_signatures()) == 1
+        assert signed_contract.get_signatures()[0].signer_id == "provider1"
+
+    @pytest.mark.asyncio
+    async def test_sign_contract_invalid_signature(self, contract_engine, sample_contract_request):
+        """Test signing a contract with invalid signature."""
+        created_by = "admin"
+        contract = await contract_engine.create_contract(sample_contract_request, created_by)
+        
+        # Propose the contract
+        proposal_request = ContractProposeRequest(proposed_to=["provider1"])
+        await contract_engine.propose_contract(contract.id, proposal_request, created_by)
+        
+        # Generate key pair for signing
+        public_key, private_key = generate_key_pair()
+        signer = Ed25519Signer.from_private_key_b64(private_key)
+        
+        # Create invalid signing message (wrong content hash)
+        invalid_signing_message = f"{contract.id}:invalid_hash:provider1:provider"
+        signature = signer.sign(invalid_signing_message)
+        
+        # Try to sign with invalid signature
+        sign_request = ContractSignRequest(
+            signer_id="provider1",
+            signer_type="provider",
+            public_key=public_key,
+            signature=signature
+        )
+        
+        with pytest.raises(ValueError, match="Invalid signature"):
+            await contract_engine.sign_contract(contract.id, sign_request)
+
+    @pytest.mark.asyncio
+    async def test_revoke_contract(self, contract_engine, sample_contract_request):
+        """Test revoking a contract."""
+        created_by = "admin"
+        contract = await contract_engine.create_contract(sample_contract_request, created_by)
+        
+        revoke_request = ContractRevokeRequest(
+            reason="Contract terms violated",
+            revoked_by="admin"
+        )
+        
+        revoked_contract = await contract_engine.revoke_contract(contract.id, revoke_request)
+        
+        assert revoked_contract is not None
+        assert revoked_contract.state == ContractState.REVOKED
+        assert revoked_contract.revoked_at is not None
+
+    @pytest.mark.asyncio
+    async def test_revoke_contract_already_revoked(self, contract_engine, sample_contract_request):
+        """Test revoking an already revoked contract."""
+        created_by = "admin"
+        contract = await contract_engine.create_contract(sample_contract_request, created_by)
+        
+        # First revoke the contract
+        revoke_request = ContractRevokeRequest(
+            reason="Contract terms violated",
+            revoked_by="admin"
+        )
+        await contract_engine.revoke_contract(contract.id, revoke_request)
+        
+        # Try to revoke again (should fail)
+        with pytest.raises(ValueError, match="Contract is already revoked"):
+            await contract_engine.revoke_contract(contract.id, revoke_request)
+
+    @pytest.mark.asyncio
+    async def test_get_contracts_by_party(self, contract_engine, sample_contract_request):
+        """Test getting contracts by party."""
+        created_by = "admin"
+        contract = await contract_engine.create_contract(sample_contract_request, created_by)
+        
+        # Get contracts for provider1
+        provider_contracts = await contract_engine.get_contracts_by_party("provider1")
+        assert len(provider_contracts) == 1
+        assert provider_contracts[0].id == contract.id
+        
+        # Get contracts for non-existent party
+        empty_contracts = await contract_engine.get_contracts_by_party("nonexistent")
+        assert len(empty_contracts) == 0
+
+    @pytest.mark.asyncio
+    async def test_cleanup_expired_contracts(self, contract_engine, sample_contract_request):
+        """Test cleanup of expired contracts."""
+        created_by = "admin"
+        
+        # Create contract with past expiration
+        past_expiration = datetime.utcnow() - timedelta(days=1)
+        sample_contract_request.expires_at = past_expiration
+        
+        contract = await contract_engine.create_contract(sample_contract_request, created_by)
+        
+        # Cleanup expired contracts
+        count = await contract_engine.cleanup_expired_contracts()
+        
+        assert count == 1
+        
+        # Verify contract is marked as expired
+        expired_contract = await contract_engine.get_contract(contract.id)
+        assert expired_contract.state == ContractState.EXPIRED
+
+    @pytest.mark.asyncio
+    async def test_get_contract_statistics(self, contract_engine, sample_contract_request):
+        """Test getting contract statistics."""
+        created_by = "admin"
+        
+        # Create multiple contracts
+        contract1 = await contract_engine.create_contract(sample_contract_request, created_by)
+        contract2 = await contract_engine.create_contract(sample_contract_request, created_by)
+        
+        # Propose one contract
+        proposal_request = ContractProposeRequest(proposed_to=["provider1"])
+        await contract_engine.propose_contract(contract1.id, proposal_request, created_by)
+        
+        # Get statistics
+        stats = await contract_engine.get_contract_statistics()
+        
+        assert stats["total_contracts"] == 2
+        assert stats["by_state"]["draft"] == 1
+        assert stats["by_state"]["proposed"] == 1
+        assert stats["hipaa_compliant"] == 2
+        assert stats["signed_contracts"] == 0
+
+
+class TestContractLifecycle:
+    """Test complete contract lifecycle."""
+
+    @pytest.fixture
+    def contract_engine(self):
+        """Create a contract engine for testing."""
+        return ContractEngine("sqlite:///:memory:")
+
+    @pytest.fixture
+    def sample_contract_request(self):
+        """Create a sample contract creation request."""
+        return ContractCreateRequest(
+            title="Test Contract",
+            description="A test contract for lifecycle testing",
+            clauses=[
+                Clause(
+                    title="Test Clause",
+                    content="This is a test clause",
+                    type="test"
+                )
+            ],
+            parties=[
+                {
+                    "id": "party1",
+                    "name": "Test Party 1",
+                    "type": "provider"
+                },
+                {
+                    "id": "party2",
+                    "name": "Test Party 2",
+                    "type": "patient"
+                }
+            ]
+        )
+
+    @pytest.mark.asyncio
+    async def test_complete_contract_lifecycle(self, contract_engine, sample_contract_request):
+        """Test complete contract lifecycle: create → propose → sign → revoke."""
+        created_by = "admin"
+        
+        # 1. Create contract
+        contract = await contract_engine.create_contract(sample_contract_request, created_by)
+        assert contract.state == ContractState.DRAFT
+        
+        # 2. Propose contract
+        proposal_request = ContractProposeRequest(
+            proposed_to=["party1", "party2"],
+            message="Please review and sign"
+        )
+        contract = await contract_engine.propose_contract(contract.id, proposal_request, created_by)
+        assert contract.state == ContractState.PROPOSED
+        
+        # 3. Sign contract (party1)
+        public_key1, private_key1 = generate_key_pair()
+        signer1 = Ed25519Signer.from_private_key_b64(private_key1)
+        signing_message1 = f"{contract.id}:{contract.get_content_hash()}:party1:provider"
+        signature1 = signer1.sign(signing_message1)
+        
+        sign_request1 = ContractSignRequest(
+            signer_id="party1",
+            signer_type="provider",
+            public_key=public_key1,
+            signature=signature1
+        )
+        contract = await contract_engine.sign_contract(contract.id, sign_request1)
+        assert len(contract.get_signatures()) == 1
+        assert contract.state == ContractState.PROPOSED  # Still proposed until all parties sign
+        
+        # 4. Sign contract (party2)
+        public_key2, private_key2 = generate_key_pair()
+        signer2 = Ed25519Signer.from_private_key_b64(private_key2)
+        signing_message2 = f"{contract.id}:{contract.get_content_hash()}:party2:patient"
+        signature2 = signer2.sign(signing_message2)
+        
+        sign_request2 = ContractSignRequest(
+            signer_id="party2",
+            signer_type="patient",
+            public_key=public_key2,
+            signature=signature2
+        )
+        contract = await contract_engine.sign_contract(contract.id, sign_request2)
+        assert len(contract.get_signatures()) == 2
+        assert contract.state == ContractState.SIGNED  # Now fully signed
+        
+        # 5. Revoke contract
+        revoke_request = ContractRevokeRequest(
+            reason="Contract terms violated",
+            revoked_by="admin"
+        )
+        contract = await contract_engine.revoke_contract(contract.id, revoke_request)
+        assert contract.state == ContractState.REVOKED
+        assert contract.revoked_at is not None

tests/contracts/test_contract_http.py

@@ -0,0 +1,298 @@
+"""Tests for contract HTTP endpoints."""
+
+import pytest
+from datetime import datetime, timedelta
+from uuid import UUID
+
+from fastmcp import FastMCP
+from fastmcp.contracts import ContractEngine, ContractState
+from fastmcp.contracts.contract import (
+    Clause, ContractCreateRequest, ContractProposeRequest,
+    ContractSignRequest, ContractRevokeRequest
+)
+from fastmcp.contracts.crypto import generate_key_pair, Ed25519Signer
+from starlette.routing import Route
+
+
+class TestContractHTTPEndpoint:
+    """Test the contract management HTTP endpoints."""
+
+    @pytest.fixture
+    def server_with_contracts(self):
+        """Create a server with contract engine enabled."""
+        server = FastMCP("Test Contract Server")
+        # Use in-memory database for testing
+        contract_engine = server.enable_contract_engine(database_url="sqlite:///:memory:")
+        return server
+
+    @pytest.fixture
+    def app(self, server_with_contracts):
+        """Create the HTTP app with contract endpoints."""
+        return server_with_contracts.http_app(transport="sse")
+
+    def test_contract_endpoints_exist(self, app):
+        """Test that all contract endpoints exist in the app."""
+        expected_paths = [
+            "/contracts",
+            "/contracts/{id}",
+            "/contracts/{id}/propose",
+            "/contracts/{id}/sign",
+            "/contracts/{id}/revoke",
+            "/contracts/statistics"
+        ]
+        
+        # Check that all contract routes exist
+        contract_routes_found = set()
+        for route in app.routes:
+            if isinstance(route, Route):
+                if route.path in expected_paths:
+                    contract_routes_found.add(route.path)
+        
+        assert len(contract_routes_found) == len(expected_paths), f"Expected {len(expected_paths)} unique contract routes, found {len(contract_routes_found)}: {sorted(contract_routes_found)}"
+
+    def test_contract_engine_integration(self, server_with_contracts):
+        """Test that contract engine is properly integrated with the server."""
+        # Check that contract engine is enabled
+        assert server_with_contracts.get_contract_engine() is not None
+        
+        # Check that contract engine is the right type
+        contract_engine = server_with_contracts.get_contract_engine()
+        assert isinstance(contract_engine, ContractEngine)
+
+    @pytest.mark.asyncio
+    async def test_create_contract_endpoint(self, app):
+        """Test the create contract endpoint."""
+        import httpx
+        
+        contract_data = {
+            "title": "Test Contract",
+            "description": "A test contract",
+            "clauses": [
+                {
+                    "title": "Test Clause",
+                    "content": "This is a test clause",
+                    "type": "test"
+                }
+            ],
+            "parties": [
+                {
+                    "id": "party1",
+                    "name": "Test Party",
+                    "type": "provider"
+                }
+            ],
+            "is_hipaa_compliant": False
+        }
+        
+        async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://test") as client:
+            response = await client.post("/contracts", json=contract_data)
+            
+            assert response.status_code == 201
+            data = response.json()
+            assert data["title"] == contract_data["title"]
+            assert data["description"] == contract_data["description"]
+            assert data["state"] == "draft"
+            assert data["is_hipaa_compliant"] is False
+
+    @pytest.mark.asyncio
+    async def test_get_contract_endpoint(self, app):
+        """Test the get contract endpoint."""
+        import httpx
+        
+        # First create a contract
+        contract_data = {
+            "title": "Test Contract",
+            "description": "A test contract",
+            "clauses": [],
+            "parties": []
+        }
+        
+        async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://test") as client:
+            # Create contract
+            create_response = await client.post("/contracts", json=contract_data)
+            assert create_response.status_code == 201
+            contract_id = create_response.json()["id"]
+            
+            # Get contract
+            get_response = await client.get(f"/contracts/{contract_id}")
+            assert get_response.status_code == 200
+            data = get_response.json()
+            assert data["id"] == contract_id
+            assert data["title"] == contract_data["title"]
+
+    @pytest.mark.asyncio
+    async def test_get_contract_not_found(self, app):
+        """Test getting a non-existent contract."""
+        import httpx
+        
+        fake_id = "12345678-1234-1234-1234-123456789012"
+        
+        async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://test") as client:
+            response = await client.get(f"/contracts/{fake_id}")
+            assert response.status_code == 404
+            data = response.json()
+            assert "not found" in data["error"].lower()
+
+    @pytest.mark.asyncio
+    async def test_list_contracts_endpoint(self, app):
+        """Test the list contracts endpoint."""
+        import httpx
+        
+        # Create multiple contracts
+        contract_data = {
+            "title": "Test Contract",
+            "description": "A test contract",
+            "clauses": [],
+            "parties": []
+        }
+        
+        async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://test") as client:
+            # Create contracts
+            await client.post("/contracts", json=contract_data)
+            await client.post("/contracts", json=contract_data)
+            
+            # List contracts
+            response = await client.get("/contracts")
+            assert response.status_code == 200
+            data = response.json()
+            assert "contracts" in data
+            assert "count" in data
+            assert data["count"] == 2
+            assert len(data["contracts"]) == 2
+
+    @pytest.mark.asyncio
+    async def test_propose_contract_endpoint(self, app):
+        """Test the propose contract endpoint."""
+        import httpx
+        
+        # First create a contract
+        contract_data = {
+            "title": "Test Contract",
+            "description": "A test contract",
+            "clauses": [],
+            "parties": []
+        }
+        
+        async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://test") as client:
+            # Create contract
+            create_response = await client.post("/contracts", json=contract_data)
+            contract_id = create_response.json()["id"]
+            
+            # Propose contract
+            proposal_data = {
+                "proposed_to": ["party1", "party2"],
+                "message": "Please review and sign"
+            }
+            
+            response = await client.post(f"/contracts/{contract_id}/propose", json=proposal_data)
+            assert response.status_code == 200
+            data = response.json()
+            assert data["state"] == "proposed"
+            assert data["proposed_at"] is not None
+
+    @pytest.mark.asyncio
+    async def test_sign_contract_endpoint(self, app):
+        """Test the sign contract endpoint."""
+        import httpx
+        
+        # First create and propose a contract
+        contract_data = {
+            "title": "Test Contract",
+            "description": "A test contract",
+            "clauses": [],
+            "parties": [{"id": "party1", "name": "Test Party", "type": "provider"}]
+        }
+        
+        async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://test") as client:
+            # Create contract
+            create_response = await client.post("/contracts", json=contract_data)
+            contract_id = create_response.json()["id"]
+            
+            # Propose contract
+            proposal_data = {"proposed_to": ["party1"]}
+            await client.post(f"/contracts/{contract_id}/propose", json=proposal_data)
+            
+            # Generate key pair for signing
+            public_key, private_key = generate_key_pair()
+            signer = Ed25519Signer.from_private_key_b64(private_key)
+            
+            # Get contract to get content hash
+            contract_response = await client.get(f"/contracts/{contract_id}")
+            contract_data_response = contract_response.json()
+            content_hash = contract_data_response["content_hash"]
+            
+            # Create signature
+            signing_message = f"{contract_id}:{content_hash}:party1:provider"
+            signature = signer.sign(signing_message)
+            
+            # Sign contract
+            sign_data = {
+                "signer_id": "party1",
+                "signer_type": "provider",
+                "public_key": public_key,
+                "signature": signature
+            }
+            
+            response = await client.post(f"/contracts/{contract_id}/sign", json=sign_data)
+            assert response.status_code == 200
+            data = response.json()
+            assert len(data["signatures"]) == 1
+            assert data["signatures"][0]["signer_id"] == "party1"
+
+    @pytest.mark.asyncio
+    async def test_revoke_contract_endpoint(self, app):
+        """Test the revoke contract endpoint."""
+        import httpx
+        
+        # First create a contract
+        contract_data = {
+            "title": "Test Contract",
+            "description": "A test contract",
+            "clauses": [],
+            "parties": []
+        }
+        
+        async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://test") as client:
+            # Create contract
+            create_response = await client.post("/contracts", json=contract_data)
+            contract_id = create_response.json()["id"]
+            
+            # Revoke contract
+            revoke_data = {
+                "reason": "Contract terms violated",
+                "revoked_by": "admin"
+            }
+            
+            response = await client.post(f"/contracts/{contract_id}/revoke", json=revoke_data)
+            assert response.status_code == 200
+            data = response.json()
+            assert data["state"] == "revoked"
+            assert data["revoked_at"] is not None
+
+    @pytest.mark.asyncio
+    async def test_contract_statistics_endpoint(self, app):
+        """Test the contract statistics endpoint."""
+        import httpx
+        
+        # Create some contracts
+        contract_data = {
+            "title": "Test Contract",
+            "description": "A test contract",
+            "clauses": [],
+            "parties": []
+        }
+        
+        async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://test") as client:
+            # Create contracts
+            await client.post("/contracts", json=contract_data)
+            await client.post("/contracts", json=contract_data)
+            
+            # Get statistics
+            response = await client.get("/contracts/statistics")
+            assert response.status_code == 200
+            data = response.json()
+            assert "total_contracts" in data
+            assert "by_state" in data
+            assert "hipaa_compliant" in data
+            assert "signed_contracts" in data
+            assert data["total_contracts"] == 2

tests/ledger/__init__.py

@@ -0,0 +1 @@
+"""Tests for the FastMCP Ledger module."""

tests/ledger/test_ledger_adapters.py

@@ -0,0 +1,234 @@
+"""Tests for the ledger adapters."""
+
+import pytest
+from fastmcp.ledger.adapter import HyperledgerAdapter, OmniSealAdapter, StubAdapter
+
+
+class TestHyperledgerAdapter:
+    """Test the HyperledgerAdapter class."""
+    
+    @pytest.fixture
+    def adapter(self):
+        """Create a Hyperledger adapter for testing."""
+        return HyperledgerAdapter(
+            network_config="test_config.json",
+            channel_name="test-channel",
+            chaincode_name="test-chaincode"
+        )
+    
+    async def test_adapter_initialization(self, adapter):
+        """Test adapter initialization."""
+        assert adapter.network_config == "test_config.json"
+        assert adapter.channel_name == "test-channel"
+        assert adapter.chaincode_name == "test-chaincode"
+        assert adapter.peer_endpoint == "localhost:7051"
+        assert adapter.orderer_endpoint == "localhost:7050"
+    
+    async def test_submit_block(self, adapter):
+        """Test block submission."""
+        block_data = {
+            "block_number": 1,
+            "merkle_root": "test_merkle_root",
+            "entry_count": 5,
+            "entries": ["entry1", "entry2", "entry3", "entry4", "entry5"]
+        }
+        
+        tx_id = await adapter.submit_block(block_data)
+        
+        assert tx_id is not None
+        assert len(tx_id) == 64  # SHA-256 hex length
+    
+    async def test_verify_block(self, adapter):
+        """Test block verification."""
+        block_id = "test_block_1"
+        
+        result = await adapter.verify_block(block_id)
+        
+        # Stub implementation always returns True
+        assert result is True
+    
+    async def test_get_block_proof(self, adapter):
+        """Test getting block proof."""
+        block_id = "test_block_1"
+        
+        proof = await adapter.get_block_proof(block_id)
+        
+        assert proof is not None
+        assert proof["block_id"] == block_id
+        assert "block_hash" in proof
+        assert "block_number" in proof
+        assert "timestamp" in proof
+        assert "proof_type" in proof
+        assert proof["proof_type"] == "hyperledger_fabric"
+        assert "signatures" in proof
+        assert "merkle_root" in proof
+
+
+class TestOmniSealAdapter:
+    """Test the OmniSealAdapter class."""
+    
+    @pytest.fixture
+    def adapter(self):
+        """Create an OmniSeal adapter for testing."""
+        return OmniSealAdapter(
+            api_endpoint="https://api.test.omniseal.com",
+            api_key="test_api_key",
+            network_id="testnet"
+        )
+    
+    async def test_adapter_initialization(self, adapter):
+        """Test adapter initialization."""
+        assert adapter.api_endpoint == "https://api.test.omniseal.com"
+        assert adapter.api_key == "test_api_key"
+        assert adapter.network_id == "testnet"
+    
+    async def test_submit_block(self, adapter):
+        """Test block submission."""
+        block_data = {
+            "block_number": 1,
+            "merkle_root": "test_merkle_root",
+            "entry_count": 3,
+            "entries": ["entry1", "entry2", "entry3"]
+        }
+        
+        tx_id = await adapter.submit_block(block_data)
+        
+        assert tx_id is not None
+        assert len(tx_id) == 64  # SHA-256 hex length
+    
+    async def test_verify_block(self, adapter):
+        """Test block verification."""
+        block_id = "test_block_1"
+        
+        result = await adapter.verify_block(block_id)
+        
+        # Stub implementation always returns True
+        assert result is True
+    
+    async def test_get_block_proof(self, adapter):
+        """Test getting block proof."""
+        block_id = "test_block_1"
+        
+        proof = await adapter.get_block_proof(block_id)
+        
+        assert proof is not None
+        assert proof["block_id"] == block_id
+        assert "block_hash" in proof
+        assert "block_number" in proof
+        assert "timestamp" in proof
+        assert "proof_type" in proof
+        assert proof["proof_type"] == "omniseal"
+        assert "network_id" in proof
+        assert proof["network_id"] == "testnet"
+        assert "merkle_root" in proof
+
+
+class TestStubAdapter:
+    """Test the StubAdapter class."""
+    
+    @pytest.fixture
+    def adapter(self):
+        """Create a stub adapter for testing."""
+        return StubAdapter()
+    
+    async def test_adapter_initialization(self, adapter):
+        """Test adapter initialization."""
+        assert adapter.submitted_blocks == {}
+        assert adapter.block_proofs == {}
+    
+    async def test_submit_block(self, adapter):
+        """Test block submission."""
+        block_data = {
+            "block_number": 1,
+            "merkle_root": "test_merkle_root",
+            "entry_count": 2,
+            "entries": ["entry1", "entry2"]
+        }
+        
+        block_id = await adapter.submit_block(block_data)
+        
+        assert block_id == "stub_block_1"
+        assert block_id in adapter.submitted_blocks
+        assert adapter.submitted_blocks[block_id] == block_data
+    
+    async def test_submit_multiple_blocks(self, adapter):
+        """Test submitting multiple blocks."""
+        for i in range(3):
+            block_data = {
+                "block_number": i + 1,
+                "merkle_root": f"merkle_root_{i}",
+                "entry_count": 1,
+                "entries": [f"entry_{i}"]
+            }
+            
+            block_id = await adapter.submit_block(block_data)
+            assert block_id == f"stub_block_{i + 1}"
+        
+        assert len(adapter.submitted_blocks) == 3
+    
+    async def test_verify_block(self, adapter):
+        """Test block verification."""
+        # Submit a block first
+        block_data = {"block_number": 1, "merkle_root": "test"}
+        block_id = await adapter.submit_block(block_data)
+        
+        # Verify existing block
+        result = await adapter.verify_block(block_id)
+        assert result is True
+        
+        # Verify non-existent block
+        result = await adapter.verify_block("nonexistent_block")
+        assert result is False
+    
+    async def test_get_block_proof(self, adapter):
+        """Test getting block proof."""
+        # Submit a block first
+        block_data = {
+            "block_number": 1,
+            "merkle_root": "test_merkle_root",
+            "entry_count": 2
+        }
+        block_id = await adapter.submit_block(block_data)
+        
+        # Get proof for existing block
+        proof = await adapter.get_block_proof(block_id)
+        
+        assert proof is not None
+        assert proof["block_id"] == block_id
+        assert proof["block_hash"] == f"stub_hash_{block_id}"
+        assert proof["block_number"] == 1
+        assert "timestamp" in proof
+        assert proof["proof_type"] == "stub"
+        assert proof["merkle_root"] == "test_merkle_root"
+        
+        # Get proof for non-existent block
+        proof = await adapter.get_block_proof("nonexistent_block")
+        assert proof is None
+    
+    async def test_adapter_state_persistence(self, adapter):
+        """Test that adapter maintains state across operations."""
+        # Submit a block
+        block_data = {"block_number": 1, "merkle_root": "test"}
+        block_id = await adapter.submit_block(block_data)
+        
+        # Verify it exists
+        assert await adapter.verify_block(block_id) is True
+        
+        # Get proof
+        proof = await adapter.get_block_proof(block_id)
+        assert proof is not None
+        
+        # Submit another block
+        block_data2 = {"block_number": 2, "merkle_root": "test2"}
+        block_id2 = await adapter.submit_block(block_data2)
+        
+        # Both blocks should exist
+        assert await adapter.verify_block(block_id) is True
+        assert await adapter.verify_block(block_id2) is True
+        
+        # Both proofs should be available
+        proof1 = await adapter.get_block_proof(block_id)
+        proof2 = await adapter.get_block_proof(block_id2)
+        assert proof1 is not None
+        assert proof2 is not None
+        assert proof1["block_id"] != proof2["block_id"]

tests/ledger/test_ledger_core.py

@@ -0,0 +1,305 @@
+"""Tests for the core ledger functionality."""
+
+import pytest
+from datetime import datetime
+from uuid import uuid4
+
+from fastmcp.ledger import ProvenanceLedger, LedgerEvent, EventType, LedgerEntry, LedgerBlock
+
+
+class TestProvenanceLedger:
+    """Test the ProvenanceLedger class."""
+    
+    @pytest.fixture
+    def ledger(self):
+        """Create a ledger instance for testing."""
+        return ProvenanceLedger("sqlite:///:memory:")
+    
+    @pytest.fixture
+    def sample_event(self):
+        """Create a sample event for testing."""
+        return LedgerEvent(
+            event_type=EventType.TOOL_CALL,
+            actor_id="user123",
+            resource_id="resource456",
+            action="execute_tool",
+            metadata={"tool_name": "test_tool", "parameters": {"x": 1, "y": 2}},
+            data_hash="sha256_hash_of_data"
+        )
+    
+    def test_ledger_initialization(self, ledger):
+        """Test ledger initialization."""
+        assert ledger is not None
+        assert ledger._current_sequence == 1
+        assert ledger._current_block is None
+        assert ledger._block_size == 100
+    
+    def test_append_event(self, ledger, sample_event):
+        """Test appending an event to the ledger."""
+        entry = ledger.append_event(sample_event)
+        
+        assert entry is not None
+        assert entry.sequence_number == 1
+        assert entry.previous_hash is None
+        assert entry.entry_hash is not None
+        assert entry.block_id is not None
+        assert entry.is_verified is True
+        
+        # Verify the event data
+        event = entry.get_event()
+        assert event.event_type == sample_event.event_type
+        assert event.actor_id == sample_event.actor_id
+        assert event.action == sample_event.action
+    
+    def test_hash_chaining(self, ledger, sample_event):
+        """Test that entries are properly hash-chained."""
+        # Append first event
+        entry1 = ledger.append_event(sample_event)
+        
+        # Append second event
+        entry2 = ledger.append_event(sample_event)
+        
+        # Verify hash chaining
+        assert entry2.previous_hash == entry1.entry_hash
+        assert entry2.sequence_number == entry1.sequence_number + 1
+    
+    def test_entry_integrity_verification(self, ledger, sample_event):
+        """Test entry integrity verification."""
+        entry = ledger.append_event(sample_event)
+        
+        # Verify entry integrity
+        assert entry.verify_integrity() is True
+        
+        # Tamper with the entry
+        original_hash = entry.entry_hash
+        entry.entry_hash = "tampered_hash"
+        
+        # Verify integrity fails
+        assert entry.verify_integrity() is False
+        
+        # Restore original hash
+        entry.entry_hash = original_hash
+        assert entry.verify_integrity() is True
+    
+    def test_get_entry(self, ledger, sample_event):
+        """Test retrieving an entry by sequence number."""
+        entry = ledger.append_event(sample_event)
+        
+        retrieved_entry = ledger.get_entry(entry.sequence_number)
+        assert retrieved_entry is not None
+        assert retrieved_entry.id == entry.id
+        assert retrieved_entry.sequence_number == entry.sequence_number
+    
+    def test_get_nonexistent_entry(self, ledger):
+        """Test retrieving a non-existent entry."""
+        entry = ledger.get_entry(999)
+        assert entry is None
+    
+    def test_block_creation_and_sealing(self, ledger, sample_event):
+        """Test block creation and sealing."""
+        # Append events to fill a block
+        entries = []
+        for i in range(5):  # Use a smaller number for testing
+            event = LedgerEvent(
+                event_type=EventType.TOOL_CALL,
+                actor_id=f"user{i}",
+                action=f"action_{i}",
+                metadata={"index": i}
+            )
+            entry = ledger.append_event(event)
+            entries.append(entry)
+        
+        # Manually seal the block (normally done when block_size is reached)
+        from sqlmodel import Session
+        with Session(ledger.engine) as session:
+            ledger._seal_block(session)
+        
+        # Get the block
+        block = ledger.get_block(1)
+        assert block is not None
+        assert block.block_number == 1
+        assert block.entry_count == 5
+        assert block.merkle_root is not None
+        assert block.sealed_at is not None
+        assert block.is_verified is True
+    
+    def test_block_integrity_verification(self, ledger, sample_event):
+        """Test block integrity verification."""
+        # Create a block with multiple entries
+        entries = []
+        for i in range(3):
+            event = LedgerEvent(
+                event_type=EventType.TOOL_CALL,
+                actor_id=f"user{i}",
+                action=f"action_{i}"
+            )
+            entry = ledger.append_event(event)
+            entries.append(entry)
+        
+        # Seal the block
+        from sqlmodel import Session
+        with Session(ledger.engine) as session:
+            ledger._seal_block(session)
+        
+        # Verify block integrity
+        assert ledger.verify_block_integrity(1) is True
+        
+        # Tamper with an entry
+        entry = ledger.get_entry(1)
+        original_hash = entry.entry_hash
+        entry.entry_hash = "tampered_hash"
+        
+        # Update the entry in the database
+        with Session(ledger.engine) as session:
+            session.add(entry)
+            session.commit()
+        
+        # Verify block integrity fails
+        assert ledger.verify_block_integrity(1) is False
+    
+    def test_chain_integrity_verification(self, ledger, sample_event):
+        """Test chain integrity verification."""
+        # Append multiple events
+        for i in range(5):
+            event = LedgerEvent(
+                event_type=EventType.TOOL_CALL,
+                actor_id=f"user{i}",
+                action=f"action_{i}"
+            )
+            ledger.append_event(event)
+        
+        # Verify entire chain
+        assert ledger.verify_chain_integrity() is True
+        
+        # Verify partial chain
+        assert ledger.verify_chain_integrity(start_sequence=2, end_sequence=4) is True
+    
+    def test_chain_integrity_with_tampering(self, ledger, sample_event):
+        """Test chain integrity verification with tampered entries."""
+        # Append multiple events
+        entries = []
+        for i in range(3):
+            event = LedgerEvent(
+                event_type=EventType.TOOL_CALL,
+                actor_id=f"user{i}",
+                action=f"action_{i}"
+            )
+            entry = ledger.append_event(event)
+            entries.append(entry)
+        
+        # Verify chain is intact
+        assert ledger.verify_chain_integrity() is True
+        
+        # Tamper with middle entry
+        middle_entry = entries[1]
+        original_hash = middle_entry.entry_hash
+        middle_entry.entry_hash = "tampered_hash"
+        
+        # Update in database
+        from sqlmodel import Session
+        with Session(ledger.engine) as session:
+            session.add(middle_entry)
+            session.commit()
+        
+        # Verify chain integrity fails
+        assert ledger.verify_chain_integrity() is False
+    
+    def test_ledger_statistics(self, ledger, sample_event):
+        """Test ledger statistics."""
+        # Initially empty
+        stats = ledger.get_ledger_statistics()
+        assert stats["total_entries"] == 0
+        assert stats["total_blocks"] == 0
+        assert stats["current_sequence"] == 0
+        
+        # Add some entries
+        for i in range(3):
+            event = LedgerEvent(
+                event_type=EventType.TOOL_CALL,
+                actor_id=f"user{i}",
+                action=f"action_{i}"
+            )
+            ledger.append_event(event)
+        
+        # Check updated statistics
+        stats = ledger.get_ledger_statistics()
+        assert stats["total_entries"] == 3
+        assert stats["total_blocks"] == 1
+        assert stats["current_sequence"] == 3
+    
+    def test_different_event_types(self, ledger):
+        """Test appending different types of events."""
+        event_types = [
+            EventType.TOOL_CALL,
+            EventType.POLICY_DECISION,
+            EventType.DATA_FLOW,
+            EventType.CONTRACT_ACTION,
+            EventType.AUTHENTICATION,
+            EventType.AUTHORIZATION,
+            EventType.SYSTEM_EVENT
+        ]
+        
+        for event_type in event_types:
+            event = LedgerEvent(
+                event_type=event_type,
+                actor_id="test_actor",
+                action="test_action"
+            )
+            entry = ledger.append_event(event)
+            
+            retrieved_event = entry.get_event()
+            assert retrieved_event.event_type == event_type
+    
+    def test_event_with_metadata(self, ledger):
+        """Test events with complex metadata."""
+        metadata = {
+            "nested": {"key": "value"},
+            "list": [1, 2, 3],
+            "boolean": True,
+            "null": None
+        }
+        
+        event = LedgerEvent(
+            event_type=EventType.TOOL_CALL,
+            actor_id="test_actor",
+            action="test_action",
+            metadata=metadata
+        )
+        
+        entry = ledger.append_event(event)
+        retrieved_event = entry.get_event()
+        
+        assert retrieved_event.metadata == metadata
+    
+    def test_event_content_hash(self, ledger):
+        """Test event content hash generation."""
+        event = LedgerEvent(
+            event_type=EventType.TOOL_CALL,
+            actor_id="test_actor",
+            action="test_action",
+            metadata={"key": "value"}
+        )
+        
+        content_hash = event.get_content_hash()
+        assert content_hash is not None
+        assert len(content_hash) == 64  # SHA-256 hex length
+        
+        # Same event should produce same hash
+        event2 = LedgerEvent(
+            event_type=EventType.TOOL_CALL,
+            actor_id="test_actor",
+            action="test_action",
+            metadata={"key": "value"}
+        )
+        
+        assert event2.get_content_hash() == content_hash
+        
+        # Different event should produce different hash
+        event3 = LedgerEvent(
+            event_type=EventType.TOOL_CALL,
+            actor_id="test_actor",
+            action="different_action",
+            metadata={"key": "value"}
+        )
+        
+        assert event3.get_content_hash() != content_hash

tests/ledger/test_ledger_http.py

@@ -0,0 +1,319 @@
+"""Tests for the ledger HTTP endpoints."""
+
+import pytest
+import httpx
+from fastmcp import FastMCP
+from fastmcp.ledger import ProvenanceLedger, LedgerEvent, EventType
+
+
+@pytest.fixture
+def server_with_ledger():
+    """Create a FastMCP server with ledger enabled."""
+    server = FastMCP("TestLedgerServer")
+    ledger = server.enable_ledger(database_url="sqlite:///:memory:")
+    return server, ledger
+
+
+@pytest.fixture
+async def client(server_with_ledger):
+    """Create an HTTP client for testing."""
+    server, ledger = server_with_ledger
+    from fastmcp.server.http import create_streamable_http_app
+    app = create_streamable_http_app(server, streamable_http_path="/")
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://test") as client:
+        # Store server and ledger in client for test access
+        client.server = server
+        client.ledger = ledger
+        yield client
+
+
+class TestLedgerHTTPEndpoints:
+    """Test the ledger HTTP endpoints."""
+    
+    async def test_append_event_endpoint(self, client):
+        """Test the append event endpoint."""
+        event_data = {
+            "event_type": "tool_call",
+            "actor_id": "user123",
+            "resource_id": "resource456",
+            "action": "execute_tool",
+            "metadata": {"tool_name": "test_tool"},
+            "data_hash": "sha256_hash"
+        }
+        
+        response = await client.post("/ledger/events", json=event_data)
+        
+        assert response.status_code == 201
+        data = response.json()
+        assert "entry_id" in data
+        assert "sequence_number" in data
+        assert "entry_hash" in data
+        assert "block_id" in data
+        assert "created_at" in data
+        assert data["sequence_number"] == 1
+    
+    async def test_append_event_invalid_data(self, client):
+        """Test append event with invalid data."""
+        invalid_data = {
+            "event_type": "invalid_type",
+            "actor_id": "user123",
+            "action": "test_action"
+        }
+        
+        response = await client.post("/ledger/events", json=invalid_data)
+        
+        assert response.status_code == 400
+        data = response.json()
+        assert "error" in data
+        assert "Invalid event data" in data["error"]
+    
+    async def test_verify_block_endpoint(self, client):
+        """Test the verify block endpoint."""
+        # First, add some events to create a block
+        for i in range(3):
+            event_data = {
+                "event_type": "tool_call",
+                "actor_id": f"user{i}",
+                "action": f"action_{i}"
+            }
+            await client.post("/ledger/events", json=event_data)
+        
+        # Manually seal the block for testing
+        client.ledger.seal_current_block()
+    
+        # Verify the block
+        response = await client.get("/ledger/verify/1")
+        
+        assert response.status_code == 200
+        data = response.json()
+        assert data["block_number"] == 1
+        assert data["verified"] is True
+        assert "block_id" in data
+        assert "entry_count" in data
+        assert "merkle_root" in data
+    
+    async def test_verify_nonexistent_block(self, client):
+        """Test verifying a non-existent block."""
+        response = await client.get("/ledger/verify/999")
+        
+        assert response.status_code == 400
+        data = response.json()
+        assert "error" in data
+        assert "Block integrity verification failed" in data["error"]
+    
+    async def test_get_entry_endpoint(self, client):
+        """Test the get entry endpoint."""
+        # First, add an event
+        event_data = {
+            "event_type": "tool_call",
+            "actor_id": "user123",
+            "action": "test_action"
+        }
+        await client.post("/ledger/events", json=event_data)
+        
+        # Get the entry
+        response = await client.get("/ledger/entries/1")
+        
+        assert response.status_code == 200
+        data = response.json()
+        assert data["sequence_number"] == 1
+        assert "entry_hash" in data
+        assert "previous_hash" in data
+        assert "event" in data
+        assert data["event"]["actor_id"] == "user123"
+        assert data["event"]["action"] == "test_action"
+    
+    async def test_get_nonexistent_entry(self, client):
+        """Test getting a non-existent entry."""
+        response = await client.get("/ledger/entries/999")
+        
+        assert response.status_code == 404
+        data = response.json()
+        assert "error" in data
+        assert "Entry not found" in data["error"]
+    
+    async def test_get_block_endpoint(self, client):
+        """Test the get block endpoint."""
+        # First, add some events to create a block
+        for i in range(3):
+            event_data = {
+                "event_type": "tool_call",
+                "actor_id": f"user{i}",
+                "action": f"action_{i}"
+            }
+            await client.post("/ledger/events", json=event_data)
+        
+        # Get the block
+        response = await client.get("/ledger/blocks/1")
+        
+        assert response.status_code == 200
+        data = response.json()
+        assert data["block_number"] == 1
+        assert "entry_count" in data
+        assert "merkle_root" in data
+        assert "entries" in data
+        assert len(data["entries"]) == 3
+    
+    async def test_get_nonexistent_block(self, client):
+        """Test getting a non-existent block."""
+        response = await client.get("/ledger/blocks/999")
+        
+        assert response.status_code == 404
+        data = response.json()
+        assert "error" in data
+        assert "Block not found" in data["error"]
+    
+    async def test_verify_chain_endpoint(self, client):
+        """Test the verify chain endpoint."""
+        # Add some events
+        for i in range(3):
+            event_data = {
+                "event_type": "tool_call",
+                "actor_id": f"user{i}",
+                "action": f"action_{i}"
+            }
+            await client.post("/ledger/events", json=event_data)
+        
+        # Verify the chain
+        response = await client.get("/ledger/verify-chain")
+        
+        assert response.status_code == 200
+        data = response.json()
+        assert data["verified"] is True
+        assert "start_sequence" in data
+        assert "end_sequence" in data
+    
+    async def test_verify_chain_with_range(self, client):
+        """Test verify chain with specific range."""
+        # Add some events
+        for i in range(5):
+            event_data = {
+                "event_type": "tool_call",
+                "actor_id": f"user{i}",
+                "action": f"action_{i}"
+            }
+            await client.post("/ledger/events", json=event_data)
+        
+        # Verify partial chain
+        response = await client.get("/ledger/verify-chain?start_sequence=2&end_sequence=4")
+        
+        assert response.status_code == 200
+        data = response.json()
+        assert data["verified"] is True
+        assert data["start_sequence"] == 2
+        assert data["end_sequence"] == 4
+    
+    async def test_get_merkle_proof_endpoint(self, client):
+        """Test the get Merkle proof endpoint."""
+        # Add some events to create a block
+        for i in range(3):
+            event_data = {
+                "event_type": "tool_call",
+                "actor_id": f"user{i}",
+                "action": f"action_{i}"
+            }
+            await client.post("/ledger/events", json=event_data)
+        
+        # Manually seal the block for testing
+        client.ledger.seal_current_block()
+    
+        # Get Merkle proof for first entry
+        response = await client.get("/ledger/proof/1")
+        
+        assert response.status_code == 200
+        data = response.json()
+        assert data["sequence_number"] == 1
+        assert "entry_hash" in data
+        assert "block_number" in data
+        assert "merkle_root" in data
+        assert "proof" in data
+        assert "leaf_hash" in data["proof"]
+        assert "path" in data["proof"]
+        assert "root_hash" in data["proof"]
+        assert data["verified"] is True
+    
+    async def test_get_merkle_proof_nonexistent_entry(self, client):
+        """Test getting Merkle proof for non-existent entry."""
+        response = await client.get("/ledger/proof/999")
+        
+        assert response.status_code == 404
+        data = response.json()
+        assert "error" in data
+        assert "Entry not found" in data["error"]
+    
+    async def test_get_ledger_statistics_endpoint(self, client):
+        """Test the get ledger statistics endpoint."""
+        # Initially empty
+        response = await client.get("/ledger/statistics")
+        
+        assert response.status_code == 200
+        data = response.json()
+        assert data["total_entries"] == 0
+        assert data["total_blocks"] == 0
+        assert data["current_sequence"] == 0
+        
+        # Add some events
+        for i in range(3):
+            event_data = {
+                "event_type": "tool_call",
+                "actor_id": f"user{i}",
+                "action": f"action_{i}"
+            }
+            await client.post("/ledger/events", json=event_data)
+        
+        # Check updated statistics
+        response = await client.get("/ledger/statistics")
+        
+        assert response.status_code == 200
+        data = response.json()
+        assert data["total_entries"] == 3
+        assert data["total_blocks"] == 1
+        assert data["current_sequence"] == 3
+    
+    async def test_multiple_event_types(self, client):
+        """Test appending different event types."""
+        event_types = [
+            "tool_call",
+            "policy_decision", 
+            "data_flow",
+            "contract_action",
+            "authentication",
+            "authorization",
+            "system_event"
+        ]
+        
+        for event_type in event_types:
+            event_data = {
+                "event_type": event_type,
+                "actor_id": "test_actor",
+                "action": "test_action"
+            }
+            
+            response = await client.post("/ledger/events", json=event_data)
+            assert response.status_code == 201
+    
+    async def test_event_with_complex_metadata(self, client):
+        """Test event with complex metadata."""
+        event_data = {
+            "event_type": "tool_call",
+            "actor_id": "test_actor",
+            "action": "test_action",
+            "metadata": {
+                "nested": {"key": "value"},
+                "list": [1, 2, 3],
+                "boolean": True,
+                "null": None
+            }
+        }
+        
+        response = await client.post("/ledger/events", json=event_data)
+        
+        assert response.status_code == 201
+        data = response.json()
+        assert data["sequence_number"] == 1
+        
+        # Verify the event was stored correctly
+        entry_response = await client.get("/ledger/entries/1")
+        assert entry_response.status_code == 200
+        entry_data = entry_response.json()
+        assert entry_data["event"]["metadata"] == event_data["metadata"]

tests/ledger/test_merkle_tree.py

@@ -0,0 +1,235 @@
+"""Tests for the Merkle tree functionality."""
+
+import pytest
+
+from fastmcp.ledger.merkle import MerkleTree, MerkleProof, verify_merkle_proof
+
+
+class TestMerkleTree:
+    """Test the MerkleTree class."""
+    
+    def test_single_leaf(self):
+        """Test Merkle tree with a single leaf."""
+        leaf_hashes = ["hash1"]
+        tree = MerkleTree(leaf_hashes)
+        
+        assert tree.get_root() == "hash1"
+        assert tree.get_leaf_count() == 1
+        assert tree.get_tree_height() == 1
+    
+    def test_two_leaves(self):
+        """Test Merkle tree with two leaves."""
+        leaf_hashes = ["hash1", "hash2"]
+        tree = MerkleTree(leaf_hashes)
+        
+        # Root should be hash of concatenated leaves
+        import hashlib
+        expected_root = hashlib.sha256(("hash1" + "hash2").encode()).hexdigest()
+        assert tree.get_root() == expected_root
+        assert tree.get_leaf_count() == 2
+        assert tree.get_tree_height() == 2
+    
+    def test_three_leaves(self):
+        """Test Merkle tree with three leaves (odd number)."""
+        leaf_hashes = ["hash1", "hash2", "hash3"]
+        tree = MerkleTree(leaf_hashes)
+        
+        # With odd number of leaves, last leaf should be duplicated
+        assert tree.get_leaf_count() == 3
+        assert tree.get_tree_height() == 3
+    
+    def test_four_leaves(self):
+        """Test Merkle tree with four leaves."""
+        leaf_hashes = ["hash1", "hash2", "hash3", "hash4"]
+        tree = MerkleTree(leaf_hashes)
+        
+        assert tree.get_leaf_count() == 4
+        assert tree.get_tree_height() == 3
+    
+    def test_large_tree(self):
+        """Test Merkle tree with many leaves."""
+        leaf_hashes = [f"hash{i}" for i in range(100)]
+        tree = MerkleTree(leaf_hashes)
+        
+        assert tree.get_leaf_count() == 100
+        assert tree.get_tree_height() > 1
+        assert tree.get_root() is not None
+    
+    def test_generate_proof_single_leaf(self):
+        """Test proof generation for single leaf."""
+        leaf_hashes = ["hash1"]
+        tree = MerkleTree(leaf_hashes)
+        
+        proof = tree.generate_proof("hash1")
+        assert proof is not None
+        assert proof.leaf_hash == "hash1"
+        assert proof.path == []
+        assert proof.root_hash == "hash1"
+        assert proof.verify() is True
+    
+    def test_generate_proof_two_leaves(self):
+        """Test proof generation for two leaves."""
+        leaf_hashes = ["hash1", "hash2"]
+        tree = MerkleTree(leaf_hashes)
+        
+        # Proof for first leaf
+        proof1 = tree.generate_proof("hash1")
+        assert proof1 is not None
+        assert proof1.leaf_hash == "hash1"
+        assert len(proof1.path) == 1
+        assert proof1.path[0]["hash"] == "hash2"
+        assert proof1.path[0]["position"] == "right"
+        assert proof1.verify() is True
+        
+        # Proof for second leaf
+        proof2 = tree.generate_proof("hash2")
+        assert proof2 is not None
+        assert proof2.leaf_hash == "hash2"
+        assert len(proof2.path) == 1
+        assert proof2.path[0]["hash"] == "hash1"
+        assert proof2.path[0]["position"] == "left"
+        assert proof2.verify() is True
+    
+    def test_generate_proof_nonexistent_leaf(self):
+        """Test proof generation for non-existent leaf."""
+        leaf_hashes = ["hash1", "hash2"]
+        tree = MerkleTree(leaf_hashes)
+        
+        proof = tree.generate_proof("nonexistent")
+        assert proof is None
+    
+    def test_verify_leaf(self):
+        """Test leaf verification."""
+        leaf_hashes = ["hash1", "hash2", "hash3"]
+        tree = MerkleTree(leaf_hashes)
+        
+        # Verify existing leaves
+        assert tree.verify_leaf("hash1") is True
+        assert tree.verify_leaf("hash2") is True
+        assert tree.verify_leaf("hash3") is True
+        
+        # Verify non-existent leaf
+        assert tree.verify_leaf("nonexistent") is False
+    
+    def test_verify_proof(self):
+        """Test proof verification."""
+        leaf_hashes = ["hash1", "hash2", "hash3", "hash4"]
+        tree = MerkleTree(leaf_hashes)
+        
+        proof = tree.generate_proof("hash1")
+        assert proof is not None
+        assert tree.verify_proof(proof) is True
+        
+        # Tamper with proof
+        proof.leaf_hash = "tampered"
+        assert tree.verify_proof(proof) is False
+    
+    def test_to_dict_and_from_dict(self):
+        """Test serialization and deserialization."""
+        leaf_hashes = ["hash1", "hash2", "hash3"]
+        tree1 = MerkleTree(leaf_hashes)
+        
+        # Convert to dict
+        tree_dict = tree1.to_dict()
+        assert "root_hash" in tree_dict
+        assert "leaf_count" in tree_dict
+        assert "tree_height" in tree_dict
+        assert "tree_data" in tree_dict
+        assert "leaf_hashes" in tree_dict
+        
+        # Convert back to tree
+        tree2 = MerkleTree.from_dict(tree_dict)
+        assert tree2.get_root() == tree1.get_root()
+        assert tree2.get_leaf_count() == tree1.get_leaf_count()
+        assert tree2.get_tree_height() == tree1.get_tree_height()
+        assert tree2.get_leaf_hashes() == tree1.get_leaf_hashes()
+    
+    def test_empty_tree_raises_error(self):
+        """Test that empty tree raises error."""
+        with pytest.raises(ValueError, match="Cannot create Merkle tree with empty leaf list"):
+            MerkleTree([])
+
+
+class TestMerkleProof:
+    """Test the MerkleProof class."""
+    
+    def test_proof_verification_simple(self):
+        """Test simple proof verification."""
+        import hashlib
+        
+        # Create a simple two-leaf tree
+        leaf_hash = "hash1"
+        sibling_hash = "hash2"
+        combined = sibling_hash + leaf_hash  # sibling on left, leaf on right
+        root_hash = hashlib.sha256(combined.encode()).hexdigest()
+        
+        proof = MerkleProof(
+            leaf_hash=leaf_hash,
+            path=[{"hash": sibling_hash, "position": "left"}],
+            root_hash=root_hash
+        )
+        
+        assert proof.verify() is True
+    
+    def test_proof_verification_complex(self):
+        """Test complex proof verification with multiple levels."""
+        import hashlib
+        
+        # Create a more complex tree structure
+        leaf_hash = "hash1"
+        path = [
+            {"hash": "hash2", "position": "right"},  # sibling at leaf level
+            {"hash": "intermediate_hash", "position": "left"}  # sibling at parent level
+        ]
+        
+        # Calculate expected root
+        # First level: hash1 + hash2
+        level1 = hashlib.sha256(("hash1" + "hash2").encode()).hexdigest()
+        # Second level: intermediate_hash + level1
+        root_hash = hashlib.sha256(("intermediate_hash" + level1).encode()).hexdigest()
+        
+        proof = MerkleProof(
+            leaf_hash=leaf_hash,
+            path=path,
+            root_hash=root_hash
+        )
+        
+        assert proof.verify() is True
+    
+    def test_proof_verification_failure(self):
+        """Test proof verification failure."""
+        proof = MerkleProof(
+            leaf_hash="hash1",
+            path=[{"hash": "hash2", "position": "left"}],
+            root_hash="wrong_root_hash"
+        )
+        
+        assert proof.verify() is False
+
+
+class TestVerifyMerkleProof:
+    """Test the standalone verify_merkle_proof function."""
+    
+    def test_verify_merkle_proof_function(self):
+        """Test the standalone verify_merkle_proof function."""
+        import hashlib
+        
+        leaf_hash = "hash1"
+        path = [{"hash": "hash2", "position": "left"}]
+        # When sibling is on the left, we concatenate sibling + leaf
+        combined = "hash2" + leaf_hash
+        root_hash = hashlib.sha256(combined.encode()).hexdigest()
+        
+        assert verify_merkle_proof(leaf_hash, path, root_hash) is True
+        
+        # Test with wrong root
+        assert verify_merkle_proof(leaf_hash, path, "wrong_root") is False
+    
+    def test_verify_merkle_proof_empty_path(self):
+        """Test verify_merkle_proof with empty path (single leaf)."""
+        leaf_hash = "hash1"
+        path = []
+        root_hash = "hash1"  # For single leaf, root equals leaf
+        
+        assert verify_merkle_proof(leaf_hash, path, root_hash) is True
+        assert verify_merkle_proof(leaf_hash, path, "wrong_root") is False