Description

Practical guide for validators responding to validation requests

Audience: Validators, auditors, testing services

Overview

This guide provides best practices for validators responding to ERC-8004 validation requests, ensuring high-quality validation responses that build trust in the ecosystem.

What You'll Learn:

• ✅ Structure validation responses effectively
• ✅ Choose appropriate validation types
• ✅ Provide comprehensive evidence
• ✅ Use zkSNARK proofs (Groth16, PLONK, STARK)
• ✅ Leverage attachment pattern for complex evidence
• ✅ Migrate from custom formats to ERC-8004 standard

Validation Response Principles

1. Be Thorough and Evidence-Based

Every validation MUST include:

• Clear result (approved/rejected/conditional)
• Detailed reasoning
• Supporting evidence
• Reproducible test methodology

❌ Bad:

{
  "result": "approved"
}

✅ Good:

{
  "agentRegistry": "eip155:84532:0x8004C269...",
  "agentId": 56,
  "validatorAddress": "eip155:84532:0x4baf957...",
  "createdAt": "2025-12-20T05:00:38Z",
  "validationType": "security-audit",
  "result": "approved",
  "reasoning": "Agent passed security audit with 0 critical findings. Tested 15 attack vectors including reentrancy, integer overflow, and access control. All tests passed.",
  "attachments": [
    {
      "name": "Security Audit Report",
      "uri": "ipfs://bafkrei...",
      "mimeType": "application/pdf",
      "description": "Comprehensive security audit using Slither v0.9.6 + manual review"
    }
  ]
}

2. Match Validation Type to Request

Ensure your response addresses the specific validation type requested:

Validation Type	What to Validate	Evidence to Provide
security-audit	Code security, vulnerabilities	Audit report, test results
performance-test	Speed, scalability, uptime	Benchmark data, load test results
accuracy-test	Output correctness, reliability	Test cases, comparison data
zkml-proof	Zero-knowledge ML verification	zkSNARK proof, public signals
tee-attestation	Trusted execution environment	Attestation certificate, enclave report
crypto-economic	Economic stake verification	Stake proof, slashing conditions

3. Use Structured Result Values

Standard Results:

• approved - Agent meets validation criteria
• rejected - Agent fails validation criteria
• conditional - Agent meets criteria with conditions/warnings

With Confidence Scores:

{
  "result": "approved",
  "confidence": 0.95,
  "reasoning": "95% confidence based on 1000 test cases. 5% margin due to limited edge case coverage."
}

Validation Type Guides

Security Audit

Checklist:

• [ ] Smart contract vulnerabilities (if applicable)
• [ ] API endpoint security
• [ ] Access control validation
• [ ] Data privacy compliance
• [ ] Common attack vectors tested

Response Example:

{
  "validationType": "security-audit",
  "result": "approved",
  "reasoning": "Comprehensive security audit completed. Scanned 5 smart contracts and 12 API endpoints. 0 critical findings, 2 low-severity recommendations provided.",
  "attachments": [
    {
      "name": "Slither Automated Scan",
      "uri": "ipfs://bafkrei...",
      "mimeType": "application/json",
      "description": "Automated scan results using Slither v0.9.6. 47 detectors run, 0 critical issues found."
    },
    {
      "name": "Manual Review Report",
      "uri": "ipfs://bafkrei...",
      "mimeType": "application/pdf",
      "description": "Manual code review by certified auditor. Focused on business logic and edge cases. 2 recommendations for optimization."
    },
    {
      "name": "Penetration Test Results",
      "uri": "ipfs://bafkrei...",
      "mimeType": "text/markdown",
      "description": "Tested 15 attack vectors including reentrancy, access control bypass, SQL injection. All tests passed."
    }
  ],
  "testMetadata": {
    "tool": "Slither v0.9.6",
    "manualReviewHours": 8,
    "auditor": "Certified Smart Contract Auditor (CSCA)",
    "date": "2025-12-20"
  }
}

Performance Test

Metrics to Measure:

• Response time (average, p50, p95, p99)
• Throughput (requests per second)
• Uptime (percentage over test period)
• Resource usage (CPU, memory, network)

Response Example:

{
  "validationType": "performance-test",
  "result": "approved",
  "reasoning": "Agent demonstrated excellent performance under load. Average response time 1.2s, 99.9% uptime over 7-day test period.",
  "attachments": [
    {
      "name": "Load Test Results",
      "uri": "ipfs://bafkrei...",
      "mimeType": "application/json",
      "description": "Results from 10,000 API calls over 7 days. Peak load: 100 concurrent requests."
    },
    {
      "name": "Performance Graphs",
      "uri": "ipfs://bafkrei...",
      "mimeType": "image/png",
      "description": "Response time distribution and load curve graphs"
    }
  ],
  "metrics": {
    "avgResponseTime": 1.2,
    "p50ResponseTime": 0.9,
    "p95ResponseTime": 2.1,
    "p99ResponseTime": 3.5,
    "uptime": 99.9,
    "throughput": 50,
    "testDuration": "7 days",
    "totalRequests": 10000
  }
}

