# ERC-8004 Smart Contracts

**Repository:** https://github.com/erc-8004/erc-8004-contracts

All contracts are UUPS-upgradeable (OpenZeppelin v5.4.0), using ERC-7201 namespaced storage. Solidity 0.8.24, Shanghai EVM, optimizer enabled (200 runs, viaIR).

## Contract Addresses

Deterministic cross-chain vanity addresses via CREATE2 (SAFE Singleton Factory at `0x914d7Fec6aaC8cd542e72Bca78B30650d45643d7`).

### Mainnet (Ethereum, Base, Polygon, Arbitrum, Optimism, Avalanche, Celo, Gnosis, Linea, Mantle, MegaETH, Scroll, Taiko, Monad, BSC)

| Contract | Address |
|----------|---------|
| IdentityRegistry | `0x8004A169FB4a3325136EB29fA0ceB6D2e539a432` |
| ReputationRegistry | `0x8004BAa17C55a88189AE136b182e5fdA19dE9b63` |
| ValidationRegistry | `0x8004Cb1BF31DAf7788923b405b754f57acEB4272` |

### Testnet (Sepolia, Base Sepolia, + corresponding testnets)

| Contract | Address |
|----------|---------|
| IdentityRegistry | `0x8004A818BFB912233c491871b3d84c89A494BD9e` |
| ReputationRegistry | `0x8004B663056A597Dffe9eCcC1965A193B7388713` |
| ValidationRegistry | `0x8004Cb1BF31DAf7788923b405b754f57acEB4272` |

**Owner:** `0x547289319C3e6aedB179C0b8e8aF0B5ACd062603`

## IdentityRegistryUpgradeable

**Inherits:** `ERC721URIStorageUpgradeable`, `OwnableUpgradeable`, `UUPSUpgradeable`, `EIP712Upgradeable`

**Version:** 2.0.0

### Storage Layout

```solidity
// Slot 0 (shared with MinimalUUPS for upgrade persistence)
address private _identityRegistry;

// ERC-7201 namespaced storage
struct IdentityRegistryStorage {
    uint256 _lastId;
    mapping(uint256 => mapping(string => bytes)) _metadata;  // agentId => key => value
}
```

### Registration Functions

```solidity
// Mint without URI (set later via setAgentURI)
function register() external returns (uint256 agentId)

// Mint with URI
function register(string agentURI) external returns (uint256 agentId)

// Mint with URI and initial metadata
function register(string agentURI, MetadataEntry[] calldata metadata) external returns (uint256 agentId)

struct MetadataEntry {
    string metadataKey;
    bytes metadataValue;
}
```

All variants auto-set `agentWallet` metadata to `msg.sender`. The reserved `agentWallet` key is rejected in the metadata array.

### URI Management

```solidity
function setAgentURI(uint256 agentId, string calldata newURI) external
// Owner or operator only. Emits URIUpdated.
```

### Metadata Functions

```solidity
function getMetadata(uint256 agentId, string memory metadataKey) external view returns (bytes memory)
function setMetadata(uint256 agentId, string memory metadataKey, bytes memory metadataValue) external
// Owner or operator only. Reverts if metadataKey == "agentWallet".
```

### Agent Wallet (EIP-712 Verified)

```solidity
// Requires signature from newWallet (EIP-712 for EOA, ERC-1271 for smart contract wallet)
// Deadline max 5 minutes from current block.timestamp
function setAgentWallet(uint256 agentId, address newWallet, uint256 deadline, bytes calldata signature) external

function getAgentWallet(uint256 agentId) external view returns (address)

function unsetAgentWallet(uint256 agentId) external
```

EIP-712 domain: name `"ERC8004IdentityRegistry"`, version `"1"`. Typed data: `AgentWalletSet(uint256 agentId, address newWallet, address owner, uint256 deadline)`.

On NFT transfer, `agentWallet` is automatically cleared (Checks-Effects-Interactions pattern in `_update`).

### Authorization

```solidity
function isAuthorizedOrOwner(address spender, uint256 agentId) external view returns (bool)
// Used by Reputation and Validation registries to check permissions
```

### Events

```solidity
event Registered(uint256 indexed agentId, string agentURI, address indexed owner)
event MetadataSet(uint256 indexed agentId, string indexed indexedMetadataKey, string metadataKey, bytes metadataValue)
event URIUpdated(uint256 indexed agentId, string newURI, address indexed updatedBy)
```

## ReputationRegistryUpgradeable

**Inherits:** `OwnableUpgradeable`, `UUPSUpgradeable`

**Version:** 2.0.0

### Storage Layout

```solidity
struct Feedback {
    int128 value;       // signed fixed-point (max abs 1e38)
    uint8 valueDecimals; // 0-18
    bool isRevoked;
    string tag1;
    string tag2;
}

struct ReputationRegistryStorage {
    // agentId => clientAddr => feedbackIndex (1-indexed) => Feedback
    mapping(uint256 => mapping(address => mapping(uint64 => Feedback))) _feedback;
    mapping(uint256 => mapping(address => uint64)) _lastIndex;
    // Response tracking (counters only, not stored content)
    mapping(uint256 => mapping(address => mapping(uint64 => mapping(address => uint64)))) _responseCount;
    mapping(uint256 => mapping(address => mapping(uint64 => address[]))) _responders;
    mapping(uint256 => mapping(address => mapping(uint64 => mapping(address => bool)))) _responderExists;
    // Client tracking
    mapping(uint256 => address[]) _clients;
    mapping(uint256 => mapping(address => bool)) _clientExists;
}
```

### Write Functions

```solidity
function giveFeedback(
    uint256 agentId, int128 value, uint8 valueDecimals,
    string calldata tag1, string calldata tag2,
    string calldata endpoint, string calldata feedbackURI, bytes32 feedbackHash
) external
// Self-feedback rejected: calls isAuthorizedOrOwner() and reverts if true.
// endpoint, feedbackURI, feedbackHash emitted but NOT stored.

function revokeFeedback(uint256 agentId, uint64 feedbackIndex) external
// Only the original clientAddress can revoke.

function appendResponse(
    uint256 agentId, address clientAddress, uint64 feedbackIndex,
    string calldata responseURI, bytes32 responseHash
) external
// Anyone can respond. Only counters tracked, not content.
```

### Read Functions

```solidity
function readFeedback(uint256 agentId, address clientAddress, uint64 feedbackIndex)
    external view returns (int128 value, uint8 valueDecimals, string tag1, string tag2, bool isRevoked)
// feedbackIndex is 1-indexed

function getSummary(uint256 agentId, address[] calldata clientAddresses, string tag1, string tag2)
    external view returns (uint64 count, int128 summaryValue, uint8 summaryValueDecimals)
// clientAddresses MUST be non-empty - REVERTS if empty (Sybil protection).
// Callers must supply a trusted reviewer list.
// Empty strings for tag1/tag2 act as wildcards.
// Aggregation: normalizes to 18-decimal WAD, averages, scales to mode precision.

function readAllFeedback(uint256 agentId, address[] calldata clientAddresses,
    string tag1, string tag2, bool includeRevoked) external view returns (...)
// If clientAddresses is empty, uses all tracked clients.

function getResponseCount(uint256 agentId, address clientAddress,
    uint64 feedbackIndex, address[] responders) external view returns (uint64)
// address(0) = all clients; feedbackIndex 0 = all feedbacks.

function getClients(uint256 agentId) external view returns (address[] memory)
function getLastIndex(uint256 agentId, address clientAddress) external view returns (uint64)
```

### Events

```solidity
event NewFeedback(uint256 indexed agentId, address indexed clientAddress, uint64 feedbackIndex,
    int128 value, uint8 valueDecimals, string indexed indexedTag1,
    string tag1, string tag2, string endpoint, string feedbackURI, bytes32 feedbackHash)
event FeedbackRevoked(uint256 indexed agentId, address indexed clientAddress, uint64 indexed feedbackIndex)
event ResponseAppended(uint256 indexed agentId, address indexed clientAddress,
    uint64 feedbackIndex, address indexed responder, string responseURI, bytes32 responseHash)
```

## ValidationRegistryUpgradeable

**Inherits:** `OwnableUpgradeable`, `UUPSUpgradeable`

**Version:** 2.0.0

### Storage Layout

```solidity
struct ValidationStatus {
    address validatorAddress;
    uint256 agentId;
    uint8 response;        // 0-100
    bytes32 responseHash;
    string tag;
    uint256 lastUpdate;
    bool hasResponse;
}

struct ValidationRegistryStorage {
    mapping(bytes32 => ValidationStatus) validations;        // requestHash => status
    mapping(uint256 => bytes32[]) _agentValidations;         // agentId => requestHashes
    mapping(address => bytes32[]) _validatorRequests;        // validatorAddress => requestHashes
}
```

### Functions

```solidity
function validationRequest(
    address validatorAddress, uint256 agentId,
    string requestURI, bytes32 requestHash
) external
// Must be called by owner/operator. Duplicate requestHash rejected.

function validationResponse(
    bytes32 requestHash, uint8 response,
    string responseURI, bytes32 responseHash, string tag
) external
// Must be called by the validatorAddress from the request.
// response: 0=failed, 100=passed, intermediate for spectrum.
// Can be called multiple times (progressive finality via tag).

function getValidationStatus(bytes32 requestHash)
    external view returns (address, uint256, uint8, bytes32, string, uint256)

function getSummary(uint256 agentId, address[] calldata validatorAddresses, string tag)
    external view returns (uint64 count, uint8 avgResponse)
// ACCEPTS empty validatorAddresses (includes ALL validators - no filter).
// This differs from ReputationRegistry.getSummary() which REVERTS on empty.
// Only counts requests with hasResponse == true.

function getAgentValidations(uint256 agentId) external view returns (bytes32[] memory)
function getValidatorRequests(address validatorAddress) external view returns (bytes32[] memory)
```

### Events

```solidity
event ValidationRequest(address indexed validatorAddress, uint256 indexed agentId,
    string requestURI, bytes32 indexed requestHash)
event ValidationResponse(address indexed validatorAddress, uint256 indexed agentId,
    bytes32 indexed requestHash, uint8 response,
    string responseURI, bytes32 responseHash, string tag)
```

## Deployment Architecture

### Two-Phase Vanity Deployment

1. Deploy `MinimalUUPS` via CREATE2 (stores `_identityRegistry` at slot 0)
2. Deploy three vanity proxies via CREATE2 pointing to MinimalUUPS
3. Deploy three real implementations via CREATE2
4. Upgrade proxies to real implementations (slot 0 data persists)

This enables deterministic vanity addresses across all EVM chains.

### Dependencies

- OpenZeppelin Contracts Upgradeable v5.4.0
- SAFE Singleton Factory (`0x914d7Fec6aaC8cd542e72Bca78B30650d45643d7`)
- Hardhat v3 with viem v2.38 for testing/deployment

### ABI Files

Pre-built ABI JSON files available in the contracts repository:
- `abis/IdentityRegistry.json`
- `abis/ReputationRegistry.json`
- `abis/ValidationRegistry.json`

# OASF Taxonomy v0.8.0

Open Agentic Schema Framework - standardized skills (136) and domains (204) for agent classification. Use slash-separated slugs with `agent.addSkill()` / `agent.addDomain()`.

Source: https://github.com/agntcy/oasf

## Skills (136 total)

### advanced_reasoning_planning

| Slug | Description |
|------|-------------|
| `advanced_reasoning_planning/advanced_reasoning_planning` | (category root) |
| `advanced_reasoning_planning/chain_of_thought_structuring` | Organizing intermediate reasoning steps into clear, justifiable sequences |
| `advanced_reasoning_planning/hypothesis_generation` | Proposing plausible explanations or solution pathways for incomplete or uncertain scenarios |
| `advanced_reasoning_planning/long_horizon_reasoning` | Maintaining coherent reasoning chains over extended sequences of steps or time |
| `advanced_reasoning_planning/strategic_planning` | Formulating high-level multi-phase strategies aligned with long-term objectives |

### agent_orchestration

