# @vaultfire/agent-sdk


> **⚠️ 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.

> Official TypeScript SDK for the Vaultfire Protocol — the trust and accountability layer for AI agents.

![npm version](https://img.shields.io/npm/v/@vaultfire/agent-sdk.svg)
![License](https://img.shields.io/badge/License-MIT-green.svg)
![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)
![Base](https://img.shields.io/badge/Chain-Base-blue.svg)
![Avalanche](https://img.shields.io/badge/Chain-Avalanche-red.svg)

---

## What is This?

The TypeScript SDK for integrating Vaultfire trust verification, bonds, insurance, and task escrow into any application. Read live on-chain state, build unsigned transactions for any signer (Safe, AgentKit, smart accounts, MPC), and pull a combined trust profile in a single HTTP call.

Built on ERC-8004 identity, CRYSTALS-Dilithium quantum-resistant attestations, and the Vaultfire belief verification system.

### Chain coverage

| Module | Base (8453) | Avalanche (43114) | Arbitrum (42161) | Polygon (137) |
| --- | --- | --- | --- | --- |
| Identity (ERC-8004) | ✓ | ✓ | ✓ | ✓ |
| Belief attestations (Dilithium) | ✓ | ✓ | ✓ | ✓ |
| **Bonds + insurance pool** | ✓ | (read-only) | (read-only) | (read-only) |
| **Task escrow (USDC)** | ✓ | (read-only) | (read-only) | (read-only) |
| Combined trust profile API | ✓ | (via API) | (via API) | (via API) |

The `bonds`, `tasks`, and tx-builder helpers in this SDK currently target Base mainnet by default. The contracts are deployed on all four chains (134 total — see [CONTRACTS.md](https://node.gitlawb.com/z6MkryiNsYdFEMHv95wxzSQ1vtFXPyVQQrxXdPw3tE5HpfxV/vaultfire/blob/main/CONTRACTS.md)), and signer-bound writes will be wired across Avalanche/Arbitrum/Polygon in a follow-up release.

**Two modes:**
- **VaultfireSDK** — Full access, raw `beliefHash` input, all methods exposed
- **VaultfireSafeSDK** — Privacy-preserving wrapper, hashes statements locally, analytics off by default

---

## Installation

```bash
npm install @vaultfire/agent-sdk ethers
```

---

## Quick Start

### Recommended: Safe Defaults (Privacy-Preserving)

```typescript
import { VaultfireSafeSDK, ModuleType } from '@vaultfire/agent-sdk';
import { Wallet } from 'ethers';

const vaultfire = new VaultfireSafeSDK({
  chain: 'base',
  privacySalt: process.env.VAULTFIRE_PRIVACY_SALT,
});

vaultfire.connect(new Wallet(process.env.AGENT_PRIVATE_KEY));

const result = await vaultfire.verifyStatement({
  statement: 'I contribute to open source',
  moduleId: ModuleType.GITHUB,
});

console.log('Verified:', result.verified);
console.log('TX Hash:', result.txHash);
```

### Raw SDK (Advanced)

```typescript
import { VaultfireSDK, ModuleType } from '@vaultfire/agent-sdk';
import { Wallet } from 'ethers';

const vaultfire = new VaultfireSDK({ chain: 'base' });
vaultfire.connect(new Wallet(process.env.AGENT_PRIVATE_KEY));

const result = await vaultfire.verifyBelief({
  beliefHash: vaultfire.hashBelief('I contribute to open source'),
  moduleId: ModuleType.GITHUB,
});

console.log('Verified:', result.verified);
console.log('TX Hash:', result.txHash);
```

### Avalanche

```typescript
const vaultfire = new VaultfireSDK({ chain: 'avalanche' });
```

That's it. The SDK handles RPC endpoints and contract addresses automatically for each chain.

---

## Features

- **Multi-chain** — Base (8453), Avalanche (43114), Arbitrum (42161), and Polygon (137) out of the box
- **Post-quantum attestations** — CRYSTALS-Dilithium via DilithiumAttestor contracts
- **Privacy-preserving mode** — VaultfireSafeSDK hashes statements locally with a salt, never sends raw text on-chain
- **Type-safe** — Full TypeScript types and declaration files
- **Minimal dependencies** — Just `ethers` v6
- **Read and write** — Query attestations (read-only) or submit new ones (with a connected signer)

---

## Supported Chains

| Chain | Chain ID | Status | DilithiumAttestor | BeliefVerifier |
|-------|----------|--------|-------------------|----------------|
| Base | 8453 | **Live** | [`0xBBC0...0A4`](https://basescan.org/address/0xBBC0EFdEE23854e7cb7C4c0f56fF7670BB0530A4) | [`0xa5CE...272`](https://basescan.org/address/0xa5CEC47B48999EB398707838E3A18dd20A1ae272) |
| Avalanche | 43114 | **Live** | [`0x2115...cF1f`](https://snowtrace.io/address/0x211554bd46e3D4e064b51a31F61927ae9c7bCF1f) | [`0xb3d8...D2F`](https://snowtrace.io/address/0xb3d8063e67bdA1a869721D0F6c346f1Af0469D2F) |
| Base Sepolia | 84532 | Testnet | — | — |

---

## API Reference

### VaultfireSDK

```typescript
import { VaultfireSDK } from '@vaultfire/agent-sdk';

const sdk = new VaultfireSDK({
  chain: 'base',           // 'base' | 'avalanche' | 'base-sepolia' | 'base-goerli'
  rpcUrl: '...',           // Optional custom RPC
  contracts: { ... },      // Optional custom contract addresses
  apiKey: '...',           // Optional API key
  analytics: true,         // Optional (default: true)
});
```

#### Methods

| Method | Description |
|--------|-------------|
| `connect(signer)` | Connect an ethers Signer for write operations |
| `verifyBelief(attestation)` | Submit a belief attestation on-chain |
| `isSovereign(beliefHash)` | Check if a belief has been attested |
| `getAttestations(address, limit?)` | Get attestations for an address |
| `getModules()` | List available verification modules |
| `hashBelief(statement)` | Hash a statement with keccak256 |
| `estimateGas(attestation)` | Estimate gas for a verification |
| `getChainConfig()` | Get current chain configuration |

### VaultfireSafeSDK

Privacy-preserving wrapper. Hashes statements locally before sending on-chain.

```typescript
import { VaultfireSafeSDK } from '@vaultfire/agent-sdk';

const sdk = new VaultfireSafeSDK({
  chain: 'base',
  privacySalt: process.env.VAULTFIRE_PRIVACY_SALT,  // Recommended
});
```

| Method | Description |
|--------|-------------|
| `connect(signer)` | Connect an ethers Signer |
| `verifyStatement(request)` | Hash locally + verify on-chain |
| `hashStatement(statement)` | Hash with salt (never sends raw text) |
| `isSovereign(beliefHash)` | Check attestation status |
| `getModules()` | List modules |
| `getChainConfig()` | Get chain config |
| `unsafeRaw()` | Escape hatch to underlying VaultfireSDK |

See [SAFE_DEFAULTS.md](./SAFE_DEFAULTS.md) for the full privacy model.

### ModuleType Enum

```typescript
enum ModuleType {
  GENERIC = 0,      // Generic belief attestation
  GITHUB = 1,       // GitHub contributions
  NS3 = 2,          // NS3 namespace ownership
  BASE = 3,         // Base transactions
  CREDENTIAL = 4,   // Professional credentials
  REPUTATION = 5,   // On-chain reputation
  IDENTITY = 6,     // Identity verification
  GOVERNANCE = 7,   // DAO governance proofs
}
```

---

## Examples

### DeFi: Prove Trading History

```typescript
const result = await sdk.verifyBelief({
  beliefHash: sdk.hashBelief('Profitable trader Q1 2026'),
  moduleId: ModuleType.REPUTATION,
  metadata: { pnl: '+15%', trades: 47 }, // stays off-chain
});
```

### DAO: Reputation-Weighted Voting

```typescript
const attestations = await sdk.getAttestations(memberAddress);
const reputationScore = attestations.filter(a => a.zkVerified).length;

if (reputationScore >= 10) {
  // Allow proposal submission
}
```

See the `examples/` directory for complete runnable examples.

---

## Full API Documentation

See [API_REFERENCE.md](./API_REFERENCE.md) for the complete API reference including REST API endpoints, error handling, and rate limits.

---

## Architecture

```
┌────────────────────────────────────────────────────┐
│                  Your Application                  │
├────────────────────────────────────────────────────┤
│                                                    │
│   VaultfireSafeSDK (privacy-preserving)            │
│       └── VaultfireSDK (core)                      │
│               └── ethers.js (provider + signer)    │
│                                                    │
├────────────────────────────────────────────────────┤
│                                                    │
│   Base (8453)            Avalanche (43114)          │
│   ├── DilithiumAttestor  ├── DilithiumAttestor     │
│   └── BeliefVerifier     └── BeliefVerifier        │
│                                                    │
└────────────────────────────────────────────────────┘
```

---

## Ecosystem

The SDK is one piece of the Vaultfire stack. Combine with these packages for the full agent operating system:

| Package | Description |
|---|---|
| [`@vaultfire/langchain`](https://github.com/Ghostkey316/vaultfire-langchain) | LangChain/LangGraph integration — 9 tools, 3-line setup, 4 chains |
| [`@vaultfire/x402`](https://github.com/Ghostkey316/vaultfire-x402) | x402 payment protocol — HTTP 402 USDC micropayments on Base & Avalanche |
| [`@vaultfire/xmtp`](https://github.com/Ghostkey316/vaultfire-xmtp) | Trust-gated encrypted agent messaging via XMTP |
| [`@vaultfire/vns`](https://github.com/Ghostkey316/vaultfire-vns) | On-chain `.vns` name service for AI agents |
| [`vaultfire-contracts`](https://github.com/Ghostkey316/vaultfire-contracts) | Canonical contract registry — all deployed ABIs and addresses |
| [`@vaultfire/arbitrum`](https://github.com/Ghostkey316/vaultfire-arbitrum) | Arbitrum One — 16 contracts deployed |
| [`@vaultfire/polygon`](https://github.com/Ghostkey316/vaultfire-polygon) | Polygon PoS — 16 contracts deployed |
| [`@vaultfire/a2a`](https://github.com/Ghostkey316/vaultfire-a2a) | A2A Agent Card enrichment with on-chain Vaultfire trust |
| [`vaultfire-langgraph-demo`](https://github.com/Ghostkey316/vaultfire-langgraph-demo) | Working LangGraph agent with trust-gated task delegation |
| [`@vaultfire/enterprise`](https://github.com/Ghostkey316/vaultfire-enterprise) | Enterprise IAM bridge — Okta/Azure AD to on-chain trust |
| [`vaultfire-agents`](https://github.com/Ghostkey316/vaultfire-agents) | 3 reference agents with live on-chain trust verification |
| [`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 |

---

## Explore

- **Hub:** [theloopbreaker.com](https://theloopbreaker.com)
- **Main Protocol Repo:** [ghostkey-316-vaultfire-init](https://github.com/Ghostkey316/ghostkey-316-vaultfire-init)
- **Vaultfire on Base:** [vaultfire-base](https://github.com/Ghostkey316/vaultfire-base)
- **Vaultfire on Avalanche:** [vaultfire-avalanche](https://github.com/Ghostkey316/vaultfire-avalanche)
- **Hermes Integration:** [hermes-vaultfire](https://github.com/Ghostkey316/hermes-vaultfire)
- **OpenClaw Plugin:** [openclaw-vaultfire](https://github.com/Ghostkey316/openclaw-vaultfire)

---

## Mission

> Morals over metrics. Privacy over surveillance. Freedom over control.

---


## Vaultfire Ecosystem

| Package | Description |
|---|---|
| [`@vaultfire/agent-sdk`](https://github.com/Ghostkey316/vaultfire-sdk) | **This package** — 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) | 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 |

## License

MIT — Vaultfire Protocol is open source.
