<p align="center">
  <img src="./brand/logo-full.png" alt="Vaultfire" width="420" />
</p>

# @vaultfire/a2a


> **⚠️ Alpha Software** — Vaultfire Protocol is in active development. Smart contracts are deployed on mainnet but have **not been formally audited** by a third-party security firm. Use at your own risk. APIs and interfaces may change. See [LICENSE](./LICENSE) for warranty disclaimers.

Bridge **Google's A2A (Agent-to-Agent) protocol** with **Vaultfire Protocol's on-chain trust**.

Any A2A-compatible agent can use this package to:
- Enrich their Agent Card with Street Cred score, bond status, and reputation from the blockchain
- Verify other agents' trust before delegating tasks via A2A
- Discover trusted agents from the Vaultfire registry

[![npm version](https://img.shields.io/npm/v/@vaultfire/a2a)](https://www.npmjs.com/package/@vaultfire/a2a)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

---

## Quick Start

```bash
npm install @vaultfire/a2a
```

```typescript
import { enrichAgentCard } from '@vaultfire/a2a';

const enriched = await enrichAgentCard({
  agentCard: myA2ACard,
  chain: 'base',
  agentAddress: '0x...',
});
// enriched['x-vaultfire'].streetCred.score => 72
```

---

## What is A2A?

The **Agent-to-Agent (A2A) protocol** is an open standard by Google that defines how AI agents discover, communicate with, and delegate tasks to each other. Each agent publishes a JSON **Agent Card** at `/.well-known/agent.json` describing its capabilities, skills, and security configuration.

`@vaultfire/a2a` extends this standard with **on-chain trust signals** from the Vaultfire Protocol — so agents can make informed decisions about who to trust before delegating sensitive tasks.

---

## API Reference

### `enrichAgentCard(options)`

Fetch on-chain trust data for an agent and attach it to their A2A Agent Card as an `x-vaultfire` extension field.

```typescript
import { enrichAgentCard } from '@vaultfire/a2a';
import type { AgentCard } from '@vaultfire/a2a';

const myCard: AgentCard = {
  name: 'DataAnalysis Agent',
  url: 'https://my-agent.example.com',
  provider: { organization: 'Acme AI', url: 'https://acme.ai' },
  version: '1.0.0',
  capabilities: { streaming: true },
  skills: [{ id: 'csv-analysis', name: 'CSV Analysis' }],
};

const enriched = await enrichAgentCard({
  agentCard: myCard,
  chain: 'base',            // 'base' | 'avalanche' | 'arbitrum' | 'polygon'
  agentAddress: '0x...',   // your on-chain agent address
});

console.log(enriched['x-vaultfire'].streetCred.score); // e.g. 72
console.log(enriched['x-vaultfire'].streetCred.tier);  // e.g. "Platinum"
```

**Returns:** `EnrichedAgentCard` — the original card plus the `x-vaultfire` extension.

---

### `verifyAgentCard(enrichedCard)`

Re-fetch live on-chain data and verify the trust claims in an enriched Agent Card.

```typescript
import { verifyAgentCard } from '@vaultfire/a2a';

const verification = await verifyAgentCard(enrichedCard);

if (!verification.trusted) {
  throw new Error(`Refusing to delegate: ${verification.reason}`);
}

console.log(verification.streetCred.score);  // live score from chain
console.log(verification.reason);            // human-readable explanation
```

**Returns:** `VerificationResult`
```typescript
interface VerificationResult {
  trusted: boolean;
  streetCred: { score: number; tier: string; maxPossible: 95 };
  bonds: { total: number; active: number };
  reputation: { averageRating: number; totalFeedbacks: number };
  identity: { registered: boolean; active: boolean; agentType: string };
  reason: string;
  chain: SupportedChain;
  address: string;
  verifiedAt: string; // ISO timestamp
}
```

**Trust criteria:**
- Agent must be active on-chain
- Claimed Street Cred score must not drift more than 15 points from live data

---

### `vaultfireAgentCardMiddleware(options)`

Express middleware that serves an enriched Agent Card with a built-in cache.

```typescript
import express from 'express';
import { vaultfireAgentCardMiddleware } from '@vaultfire/a2a';

const app = express();

app.get('/.well-known/agent.json', vaultfireAgentCardMiddleware({
  agentCard: myCard,
  chain: 'base',
  agentAddress: '0x...',
  cacheTtl: 5 * 60 * 1000, // 5 minutes (default)
}));

app.listen(3000);
```

**Options:**
| Option | Type | Default | Description |
|---|---|---|---|
| `agentCard` | `AgentCard` | required | Base A2A Agent Card |
| `chain` | `SupportedChain` | required | Blockchain network |
| `agentAddress` | `string` | required | On-chain agent address |
| `cacheTtl` | `number` | `300000` | Cache TTL in ms (0 = disabled) |
| `onError` | `(err) => card \| null` | serve plain card | Error handler |

If enrichment fails, the middleware falls back to serving the plain (un-enriched) Agent Card by default.

---

### `discoverTrustedAgents(options)`

Discover trusted agents from the Vaultfire registry, filtered by Street Cred score and bond count.

```typescript
import { discoverTrustedAgents } from '@vaultfire/a2a';

const agents = await discoverTrustedAgents({
  chain: 'base',
  minStreetCred: 40,    // Silver tier minimum
  requireActive: true,
  limit: 20,
});

for (const agent of agents) {
  console.log(`${agent.address}: ${agent.streetCred.score} (${agent.streetCred.tier})`);
}
```

**Options:**
| Option | Type | Default | Description |
|---|---|---|---|
| `chain` | `SupportedChain` | required | Blockchain network |
| `minStreetCred` | `number` | `0` | Minimum Street Cred score |
| `minBonds` | `number` | `0` | Minimum active bonds required |
| `requireActive` | `boolean` | `true` | Only return active agents |
| `agentType` | `string` | — | Filter by agent type |
| `limit` | `number` | `50` | Max agents to return |

Results are sorted by Street Cred score descending.

---

## Agent Card Extension Schema

The `x-vaultfire` field added to Agent Cards:

```typescript
interface VaultfireAgentCardExtension {
  "x-vaultfire": {
    chain: "base" | "avalanche" | "arbitrum" | "polygon";
    address: string;                    // On-chain agent address
    streetCred: {
      score: number;                    // 0–95 composite trust score
      tier: string;                     // "Newcomer" | "Bronze" | "Silver" | "Gold" | "Platinum" | "Diamond"
      maxPossible: 95;                  // Always 95
    };
    bonds: {
      total: number;                    // Total partnership bonds ever created
      active: number;                   // Currently active bonds
    };
    reputation: {
      averageRating: number;            // 0.0–5.0 average feedback rating
      totalFeedbacks: number;           // Total number of feedback submissions
    };
    identity: {
      registered: boolean;              // Whether the agent is in the registry
      active: boolean;                  // Whether the agent is currently active
      agentType: string;                // e.g. "autonomous", "assistant", "specialized"
    };
    verifiedAt: string;                 // ISO 8601 timestamp of the last on-chain read
  }
}
```

---

## Street Cred Scoring

Street Cred is a composite trust score (0–95) calculated from four on-chain signals:

| Signal | Max Points | Description |
|---|---|---|
| Identity | 25 | Active registration (+20), age bonus for >30 days (+5) |
| Partnership Bonds | 30 | 5 points per active bond, capped at 6 bonds |
| Reputation | 30 | Up to 15 pts from average rating + 15 pts from feedback volume |
| Bridge Recognition | 10 | Cross-chain recognition by the Vaultfire Bridge |

**Tier Thresholds:**
| Tier | Score Range | Meaning |
|---|---|---|
| Newcomer | 0–19 | Just registered, no track record |
| Bronze | 20–34 | Early trust signals |
| Silver | 35–49 | Moderate trust; minimum for delegation in most apps |
| Gold | 50–64 | Established agent with bonds and reputation |
| Platinum | 65–79 | Highly trusted; multi-bond, strong reputation |
| Diamond | 80–95 | Maximum trust; fully bonded, cross-chain recognized |

---

## Deployed Contracts

### Base (Chain ID: 8453)
| Contract | Address |
|---|---|
| Identity | [0x35978DB675576598F0781dA2133E94cdCf4858bC](https://basescan.org/address/0x35978DB675576598F0781dA2133E94cdCf4858bC) |
| Partnership | [0x01C479F0c039fEC40c0Cf1c5C921bab457d57441](https://basescan.org/address/0x01C479F0c039fEC40c0Cf1c5C921bab457d57441) |
| Reputation | [0xdB54B8925664816187646174bdBb6Ac658A55a5F](https://basescan.org/address/0xdB54B8925664816187646174bdBb6Ac658A55a5F) |
| Bridge | [0x94F54c849692Cc64C35468D0A87D2Ab9D7Cb6Fb2](https://basescan.org/address/0x94F54c849692Cc64C35468D0A87D2Ab9D7Cb6Fb2) |

### Avalanche (Chain ID: 43114)
| Contract | Address |
|---|---|
| Identity | [0x57741F4116925341d8f7Eb3F381d98e07C73B4a3](https://snowtrace.io/address/0x57741F4116925341d8f7Eb3F381d98e07C73B4a3) |
| Partnership | [0xDC8447c66fE9D9c7D54607A98346A15324b7985D](https://snowtrace.io/address/0xDC8447c66fE9D9c7D54607A98346A15324b7985D) |
| Reputation | [0x11C267C8A75B13A4D95357CEF6027c42F8e7bA24](https://snowtrace.io/address/0x11C267C8A75B13A4D95357CEF6027c42F8e7bA24) |
| Bridge | [0x0dF0523aF5aF2Aef180dB052b669Bea97fee3d31](https://snowtrace.io/address/0x0dF0523aF5aF2Aef180dB052b669Bea97fee3d31) |

### Arbitrum (Chain ID: 42161)
| Contract | Address |
|---|---|
| Identity | [0x6298c62FDA57276DC60de9E716fbBAc23d06D5F1](https://arbiscan.io/address/0x6298c62FDA57276DC60de9E716fbBAc23d06D5F1) |
| Partnership | [0xdB54B8925664816187646174bdBb6Ac658A55a5F](https://arbiscan.io/address/0xdB54B8925664816187646174bdBb6Ac658A55a5F) |
| Reputation | [0x8aceF0Bc7e07B2dE35E9069663953f41B5422218](https://arbiscan.io/address/0x8aceF0Bc7e07B2dE35E9069663953f41B5422218) |
| Bridge | [0xe2aDfe84703dd6B5e421c306861Af18F962fDA91](https://arbiscan.io/address/0xe2aDfe84703dd6B5e421c306861Af18F962fDA91) |

### Polygon (Chain ID: 137)
| Contract | Address |
|---|---|
| Identity | [0x6298c62FDA57276DC60de9E716fbBAc23d06D5F1](https://polygonscan.com/address/0x6298c62FDA57276DC60de9E716fbBAc23d06D5F1) |
| Partnership | [0x83dd216449B3F0574E39043ECFE275946fa492e9](https://polygonscan.com/address/0x83dd216449B3F0574E39043ECFE275946fa492e9) |
| Reputation | [0x8aceF0Bc7e07B2dE35E9069663953f41B5422218](https://polygonscan.com/address/0x8aceF0Bc7e07B2dE35E9069663953f41B5422218) |
| Bridge | [0xe2aDfe84703dd6B5e421c306861Af18F962fDA91](https://polygonscan.com/address/0xe2aDfe84703dd6B5e421c306861Af18F962fDA91) |

---

## Vaultfire Ecosystem

| Package | Description |
|---|---|
| [`@vaultfire/agent-sdk`](https://github.com/Ghostkey316/vaultfire-sdk) | Core SDK — register agents, create bonds, query reputation |
| [`@vaultfire/langchain`](https://github.com/Ghostkey316/vaultfire-langchain) | LangChain / LangGraph integration |
| [`@vaultfire/a2a`](https://github.com/Ghostkey316/vaultfire-a2a) | **This package** — Agent-to-Agent (A2A) protocol bridge |
| [`@vaultfire/enterprise`](https://github.com/Ghostkey316/vaultfire-enterprise) | Enterprise IAM bridge (Okta, Azure AD, OIDC) |
| [`@vaultfire/mcp-server`](https://github.com/Ghostkey316/vaultfire-mcp-server) | MCP server for Claude, Copilot, Cursor |
| [`@vaultfire/openai-agents`](https://github.com/Ghostkey316/vaultfire-openai-agents) | OpenAI Agents SDK integration |
| [`@vaultfire/vercel-ai`](https://github.com/Ghostkey316/vaultfire-vercel-ai) | Vercel AI SDK middleware and tools |
| [`@vaultfire/xmtp`](https://github.com/Ghostkey316/vaultfire-xmtp) | XMTP messaging with trust verification |
| [`@vaultfire/x402`](https://github.com/Ghostkey316/vaultfire-x402) | X402 payment protocol with trust gates |
| [`@vaultfire/vns`](https://github.com/Ghostkey316/vaultfire-vns) | Vaultfire Name Service — human-readable agent IDs |
| [`vaultfire-crewai`](https://github.com/Ghostkey316/vaultfire-crewai) | CrewAI integration (Python) |
| [`vaultfire-agents`](https://github.com/Ghostkey316/vaultfire-agents) | 3 reference agents with live on-chain trust |
| [`vaultfire-a2a-trust-extension`](https://github.com/Ghostkey316/vaultfire-a2a-trust-extension) | A2A Trust Extension spec — on-chain trust for Agent Cards |
| [`vaultfire-showcase`](https://github.com/Ghostkey316/vaultfire-showcase) | Why Vaultfire Bonds beat trust scores — live proof |
| [`vaultfire-whitepaper`](https://github.com/Ghostkey316/vaultfire-whitepaper) | Trust Framework whitepaper — economic accountability for AI |
| [`vaultfire-docs`](https://github.com/Ghostkey316/vaultfire-docs) | Developer portal — quickstart, playground, framework picker |
---

## Requirements

- Node.js >= 18
- An EVM-compatible address registered with the Vaultfire Identity contract

---

## License

MIT © 2026 Ghostkey316

See [LICENSE](./LICENSE) for details.
