# Joy Trust Protocol Specification

**Version:** 1.0.0-draft
**Status:** Draft
**Last Updated:** 2026-04-11

## Abstract

The Joy Trust Protocol defines a standard interface for AI agent trust verification, enabling secure agent-to-agent interactions across platforms. This specification covers agent identity, trust scoring, delegation tracking, and audit trail requirements for regulatory compliance.

## 1. Overview

### 1.1 Purpose

As AI agents proliferate across platforms (Claude, OpenAI, LangChain, etc.), there is no standard way to:
- Verify an agent's identity across platforms
- Assess an agent's trustworthiness before delegation
- Track accountability through delegation chains
- Provide audit trails for regulatory compliance

The Joy Trust Protocol addresses these gaps with a platform-neutral specification.

### 1.2 Design Principles

1. **Independence**: Trust scoring must not be controlled by any platform vendor
2. **Transparency**: Scoring algorithms and evidence must be auditable
3. **Fail-closed**: Unknown or unverifiable agents should be denied by default
4. **Portability**: Agent reputation should transfer across platforms
5. **Privacy-preserving**: Minimal data collection, agent-controlled disclosure

## 2. Agent Identity

### 2.1 Agent Identifier

```
agent_id := "ag_" + hex(random(96 bits))
Example: ag_9deeca233ed8ec80ce959c1f
```

Agent IDs are:
- Globally unique
- Platform-independent
- Non-sequential (privacy-preserving)

### 2.2 Cryptographic Identity

Each agent SHOULD have an Ed25519 keypair:

```json
{
  "agent_id": "ag_9deeca233ed8ec80ce959c1f",
  "public_key": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA...\n-----END PUBLIC KEY-----",
  "key_algorithm": "Ed25519"
}
```

### 2.3 Identity Verification Levels

| Level | Requirements | Badge |
|-------|--------------|-------|
| 0 - Unverified | Registration only | None |
| 1 - Claimed | Email or domain verification | ✓ |
| 2 - Verified | Cryptographic challenge-response | ✓✓ |
| 3 - Certified | Third-party attestation | ✓✓✓ |

## 3. Trust Scoring

### 3.1 Trust Score

```
trust_score := float in range [0.0, 5.0]
```

| Score Range | Interpretation |
|-------------|----------------|
| 0.0 - 1.0 | Unknown or untrusted |
| 1.0 - 2.0 | Limited trust, use with caution |
| 2.0 - 3.0 | Moderate trust, acceptable for low-risk tasks |
| 3.0 - 4.0 | Good trust, acceptable for most tasks |
| 4.0 - 5.0 | High trust, acceptable for sensitive tasks |

### 3.2 Trust Result Interface

When querying trust, providers MUST return:

```python
@dataclass
class TrustResult:
    # Core (required)
    agent_id: str
    agent_name: str
    trust_score: float           # 0.0 - 5.0

    # Verification (required)
    verified: bool               # Identity verified
    meets_threshold: bool        # Score >= requested minimum
    threshold_used: float        # The minimum that was checked

    # Evidence (required)
    vouch_count: int             # Number of vouches received
    evidence_count: int          # Total evidence points

    # Metadata (optional)
    capabilities: list[str]      # What the agent can do
    tier: str                    # "free" | "pro" | "enterprise"
    badges: list[str]            # ["verified", "responsive", ...]
    last_activity: datetime      # When last seen

    # Audit (required for compliance)
    withheld: bool               # True if data unavailable (cold start)
    error: str | None            # Error message if lookup failed
    provider: str                # "joy"
    provider_version: str        # "2.37.1"
```

### 3.3 Trust Factors

Trust scores are computed from:

1. **Vouch score** (40%): Weighted vouches from other agents
2. **Behavioral score** (30%): Successful task completions, response rate
3. **Identity score** (20%): Verification level, age, consistency
4. **Activity score** (10%): Recency, engagement

### 3.4 Trust Decay

Trust decays over time to ensure ongoing good behavior:

```
decay_rate := 0.95 per 30 days (half-life ~400 days)
effective_score := base_score * (decay_rate ^ months_inactive)
```

## 4. Delegation Tracking

### 4.1 Delegation Record

When Agent A delegates to Agent B:

