Attachment Pattern Standard

Description

Reusable attachment schema for evidence and supporting documents in ERC-8004 offchain data

Document Purpose

This document defines a reusable attachment pattern for including evidence files, receipts, and supporting documents in ERC-8004 offchain data structures. This pattern is shared across:

Feedback Records (Reputation Registry)
Validation Requests (Validation Registry)
Validation Responses (Validation Registry)

Terminology: This document follows conventions defined in Conventions.

Overview
Attachment Object Schema
Field Reference
Implementation Requirements
Use Cases and Examples
Best Practices
Security Considerations

Overview

Purpose

The Attachment Pattern provides a standardized way to reference external files in offchain data, enabling:

Evidence Collection: Supporting documents for feedback or validation claims
Transparency: Providing verifiable proof of service delivery or test results
Rich Context: Adding detailed information beyond JSON fields
Flexibility: Supporting any file type without schema changes

Design Goals

Simplicity: Minimal required fields for easy adoption
Extensibility: Optional fields for rich metadata
Interoperability: Standard MIME types and URI schemes
Backward Compatibility: Unknown fields preserved for future extensions

Inspiration

This pattern was inspired by the v1 frontend design of 8004scan, which proved successful in production for feedback evidence collection.

Attachment Object Schema

Minimal Example (Required Fields Only)

json

{
  "name": "Service Receipt",
  "uri": "ipfs://QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco",
  "mimeType": "application/pdf",
  "size": 245760
}

Full Example (All Fields)

json

{
  "name": "Portfolio Analysis Report",
  "uri": "ipfs://bafkreiaqdaerh5dvqmtjievkfnwfft6psghkxezygncbuvhl2uwyu6scn4",
  "mimeType": "application/pdf",
  "size": 1536000,
  "description": "Detailed analysis report with recommendations for portfolio optimization",
  "uploadedAt": "2025-12-21T14:30:00Z"
}

TypeScript Interface (Informative)

typescript

/**
 * Attachment file metadata for evidence and supporting documents
 * @see https://docs.8004scan.io/standards/attachment-pattern (coming soon)
 */
interface AttachmentFile {
  /** Display name of the file */
  name: string;

  /** URI to the file content (IPFS, HTTPS, Arweave, Data URI) */
  uri: string;

  /** IANA MIME type of the file */
  mimeType: string;

  /** File size in bytes */
  size: number;

  /** Optional context or explanation of the file's purpose */
  description?: string;

  /** Optional timestamp when file was uploaded (ISO 8601 UTC) */
  uploadedAt?: string;
}

Field Reference

Required Fields

Field	Type	Constraints	Description
`name`	`string`	Length: 1–200 chars	Display name for the file. SHOULD be descriptive and human-readable.
`uri`	`string`	Valid URI	Location of the file content. MUST use supported URI scheme (see Conventions).
`mimeType`	`string`	IANA MIME type	File type identifier. MUST be a valid MIME type (see Conventions).
`size`	`number`	`uint`, `≥ 0`	File size in bytes. SHOULD be accurate to enable size validation and UI display.

Optional Fields

Field	Type	Constraints	Description
`description`	`string`	Length: 0–1000 chars	Human-readable explanation of the file's purpose, context, or contents.
`uploadedAt`	`string`	ISO 8601 UTC	Timestamp when the file was uploaded or created. MUST follow ISO 8601 format in UTC (see Conventions).

Implementation Requirements

For Data Producers (Clients, Validators)

Implementations that create attachment data MUST:

✅ Include all required fields (name, uri, mimeType, size)
✅ Use valid URI schemes (see Conventions)
✅ Provide accurate MIME types (see Conventions)
✅ Report correct file sizes in bytes

Implementations SHOULD:

🟡 Include description for context and transparency
🟡 Include uploadedAt for audit trails
🟡 Validate file accessibility before submitting URIs
🟡 Use decentralized storage (IPFS, Arweave) for permanence

For Data Consumers (Explorers, Indexers, Clients)

Implementations that parse attachment data MUST:

✅ Support all required fields (name, uri, mimeType, size)
✅ Gracefully handle missing optional fields
✅ Preserve unknown fields for forward compatibility

Implementations SHOULD:

🟡 Display optional fields when present (description, uploadedAt)
🟡 Validate file sizes against size field before download
🟡 Support multiple URI schemes (at minimum: https://, ipfs://)
🟡 Provide MIME type icons for visual file type identification
🟡 Warn users about large files before download

Implementations MAY:

⚪ Cache file metadata for performance
⚪ Verify file integrity using content hashes
⚪ Scan for malware before displaying downloads
⚪ Generate thumbnails for image/video files

Use Cases and Examples

Use Case 1: Service Receipt (Feedback)

A client provides proof of service completion with their feedback.

json

{
  "attachments": [
    {
      "name": "Service Receipt - Portfolio Analysis",
      "uri": "ipfs://QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco",
      "mimeType": "application/pdf",
      "size": 245760,
      "description": "Invoice and deliverables for portfolio analysis service completed on 2025-12-20",
      "uploadedAt": "2025-12-20T15:00:00Z"
    }
  ]
}

Context: Used in Feedback Standard's attachments array.

Use Case 2: Chat Transcript (Feedback)

A client provides communication logs as evidence of responsiveness.

json

{
  "attachments": [
    {
      "name": "Chat Transcript",
      "uri": "https://storage.example.com/transcripts/session-abc123.txt",
      "mimeType": "text/plain",
      "size": 15360,
      "description": "Full conversation transcript showing agent responsiveness and professionalism"
    }
  ]
}

Context: Used in Feedback Standard's attachments array.

Use Case 3: Test Dataset (Validation Request)

A client provides test data for the validator to use.

json

{
  "attachments": [
    {
      "name": "Test Dataset - Portfolio Scenarios",
      "uri": "ipfs://bafkreiaqdaerh5dvqmtjievkfnwfft6psghkxezygncbuvhl2uwyu6scn4",
      "mimeType": "application/json",
      "size": 50000,
      "description": "Sample portfolio data for testing rebalancing logic. Contains 10 realistic scenarios.",
      "uploadedAt": "2025-12-21T10:00:00Z"
    },
    {
      "name": "Expected Outputs",
      "uri": "ipfs://bafkreib234...",
      "mimeType": "application/json",
      "size": 25000,
      "description": "Expected rebalancing recommendations for each test scenario"
    }
  ]
}

Context: Used in Validation Request's attachments array.

Use Case 4: Validation Proof (Validation Response)

A validator provides test results and proof of validation.

json

{
  "attachments": [
    {
      "name": "Test Results Summary",
      "uri": "https://validator.example.com/results/abc123.pdf",
      "mimeType": "application/pdf",
      "size": 512000,
      "description": "Comprehensive test report with pass/fail results for all scenarios"
    },
    {
      "name": "Execution Logs",
      "uri": "ipfs://QmYyy...",
      "mimeType": "text/plain",
      "size": 102400,
      "description": "Raw execution logs from validation test runs"
    }
  ]
}

Context: Used in Validation Response's attachments array.

Use Case 5: zkSNARK Proof Circuit (Validation)

A validator provides the proof circuit definition and public inputs.

json

{
  "attachments": [
    {
      "name": "Circuit Definition",
      "uri": "ipfs://Qmcircuit...",
      "mimeType": "application/json",
      "size": 8192,
      "description": "ZyFi rebalancing validation circuit (Groth16 format)"
    },
    {
      "name": "Public Inputs",
      "uri": "data:application/json;base64,eyJpbnB1dHMiOlsiNDE5MDgwNDQ0NSIsIjEiXX0=",
      "mimeType": "application/json",
      "size": 128,
      "description": "Public inputs for proof verification: [agentId, validationType]"
    }
  ]
}

Context: Used in Validation Request/Response for zkSNARK validations.

Use Case 6: Multiple File Types

Combining different evidence types in a single record.

json

{
  "attachments": [
    {
      "name": "Screenshot - Agent Response",
      "uri": "ipfs://QmImg...",
      "mimeType": "image/png",
      "size": 1024000,
      "description": "Screenshot of agent's analysis output"
    },
    {
      "name": "Video Demonstration",
      "uri": "ar://video123...",
      "mimeType": "video/mp4",
      "size": 15728640,
      "description": "Screen recording of agent interaction session"
    },
    {
      "name": "Raw Data Export",
      "uri": "ipfs://QmData...",
      "mimeType": "text/csv",
      "size": 204800,
      "description": "CSV export of agent's analysis results for verification"
    }
  ]
}

Context: Demonstrates flexibility to support any file type.

Best Practices

For File Selection

Relevance: Only attach files directly relevant to the feedback/validation
Size: Keep total attachment size reasonable (< 10 MB per record recommended)
Format: Use widely-supported formats (PDF, PNG, JSON, CSV, TXT)
Quality: Ensure files are readable and not corrupted

For URI Selection

Permanence: Prefer decentralized storage (IPFS, Arweave) over HTTPS for long-term availability
Accessibility: Ensure URIs are publicly accessible (no authentication required)
Performance: Use CDNs or IPFS gateways for faster access
Backup: Consider storing critical files on multiple platforms

For MIME Types

Accuracy: Use correct MIME types matching actual file format
Standards: Use IANA-registered MIME types when possible
Custom: Use application/x-<format> pattern for custom formats
Fallback: Use application/octet-stream only as last resort

For Descriptions

Clarity: Explain what the file contains and why it's relevant
Context: Mention key details (date, purpose, format specifics)
Brevity: Keep descriptions concise (1-2 sentences)
Audience: Write for someone unfamiliar with the interaction

For File Uploads

Validation: Check file size and type before uploading
Naming: Use descriptive filenames without special characters
Metadata: Include uploadedAt for audit trails
Verification: Test file accessibility after upload

Security Considerations

For Data Producers

⚠️ Do NOT attach:

Private keys or passwords
Personal identifiable information (PII) without consent
Confidential business data
Executable files (.exe, .sh, .bat)
Files with embedded malware

✅ DO:

Review file contents before attaching
Redact sensitive information
Use file integrity checks (hashes)
Warn about file size in descriptions

For Data Consumers

⚠️ Risks:

Malicious Content: Files may contain malware or exploits
Large Files: May consume excessive bandwidth or storage
External Links: HTTPS URIs may become unavailable
Privacy Leaks: Files may contain unintended personal data

✅ Mitigations:

Scan downloaded files for malware
Implement size limits (e.g., warn if > 10 MB)
Sandbox file previews in isolated environments
Respect user privacy (don't auto-download)
Provide clear warnings before file access

IPFS-Specific Considerations

Content Persistence: IPFS content may become unavailable if no nodes pin it
Gateway Risks: Public IPFS gateways may be rate-limited or blocked
Content Addressing: CIDs are unique, but content can still be malicious

Recommendations:

Use multiple IPFS gateways for redundancy
Pin important content to ensure availability
Verify file integrity using CID

Data URI Considerations

Size: Data URIs increase JSON size significantly
Encoding: Base64 encoding adds ~33% overhead
Performance: Large data URIs slow parsing and transfer

Recommendations:

Only use data URIs for small files (< 1 KB)
Prefer external storage (IPFS/HTTPS) for larger files
Consider compression for data URIs (see Data URI Compression Extension)

Validation Rules

Field Validation

name:

MUST NOT be empty string
SHOULD be 1–200 characters
SHOULD NOT contain path separators (/, \)
SHOULD be descriptive

uri:

MUST be valid URI
MUST use supported scheme (https://, ipfs://, ar://, data:)
MUST NOT be relative path
SHOULD be accessible (reachable)

mimeType:

MUST be valid MIME type format (type/subtype)
SHOULD be IANA-registered or use x- prefix for custom types
SHOULD match actual file content

size:

MUST be non-negative integer
SHOULD accurately reflect file size
SHOULD be reasonable (< 100 MB recommended)

description (optional):

SHOULD be 0–1000 characters
SHOULD be human-readable

uploadedAt (optional):

MUST be valid ISO 8601 format
MUST be in UTC timezone (Z suffix)
SHOULD be reasonably recent

Error Handling

Missing Required Fields

If a required field is missing:

Status: validation_error
Code: attachment_missing_<field>
Example: attachment_missing_uri

Behavior:

Implementations MAY reject the entire record
Implementations MAY skip the invalid attachment but preserve others
Implementations SHOULD log the error

Invalid Field Values

If a field value is invalid:

Status: validation_warning
Code: attachment_invalid_<field>
Example: attachment_invalid_mime_type

Behavior:

Implementations SHOULD accept the record with warning
Implementations SHOULD display warning in UI
Implementations MAY attempt to correct (e.g., infer MIME type)

Unknown Fields

If unknown fields are present:

Behavior:

Implementations MUST NOT reject
Implementations SHOULD preserve unknown fields
Implementations MAY log informational message

Migration and Compatibility

Forward Compatibility

This schema supports forward compatibility by:

Allowing unknown fields (MUST preserve)
Using optional fields for new features
Maintaining stable required field set

Backward Compatibility

Future versions of this standard will:

NEVER remove required fields
NEVER change field semantics without major version bump
MAY add new optional fields in minor versions
MAY promote optional fields to recommended in minor versions

Versioning

This Attachment Pattern Standard follows its own version number:

Current Version: 1.0

Future versions referenced in documents will specify compatibility:

1.x: Fully compatible (new optional fields)
2.x: Breaking changes (read migration guide)

References

Conventions: Shared terminology and format standards
Feedback Standard: Feedback record format using attachments
Validation Standard: Validation record format using attachments
Data URI Compression Extension: Gas optimization for data URIs

Appendix: Full Schema (Informative)

JSON Schema (Draft-07)

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "AttachmentFile",
  "description": "Attachment file metadata for ERC-8004 offchain data",
  "type": "object",
  "required": ["name", "uri", "mimeType", "size"],
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Display name of the file"
    },
    "uri": {
      "type": "string",
      "format": "uri",
      "description": "URI to the file content"
    },
    "mimeType": {
      "type": "string",
      "pattern": "^[a-z]+/[a-z0-9.+-]+$",
      "description": "IANA MIME type of the file"
    },
    "size": {
      "type": "integer",
      "minimum": 0,
      "description": "File size in bytes"
    },
    "description": {
      "type": "string",
      "maxLength": 1000,
      "description": "Optional context or explanation"
    },
    "uploadedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Upload timestamp (ISO 8601 UTC)"
    }
  },
  "additionalProperties": true
}