| Slug | Description |
|------|-------------|
| `agent_orchestration/agent_orchestration` | (category root) |
| `agent_orchestration/agent_coordination` | Managing real-time collaboration and state synchronization among agents |
| `agent_orchestration/multi_agent_planning` | Coordinating plans across multiple agents, resolving dependencies and optimizing sequencing |
| `agent_orchestration/negotiation_resolution` | Facilitating negotiation, conflict handling, and consensus-building between agents |
| `agent_orchestration/role_assignment` | Allocating responsibilities to agents based on capabilities and task requirements |
| `agent_orchestration/task_decomposition` | Breaking complex objectives into structured, atomic subtasks |

### analytical_skills

| Slug | Description |
|------|-------------|
| `analytical_skills/analytical_skills` | (category root) |
| `analytical_skills/coding_skills/coding_skills` | Capabilities for code generation, documentation, and optimization |
| `analytical_skills/coding_skills/code_optimization` | Rewriting and optimizing existing code through refactoring techniques |
| `analytical_skills/coding_skills/code_templates` | Automatically filling in code templates with appropriate content |
| `analytical_skills/coding_skills/code_to_docstrings` | Generating natural language documentation for code segments |
| `analytical_skills/coding_skills/text_to_code` | Translating natural language instructions into executable code |
| `analytical_skills/mathematical_reasoning/mathematical_reasoning` | Capabilities for solving mathematical problems and proving theorems |
| `analytical_skills/mathematical_reasoning/geometry` | Solving geometric problems and spatial reasoning tasks |
| `analytical_skills/mathematical_reasoning/math_word_problems` | Solving mathematical exercises presented in natural language format |
| `analytical_skills/mathematical_reasoning/pure_math_operations` | Executing pure mathematical operations, such as arithmetic calculations |
| `analytical_skills/mathematical_reasoning/theorem_proving` | Proving mathematical theorems using computational methods |

### audio

| Slug | Description |
|------|-------------|
| `audio/audio` | (category root) |
| `audio/audio_classification` | Assigning labels or classes to audio content based on its characteristics |
| `audio/audio_to_audio` | Transforming audio through various manipulations including cutting, filtering, and mixing |

### data_engineering

| Slug | Description |
|------|-------------|
| `data_engineering/data_engineering` | (category root) |
| `data_engineering/data_cleaning` | Detecting and correcting errors, inconsistencies, and missing values |
| `data_engineering/data_quality_assessment` | Evaluating datasets for completeness, validity, consistency, and timeliness |
| `data_engineering/data_transformation_pipeline` | Designing multi-step sequences that extract, transform, and load datasets |
| `data_engineering/feature_engineering` | Constructing informative transformed variables to improve model performance |
| `data_engineering/schema_inference` | Deriving structural metadata (fields, types, relationships) from raw data |

### devops_mlops

| Slug | Description |
|------|-------------|
| `devops_mlops/devops_mlops` | (category root) |
| `devops_mlops/ci_cd_configuration` | Designing or modifying continuous integration and delivery workflows |
| `devops_mlops/deployment_orchestration` | Coordinating multi-stage deployments, rollbacks, and version transitions |
| `devops_mlops/infrastructure_provisioning` | Allocating and configuring compute, storage, and networking resources |
| `devops_mlops/model_versioning` | Tracking, promoting, and documenting different iterations of models |
| `devops_mlops/monitoring_alerting` | Configuring and interpreting telemetry signals, thresholds, and alerts |

### evaluation_monitoring

| Slug | Description |
|------|-------------|
| `evaluation_monitoring/evaluation_monitoring` | (category root) |
| `evaluation_monitoring/anomaly_detection` | Identifying unusual patterns, drifts, or deviations in data or model outputs |
| `evaluation_monitoring/benchmark_execution` | Running standardized benchmarks or evaluation suites |
| `evaluation_monitoring/performance_monitoring` | Tracking latency, throughput, resource utilization, and reliability |
| `evaluation_monitoring/quality_evaluation` | Assessing outputs for accuracy, relevance, coherence, safety, and style |
| `evaluation_monitoring/test_case_generation` | Creating targeted test inputs or scenarios to probe system behavior |

### governance_compliance

| Slug | Description |
|------|-------------|
| `governance_compliance/governance_compliance` | (category root) |
| `governance_compliance/audit_trail_summarization` | Condensing event/transaction logs into human-readable compliance summaries |
| `governance_compliance/compliance_assessment` | Evaluating against standards (GDPR, HIPAA) and identifying gaps |
| `governance_compliance/policy_mapping` | Translating policies into structured, enforceable rules or checklists |
| `governance_compliance/risk_classification` | Categorizing risks by impact and likelihood for prioritization |

### images_computer_vision

| Slug | Description |
|------|-------------|
| `images_computer_vision/images_computer_vision` | (category root) |
| `images_computer_vision/depth_estimation` | Predicting distance or depth of objects within a scene |
| `images_computer_vision/image_classification` | Assigning labels or categories to images |
| `images_computer_vision/image_feature_extraction` | Identifying and isolating key characteristics from images |
| `images_computer_vision/image_generation` | Creating new images from learned patterns |
| `images_computer_vision/image_segmentation` | Pixel-level classification of image regions |
| `images_computer_vision/image_to_3d` | Converting 2D images into 3D representations |
| `images_computer_vision/image_to_image` | Transforming images (style transfer, colorization, enhancement) |
| `images_computer_vision/keypoint_detection` | Identifying specific points of interest within images |
| `images_computer_vision/mask_generation` | Producing segmented regions to highlight specific areas |
| `images_computer_vision/object_detection` | Identifying and locating objects with bounding boxes |
| `images_computer_vision/video_classification` | Assigning labels to videos or segments |

### multi_modal

| Slug | Description |
|------|-------------|
| `multi_modal/multi_modal` | (category root) |
| `multi_modal/any_to_any` | Converting between any supported modalities |
| `multi_modal/audio_processing/audio_processing` | Audio processing capabilities |
| `multi_modal/audio_processing/speech_recognition` | Converting spoken language into written text |
| `multi_modal/audio_processing/text_to_speech` | Converting text into natural-sounding speech |
| `multi_modal/image_processing/image_processing` | Image processing and generation capabilities |
| `multi_modal/image_processing/image_to_text` | Generating textual descriptions for images |
| `multi_modal/image_processing/text_to_3d` | Generating 3D objects from text descriptions |
| `multi_modal/image_processing/text_to_image` | Generating images from text descriptions |
| `multi_modal/image_processing/text_to_video` | Generating video from text descriptions |
| `multi_modal/image_processing/visual_qa` | Answering questions about images |

### natural_language_processing

| Slug | Description |
|------|-------------|
| `natural_language_processing/natural_language_processing` | (category root) |
| **analytical_reasoning** | |
| `natural_language_processing/analytical_reasoning/analytical_reasoning` | Logical analysis, inference, and problem-solving |
| `natural_language_processing/analytical_reasoning/fact_verification` | Verifying facts and claims given reference text |
| `natural_language_processing/analytical_reasoning/inference_deduction` | Making logical inferences from provided information |
| `natural_language_processing/analytical_reasoning/problem_solving` | Generating potential solutions or strategies |
| **creative_content** | |
| `natural_language_processing/creative_content/creative_content` | Creative content generation |
| `natural_language_processing/creative_content/poetry_writing` | Composing poems, prose, or creative literature |
| `natural_language_processing/creative_content/storytelling` | Creating narratives and fictional content |
| **ethical_interaction** | |
| `natural_language_processing/ethical_interaction/ethical_interaction` | Ethical and safe interaction |
| `natural_language_processing/ethical_interaction/bias_mitigation` | Reducing biased language, ensuring fair output |
| `natural_language_processing/ethical_interaction/content_moderation` | Avoiding harmful or inappropriate content |
| **feature_extraction** | |
| `natural_language_processing/feature_extraction/feature_extraction` | Textual feature extraction |
| `natural_language_processing/feature_extraction/model_feature_extraction` | Representing text as vectors for downstream tasks |
| **information_retrieval_synthesis** | |
| `natural_language_processing/information_retrieval_synthesis/information_retrieval_synthesis` | Information retrieval and synthesis |
| `natural_language_processing/information_retrieval_synthesis/document_passage_retrieval` | Retrieving relevant documents or passages |
| `natural_language_processing/information_retrieval_synthesis/fact_extraction` | Extracting factual information from text |
| `natural_language_processing/information_retrieval_synthesis/knowledge_synthesis` | Aggregating information from multiple sources |
| `natural_language_processing/information_retrieval_synthesis/question_answering` | Understanding questions and providing answers |
| `natural_language_processing/information_retrieval_synthesis/search` | Efficient search within textual databases |
| `natural_language_processing/information_retrieval_synthesis/sentence_similarity` | Determining semantic similarity between sentences |
| **language_translation** | |
| `natural_language_processing/language_translation/language_translation` | Translation and multilingual support |
| `natural_language_processing/language_translation/multilingual_understanding` | Processing text in multiple languages |
| `natural_language_processing/language_translation/translation` | Converting text between languages |
| **natural_language_generation** | |
| `natural_language_processing/natural_language_generation/natural_language_generation` | Text generation from data or inputs |
| `natural_language_processing/natural_language_generation/dialogue_generation` | Producing conversational responses |
| `natural_language_processing/natural_language_generation/paraphrasing` | Rewriting text with different words, same meaning |
| `natural_language_processing/natural_language_generation/question_generation` | Generating questions from text |
| `natural_language_processing/natural_language_generation/story_generation` | Generating text from a description or first sentence |
| `natural_language_processing/natural_language_generation/style_transfer` | Rewriting text to match a given style |
| `natural_language_processing/natural_language_generation/summarization` | Condensing text while preserving essential information |
| `natural_language_processing/natural_language_generation/text_completion` | Continuing text in a coherent manner |
| **natural_language_understanding** | |
| `natural_language_processing/natural_language_understanding/natural_language_understanding` | Interpreting and comprehending language |
| `natural_language_processing/natural_language_understanding/contextual_comprehension` | Understanding context and nuances |
| `natural_language_processing/natural_language_understanding/entity_recognition` | Identifying key entities (names, dates, locations) |
| `natural_language_processing/natural_language_understanding/semantic_understanding` | Grasping meaning and intent |
| **personalization** | |
| `natural_language_processing/personalization/personalization` | Personalisation and adaptation |
| `natural_language_processing/personalization/style_adjustment` | Modifying tone or style for specific audiences |
| `natural_language_processing/personalization/user_adaptation` | Tailoring responses based on user preferences |
| **text_classification** | |
| `natural_language_processing/text_classification/text_classification` | Text classification and categorization |
| `natural_language_processing/text_classification/natural_language_inference` | Classifying relations between texts (contradiction, entailment) |
| `natural_language_processing/text_classification/sentiment_analysis` | Classifying sentiment of text |
| `natural_language_processing/text_classification/topic_labeling` | Classifying text by topic |
| **token_classification** | |
| `natural_language_processing/token_classification/token_classification` | Token-level classification |
| `natural_language_processing/token_classification/named_entity_recognition` | Recognizing named entities |
| `natural_language_processing/token_classification/pos_tagging` | Part-of-speech tagging |

### retrieval_augmented_generation

| Slug | Description |
|------|-------------|
| `retrieval_augmented_generation/retrieval_augmented_generation` | (category root) |
| `retrieval_augmented_generation/document_or_database_question_answering` | Retrieving info from documents/databases to answer questions |
| `retrieval_augmented_generation/generation_of_any` | Augmenting creation of text/images/audio with retrieved information |
| `retrieval_augmented_generation/retrieval_of_information/retrieval_of_information` | Fetching relevant data from datasets |
| `retrieval_augmented_generation/retrieval_of_information/document_retrieval` | Retrieving relevant documents from collections |
| `retrieval_augmented_generation/retrieval_of_information/indexing` | Indexing data for efficient retrieval |
| `retrieval_augmented_generation/retrieval_of_information/search` | Exploring datasets to find relevant information |

### security_privacy

| Slug | Description |
|------|-------------|
| `security_privacy/security_privacy` | (category root) |
| `security_privacy/privacy_risk_assessment` | Evaluating data handling for potential privacy risks |
| `security_privacy/secret_leak_detection` | Scanning for exposed credentials, tokens, or secrets |
| `security_privacy/threat_detection` | Identifying indicators of malicious activity |
| `security_privacy/vulnerability_analysis` | Reviewing code/configs for security weaknesses |

