@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 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

Quick Start

npm install @vaultfire/a2a

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.

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.

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

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.

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.

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:

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 | | Partnership | 0x01C479F0c039fEC40c0Cf1c5C921bab457d57441 | | Reputation | 0xdB54B8925664816187646174bdBb6Ac658A55a5F | | Bridge | 0x94F54c849692Cc64C35468D0A87D2Ab9D7Cb6Fb2 |

Avalanche (Chain ID: 43114)

| Contract | Address | |---|---| | Identity | 0x57741F4116925341d8f7Eb3F381d98e07C73B4a3 | | Partnership | 0xDC8447c66fE9D9c7D54607A98346A15324b7985D | | Reputation | 0x11C267C8A75B13A4D95357CEF6027c42F8e7bA24 | | Bridge | 0x0dF0523aF5aF2Aef180dB052b669Bea97fee3d31 |

Arbitrum (Chain ID: 42161)

| Contract | Address | |---|---| | Identity | 0x6298c62FDA57276DC60de9E716fbBAc23d06D5F1 | | Partnership | 0xdB54B8925664816187646174bdBb6Ac658A55a5F | | Reputation | 0x8aceF0Bc7e07B2dE35E9069663953f41B5422218 | | Bridge | 0xe2aDfe84703dd6B5e421c306861Af18F962fDA91 |

Polygon (Chain ID: 137)

| Contract | Address | |---|---| | Identity | 0x6298c62FDA57276DC60de9E716fbBAc23d06D5F1 | | Partnership | 0x83dd216449B3F0574E39043ECFE275946fa492e9 | | Reputation | 0x8aceF0Bc7e07B2dE35E9069663953f41B5422218 | | Bridge | 0xe2aDfe84703dd6B5e421c306861Af18F962fDA91 |

Vaultfire Ecosystem

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