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:

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:

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:

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:

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

# Agent provides inscription ID
inscription_id = "abc123..."
agent_id = "agent_001"

2. System Retrieves Inscription

# Get inscription from Ordinals API
inscription = await ordinals_api.get_inscription(inscription_id)

3. Content Verification

# 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

# 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

# Create system
system = OrdinalsInscriptionSystem()

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

Check Verification Status

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

Get Verification Report

# 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

# 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

# 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

python -m pytest tests/test_ordinals_verification.py -v

Integration Tests

# 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.