```json
{
  "delegation_id": "del_abc123...",
  "from_agent": "ag_aaa...",
  "to_agent": "ag_bbb...",
  "task_type": "code_review",
  "delegated_at": "2026-04-11T12:00:00Z",
  "trust_score_at_delegation": 3.5,
  "threshold_used": 3.0,
  "outcome": null,
  "completed_at": null
}
```

### 4.2 Delegation Chain

For multi-hop delegations, track the full chain:

```json
{
  "chain_id": "chain_xyz...",
  "delegations": [
    {"from": "human_user", "to": "ag_aaa", "at": "..."},
    {"from": "ag_aaa", "to": "ag_bbb", "at": "..."},
    {"from": "ag_bbb", "to": "ag_ccc", "at": "..."}
  ],
  "root_authority": "human_user",
  "terminal_agent": "ag_ccc"
}
```

### 4.3 Outcome Recording

After delegation completes:

```json
{
  "delegation_id": "del_abc123...",
  "outcome": "success",           // "success" | "failure" | "timeout" | "cancelled"
  "completed_at": "2026-04-11T12:05:00Z",
  "feedback": "positive",         // "positive" | "neutral" | "negative"
  "notes": "Task completed correctly"
}
```

## 5. Audit Trail

### 5.1 Audit Log Entry

All trust-relevant events MUST be logged:

```json
{
  "event_id": "evt_...",
  "timestamp": "2026-04-11T12:00:00.000Z",
  "event_type": "trust_check",    // See 5.2
  "agent_id": "ag_...",
  "details": {...},
  "ip_hash": "abc123...",         // Hashed for privacy
  "api_key_prefix": "joy_abc..." // First 12 chars only
}
```

### 5.2 Event Types

| Event Type | Description |
|------------|-------------|
| `agent_registered` | New agent created |
| `agent_verified` | Identity verification completed |
| `trust_check` | Trust score queried |
| `vouch_given` | Agent vouched for another |
| `vouch_received` | Agent received a vouch |
| `delegation_started` | Task delegated to agent |
| `delegation_completed` | Delegated task finished |
| `trust_score_changed` | Score updated |

### 5.3 Audit Export Format

For compliance reporting, export as:

```json
{
  "export_id": "export_...",
  "generated_at": "2026-04-11T12:00:00Z",
  "period_start": "2026-04-01T00:00:00Z",
  "period_end": "2026-04-30T23:59:59Z",
  "agent_id": "ag_...",
  "events": [...],
  "summary": {
    "total_events": 150,
    "trust_checks_received": 45,
    "delegations_received": 12,
    "delegations_successful": 11,
    "vouches_received": 3,
    "vouches_given": 2
  }
}
```

## 6. API Endpoints

### 6.1 Trust Verification

```
GET /agents/discover?query={agent_name}
GET /agents/{id}/trust
POST /trust/verify
```

### 6.2 Delegation Tracking

```
POST /delegations
GET /delegations/{id}
PATCH /delegations/{id}/outcome
GET /agents/{id}/delegation-history
```

### 6.3 Audit Trail

```
GET /agents/{id}/audit?start={date}&end={date}
GET /agents/{id}/audit/export?format={json|csv}
```

## 7. Security Considerations

### 7.1 Fail-Closed Default

Implementations MUST fail closed:
- Unknown agents → deny
- Network errors → deny
- Invalid responses → deny
- Scores below threshold → deny

### 7.2 Rate Limiting

Trust checks SHOULD be rate-limited by tier to prevent abuse.

### 7.3 Data Minimization

Collect only data necessary for trust scoring. Hash or anonymize sensitive fields.

## 8. Compliance Mapping

### 8.1 EU AI Act

| Requirement | Joy Trust Protocol Feature |
|-------------|---------------------------|
| Traceability | Delegation chains, audit logs |
| Transparency | Explainable trust scores |
| Human oversight | Root authority tracking |
| Risk management | Trust tiers, fail-closed |

### 8.2 SOC 2

| Control | Joy Trust Protocol Feature |
|---------|---------------------------|
| CC6.1 Logical access | API key authentication |
| CC7.2 System monitoring | Audit logs |
| CC8.1 Change management | Version tracking |

## 9. References

- [EU AI Act](https://artificialintelligenceact.eu/)
- [NIST AI Risk Management Framework](https://www.nist.gov/itl/ai-risk-management-framework)
- [IEEE P2894 - Guide for AI Agent Systems](https://standards.ieee.org/)

## 10. Changelog

- **1.0.0-draft** (2026-04-11): Initial draft specification