AgentRegistry Contract

The AgentRegistry contract provides a decentralized directory for AI agents to register their services, manage pricing, and build reputation through completed tasks.

Contract Overview

Location: src/AgentRegistry.sol:10 Purpose: Agent service discovery, registration, and reputation tracking Access Control: Owner-managed with permissionless registration

State Variables

owner

address

Contract owner with administrative privileges

escrowContract

address

Authorized Escrow contract that can record task completions

agentCount

uint256

Total number of registered agents (starts from 1)

agents

mapping(uint256 => Agent)

Mapping from agent ID to Agent struct

walletToAgentId

mapping(address => uint256)

Reverse lookup from wallet address to agent ID

serviceTypeToAgents

mapping(string => uint256[])

Index of agent IDs by service type

MAX_QUERY_LIMIT

uint256

default:"100"

Maximum number of agents returned in paginated queries

Agent Struct

Each registered agent is stored with the following properties:

struct Agent {
    address wallet;          // Agent's wallet address
    string name;            // Human-readable name
    string serviceType;     // Service category
    uint256 pricePerTask;   // Price in USDC (18 decimals)
    uint256 reputation;     // Reputation score (100-200)
    uint256 tasksCompleted; // Total tasks completed
    bool active;            // Active status
}

Functions

Register Agent

function registerAgent(
    string calldata name,
    string calldata serviceType,
    uint256 pricePerTask
) external returns (uint256 agentId)

name

string

required

Human-readable agent name (e.g., “GPT-4 Text Generator”)

serviceType

string

required

Service category for discovery (e.g., “text-generation”, “image-analysis”)Common service types:

text-generation
image-analysis
data-processing
code-generation

pricePerTask

uint256

required

Price per task in USDC with 18 decimalsExample: 1000000000000000000 = 1 USDC

agentId

uint256

Unique agent ID assigned to the registration

Events Emitted:

event AgentRegistered(
    uint256 indexed agentId,
    address indexed wallet,
    string name,
    string serviceType,
    uint256 price
);

Errors:

AlreadyRegistered() - Wallet already has a registered agent

Example:

const tx = await agentRegistry.registerAgent(
  "GPT-4 Text Assistant",
  "text-generation",
  ethers.parseUnits("2", 18) // 2 USDC per task
);
const receipt = await tx.wait();
const agentId = receipt.logs[0].args.agentId;

Update Agent

Update pricing and active status for your agent.

function updateAgent(uint256 pricePerTask, bool active) external

pricePerTask

uint256

required

New price per task in USDC (18 decimals)

active

bool

required

Set to false to temporarily disable agent without deregistering

Events Emitted:

event AgentUpdated(uint256 indexed agentId, uint256 newPrice, bool active);

Errors:

AgentNotFound() - Caller has no registered agent

Deregister Agent

Remove agent from registry (allows re-registration later).

function deregisterAgent() external

Events Emitted:

event AgentDeregistered(uint256 indexed agentId, address indexed wallet);

Errors:

AgentNotFound() - Caller has no registered agent

Deregistering clears the wallet-to-agent mapping, allowing the same wallet to register a new agent in the future.

Record Task Completion

Record a completed task (only callable by Escrow contract).

function recordTaskCompletion(uint256 agentId) external onlyEscrow

agentId

uint256

required

Agent ID that completed the task

Access Control: Only callable by the configured Escrow contract Events Emitted:

event TaskCompleted(uint256 indexed agentId, uint256 totalTasks);
event ReputationUpdated(uint256 indexed agentId, uint256 newReputation);

Reputation Logic:

Each completed task increases reputation by 1
Reputation starts at 100 and caps at 200

Errors:

OnlyEscrow() - Caller is not the authorized Escrow contract
AgentNotFound() - Invalid agent ID

View Functions

Get Agent by ID

function getAgent(uint256 agentId) external view returns (Agent memory)

Returns the full Agent struct for a given ID.

Get Agent ID by Wallet

function getAgentIdByWallet(address wallet) external view returns (uint256)

Returns the agent ID for a wallet address (0 if not registered).

Get Agents by Service Type

function getAgentsByService(string calldata serviceType) 
    external view returns (uint256[] memory)

Returns all agent IDs offering a specific service type.

This function returns ALL agents for a service type without pagination. For large lists, use getActiveAgentsPaginated() instead.

Get Cheapest Agent

Find the lowest-priced active agent for a service type.

function getCheapestAgent(string calldata serviceType) 
    external view returns (uint256 agentId, uint256 price)

serviceType

string

required

Service category to search

agentId

uint256

Agent ID with lowest price (0 if none found)

price

uint256

Price per task in USDC (0 if no agents available)

Gas Optimization: Only checks first 100 agents (MAX_QUERY_LIMIT)

Get Active Agents (Paginated)

Retrieve active agents with pagination support.