### tabular_text

| Slug | Description |
|------|-------------|
| `tabular_text/tabular_text` | (category root) |
| `tabular_text/tabular_classification` | Classifying data based on tabular attributes |
| `tabular_text/tabular_regression` | Predicting numerical values from tabular features |

### tool_interaction

| Slug | Description |
|------|-------------|
| `tool_interaction/tool_interaction` | (category root) |
| `tool_interaction/api_schema_understanding` | Interpreting API specs, endpoints, parameters |
| `tool_interaction/script_integration` | Linking scripts with external tools |
| `tool_interaction/tool_use_planning` | Selecting and ordering tool invocations |
| `tool_interaction/workflow_automation` | Designing automated multi-tool sequences |

---

## Domains (204 total)

### agriculture

| Slug | Description |
|------|-------------|
| `agriculture/agriculture` | (category root) |
| `agriculture/agricultural_technology` | Drones, IoT, and automation in farming |
| `agriculture/crop_management` | Planning, monitoring, and optimizing crop production |
| `agriculture/livestock_management` | Care, breeding, and management of farm animals |
| `agriculture/precision_agriculture` | Data-driven farming using sensors, GPS, and analytics |
| `agriculture/sustainable_farming` | Environmentally responsible agricultural practices |

### education

| Slug | Description |
|------|-------------|
| `education/education` | (category root) |
| `education/curriculum_design` | Creating structured educational content |
| `education/e_learning` | Digital platforms and online courses |
| `education/educational_technology` | Digital tools to enhance teaching and learning |
| `education/learning_management_systems` | Software for delivering and tracking courses |
| `education/pedagogy` | Methods and practices of teaching |

### energy

| Slug | Description |
|------|-------------|
| `energy/energy` | (category root) |
| `energy/energy_management` | Optimization of energy consumption and efficiency |
| `energy/energy_storage` | Battery systems, pumped hydro, and storage tech |
| `energy/oil_and_gas` | Exploration, extraction, refining, and distribution |
| `energy/power_generation` | Electricity generation from various sources |
| `energy/renewable_energy` | Solar, wind, hydro, and sustainable energy |
| `energy/smart_grids` | Intelligent power distribution networks |

### environmental_science

| Slug | Description |
|------|-------------|
| `environmental_science/environmental_science` | (category root) |
| `environmental_science/climate_science` | Climate modeling, change research, atmospheric science |
| `environmental_science/conservation_biology` | Species conservation, habitat protection, biodiversity |
| `environmental_science/ecology` | Ecosystem science, ecological modeling |
| `environmental_science/environmental_monitoring` | Air/water quality, pollution tracking |
| `environmental_science/environmental_policy` | Regulations, policy development, environmental law |
| `environmental_science/sustainability` | Carbon footprint reduction, circular economy, green tech |

### finance_and_business

| Slug | Description |
|------|-------------|
| `finance_and_business/finance_and_business` | (category root) |
| `finance_and_business/banking` | Retail, investment, corporate, and digital banking |
| `finance_and_business/consumer_goods` | Product development, consumer behavior, marketing |
| `finance_and_business/finance` | Corporate finance, risk management, accounting |
| `finance_and_business/investment_services` | Asset management, advisory, financial planning |
| `finance_and_business/retail` | E-commerce, in-store, inventory, omnichannel |

### government_and_public_sector

| Slug | Description |
|------|-------------|
| `government_and_public_sector/government_and_public_sector` | (category root) |
| `government_and_public_sector/civic_engagement` | Citizen participation, community outreach |
| `government_and_public_sector/e_government` | Digital government services and portals |
| `government_and_public_sector/emergency_management` | Disaster response, crisis management |
| `government_and_public_sector/public_administration` | Government operations, civil service |
| `government_and_public_sector/public_infrastructure` | Infrastructure planning, public works |
| `government_and_public_sector/public_policy` | Policy development, legislative processes |

### healthcare

| Slug | Description |
|------|-------------|
| `healthcare/healthcare` | (category root) |
| `healthcare/health_information_systems` | Systems for managing healthcare data |
| `healthcare/healthcare_informatics` | Health data analytics, clinical informatics |
| `healthcare/medical_technology` | Medical devices, diagnostics, wearable health tech |
| `healthcare/patient_management_systems` | Scheduling, portals, billing, health records |
| `healthcare/telemedicine` | Remote consultation, telehealth platforms |

### hospitality_and_tourism

| Slug | Description |
|------|-------------|
| `hospitality_and_tourism/hospitality_and_tourism` | (category root) |
| `hospitality_and_tourism/event_planning` | Conference management, venue coordination |
| `hospitality_and_tourism/food_and_beverage` | Restaurant management, catering, menu planning |
| `hospitality_and_tourism/hospitality_technology` | PMS, booking engines, guest experience platforms |
| `hospitality_and_tourism/hotel_management` | Hotel operations, reservations, guest services |
| `hospitality_and_tourism/tourism_management` | Destinations, attractions, tourism marketing |
| `hospitality_and_tourism/travel_services` | Travel booking, itinerary planning |

### human_resources

| Slug | Description |
|------|-------------|
| `human_resources/human_resources` | (category root) |
| `human_resources/compensation_and_benefits` | Salary structures, bonuses, benefits |
| `human_resources/employee_relations` | Conflict resolution, engagement, workplace culture |
| `human_resources/hr_analytics` | People analytics, workforce metrics |
| `human_resources/recruitment` | Talent acquisition, sourcing, onboarding |
| `human_resources/training_and_development` | Skills training, leadership development |

### industrial_manufacturing

| Slug | Description |
|------|-------------|
| `industrial_manufacturing/industrial_manufacturing` | (category root) |
| `industrial_manufacturing/automation` | Automated manufacturing, control systems, industrial IoT |
| `industrial_manufacturing/lean_manufacturing` | Continuous improvement, Six Sigma, Kaizen |
| `industrial_manufacturing/process_engineering` | Process design, optimization, quality control |
| `industrial_manufacturing/robotics` | Industrial robotics, RPA, collaborative robots |
| `industrial_manufacturing/supply_chain_management` | Inventory, procurement, logistics, demand forecasting |

### insurance

| Slug | Description |
|------|-------------|
| `insurance/insurance` | (category root) |
| `insurance/actuarial_science` | Risk modeling, statistical modeling, pricing |
| `insurance/claims_processing` | Claims management, loss adjustment, automation |
| `insurance/insurance_sales` | Agent management, distribution, customer acquisition |
| `insurance/insurtech` | Digital insurance platforms, telematics, innovation |
| `insurance/policy_management` | Policy administration, renewals, endorsements |
| `insurance/underwriting` | Risk assessment, policy pricing, automation |

### legal

| Slug | Description |
|------|-------------|
| `legal/legal` | (category root) |
| `legal/contract_law` | Agreements and contracts between parties |
| `legal/corporate_governance` | Directing and controlling corporations |
| `legal/intellectual_property` | Patents, trademarks, copyrights, trade secrets |
| `legal/legal_research` | Precedents, statutes, and case law |
| `legal/litigation` | Legal proceedings and dispute resolution |
| `legal/regulatory_compliance` | Adherence to laws and industry standards |

### life_science

| Slug | Description |
|------|-------------|
| `life_science/life_science` | (category root) |
| `life_science/bioinformatics` | Computational analysis of biological data |
| `life_science/biotechnology` | Biological systems for products and technologies |
| `life_science/genomics` | Genetic structure, function, and evolution |
| `life_science/molecular_biology` | DNA, RNA, proteins, and cell signaling |
| `life_science/pharmaceutical_research` | Drug discovery, clinical trials, pharmacology |

### marketing_and_advertising

| Slug | Description |
|------|-------------|
| `marketing_and_advertising/marketing_and_advertising` | (category root) |
| `marketing_and_advertising/advertising` | Ad campaigns, media buying, creative development |
| `marketing_and_advertising/brand_management` | Brand strategy, identity, positioning |
| `marketing_and_advertising/digital_marketing` | SEO, SEM, content marketing, social media |
| `marketing_and_advertising/market_research` | Consumer research, competitive intelligence |
| `marketing_and_advertising/marketing_analytics` | Metrics, ROI analysis, attribution modeling |
| `marketing_and_advertising/marketing_automation` | Campaign automation, lead nurturing |

### media_and_entertainment

| Slug | Description |
|------|-------------|
| `media_and_entertainment/media_and_entertainment` | (category root) |
| `media_and_entertainment/broadcasting` | Radio and television systems |
| `media_and_entertainment/content_creation` | Video, audio, and written media production |
| `media_and_entertainment/digital_media` | Social media, blogs, podcasts |
| `media_and_entertainment/gaming` | Video game development, esports |
| `media_and_entertainment/publishing` | Book, magazine, and digital publishing |
| `media_and_entertainment/streaming_services` | On-demand video and audio platforms |

### real_estate

| Slug | Description |
|------|-------------|
| `real_estate/real_estate` | (category root) |
| `real_estate/construction` | Building construction and project management |
| `real_estate/facilities_management` | Building operations and maintenance |
| `real_estate/property_management` | Residential and commercial property management |
| `real_estate/proptech` | Smart buildings and real estate platforms |
| `real_estate/real_estate_investment` | Investment strategies and portfolio management |
| `real_estate/urban_planning` | City planning, zoning, urban development |

### research_and_development

| Slug | Description |
|------|-------------|
| `research_and_development/research_and_development` | (category root) |
| `research_and_development/grant_management` | Research funding, grant applications |
| `research_and_development/innovation_management` | Innovation processes, technology transfer |
| `research_and_development/laboratory_management` | Lab operations, equipment, safety protocols |
| `research_and_development/product_development` | Product design, prototyping, testing |
| `research_and_development/research_data_management` | Data storage, research databases, sharing |
| `research_and_development/scientific_research` | Methodology, experimental design, data collection |

### retail_and_ecommerce

| Slug | Description |
|------|-------------|
| `retail_and_ecommerce/retail_and_ecommerce` | (category root) |
| `retail_and_ecommerce/customer_experience` | Personalization, loyalty, shopping optimization |
| `retail_and_ecommerce/inventory_management` | Stock control, warehouse management |
| `retail_and_ecommerce/online_retail` | E-commerce platforms, digital marketplaces |
| `retail_and_ecommerce/order_fulfillment` | Order processing, shipping, returns |
| `retail_and_ecommerce/point_of_sale` | POS systems, payment processing |
| `retail_and_ecommerce/retail_analytics` | Sales analytics, customer insights |

### social_services

| Slug | Description |
|------|-------------|
| `social_services/social_services` | (category root) |
| `social_services/case_management` | Client case tracking, service coordination |
| `social_services/child_and_family_services` | Child welfare, foster care, adoption |
| `social_services/community_outreach` | Community programs and engagement |
| `social_services/disability_services` | Disability support, accessibility, assistive technology |
| `social_services/housing_assistance` | Homeless services, emergency shelter |
| `social_services/mental_health_services` | Counseling, crisis intervention |

### sports_and_fitness

| Slug | Description |
|------|-------------|
| `sports_and_fitness/sports_and_fitness` | (category root) |
| `sports_and_fitness/athletic_training` | Performance training, coaching, athlete development |
| `sports_and_fitness/fitness_and_wellness` | Fitness programs, wellness coaching |
| `sports_and_fitness/sports_analytics` | Performance metrics, game analysis |
| `sports_and_fitness/sports_management` | Team management, facilities, event organization |
| `sports_and_fitness/sports_medicine` | Injury prevention, rehabilitation |
| `sports_and_fitness/sports_technology` | Wearables, performance tracking systems |

### technology

