spoon-erc8004-standard

Original source / Raw SKILL.md

---
name: spoon-erc8004-standard
description: Implement ERC-8004 trustless agent identity. Use when registering agents on-chain, managing reputation, handling validation, or generating DID documents.
---

# ERC-8004 Standard

Implement trustless on-chain agent identity with ERC-8004.

## Overview

ERC-8004 provides:
- On-chain agent registration
- Decentralized identity (DID)
- Reputation tracking
- Validation mechanisms

## Quick Start

```python
from spoon_ai.identity.erc8004_client import ERC8004Client

client = ERC8004Client(
    rpc_url="https://testnet.rpc.banelabs.org",
    agent_registry_address="0x...",
    identity_registry_address="0x...",
    reputation_registry_address="0x...",
    validation_registry_address="0x...",
    private_key=os.getenv("PRIVATE_KEY")
)

# Register agent
tx_hash = client.register_agent(
    did="did:spoon:agent123",
    agent_card_uri="https://storage.example.com/card.json",
    did_doc_uri="https://storage.example.com/did.json"
)
```

## Scripts

| Script | Purpose |
|--------|---------|
| [register_agent.py](scripts/register_agent.py) | Agent registration |
| [resolve_agent.py](scripts/resolve_agent.py) | DID resolution |
| [update_reputation.py](scripts/update_reputation.py) | Reputation management |
| [generate_did.py](scripts/generate_did.py) | DID document generation |

## References

| Reference | Content |
|-----------|---------|
| [contracts.md](references/contracts.md) | Contract addresses |
| [did_format.md](references/did_format.md) | DID document format |

## Contract Addresses (NeoX Testnet)

| Contract | Address |
|----------|---------|
| AgentRegistry | `0xaB5623F3DD66f2a52027FA06007C78c7b0E63508` |
| IdentityRegistry | `0x8bb086D12659D6e2c7220b07152255d10b2fB049` |
| ReputationRegistry | `0x18A9240c99c7283d9332B738f9C6972b5B59aEc2` |

## Best Practices

1. Store agent cards on IPFS/Arweave
2. Use EIP-712 signatures for registration
3. Monitor reputation changes
4. Implement validation before transactions


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### scripts/register_agent.py

```python
#!/usr/bin/env python3
"""Register an agent on-chain using ERC-8004."""

import os
import json
from spoon_ai.identity.erc8004_client import ERC8004Client


# Contract addresses (NeoX Testnet)
CONTRACTS = {
    "agent_registry": "0xaB5623F3DD66f2a52027FA06007C78c7b0E63508",
    "identity_registry": "0x8bb086D12659D6e2c7220b07152255d10b2fB049",
    "reputation_registry": "0x18A9240c99c7283d9332B738f9C6972b5B59aEc2",
    "validation_registry": "0x..."
}


def register_agent(
    did: str,
    agent_card_uri: str,
    did_doc_uri: str
) -> str:
    """Register an agent on-chain.

    Args:
        did: Decentralized identifier (e.g., "did:spoon:my_agent")
        agent_card_uri: URI to agent card JSON
        did_doc_uri: URI to DID document JSON

    Returns:
        Transaction hash
    """
    client = ERC8004Client(
        rpc_url=os.getenv("RPC_URL", "https://testnet.rpc.banelabs.org"),
        agent_registry_address=CONTRACTS["agent_registry"],
        identity_registry_address=CONTRACTS["identity_registry"],
        reputation_registry_address=CONTRACTS["reputation_registry"],
        validation_registry_address=CONTRACTS["validation_registry"],
        private_key=os.getenv("PRIVATE_KEY")
    )

    tx_hash = client.register_agent(
        did=did,
        agent_card_uri=agent_card_uri,
        did_doc_uri=did_doc_uri
    )

    return tx_hash


def main():
    # Example registration
    did = "did:spoon:my_trading_agent"
    agent_card_uri = "ipfs://QmXyz.../agent_card.json"
    did_doc_uri = "ipfs://QmXyz.../did_document.json"

    try:
        tx_hash = register_agent(did, agent_card_uri, did_doc_uri)
        print(f"Agent registered successfully!")
        print(f"DID: {did}")
        print(f"Transaction: {tx_hash}")
    except Exception as e:
        print(f"Registration failed: {e}")


if __name__ == "__main__":
    main()

```

### references/did_format.md

```markdown
# DID Document Format

## Agent Card JSON

```json
{
  "@context": "https://schema.org",
  "@type": "SoftwareAgent",
  "name": "Trading Agent",
  "description": "Automated trading agent",
  "version": "1.0.0",
  "capabilities": [
    "market-analysis",
    "order-execution",
    "risk-management"
  ],
  "tools": [
    {
      "name": "get_price",
      "description": "Get token price"
    }
  ],
  "endpoints": {
    "invoke": "https://agent.example.com/invoke",
    "status": "https://agent.example.com/status"
  }
}
```

## DID Document JSON

```json
{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/v1"
  ],
  "id": "did:spoon:agent123",
  "controller": "did:spoon:agent123",
  "verificationMethod": [
    {
      "id": "did:spoon:agent123#keys-1",
      "type": "EcdsaSecp256k1VerificationKey2019",
      "controller": "did:spoon:agent123",
      "publicKeyHex": "0x..."
    }
  ],
  "authentication": [
    "did:spoon:agent123#keys-1"
  ],
  "service": [
    {
      "id": "did:spoon:agent123#agent-service",
      "type": "AgentService",
      "serviceEndpoint": "https://agent.example.com"
    }
  ]
}
```

## DID Method Syntax

```
did:spoon:<network>:<agent_id>

Examples:
- did:spoon:mainnet:agent123
- did:spoon:neox:trading_bot
- did:spoon:testnet:research_agent
```

```