Accuracy Test

Test Methodology:

• Ground truth dataset
• Comparison with baseline/control
• Error rate calculation
• Edge case coverage

Response Example:

{
  "validationType": "accuracy-test",
  "result": "approved",
  "reasoning": "Agent achieved 94% accuracy on 1000-sample test dataset. Matches industry benchmark for blockchain analytics agents.",
  "attachments": [
    {
      "name": "Test Dataset",
      "uri": "ipfs://bafkrei...",
      "mimeType": "application/json",
      "description": "1000 blockchain transactions with ground truth labels"
    },
    {
      "name": "Accuracy Report",
      "uri": "ipfs://bafkrei...",
      "mimeType": "text/csv",
      "description": "Per-sample results with predicted vs actual labels"
    },
    {
      "name": "Confusion Matrix",
      "uri": "ipfs://bafkrei...",
      "mimeType": "image/png",
      "description": "Visualization of classification performance"
    }
  ],
  "metrics": {
    "accuracy": 0.94,
    "precision": 0.93,
    "recall": 0.95,
    "f1Score": 0.94,
    "testSamples": 1000,
    "falsePositives": 30,
    "falseNegatives": 30
  }
}

zkML Proof (zkSNARK)

Purpose: Zero-knowledge proof of ML model inference without revealing model weights or input data.

Supported Proof Systems:

• Groth16 (most common, 8000+ validations on Base Sepolia)
• PLONK (universal setup, more flexible)
• STARK (no trusted setup, transparent)

Groth16 Proof Example

Current Format (used by ZyFi and others):

{
  "validationType": "zkml-proof",
  "result": "approved",
  "proof": {
    "pi_a": ["8070450532247928943", "1234567890123456789", "1"],
    "pi_b": [
      ["...", "..."],
      ["...", "..."],
      ["1", "0"]
    ],
    "pi_c": ["...", "...", "1"],
    "protocol": "groth16",
    "curve": "bn128"
  },
  "publicSignals": ["4190804445", "1"],
  "verifierAddress": "0x4baf957830423f36978039e32d95ee958aa0560c",
  "validationRegistryAddress": "0x8004C269D0A5647E51E121FeB226200ECE932d55",
  "chainId": 84532,
  "circuit": "zyfi-rebalancing-validation",
  "version": "1.0",
  "timestamp": 1766206835991
}

ERC-8004 Standard Format (recommended for new implementations):

{
  "agentRegistry": "eip155:84532:0x8004C269D0A5647E51E121FeB226200ECE932d55",
  "agentId": 56,
  "validatorAddress": "eip155:84532:0x4baf957830423f36978039e32d95ee958aa0560c",
  "createdAt": "2025-12-20T05:00:38Z",
  "validationType": "zkml-proof",
  "result": "approved",
  "reasoning": "Zero-knowledge proof verified. Agent rebalancing algorithm meets specification.",
  "proofData": {
    "proof": {
      "pi_a": ["...", "...", "1"],
      "pi_b": [
        ["...", "..."],
        ["...", "..."],
        ["1", "0"]
      ],
      "pi_c": ["...", "...", "1"],
      "protocol": "groth16",
      "curve": "bn128"
    },
    "publicSignals": ["4190804445", "1"],
    "circuit": "zyfi-rebalancing-validation",
    "verifierAddress": "0x4baf957..."
  }
}

Migration Path: See Validation Standard - Migration Guide

PLONK Proof Example

{
  "validationType": "zkml-proof",
  "result": "approved",
  "proofData": {
    "proof": {
      "A": ["...", "..."],
      "B": ["...", "..."],
      "C": ["...", "..."],
      "Z": ["...", "..."],
      "T1": ["...", "..."],
      "T2": ["...", "..."],
      "T3": ["...", "..."],
      "Wxi": ["...", "..."],
      "Wxiw": ["...", "..."],
      "protocol": "plonk",
      "curve": "bn254"
    },
    "publicSignals": [...],
    "circuit": "ml-inference-verification"
  }
}

TEE Attestation

Purpose: Verify agent runs in Trusted Execution Environment (Intel SGX, AMD SEV, AWS Nitro).

Response Example:

