Skip to content

AgentRegistry Contract#

Overview#

The AgentRegistry is the core contract for managing AI agent registrations, metadata, and ownership on the Eden platform. It implements ERC-721 functionality with enhanced metadata management and trainer authorization systems.

Key Features#

  • ERC-721 NFT Standard: Each registered agent is a unique NFT
  • IPFS Metadata Storage: Decentralized metadata storage with on-chain URIs
  • Trainer System: Multi-trainer authorization per agent
  • Ownership Transfer Events: Real-time ownership tracking
  • Treasury Integration: Built-in treasury system for platform fees
  • Metadata Updates: Dynamic metadata updates with event logging

Architecture#

graph TB
    subgraph "AgentRegistry Contract"
        A[Agent Registration] --> B[ERC-721 Mint]
        B --> C[IPFS Metadata]
        C --> D[Event Emission]

        E[Trainer Management] --> F[Add/Remove Trainers]
        F --> G[Trainer Events]

        H[Ownership Transfers] --> I[Transfer Events]
        I --> J[Cache Updates]

        K[Metadata Updates] --> L[URI Changes]
        L --> M[Update Events]
    end

    subgraph "External Systems"
        N[IPFS Gateway]
        O[Cache Service]
        P[Frontend Apps]
    end

    C --> N
    D --> O
    G --> O
    I --> O
    M --> O
    O --> P

Contract Functions#

Registration Functions#

registerAgent(string metadataURI, address initialOwner)#

  • Purpose: Register a new AI agent with metadata
  • Access: Public
  • Parameters:
  • metadataURI: IPFS URI containing agent metadata
  • initialOwner: Address that will own the agent NFT
  • Events: Emits AgentRegistered(tokenId, initialOwner, metadataURI)

deregisterAgent(uint256 tokenId)#

  • Purpose: Remove an agent from the registry
  • Access: Owner or approved address
  • Parameters: tokenId: ID of the agent to deregister
  • Events: Emits AgentDeregistered(tokenId, metadataURI)

Metadata Management#

updateTokenURI(uint256 tokenId, string newURI)#

  • Purpose: Update agent metadata URI
  • Access: Owner or approved address
  • Parameters:
  • tokenId: ID of the agent to update
  • newURI: New IPFS metadata URI
  • Events: Emits TokenURIUpdated(tokenId, previousURI, newURI)

tokenURI(uint256 tokenId)#

  • Purpose: Retrieve agent metadata URI
  • Access: Public view
  • Returns: IPFS URI string

Trainer Management#

addTrainer(uint256 tokenId, address trainer)#

  • Purpose: Authorize a trainer wallet for an agent
  • Access: Owner or approved address
  • Parameters:
  • tokenId: ID of the agent
  • trainer: Wallet address to authorize as trainer
  • Events: Emits TrainerAdded(tokenId, trainer)
  • Note: Trainers are simply wallet addresses, no separate registry

removeTrainer(uint256 tokenId, address trainer)#

  • Purpose: Remove trainer wallet authorization
  • Access: Owner or approved address
  • Parameters:
  • tokenId: ID of the agent
  • trainer: Wallet address to remove as trainer
  • Events: Emits TrainerRemoved(tokenId, trainer)

isTrainer(uint256 tokenId, address trainer)#

  • Purpose: Check if wallet address is authorized trainer
  • Access: Public view
  • Returns: Boolean indicating trainer status

Treasury Functions#

updateTreasury(address newTreasury)#

  • Purpose: Update treasury address for fee collection
  • Access: Owner only
  • Parameters: newTreasury: New treasury contract address

Events#

The contract emits several events for real-time system updates:

event AgentRegistered(uint256 indexed tokenId, address indexed owner, string metadataURI);
event AgentDeregistered(uint256 indexed tokenId, string metadataURI);
event TokenURIUpdated(uint256 indexed tokenId, string previousURI, string newURI);
event TrainerAdded(uint256 indexed tokenId, address indexed trainer);
event TrainerRemoved(uint256 indexed tokenId, address indexed trainer);
event Transfer(address indexed from, address indexed to, uint256 indexed tokenId);