Attachment Pattern Standard

Description ​

Document Purpose ​

Table of Contents ​

Overview ​

Purpose ​

Design Goals ​

Inspiration ​

Attachment Object Schema ​

Minimal Example (Required Fields Only) ​

Full Example (All Fields) ​

TypeScript Interface (Informative) ​

Field Reference ​

Required Fields ​

Optional Fields ​

Implementation Requirements ​

For Data Producers (Clients, Validators) ​

For Data Consumers (Explorers, Indexers, Clients) ​

Use Cases and Examples ​

Use Case 1: Service Receipt (Feedback) ​

Use Case 2: Chat Transcript (Feedback) ​

Use Case 3: Test Dataset (Validation Request) ​

Use Case 4: Validation Proof (Validation Response) ​

Use Case 5: zkSNARK Proof Circuit (Validation) ​

Use Case 6: Multiple File Types ​

Best Practices ​

For File Selection ​

For URI Selection ​

For MIME Types ​

For Descriptions ​

For File Uploads ​

Security Considerations ​

For Data Producers ​

For Data Consumers ​

IPFS-Specific Considerations ​

Data URI Considerations ​

Validation Rules ​

Field Validation ​

Error Handling ​

Missing Required Fields ​

Invalid Field Values ​

Unknown Fields ​

