> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.adid.dev/llms.txt.
> For full documentation content, see https://docs.adid.dev/llms-full.txt.

# Agent Trust Registry

The Agent Trust Registry is an on-chain smart contract that maintains agent identity, reputation scores, and capability attestations. It enables verifiers to make trust decisions about agents based on observable, verifiable signals.

## Architecture

```mermaid
graph TB
    subgraph "On-Chain (Agent Trust Registry)"
        REG[Agent Registration]
        SCORE[Trust Scoring]
        CAP[Capability Registry]
        VAL[Validator Hooks]
    end

    subgraph "Off-Chain Signals"
        VH[Verification History]
        DV[Delegation Validity]
        AT[Third-Party Attestations]
        AR[Action Results]
    end

    subgraph "Consumers"
        V[Verifiers]
        M[Marketplace]
        A[Other Agents]
    end

    VH --> SCORE
    DV --> SCORE
    AT --> SCORE
    AR --> SCORE

    REG --> V
    SCORE --> V
    SCORE --> M
    CAP --> A
    VAL --> SCORE
```

## Trust Score

The trust score is a composite metric (0-100) computed from multiple signals:

### Scoring Formula

```
trustScore = w1 * verificationSuccessRate
           + w2 * delegationValidityRate
           + w3 * attestationScore
           + w4 * longevityBonus
           + w5 * actionSuccessRate
           - penalties
```

### Weights

| Signal                    | Weight (w) | Description                                  |
| ------------------------- | ---------- | -------------------------------------------- |
| Verification success rate | 0.25       | % of successful VC verifications             |
| Delegation validity rate  | 0.20       | % of time delegation chain is valid          |
| Attestation score         | 0.25       | Weighted score from third-party attestations |
| Longevity bonus           | 0.10       | Time since registration (capped)             |
| Action success rate       | 0.20       | % of successful actions (non-reverted)       |

### Penalties

| Penalty                 | Points | Trigger                              |
| ----------------------- | ------ | ------------------------------------ |
| Failed verification     | -5     | Agent presented invalid credential   |
| Delegation revoked      | -10    | Operator revoked delegation          |
| Suspension              | -20    | Agent was suspended                  |
| Scope violation attempt | -15    | Agent attempted action outside scope |
| Complaint               | -5 per | User filed complaint against agent   |

### Score Interpretation

| Range  | Level     | Color  | Description                            |
| ------ | --------- | ------ | -------------------------------------- |
| 90-100 | Excellent | Green  | Highly trusted, eligible for Principal |
| 80-89  | Good      | Green  | Trusted, eligible for Senior           |
| 60-79  | Fair      | Amber  | Moderate trust, Junior level           |
| 40-59  | Low       | Orange | Needs improvement                      |
| 0-39   | Poor      | Red    | Requires investigation                 |

## Autonomy Levels

Trust scores drive autonomy level promotions and demotions:

| Level     | Required Score | Required Actions | Additional Requirements   |
| --------- | -------------- | ---------------- | ------------------------- |
| Intern    | 0+             | 0                | Default for new agents    |
| Junior    | 60+            | 100+             | No suspensions in 30 days |
| Senior    | 80+            | 1000+            | Operator approval         |
| Principal | 90+            | 5000+            | Security audit passed     |

### Promotion Request

```http
POST /api/v1/agents/did:adi:agent:shop01.../promote
Authorization: Bearer <operator-api-key>

{
  "targetLevel": "Senior",
  "justification": "1500 successful actions, trust score 85, no incidents"
}
```

### Automatic Demotion

If an agent's trust score drops below the threshold for their current level:

```
Senior (score 85) -> trust score drops to 72 -> automatically demoted to Junior
```

## Validator Hooks

Third parties can register as validators to provide attestations:

```solidity
interface IAgentValidator {
    function validateAgent(
        string calldata agentDid,
        bytes calldata attestationData
    ) external returns (bool valid, uint8 score);
}
```

### Register a Validator

```http
POST /api/v1/trust-registry/validators
Authorization: Bearer <admin-api-key>

{
  "validatorDid": "did:adi:auditor001...",
  "name": "SafetyFirst Auditing",
  "type": "safety-auditor",
  "contractAddress": "0xvalidator..."
}
```

### Attestation Types

| Type                    | Validator                | Score Impact   |
| ----------------------- | ------------------------ | -------------- |
| Safety audit            | Certified auditor        | +15 points     |
| Capability verification | IDA platform             | +10 points     |
| Compliance certificate  | Regulatory body          | +10 points     |
| Peer review             | Other agents (>80 trust) | +5 points      |
| User rating             | End users                | +/- 1-5 points |

## On-Chain Data

### Agent Registration Record

```solidity
struct AgentRecord {
    string agentDid;
    string operatorDid;
    uint8 trustScore;
    AgentState state;          // registered, active, suspended, decommissioned
    AutonomyLevel autonomy;    // intern, junior, senior, principal
    uint256 registeredAt;
    uint256 lastUpdated;
    uint256 totalActions;
    uint256 successfulActions;
    string[] capabilities;
}
```

### Smart Contract Interface

```solidity
interface IAgentTrustRegistry {
    function registerAgent(string calldata agentDid, string calldata operatorDid, string[] calldata capabilities) external;
    function getAgent(string calldata agentDid) external view returns (AgentRecord memory);
    function updateTrustScore(string calldata agentDid, int8 delta, string calldata reason) external;
    function setAgentState(string calldata agentDid, AgentState state) external;
    function promoteAgent(string calldata agentDid, AutonomyLevel level) external;
    function recordAction(string calldata agentDid, bool success) external;
    function addAttestation(string calldata agentDid, string calldata validatorDid, uint8 score) external;
    function decommissionAgent(string calldata agentDid) external;

    event AgentRegistered(string agentDid, string operatorDid);
    event TrustScoreUpdated(string agentDid, uint8 oldScore, uint8 newScore, string reason);
    event AgentStateChanged(string agentDid, AgentState oldState, AgentState newState);
    event AgentPromoted(string agentDid, AutonomyLevel oldLevel, AutonomyLevel newLevel);
    event AgentDecommissioned(string agentDid);
}
```

## Querying the Registry

### Get Agent Trust Info

```http
GET /api/v1/trust-registry/agents/did:adi:agent:shop01...
```

```json
{
  "agentDid": "did:adi:agent:shop01...",
  "operatorDid": "did:adi:human001...",
  "trustScore": 85,
  "autonomyLevel": "Senior",
  "state": "active",
  "stats": {
    "totalActions": 1523,
    "successfulActions": 1498,
    "successRate": 0.983,
    "registeredAt": "2026-03-15T09:00:00Z",
    "daysSinceRegistration": 13
  },
  "attestations": [
    {
      "validator": "did:adi:auditor001...",
      "type": "safety-audit",
      "score": 15,
      "issuedAt": "2026-03-20T00:00:00Z"
    }
  ],
  "capabilities": ["shopping", "price-comparison", "order-placement"],
  "scoreHistory": [
    { "date": "2026-03-28", "score": 85 },
    { "date": "2026-03-21", "score": 82 },
    { "date": "2026-03-14", "score": 60 }
  ]
}
```

### Search Agents by Trust Score

```http
GET /api/v1/trust-registry/agents?minScore=80&capability=shopping&state=active
```

### Leaderboard

```http
GET /api/v1/trust-registry/leaderboard?capability=shopping&limit=10
```