The Protocol Quantum Agent Card Schema

# Quantum Agent Card Schema Reference
## The Protocol Quantum-Enhanced Schema v2.0

## Overview

The Quantum Agent Card extends the current The Protocol Agent Card schema to support quantum computing capabilities, enabling agents to participate in the emerging quantum computation marketplace. This schema introduces quantum-specific roles, hardware specifications, and economic models for the quantum era.

The Quantum Agent Card enables:
- **Quantum Service Discovery**: Find quantum encoders, decoders, and QPU providers
- **Hardware Specifications**: Declare quantum hardware capabilities
- **Probabilistic Contracts**: Support for quantum result verification
- **Proof of Quantum Work**: Participate in quantum mining
- **Circuit Management**: Handle QIR/QASM formats
- **Error Correction**: Specify decoder capabilities
- **Quantum Marketplace**: Economic model for quantum services

## Complete Quantum Agent Card Example

```json
{
  // STANDARD AGENT CARD FIELDS (Inherited from v1.0)
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "developer_id": 123,
  "developer_is_verified": true,
  
  // ENHANCED CARD DATA WITH QUANTUM CAPABILITIES
  "card_data": {
    // Standard A2A Protocol Fields
    "schemaVersion": "2.0",  // Updated for quantum support
    "humanReadableId": "quantumvault/ibm-q-encoder",
    "agentVersion": "2.0.0",
    "name": "IBM Quantum Circuit Encoder",
    "description": "High-performance quantum circuit compilation for IBM quantum processors with advanced optimization",
    "url": "https://api.quantum-encoder.agentvault.org/a2a",
    
    "provider": {
      "name": "QuantumVault Services",
      "url": "https://quantumvault.agentvault.org",
      "support_contact": "quantum@agentvault.org",
      "quantum_certified": true,
      "certification_level": "enterprise"
    },
    
    "capabilities": {
      "a2aVersion": "1.0",
      "quantumVersion": "1.0",  // New: Quantum protocol version
      "supportedMessageParts": ["text", "file", "data", "json", "qasm", "qir"],
      "supportsPushNotifications": true,
      "supportsWebSocket": true,
      "federationEnabled": true,
      "quantumEnabled": true,  // New: Quantum capabilities flag
      "poqEnabled": true       // New: Proof of Quantum Work support
    },
    
    // QUANTUM-SPECIFIC CAPABILITIES
    "quantumCapabilities": {
      // Agent Roles in Quantum Ecosystem
      "roles": {
        "isEncoder": true,        // Can compile quantum circuits
        "isDecoder": false,       // Can decode quantum results
        "isQpuProvider": false,   // Has quantum hardware
        "isSimulator": true,      // Can simulate quantum circuits
        "isVerifier": true,       // Can verify quantum proofs
        "isValidator": true       // Can validate PoQ blocks
      },
      
      // Encoder Specifications (if isEncoder)
      "encoderSpecs": {
        "supportedFormats": ["QASM", "QIR", "Qiskit", "Cirq", "OpenQASM3"],
        "supportedBackends": ["IBM", "Google", "IonQ", "Rigetti", "Honeywell"],
        "optimizationLevels": [0, 1, 2, 3],  // 0=none, 3=maximum
        "maxCircuitDepth": 10000,
        "maxQubitCount": 127,
        "compilationStrategies": ["routing", "optimization", "error_mitigation"],
        "avgCompilationTimeMs": 250,
        "successRate": 99.5
      },
      
      // Decoder Specifications (if isDecoder)
      "decoderSpecs": {
        "errorCorrectionCodes": ["surface", "color", "repetition", "shor", "steane"],
        "decodingAlgorithms": ["MWPM", "UnionFind", "ML-Enhanced", "Tensor-Network"],
        "maxSyndromeRate": 10000,  // Syndromes per second
        "decodingAccuracy": 99.8,
        "supportedNoiseModels": ["depolarizing", "amplitude_damping", "phase_damping"],
        "realtimeCapable": true,
        "batchProcessing": true,
        "maxBatchSize": 1000
      },
      
      // QPU Provider Specifications (if isQpuProvider)
      "qpuSpecs": {
        "hardwareType": "superconducting",  // superconducting/trapped-ion/photonic/neutral-atom
        "qubitCount": 127,
        "connectivity": "heavy-hex",  // Topology type
        "connectivityGraph": {
          // Adjacency list representation
          "0": [1, 4],
          "1": [0, 2, 5],
          // ... full connectivity map
        },
        "nativeGates": ["X", "Y", "Z", "H", "CNOT", "RZ", "SX", "ECR"],
        "gateFidelities": {
          "single_qubit": 0.9999,
          "two_qubit": 0.995,
          "readout": 0.98
        },
        "coherenceTimes": {
          "t1_us": 100.5,  // T1 coherence time in microseconds
          "t2_us": 85.3    // T2 coherence time in microseconds
        },
        "quantumVolume": 512,
        "clops": 15000,  // Circuit layer operations per second
        "lastCalibration": "2025-08-15T06:00:00Z",
        "calibrationFrequency": "daily",
        "noiseModel": {
          "type": "empirical",
          "url": "https://quantum.agentvault.org/noise/ibm-q-127"
        }
      },
      
      // Simulator Specifications (if isSimulator)
      "simulatorSpecs": {
        "simulationType": "statevector",  // statevector/density-matrix/tensor-network
        "maxQubits": 35,
        "supportedGates": ["all"],  // Or specific gate list
        "noiseSimulation": true,
        "customNoiseModels": true,
        "gpuAccelerated": true,
        "distributedCompute": false,
        "avgSimulationTimePerGate": 0.001  // milliseconds
      },
      
      // Verifier Specifications (if isVerifier)
      "verifierSpecs": {
        "verificationMethods": ["cross_entropy", "quantum_supremacy", "bell_inequality"],
        "supportedCircuits": ["random", "qaoa", "vqe", "grover"],
        "statisticalTests": ["chi_square", "kolmogorov_smirnov", "anderson_darling"],
        "confidenceLevels": [0.95, 0.99, 0.999],
        "zkpSupport": true,
        "attestationEndpoint": "https://quantum.agentvault.org/attestation"
      }
    },
    
    // QUANTUM ECONOMIC MODEL
    "quantumEconomics": {
      "pricing": {
        "pricePerShot": "0.00001",      // TEG per quantum measurement
        "pricePerCircuit": "0.001",     // TEG per circuit compilation
        "pricePerQubitHour": "0.1",     // TEG per qubit-hour (QPU reservation)
        "pricePerDecode": "0.0001",     // TEG per syndrome decode
        "pricePerVerification": "0.005", // TEG per result verification
        "bulkDiscounts": [
          { "shots": 10000, "discount": 0.1 },
          { "shots": 100000, "discount": 0.2 }
        ]
      },
      "staking": {
        "minimumStake": "1000",  // Minimum TEG to provide services
        "validatorStake": "5000", // TEG required for PoQ validation
        "slashingConditions": ["false_results", "availability_violation"],
        "rewardDistribution": "proportional"  // or "equal", "performance_based"
      },
      "sla": {
        "availabilityTarget": 99.9,  // Percentage
        "maxQueueDepth": 100,
        "maxWaitTime": 3600,  // seconds
        "priorityTiers": ["standard", "priority", "exclusive"]
      }
    },
    
    // QUANTUM JOB SPECIFICATIONS
    "quantumJobSupport": {
      "supportedJobTypes": ["circuit_execution", "vqe", "qaoa", "quantum_ml", "error_correction"],
      "maxJobDuration": 86400,  // seconds
      "jobPriorities": ["low", "normal", "high", "critical"],
      "resultFormats": ["counts", "statevector", "density_matrix", "expectation_values"],
      "compressionSupport": ["gzip", "lz4", "zstd"],
      "encryptionSupport": ["aes256", "quantum_safe"]
    },
    
    // PROOF OF QUANTUM WORK
    "proofOfQuantumWork": {
      "minerCapable": true,
      "validatorCapable": true,
      "supportedChallenges": ["random_circuit_sampling", "boson_sampling", "iqp"],
      "hashPower": 1000,  // Relative quantum computing power
      "validationSpeed": 100,  // Validations per second
      "consensusParticipation": true,
      "rewardAddress": "did:agentvault:quantum-miner-001"
    },
    
    // STANDARD A2A FIELDS (Enhanced for Quantum)
    "authSchemes": [
      {
        "scheme": "oauth2",
        "description": "OAuth2 for quantum service access",
        "tokenUrl": "https://auth.quantumvault.org/oauth/token",
        "scopes": ["quantum:execute", "quantum:compile", "quantum:verify"],
        "service_identifier": "quantumvault-oauth"
      },
      {
        "scheme": "zkp",  // New: Zero-knowledge proof auth
        "description": "ZKP-based quantum attestation",
        "verificationEndpoint": "https://quantum.agentvault.org/zkp/verify",
        "circuitId": "quantum_authorization_v1"
      }
    ],
    
    "skills": [
      {
        "id": "circuit_compilation",
        "name": "Quantum Circuit Compilation",
        "description": "Compile high-level quantum circuits to hardware-specific implementations",
        "input_schema": {
          "type": "object",
          "properties": {
            "circuit": { "type": "string", "format": "qasm" },
            "backend": { "type": "string", "enum": ["IBM", "Google", "IonQ"] },
            "optimization_level": { "type": "integer", "minimum": 0, "maximum": 3 }
          },
          "required": ["circuit", "backend"]
        },
        "output_schema": {
          "type": "object",
          "properties": {
            "compiled_circuit": { "type": "string" },
            "gate_count": { "type": "integer" },
            "circuit_depth": { "type": "integer" },
            "estimated_fidelity": { "type": "number" }
          }
        }
      },
      {
        "id": "quantum_simulation",
        "name": "Quantum Circuit Simulation",
        "description": "Simulate quantum circuits up to 35 qubits",
        "input_schema": {
          "type": "object",
          "properties": {
            "circuit": { "type": "string" },
            "shots": { "type": "integer", "minimum": 1, "maximum": 100000 },
            "noise_model": { "type": "string", "enum": ["ideal", "realistic", "custom"] }
          }
        }
      }
    ],
    
    "tags": ["quantum", "encoder", "compiler", "IBM", "optimization", "VQE", "QAOA"],
    "quantumTags": ["superconducting", "error-mitigation", "variational", "NISQ"],
    
    // Quantum-specific URLs
    "quantumDocsUrl": "https://quantumvault.org/docs/quantum",
    "calibrationDataUrl": "https://quantum.agentvault.org/calibration/latest",
    "noiseModelUrl": "https://quantum.agentvault.org/noise/current"
  },
  
  // DATABASE FIELDS (Extended)
  "name": "IBM Quantum Circuit Encoder",
  "description": "High-performance quantum circuit compilation",
  "is_active": true,
  "quantum_capable": true,  // New indexed field
  
  // QUANTUM STATUS FIELDS
  "quantum_status": {
    "operational_status": "online",  // online/maintenance/offline/degraded
    "current_queue_depth": 42,
    "estimated_wait_time_s": 180,
    "last_successful_job": "2025-08-15T14:30:00Z",
    "success_rate_24h": 98.5,
    "total_jobs_completed": 152847
  },
  
  // TIMESTAMPS
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-08-15T14:45:00Z",
  "quantum_verified_at": "2025-08-15T12:00:00Z"  // Quantum capability verification
}
```

