⚠️ Validation Best Practices (PENDING SPECIFICATION)

🚨 CRITICAL NOTICE
This guide is based on an UNSTABLE specification that is PENDING FINALIZATION.
The ERC-8004 Validation Registry specification is still under active development and may change significantly based on ongoing discussions with the TEE/ZK community. The best practices in this document represent current recommendations but should not be considered final for production deployment.
Key uncertainties:
TEE attestation format and requirements (to be revised)
Validation data schema (subject to change)
Response structure and fields (may be updated)
Status tracking: See official ERC-8004 repository for latest specification updates.
For production use: Wait for final v1.1 release before implementing Validation Registry integrations. These best practices will be updated to match the final specification.

Description

Practical guide for validators responding to validation requests

Audience: Validators, auditors, testing services

Current state: v1.1-preview based on SpecsJan26Update (Jan 2026). See Validation Data Profile for the corresponding data specification.

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:

json

{
  "result": "approved"
}

✅ Good:

json

{
  "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:

json

{
  "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:

json

{
  "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:

json

{
  "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:

json

{
  "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):

json

{
  "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):

json

{
  "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

json

{
  "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:

json

{
  "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:

json

{
  "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

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

Example: Comprehensive Security Validation

json

{
  "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

json

{
  "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

json

{
  "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

json

{
  "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:

json

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

Reproducibility

Include Test Environment Details

json

{
  "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

json

{
  "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:

json

// ❌ 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

json

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

✅ Good: Using CAIP-2 and CAIP-10

json

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

Advanced Patterns

Multi-Validator Consensus

For critical validations, coordinate with multiple validators:

json

{
  "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:

json

{
  "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:

json

{
  "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)

⚠️ Validation Best Practices (PENDING SPECIFICATION)

Description ​

Overview ​

Validation Response Principles ​

1. Be Thorough and Evidence-Based ​

2. Match Validation Type to Request ​

3. Use Structured Result Values ​

Validation Type Guides ​

Security Audit ​

Performance Test ​

Accuracy Test ​

zkML Proof (zkSNARK) ​

Groth16 Proof Example ​

PLONK Proof Example ​

TEE Attestation ​

Crypto-Economic Validation ​

Attachment Pattern for Complex Evidence ​

Use Cases ​

Example: Comprehensive Security Validation ​

Response Templates ​

Template 1: Approved Validation ​

Template 2: Rejected Validation ​

Template 3: Conditional Approval ​

Validation Tiers and Weights ​

Reproducibility ​

Include Test Environment Details ​

Provide Reproducible Test Scripts ​

Common Mistakes to Avoid ​

Mistake 1: Insufficient Evidence ​

Mistake 2: Non-Standard Format ​

Mistake 3: Vague Rejection Reasons ​

Mistake 4: Missing CAIP Format ​

Advanced Patterns ​

Multi-Validator Consensus ​

Time-Bound Validations ​

Staged Validations ​

Resources ​

Description

Overview

Validation Response Principles

1. Be Thorough and Evidence-Based

2. Match Validation Type to Request

3. Use Structured Result Values

Validation Type Guides

Security Audit

Performance Test

Accuracy Test

zkML Proof (zkSNARK)

Groth16 Proof Example

PLONK Proof Example

TEE Attestation

Crypto-Economic Validation

Attachment Pattern for Complex Evidence

Use Cases

Example: Comprehensive Security Validation

Response Templates

Template 1: Approved Validation

Template 2: Rejected Validation

Template 3: Conditional Approval

Validation Tiers and Weights

Reproducibility

Include Test Environment Details

Provide Reproducible Test Scripts

Common Mistakes to Avoid

Mistake 1: Insufficient Evidence

Mistake 2: Non-Standard Format

Mistake 3: Vague Rejection Reasons

Mistake 4: Missing CAIP Format

Advanced Patterns

Multi-Validator Consensus

Time-Bound Validations

Staged Validations

Resources