| Slug | Description |
|------|-------------|
| `technology/technology` | (category root) |
| **automation** | |
| `technology/automation/automation` | Process automation with minimal human intervention |
| `technology/automation/rpa` | Robotic Process Automation for repetitive tasks |
| `technology/automation/workflow_automation` | Automated business process sequences |
| **blockchain** | |
| `technology/blockchain/blockchain` | Distributed ledger technology |
| `technology/blockchain/cryptocurrency` | Digital currency secured by cryptography |
| `technology/blockchain/defi` | Decentralized finance services on blockchain |
| `technology/blockchain/smart_contracts` | Self-executing contracts on blockchain |
| **cloud_computing** | |
| `technology/cloud_computing/cloud_computing` | Computing services over the internet |
| `technology/cloud_computing/aws` | Amazon Web Services |
| `technology/cloud_computing/azure` | Microsoft Azure |
| `technology/cloud_computing/gcp` | Google Cloud Platform |
| **communication_systems** | |
| `technology/communication_systems/communication_systems` | Information transmission technologies |
| `technology/communication_systems/broadcasting_systems` | Distributing content to large audiences |
| `technology/communication_systems/signal_processing` | Analysis and modification of signals |
| `technology/communication_systems/telecommunication` | Long-distance information transmission |
| `technology/communication_systems/wireless_communication` | Communication without physical connections |
| **data_science** | |
| `technology/data_science/data_science` | Extracting insights from data |
| `technology/data_science/big_data` | Large/complex datasets requiring advanced tools |
| `technology/data_science/data_engineering` | Systems for collecting, storing, processing data |
| `technology/data_science/data_visualization` | Graphical representation of data |
| **information_technology** | |
| `technology/information_technology/information_technology` | Managing technology systems |
| `technology/information_technology/database_administration` | Database management and maintenance |
| `technology/information_technology/help_desk_support` | Technical support for end users |
| `technology/information_technology/performance_analysis` | System performance optimization |
| `technology/information_technology/system_administration` | Computer systems and servers management |
| **iot** | |
| `technology/iot/iot` | Internet of Things |
| `technology/iot/industrial_iot` | IoT in industrial settings |
| `technology/iot/iot_devices` | Devices with sensors and connectivity |
| `technology/iot/iot_networks` | Communication protocols for IoT |
| `technology/iot/iot_security` | Protection of IoT devices and networks |
| `technology/iot/smart_homes` | Residential IoT environments |
| **networking** | |
| `technology/networking/networking` | Computer network design and management |
| `technology/networking/network_architecture` | Network topology, protocols, and components |
| `technology/networking/network_management` | Monitoring, configuring, and optimizing networks |
| `technology/networking/network_operations` | Smooth operation of network infrastructure |
| `technology/networking/network_protocols` | Rules governing device communication |
| `technology/networking/network_security` | Protection from unauthorized access |
| **security** | |
| `technology/security/security` | Protecting systems from cyber threats |
| `technology/security/application_security` | Protecting applications from threats |
| `technology/security/cyber_network_security` | Network protection from attacks |
| `technology/security/cybersecurity` | Protection from digital attacks |
| `technology/security/data_security` | Digital data protection throughout lifecycle |
| `technology/security/identity_management` | Managing digital identities and access |
| `technology/security/incident_management` | Detecting and resolving security incidents |
| **software_engineering** | |
| `technology/software_engineering/software_engineering` | Software design, development, and maintenance |
| `technology/software_engineering/apis_integration` | APIs and integration technologies |
| `technology/software_engineering/devops` | Development + operations practices |
| `technology/software_engineering/mlops` | ML + DevOps lifecycle management |
| `technology/software_engineering/quality_assurance` | Testing, code review, quality standards |
| `technology/software_engineering/software_development` | Designing, creating, testing software |

### telecommunications

| Slug | Description |
|------|-------------|
| `telecommunications/telecommunications` | (category root) |
| `telecommunications/internet_services` | ISP operations, broadband, connectivity |
| `telecommunications/iot_connectivity` | IoT networks, M2M, NB-IoT, LoRaWAN |
| `telecommunications/network_infrastructure` | Fiber optics, network equipment |
| `telecommunications/telecom_operations` | Service provisioning, billing, customer management |
| `telecommunications/voip_and_unified_communications` | VoIP, video conferencing, collaboration |
| `telecommunications/wireless_communications` | Mobile networks, 5G/6G, cellular services |

### transportation

| Slug | Description |
|------|-------------|
| `transportation/transportation` | (category root) |
| `transportation/automotive` | Vehicle design, engineering, manufacturing |
| `transportation/autonomous_vehicles` | Self-driving technology and vehicle AI |
| `transportation/freight` | Freight forwarding, cargo management |
| `transportation/logistics` | Warehousing, distribution, transportation planning |
| `transportation/public_transit` | Urban transit, rail, bus networks |
| `transportation/supply_chain` | Production, processing, distribution of goods |

### trust_and_safety

| Slug | Description |
|------|-------------|
| `trust_and_safety/trust_and_safety` | (category root) |
| `trust_and_safety/content_moderation` | Reviewing user content against guidelines |
| `trust_and_safety/data_privacy` | Personal information protection and compliance |
| `trust_and_safety/fraud_prevention` | Identifying and stopping fraudulent activities |
| `trust_and_safety/online_safety` | Protecting internet users from harm |
| `trust_and_safety/risk_management` | Identifying, assessing, and prioritizing risks |

# Agent Registration Best Practices

**Source:** https://github.com/erc-8004/best-practices

## Registration File Format

Every agent's `agentURI` MUST resolve to a JSON file with this structure:

```json
{
  "type": "https://eips.ethereum.org/EIPS/eip-8004#registration-v1",
  "name": "CryptoTrader Alpha",
  "description": "AI agent that analyzes crypto markets using on-chain data. Supports real-time price feeds, portfolio analysis, and trading signals. Pricing: $0.01 per request via x402. Interact via MCP tools or A2A tasks.",
  "image": "https://example.com/cryptotrader-alpha.png",
  "services": [
    {
      "name": "MCP",
      "endpoint": "https://mcp.cryptotrader.example.com",
      "version": "2025-06-18",
      "mcpTools": ["get_price", "analyze_portfolio", "trading_signal"]
    },
    {
      "name": "A2A",
      "endpoint": "https://cryptotrader.example.com/.well-known/agent-card.json",
      "version": "0.3.0",
      "a2aSkills": ["analytical_skills/mathematical_reasoning/quantitative_analysis"]
    },
    {
      "name": "OASF",
      "endpoint": "https://github.com/agntcy/oasf/",
      "version": "v0.8.0",
      "skills": [
        "analytical_skills/mathematical_reasoning/quantitative_analysis",
        "data_engineering/data_transformation_pipeline"
      ],
      "domains": [
        "finance_and_business/investment_services",
        "technology/blockchain_and_web3"
      ]
    },
    {
      "name": "ENS",
      "endpoint": "cryptotrader.eth",
      "version": "v1"
    },
    {
      "name": "agentWallet",
      "endpoint": "eip155:8453:0x1234567890abcdef1234567890abcdef12345678"
    },
    {
      "name": "web",
      "endpoint": "https://cryptotrader.example.com"
    },
    {
      "name": "email",
      "endpoint": "support@cryptotrader.example.com"
    }
  ],
  "registrations": [
    {
      "agentId": 42,
      "agentRegistry": "eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432"
    }
  ],
  "supportedTrust": ["reputation"],
  "active": true,
  "x402Support": true
}
```

## The Four Golden Rules

### Rule 1: Name, Image, Description

- **Name**: Clear and memorable. Should convey what the agent does.
- **Image**: PNG, SVG, or WebP. High quality, distinctive. This is how the agent appears in NFT apps and catalogs.
- **Description**: Elevator pitch covering:
  - What the agent does
  - How to interact with it
  - Pricing information
  - Key capabilities

### Rule 2: Always Include a Service

At minimum, one service endpoint. Service-specific guidelines:

**MCP service:**
- Include `mcpTools` array listing tool names
- Set `version` to the MCP protocol version (e.g., `"2025-06-18"`)

**A2A service:**
- Set `endpoint` to the agent card URL (`/.well-known/agent-card.json`)
- Include `a2aSkills` using OASF slash-separated identifiers

**ENS service:**
- `endpoint` is the ENS name (e.g., `"myagent.eth"`)

**DID service:**
- `endpoint` is the full DID string (e.g., `"did:ethr:0x..."`)

**agentWallet service:**
- Format: `eip155:{chainId}:{address}`
- Can advertise wallets on chains other than where registered

### Rule 3: Declare Skills and Domains Using OASF

OASF (Open Agentic Schema Framework, Linux Foundation) provides standardized taxonomy:

- **Domains**: Fields of application (e.g., `finance_and_business/investment_services`)
- **Skills**: Specific capabilities (e.g., `natural_language_processing/natural_language_generation/summarization`)

Use the `OASF` service entry with `skills` and `domains` arrays. v0.8.0 includes 136 skills and 204 domains.

### Rule 4: Include Registrations Back-Reference

The `registrations` array creates a bidirectional cryptographic link:
- On-chain NFT -> `agentURI` -> registration file
- Registration file -> `registrations` -> on-chain NFT

Both fields are mandatory in each registration entry:
- `agentId`: The ERC-721 tokenId
- `agentRegistry`: `eip155:{chainId}:{identityRegistryAddress}`

## Nice-to-Have Extras

- `"x402Support": true` - Signals support for Coinbase x402 HTTP payment protocol
- `"active": true/false` - Set `false` until agent is tested and ready for discovery
- Set `agentWallet` on-chain via `setAgentWallet()` if payment address differs from owner

## Endpoint Domain Verification

Optional but recommended. Publish `https://{endpoint-domain}/.well-known/agent-registration.json` containing at least a `registrations` list matching the on-chain identity.

Verification logic:
1. File reachable over HTTPS
2. Contains `registrations` entry where `agentRegistry` and `agentId` match on-chain values
3. If endpoint-domain is the same as `agentURI` domain, this check is redundant

## Registration Flows

### IPFS Registration (Recommended)

```typescript
const sdk = new SDK({
  chainId: 84532,
  rpcUrl: '...',
  privateKey: '...',
  ipfs: 'pinata',       // or 'filecoinPin' (free for ERC-8004), or 'node'
  pinataJwt: '...',
});

const agent = sdk.createAgent('MyAgent', 'Description');
await agent.setMCP('https://mcp.example.com');
agent.setActive(true);

const tx = await agent.registerIPFS();
const { result } = await tx.waitConfirmed();
// result.agentId = "84532:42", result.agentURI = "ipfs://Qm..."
```

IPFS providers:
- **Filecoin Pin** (`filecoinPin`): Free for ERC-8004 agents via Protocol Labs
- **Pinata** (`pinata`): Free for ERC-8004 agents via Pinata
- **IPFS Node** (`node`): Self-hosted node

### HTTP Registration

```typescript
const agent = sdk.createAgent('MyAgent', 'Description');
await agent.setMCP('https://mcp.example.com');
const regFile = agent.getRegistrationFile();
// Host regFile JSON at your URL
const tx = await agent.registerHTTP('https://example.com/agent.json');
```

### Updating Registration

```typescript
const agent = await sdk.loadAgent('84532:42');
agent.updateInfo(undefined, 'Updated description');
await agent.setMCP('https://new-mcp.example.com');
const tx = await agent.registerIPFS();  // uploads new file, updates URI
```

## Field Reference

| Field | Required | Description |
|-------|----------|-------------|
| `type` | MUST | `"https://eips.ethereum.org/EIPS/eip-8004#registration-v1"` |
| `name` | MUST | Agent display name |
| `description` | MUST | Natural language description |
| `image` | SHOULD | Agent image URL |
| `services` | SHOULD | Array of service endpoints |
| `services[].name` | MUST | Service type (`MCP`, `A2A`, `OASF`, `ENS`, `DID`, `web`, `email`, `agentWallet`) |
| `services[].endpoint` | MUST | Service URL or identifier |
| `services[].version` | SHOULD | Protocol version |
| `registrations` | SHOULD | On-chain back-references |
| `registrations[].agentId` | MUST | ERC-721 tokenId |
| `registrations[].agentRegistry` | MUST | `eip155:{chainId}:{address}` |
| `supportedTrust` | MAY | Trust model array |
| `active` | MAY | Visibility flag |
| `x402Support` | MAY | Payment protocol flag |

# ERC-8004 Reputation and Feedback System

**Best Practices Source:** https://github.com/erc-8004/best-practices

## Overview

