schema.graphql

# Agent0 SDK Subgraph Schema
# Comprehensive indexing for ERC-8004 Agent Discovery and Trust

# =============================================================================
# CORE ENTITIES
# =============================================================================

type Agent @entity(immutable: false) {
  # Primary identifiers
  id: ID! # Format: "chainId:agentId" (e.g., "11155111:123")
  chainId: BigInt!
  agentId: BigInt!
  
  # Basic on-chain information
  agentURI: String
  agentURIType: String # "ipfs", "https", "http", "unknown"
  
  # Ownership and permissions
  owner: Bytes! # Address
  agentWallet: Bytes # Address (20 bytes). Sourced from on-chain MetadataSet(metadataKey == "agentWallet")
  operators: [Bytes!]! # List of approved operators
  
  # Status and metadata
  createdAt: BigInt!
  updatedAt: BigInt!
  
  # Link to IPFS registration file (source of truth, immutable)
  registrationFile: AgentRegistrationFile
  
  # Relationships
  feedback: [Feedback!]! @derivedFrom(field: "agent")
  validations: [Validation!]! @derivedFrom(field: "agent")
  metadata: [AgentMetadata!]! @derivedFrom(field: "agent")
  
  # Computed fields for search
  totalFeedback: BigInt!
  lastActivity: BigInt!
}

type Feedback @entity(immutable: false) {
  # Primary identifier
  id: ID! # Format: "chainId:agentId:clientAddress:feedbackIndex"
  
  # Relationships
  agent: Agent!
  clientAddress: Bytes!
  feedbackIndex: BigInt!
  
  # On-chain feedback data
  value: BigDecimal!
  tag1: String
  tag2: String
  endpoint: String
  feedbackURI: String
  feedbackURIType: String
  feedbackHash: Bytes
  
  # Status
  isRevoked: Boolean!
  createdAt: BigInt!
  revokedAt: BigInt
  
  # Link to IPFS feedback file (source of truth, immutable)
  feedbackFile: FeedbackFile
  
  # Response data
  responses: [FeedbackResponse!]! @derivedFrom(field: "feedback")
}

type FeedbackResponse @entity(immutable: false) {
  id: ID! # Format: "feedbackId:responseIndex"
  feedback: Feedback!
  responder: Bytes!
  responseUri: String
  responseHash: Bytes
  createdAt: BigInt!
}

type Validation @entity(immutable: false) {
  # Primary identifier
  id: ID! # requestHash
  
  # Relationships
  agent: Agent!
  validatorAddress: Bytes!
  
  # Validation data
  requestUri: String
  requestHash: Bytes!
  response: Int # 0-100, 0 means pending
  responseUri: String
  responseHash: Bytes
  tag: String
  
  # Status
  status: ValidationStatus!
  createdAt: BigInt!
  updatedAt: BigInt!
}

type AgentMetadata @entity(immutable: false) {
  id: ID! # Format: "chainId:agentId:key"
  agent: Agent!
  key: String!
  value: Bytes!
  updatedAt: BigInt!
}

# =============================================================================
# ENUMS
# =============================================================================

enum ValidationStatus {
  PENDING
  COMPLETED
  EXPIRED
}

# =============================================================================
# AGGREGATION ENTITIES (for analytics and search)
# =============================================================================

type AgentStats @entity(immutable: false) {
  id: ID! # "chainId:agentId"
  agent: Agent!
  
  # Feedback statistics
  totalFeedback: BigInt!
  averageFeedbackValue: BigDecimal!
  
  # Validation statistics
  totalValidations: BigInt!
  completedValidations: BigInt!
  averageValidationScore: BigDecimal!
  
  # Activity metrics
  lastActivity: BigInt!
  
  updatedAt: BigInt!
}

# =============================================================================
# PROTOCOL ENTITIES
# =============================================================================

type Protocol @entity(immutable: false) {
  id: ID! # "chainId"
  chainId: BigInt!
  name: String!
  
  # Registry addresses
  identityRegistry: Bytes!
  reputationRegistry: Bytes!
  validationRegistry: Bytes!
  
  # Total counts (symmetric with GlobalStats)
  totalAgents: BigInt!
  totalFeedback: BigInt!
  totalValidations: BigInt!
  
  # Search and discovery data (chain-specific)
  agents: [Agent!]!           # Array of agents on this chain
  tags: [String!]!           # All unique tags on this chain
  
  # Timestamps
  updatedAt: BigInt!
}

# =============================================================================
# GLOBAL STATISTICS
# =============================================================================

type GlobalStats @entity(immutable: false) {
  id: ID! # "global"
  
  # Total counts
  totalAgents: BigInt!
  totalFeedback: BigInt!
  totalValidations: BigInt!
  totalProtocols: BigInt!
  
  # Search and discovery data
  agents: [Agent!]!           # Array of all agents
  tags: [String!]!           # All unique tags
  
  
  # Timestamps
  updatedAt: BigInt!
}

# =============================================================================
# IMMUTABLE FILE-BASED ENTITIES (IPFS Data Sources)
# =============================================================================

type AgentRegistrationFile @entity(immutable: true) {
  id: ID! # Format: "transactionHash:cid"
  cid: String! # IPFS CID (for querying by content)
  
  # Agent link (passed via context)
  agentId: String! # Format: "chainId:agentId"
  
  # IPFS file data
  name: String
  description: String
  image: String
  active: Boolean
  x402Support: Boolean
  supportedTrusts: [String!]!
  
  # Endpoints
  endpointsRawJson: String
  mcpEndpoint: String
  mcpVersion: String
  a2aEndpoint: String
  a2aVersion: String
  webEndpoint: String
  oasfEndpoint: String
  oasfVersion: String
  oasfSkills: [String!]!
  oasfDomains: [String!]!
  # Derived convenience flag for exact filtering: true if oasfSkills or oasfDomains is non-empty.
  hasOASF: Boolean!
  emailEndpoint: String
  
  # External identifiers
  ens: String
  did: String
  
  # Capabilities (not implemented yet)
  mcpTools: [String!]!
  mcpPrompts: [String!]!
  mcpResources: [String!]!
  a2aSkills: [String!]!
  
  createdAt: BigInt!
}

type FeedbackFile @entity(immutable: true) {
  id: ID! # Format: "transactionHash:cid"
  cid: String! # IPFS CID (for querying by content)
  
  # Feedback link (passed via context)
  feedbackId: String! # Format: "chainId:agentId:clientAddress:feedbackIndex"
  
  # ERC-8004 off-chain feedback envelope (spec)
  agentRegistry: String
  agentId: BigInt
  clientAddress: String
  createdAtIso: String
  valueRaw: BigInt
  valueDecimals: Int

  # IPFS file data (rich/off-chain)
  text: String

  # ERC-8004 nested objects (spec)
  mcpTool: String
  mcpPrompt: String
  mcpResource: String

  a2aSkills: [String!]!
  a2aContextId: String
  a2aTaskId: String

  oasfSkills: [String!]!
  oasfDomains: [String!]!
  
  # Proof of payment
  proofOfPaymentFromAddress: String
  proofOfPaymentToAddress: String
  proofOfPaymentChainId: String
  proofOfPaymentTxHash: String
  
  # Tags (only if on-chain tags are empty)
  tag1: String
  tag2: String
  
  createdAt: BigInt!
}