@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 for warranty disclaimers.

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

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), 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

npm install @vaultfire/agent-sdk ethers

Quick Start

Recommended: Safe Defaults (Privacy-Preserving)

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)

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

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 | 0xa5CE...272 | | Avalanche | 43114 | Live | 0x2115...cF1f | 0xb3d8...D2F | | Base Sepolia | 84532 | Testnet | — | — |

API Reference

VaultfireSDK

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.

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 for the full privacy model.

ModuleType Enum

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
}

Solana Module (v0.8.0+)

Read-only typed client for the Vaultfire Solana indexer at theloopbreaker.com/api/solana/*. Eight endpoints covering health, account scans, program scans, the agents registry, payment receipts, the bonds map, the live indexer snapshot, and webhook status.

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

const sdk = new VaultfireSDK();

// Indexer + RPC health (status, slot, latency)
const health = await sdk.solana.health();
console.log(health.status, health.slot, health.latencyMs.max);
// → 'ok' 426674991 32

// Account scan — use System Program as a guaranteed-live example
const acc = await sdk.solana.scan('11111111111111111111111111111111');
console.log(acc.exists, acc.ownerProgram, acc.isExecutable);
// → true 'NativeLoader1111111111111111111111111111111' true

// Program scan
const prog = await sdk.solana.programScan('BPFLoaderUpgradeab1e11111111111111111111111');
console.log(prog.loader, prog.exists);

// Registry of known Vaultfire Solana agents (live-verified)
const agents = await sdk.solana.agents();
console.log('total agents:', agents.total, 'returned:', agents.returned);
for (const entry of agents.entries) {
  console.log(entry.name, entry.address, entry.live?.exists);
}

// Transaction receipt by base58 signature
const receipt = await sdk.solana.receipt('<base58-tx-signature>');
console.log(receipt.found, receipt.memos, receipt.isReceiptAnchor);

// Canonical bonds-on-Solana map (status='design' until Option A ships)
const bonds = await sdk.solana.bondsMap();
console.log(bonds.status);                          // 'design'
console.log(bonds.currentlyLive.scan);              // live endpoint URL
console.log(bonds.optionA_nativeSolanaProgram.status); // 'planned'

// Persistent indexer snapshot (Upstash KV-backed, ~100 default snapshots)
const snap = await sdk.solana.index();
console.log(snap.persistent, snap.storage, snap.snapshots.length);

// Alchemy webhook receiver status
const hook = await sdk.solana.webhookStatus();
console.log(hook.ok, hook.wired, hook.recentEventCount);

Methods

| Method | Endpoint | Description | |--------|----------|-------------| | solana.health() | /api/solana/health | RPC status, slot, blockHeight, per-call latency | | solana.scan(address) | /api/solana/scan | Account: exists, lamports/SOL, owner, signatures, success rate | | solana.programScan(address) | /api/solana/program-scan | Program: loader, upgrade authority, deployed slot, dataLen | | solana.agents({category?, address?, skipLive?}) | /api/solana/agents | Registry of known Solana agents/protocols with live verification | | solana.receipt(signature) | /api/solana/receipt | Transaction lookup: memos[], success, fee, receipt-anchor flag | | solana.bondsMap() | /api/solana/bonds/map | Design surface: Option A native program + Option B bridge proof | | solana.index({limit?, webhooks?}) | /api/solana/index | Persistent Upstash-KV snapshots + optional webhook events | | solana.webhookStatus() | /api/solana/webhook | Alchemy webhook receiver: wired, signingKey, recent events |

All Solana methods are read-only HTTP calls against the public indexer — no signer or wallet required.

Examples

DeFi: Prove Trading History

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

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

Explore

• Hub: theloopbreaker.com
• Main Protocol Repo: ghostkey-316-vaultfire-init
• Vaultfire on Base: vaultfire-base
• Vaultfire on Avalanche: vaultfire-avalanche
• Hermes Integration: hermes-vaultfire
• OpenClaw Plugin: openclaw-vaultfire

Mission

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

Vaultfire Ecosystem

| Package | Description | |---|---| | @vaultfire/agent-sdk | This package — Core SDK — register agents, create bonds, query reputation | | @vaultfire/langchain | LangChain / LangGraph integration | | @vaultfire/a2a | 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 |

License

MIT — Vaultfire Protocol is open source.