<div align="center">

> **⚠️ 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. Read-only tools are safe for any agent. Write tools interact with live contracts and transactions are irreversible. Use at your own risk. See [LICENSE](./LICENSE) for warranty disclaimers.


# @vaultfire/langchain

**LangChain/LangGraph integration for [Vaultfire Protocol](https://github.com/Ghostkey316/ghostkey-316-vaultfire-init)**

On-chain identity, trust verification, and partnership bonds for AI agents.
Deployed on **Base · Avalanche · Arbitrum · Polygon**.

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

</div>

---

## Why Vaultfire?

Every AI agent needs three things before a partner will trust it:

1. **Identity** — Who is this agent? (ERC-8004 on-chain identity registry)
2. **Reputation** — Has it performed well? (Verified feedback with Street Cred scoring)
3. **Skin in the game** — What happens if it fails? (AI Partnership Bonds with economic stakes)

Vaultfire Protocol makes all three verifiable on-chain. This package gives your LangChain agent direct access.

## Quick Start

### Install

```bash
npm install @vaultfire/langchain
```

### 3-Line Setup

```typescript
import { createVaultfireTools } from '@vaultfire/langchain';

const tools = createVaultfireTools({ chain: 'base' });
// Pass `tools` to your LangChain agent — done.
```

### With a LangGraph Agent

```typescript
import { createVaultfireTools } from '@vaultfire/langchain';
import { ChatOpenAI } from '@langchain/openai';
import { createReactAgent } from '@langchain/langgraph/prebuilt';

const tools = createVaultfireTools({ chain: 'base' });
const model = new ChatOpenAI({ model: 'gpt-4o' });

const agent = createReactAgent({ llm: model, tools });

// Agent can now verify trust, check Street Cred, read bonds, etc.
const result = await agent.invoke({
  messages: [{ role: 'user', content: 'Is agent 0xA054...b84F trustworthy?' }],
});
```

## Available Tools

### Read-Only (7 tools — safe for any agent)

| Tool | Description |
|------|-------------|
| `vaultfire_verify_agent` | Full trust verification — identity, bonds, Street Cred, reputation, bridge status |
| `vaultfire_get_street_cred` | Get Street Cred score (0–95) and tier: Unranked, Bronze, Silver, Gold, Platinum |
| `vaultfire_get_agent` | Get on-chain identity data (URI, type, registration date, active status) |
| `vaultfire_get_bonds` | Get all partnership bonds for an address (stake, type, status) |
| `vaultfire_get_reputation` | Get reputation data (average rating, feedback count, verified %) |
| `vaultfire_discover_agents` | Find agents by capability tags in the on-chain registry |
| `vaultfire_protocol_stats` | Protocol stats: total agents, bonds, bonded value, bridge sync count |

### Write Tools (2 additional — requires signer)

| Tool | Description |
|------|-------------|
| `vaultfire_register_agent` | Register a new AI agent on-chain via ERC-8004 Identity Registry |
| `vaultfire_create_bond` | Create a partnership bond with economic stake |

## Usage Examples

### Read-Only — Verify Trust Before Interacting

```typescript
import { createVaultfireReadTools } from '@vaultfire/langchain';

// Safe to give any agent — no signer, no write operations
const tools = createVaultfireReadTools({ chain: 'base' });

// Use with any LangChain-compatible agent
```

### Write Operations — Register Agent & Create Bond

```typescript
import { createVaultfireTools } from '@vaultfire/langchain';

const tools = createVaultfireTools({
  chain: 'base',
  privateKey: process.env.AGENT_PRIVATE_KEY,  // NEVER hardcode keys
});

// Agent now has 9 tools — including register and create_bond
```

### Multi-Chain — Check Trust Across All 4 Chains

```typescript
import { VaultfireClient } from '@vaultfire/langchain';

const trust = await VaultfireClient.verifyTrustMultiChain(
  '0xA054f831B562e729F8D268291EBde1B2EDcFb84F'
);

// trust.base, trust.avalanche, trust.arbitrum, trust.polygon
for (const [chain, result] of Object.entries(trust)) {
  console.log(`${chain}: Score ${result.streetCred.score}/95 (${result.streetCred.tier})`);
}
```

### Direct Client — Without LangChain

```typescript
import { VaultfireClient } from '@vaultfire/langchain';

const client = new VaultfireClient({ chain: 'base' });

// Check if an agent is trustworthy
const cred = await client.getStreetCred('0x...');
console.log(`Street Cred: ${cred.score}/95 (${cred.tier})`);

// Full trust verification
const trust = await client.verifyTrust('0x...');
if (trust.trusted) {
  console.log('Agent is verified and trusted');
}
```

## Street Cred Scoring

Street Cred is Vaultfire's composite trust score (0–95 points):

| Component | Points | Description |
|-----------|--------|-------------|
| Identity Registered | 30 | Agent has ERC-8004 on-chain identity |
| Has Bond | 25 | At least one partnership bond exists |
| Bond Active | 15 | Bond is currently active |
| Bond Tier | 5–20 | Based on stake amount (Bronze → Platinum) |
| Multiple Bonds | 5 | More than one bond on record |

### Tiers

| Tier | Score | Meaning |
|------|-------|---------|
| Unranked | 0–19 | No on-chain presence |
| Bronze | 20–39 | Basic identity registered |
| Silver | 40–59 | Identity + bond established |
| Gold | 60–79 | Active bonds with meaningful stake |
| Platinum | 80–95 | Full trust profile — identity, active bonds, high stake |

### Bond Tier Thresholds

| Stake Amount | Tier Points |
|-------------|-------------|
| ≥ 0.01 ETH | 5 (Bronze) |
| ≥ 0.05 ETH | 10 (Silver) |
| ≥ 0.1 ETH | 15 (Gold) |
| ≥ 0.5 ETH | 20 (Platinum) |

## Supported Chains

| Chain | ID | Hub | Explorer |
|-------|----|-----|----------|
| **Base** | 8453 | ✅ Primary | [basescan.org](https://basescan.org) |
| **Avalanche** | 43114 | Spoke | [snowtrace.io](https://snowtrace.io) |
| **Arbitrum** | 42161 | Spoke | [arbiscan.io](https://arbiscan.io) |
| **Polygon** | 137 | Spoke | [polygonscan.com](https://polygonscan.com) |

## Deployed Contracts

### Base (Chain 8453) — Hub Chain

| Contract | Address |
|----------|---------|
| Identity (ERC-8004) | [`0x35978DB675576598F0781dA2133E94cdCf4858bC`](https://basescan.org/address/0x35978DB675576598F0781dA2133E94cdCf4858bC) |
| Partnership Bonds | [`0x01C479F0c039fEC40c0Cf1c5C921bab457d57441`](https://basescan.org/address/0x01C479F0c039fEC40c0Cf1c5C921bab457d57441) |
| Accountability Bonds | [`0x6750D28865434344e04e1D0a6044394b726C3dfE`](https://basescan.org/address/0x6750D28865434344e04e1D0a6044394b726C3dfE) |
| Reputation | [`0xdB54B8925664816187646174bdBb6Ac658A55a5F`](https://basescan.org/address/0xdB54B8925664816187646174bdBb6Ac658A55a5F) |
| Bridge | [`0x94F54c849692Cc64C35468D0A87D2Ab9D7Cb6Fb2`](https://basescan.org/address/0x94F54c849692Cc64C35468D0A87D2Ab9D7Cb6Fb2) |
| VNS | [`0x1437c4081233A4f0B6907dDf5374Ed610cBD6B25`](https://basescan.org/address/0x1437c4081233A4f0B6907dDf5374Ed610cBD6B25) |

### Avalanche (Chain 43114)

| Contract | Address |
|----------|---------|
| Identity (ERC-8004) | [`0x57741F4116925341d8f7Eb3F381d98e07C73B4a3`](https://snowtrace.io/address/0x57741F4116925341d8f7Eb3F381d98e07C73B4a3) |
| Partnership Bonds | [`0xDC8447c66fE9D9c7D54607A98346A15324b7985D`](https://snowtrace.io/address/0xDC8447c66fE9D9c7D54607A98346A15324b7985D) |
| Accountability Bonds | [`0x376831fB2457E34559891c32bEb61c442053C066`](https://snowtrace.io/address/0x376831fB2457E34559891c32bEb61c442053C066) |
| Reputation | [`0x11C267C8A75B13A4D95357CEF6027c42F8e7bA24`](https://snowtrace.io/address/0x11C267C8A75B13A4D95357CEF6027c42F8e7bA24) |
| Bridge | [`0x0dF0523aF5aF2Aef180dB052b669Bea97fee3d31`](https://snowtrace.io/address/0x0dF0523aF5aF2Aef180dB052b669Bea97fee3d31) |

### Arbitrum (Chain 42161)

| Contract | Address |
|----------|---------|
| Identity (ERC-8004) | [`0x6298c62FDA57276DC60de9E716fbBAc23d06D5F1`](https://arbiscan.io/address/0x6298c62FDA57276DC60de9E716fbBAc23d06D5F1) |
| Partnership Bonds | [`0xdB54B8925664816187646174bdBb6Ac658A55a5F`](https://arbiscan.io/address/0xdB54B8925664816187646174bdBb6Ac658A55a5F) |
| Accountability Bonds | [`0xef3A944f4d7bb376699C83A29d7Cb42C90D9B6F0`](https://arbiscan.io/address/0xef3A944f4d7bb376699C83A29d7Cb42C90D9B6F0) |
| Reputation | [`0x8aceF0Bc7e07B2dE35E9069663953f41B5422218`](https://arbiscan.io/address/0x8aceF0Bc7e07B2dE35E9069663953f41B5422218) |
| Bridge | [`0xe2aDfe84703dd6B5e421c306861Af18F962fDA91`](https://arbiscan.io/address/0xe2aDfe84703dd6B5e421c306861Af18F962fDA91) |
| VNS | [`0x247F31bB2b5a0d28E68bf24865AA242965FF99cd`](https://arbiscan.io/address/0x247F31bB2b5a0d28E68bf24865AA242965FF99cd) |

### Polygon (Chain 137)

| Contract | Address |
|----------|---------|
| Identity (ERC-8004) | [`0x6298c62FDA57276DC60de9E716fbBAc23d06D5F1`](https://polygonscan.com/address/0x6298c62FDA57276DC60de9E716fbBAc23d06D5F1) |
| Partnership Bonds | [`0x83dd216449B3F0574E39043ECFE275946fa492e9`](https://polygonscan.com/address/0x83dd216449B3F0574E39043ECFE275946fa492e9) |
| Accountability Bonds | [`0xdB54B8925664816187646174bdBb6Ac658A55a5F`](https://polygonscan.com/address/0xdB54B8925664816187646174bdBb6Ac658A55a5F) |
| Reputation | [`0x8aceF0Bc7e07B2dE35E9069663953f41B5422218`](https://polygonscan.com/address/0x8aceF0Bc7e07B2dE35E9069663953f41B5422218) |
| Bridge | [`0xe2aDfe84703dd6B5e421c306861Af18F962fDA91`](https://polygonscan.com/address/0xe2aDfe84703dd6B5e421c306861Af18F962fDA91) |
| VNS | [`0x247F31bB2b5a0d28E68bf24865AA242965FF99cd`](https://polygonscan.com/address/0x247F31bB2b5a0d28E68bf24865AA242965FF99cd) |

## API Reference

### `createVaultfireTools(config?)`

Creates all Vaultfire tools for a LangChain agent. If a signer or private key is provided, includes write tools (register, bond).

```typescript
createVaultfireTools({
  chain?: 'base' | 'avalanche' | 'arbitrum' | 'polygon',  // default: 'base'
  rpcUrl?: string,        // custom RPC (overrides default)
  signer?: ethers.Signer, // for write operations
  privateKey?: string,    // alternative to signer — use env vars, NEVER hardcode
}): VaultfireTool[]
```

### `createVaultfireReadTools(config?)`

Creates read-only Vaultfire tools. Safe to give to any agent — cannot modify on-chain state.

```typescript
createVaultfireReadTools({
  chain?: 'base' | 'avalanche' | 'arbitrum' | 'polygon',
  rpcUrl?: string,
}): VaultfireTool[]
```

### `VaultfireClient`

Direct access to all protocol operations without the LangChain tool wrapper.

```typescript
const client = new VaultfireClient({ chain: 'base' });

// Read operations (no signer needed)
await client.getAgent(address)
await client.isAgentActive(address)
await client.getTotalAgents()
await client.getStreetCred(address)
await client.getReputation(address)
await client.verifyTrust(address, minScore?)
await client.getBond(bondId)
await client.getBondsByParticipant(address)
await client.discoverAgents(capabilities)

// Write operations (requires signer)
await client.registerAgent(uri, type, capabilities)
await client.createBond(agentAddress, partnershipType, stakeEther?)

// Multi-chain (static)
await VaultfireClient.verifyTrustMultiChain(address, minScore?)
```

### Chain Utilities

```typescript
import { CHAIN_CONFIG, getChainConfig, getSupportedChains } from '@vaultfire/langchain';

getSupportedChains();           // ['base', 'avalanche', 'arbitrum', 'polygon']
getChainConfig('base');         // { name, chainId, rpcUrl, explorer, contracts }
getChainConfig(42161);          // look up by chain ID
```

## 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) | **This package** — LangChain / LangGraph integration |
| [`@vaultfire/a2a`](https://github.com/Ghostkey316/vaultfire-a2a) | 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 |
## Security

- **Never hardcode private keys.** Always use environment variables.
- Read-only tools are safe for any agent — they cannot modify on-chain state.
- Write tools require a signer and should only be given to trusted agent pipelines.
- All contract addresses are verified on mainnet explorers.

## Requirements

- Node.js ≥ 18
- `@langchain/core` ≥ 0.3.0 (peer dependency, optional)

## License

MIT — [Ghostkey316](https://github.com/Ghostkey316)