## Enhanced Database Schema

### QuantumCapabilities Table (New)

| Field Name | Type | Constraints | Description |
|------------|------|------------|-------------|
| `id` | UUID | Primary Key | Unique identifier |
| `agent_card_id` | UUID | Foreign Key, Unique | Link to agent card |
| `agent_did` | String | Foreign Key | Agent DID reference |
| `is_encoder` | Boolean | Default: false | Can compile circuits |
| `is_decoder` | Boolean | Default: false | Can decode results |
| `is_qpu_provider` | Boolean | Default: false | Has quantum hardware |
| `is_simulator` | Boolean | Default: false | Can simulate circuits |
| `is_verifier` | Boolean | Default: false | Can verify proofs |
| `supported_formats` | Array[String] | | Circuit formats |
| `qubit_count` | Integer | Nullable | Number of qubits |
| `gate_fidelity` | Float | Nullable | Average gate fidelity |
| `coherence_time_us` | Float | Nullable | Coherence time |
| `connectivity_graph` | JSON | Nullable | Qubit connectivity |
| `native_gates` | Array[String] | Nullable | Hardware gates |
| `quantum_volume` | Integer | Nullable | IBM QV metric |
| `clops` | Integer | Nullable | Circuit operations/sec |
| `price_per_shot` | Decimal(10,8) | Nullable | Cost per measurement |
| `price_per_circuit` | Decimal(10,8) | Nullable | Compilation cost |
| `last_calibration` | Timestamp | Nullable | Last calibration time |
| `verified_by` | String | Nullable | Verification authority |