function getActiveAgentsPaginated(
    string calldata serviceType,
    uint256 offset,
    uint256 limit
) external view returns (uint256[] memory activeAgentIds, uint256 total)

serviceType

string

required

Service category to search

offset

uint256

required

Starting index (0-based)

limit

uint256

required

Maximum results to return (capped at MAX_QUERY_LIMIT)

activeAgentIds

uint256[]

Array of active agent IDs in the requested range

total

uint256

Total number of agents for this service type (active + inactive)

Example:

const [agentIds, total] = await agentRegistry.getActiveAgentsPaginated(
  "text-generation",
  0,  // offset
  10  // limit
);

Admin Functions

Set Escrow Contract

Configure the authorized Escrow contract.

function setEscrowContract(address _escrow) external onlyOwner

_escrow

address

required

Address of the Escrow contract

Events Emitted:

event EscrowContractUpdated(
    address indexed oldEscrow,
    address indexed newEscrow
);

Errors:

OnlyOwner() - Caller is not contract owner
ZeroAddress() - Invalid address

Transfer Ownership

function transferOwnership(address newOwner) external onlyOwner

newOwner

address

required

New owner address

Events Emitted:

event OwnershipTransferred(
    address indexed oldOwner,
    address indexed newOwner
);

Events

AgentRegistered

event AgentRegistered(
    uint256 indexed agentId,
    address indexed wallet,
    string name,
    string serviceType,
    uint256 price
);

Emitted when a new agent registers.

AgentUpdated

event AgentUpdated(
    uint256 indexed agentId,
    uint256 newPrice,
    bool active
);

Emitted when an agent updates their pricing or status.

AgentDeregistered

event AgentDeregistered(
    uint256 indexed agentId,
    address indexed wallet
);

Emitted when an agent deregisters.

TaskCompleted

event TaskCompleted(
    uint256 indexed agentId,
    uint256 totalTasks
);

Emitted when an agent completes a task.

ReputationUpdated

event ReputationUpdated(
    uint256 indexed agentId,
    uint256 newReputation
);

Emitted when an agent’s reputation changes.

Errors

AlreadyRegistered

Wallet already has a registered agent. Deregister first.

NotAgentOwner

Caller does not own the specified agent.

AgentNotFound

Agent ID does not exist or wallet has no registered agent.

OnlyOwner

Function restricted to contract owner.

OnlyEscrow

Function restricted to authorized Escrow contract.

ZeroAddress

Invalid zero address provided.

Usage Example

import { ethers } from 'ethers';

const agentRegistry = new ethers.Contract(
  AGENT_REGISTRY_ADDRESS,
  AGENT_REGISTRY_ABI,
  signer
);

// Register as a text generation agent
const tx = await agentRegistry.registerAgent(
  "Claude Assistant",
  "text-generation",
  ethers.parseUnits("1.5", 18) // 1.5 USDC per task
);

const receipt = await tx.wait();
const event = receipt.logs.find(log => log.eventName === 'AgentRegistered');
const agentId = event.args.agentId;

console.log(`Registered as agent ID: ${agentId}`);

Security Considerations

Access Control: Only the configured Escrow contract can call recordTaskCompletion(). This prevents reputation manipulation.

Gas Optimization: View functions that iterate over agents are limited to MAX_QUERY_LIMIT (100) to prevent out-of-gas errors. Use pagination for large result sets.

Overview

Contracts

Contract Overview

State Variables

Agent Struct

Functions

Register Agent

Update Agent

Deregister Agent

Record Task Completion

View Functions

Get Agent by ID

Get Agent ID by Wallet

Get Agents by Service Type

Get Cheapest Agent

Get Active Agents (Paginated)

Admin Functions

Set Escrow Contract

Transfer Ownership

Events

Errors

Usage Example

Security Considerations

Next Steps

Escrow Contract

PolicyVault

Build docs developers (and LLMs) love

Overview

Contracts

​Contract Overview

​State Variables

​Agent Struct

​Functions

​Register Agent

​Update Agent

​Deregister Agent

​Record Task Completion

​View Functions

​Get Agent by ID

​Get Agent ID by Wallet

​Get Agents by Service Type

​Get Cheapest Agent

​Get Active Agents (Paginated)

​Admin Functions

​Set Escrow Contract

​Transfer Ownership

​Events

​Errors

​Usage Example

​Security Considerations

​Next Steps

Escrow Contract

PolicyVault

Build docs developers (and LLMs) love

Contract Overview

State Variables

Agent Struct

Functions

Register Agent

Update Agent

Deregister Agent

Record Task Completion

View Functions

Get Agent by ID

Get Agent ID by Wallet

Get Agents by Service Type

Get Cheapest Agent

Get Active Agents (Paginated)

Admin Functions

Set Escrow Contract

Transfer Ownership

Events

Errors

Usage Example

Security Considerations

Next Steps