@perkos/contracts-erc8004

ERC-8004 Decentralized AI Agent Registry contract ABIs and utilities. Provides TypeScript types and ABIs for interacting with ERC-8004 compliant smart contracts.

Installation

npm install @perkos/contracts-erc8004

Overview

ERC-8004 defines three core registries for decentralized AI agent management:

• IdentityRegistry: NFT-based agent identity with metadata and wallet management
• ReputationRegistry: Client feedback system with filtering by tags and reviewers
• ValidationRegistry: Request-response validation model for third-party attestations

Usage

Identity Registry

Register and manage agent identities as ERC-721 NFTs.

import { createPublicClient, createWalletClient, http } from 'viem';
import { base } from 'viem/chains';
import { IDENTITY_REGISTRY_ABI, type MetadataEntry } from '@perkos/contracts-erc8004';

const IDENTITY_REGISTRY = '0x...'; // Contract address

const publicClient = createPublicClient({
  chain: base,
  transport: http()
});

// Get agent info
const tokenURI = await publicClient.readContract({
  address: IDENTITY_REGISTRY,
  abi: IDENTITY_REGISTRY_ABI,
  functionName: 'tokenURI',
  args: [1n] // agentId
});

const owner = await publicClient.readContract({
  address: IDENTITY_REGISTRY,
  abi: IDENTITY_REGISTRY_ABI,
  functionName: 'ownerOf',
  args: [1n]
});

// Get metadata
const description = await publicClient.readContract({
  address: IDENTITY_REGISTRY,
  abi: IDENTITY_REGISTRY_ABI,
  functionName: 'getMetadata',
  args: [1n, 'description']
});

// Get all agents by owner
const agentIds = await publicClient.readContract({
  address: IDENTITY_REGISTRY,
  abi: IDENTITY_REGISTRY_ABI,
  functionName: 'getAgentsByOwner',
  args: ['0x...']
});

// Register new agent with metadata
const metadata: MetadataEntry[] = [
  { key: 'description', value: 'AI Assistant Agent' },
  { key: 'capabilities', value: 'chat,analysis,code' }
];

const hash = await walletClient.writeContract({
  address: IDENTITY_REGISTRY,
  abi: IDENTITY_REGISTRY_ABI,
  functionName: 'register',
  args: ['ipfs://...', metadata]
});

Reputation Registry

Submit and query client feedback for agents.

import { REPUTATION_REGISTRY_ABI, type Feedback, type ReputationSummary } from '@perkos/contracts-erc8004';

const REPUTATION_REGISTRY = '0x...';

// Get reputation summary
const [count, averageScore] = await publicClient.readContract({
  address: REPUTATION_REGISTRY,
  abi: REPUTATION_REGISTRY_ABI,
  functionName: 'getSummary',
  args: [
    1n,           // agentId
    [],           // clientAddresses (empty = all)
    '',           // tag1 filter (empty = all)
    ''            // tag2 filter (empty = all)
  ]
});

// Get detailed feedback
const feedback = await publicClient.readContract({
  address: REPUTATION_REGISTRY,
  abi: REPUTATION_REGISTRY_ABI,
  functionName: 'getFeedbackDetails',
  args: [1n, '0x...', 0n] // agentId, clientAddress, index
});

// Submit feedback (score 0-100)
const hash = await walletClient.writeContract({
  address: REPUTATION_REGISTRY,
  abi: REPUTATION_REGISTRY_ABI,
  functionName: 'giveFeedback',
  args: [
    1n,                    // agentId
    85,                    // score (0-100)
    'quality',             // tag1
    'speed',               // tag2
    '/api/chat',           // endpoint
    'ipfs://...',          // feedbackURI
    '0x...'                // feedbackHash
  ]
});

// Simple feedback (score only)
const hash = await walletClient.writeContract({
  address: REPUTATION_REGISTRY,
  abi: REPUTATION_REGISTRY_ABI,
  functionName: 'giveFeedback',
  args: [1n, 90] // agentId, score
});

Validation Registry

Request and respond to third-party validations.

import {
  VALIDATION_REGISTRY_ABI,
  ValidationStatus,
  isValidationApproved,
  getValidationStatusString,
  type ValidationRequest,
  type ValidationSummary
} from '@perkos/contracts-erc8004';