Migration and Compatibility ​

Forward Compatibility ​

Backward Compatibility ​

Versioning ​

References ​

Appendix: Full Schema (Informative) ​

JSON Schema (Draft-07) ​

Description

Document Purpose

Table of Contents

Overview

Purpose

Design Goals

Inspiration

Attachment Object Schema

Minimal Example (Required Fields Only)

Full Example (All Fields)

TypeScript Interface (Informative)

Field Reference

Required Fields

Optional Fields

Implementation Requirements

For Data Producers (Clients, Validators)

For Data Consumers (Explorers, Indexers, Clients)

Use Cases and Examples

Use Case 1: Service Receipt (Feedback)

Use Case 2: Chat Transcript (Feedback)

Use Case 3: Test Dataset (Validation Request)

Use Case 4: Validation Proof (Validation Response)

Use Case 5: zkSNARK Proof Circuit (Validation)

Use Case 6: Multiple File Types

Best Practices

For File Selection

For URI Selection

For MIME Types

For Descriptions

For File Uploads

Security Considerations

For Data Producers

For Data Consumers

IPFS-Specific Considerations

Data URI Considerations

Validation Rules

Field Validation

Error Handling

Missing Required Fields

Invalid Field Values

Unknown Fields

Migration and Compatibility

Forward Compatibility

Backward Compatibility

Versioning

References

Appendix: Full Schema (Informative)

JSON Schema (Draft-07)