### QuantumJobs Table (New)

| Field Name | Type | Constraints | Description |
|------------|------|------------|-------------|
| `id` | UUID | Primary Key | Job identifier |
| `job_id` | String | Unique, Indexed | External job ID |
| `client_did` | String | Foreign Key | Client agent DID |
| `encoder_did` | String | Foreign Key | Encoder agent DID |
| `qpu_provider_did` | String | Foreign Key | QPU provider DID |
| `decoder_did` | String | Foreign Key | Decoder agent DID |
| `circuit_hash` | String | Indexed | Circuit fingerprint |
| `circuit_depth` | Integer | | Circuit depth |
| `gate_count` | Integer | | Number of gates |
| `qubit_count` | Integer | | Number of qubits |
| `shots` | Integer | | Measurements requested |
| `result_distribution` | JSON | | Probability distribution |
| `result_confidence` | Float | | Statistical confidence |
| `error_rate` | Float | | Estimated error |
| `proof_of_quantum_hash` | String | | PoQ hash |
| `verification_status` | String | | pending/verified/failed |
| `total_cost` | Decimal(10,8) | | Total TEG cost |
| `submitted_at` | Timestamp | | Submission time |
| `completed_at` | Timestamp | Nullable | Completion time |

### ProofOfQuantumBlocks Table (New)

