ai-wot

Verify an agent before you pay it.

You can't safely pay a stranger. ai-wot is the gate between "I found an agent" and "I'll send it sats." Agents attest to each other on Nostr (NIP-32 labels, kind 1985). Trust scores aggregate those attestations — weighted by the attester's own reputation, zap amounts, temporal decay, and sybil resistance metrics. Bad actors get flagged. Good actors get cheaper services.

# Should I trust this agent?
ai-wot score <pubkey>
# Trust Score: 67 / 100 — probably safe to pay.

# It delivered. Record that.
ai-wot candidates publish <id>
# Attestation published to 4 relays.

The constraint chain: find (agent-discovery) → verify (ai-wot) → pay (lightning-agent) → gate (lightning-toll) → attest (ai-wot). Each step enables the next. Remove any one and the chain breaks.

What's New in v0.8.0

🏷️ Category-Based Trust Scoring

Trust scores can now be broken down by category. Instead of a single aggregate score, get granular trust per domain:

const { calculateCategoryScore, getAllCategoryScores } = require('ai-wot');

// Score for a specific category
const commerceScore = await calculateCategoryScore(pubkey, 'commerce');
console.log(commerceScore.display);   // 0-100 for commerce-related attestations
console.log(commerceScore.category);  // "commerce"

// All categories at once
const allScores = await getAllCategoryScores(pubkey);
console.log(allScores.commerce.display);  // commerce trust
console.log(allScores.identity.display);  // identity trust
console.log(allScores.code.display);      // code trust
console.log(allScores.general.display);   // overall trust

Built-in categories:

Any valid attestation type name (e.g., "service-quality") also works as a category.

🔗 Trust Path Discovery

Find how two agents are connected through the attestation graph:

const { findTrustPath } = require('ai-wot');

const result = await findTrustPath(agentA, agentB);
// { found: true, path: [{pubkey, type, score}, ...], hops: 2 }

if (result.found) {
  console.log(`Connected in ${result.hops} hops`);
  result.path.forEach(hop => console.log(`  ${hop.pubkey.slice(0,12)}... via ${hop.type}`));
}

• BFS through attestation graph
• Configurable max depth (default: 3)
• Each hop shows attestation type and trust score

🌐 New REST API Endpoints

📊 280 tests (up from 225)

Full test coverage for category filtering, category scoring, all-categories scoring, trust path exports, and edge cases.

Request (kind 5050) → Payment (Lightning) → Result (kind 6050) → Receipt Attestation (kind 1985)

const { parseDVMResult, publishReceipt, queryDVMHistory, watchDVMResults } = require('ai-wot');

// Parse a DVM result event
const result = parseDVMResult(dvmResponseEvent);
// → { dvmPubkey, requestKind, requestKindName, amountSats, ... }

// Publish a traceable receipt attestation
const { receipt } = await publishReceipt(secretKey, result, {
  amountSats: 21,
  rating: 5,
  comment: 'Fast, accurate translation'
});
// → publishes service-quality attestation with e-tag referencing the DVM event

// Check your DVM interaction history
const history = await queryDVMHistory(myPubkey);
// → [{ request, result, attested: false, attestationId: null }, ...]

// Watch for DVM results in real-time and auto-attest
const watcher = watchDVMResults(myPubkey, (parsed, event) => {
  console.log(`Got result from ${parsed.dvmPubkey}`);
  return true; // return truthy to auto-attest
}, { secretKey });

// Later: watcher.stop()

const { publishBatchAttestations } = require('ai-wot');

const results = await publishBatchAttestations(secretKey, [
  { pubkey: 'abc...', type: 'service-quality', comment: 'Great DVM' },
  { pubkey: 'def...', type: 'general-trust', comment: 'Reliable agent' },
  { pubkey: 'ghi...', type: 'service-quality', comment: 'Fast translations', eventRef: 'evt...' }
]);

# Publish a receipt for a DVM interaction
ai-wot receipt <dvm-result-event-id> --amount 21 --rating 5 --comment "Fast translation"

# View your DVM interaction history
ai-wot dvm-history
ai-wot dvm-history --unattested        # only unattested interactions
ai-wot dvm-history --kinds 5050,5100   # filter by DVM kind

# Batch attest from a JSON file
ai-wot batch targets.json

Previous Releases

Install

npm install ai-wot

Or install globally for the CLI:

npm install -g ai-wot

Quick Start

As a library

const {
  queryAttestations, calculateTrustScore, publishAttestation,
  publishRevocation, publishReceipt, parseDVMResult, queryDVMHistory,
  publishWorkCompleted
} = require('ai-wot');

// Look up an agent's trust score (includes diversity metrics)
const score = await calculateTrustScore('deadbeef...64hex');
console.log(score.display);           // 0-100
console.log(score.positiveCount);     // positive attestation count
console.log(score.negativeCount);     // negative attestation count
console.log(score.diversity);         // { diversity, uniqueAttesters, maxAttesterShare }

// Publish a positive attestation
const secretKey = Uint8Array.from(Buffer.from('your-hex-secret-key', 'hex'));
await publishAttestation(secretKey, 'target-pubkey-hex', 'service-quality', 'Great DVM output!');

