> ## Documentation Index
> Fetch the complete documentation index at: https://docs.x0protocol.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Registry & Reputation

> Agent discovery with RegistryManager and trust scoring with ReputationManager.

## RegistryManager

The `RegistryManager` handles agent registration, capability discovery, and metadata management.

```typescript theme={null}
const registry = client.registry;
```

### Registering an Agent

```typescript theme={null}
const { instruction, registryAddress } = registry.buildRegisterAgentInstruction({
  agentPolicyId: policyPda,
  owner: ownerPubkey,
  endpoint: 'https://my-agent.example.com/api',
  capabilities: [
    registry.createCapability('text_generation', '{"model":"gpt-4","maxTokens":4096}'),
    registry.createCapability('code_execution', '{"runtime":"node20"}'),
  ],
  metadataJson: registry.buildMetadata({
    name: 'My Agent',
    description: 'General-purpose AI agent',
    version: '1.0.0',
    documentation: 'https://docs.example.com',
    tags: ['ai', 'text'],
    rateLimit: '100/min',
  }),
});
```

### Capability Types

Built-in capability type constants:

```typescript theme={null}
RegistryManager.CAPABILITY_TYPES = {
  TEXT_GENERATION,
  IMAGE_GENERATION,
  CODE_EXECUTION,
  WEB_SEARCH,
  DATA_ANALYSIS,
  EMBEDDING,
  SPEECH_TO_TEXT,
  TEXT_TO_SPEECH,
  TRANSLATION,
  SUMMARIZATION,
  CUSTOM,
};
```

### Discovery

```typescript theme={null}
// Find agents by capability
const agents = await registry.findAgentsByCapability('text_generation');

// Find cheapest agent for a capability
const cheapest = await registry.findCheapestAgent('image_generation');

// Find agents by domain
const merchants = await registry.findAgentsByDomain('merchant');

// Get all active agents
const all = await registry.getAllActiveAgents();
```

### Updating & Deregistering

```typescript theme={null}
// Update endpoint
const updateIx = registry.buildUpdateRegistryInstruction(
  ownerPubkey, registryPda,
  { endpoint: 'https://new-endpoint.com/api' }
);

// Deactivate (soft delete)
const deactivateIx = registry.buildDeactivateInstruction(ownerPubkey, registryPda);

// Reactivate
const reactivateIx = registry.buildReactivateInstruction(ownerPubkey, registryPda);

// Permanently deregister
const deregisterIx = registry.buildDeregisterInstruction(ownerPubkey, registryPda);
```

### Metadata Builder

```typescript theme={null}
const json = registry.buildMetadata({
  name: 'Translation Agent',
  description: 'Translates text between 40 languages',
  version: '2.1.0',
  documentation: 'https://docs.translate.ai',
  terms: 'https://translate.ai/terms',
  contact: 'support@translate.ai',
  tags: ['translation', 'nlp'],
  rateLimit: '50/min',
});
```

***

## ReputationManager

The `ReputationManager` handles reputation initialization, scoring, decay, and analytics.

```typescript theme={null}
const reputation = client.reputation;
```

### Initialize Reputation

```typescript theme={null}
const { instruction, reputationAddress } = reputation.buildInitializeReputationInstruction(
  payerPubkey,
  agentPolicyId
);
```

### Recording Outcomes

Called by the escrow program via CPI — but available for direct use in testing:

```typescript theme={null}
// Record successful transaction
const successIx = reputation.buildRecordSuccessInstruction(
  authority, reputationPda, volume
);

// Record dispute
const disputeIx = reputation.buildRecordDisputeInstruction(authority, reputationPda);

// Record resolution in agent's favor
const resolutionIx = reputation.buildRecordResolutionFavorInstruction(authority, reputationPda);

// Record failure
const failureIx = reputation.buildRecordFailureInstruction(
  authority, agentPolicyId, reputationPda, errorCode
);
```

### Scoring

```typescript theme={null}
// Calculate current score (0-10000)
const score = reputation.calculateScore(account);

// Score with temporal decay applied
const decayedScore = reputation.calculateScoreWithDecay(account);

// Format as percentage
reputation.formatScoreAsPercentage(8500); // "85.00%"
```

### Reputation Tiers

| Tier        | Min Score | Percentage |
| ----------- | --------- | ---------- |
| `legendary` | 9500      | ≥ 95%      |
| `excellent` | 8500      | ≥ 85%      |
| `good`      | 7000      | ≥ 70%      |
| `fair`      | 5000      | ≥ 50%      |
| `poor`      | 2500      | ≥ 25%      |
| `untrusted` | 0         | \< 25%     |

```typescript theme={null}
const { tier, label, minScore } = reputation.getReputationTier(8700);
// { tier: 'excellent', label: 'Excellent', minScore: 8500 }
```

### Querying

```typescript theme={null}
// Get a specific agent's reputation
const account = await reputation.fetchReputationByAgent(agentPolicyId);

// Get detailed snapshot
const details = reputation.getDetailedSnapshot(account);
// { agentId, score, tier, tierLabel, successRate, disputeRate, totalVolume, ... }

// Top agents by score
const top = await reputation.getTopAgents(10);

// Agents above a threshold
const reliable = await reputation.getAgentsAboveThreshold(7000);

// Check if agent meets requirement
const ok = await reputation.meetsReputationRequirement(agentPolicyId, 8000);

// Network-wide analytics
const avg = await reputation.getAverageScore();
const distribution = await reputation.getDistributionByTier();
// { legendary: 5, excellent: 23, good: 45, fair: 12, poor: 3, untrusted: 2 }
```

### Temporal Decay

Reputation scores decay at 1% per 30 days of inactivity:

```typescript theme={null}
// Apply decay manually
const decayIx = reputation.buildApplyDecayInstruction(reputationPda);

// Check score with decay
const currentScore = reputation.calculateScoreWithDecay(account);
```

### Migration & Cleanup

```typescript theme={null}
// Migrate v1 account to v2
const migrateIx = reputation.buildMigrateReputationInstruction(owner, policyId, repPda);

// Close reputation account (owner only)
const closeIx = reputation.buildCloseReputationInstruction(owner, policyId);
```