| Field Name | Type | Description |
|------------|------|-------------|
| `id` | UUID | Block identifier |
| `block_height` | Integer | Block number |
| `quantum_hash` | String | Quantum-generated hash |
| `challenge` | JSON | Quantum challenge |
| `solution` | JSON | Quantum solution |
| `miner_did` | String | Miner agent DID |
| `validators` | Array[String] | Validator DIDs |
| `difficulty` | Integer | Mining difficulty |
| `reward_amount` | Decimal | TEG reward |

## Quantum-Specific API Endpoints

### Quantum Service Discovery

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/quantum/providers` | List quantum service providers |
| GET | `/api/v1/quantum/encoders` | Find circuit compilers |
| GET | `/api/v1/quantum/decoders` | Find error decoders |
| GET | `/api/v1/quantum/qpu` | List QPU providers |
| GET | `/api/v1/quantum/simulators` | Find simulators |

### Quantum Job Management

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/quantum/circuits/submit` | Submit quantum circuit |
| GET | `/api/v1/quantum/jobs/{job_id}` | Get job status |
| GET | `/api/v1/quantum/jobs/{job_id}/result` | Get job results |
| POST | `/api/v1/quantum/jobs/{job_id}/verify` | Verify results |

### Proof of Quantum Work

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/quantum/blocks/mine` | Mine quantum block |
| POST | `/api/v1/quantum/blocks/validate` | Validate block |
| GET | `/api/v1/quantum/blocks/latest` | Get latest block |
| GET | `/api/v1/quantum/difficulty` | Current difficulty |

### Quantum Contracts

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/quantum/contracts/create` | Create probabilistic contract |
| POST | `/api/v1/quantum/contracts/{id}/verify` | Verify result distribution |
| GET | `/api/v1/quantum/contracts/{id}/payout` | Calculate payout |