{
  "validationType": "tee-attestation",
  "result": "approved",
  "reasoning": "Agent verified to run in Intel SGX enclave. Remote attestation successful.",
  "attachments": [
    {
      "name": "SGX Quote",
      "uri": "ipfs://bafkrei...",
      "mimeType": "application/octet-stream",
      "description": "Intel SGX remote attestation quote"
    },
    {
      "name": "Attestation Report",
      "uri": "ipfs://bafkrei...",
      "mimeType": "application/json",
      "description": "IAS (Intel Attestation Service) verification report"
    }
  ],
  "attestationData": {
    "teeType": "intel-sgx",
    "mrenclave": "0xabc123...",
    "mrsigner": "0xdef456...",
    "isvprodid": 1,
    "isvsvn": 1,
    "reportData": "0x...",
    "verified": true,
    "timestamp": "2025-12-20T05:00:38Z"
  }
}

Crypto-Economic Validation

Purpose: Verify economic stake backing agent behavior.

Response Example:

{
  "validationType": "crypto-economic",
  "result": "approved",
  "reasoning": "Agent has staked 10 ETH with slashing conditions. Economic security verified.",
  "stakeProof": {
    "amount": "10000000000000000000",
    "currency": "ETH",
    "stakingContract": "0xstaking123...",
    "slashingConditions": [
      "Incorrect predictions >10% error rate",
      "Downtime >1 hour",
      "Data privacy breach"
    ],
    "lockupPeriod": "30 days",
    "transactionHash": "0x..."
  }
}

Attachment Pattern for Complex Evidence

Use Cases

1. Multi-file Test Suites: Upload ZIP with all test files
2. Video Demonstrations: Screen recordings of agent behavior
3. Large Datasets: Benchmark data, test results
4. Binary Proofs: zkSNARK proofs, attestation quotes
5. Documentation: Detailed methodology, audit reports

Example: Comprehensive Security Validation

{
  "validationType": "security-audit",
  "result": "conditional",
  "reasoning": "Agent passed automated scans with 2 medium-severity recommendations. Recommend implementing before production deployment.",
  "attachments": [
    {
      "name": "Automated Scan Results",
      "uri": "ipfs://bafkrei...",
      "mimeType": "application/json",
      "size": 150000,
      "description": "Slither + MythX automated security scan results. 0 critical, 0 high, 2 medium findings."
    },
    {
      "name": "Manual Review Report",
      "uri": "ipfs://bafkrei...",
      "mimeType": "application/pdf",
      "size": 2048000,
      "description": "16-page manual code review by certified auditor. Includes recommendations for gas optimization and edge case handling."
    },
    {
      "name": "Test Suite Results",
      "uri": "ipfs://bafkrei...",
      "mimeType": "application/zip",
      "size": 5000000,
      "description": "Complete test suite with 250+ unit tests and 50+ integration tests. All tests passing."
    },
    {
      "name": "Recommendations Document",
      "uri": "ipfs://bafkrei...",
      "mimeType": "text/markdown",
      "size": 10000,
      "description": "Actionable recommendations for addressing 2 medium-severity findings. Estimated 4-8 hours implementation time."
    }
  ]
}

Response Templates

Template 1: Approved Validation

{
  "agentRegistry": "eip155:CHAIN_ID:0x...",
  "agentId": AGENT_ID,
  "validatorAddress": "eip155:CHAIN_ID:0x...",
  "createdAt": "2025-12-20T05:00:38Z",
  "validationType": "VALIDATION_TYPE",
  "result": "approved",
  "reasoning": "[Clear explanation of what was tested and why it passed]",
  "attachments": [
    {
      "name": "PRIMARY_EVIDENCE",
      "uri": "ipfs://...",
      "mimeType": "application/TYPE",
      "description": "[Detailed description of evidence]"
    }
  ]
}

Template 2: Rejected Validation

{
  "agentRegistry": "eip155:CHAIN_ID:0x...",
  "agentId": AGENT_ID,
  "validatorAddress": "eip155:CHAIN_ID:0x...",
  "createdAt": "2025-12-20T05:00:38Z",
  "validationType": "VALIDATION_TYPE",
  "result": "rejected",
  "reasoning": "[Specific failures and why they disqualify the agent]",
  "failureDetails": [
    {
      "category": "FAILURE_CATEGORY",
      "severity": "critical|high|medium|low",
      "description": "[Detailed description]"
    }
  ],
  "attachments": [
    {
      "name": "FAILURE_EVIDENCE",
      "uri": "ipfs://...",
      "mimeType": "application/TYPE",
      "description": "[Evidence of failure]"
    }
  ],
  "recommendations": [
    "Recommendation 1: [Actionable fix]",
    "Recommendation 2: [Actionable fix]"
  ]
}

Template 3: Conditional Approval