The Reputation Registry stores agent feedback as signed fixed-point numbers on-chain, with optional rich metadata off-chain (IPFS/HTTPS). Anyone can post feedback about any agent, but self-feedback is rejected (owner/operators cannot review their own agent).

## Value/ValueDecimals Encoding

Feedback uses `int128 value` + `uint8 valueDecimals` (0-18):

| tag1 | Measures | Human Example | value | valueDecimals |
|------|----------|---------------|-------|---------------|
| `starred` | Quality rating 0-100 | 87/100 | 87 | 0 |
| `reachable` | Endpoint reachable (binary) | true | 1 | 0 |
| `ownerVerified` | Endpoint owned by agent | true | 1 | 0 |
| `uptime` | Endpoint uptime % | 99.77% | 9977 | 2 |
| `successRate` | Request success rate % | 89% | 89 | 0 |
| `responseTime` | Latency in ms | 560ms | 560 | 0 |
| `blocktimeFreshness` | Avg block delay | 4 blocks | 4 | 0 |
| `revenues` | Cumulative revenues | $560 | 560 | 0 |
| `tradingYield` | Yield (tag2=day/week/month/year) | -3.2% | -32 | 1 |

### 5-Star to 0-100 Mapping (for catalogs)

| Stars | Value |
|-------|-------|
| 1 | 20 |
| 2 | 40 |
| 3 | 60 |
| 4 | 80 |
| 5 | 100 |

## On-Chain Storage

Stored in contract state (queryable by smart contracts):
- `value` (int128)
- `valueDecimals` (uint8)
- `tag1` (string)
- `tag2` (string)
- `isRevoked` (bool)
- `feedbackIndex` (uint64, 1-indexed per clientAddress per agentId)

Emitted in events but NOT stored:
- `endpoint` (string)
- `feedbackURI` (string)
- `feedbackHash` (bytes32)

## Off-Chain Feedback File

Optional file at `feedbackURI` for rich metadata:

```json
{
  "agentRegistry": "eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432",
  "agentId": 42,
  "clientAddress": "eip155:8453:0xReviewerAddress",
  "createdAt": "2025-09-23T12:00:00Z",
  "value": 85,
  "valueDecimals": 0,
  "tag1": "starred",
  "tag2": "finance",
  "endpoint": "https://mcp.agent.example.com",
  "mcp": {
    "tool": "financial_analyzer"
  },
  "a2a": {
    "skills": ["trading_analysis"],
    "contextId": "ctx-123",
    "taskId": "task-456"
  },
  "oasf": {
    "skills": ["analytical_skills/mathematical_reasoning"],
    "domains": ["finance_and_business"]
  },
  "proofOfPayment": {
    "fromAddress": "0xReviewer...",
    "toAddress": "0xAgent...",
    "chainId": "8453",
    "txHash": "0xPaymentTx..."
  }
}
```

IPFS is recommended for integrity (CID verifies content). For HTTPS files, `feedbackHash` (keccak256) guarantees integrity on-chain.

## SDK Usage

### Give Feedback

```typescript
// Minimal - just value
const tx = await sdk.giveFeedback('84532:42', 85);
await tx.waitConfirmed();

// With tags and endpoint
const tx = await sdk.giveFeedback(
  '84532:42',   // agentId
  85,            // value (0-100 for starred)
  'starred',     // tag1
  'finance',     // tag2
  'https://mcp.example.com',  // endpoint
);

// Full with off-chain file
const feedbackFile = await sdk.prepareFeedbackFile({
  text: 'Accurate market analysis with fast response times',
  capability: 'tools',          // MCP capability type
  name: 'financial_analyzer',   // MCP tool name
  skill: 'trading_analysis',    // A2A skill
  task: 'analyze_portfolio',    // A2A task
  context: { sessionId: 'abc', duration: 1200 },
  proofOfPayment: {
    txHash: '0x...', chainId: '8453',
    fromAddress: '0x...', toAddress: '0x...',
  },
});

const tx = await sdk.giveFeedback('84532:42', 85, 'starred', '', '', feedbackFile);
await tx.waitConfirmed();
```

### Read Feedback

```typescript
// Single feedback entry
const feedback = await sdk.getFeedback('84532:42', '0xClientAddr', 0);
// feedback.value, feedback.tags, feedback.text, feedback.isRevoked

// Search feedback for an agent
const results = await sdk.searchFeedback({
  agentId: '84532:42',
  tags: ['starred'],
});

// Search by reviewer (across all agents, requires subgraph)
const results = await sdk.searchFeedback({
  reviewers: ['0xReviewerAddr'],
});

// Multi-agent search
const results = await sdk.searchFeedback({
  agents: ['84532:42', '84532:43', '84532:44'],
  tags: ['starred'],
});
```

### Reputation Summary

```typescript
const summary = await sdk.getReputationSummary('84532:42');
// { count: 15, averageValue: 87.5 }

// With tag filters
const summary = await sdk.getReputationSummary('84532:42', 'starred', 'finance');
```

### Respond to Feedback

```typescript
// Agent responds to specific feedback
await sdk.appendResponse('84532:42', '0xClientAddr', 0, {
  uri: 'ipfs://QmResponseFile',
  hash: '0x...',
});
```

### Revoke Feedback

```typescript
// Only original submitter can revoke
await sdk.revokeFeedback('84532:42', 0);
```

## On-Chain Aggregation (getSummary)

The `getSummary()` function computes averages on-chain:

1. Normalizes all `value`/`valueDecimals` pairs to 18-decimal WAD
2. Sums all values
3. Finds mode (most common) `valueDecimals` across included feedbacks
4. Computes average
5. Scales back to mode precision

**Anti-Sybil requirement:** `clientAddresses` parameter MUST be non-empty. Callers must supply a trusted reviewer list. Results without filtering are vulnerable to Sybil/spam attacks.

**Tag filtering:** Empty strings for `tag1`/`tag2` act as wildcards (match all).

## Self-Feedback Prevention

The ReputationRegistry calls `isAuthorizedOrOwner()` on the IdentityRegistry before accepting feedback. If the feedback submitter is the agent owner or any approved operator, the transaction reverts.

When agent-to-agent feedback occurs, the reviewing agent SHOULD use its on-chain `agentWallet` as the `clientAddress` for reputation aggregation.

## Feedback ID Format

In the SDK: `"agentId:clientAddress:feedbackIndex"` (e.g., `"84532:42:0x742d...:0"`).

In TypeScript, `Feedback.id` is a tuple `[AgentId, Address, number]`.

The `feedbackIndex` is 0-based in the SDK (converted to 1-based when calling the contract).

## Reputation-Gated Agent Search

The SDK supports finding agents filtered by reputation thresholds:

```typescript
const agents = await sdk.searchAgents({
  active: true,
  hasMCP: true,
  feedback: {
    hasFeedback: true,
    minValue: 80,        // average value >= 80
    maxValue: 100,       // average value <= 100 (upper bound)
    minCount: 5,         // at least 5 feedbacks
    maxCount: 1000,      // at most 1000 feedbacks (upper bound)
    tag1: 'starred',     // only starred feedback
    fromReviewers: ['0xTrustedReviewer'],  // specific reviewers
  },
}, {
  sort: ['averageValue:desc'],
});
```

This uses two-phase filtering: first queries feedback subgraph for matching agentIds, then intersects with the main agent query.

## Ecosystem Patterns

### Agent-as-Rater

When the rater is itself an agent, it SHOULD submit feedback from its on-chain `agentWallet` address so `clientAddress == agentWallet`. This lets UIs resolve the wallet back to an agent identity - finding which agent has that `agentWallet`, then reading its registration file for `name` and `image` to show a profile for the rater.

### Watchtower Monitoring

Trusted third parties (infra companies, watchtowers, data providers) can routinely probe agents and publish periodic signals (e.g., once per week) so anyone can reuse them. Common reliability dimensions:

- `tag1=reachable` - Endpoint reachable (binary)
- `tag1=uptime` - Uptime over a period (percentage)
- `tag1=successRate` - Fraction of successful requests (percentage)
- `tag1=responseTime` - Average latency (milliseconds)

Consumers choose their own trusted sources by filtering feedback by `clientAddress` (e.g., "I trust this watchtower for reachability pings"). Different applications can compose the same underlying signals into dashboards, rankings, alerts, and SLAs.

### Revenue Signals

Cumulative revenue (`tag1=revenues`) helps clients assess whether an agent is battle-tested and in production use. Revenue is NOT directly computable on-chain in a clean way - smart contracts can't conveniently aggregate all payments, and indexers can't reliably distinguish between generic transfers and x402 payments.

In practice, revenue data is best known by the **facilitator** (or specialized infrastructure that interprets payment + service context). These parties publish standardized revenue signals on-chain, making them public so catalogs can filter/weight by trusted `clientAddress`.

# Agent0 TypeScript SDK

**Package:** `agent0-sdk` (npm)
**Version:** 1.5.3+
**License:** MIT
**Node.js:** >= 22.0.0
**Repository:** https://github.com/agent0lab/agent0-ts
**Docs:** https://sdk.ag0.xyz
**Docs Source:** https://github.com/agent0lab/agent0-sdk-docs

## Installation

```bash
npm install agent0-sdk
```

**Runtime dependencies:** `viem ^2.37.5`, `graphql-request ^6.1.0`, `ipfs-http-client ^60.0.1`

## SDK Initialization

```typescript
import { SDK } from 'agent0-sdk';

const sdk = new SDK({
  chainId: number,              // Required: chain ID (1, 8453, 11155111, 84532, 137)
  rpcUrl: string,               // Required: Ethereum RPC endpoint
  privateKey?: string,          // Server-side signing
  walletProvider?: EIP1193Provider, // Browser-side (ERC-6963)
  ipfs?: 'pinata' | 'filecoinPin' | 'node',
  pinataJwt?: string,
  filecoinPrivateKey?: string,
  ipfsNodeUrl?: string,
  subgraphUrl?: string,         // Override default subgraph
  subgraphOverrides?: Record<ChainId, string>,
  registryOverrides?: Record<ChainId, Record<string, Address>>,
});
```

`sdk.isReadOnly` is `true` when no signer is configured (search/discovery still works).

## Agent Lifecycle

### Create Agent

```typescript
const agent = sdk.createAgent(
  'AgentName',
  'Description of what this agent does',
  'https://example.com/image.png'  // optional
);
```

### Configure Agent (Sync - Returns `this`)

```typescript
agent.updateInfo('NewName', 'New description', 'https://new-image.png');
agent.setActive(true);
agent.setX402Support(true);
agent.setTrust(true, false, false);  // reputation, cryptoEconomic, teeAttestation

// OASF taxonomy
agent.addSkill('natural_language_processing/summarization', true);  // validate=true
agent.addDomain('finance_and_business/investment_services', true);
agent.removeSkill('old/skill');
agent.removeDomain('old/domain');

// ENS
agent.setENS('myagent.eth', 'v1');

// Metadata
agent.setMetadata({ customKey: 'customValue' });
agent.delMetadata('customKey');

// Remove endpoints
agent.removeEndpoint('MCP');       // by type
agent.removeEndpoint(undefined, 'https://old.com');  // by value
agent.removeEndpoints();           // all
```

### Configure Agent (Async)

```typescript
// Auto-fetches tools/prompts/resources from MCP endpoint
await agent.setMCP('https://mcp.example.com', '2025-06-18', true);

// Auto-fetches skills from A2A agent card
await agent.setA2A('https://example.com/.well-known/agent-card.json', '0.3.0', true);
```

### Register on IPFS

```typescript
const tx = await agent.registerIPFS();
const { receipt, result } = await tx.waitConfirmed();
// result: RegistrationFile with agentId, agentURI (ipfs://CID), etc.
console.log(result.agentId);  // "84532:42"
```

Two transactions: (1) mint NFT via `register()`, (2) upload to IPFS + `setAgentURI()`.

### Register with HTTP URI

```typescript
// Generate and host the file yourself
const regFile = agent.getRegistrationFile();
// Host regFile JSON at your URL, then:
const tx = await agent.registerHTTP('https://example.com/agent.json');
```

### Load Existing Agent

