erc-8004-py 1.0.0

Python SDK for ERC-8004 Trustless Agents protocol

ERC-8004 SDK (Python)

Python SDK for interacting with ERC-8004 Trustless Agents protocol.

Installation

pip install erc-8004-py

Quick Start

from erc8004 import ERC8004Client, Web3Adapter
from web3 import Web3

# Connect to Ethereum node
w3 = Web3(Web3.HTTPProvider('YOUR_RPC_URL'))
adapter = Web3Adapter(w3, private_key='0x...')

# Initialize client
client = ERC8004Client(
    adapter=adapter,
    addresses={
        'identityRegistry': '0x...',
        'reputationRegistry': '0x...',
        'validationRegistry': '0x...',
        'chainId': 11155111,
    }
)

# Register an agent
result = client.identity.register_with_uri('ipfs://QmYourAgentData')
print(f"Agent ID: {result['agentId']}")

Contract Addresses

Important: All contracts use CREATE2 deterministic deployment. The addresses are the same on all networks (localhost, Sepolia, mainnet, etc.):

addresses = {
    'identityRegistry': '0x8004AbdDA9b877187bF865eD1d8B5A41Da3c4997',
    'reputationRegistry': '0x8004B312333aCb5764597c2BeEe256596B5C6876',
    'validationRegistry': '0x8004C8AEF64521bC97AB50799d394CDb785885E3',
    'chainId': 11155111,  # Change based on your network
}

The addresses use a vanity prefix 0x8004... to make them easily recognizable.

Core Features

Identity Management

# Register an agent
result = client.identity.register_with_uri('ipfs://QmYourAgentData')
agent_id = result['agentId']

# Get agent info
owner = client.identity.get_owner(agent_id)
token_uri = client.identity.get_token_uri(agent_id)

Reputation & Feedback

Note: The new contract version has removed the feedbackAuth mechanism. Anyone can now give feedback directly (except self-feedback).

# Submit feedback directly (no authorization needed!)
client.reputation.give_feedback(
    agent_id=agent_id,
    score=95,
    tag1='excellent-service',  # Now strings, not bytes32!
    tag2='fast-response',
)

# Get reputation summary
summary = client.reputation.get_summary(agent_id)
print(f"Average: {summary['averageScore']}, Count: {summary['count']}")

# Read specific feedback (indices start at 1)
feedback = client.reputation.read_feedback(agent_id, client_address, 1)
print(f"Score: {feedback['score']}, Tags: {feedback['tag1']}, {feedback['tag2']}")

Validation

from erc8004 import ipfs_uri_to_bytes32

# Request validation
request_uri = 'ipfs://QmValidationRequest'
request_hash = ipfs_uri_to_bytes32(request_uri)

client.validation.validation_request(
    validator_address=validator_address,
    agent_id=agent_id,
    request_uri=request_uri,
    request_hash=request_hash,
)

# Validator provides response
client.validation.validation_response(
    request_hash=request_hash,
    response=100,
    response_uri='ipfs://QmValidationResponse',
    tag='zkML-proof',
)

IPFS Integration

from erc8004 import IPFSClientConfig, create_ipfs_client, cid_to_bytes32

# Create IPFS client
config = IPFSClientConfig(
    provider='pinata',
    api_key='YOUR_PINATA_API_KEY',
    api_secret='YOUR_PINATA_API_SECRET',
)
ipfs = create_ipfs_client(config)

# Upload agent registration data
agent_data = {
    'type': 'https://eips.ethereum.org/EIPS/eip-8004#registration-v1',
    'name': 'My Agent',
    'description': 'AI agent for task automation',
    'endpoints': [],
}

result = ipfs.upload_json(agent_data)
client.identity.register_with_uri(result.uri)

# Convert CID to bytes32
hash_bytes = cid_to_bytes32(result.cid)

API Reference

ERC8004Client

Main client with three sub-clients:

• client.identity - Agent registration and identity
• client.reputation - Feedback and reputation
• client.validation - Validation requests and responses

IdentityClient

• register() - Register agent without URI
• register_with_uri(token_uri) - Register with token URI
• register_with_metadata(token_uri, metadata=None) - Register with URI and optional metadata
• get_token_uri(agent_id) - Get token URI
• set_agent_uri(agent_id, new_uri) - Set token URI
• get_owner(agent_id) - Get agent owner
• get_metadata(agent_id, key) - Get on-chain metadata
• set_metadata(agent_id, key, value) - Set on-chain metadata
• get_registration_file(agent_id) - Fetch and parse agent registration file

ReputationClient

• give_feedback(agent_id, score, tag1=None, tag2=None, feedback_uri=None, feedback_hash=None) - Submit feedback (no auth needed!)
• revoke_feedback(agent_id, feedback_index) - Revoke your own feedback
• append_response(agent_id, client_address, feedback_index, response_uri, response_hash=None) - Agent can append response to feedback
• get_summary(agent_id, client_addresses=None, tag1=None, tag2=None) - Get reputation summary with optional filters
• read_feedback(agent_id, client_address, index) - Read specific feedback (indices start at 1)
• read_all_feedback(agent_id, client_addresses=None, tag1=None, tag2=None, include_revoked=False) - Read all feedback with optional filters
• get_clients(agent_id) - Get all clients who gave feedback
• get_last_index(agent_id, client_address) - Get last feedback index for a client

ValidationClient

• validation_request(validator_address, agent_id, request_uri, request_hash) - Request validation
• validation_response(request_hash, response, response_uri=None, response_hash=None, tag=None) - Provide validation response
• get_validation_status(request_hash) - Get validation status
• get_summary(agent_id, validator_addresses=None, tag=None) - Get validation summary with optional filters
• get_agent_validations(agent_id) - Get all validations for agent
• get_validator_requests(validator_address) - Get all requests for a validator

IPFSClient

• upload(content, name, metadata) - Upload content
• upload_json(data, name, metadata) - Upload JSON
• pin(cid, name) - Pin existing CID
• fetch(cid_or_uri) - Fetch content
• fetch_json(cid_or_uri) - Fetch and parse JSON

Links

• ERC-8004 Specification
• GitHub Repository

License

MIT