{
  "result": "conditional",
  "reasoning": "Agent meets basic criteria but has limitations that users should be aware of.",
  "conditions": [
    "Only use for datasets <10,000 rows",
    "Not suitable for real-time applications (response time >5s)",
    "Requires manual verification for high-stakes decisions"
  ],
  "attachments": [...]
}

Validation Tiers and Weights

When multiple validators validate the same agent, their validations are weighted differently based on validator tier:

Validator Tier	Weight Multiplier	Example
Platform	+30% per validator	8004scan official validators
Official	+20% per validator	EIP-8004 reference validators
Verified	+10% per validator	KYC'd validators with track record
Community	+5% per validator	Anonymous but reputable validators

Best Practice: If you're a verified or platform validator, clearly indicate this in your validation metadata:

{
  "validatorMetadata": {
    "tier": "verified",
    "organization": "SecureAudit Inc.",
    "certifications": ["CSCA", "ISO27001"],
    "website": "https://secureaudit.com"
  }
}

Reproducibility

Include Test Environment Details

{
  "testEnvironment": {
    "network": "sepolia",
    "blockNumber": 18500000,
    "timestamp": "2025-12-20T05:00:38Z",
    "toolsUsed": ["Slither v0.9.6", "MythX", "Foundry"],
    "testDuration": "7 days",
    "infrastructure": "AWS EC2 t3.large"
  }
}

Provide Reproducible Test Scripts

{
  "attachments": [
    {
      "name": "Test Automation Script",
      "uri": "ipfs://bafkrei...",
      "mimeType": "text/x-shellscript",
      "description": "Bash script to reproduce our validation tests. Requires Foundry and Node.js 18+."
    }
  ]
}

Common Mistakes to Avoid

Mistake 1: Insufficient Evidence

❌ Bad: "Looks good to me"

✅ Good: Detailed reasoning + multiple evidence attachments

Mistake 2: Non-Standard Format

❌ Bad: Using custom JSON schema without ERC-8004 envelope

✅ Good: Wrap custom proofs in ERC-8004 standard format

Migration Example:

// ❌ OLD (Groth16 standalone)
{
  "proof": {...},
  "publicSignals": [...],
  "verifierAddress": "0x..."
}

// ✅ NEW (ERC-8004 envelope + Groth16)
{
  "agentRegistry": "eip155:84532:0x...",
  "agentId": 56,
  "validatorAddress": "eip155:84532:0x...",
  "createdAt": "2025-12-20T05:00:38Z",
  "validationType": "zkml-proof",
  "proofData": {
    "proof": {...},
    "publicSignals": [...],
    "protocol": "groth16"
  }
}

Mistake 3: Vague Rejection Reasons

❌ Bad: "Failed security check"

✅ Good: "Failed reentrancy test. Attack vector: Contract allows recursive calls to withdraw() function without proper state updates. See attached exploit proof-of-concept."

Mistake 4: Missing CAIP Format

❌ Bad: Using plain addresses

{
  "agentRegistry": "0x8004...",
  "validatorAddress": "0x4baf..."
}

✅ Good: Using CAIP-2 and CAIP-10

{
  "agentRegistry": "eip155:84532:0x8004...",
  "validatorAddress": "eip155:84532:0x4baf..."
}

Advanced Patterns

Multi-Validator Consensus

For critical validations, coordinate with multiple validators:

{
  "result": "approved",
  "reasoning": "Consensus validation by 3 platform-tier validators. All reached same conclusion independently.",
  "consensusMetadata": {
    "totalValidators": 3,
    "approvals": 3,
    "rejections": 0,
    "validators": ["eip155:1:0x1234...", "eip155:1:0x5678...", "eip155:1:0x9abc..."]
  }
}

Time-Bound Validations

For validations that expire:

{
  "result": "approved",
  "reasoning": "Security audit valid for 6 months. Re-validation recommended after major updates.",
  "validUntil": "2026-06-20T05:00:38Z",
  "renewalRequired": true
}

Staged Validations

For complex multi-stage validations:

{
  "result": "approved",
  "reasoning": "Passed all 3 validation stages.",
  "stages": [
    {
      "stage": "automated-scan",
      "result": "passed",
      "completedAt": "2025-12-18T10:00:00Z"
    },
    {
      "stage": "manual-review",
      "result": "passed",
      "completedAt": "2025-12-19T15:00:00Z"
    },
    {
      "stage": "penetration-test",
      "result": "passed",
      "completedAt": "2025-12-20T05:00:38Z"
    }
  ]
}

Resources

• Validation Standard
• Feedback Best Practices
• Agent Metadata Parsing
• Groth16 Proof System
• PLONK Protocol
• 8004scan Validator Dashboard (coming soon)