```typescript
const agent = await sdk.loadAgent('84532:42');  // mutable Agent object
// Make changes...
agent.updateInfo(undefined, 'Updated description');
await agent.registerIPFS();  // re-uploads and updates URI
```

### Update Agent URI

```typescript
await agent.setAgentURI('ipfs://newCID');  // updates on-chain only
```

### Agent Properties (Read-Only)

```typescript
agent.agentId          // "84532:42"
agent.agentURI         // "ipfs://Qm..."
agent.name             // "AgentName"
agent.description      // "Description"
agent.image            // "https://..."
agent.mcpEndpoint      // "https://mcp..."
agent.a2aEndpoint      // "https://a2a..."
agent.ensEndpoint      // "myagent.eth"
agent.walletAddress    // "0x..."
agent.mcpTools         // ["tool1", "tool2"]
agent.mcpPrompts       // ["prompt1"]
agent.mcpResources     // ["resource1"]
agent.a2aSkills        // ["skill1"]
agent.getRegistrationFile()  // full RegistrationFile object
agent.getMetadata()    // { key: value }
```

## Wallet Management

### Set Agent Wallet (EIP-712)

```typescript
// If SDK signer IS the new wallet:
await agent.setWallet('0xNewWallet');

// If new wallet is a different key:
await agent.setWallet('0xNewWallet', {
  newWalletPrivateKey: '0x...',  // pragma: allowlist secret
  deadline: Math.floor(Date.now() / 1000) + 300,  // 5 min max
});

// Pre-computed signature (for smart contract wallets / ERC-1271):
await agent.setWallet('0xNewWallet', { signature: '0x...' });
```

### Unset / Read Wallet

```typescript
await agent.unsetWallet();
const wallet = await agent.getWallet();
```

## Agent Transfer

```typescript
// From a loaded Agent object
const tx = await agent.transfer('0xNewOwner');
const { result } = await tx.waitConfirmed();
// result: { txHash, from, to, agentId }

// Top-level convenience (when you only have an agentId string)
const tx = await sdk.transferAgent('84532:42', '0xNewOwner');
const { result } = await tx.waitConfirmed();

// Check ownership
const isOwner = await sdk.isAgentOwner('84532:42', '0x...');
const owner = await sdk.getAgentOwner('84532:42');
```

`sdk.transferAgent()` internally loads the agent then calls `agent.transfer()`. Use the top-level method when working with agentId strings (common when reading from subgraph); use `agent.transfer()` when you already have a loaded Agent instance.

On transfer, `agentWallet` is cleared. New owner must re-verify.

## Operator Management

`addOperator()` and `removeOperator()` are **not available** in the TypeScript SDK. Use direct contract calls via `sdk.registries()` + viem:

```typescript
import { getContract } from 'viem';

const registries = sdk.registries();
// registries.identityRegistry = "0x8004A169..."

// Use viem directly with a minimal ABI for approve/setApprovalForAll
// See the IdentityRegistry ABI for operator functions (ERC-721 approval)
```

The Python SDK has `agent.addOperator()` and `agent.removeOperator()` natively.

## Discovery and Search

### Get Single Agent

```typescript
const summary = await sdk.getAgent('84532:42');  // AgentSummary (read-only, from subgraph)
```

### Search Agents

```typescript
const agents = await sdk.searchAgents(
  {
    // Text
    name: 'crypto',              // substring match
    description: 'market',

    // Endpoints
    hasMCP: true,
    hasA2A: true,
    hasOASF: true,
    mcpContains: 'example.com',

    // Capabilities (ANY semantics - matches if at least one found)
    mcpTools: ['financial_analyzer'],
    a2aSkills: ['trading'],
    oasfSkills: ['data_engineering/data_transformation_pipeline'],
    oasfDomains: ['finance_and_business'],

    // Status
    active: true,
    x402support: true,
    supportedTrust: ['reputation'],

    // Identity
    chains: [8453, 84532],       // specific chains; 'all' for all
    agentIds: ['84532:42'],
    owners: ['0x...'],
    walletAddress: '0x...',

    // Time
    registeredAtFrom: 1700000000,
    updatedAtTo: 1800000000,

    // Metadata (two-phase prefilter)
    hasMetadataKey: 'customKey',

    // Semantic search
    keyword: 'crypto market analysis',

    // Reputation (two-phase prefilter)
    feedback: {
      hasFeedback: true,
      minValue: 80,
      minCount: 5,
      tag1: 'starred',
      fromReviewers: ['0x...'],
    },
  },
  {
    sort: ['averageValue:desc', 'updatedAt:desc'],
    semanticMinScore: 0.5,
    semanticTopK: 100,
  }
);
```

**Default chains:** chain 1 + SDK's chainId. Use `chains: 'all'` for all 5 indexed chains.

### AgentSummary Fields

```typescript
interface AgentSummary {
  chainId: number;
  agentId: string;         // "chainId:tokenId"
  name: string;
  description: string;
  image?: string;
  owners: Address[];
  operators: Address[];
  mcp?: string;            // MCP endpoint
  a2a?: string;            // A2A endpoint
  web?: string;
  email?: string;
  ens?: string;
  did?: string;
  walletAddress?: string;
  supportedTrusts: string[];
  a2aSkills: string[];
  mcpTools: string[];
  mcpPrompts: string[];
  mcpResources: string[];
  oasfSkills: string[];
  oasfDomains: string[];
  active: boolean;
  x402support: boolean;
  createdAt?: number;
  updatedAt?: number;
  lastActivity?: number;
  agentURI?: string;
  agentURIType?: string;
  feedbackCount?: number;
  averageValue?: number;
  semanticScore?: number;
  extras: Record<string, any>;
}
```

## Feedback System

### Give Feedback

```typescript
// Minimal (value only)
const tx = await sdk.giveFeedback('84532:42', 85);

// Full
const feedbackFile = await sdk.prepareFeedbackFile({
  text: 'Great analysis',
  capability: 'tools',
  name: 'financial_analyzer',
  skill: 'financial_analysis',
  task: 'analyze_portfolio',
  context: { sessionId: 'abc123' },
  proofOfPayment: {
    txHash: '0x...', chainId: '8453',
    fromAddress: '0x...', toAddress: '0x...',
  },
});

const tx = await sdk.giveFeedback(
  '84532:42',   // agentId
  85,            // value
  'starred',     // tag1
  'finance',     // tag2
  'https://mcp.example.com',  // endpoint
  feedbackFile   // off-chain file
);
const { result } = await tx.waitConfirmed();
```

### Read Feedback

```typescript
// Single feedback
const feedback = await sdk.getFeedback('84532:42', '0xClientAddr', 0);

// Search feedback
const results = await sdk.searchFeedback({
  agentId: '84532:42',
  tags: ['starred'],
  // Or multi-agent:
  agents: ['84532:42', '84532:43'],
  // Or by reviewer:
  reviewers: ['0x...'],
});

// Reputation summary
const summary = await sdk.getReputationSummary('84532:42', 'starred');
// { count: 15, averageValue: 87.5 }
```

### Manage Feedback

```typescript
// Agent responds to feedback
await sdk.appendResponse('84532:42', '0xClient', 0, {
  uri: 'ipfs://responseFile',
  hash: '0x...',
});

// Revoke your own feedback
await sdk.revokeFeedback('84532:42', 0);
```

## TransactionHandle Pattern

All write operations return a `TransactionHandle<T>`:

```typescript
const tx = await sdk.giveFeedback(...);
tx.hash;  // transaction hash (immediately available)

// Wait for mining:
const { receipt, result } = await tx.waitConfirmed();
// or with options:
const { receipt, result } = await tx.waitMined({
  timeoutMs: 60000,
  confirmations: 1,
  throwOnRevert: true,
});
```

Multiple calls to `waitConfirmed()` reuse the same promise (memoized).

## Browser Support (ERC-6963)

```typescript
import { discoverEip6963Providers, connectEip1193 } from 'agent0-sdk/eip6963';

const providers = await discoverEip6963Providers({ timeoutMs: 800 });
const { provider } = providers[0];
const walletProvider = await connectEip1193(provider);

const sdk = new SDK({
  chainId: 84532,
  rpcUrl: 'https://...',
  walletProvider,  // writes go through browser wallet
});
```

## AgentId Format

String format `"chainId:tokenId"` (e.g., `"11155111:123"`, `"84532:42"`). When no chain prefix, SDK's default chainId is used.

## Type Reference

```typescript
type AgentId = string;     // "chainId:tokenId"
type ChainId = number;
type Address = string;     // 0x-hex
type URI = string;
type Timestamp = number;

enum EndpointType { MCP, A2A, ENS, DID, WALLET = 'wallet', OASF }
enum TrustModel {
  REPUTATION = 'reputation',
  CRYPTO_ECONOMIC = 'crypto-economic',
  TEE_ATTESTATION = 'tee-attestation',
}

interface Endpoint {
  type: EndpointType;
  value: string;
  meta: Record<string, any>;
}

interface RegistrationFile {
  agentId?: string;
  agentURI?: string;
  name: string;
  description: string;
  image?: string;
  walletAddress?: string;
  walletChainId?: number;
  endpoints: Endpoint[];
  trustModels: TrustModel[];
  owners: Address[];
  operators: Address[];
  active: boolean;
  x402support: boolean;
  metadata: Record<string, any>;
  updatedAt: Timestamp;
}

interface Feedback {
  id: [AgentId, Address, number];
  agentId: string;
  reviewer: string;
  txHash?: string;
  value?: number;
  tags: string[];
  endpoint?: string;
  text?: string;
  context?: Record<string, any>;
  proofOfPayment?: Record<string, any>;
  fileURI?: string;
  createdAt: number;
  answers: any[];
  isRevoked: boolean;
  capability?: string;
  name?: string;
  skill?: string;
  task?: string;
}
```

## Supported Networks

| Network | Chain ID | Status |
|---------|----------|--------|
| Ethereum Mainnet | 1 | Indexed |
| Base Mainnet | 8453 | Indexed |
| Polygon Mainnet | 137 | Indexed |
| Ethereum Sepolia | 11155111 | Indexed |
| Base Sepolia | 84532 | Indexed |

Coming soon: BNB Chain, Monad, additional networks.

## Architecture

```
SDK
 ├── Agent (lifecycle, registration)
 │     ├── EndpointCrawler (MCP/A2A auto-fetch, soft-fail)
 │     ├── IPFSClient (Pinata / FilecoinPin / local node)
 │     └── ViemChainClient (EVM RPC -> Identity Registry)
 ├── AgentIndexer (multi-chain search)
 │     ├── SubgraphClient (The Graph GraphQL)
 │     └── SemanticSearchClient (semantic-search.ag0.xyz)
 └── FeedbackManager (reputation)
       ├── ViemChainClient (-> Reputation Registry)
       ├── IPFSClient (feedback file storage)
       └── SubgraphClient (feedback search)
```

**Key patterns:**
- **Soft-fail crawling**: MCP/A2A capability extraction never throws; registration continues without capabilities if endpoint unreachable
- **Read-only mode**: All discovery/search works without a signer
- **Two-phase feedback filtering**: Reputation-gated searches first query feedback subgraph for matching agentIds, then intersect with main query
- **Backward compatibility**: Handles old field names (`score` vs `value`, `services[]` vs `endpoints[]`, `x402support` vs `x402Support`)

# Agent Search and Discovery

## Overview

ERC-8004 agents are discoverable through a subgraph (The Graph) that indexes both on-chain data and IPFS registration files. The Agent0 SDK provides a unified search API with multi-chain support, semantic search, and reputation-gated filtering.

## Search Methods

### Basic Search

```typescript
const sdk = new SDK({ chainId: 84532, rpcUrl: '...' });

// All active MCP agents
const agents = await sdk.searchAgents({ hasMCP: true, active: true });

// By name
const agents = await sdk.searchAgents({ name: 'crypto' });

// Get single agent
const agent = await sdk.getAgent('84532:42');
```

### Capability Search

```typescript
// By MCP tools (ANY semantics - matches if at least one listed tool found)
const agents = await sdk.searchAgents({
  mcpTools: ['financial_analyzer', 'price_feed'],
});

// By A2A skills
const agents = await sdk.searchAgents({
  a2aSkills: ['trading_analysis'],
});

// By OASF taxonomy
const agents = await sdk.searchAgents({
  oasfSkills: ['natural_language_processing/summarization'],
  oasfDomains: ['finance_and_business'],
});

// By trust model
const agents = await sdk.searchAgents({
  supportedTrust: ['reputation'],
});
```