const VALIDATION_REGISTRY = '0x...';

// Request validation
const requestHash = await walletClient.writeContract({
  address: VALIDATION_REGISTRY,
  abi: VALIDATION_REGISTRY_ABI,
  functionName: 'validationRequest',
  args: [
    '0x...',              // validatorAddress
    1n,                   // agentId
    'ipfs://...',         // requestURI
    '0x...'               // requestDataHash
  ]
});

// Get validation status
const [status, agentId, validator, response, tag] = await publicClient.readContract({
  address: VALIDATION_REGISTRY,
  abi: VALIDATION_REGISTRY_ABI,
  functionName: 'getValidationStatus',
  args: [requestHash]
});

// Check if approved
if (isValidationApproved(status)) {
  console.log('Validation approved!');
}

// Get status string
console.log(getValidationStatusString(status)); // 'approved' | 'pending' | 'rejected' | etc.

// Get validation statistics
const summary = await publicClient.readContract({
  address: VALIDATION_REGISTRY,
  abi: VALIDATION_REGISTRY_ABI,
  functionName: 'getValidationStatistics',
  args: [1n]
});

// Check for specific validation type
const hasSecurityAudit = await publicClient.readContract({
  address: VALIDATION_REGISTRY,
  abi: VALIDATION_REGISTRY_ABI,
  functionName: 'hasApprovedValidation',
  args: [1n, 'security']
});

// Respond to validation (validator only)
await walletClient.writeContract({
  address: VALIDATION_REGISTRY,
  abi: VALIDATION_REGISTRY_ABI,
  functionName: 'validationResponse',
  args: [
    requestHash,          // requestHash
    85,                   // response (0-100)
    'ipfs://...',         // responseURI
    '0x...',              // responseDataHash
    'security'            // tag
  ]
});

API Reference

ABIs

import {
  IDENTITY_REGISTRY_ABI,
  REPUTATION_REGISTRY_ABI,
  VALIDATION_REGISTRY_ABI,
  ERC8004_ABIS
} from '@perkos/contracts-erc8004';

// Combined ABIs object
const { IdentityRegistry, ReputationRegistry, ValidationRegistry } = ERC8004_ABIS;

Types

import type {
  Hex,
  MetadataEntry,
  Feedback,
  ReputationSummary,
  ValidationStatus,
  ValidationRequest,
  ValidationSummary
} from '@perkos/contracts-erc8004';

MetadataEntry

interface MetadataEntry {
  key: string;
  value: string;
}

Feedback

interface Feedback {
  client: Address;
  score: number;        // 0-100
  tag1: string;
  tag2: string;
  endpoint: string;
  feedbackURI: string;
  feedbackHash: Hex;
  timestamp: bigint;
  isRevoked: boolean;
  responseURI: string;
  responseHash: Hex;
}

ReputationSummary

interface ReputationSummary {
  count: bigint;
  averageScore: number; // 0-100
}

ValidationStatus

enum ValidationStatus {
  None = 0,
  Pending = 1,
  Approved = 2,
  Rejected = 3,
  Cancelled = 4
}

ValidationRequest

interface ValidationRequest {
  agentId: bigint;
  requester: Address;
  validatorAddress: Address;
  requestURI: string;
  requestDataHash: Hex;
  requestedAt: bigint;
  status: ValidationStatus;
  response: number;     // 0-100
  responseURI: string;
  responseDataHash: Hex;
  tag: string;
  respondedAt: bigint;
}

ValidationSummary

interface ValidationSummary {
  totalRequests: bigint;
  approvedCount: bigint;
  rejectedCount: bigint;
  pendingCount: bigint;
  averageResponse: number; // 0-100
}

Constants

VALIDATION_TAGS

import { VALIDATION_TAGS } from '@perkos/contracts-erc8004';

// Pre-defined validation tags per EIP-8004
VALIDATION_TAGS.SECURITY    // 'security'
VALIDATION_TAGS.COMPLIANCE  // 'compliance'
VALIDATION_TAGS.PERFORMANCE // 'performance'
VALIDATION_TAGS.IDENTITY    // 'identity'
VALIDATION_TAGS.CAPABILITY  // 'capability'
VALIDATION_TAGS.KYC         // 'kyc'
VALIDATION_TAGS.AML         // 'aml'