## Quantum Message Formats

### QIR (Quantum Intermediate Representation)
```json
{
  "format": "QIR",
  "version": "0.1",
  "circuit": {
    "qubits": 5,
    "operations": [
      { "gate": "H", "targets": [0] },
      { "gate": "CNOT", "controls": [0], "targets": [1] }
    ]
  }
}
```

### QASM (Quantum Assembly)
```qasm
OPENQASM 3;
include "stdgates.inc";

qubit[5] q;
bit[5] c;

h q[0];
cx q[0], q[1];
measure q -> c;
```

## Probabilistic Smart Contract Example

```python
{
  "contract_type": "probabilistic",
  "expected_distribution": {
    "00": 0.5,
    "11": 0.5
  },
  "confidence_threshold": 0.95,
  "min_shots": 8192,
  "verification_method": "chi_square",
  "payout_formula": "base_amount * (confidence * fidelity)",
  "dispute_resolution": "statistical_arbitration"
}
```

## WebSocket Events (Quantum-Enhanced)

```javascript
// Quantum job submitted
{
  "type": "quantum_job_submitted",
  "data": {
    "job_id": "qjob_123",
    "circuit_hash": "0xabc...",
    "encoder": "did:encoder",
    "qpu": "did:qpu"
  }
}

// Quantum block mined
{
  "type": "quantum_block_mined",
  "data": {
    "block_height": 12345,
    "quantum_hash": "0x000...",
    "miner": "did:miner",
    "reward": "100"
  }
}

// QPU status change
{
  "type": "qpu_status_change",
  "data": {
    "qpu_did": "did:qpu",
    "status": "maintenance",
    "estimated_downtime": 3600
  }
}
```

## Best Practices for Quantum Agents

1. **Calibration Updates**: Update calibration data at least daily
2. **Error Rates**: Report honest error rates for reputation
3. **Queue Management**: Implement fair queuing algorithms
4. **Result Caching**: Cache frequently requested simulations
5. **Noise Models**: Provide accurate noise characterization
6. **Price Transparency**: Clear pricing for all quantum operations
7. **Verification**: Support multiple verification methods
8. **Documentation**: Provide quantum-specific documentation

## Migration Path to Quantum

### Phase 1: Basic Quantum Support
1. Add `quantum_capable` flag to existing agents
2. Implement basic circuit format support
3. Register as simulator if applicable

### Phase 2: Full Quantum Integration
1. Complete QuantumCapabilities registration
2. Implement pricing model
3. Join quantum job marketplace
4. Support verification protocols

### Phase 3: Advanced Quantum Features
1. Participate in PoQ consensus
2. Offer specialized quantum services
3. Implement error correction
4. Support quantum contracts

## Validation Rules (Quantum-Specific)

1. **Qubit Count Consistency**: Declared qubits must match actual capacity
2. **Fidelity Verification**: Gate fidelities must be verifiable
3. **Calibration Freshness**: Calibration data must be < 7 days old
4. **Price Reasonableness**: Prices must be within market ranges
5. **Format Support**: Must handle declared circuit formats
6. **Connectivity Accuracy**: Graph must represent actual topology

## Economic Considerations

### Staking Requirements
- **Encoder**: 100 TEG minimum stake
- **Decoder**: 100 TEG minimum stake
- **QPU Provider**: 1000 TEG minimum stake
- **Validator**: 5000 TEG minimum stake

### Reward Distribution
- **Job Execution**: 70% provider, 20% platform, 10% validators
- **Block Mining**: 50% miner, 30% validators, 20% treasury
- **Verification**: Fixed fee per verification

This reference represents the future quantum-enhanced implementation of Agent Cards in the Protocol Registry system, positioning agents for the quantum computing era.