### Multi-Chain Search

```typescript
// Default: queries chain 1 + SDK's chainId (de-duplicated)
const agents = await sdk.searchAgents({ active: true });

// Specific chains
const agents = await sdk.searchAgents({
  chains: [1, 8453, 137],  // Mainnet, Base, Polygon
  active: true,
});

// All indexed chains
const agents = await sdk.searchAgents({
  chains: 'all',  // 1, 8453, 137, 11155111, 84532
  active: true,
});
```

Results are merged and sorted client-side. AgentId format includes chainId prefix: `"8453:42"`.

### Semantic Search

```typescript
const agents = await sdk.searchAgents(
  { keyword: 'crypto market analysis' },
  {
    sort: ['semanticScore:desc'],
    semanticMinScore: 0.5,
    semanticTopK: 100,
  }
);
```

Uses external semantic search endpoint (`semantic-search.ag0.xyz`) for vector-based matching, then fetches agents from subgraph by ID.

### Reputation-Gated Search

```typescript
const agents = await sdk.searchAgents({
  active: true,
  feedback: {
    hasFeedback: true,
    minValue: 80,
    minCount: 5,
    tag1: 'starred',
    fromReviewers: ['0xTrustedReviewer'],
    endpoint: 'mcp',  // substring match on endpoint
    hasResponse: true,
  },
}, {
  sort: ['averageValue:desc'],
});
```

Two-phase filtering: queries feedback subgraph first for matching agentIds, then intersects with main query.

### Combined Search

```typescript
const agents = await sdk.searchAgents(
  {
    // Endpoint requirements
    hasMCP: true,
    hasOASF: true,

    // Capability requirements
    mcpTools: ['analyzer'],
    oasfDomains: ['finance_and_business'],

    // Status
    active: true,
    x402support: true,

    // Reputation
    feedback: {
      minValue: 80,
      minCount: 3,
    },

    // Time range
    updatedAtFrom: Math.floor(Date.now() / 1000) - 30 * 86400,  // last 30 days

    // Metadata
    hasMetadataKey: 'verified',
  },
  {
    sort: ['averageValue:desc', 'updatedAt:desc'],
  }
);
```

## Search Filters Reference

### Pushdown Filters (Sent to Subgraph)

| Filter | Type | Description |
|--------|------|-------------|
| `name` | string | Substring match on agent name |
| `description` | string | Substring match |
| `hasMCP` | boolean | Has MCP endpoint |
| `hasA2A` | boolean | Has A2A endpoint |
| `hasWeb` | boolean | Has web endpoint |
| `hasOASF` | boolean | Has OASF endpoint |
| `hasEndpoints` | boolean | Has any endpoints |
| `mcpContains` | string | MCP URL substring |
| `a2aContains` | string | A2A URL substring |
| `ensContains` | string | ENS name substring |
| `didContains` | string | DID substring |
| `mcpTools` | string[] | Match any listed tool |
| `mcpPrompts` | string[] | Match any listed prompt |
| `mcpResources` | string[] | Match any listed resource |
| `a2aSkills` | string[] | Match any listed skill |
| `oasfSkills` | string[] | Match any listed OASF skill |
| `oasfDomains` | string[] | Match any listed OASF domain |
| `supportedTrust` | string[] | Match any listed trust model |
| `active` | boolean | Active status |
| `x402support` | boolean | x402 payment support |
| `chains` | number[] or 'all' | Target chains |
| `agentIds` | string[] | Specific agent IDs |
| `owners` | string[] | Owner addresses |
| `operators` | string[] | Operator addresses |
| `walletAddress` | string | Agent wallet address |
| `registeredAtFrom` | number | Registration timestamp >= |
| `registeredAtTo` | number | Registration timestamp <= |
| `updatedAtFrom` | number | Update timestamp >= |
| `updatedAtTo` | number | Update timestamp <= |

### Two-Phase Prefilters (Separate Query Then Intersect)

| Filter | Type | Description |
|--------|------|-------------|
| `hasMetadataKey` | string | Agent has this metadata key |
| `metadataValue` | string | Metadata value match |
| `keyword` | string | Semantic vector search |
| `feedback.hasFeedback` | boolean | Has any feedback |
| `feedback.hasNoFeedback` | boolean | Has no feedback |
| `feedback.minValue` | number | Average value >= |
| `feedback.maxValue` | number | Average value <= |
| `feedback.minCount` | number | Feedback count >= |
| `feedback.maxCount` | number | Feedback count <= |
| `feedback.tag1` | string | Feedback tag1 filter |
| `feedback.tag2` | string | Feedback tag2 filter |
| `feedback.tag` | string | Matches tag1 OR tag2 |
| `feedback.fromReviewers` | string[] | Specific reviewer addresses |
| `feedback.endpoint` | string | Feedback endpoint substring |
| `feedback.hasResponse` | boolean | Has response from agent |
| `feedback.includeRevoked` | boolean | Include revoked feedback |

### Search Options

```typescript
interface SearchOptions {
  sort?: string[];           // e.g., ["averageValue:desc", "name:asc"]
  semanticMinScore?: number; // keyword searches only (default 0.5)
  semanticTopK?: number;     // keyword searches only
}
```

Sortable fields: `name`, `updatedAt`, `createdAt`, `averageValue`, `feedbackCount`, `semanticScore`, `lastActivity`.

## Subgraph Data Model

### Core Entities

```graphql
type Agent @entity {
  id: ID!                          # "chainId:agentId"
  chainId: Int!
  agentId: BigInt!
  agentURI: String
  agentURIType: String             # "ipfs" or "http"
  owner: Bytes!
  operators: [Bytes!]!
  createdAt: BigInt!
  updatedAt: BigInt!
  registrationFile: AgentRegistrationFile
  feedback: [Feedback!]! @derivedFrom(field: "agent")
  validations: [Validation!]! @derivedFrom(field: "agent")
  metadata: [AgentMetadata!]! @derivedFrom(field: "agent")
  totalFeedback: Int!
  lastActivity: BigInt
}

type AgentRegistrationFile @entity {
  id: ID!
  cid: String
  name: String
  description: String
  image: String
  active: Boolean
  x402Support: Boolean
  supportedTrusts: [String!]
  mcpEndpoint: String
  a2aEndpoint: String
  webEndpoint: String
  emailEndpoint: String
  ens: String
  did: String
  mcpTools: [String!]
  mcpPrompts: [String!]
  mcpResources: [String!]
  a2aSkills: [String!]
  oasfSkills: [String!]
  oasfDomains: [String!]
  hasOASF: Boolean
}

type Feedback @entity {
  id: ID!                          # "chainId:agentId:clientAddress:feedbackIndex"
  agent: Agent!
  clientAddress: Bytes!
  value: BigDecimal
  tag1: String
  tag2: String
  feedbackUri: String
  feedbackURIType: String
  feedbackHash: Bytes
  isRevoked: Boolean!
  createdAt: BigInt!
  feedbackFile: FeedbackFile
  responses: [FeedbackResponse!]! @derivedFrom(field: "feedback")
}

type AgentStats @entity {
  id: ID!                          # "chainId:agentId"
  totalFeedback: Int!
  averageValue: BigDecimal
  totalValidations: Int!
  completedValidations: Int!
  averageValidationScore: BigDecimal
  lastActivity: BigInt
}

type GlobalStats @entity {
  id: ID!                          # "global"
  totalAgents: Int!
  totalFeedback: Int!
  totalValidations: Int!
}
```

### Example GraphQL Queries

**Find all active MCP agents:**

```graphql
{
  agents(
    where: {
      registrationFile_: {
        mcpEndpoint_not: null,
        active: true
      }
    }
    orderBy: updatedAt
    orderDirection: desc
    first: 20
  ) {
    id
    agentId
    owner
    registrationFile {
      name
      description
      mcpEndpoint
      mcpTools
      active
      x402Support
    }
  }
}
```

**Find high-rated agents:**

```graphql
{
  agentStats(
    where: { averageValue_gte: "80.0", totalFeedback_gte: 5 }
    orderBy: averageValue
    orderDirection: desc
  ) {
    id
    totalFeedback
    averageValue
  }
}
```

**Search by capability:**

```graphql
{
  agents(where: { registrationFile_: { mcpTools_contains: ["financial_analyzer"] } }) {
    id
    registrationFile {
      name
      mcpTools
      oasfSkills
      oasfDomains
    }
  }
}
```

**Agent with feedback details:**

```graphql
{
  agent(id: "84532:42") {
    id
    agentId
    owner
    registrationFile { name description mcpEndpoint a2aEndpoint }
    feedback(where: { isRevoked: false }) {
      clientAddress
      value
      tag1
      tag2
      createdAt
      responses { responder createdAt }
    }
  }
}
```

**Global statistics:**

```graphql
{
  globalStats(id: "global") {
    totalAgents
    totalFeedback
    totalValidations
  }
}
```

## Indexed Networks

URL pattern: `https://gateway.thegraph.com/api/<API_KEY>/subgraphs/id/<SUBGRAPH_ID>`

| Network | Chain ID | Subgraph ID |
|---------|----------|-------------|
| Ethereum Mainnet | 1 | `FV6RR6y13rsnCxBAicKuQEwDp8ioEGiNaWaZUmvr1F8k` |
| Base Mainnet | 8453 | `43s9hQRurMGjuYnC1r2ZwS6xSQktbFyXMPMqGKUFJojb` |
| Polygon Mainnet | 137 | `9q16PZv1JudvtnCAf44cBoxg82yK9SSsFvrjCY9xnneF` |
| Ethereum Sepolia | 11155111 | `6wQRC7geo9XYAhckfmfo8kbMRLeWU8KQd3XsJqFKmZLT` |
| Base Sepolia | 84532 | `4yYAvQLFjBhBtdRCY7eUWo181VNoTSLLFd5M7FXQAi6u` |

The SDK embeds sponsored API keys per chain. Override with `subgraphOverrides` per chain in SDK config.

## Architecture Notes

- Subgraph indexes both on-chain events and IPFS registration files
- SDK auto-uses default subgraph URL per chain
- Search returns ALL matching results (no pagination needed)
- Multi-chain results merged and sorted client-side
- Semantic search hits `semantic-search.ag0.xyz`, then subgraph for full data
- Two-phase prefilters (metadata, feedback, keyword) run separate queries then intersect IDs

# ERC-8004 Specification

**EIP:** 8004
**Title:** Trustless Agents
**Status:** Draft
**Type:** Standards Track (ERC)
**Created:** 2025-08-13
**Requires:** EIP-155, EIP-712, ERC-721, ERC-1271
**Authors:** Marco De Rossi (@MarcoMetaMask), Davide Crapis (@dcrapis), Jordan Ellis (Google), Erik Reppel (Coinbase)
**Discussion:** https://ethereum-magicians.org/t/erc-8004-trustless-agents/25098
**Best Practices:** https://github.com/erc-8004/best-practices

## Abstract

This protocol uses blockchains to discover, choose, and interact with agents across organizational boundaries without pre-existing trust, enabling open-ended agent economies.

Trust models are pluggable and tiered, with security proportional to value at risk. Developers choose from: reputation systems using client feedback, validation via stake-secured re-execution, zero-knowledge machine learning (zkML) proofs, or trusted execution environment (TEE) oracles.

## Motivation

MCP allows servers to list capabilities (prompts, resources, tools, completions). A2A handles agent authentication, skills advertisement via AgentCards, messaging, and task-lifecycle orchestration. However, these agent communication protocols don't cover agent discovery and trust.

This ERC addresses this through three lightweight registries deployed as per-chain singletons:

- **Identity Registry** - ERC-721 with URIStorage extension resolving to agent registration files
- **Reputation Registry** - Standard interface for posting/fetching feedback signals with on-chain and off-chain aggregation
- **Validation Registry** - Generic hooks for independent validator checks (stakers, zkML verifiers, TEE oracles)