FEEDBACK_TAGS

import { FEEDBACK_TAGS } from '@perkos/contracts-erc8004';

// Pre-defined feedback tags per EIP-8004
FEEDBACK_TAGS.QUALITY     // 'quality'
FEEDBACK_TAGS.SPEED       // 'speed'
FEEDBACK_TAGS.RELIABILITY // 'reliability'
FEEDBACK_TAGS.ACCURACY    // 'accuracy'
FEEDBACK_TAGS.SUPPORT     // 'support'

Utility Functions

import {
  isValidationApproved,
  getValidationStatusString,
  getScorePercentage,
  isScoreApproved
} from '@perkos/contracts-erc8004';

// Check if validation is approved
isValidationApproved(ValidationStatus.Approved);  // true

// Get human-readable status
getValidationStatusString(ValidationStatus.Pending);  // 'pending'

// Normalize score to 0-100 range
getScorePercentage(85);  // 85

// Check if score indicates approval (>50)
isScoreApproved(85);  // true
isScoreApproved(30);  // false

Contract Functions

Identity Registry

| Function | Description | |----------|-------------| | register(agentURI, metadata?) | Register new agent identity | | setAgentURI(agentId, newURI) | Update agent URI | | setMetadata(agentId, key, value) | Set metadata entry | | setAgentWallet(agentId, newWallet, deadline, signature) | Update agent wallet | | tokenURI(agentId) | Get agent URI | | ownerOf(agentId) | Get agent owner | | getMetadata(agentId, key) | Get metadata value | | getAgentWallet(agentId) | Get agent wallet address | | getAgentsByOwner(owner) | Get all agents owned by address | | totalAgents() | Get total registered agents |

Reputation Registry

| Function | Description | |----------|-------------| | giveFeedback(agentId, score, ...) | Submit feedback | | revokeFeedback(agentId, index) | Revoke feedback | | appendResponse(agentId, client, index, responseURI, hash) | Add agent response | | getSummary(agentId, clients, tag1, tag2) | Get reputation summary | | readFeedback(agentId, client, index) | Read specific feedback | | readAllFeedback(agentId, clients, tag1, tag2, includeRevoked) | Read all feedback | | getFeedbackDetails(agentId, client, index) | Get full feedback details | | getClients(agentId) | Get all feedback clients |

Validation Registry

| Function | Description | |----------|-------------| | validationRequest(validator, agentId, requestURI, hash) | Request validation | | validationResponse(requestHash, response, responseURI, hash, tag) | Submit response | | cancelValidation(requestHash) | Cancel validation request | | getValidationStatus(requestHash) | Get validation status | | getValidation(requestHash) | Get full validation details | | getSummary(agentId, validators, tag) | Get validation summary | | hasApprovedValidation(agentId, tag) | Check for approved validation | | getValidationStatistics(agentId) | Get agent validation stats | | getAgentValidations(agentId) | Get all validation hashes | | getPendingRequests(validator) | Get pending requests for validator |

Events

Identity Registry Events

• Registered(agentId, agentURI, owner)
• URIUpdated(agentId, newURI, updatedBy)
• MetadataSet(agentId, indexedKey, metadataKey, metadataValue)
• AgentWalletUpdated(agentId, oldWallet, newWallet)

Reputation Registry Events

• NewFeedback(agentId, clientAddress, score, tag1, tag2, endpoint, feedbackURI, feedbackHash)
• FeedbackRevoked(agentId, clientAddress, feedbackIndex)
• ResponseAppended(agentId, clientAddress, feedbackIndex, responder, responseURI)

Validation Registry Events

• ValidationRequested(requestHash, agentId, validatorAddress, requestURI, requestDataHash)
• ValidationResponseSubmitted(requestHash, agentId, validatorAddress, response, tag)
• ValidationCancelled(requestHash, agentId, cancelledBy)

Related Packages

• @perkos/types-x402 - Core x402 types
• @perkos/service-x402 - x402 service orchestrator

License

MIT