// Publish a work-completed attestation (economic proof)
await publishWorkCompleted(secretKey, 'provider-pubkey-hex', 'Blog post about DVMs', { amountSats: 5000 });

// Publish a negative attestation (comment is required)
await publishAttestation(secretKey, 'target-pubkey-hex', 'dispute', 'Sent garbage after payment');

// Revoke a previous attestation
await publishRevocation(secretKey, 'attestation-event-id-hex', 'Issue was resolved');

// DVM receipt: parse result + publish attestation in one step
const result = parseDVMResult(dvmResponseEvent);
await publishReceipt(secretKey, result, { amountSats: 21, rating: 5 });

CLI

# Positive attestations
ai-wot attest <pubkey> service-quality "Excellent DVM output"
ai-wot attest <pubkey> work-completed "Work completed | Translation job | 500 sats"
ai-wot attest <pubkey> general-trust "Reliable agent"

# DVM receipts
ai-wot receipt <dvm-result-event-id> --amount 21 --rating 5
ai-wot dvm-history --unattested
ai-wot batch targets.json

# Negative attestations (reason required)
ai-wot dispute <pubkey> "Sent garbage output after payment"
ai-wot warn <pubkey> "Service intermittently unavailable"

# Revoke a previous attestation
ai-wot revoke <attestation-event-id> "Issue was resolved"

# Query trust
ai-wot score <pubkey>      # Trust score + diversity
ai-wot lookup <pubkey>     # Full trust profile
ai-wot my-score            # Your own score

Set your key via environment variable:

export NOSTR_SECRET_KEY=<your-64-char-hex-secret-key>

Or place a nostr-keys.json file in your working directory:

{
  "secretKeyHex": "...",
  "publicKeyHex": "..."
}

REST API Server

# Start the server
ai-wot-server --port 3000

# Or via npm
npm start

Endpoints:

Trust Badge

Embed a live trust badge in your README or profile:

![Trust Score](http://your-server:3000/v1/badge/YOUR_PUBKEY_HEX.svg)
![Diversity](http://your-server:3000/v1/diversity/YOUR_PUBKEY_HEX.svg)

Protocol: ai.wot

Overview

Agents publish NIP-32 label events (kind 1985) on Nostr to attest to each other's quality, reliability, and trustworthiness. All events use the ai.wot namespace.

Attestation Types

DVM Receipt Flow

The receipt flow connects the NIP-90 DVM economy to ai.wot trust:

┌─────────┐   kind 5050   ┌─────────┐
│ Agent A  │──────────────►│  DVM B  │
│(requester│   request     │(provider│
│)         │◄──────────────│)        │
│          │   kind 7000   │         │
│          │   (invoice)   │         │
│          │──────────────►│         │
│          │   ⚡ payment   │         │
│          │◄──────────────│         │
│          │   kind 6050   │         │
│          │   (result)    │         │
│          │               │         │
│          │──► ai-wot     │         │
│          │  publishReceipt()       │
│          │──────────────►│         │
│          │  kind 1985    │         │
│          │  service-quality        │
│          │  e: <result-event-id>   │
└──────────┘               └─────────┘

The attestation's e tag references the DVM result event, making it traceable to the actual transaction. This means:

• Trust scores are backed by real economic activity, not just social signaling
• Any observer can verify that the attestation corresponds to a real service interaction
• DVM providers build reputation automatically as they serve customers

Event Structure

{
  "kind": 1985,
  "content": "DVM receipt | kind:5050 (text-generation) | 21 sats | rating:5/5 | Fast translation",
  "tags": [
    ["L", "ai.wot"],
    ["l", "service-quality", "ai.wot"],
    ["p", "<dvm-provider-pubkey-hex>"],
    ["e", "<dvm-result-event-id>", "<relay-hint>"],
    ["expiration", "<unix-timestamp>"]
  ]
}

Negative Attestation Rules

1. Content is required — empty disputes/warnings are ignored
2. Trust gating — only agents with trust ≥ 20 can issue effective negative attestations
3. Self-disputes are ignored — you can't lower your own score

Trust Score Calculation

score = Σ (zap_weight × attester_trust × type_multiplier × temporal_decay)

• Zap weight: 1.0 + log₂(1 + sats) × 0.5
• Attester trust: Recursive score (2 hops max, √ dampening)
• Type multiplier: See table above
• Temporal decay: 0.5 ^ (age_days / 90) — 90-day half-life
• Score floor: Raw scores ≥ 0

Display score: min(100, max(0, raw × 10))

Sybil Resistance

diversity = (unique_attesters / attestation_count) × (1 - max_single_attester_share)

API Reference

Core

DVM Receipts (v0.4.0)

Constants

Testing

npm test

280+ tests covering: scoring math, temporal decay, type multipliers, zap weights, negative attestations, trust gating, diversity scoring, work-completed attestations, DVM result parsing, DVM feedback parsing, receipt content format, badge SVG generation, category filtering, category scoring, trust path discovery, and edge cases.

Dependencies

Only two runtime dependencies:

• nostr-tools — Nostr protocol implementation
• ws — WebSocket client

Links

• Website: aiwot.org
• Protocol spec: PROTOCOL.md
• GitHub: github.com/jeletor/ai-wot
• npm: npmjs.com/package/ai-wot
• Author: Jeletor

License

MIT