Payments are orthogonal and not covered. Examples show how x402 payments can enrich feedback signals.

## Specification

Key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHOULD", "RECOMMENDED", "MAY", "OPTIONAL" per RFC 2119 and RFC 8174.

### Identity Registry

Uses ERC-721 with URIStorage extension. Each agent is globally identified by:

- **agentRegistry**: `{namespace}:{chainId}:{identityRegistry}` (e.g., `eip155:1:0x742...`)
  - namespace: chain family identifier (`eip155` for EVM)
  - chainId: blockchain network identifier
  - identityRegistry: deployed contract address
- **agentId**: ERC-721 tokenId (assigned incrementally)

Throughout this spec: `tokenId` = `agentId`, `tokenURI` = `agentURI`. The ERC-721 owner owns the agent and can delegate management to operators.

#### Agent URI and Registration File

The `agentURI` MUST resolve to the agent registration file. MAY use any URI scheme (`ipfs://`, `https://`). Updated via `setAgentURI()`.

Registration file MUST have this structure:

```jsonc
{
  "type": "https://eips.ethereum.org/EIPS/eip-8004#registration-v1",
  "name": "myAgentName",
  "description": "Natural language description - what it does, pricing, interaction methods",
  "image": "https://example.com/agentimage.png",
  "services": [
    { "name": "web", "endpoint": "https://web.agentxyz.com/" },
    { "name": "A2A", "endpoint": "https://agent.example/.well-known/agent-card.json", "version": "0.3.0" },
    { "name": "MCP", "endpoint": "https://mcp.agent.eth/", "version": "2025-06-18" },
    { "name": "OASF", "endpoint": "ipfs://{cid}", "version": "0.8",
      "skills": [],   // OPTIONAL
      "domains": []   // OPTIONAL
    },
    { "name": "ENS", "endpoint": "vitalik.eth", "version": "v1" },
    { "name": "DID", "endpoint": "did:method:foobar", "version": "v1" },
    { "name": "email", "endpoint": "mail@myagent.com" }
  ],
  "x402Support": false,
  "active": true,
  "registrations": [
    { "agentId": 22, "agentRegistry": "{namespace}:{chainId}:{identityRegistry}" }
  ],
  "supportedTrust": ["reputation", "crypto-economic", "tee-attestation"]
}
```

The `type`, `name`, `description`, and `image` fields SHOULD ensure ERC-721 app compatibility. Endpoint types and count are fully customizable. The `version` field is SHOULD, not MUST.

#### Endpoint Domain Verification (Optional)

An agent MAY prove control of an HTTPS endpoint-domain by publishing `https://{endpoint-domain}/.well-known/agent-registration.json` containing at least a `registrations` list. Verifiers MAY treat the domain as verified if the file includes a `registrations` entry matching the on-chain agent. If the endpoint-domain is the same domain serving the `agentURI`, this check is unnecessary.

Agents SHOULD have at least one registration. All registration fields are mandatory.

The `supportedTrust` field is OPTIONAL. If absent/empty, ERC-8004 is used only for discovery.

#### On-chain Metadata

```solidity
function getMetadata(uint256 agentId, string memory metadataKey) external view returns (bytes memory)
function setMetadata(uint256 agentId, string memory metadataKey, bytes memory metadataValue) external

event MetadataSet(uint256 indexed agentId, string indexed indexedMetadataKey, string metadataKey, bytes metadataValue)
```

The key `agentWallet` is **reserved** - cannot be set via `setMetadata()` or during `register()`. It represents the payment address and defaults to the owner's address. To change it, the owner must prove control of the new wallet via EIP-712 (EOA) or ERC-1271 (smart contract wallet):

```solidity
function setAgentWallet(uint256 agentId, address newWallet, uint256 deadline, bytes calldata signature) external
function getAgentWallet(uint256 agentId) external view returns (address)
function unsetAgentWallet(uint256 agentId) external
```

On transfer, `agentWallet` is automatically cleared to zero address.

#### Registration

```solidity
struct MetadataEntry {
    string metadataKey;
    bytes metadataValue;
}

function register(string agentURI, MetadataEntry[] calldata metadata) external returns (uint256 agentId)
function register(string agentURI) external returns (uint256 agentId)
function register() external returns (uint256 agentId)  // agentURI added later via setAgentURI()
```

Emits: Transfer event, MetadataSet for `agentWallet`, MetadataSet for each additional entry, and:

```solidity
event Registered(uint256 indexed agentId, string agentURI, address indexed owner)
```

#### Update agentURI

```solidity
function setAgentURI(uint256 agentId, string calldata newURI) external
event URIUpdated(uint256 indexed agentId, string newURI, address indexed updatedBy)
```

For on-chain storage, use base64-encoded data URI: `data:application/json;base64,eyJ0eXBlIjoi...`

### Reputation Registry

Initialized with `initialize(address identityRegistry_)`. Identity registry address visible via `getIdentityRegistry()`.

Feedback consists of: signed fixed-point `value` (int128) + `valueDecimals` (uint8, 0-18), optional `tag1`/`tag2`, optional `endpoint` URI, optional feedback file URI + hash. IPFS recommended for indexing by subgraphs.

#### Value/ValueDecimals Examples

| tag1 | Measures | Example | value | valueDecimals |
|------|----------|---------|-------|---------------|
| `starred` | Quality 0-100 | 87/100 | 87 | 0 |
| `reachable` | Endpoint reachable | true | 1 | 0 |
| `ownerVerified` | Owner verified | true | 1 | 0 |
| `uptime` | Uptime % | 99.77% | 9977 | 2 |
| `successRate` | Success rate % | 89% | 89 | 0 |
| `responseTime` | Latency ms | 560ms | 560 | 0 |
| `blocktimeFreshness` | Block delay | 4 blocks | 4 | 0 |
| `revenues` | Revenue USD | $560 | 560 | 0 |
| `tradingYield` | Yield (tag2=period) | 4% | 4 | 2 |

#### Giving Feedback

```solidity
function giveFeedback(
    uint256 agentId, int128 value, uint8 valueDecimals,
    string calldata tag1, string calldata tag2,
    string calldata endpoint, string calldata feedbackURI, bytes32 feedbackHash
) external
```

Requirements: agentId must be registered, valueDecimals 0-18, submitter MUST NOT be agent owner or approved operator. tag1, tag2, endpoint, feedbackURI, feedbackHash are OPTIONAL.

```solidity
event NewFeedback(
    uint256 indexed agentId, address indexed clientAddress, uint64 feedbackIndex,
    int128 value, uint8 valueDecimals, string indexed indexedTag1,
    string tag1, string tag2, string endpoint, string feedbackURI, bytes32 feedbackHash
)
```

Stored on-chain: value, valueDecimals, tag1, tag2, isRevoked, feedbackIndex (1-indexed). Emitted only: endpoint, feedbackURI, feedbackHash.

When feedback is given by an agent, it SHOULD use the on-chain `agentWallet` as clientAddress for reputation aggregation.

#### Revoking Feedback

```solidity
function revokeFeedback(uint256 agentId, uint64 feedbackIndex) external
event FeedbackRevoked(uint256 indexed agentId, address indexed clientAddress, uint64 indexed feedbackIndex)
```

#### Appending Responses

Anyone can respond (agent showing refund, aggregator tagging spam):

```solidity
function appendResponse(
    uint256 agentId, address clientAddress, uint64 feedbackIndex,
    string calldata responseURI, bytes32 responseHash
) external

event ResponseAppended(
    uint256 indexed agentId, address indexed clientAddress, uint64 feedbackIndex,
    address indexed responder, string responseURI, bytes32 responseHash
)
```

#### Read Functions

```solidity
// clientAddresses MUST be non-empty (Sybil protection). tag1/tag2 optional filters.
function getSummary(uint256 agentId, address[] calldata clientAddresses, string tag1, string tag2)
    external view returns (uint64 count, int128 summaryValue, uint8 summaryValueDecimals)

function readFeedback(uint256 agentId, address clientAddress, uint64 feedbackIndex)
    external view returns (int128 value, uint8 valueDecimals, string tag1, string tag2, bool isRevoked)

function readAllFeedback(uint256 agentId, address[] calldata clientAddresses,
    string tag1, string tag2, bool includeRevoked)
    external view returns (address[] memory, uint64[] memory, int128[] memory,
    uint8[] memory, string[] memory, string[] memory, bool[] memory)

function getResponseCount(uint256 agentId, address clientAddress,
    uint64 feedbackIndex, address[] responders) external view returns (uint64 count)

function getClients(uint256 agentId) external view returns (address[] memory)
function getLastIndex(uint256 agentId, address clientAddress) external view returns (uint64)
```

#### Off-Chain Feedback File Structure

```jsonc
{
  "agentRegistry": "eip155:1:{identityRegistry}",
  "agentId": 22,
  "clientAddress": "eip155:1:{clientAddress}",
  "createdAt": "2025-09-23T12:00:00Z",
  "value": 100,
  "valueDecimals": 0,
  // ALL OPTIONAL:
  "tag1": "foo",
  "tag2": "bar",
  "endpoint": "https://agent.example.com/GetPrice",
  "mcp": { "tool": "ToolName" },
  "a2a": { "skills": [], "contextId": "...", "taskId": "..." },
  "oasf": { "skills": [], "domains": [] },
  "proofOfPayment": {
    "fromAddress": "0x...", "toAddress": "0x...",
    "chainId": "1", "txHash": "0x..."
  }
}
```

### Validation Registry

Enables agents to request third-party verification. Validators can use stake-secured re-execution, zkML verifiers, or TEE oracles.

#### Validation Request

```solidity
function validationRequest(
    address validatorAddress, uint256 agentId,
    string requestURI, bytes32 requestHash
) external

event ValidationRequest(
    address indexed validatorAddress, uint256 indexed agentId,
    string requestURI, bytes32 indexed requestHash
)
```

MUST be called by owner/operator of agentId. requestHash = keccak256 of request payload, identifies the request.

#### Validation Response

```solidity
function validationResponse(
    bytes32 requestHash, uint8 response,
    string responseURI, bytes32 responseHash, string tag
) external

event ValidationResponse(
    address indexed validatorAddress, uint256 indexed agentId,
    bytes32 indexed requestHash, uint8 response,
    string responseURI, bytes32 responseHash, string tag
)
```

Only requestHash and response are mandatory. MUST be called by the validatorAddress from the original request. Response: 0-100 (0=failed, 100=passed, intermediate for spectrum outcomes). Can be called multiple times per requestHash for progressive finality (e.g., "soft_finality"/"hard_finality" via tag).

#### Read Functions

```solidity
function getValidationStatus(bytes32 requestHash)
    external view returns (address, uint256, uint8, bytes32, string, uint256)

function getSummary(uint256 agentId, address[] calldata validatorAddresses, string tag)
    external view returns (uint64 count, uint8 averageResponse)

function getAgentValidations(uint256 agentId) external view returns (bytes32[] memory)
function getValidatorRequests(address validatorAddress) external view returns (bytes32[] memory)
```

Incentives and slashing are managed by specific validation protocols, outside this registry's scope.

## Rationale

- **Agent communication protocols**: MCP and A2A are popular but more could emerge. The flexible registration file with open-ended endpoint lists combines AI primitives (MCP, A2A) with Web3 primitives (wallets, DIDs, ENS).
- **Feedback**: Leverages A2A nomenclature (tasks, skills) and MCP (tools, prompts) with complete flexibility in signal structure.
- **Gas Sponsorship**: Clients don't need registration; any app can implement frictionless feedback via EIP-7702.
- **Indexing**: On-chain data + IPFS makes subgraph indexing straightforward.
- **Deployment**: Singleton per chain. An agent registered on chain A can operate on other chains. Multi-chain registration is supported.

## Security Considerations

- **Sybil attacks**: Possible via fake feedback. Mitigated by reputation systems around reviewers and filtering by clientAddress (already protocol-enabled).
- **Audit trail**: On-chain pointers and hashes cannot be deleted.
- **Validator incentives**: Managed by specific validation protocols.
- **Capability guarantees**: ERC-8004 cannot cryptographically guarantee advertised capabilities are functional/non-malicious. The three trust models (reputation, validation, TEE) address this.