Integration Flow#

sequenceDiagram
    participant App as Frontend App
    participant AR as AgentRegistry
    participant IPFS as IPFS Network
    participant CS as Cache Service

    App->>IPFS: Upload agent metadata
    IPFS-->>App: Return IPFS hash
    App->>AR: registerAgent(ipfsURI, owner)
    AR->>AR: Mint NFT token
    AR->>CS: Emit AgentRegistered event
    CS->>IPFS: Fetch and cache metadata
    CS-->>App: Confirm agent cached

    Note over App,CS: Agent is now registered and accessible

    App->>AR: addTrainer(tokenId, trainerAddr)
    AR->>CS: Emit TrainerAdded event
    CS->>CS: Update cached trainer list

    App->>AR: updateTokenURI(tokenId, newURI)
    AR->>CS: Emit TokenURIUpdated event
    CS->>IPFS: Fetch new metadata
    CS->>CS: Update cache with new data

Metadata Schema#

Agent metadata stored on IPFS follows this JSON schema:

{
  "name": "Agent Name",
  "description": "Agent description",
  "image": "ipfs://QmImageHash",
  "attributes": [
    {
      "trait_type": "Category",
      "value": "Art Generation"
    },
    {
      "trait_type": "Model Type", 
      "value": "Diffusion"
    }
  ],
  "external_url": "https://eden.art/agent/123",
  "animation_url": "ipfs://QmVideoHash",
  "properties": {
    "capabilities": ["text-to-image", "style-transfer"],
    "version": "1.0.0",
    "created_at": "2025-09-01T00:00:00Z"
  }
}

Gas Optimization#

The contract is optimized for gas efficiency:

  • Packed Storage: Multiple values stored in single slots
  • Event-Based Indexing: Critical data indexed for efficient queries
  • Minimal State Changes: Functions designed to minimize storage writes
  • Batch Operations: Support for batch trainer operations

Security Features#

  • Access Control: Owner-only functions for critical operations
  • Input Validation: Parameter validation on all functions
  • Reentrancy Protection: ReentrancyGuard on state-changing functions
  • Treasury Security: Protected treasury update mechanism

Deployment Info#

  • Network: Sepolia Testnet
  • Address: 0x3F91E8Ec6d6861309B726AFab8dCD21E83259492
  • Verified: ✅ View on Etherscan

Usage Examples#

JavaScript/TypeScript#

import { ethers } from 'ethers';
import AgentRegistryABI from './AgentRegistry.json';

const AGENT_REGISTRY_ADDRESS = "0x3F91E8Ec6d6861309B726AFab8dCD21E83259492";

// Connect to contract
const agentRegistry = new ethers.Contract(
  AGENT_REGISTRY_ADDRESS,
  AgentRegistryABI,
  signer
);

// Register new agent
const tx = await agentRegistry.registerAgent(
  "ipfs://QmYourMetadataHash",
  "0xOwnerAddress"
);
await tx.wait();

// Add trainer
await agentRegistry.addTrainer(tokenId, "0xTrainerAddress");

// Update metadata
await agentRegistry.updateTokenURI(tokenId, "ipfs://QmNewMetadataHash");

Solidity Integration#

import "./AgentRegistry.sol";

contract MyContract {
    AgentRegistry public immutable agentRegistry;

    constructor(address _agentRegistry) {
        agentRegistry = AgentRegistry(_agentRegistry);
    }

    function registerMyAgent(string calldata metadataURI) external {
        agentRegistry.registerAgent(metadataURI, msg.sender);
    }

    function checkTrainer(uint256 tokenId, address trainer) 
        external 
        view 
        returns (bool) 
    {
        return agentRegistry.isTrainer(tokenId, trainer);
    }
}

Contract Status: Production Ready
Last Updated: September 1, 2025