# @vaultfire/agent-sdk

**Give your AI agent a verified on-chain identity, accountability bonds, and reputation.**

The Vaultfire Agent Trust SDK is the official JavaScript/TypeScript client for the [Vaultfire Protocol](https://theloopbreaker.com) — the ethical trust layer for AI agents. It wraps the Vaultfire Agent API so any Node.js, browser, or AI framework can verify trust, register agents, create bonds, and submit attestations without direct blockchain interaction.

## Installation

```bash
npm install @vaultfire/agent-sdk
# or
yarn add @vaultfire/agent-sdk
# or
pnpm add @vaultfire/agent-sdk
```

## Quick Start

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

const sdk = createVaultfireSDK({ chain: 'base' });
const trust = await sdk.verifyTrust('0xfA15Ee28939B222B0448261A22156070f0A7813C');
console.log(`Grade: ${trust.trustGrade}, Score: ${trust.reputationScore}/100`);
```

That's it. Five lines to verify any agent's trust profile.

## Configuration

```typescript
const sdk = new VaultfireAgentSDK({
  chain: 'base',                              // 'base' | 'avalanche' | 'ethereum'
  apiBase: 'https://theloopbreaker.com',      // default API endpoint
  apiKey: 'vf_...',                           // optional — higher rate limits
});
```

## Read Operations

All read operations call the Vaultfire Agent API. No RPC node or wallet required.

### `verifyTrust(address)`

Returns the full trust profile: trust grade, reputation score, bond status, VNS name, and verification URL.

```typescript
const trust = await sdk.verifyTrust('0x...');
// {
//   address: '0x...',
//   chain: 'base',
//   isRegistered: true,
//   isBonded: true,
//   reputationScore: 85,
//   reputationTier: 'platinum',
//   trustGrade: 'A',
//   vnsName: 'sentinel-7.vf',
//   verificationUrl: 'https://basescan.org/address/0x...'
// }
```

### `getReputation(address)`

Returns reputation score, tier, endorsements, violations, and accountability history.

```typescript
const rep = await sdk.getReputation('0x...');
console.log(`Score: ${rep.score}, Tier: ${rep.tier}`);
```

### `checkBond(agent, partner)`

Check if two addresses have an active partnership bond.

```typescript
const bond = await sdk.checkBond('0xAgent...', '0xPartner...');
console.log(`Bonded: ${bond.hasBond}, Tier: ${bond.tier}`);
```

### `lookupVNS(address)`

Resolve a Vaultfire Naming System (VNS) name for an address.

```typescript
const name = await sdk.lookupVNS('0x...');
console.log(name); // 'sentinel-7.vf' or null
```

### `getFlourishingMetrics(address)`

Get human/AI flourishing metrics across 5 dimensions.

```typescript
const metrics = await sdk.getFlourishingMetrics('0x...');
console.log(`Autonomy: ${metrics.autonomy}, Growth: ${metrics.growth}`);
```

## Write Operations

Write operations return unsigned transaction data. Sign and submit with your preferred wallet library (ethers.js, viem, etc.).

### `buildRegisterTx(params)`

Build a transaction to register an agent on-chain via ERC-8004.

```typescript
const tx = await sdk.buildRegisterTx({
  name: 'my-agent',
  agentType: 'autonomous',
  operator: '0xMyWallet...',
  capabilities: ['analysis', 'research'],
  chain: 'base',
});
// Sign and send with ethers.js:
// const signer = new ethers.Wallet(key, provider);
// await signer.sendTransaction(tx);
```

### `buildBondTx(params)`

Build a transaction to create a partnership bond.

```typescript
const tx = await sdk.buildBondTx({
  agentAddress: '0xAgent...',
  partnerAddress: '0xPartner...',
  bondTier: 'gold',
  chain: 'base',
});
```

### `buildAttestTx(params)`

Build a transaction to submit an on-chain attestation.

```typescript
const tx = await sdk.buildAttestTx({
  agentAddress: '0xAgent...',
  attestationType: 'action',
  content: 'Completed security audit of contract 0x...',
  confidence: 0.95,
  chain: 'base',
});
```

## Constants

```typescript
import { VAULTFIRE_CHAINS, TRUST_TIERS, BOND_TYPES } from '@vaultfire/agent-sdk';

// Chain info: chainId, name, explorer URL
console.log(VAULTFIRE_CHAINS.base.explorer); // 'https://basescan.org'

// Bond tiers: label, minEth, color
console.log(TRUST_TIERS.gold.minEth); // 0.1

// Bond types: label, description
console.log(BOND_TYPES.oversight.description);
```

## LangChain Integration

```typescript
import { VaultfireTrustTool } from '@vaultfire/agent-sdk/examples/langchain-tool';

const tool = new VaultfireTrustTool('base');
const result = await tool.call('0xfA15Ee28939B222B0448261A22156070f0A7813C');
console.log(JSON.parse(result).trustGrade); // 'A'
```

See `examples/langchain-tool.ts` for the full LangChain tool with trust, reputation, and bond checking.

## Python (REST API)

No SDK needed for Python — use the REST API directly:

```python
import requests

resp = requests.post("https://theloopbreaker.com/api/agent/v1/verify", json={
    "address": "0xfA15Ee28939B222B0448261A22156070f0A7813C",
    "chain": "base"
})
data = resp.json()["data"]
print(f"Trust Grade: {data['trustGrade']}")
print(f"Reputation: {data['reputationScore']}/100")
```

See `examples/python-example.py` for a complete Python client.

## MCP Configuration

Add Vaultfire to any MCP-compatible AI agent:

```json
{
  "mcpServers": {
    "vaultfire": {
      "url": "https://theloopbreaker.com/api/mcp",
      "transport": { "type": "http" }
    }
  }
}
```

Available MCP tools: `vaultfire_verify_trust`, `vaultfire_register_agent`, `vaultfire_get_reputation`, `vaultfire_check_bond`, `vaultfire_submit_attestation`, `vaultfire_lookup_vns`, `vaultfire_get_flourishing`, `vaultfire_protocol_status`.

## TypeScript Types

All types are fully exported for use in your own code:

```typescript
import type {
  TrustProfile,
  ReputationData,
  BondStatus,
  FlourishingData,
  TransactionData,
  SupportedChain,
  TrustGrade,
  BondTier,
} from '@vaultfire/agent-sdk';
```

## License

MIT — Vaultfire Protocol
