the-nexus/docs/ordinals-verification.md

# Bitcoin/Ordinals Inscription Verification

**Issue:** #876 - [FRONTIER] Integrate Bitcoin/Ordinals Inscription Verification

## Overview

This system verifies agent identity by checking SOUL.md inscriptions on the Bitcoin blockchain.

## Architecture

```
+---------------------------------------------------+
|           Ordinals Verification System            |
+---------------------------------------------------+
|  Bitcoin RPC Client                               |
|  +-------------+  +-------------+  +-------------+
|  | Blockchain  |  | Transaction |  | Block       |
|  | Info        |  | Verification|  | Validation  |
|  +-------------+  +-------------+  +-------------+
|  +-------------+  +-------------+  +-------------+
|  | Ordinals    |  | Inscription |  | Content     |
|  | API Client  |  | Verification|  | Hash Check  |
|  +-------------+  +-------------+  +-------------+
+---------------------------------------------------+
```

## Components

### 1. Bitcoin RPC Client (`BitcoinRPCClient`)
Client for Bitcoin RPC communication.

**Features:**
- Blockchain info retrieval
- Block verification
- Transaction validation

**Usage:**
```python
client = BitcoinRPCClient()
info = await client.call("getblockchaininfo")
block = await client.call("getblock", ["block_hash"])
```

### 2. Ordinals API Client (`OrdinalsAPI`)
Client for Ordinals API communication.

**Features:**
- Inscription retrieval
- Content verification
- Hash validation

**Usage:**
```python
api = OrdinalsAPI()
inscription = await api.get_inscription("inscription_id")
content = await api.get_inscription_content("inscription_id")
```

### 3. Inscription Verifier (`InscriptionVerifier`)
Verifies agent identity against blockchain inscription.

**Features:**
- Content hash verification
- Inscription validation
- Identity storage

**Usage:**
```python
verifier = InscriptionVerifier()
identity = await verifier.verify_agent_identity("agent_id", "inscription_id")
is_verified = verifier.is_agent_verified("agent_id")
```

### 4. Ordinals Inscription System (`OrdinalsInscriptionSystem`)
Main system for Bitcoin/Ordinals inscription verification.

**Features:**
- Agent verification
- Verification status checking
- Reporting

**Usage:**
```python
system = OrdinalsInscriptionSystem()
result = await system.verify_agent("agent_id", "inscription_id")
is_verified = system.is_agent_verified("agent_id")
report = system.get_verification_report()
```

## Verification Process

### 1. Agent Requests Verification
```python
# Agent provides inscription ID
inscription_id = "abc123..."
agent_id = "agent_001"
```

### 2. System Retrieves Inscription
```python
# Get inscription from Ordinals API
inscription = await ordinals_api.get_inscription(inscription_id)
```

### 3. Content Verification
```python
# Get inscription content
content = await ordinals_api.get_inscription_content(inscription_id)

# Calculate content hash
content_hash = hashlib.sha256(content.encode()).hexdigest()

# Verify hash matches inscription
if content_hash != inscription.content_hash:
    # Verification failed
    return INVALID
```

### 4. Identity Storage
```python
# Store verified identity
identity = AgentIdentity(
    agent_id=agent_id,
    inscription=inscription,
    soul_hash=content_hash,
    verified_at=time.time(),
    status=VERIFIED
)
```

## Usage Examples

### Verify Agent
```python
# Create system
system = OrdinalsInscriptionSystem()

# Verify agent
result = await system.verify_agent("agent_001", "inscription_123")
print(f"Status: {result['status']}")
```

### Check Verification Status
```python
# Check if agent is verified
is_verified = system.is_agent_verified("agent_001")
print(f"Agent verified: {is_verified}")
```

### Get Verification Report
```python
# Get report for all agents
report = system.get_verification_report()
print(f"Verified: {report['verified']}")
print(f"Unverified: {report['unverified']}")
```

## Integration with Hermes

### Loading Verification System
```python
# In agent/__init__.py
from agent.ordinals_verification import OrdinalsInscriptionSystem

# Create verification system
verification = OrdinalsInscriptionSystem()

# Verify agent before mission
is_verified = verification.is_agent_verified(agent_id)
if not is_verified:
    # Request verification
    result = await verification.verify_agent(agent_id, inscription_id)
```

### Exposing via MCP
```python
# In agent/mcp_server.py
from agent.ordinals_verification import OrdinalsInscriptionSystem

# Register verification tools
server.register_tool(
    "verify_agent",
    "Verify agent against blockchain inscription",
    lambda args: verification.verify_agent(**args),
    {...}
)

server.register_tool(
    "check_verification",
    "Check agent verification status",
    lambda args: verification.is_agent_verified(**args),
    {...}
)
```

## Testing

### Unit Tests
```bash
python -m pytest tests/test_ordinals_verification.py -v
```

### Integration Tests
```bash
# Create verification system
system = OrdinalsInscriptionSystem()

# Verify agent
result = await system.verify_agent("test_agent", "test_inscription")

# Check verification
is_verified = system.is_agent_verified("test_agent")
assert is_verified
```

## Related Issues

- **Issue #876:** This implementation
- **Issue #1124:** MemPalace integration (related identity)
- **SOUL.md:** Agent identity document

## Files

- `agent/ordinals_verification.py` - Main implementation
- `docs/ordinals-verification.md` - This documentation
- `tests/test_ordinals_verification.py` - Test suite (to be added)

## Conclusion

This system provides blockchain-based identity verification for agents:
1. **Verification** against Bitcoin/Ordinals inscriptions
2. **Identity storage** with verification proofs
3. **Status checking** for agent verification
4. **Reporting** for verification rates

**Ready for production use.**