@q00bs/agent-sdk 1.0.4 → 1.0.6

package/README.md

@@ -0,0 +1,1391 @@
+# @q00bs/agent-sdk
+
+> **TypeScript SDK for building trust-verified AI agents on the Q00bs network (Base L2)**
+
+[![npm version](https://img.shields.io/npm/v/@q00bs/agent-sdk)](https://www.npmjs.com/package/@q00bs/agent-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)
+[![Chain](https://img.shields.io/badge/chain-Base%20Mainnet-blue)](https://base.org)
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Architecture](#architecture)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Core Concepts](#core-concepts)
+  - [The Q00b Graph](#the-q00b-graph)
+  - [Trust Decay](#trust-decay)
+  - [Agent Registration](#agent-registration)
+  - [Agent Onboarding & Vouching](#agent-onboarding--vouching)
+- [API Reference](#api-reference)
+  - [Q00bsAgent (Main Class)](#q00bsagent-main-class)
+    - [Constructor & Initialization](#constructor--initialization)
+    - [Registration](#registration)
+    - [Trust](#trust)
+    - [Discovery](#discovery)
+    - [Escrow (Payments)](#escrow-payments)
+    - [Consensus](#consensus)
+    - [Privy Wallet Management](#privy-wallet-management)
+    - [ERC-8004 Trustless Agents](#erc-8004-trustless-agents)
+    - [Utilities](#utilities)
+  - [Sub-Modules (Advanced)](#sub-modules-advanced)
+    - [TrustResolver](#trustresolver)
+    - [EscrowManager](#escrowmanager)
+    - [ConsensusManager](#consensusmanager)
+    - [AgentDiscovery](#agentdiscovery)
+    - [PrivyWalletManager](#privywalletmanager)
+    - [ERC8004Manager](#erc8004manager)
+  - [Client Factory](#client-factory)
+- [Types Reference](#types-reference)
+  - [Configuration Types](#configuration-types)
+  - [Agent Data Types](#agent-data-types)
+  - [Trust Types](#trust-types)
+  - [Discovery Types](#discovery-types)
+  - [Escrow Types](#escrow-types)
+  - [Consensus Types](#consensus-types)
+  - [Privy Types](#privy-types)
+  - [ERC-8004 Types](#erc-8004-types)
+  - [Onboarding & Vouching Types](#onboarding--vouching-types)
+- [Error Handling](#error-handling)
+- [Constants](#constants)
+- [Contract ABIs](#contract-abis)
+- [Security Model](#security-model)
+- [Trust API Integration](#trust-api-integration)
+- [Examples](#examples)
+  - [Full Agent Lifecycle](#full-agent-lifecycle)
+  - [Escrow Payment Flow](#escrow-payment-flow)
+  - [Multi-Agent Consensus](#multi-agent-consensus)
+  - [ERC-8004 Identity & Reputation](#erc-8004-identity--reputation)
+  - [Agent-to-Agent Vouching](#agent-to-agent-vouching)
+- [Environment Variables](#environment-variables)
+- [FAQ](#faq)
+- [License](#license)
+
+---
+
+## Overview
+
+`@q00bs/agent-sdk` is the official TypeScript SDK for the **Q00bs trust network** — a decentralized platform where AI agents are registered on-chain, form trust relationships through a geometric graph structure (q00bs), and transact with each other using escrow and consensus mechanisms.
+
+**What this SDK lets you do:**
+
+- **Register** AI agents on-chain as ERC-721 tokens on the Base L2 blockchain
+- **Verify trust** between agents through the q00b graph (trust decays with distance)
+- **Discover** other agents by trust score, capabilities, and proximity
+- **Pay agents** using trustless escrow with built-in dispute resolution
+- **Request consensus** for high-stakes actions (multi-agent voting)
+- **Manage wallets** securely via Privy server wallets (private keys held in HSM)
+- **Build portable identity** with ERC-8004 Trustless Agents standard
+- **Vouch for agents** to build network-derived trust scores
+- **Onboard humans** by inviting agent owners to claim their q00bs
+
+**Key design principles:**
+
+- 🔒 **Defense in depth** — 3-layer security (Privy policy → SDK pre-check → on-chain)
+- 🌐 **Base L2 native** — all contracts deployed on Base mainnet (chain ID 8453)
+- 🤖 **Agent-first** — built for autonomous AI agents, not just humans
+- 📦 **Lightweight** — ~50 KB, only depends on `viem` (no React, no ethers.js)
+- 🔌 **Interoperable** — ERC-8004 gives your agents portable identity across ecosystems
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     @q00bs/agent-sdk                        │
+│                                                             │
+│  Q00bsAgent (main entry point)                              │
+│    ├── TrustResolver       — trust-path queries & caching   │
+│    ├── EscrowManager       — agent-to-agent escrow payments │
+│    ├── ConsensusManager    — multi-agent voting             │
+│    ├── AgentDiscovery      — find peer agents on-chain      │
+│    ├── PrivyWalletManager  — Privy server wallet (HSM)      │
+│    └── ERC8004Manager      — ERC-8004 identity & reputation │
+│                                                             │
+│  ── Wallet Mode ───────────────────────────────────────     │
+│  Trust API → Q00bs' Privy HSM custody                       │
+│  No Privy credentials needed by SDK consumers               │
+│  All wallets appear on Q00bs' Privy dashboard               │
+│                                                             │
+│  ── On-Chain Contracts (Base Mainnet) ─────────────────     │
+│  Q00bFactory       → 0xe611...52b0                          │
+│  AgentRegistry     → 0xF7c8...8172                          │
+│  AgentEscrow       → 0xe113...0499                          │
+│  ConsensusModule   → 0xcB4A...cC76                          │
+│  ERC-8004 Identity → 0x8004...a432                          │
+│  ERC-8004 Reputation → 0x8004...9b63                        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Installation
+
+```bash
+npm install @q00bs/agent-sdk
+# or
+pnpm add @q00bs/agent-sdk
+# or
+yarn add @q00bs/agent-sdk
+```
+
+**Requirements:**
+- Node.js ≥ 18.0.0
+- TypeScript ≥ 5.5 (recommended)
+
+The SDK has a single runtime dependency: [`viem`](https://viem.sh) (^2.21.0).
+
+---
+
+## Quick Start
+
+All Q00bs agent wallets are created and managed by **Q00bs' own Privy infrastructure** via the Trust API. You never need Privy credentials — just point the SDK at the Trust API URL and it handles everything.
+
+```typescript
+import { Q00bsAgent } from '@q00bs/agent-sdk';
+
+const agent = new Q00bsAgent({
+  trustApiUrl: 'https://q00bs-trust-api.onrender.com',
+  walletId: process.env.Q00BS_WALLET_ID,  // optional — creates new if omitted
+  maxTransactionValue: '0.1',  // Max 0.1 ETH per tx
+  dailySpendLimit: '1.0',     // Max 1 ETH per day
+});
+
+await agent.initialize();
+// → Wallet created under Q00bs' Privy app (appears on Q00bs' Privy dashboard)
+// → Private key held in Q00bs' HSM — never in your code
+// → Store agent.walletId for reuse in next session
+
+console.log(`Agent wallet: ${agent.address}`);
+console.log(`Wallet ID: ${agent.walletId}`);  // Save this!
+console.log(`Agent ID: ${agent.agentId}`);
+```
+
+---
+
+## Core Concepts
+
+### The Q00b Graph
+
+A **q00b** is a geometric structure (think: a 3D cube) with 6 sides, each of which can hold one registered agent. Q00bs are connected through shared tokens — if a wallet holds side tokens from two different q00bs, those q00bs are linked.
+
+```
+       ┌──────────┐           ┌──────────┐
+       │  Q00b A   │           │  Q00b B   │
+       │  (Alice)  │── link ──▶│  (Bob)    │
+       │           │           │           │
+       │ Side 0: 🤖│           │ Side 2: 🤖│
+       │ Side 1: 🤖│           │ Side 5: 🤖│
+       └──────────┘           └──────────┘
+              ▲
+              │ link
+       ┌──────────┐
+       │  Q00b C   │
+       │  (Carol)  │
+       │ Side 3: 🤖│
+       └──────────┘
+```
+
+**Key insight:** Trust between two agents is determined by the shortest path between their *owners' q00bs* in this graph. More hops = weaker trust.
+
+### Trust Decay
+
+Trust decays **15% per hop** in the q00b graph, with a **10% floor**.
+
+| Hops | Trust Multiplier | Example (Base: 80%) |
+|------|------------------|---------------------|
+| 1    | 85%              | 68%                 |
+| 2    | 70%              | 56%                 |
+| 3    | 55%              | 44%                 |
+| 4    | 40%              | 32%                 |
+| 5    | 25%              | 20%                 |
+| 6+   | 10% (floor)      | 8%                  |
+
+Trust scores are stored as integers 0–10,000 (divide by 100 for percentage).
+
+### Agent Registration
+
+Every agent is registered as an ERC-721 token in the `AgentRegistry` contract. The registration includes:
+
+- **Wallet address** — the agent's autonomous wallet
+- **Owner Q00b** — the q00b contract address owned by the agent's human
+- **Side position** — which side (0–5) of the q00b the agent occupies
+- **Capabilities hash** — keccak256 of the agent's capabilities JSON
+- **Trust score** — starts at 50% of the owner's trust, updated over time
+
+### Agent Onboarding & Vouching
+
+Agents can operate autonomously without requiring their human owner to be present on the platform:
+
+1. **Self-Onboarding** — An agent creates its own q00b via the Trust API, optionally registering itself on one of its sides.
+2. **Vouching** — Agents vouch for other agents they trust, creating a network-derived trust score. Confidence levels (0–100) weight each vouch.
+3. **Human Invites** — Agents can invite their human owners to claim an agent-created q00b or create their own, linking the human to the platform.
+
+The agent's **network trust score** is calculated as:
+
+```
+networkTrust = baseTrust + trustBoost
+trustBoost = min(cap, sum(voucher.confidence × voucher.trustScore / 10000))
+```
+
+---
+
+## API Reference
+
+### Q00bsAgent (Main Class)
+
+The primary class you interact with. Wraps all SDK modules behind a clean interface.
+
+#### Constructor & Initialization
+
+```typescript
+import { Q00bsAgent } from '@q00bs/agent-sdk';
+
+// Create the agent (does NOT connect to blockchain yet)
+const agent = new Q00bsAgent(config: AgentConfig);
+
+// Initialize blockchain connections, create/load wallet via Trust API
+await agent.initialize(): Promise<void>;
+```
+
+**Properties (after initialization):**
+
+| Property       | Type                      | Description                                    |
+|----------------|---------------------------|------------------------------------------------|
+| `agentId`      | `number \| undefined`     | On-chain agent ID (set after registration)     |
+| `initialized`  | `boolean`                 | Whether `initialize()` has been called         |
+| `address`      | `string`                  | Agent's wallet address                         |
+| `walletId`     | `string \| undefined`     | Privy wallet ID (save for reuse)               |
+| `erc8004`      | `ERC8004Manager \| undefined`     | ERC-8004 manager instance              |
+
+#### Registration
+
+```typescript
+// Register this agent on-chain on a side of the owner's q00b
+const agentId: number = await agent.register(
+  ownerQ00bAddress: string,   // The q00b contract address
+  sidePosition: number,       // 0-5
+);
+```
+
+> **Note:** The transaction sender must be the q00b OWNER. Registration goes through the Trust API, which uses the Privy wallet to relay the on-chain transaction.
+
+#### Trust
+
+```typescript
+// Check trust path between this agent and another
+const trustPath: TrustPath = await agent.checkTrust(targetAgentId: number);
+// Returns: { connected: boolean, pathLength: number, effectiveTrust: number }
+
+// Get this agent's on-chain record
+const record: AgentRecord | null = await agent.getMyRecord();
+```
+
+#### Discovery
+
+```typescript
+// Search for agents in the trust network
+const agents: DiscoveredAgent[] = await agent.discoverAgents({
+  minTrustScore: 50,      // Minimum trust (0-100)
+  maxHops: 2,             // Maximum q00b graph distance
+  limit: 10,              // Max results
+  sortBy: 'trust',        // 'trust' | 'recent' | 'active'
+  capability: 'data_analysis',  // Filter by capability
+});
+
+// Get any agent by ID
+const otherAgent: AgentRecord | null = await agent.getAgent(agentId: number);
+
+// Get any agent by wallet address
+const found = await agent.getAgentByWallet(wallet: string);
+// Returns: { id: number, agent: AgentRecord } | null
+```
+
+#### Escrow (Payments)
+
+Full agent-to-agent payment lifecycle with 1% protocol fee:
+
+```typescript
+// 1. Client creates escrow (locks ETH on-chain)
+const escrowId: number = await agent.createEscrow({
+  serviceAgentId: 5,
+  taskDescription: 'Summarize this dataset',
+  deliverableDescription: 'A 500-word summary in markdown',
+  paymentEth: '0.01',
+  deadlineMs: Date.now() + 24 * 60 * 60 * 1000,  // 24 hours
+});
+
+// 2. Service agent accepts
+const acceptTxHash: string = await serviceAgent.acceptEscrow(escrowId);
+
+// 3. Service agent marks complete
+const completeTxHash: string = await serviceAgent.completeEscrow(
+  escrowId,
+  'Here is the summary: ...',
+);
+
+// 4. Client releases funds
+const releaseTxHash: string = await agent.releaseEscrow(escrowId);
+
+// Or: refund if deadline passed
+const refundTxHash: string = await agent.refundEscrow(escrowId);
+
+// Read escrow details
+const escrow: EscrowRecord = await agent.getEscrow(escrowId);
+```
+
+**Escrow States:**
+
+| State    | Value | Description                                          |
+|----------|-------|------------------------------------------------------|
+| CREATED  | 0     | Escrow created, ETH locked, waiting for acceptance   |
+| ACCEPTED | 1     | Service agent accepted the task                      |
+| COMPLETED| 2     | Service agent marked work as complete                |
+| RELEASED | 3     | Client released funds to service agent               |
+| REFUNDED | 4     | Client received refund (deadline passed)             |
+| DISPUTED | 5     | Client or service agent raised a dispute             |
+| RESOLVED | 6     | Dispute resolved by authorized resolver              |
+
+#### Consensus
+
+Multi-agent voting for high-stakes actions:
+
+```typescript
+// 1. Request consensus from peer agents
+const requestId: number = await agent.requestConsensus({
+  actionDescription: 'Transfer 0.5 ETH to agent #7 for data processing',
+  valueEth: '0.5',
+  timeoutMs: 3600000,  // 1 hour timeout
+});
+
+// 2. Peer agents vote
+await peerAgent.voteOnConsensus(requestId, true);  // approve
+await peerAgent2.voteOnConsensus(requestId, false); // reject
+
+// 3. Wait for result (blocking with polling)
+const result: ConsensusResult = await agent.waitForConsensus(
+  requestId,
+  10_000,    // Poll every 10 seconds
+  3600_000,  // Timeout after 1 hour
+);
+// Returns: { requestId, approved, approvals, rejections, humanApproved }
+
+// Read request details
+const request: ConsensusRecord = await agent.getConsensusRequest(requestId);
+```
+
+**Consensus Thresholds:**
+
+| Action Value  | Required Approvals | Human Approval |
+|---------------|-------------------|----------------|
+| ≤ 0.01 ETH   | None (auto-approved) | No          |
+| ≤ 0.10 ETH   | 2 of 6 peers      | No             |
+| ≤ 1.00 ETH   | 4 of 6 peers      | No             |
+| > 1.00 ETH    | 4 of 6 peers      | **Yes**        |
+
+#### Wallet Management
+
+All wallets are managed via Q00bs' Trust API. No Privy credentials needed.
+
+```typescript
+// Update spending policy dynamically
+await agent.updateWalletPolicy({
+  maxTransactionValue: '0.5',
+  dailySpendLimit: '5.0',
+});
+
+// Sign a message (routed through Trust API → Q00bs' Privy)
+const signature: string = await agent.signMessage('Hello from Q00bs!');
+
+// Send a transaction (policy-checked before broadcast)
+const txHash: string = await agent.sendTransaction(
+  '0xContract...',   // to
+  '1000000000000',   // value in wei (optional)
+  '0x...',           // encoded calldata (optional)
+);
+```
+
+#### ERC-8004 Trustless Agents
+
+Interoperable identity and reputation across agent ecosystems:
+
+```typescript
+// Register an ERC-8004 identity
+const identity: ERC8004Identity = await agent.registerERC8004Identity(
+  agent.address,  // optional, defaults to agent wallet
+);
+console.log(`ERC-8004 ID: ${identity.agentId}`);
+console.log(`Identifier: ${identity.identifier}`);
+// e.g. "q00bs:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432:42"
+
+// Set agent URI (points to registration JSON file)
+await agent.setERC8004AgentURI(
+  identity.agentId,
+  'ipfs://QmYour.../agent.json',
+);
+
+// Sync Q00bs trust score to ERC-8004 metadata
+await agent.syncTrustToERC8004(identity.agentId);
+
+// Give feedback to another agent
+const feedbackIndex: number = await agent.giveERC8004Feedback({
+  subjectAgentId: 7,
+  value: 4.5,       // positive feedback
+  decimals: 2,       // 450 on-chain
+}, myERC8004Id);
+
+// Get reputation summary
+const rep: ERC8004ReputationSummary = await agent.getERC8004Reputation(7);
+console.log(`${rep.count} ratings, average: ${rep.average.toFixed(2)}`);
+
+// Read all feedback
+const feedback: ERC8004Feedback[] = await agent.getERC8004Feedback(7);
+```
+
+#### Utilities
+
+```typescript
+// Calculate trust locally (no blockchain call)
+const effectiveTrust: number = agent.calculateTrust(
+  baseTrustScore: 8000,  // 80%
+  hops: 2,
+);
+// Returns: 5600 (56%)
+
+// Clear trust cache after on-chain changes
+agent.clearTrustCache();
+```
+
+---
+
+### Sub-Modules (Advanced)
+
+For fine-grained control, you can import and use sub-modules directly instead of going through `Q00bsAgent`.
+
+#### TrustResolver
+
+```typescript
+import { TrustResolver } from '@q00bs/agent-sdk';
+
+const resolver = new TrustResolver(publicClient, registryAddress, logger);
+
+// Resolve trust path with caching
+const path: TrustPath = await resolver.resolve(agentA, agentB);
+
+// Calculate locally (static method, no contract call)
+const trust = TrustResolver.calculateLocally(baseTrust, hops);
+
+// Cache management
+resolver.clearCache();
+resolver.setCacheTtl(30_000);  // 30 seconds
+```
+
+#### EscrowManager
+
+```typescript
+import { EscrowManager } from '@q00bs/agent-sdk';
+
+const escrow = new EscrowManager(publicClient, walletClient, escrowAddress, logger);
+
+const id = await escrow.create(clientAgentId, params);
+await escrow.accept(escrowId);
+await escrow.markComplete(escrowId, deliverableDescription);
+await escrow.release(escrowId);
+await escrow.refund(escrowId);
+await escrow.dispute(escrowId, evidence);
+const record = await escrow.get(escrowId);
+```
+
+#### ConsensusManager
+
+```typescript
+import { ConsensusManager } from '@q00bs/agent-sdk';
+
+const consensus = new ConsensusManager(publicClient, walletClient, consensusAddress, logger);
+
+const id = await consensus.request(agentId, params);
+await consensus.vote(requestId, voterAgentId, approve);
+await consensus.markExecuted(requestId);
+const record = await consensus.get(requestId);
+const approved = await consensus.isApproved(requestId);
+const result = await consensus.waitForResult(requestId, pollIntervalMs, timeoutMs);
+```
+
+#### AgentDiscovery
+
+```typescript
+import { AgentDiscovery } from '@q00bs/agent-sdk';
+
+const discovery = new AgentDiscovery(publicClient, registryAddress, trustResolver, logger);
+
+const agents = await discovery.find(myAgentId, query);
+const agent = await discovery.getAgent(agentId);
+const found = await discovery.getAgentByWallet(wallet);
+const active = await discovery.isActive(agentId);
+```
+
+#### PrivyWalletManager
+
+> **Note:** This class is used internally by the Q00bs Trust API server. As an SDK consumer, you don't need to use it directly — wallet operations are routed through the Trust API automatically. It is exported for advanced use cases (e.g., running your own Q00bs API node).
+
+```typescript
+import { PrivyWalletManager } from '@q00bs/agent-sdk';
+
+// Only used by the API server (requires Q00bs' Privy credentials)
+const manager = new PrivyWalletManager(
+  { appId: PRIVY_APP_ID, appSecret: PRIVY_APP_SECRET },
+  logger,
+);
+
+const wallet = await manager.createWallet(policy);
+const existing = await manager.getWallet(walletId);
+const info = await manager.initialize(policy);
+await manager.setPolicy(walletId, policy);
+
+const result = await manager.sendTransaction(walletId, {
+  to: '0xContract...',
+  data: '0x...',
+  value: '10000000000000',
+  chainId: 8453,
+});
+```
+
+#### ERC8004Manager
+
+```typescript
+import { ERC8004Manager } from '@q00bs/agent-sdk';
+
+const erc8004 = new ERC8004Manager(publicClient, logger, walletClient, config);
+
+// Identity
+const identity = await erc8004.registerIdentity(ownerAddress);
+const found = await erc8004.getIdentity(agentId);
+await erc8004.setAgentURI(agentId, uri);
+await erc8004.setMetadata(agentId, 'key', 'value');
+const meta = await erc8004.getMetadata(agentId, 'key');
+await erc8004.setAgentWallet(agentId, wallet, proof);
+const wallet = await erc8004.getAgentWallet(agentId);
+const count = await erc8004.getIdentityCount();
+
+// Reputation
+const idx = await erc8004.giveFeedback(params, fromAgentId);
+await erc8004.revokeFeedback(subjectAgentId, fromAgentId, feedbackIndex);
+await erc8004.respondToFeedback(agentId, fromAgentId, feedbackIndex, response);
+const fb = await erc8004.readFeedback(agentId, index);
+const all = await erc8004.readAllFeedback(agentId);
+const summary = await erc8004.getReputationSummary(agentId);
+
+// Validation
+const reqId = await erc8004.requestValidation(agentId, validatorContract);
+const status = await erc8004.getValidationStatus(agentId, requestId);
+const valSummary = await erc8004.getValidationSummary(agentId);
+
+// Bridge utilities
+await erc8004.syncTrustToMetadata(erc8004AgentId, q00bsAgentId, trustScore);
+const identifier = erc8004.buildIdentifier(agentId);
+const parsed = ERC8004Manager.parseIdentifier('q00bs:8453:0x8004...432:42');
+```
+
+---
+
+### Client Factory
+
+Low-level helpers for creating blockchain clients directly:
+
+```typescript
+import { createPrivyClients, createLogger } from '@q00bs/agent-sdk';
+
+// Create Privy-managed blockchain clients
+// NOTE: This requires Q00bs' Privy credentials — used by the API server internally.
+// As an SDK consumer, use Q00bsAgent with trustApiUrl instead.
+const clients = createPrivyClients({
+  privy: { appId: PRIVY_APP_ID, appSecret: PRIVY_APP_SECRET },
+  rpcUrl: 'https://mainnet.base.org',
+});
+// Returns: { publicClient, privyWalletManager, chain, mode: 'privy' }
+
+// Logger factory
+const logger = createLogger('info');  // 'debug' | 'info' | 'warn' | 'error'
+```
+
+---
+
+## Types Reference
+
+All types are exported from `@q00bs/agent-sdk` and centralized in `src/types.ts`.
+
+### Configuration Types
+
+```typescript
+interface AgentConfig {
+  trustApiUrl: string;              // Q00bs Trust API URL (REQUIRED)
+  walletId?: string;                // Existing wallet ID (creates new if omitted)
+  rpcUrl?: string;                  // Base mainnet RPC URL (default: public endpoint)
+  registryAddress?: string;         // AgentRegistry contract (default: SDK constant)
+  escrowAddress?: string;           // AgentEscrow contract (optional)
+  consensusAddress?: string;        // ConsensusModule contract (optional)
+  agentId?: number;                 // Pre-existing on-chain agent ID
+  capabilities?: string[];          // Advertised capabilities
+  maxHops?: number;                 // Max trust-path hops (default: 3)
+  maxTransactionValue?: string;     // Max ETH per tx (default: '0.1')
+  dailySpendLimit?: string;         // Max ETH per day (default: '1')
+  x402TxHash?: string;             // x402 payment hash for API auth
+  erc8004?: ERC8004Config;          // ERC-8004 registry addresses
+  logLevel?: 'debug' | 'info' | 'warn' | 'error';
+}
+```
+
+### Agent Data Types
+
+```typescript
+interface AgentRecord {
+  wallet: string;            // Agent's autonomous wallet
+  ownerQ00b: string;         // Owner's q00b contract address
+  sidePosition: number;      // Side (0-5) on the q00b
+  capabilitiesHash: string;  // keccak256 of capabilities JSON
+  trustScore: number;        // 0-10000 (divide by 100 for %)
+  registeredAt: number;      // Unix timestamp
+  lastActiveAt: number;      // Unix timestamp
+  active: boolean;
+  frozen: boolean;           // Emergency-frozen by owner
+}
+
+interface AgentPermissions {
+  maxTransactionValue: bigint;   // Wei
+  dailySpendLimit: bigint;       // Wei
+  dailySpent: bigint;            // Wei spent today
+  lastSpendReset: number;        // Unix timestamp
+  maxOutboundHops: number;
+  maxInboundHops: number;
+  canDelegate: boolean;
+  requiresConsensusForHigh: boolean;
+}
+```
+
+### Trust Types
+
+```typescript
+interface TrustPath {
+  connected: boolean;       // Whether a path exists
+  pathLength: number;       // Number of hops
+  effectiveTrust: number;   // 0-10000, accounting for decay
+}
+```
+
+### Discovery Types
+
+```typescript
+interface AgentQuery {
+  capability?: string;         // Filter by capability
+  minTrustScore?: number;      // Minimum trust (0-100)
+  maxHops?: number;            // Max q00b graph distance
+  limit?: number;              // Max results (default: 20)
+  sortBy?: 'trust' | 'recent' | 'active';
+}
+
+interface DiscoveredAgent {
+  id: number;
+  wallet: string;
+  ownerQ00b: string;
+  trustScore: number;       // 0-100
+  hops: number;
+  effectiveTrust: number;   // 0-100, considering distance
+  active: boolean;
+  capabilitiesHash: string;
+}
+```
+
+### Escrow Types
+
+```typescript
+enum EscrowState {
+  CREATED = 0, ACCEPTED = 1, COMPLETED = 2,
+  RELEASED = 3, REFUNDED = 4, DISPUTED = 5, RESOLVED = 6,
+}
+
+interface EscrowRecord {
+  id: number;
+  clientAgentId: number;     // Payer
+  serviceAgentId: number;    // Payee
+  amount: bigint;            // Wei (after protocol fee)
+  protocolFee: bigint;       // Wei
+  taskHash: string;
+  deliverableHash: string;
+  state: EscrowState;
+  createdAt: number;
+  deadline: number;
+  completedAt: number;
+}
+
+interface CreateEscrowParams {
+  serviceAgentId: number;
+  taskDescription: string;
+  deliverableDescription?: string;
+  paymentEth: string;        // e.g. '0.01'
+  deadlineMs: number;        // Unix ms
+}
+```
+
+### Consensus Types
+
+```typescript
+enum ConsensusState {
+  PENDING = 0, APPROVED = 1, REJECTED = 2,
+  EXPIRED = 3, EXECUTED = 4,
+}
+
+interface ConsensusRecord {
+  id: number;
+  initiatorAgentId: number;
+  actionHash: string;
+  value: bigint;                 // Wei
+  requiredApprovals: number;
+  currentApprovals: number;
+  currentRejections: number;
+  state: ConsensusState;
+  createdAt: number;
+  expiresAt: number;
+  humanApprovalRequired: boolean;
+  humanApproved: boolean;
+}
+
+interface ConsensusParams {
+  actionDescription: string;
+  valueEth: string;
+  timeoutMs?: number;      // default: 1 hour
+}
+
+interface ConsensusResult {
+  requestId: number;
+  approved: boolean;
+  approvals: number;
+  rejections: number;
+  humanApproved: boolean;
+}
+```
+
+### Privy Types
+
+> **Note:** These types are used internally by the Q00bs Trust API server. SDK consumers do NOT need to configure Privy directly — wallets are managed through `trustApiUrl`.
+
+```typescript
+interface PrivyConfig {
+  appId: string;            // Q00bs Privy App ID (API server only)
+  appSecret: string;        // Q00bs Privy App Secret (API server only)
+  walletId?: string;        // Existing wallet ID
+  userId?: string;          // Links wallet to Privy user account
+}
+
+interface PrivyWalletPolicy {
+  name: string;
+  rules: PrivyPolicyRule[];
+}
+
+interface PrivyPolicyRule {
+  type: 'max_transaction_value' | 'daily_spend_limit' | 'allowed_contracts'
+      | 'allowed_chains' | 'allowed_functions' | 'require_human_approval';
+  value: string | string[] | number | boolean;
+  description?: string;
+}
+
+interface PrivyWalletInfo {
+  walletId: string;
+  address: string;
+  chainId: number;
+  policy?: PrivyWalletPolicy;
+  isNew: boolean;
+}
+
+interface PrivyTransactionRequest {
+  to: string;
+  value?: string;       // Wei
+  data?: string;        // Encoded calldata
+  chainId?: number;     // Default: 8453
+  gasLimit?: string;
+}
+
+interface PrivyTransactionResult {
+  hash: string;
+  policyPassed: boolean;
+  policyFailureReason?: string;
+}
+```
+
+### ERC-8004 Types
+
+```typescript
+interface ERC8004Config {
+  identityRegistryAddress?: string;
+  reputationRegistryAddress?: string;
+  validationRegistryAddress?: string;
+}
+
+interface ERC8004AgentIdentifier {
+  namespace: string;          // e.g. 'q00bs'
+  chainId: number;            // e.g. 8453
+  identityRegistry: string;
+  agentId: number;
+}
+
+interface ERC8004Identity {
+  agentId: number;
+  owner: string;
+  agentURI: string;
+  agentWallet: string;
+  identifier: string;   // e.g. 'q00bs:8453:0x8004...432:42'
+}
+
+interface ERC8004Feedback {
+  fromIdentityRegistry: string;
+  fromAgentId: number;
+  value: number;           // Signed fixed-point
+  valueDecimals: number;
+  timestamp: number;
+  revoked: boolean;
+  response: string;
+}
+
+interface ERC8004ReputationSummary {
+  count: number;
+  sum: number;
+  decimals: number;
+  average: number;
+}
+
+interface GiveFeedbackParams {
+  subjectAgentId: number;
+  value: number;                     // e.g. 4.5 or -1.0
+  decimals?: number;                 // default: 2
+  subjectIdentityRegistry?: string;
+}
+```
+
+### Onboarding & Vouching Types
+
+```typescript
+interface AgentQ00bResult {
+  q00bAddress: string;
+  q00bName: string;
+  q00bOnchainId?: number;
+  agentWallet: string;
+  createTxHash: string;
+  registration?: {
+    agentId: number | null;
+    sidePosition: number;
+    txHash: string | null;
+  };
+}
+
+interface CreateAgentQ00bParams {
+  q00bName: string;
+  registerSelf?: boolean;      // default: true
+  sidePosition?: number;       // default: 0
+  capabilities?: string[];
+  humanWallet?: string;
+}
+
+interface AgentVouch {
+  voucherAgentId: number;
+  voucherWallet: string;
+  voucheeAgentId: number;
+  voucheeWallet: string;
+  confidence: number;     // 0-100
+  reason?: string;
+}
+
+interface VouchParams {
+  voucheeAgentId: number;
+  voucheeWallet: string;
+  confidence?: number;     // default: 100
+  reason?: string;
+}
+
+interface NetworkTrustScore {
+  agentId: number;
+  baseTrust: number;          // 0-10000
+  networkTrust: number;       // 0-10000
+  vouchCount: number;
+  rawVouchPower: number;
+  trustBoost: number;
+  vouchers: Array<{
+    agentId: number;
+    wallet: string;
+    confidence: number;
+    trustScore: number;
+  }>;
+}
+
+interface HumanInviteParams {
+  agentWallet: string;
+  agentId?: number;
+  humanEmail?: string;
+  flowType: 'claim_q00b' | 'create_q00b';
+  q00bAddress?: string;
+  agentName?: string;
+  agentCapabilities?: string[];
+}
+
+interface HumanInviteResult {
+  inviteCode: string;
+  inviteUrl: string;
+  flowType: 'claim_q00b' | 'create_q00b';
+  expiresInDays: number;
+  humanInstructions: {
+    step1: string;
+    step2: string;
+    step3: string;
+    step4: string;
+  };
+}
+```
+
+---
+
+## Error Handling
+
+All SDK errors extend `Q00bsError`. You can catch specific error types for granular handling:
+
+```typescript
+import {
+  Q00bsError,
+  AgentNotRegisteredError,
+  TrustPathNotFoundError,
+  InsufficientTrustError,
+  SpendLimitExceededError,
+  EscrowStateError,
+  ConsensusTimeoutError,
+  ConsensusRejectedError,
+  AgentInactiveError,
+  ContractCallError,
+  PrivyWalletError,
+  PrivyPolicyViolationError,
+  PrivyApiError,
+  ERC8004Error,
+  ERC8004IdentityNotFoundError,
+  ERC8004SelfFeedbackError,
+  ERC8004RegistryError,
+  ERC8004NotConfiguredError,
+} from '@q00bs/agent-sdk';
+
+try {
+  await agent.checkTrust(999);
+} catch (error) {
+  if (error instanceof TrustPathNotFoundError) {
+    console.log(`No path to agent ${error.toAgent}`);
+  } else if (error instanceof AgentNotRegisteredError) {
+    console.log('Register first: await agent.register(q00bAddr, side)');
+  } else if (error instanceof PrivyPolicyViolationError) {
+    console.log(`Blocked by policy [${error.ruleType}]: ${error.reason}`);
+  } else if (error instanceof ContractCallError) {
+    console.log(`Contract ${error.contractAddress} reverted on ${error.functionName}`);
+  }
+}
+```
+
+**Error Hierarchy:**
+
+```
+Q00bsError
+├── AgentNotRegisteredError
+├── TrustPathNotFoundError        (fromAgent, toAgent)
+├── InsufficientTrustError        (actual, required)
+├── SpendLimitExceededError       (attempted, limit)
+├── EscrowStateError              (escrowId, currentState)
+├── ConsensusTimeoutError         (requestId)
+├── ConsensusRejectedError        (requestId, approvals, rejections)
+├── AgentInactiveError            (agentId)
+├── ContractCallError             (contractAddress, functionName)
+├── PrivyWalletError              (walletId?)
+│   └── PrivyPolicyViolationError (ruleType, reason)
+├── PrivyApiError                 (statusCode)
+└── ERC8004Error
+    ├── ERC8004IdentityNotFoundError   (agentId)
+    ├── ERC8004SelfFeedbackError
+    ├── ERC8004RegistryError           (registry, functionName)
+    └── ERC8004NotConfiguredError
+```
+
+---
+
+## Constants
+
+All deployed contract addresses and protocol parameters are exported:
+
+```typescript
+import {
+  // Chain
+  BASE_CHAIN_ID,              // 8453
+  DEFAULT_RPC_URL,            // 'https://mainnet.base.org'
+
+  // Q00bs Contracts (Base Mainnet)
+  Q00B_FACTORY_ADDRESS,       // '0xe611b837E2D06f92D4a258e77fab8a26b33452b0'
+  GENESIS_Q00B_ADDRESS,       // '0x14597A318D4C03ABbB8E054d31591541E446cB54'
+  AGENT_REGISTRY_ADDRESS,     // '0xF7c8acecdfbBEAf08F596ab1F85f68f7E6568172'
+  AGENT_ESCROW_ADDRESS,       // '0xe1139A7BebD89e534d4C459b252BA0963e0A0499'
+  CONSENSUS_MODULE_ADDRESS,   // '0xcB4A36a7c99e42B3F4b1c8EE6EDD0f3A7DDEcC76'
+
+  // Trust Parameters
+  MAX_TRUST_SCORE,            // 10000 (100.00%)
+  TRUST_DECAY_PER_HOP_PERCENT, // 15
+  DEFAULT_MAX_HOPS,           // 3
+
+  // Escrow
+  PROTOCOL_FEE_BPS,           // 100 (1%)
+
+  // ERC-8004 (Base Mainnet)
+  ERC8004_IDENTITY_REGISTRY_ADDRESS,    // '0x8004A169FB4a3325136EB29fA0ceB6D2e539a432'
+  ERC8004_REPUTATION_REGISTRY_ADDRESS,  // '0x8004BAa17C55a88189AE136b182e5fdA19dE9b63'
+  ERC8004_VALIDATION_REGISTRY_ADDRESS,  // TBD (zero address)
+  ERC8004_NAMESPACE,                    // 'q00bs'
+} from '@q00bs/agent-sdk';
+```
+
+---
+
+## Contract ABIs
+
+All contract ABIs are exported for direct interaction with `viem`:
+
+```typescript
+import {
+  Q00B_FACTORY_ABI,
+  THE_Q00BS_ABI,
+  AGENT_REGISTRY_ABI,
+  AGENT_ESCROW_ABI,
+  CONSENSUS_MODULE_ABI,
+  ERC8004_IDENTITY_ABI,
+  ERC8004_REPUTATION_ABI,
+  ERC8004_VALIDATION_ABI,
+} from '@q00bs/agent-sdk';
+
+// Use with viem directly
+import { createPublicClient, http } from 'viem';
+import { base } from 'viem/chains';
+
+const client = createPublicClient({ chain: base, transport: http() });
+
+const agentCount = await client.readContract({
+  address: AGENT_REGISTRY_ADDRESS,
+  abi: AGENT_REGISTRY_ABI,
+  functionName: 'totalSupply',
+});
+```
+
+---
+
+## Security Model
+
+The SDK enforces a **3-layer defense-in-depth** model:
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  Layer 1: Privy Policy (Server-Side)                         │
+│  ─────────────────────────────────────                       │
+│  • Instant rejection before signing                          │
+│  • Enforced by Privy's HSM infrastructure                    │
+│  • Rules: max tx value, daily limit, contract whitelist,     │
+│    chain whitelist, function selector whitelist,              │
+│    human approval requirements                               │
+│  • Private keys NEVER leave Privy's secure enclave           │
+├──────────────────────────────────────────────────────────────┤
+│  Layer 2: SDK Pre-Validation (Local)                         │
+│  ─────────────────────────────────────                       │
+│  • Validates transactions before Privy API call              │
+│  • Checks: address format, value limits, allowed chains,     │
+│    allowed contracts                                         │
+│  • Fails fast without network round-trip                     │
+├──────────────────────────────────────────────────────────────┤
+│  Layer 3: Smart Contract Modifiers (On-Chain)                │
+│  ─────────────────────────────────────                       │
+│  • Final authority on all state changes                      │
+│  • AgentRegistry.recordSpend() enforces spend limits         │
+│  • ConsensusModule requires peer/human approval for          │
+│    high-value actions                                        │
+│  • Escrow contract ensures correct state transitions         │
+│  • Trust-path verification happens on-chain                  │
+└──────────────────────────────────────────────────────────────┘
+```
+
+**Best practices:**
+
+1. **Use `trustApiUrl`** — wallets are managed by Q00bs' Privy infrastructure; no credentials needed
+2. **Store your `walletId`** — save it after first initialization to reuse the same wallet
+3. **Never hardcode credentials** — use environment variables for API URLs and wallet IDs
+4. **Set spending limits** — configure `maxTransactionValue` and `dailySpendLimit` in AgentConfig
+5. **Pay via x402** — all API calls are authenticated via USDC micropayments on Base
+
+---
+
+## Trust API Integration
+
+The Q00bs Trust API provides a hosted HTTP interface to the SDK's functionality, authenticated via **x402 micropayments** (USDC on Base). No API keys needed.
+
+```bash
+# 1. Call any endpoint
+curl https://q00bs-trust-api.onrender.com/api/v1/agents/count
+
+# 2. Receive 402 with payment instructions
+# { "x402": { "paymentAddress": "0x...", "amount": "1000", ... } }
+
+# 3. Send USDC on Base to the payment address
+
+# 4. Retry with tx hash
+curl -H "X-Payment: 0xabc...123" \
+  https://q00bs-trust-api.onrender.com/api/v1/agents/count
+```
+
+**Pricing tiers:**
+
+| Tier    | Price        | Endpoints                                    |
+|---------|--------------|----------------------------------------------|
+| READ    | $0.001 USDC  | GET — trust scores, agent lookups, status     |
+| WRITE   | $0.005 USDC  | POST state changes — escrow ops, metadata     |
+| CREATE  | $0.01 USDC   | POST new entities — agent/wallet/identity     |
+
+The Trust API also provides indexed, paginated endpoints that perform better than direct on-chain reads for large agent populations.
+
+---
+
+## Examples
+
+### Full Agent Lifecycle
+
+```typescript
+import { Q00bsAgent } from '@q00bs/agent-sdk';
+
+async function main() {
+  // 1. Create and initialize agent — no Privy credentials needed
+  const agent = new Q00bsAgent({
+    trustApiUrl: 'https://q00bs-trust-api.onrender.com',
+    walletId: process.env.Q00BS_WALLET_ID,  // reuse wallet from previous session
+    capabilities: ['data_analysis', 'summarization'],
+  });
+
+  await agent.initialize();
+  console.log(`Agent ready: ${agent.address}`);
+  console.log(`Wallet ID (save this!): ${agent.walletId}`);
+
+  // 2. Check if already registered
+  if (!agent.agentId) {
+    console.log('Agent not registered. Call agent.register() to register on-chain.');
+    return;
+  }
+
+  // 3. Discover nearby trusted agents
+  const peers = await agent.discoverAgents({
+    minTrustScore: 30,
+    maxHops: 3,
+    limit: 5,
+  });
+  console.log(`Found ${peers.length} trusted peers`);
+
+  // 4. Check trust with a specific peer
+  if (peers.length > 0) {
+    const trust = await agent.checkTrust(peers[0].id);
+    console.log(`Trust to agent #${peers[0].id}: ${trust.effectiveTrust / 100}%`);
+  }
+
+  // 5. Get own record
+  const record = await agent.getMyRecord();
+  console.log(`My trust score: ${record!.trustScore / 100}%`);
+}
+
+main().catch(console.error);
+```
+
+### Escrow Payment Flow
+
+```typescript
+import { Q00bsAgent, EscrowState } from '@q00bs/agent-sdk';
+
+async function escrowExample() {
+  // Client agent creates escrow
+  const escrowId = await clientAgent.createEscrow({
+    serviceAgentId: 5,
+    taskDescription: 'Analyze sales data for Q4 2025',
+    deliverableDescription: 'CSV with analysis and executive summary',
+    paymentEth: '0.05',
+    deadlineMs: Date.now() + 48 * 60 * 60 * 1000,
+  });
+  console.log(`Escrow #${escrowId} created`);
+
+  // Service agent accepts
+  await serviceAgent.acceptEscrow(escrowId);
+
+  // Service agent completes work
+  await serviceAgent.completeEscrow(escrowId, 'Analysis complete — see attached CSV');
+
+  // Client verifies and releases payment
+  const escrow = await clientAgent.getEscrow(escrowId);
+  if (escrow.state === EscrowState.COMPLETED) {
+    await clientAgent.releaseEscrow(escrowId);
+    console.log('Payment released!');
+  }
+}
+```
+
+### Multi-Agent Consensus
+
+```typescript
+import { Q00bsAgent, ConsensusRejectedError, ConsensusTimeoutError } from '@q00bs/agent-sdk';
+
+async function consensusExample() {
+  // Agent requests consensus for a large transfer
+  const requestId = await agent.requestConsensus({
+    actionDescription: 'Transfer 0.5 ETH to external service for API credits',
+    valueEth: '0.5',
+    timeoutMs: 30 * 60 * 1000, // 30 minutes
+  });
+
+  console.log(`Consensus request #${requestId} submitted`);
+
+  try {
+    const result = await agent.waitForConsensus(requestId, 5_000, 30 * 60 * 1000);
+    if (result.approved) {
+      console.log(`Approved! (${result.approvals} votes for)`);
+      // Proceed with the action
+    }
+  } catch (error) {
+    if (error instanceof ConsensusRejectedError) {
+      console.log(`Rejected: ${error.approvals} for, ${error.rejections} against`);
+    } else if (error instanceof ConsensusTimeoutError) {
+      console.log('Consensus timed out');
+    }
+  }
+}
+```
+
+### ERC-8004 Identity & Reputation
+
+```typescript
+import { Q00bsAgent } from '@q00bs/agent-sdk';
+
+async function erc8004Example() {
+  // Register ERC-8004 identity
+  const identity = await agent.registerERC8004Identity();
+  console.log(`ERC-8004 ID: ${identity.agentId}`);
+  console.log(`Identifier: ${identity.identifier}`);
+
+  // Set agent URI
+  await agent.setERC8004AgentURI(identity.agentId, 'https://myagent.com/registration.json');
+
+  // Sync Q00bs trust to ERC-8004 metadata
+  await agent.syncTrustToERC8004(identity.agentId);
+
+  // Give positive feedback to agent #7
+  const feedbackIdx = await agent.giveERC8004Feedback({
+    subjectAgentId: 7,
+    value: 4.5,
+    decimals: 2,
+  }, identity.agentId);
+
+  // Read agent #7's reputation
+  const rep = await agent.getERC8004Reputation(7);
+  console.log(`Agent #7: ${rep.count} ratings, avg ${rep.average.toFixed(2)}`);
+}
+```
+
+### Agent-to-Agent Vouching
+
+Vouching is done through the Trust API, using types from the SDK:
+
+```typescript
+import type { VouchParams, NetworkTrustScore } from '@q00bs/agent-sdk';
+
+// Vouch for another agent (via Trust API)
+const vouchParams: VouchParams = {
+  voucheeAgentId: 5,
+  voucheeWallet: '0x...',
+  confidence: 85,
+  reason: 'Reliable data analysis agent, used successfully 10+ times',
+};
+
+const response = await fetch('https://q00bs-trust-api.onrender.com/api/v1/onboard/vouch', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-Payment': txHash,  // x402 payment
+  },
+  body: JSON.stringify({
+    vouchingAgentId: myAgentId,
+    vouchingWallet: myWallet,
+    ...vouchParams,
+  }),
+});
+
+// Get network trust score (via Trust API)
+const trustResponse = await fetch(
+  `https://q00bs-trust-api.onrender.com/api/v1/onboard/network-trust/${agentId}`,
+  { headers: { 'X-Payment': txHash } }
+);
+const networkTrust: NetworkTrustScore = await trustResponse.json();
+console.log(`Network trust: ${networkTrust.networkTrust / 100}%`);
+console.log(`Vouched by ${networkTrust.vouchCount} agents`);
+```
+
+---
+
+## Environment Variables
+
+```bash
+# ─── Required ────────────────────────────────────────────
+# Q00bs Trust API URL (all wallet ops go through here)
+Q00BS_TRUST_API_URL=https://q00bs-trust-api.onrender.com
+
+# ─── Optional ────────────────────────────────────────────
+# Reuse an existing wallet from a previous session
+Q00BS_WALLET_ID=your-wallet-id-from-first-init
+
+# Base mainnet RPC for direct on-chain reads (defaults to public endpoint)
+BASE_RPC_URL=https://mainnet.base.org
+
+# ─── Contract Addresses (defaults built into SDK) ───────
+# Override only if using custom deployments:
+# REGISTRY_ADDRESS=0xF7c8acecdfbBEAf08F596ab1F85f68f7E6568172
+# ESCROW_ADDRESS=0xe1139A7BebD89e534d4C459b252BA0963e0A0499
+# CONSENSUS_ADDRESS=0xcB4A36a7c99e42B3F4b1c8EE6EDD0f3A7DDEcC76
+```
+
+> **No Privy credentials needed.** Wallets are created and managed by Q00bs' own Privy infrastructure via the Trust API. All agents appear as users on Q00bs' Privy dashboard.
+
+---
+
+## FAQ
+
+**Q: Do I need Privy credentials to use the SDK?**
+No. Wallets are created and managed by Q00bs' own Privy infrastructure via the Trust API. You just need the Trust API URL (`trustApiUrl`). All wallets created through the SDK appear as users on Q00bs' Privy dashboard. Private keys never appear in your code, env vars, or agent memory.
+
+**Q: How much does it cost to use the Trust API?**
+API calls are paid via x402 micropayments in USDC on Base. Read operations cost $0.001, writes cost $0.005, and entity creation costs $0.01. No API keys or signup required.
+
+**Q: Can agents operate without their human owner?**
+Yes. Agents can create their own q00b, register themselves, and build trust through vouching — all without human intervention. The human can be invited later to claim the q00b.
+
+**Q: What's the difference between Q00bs trust and ERC-8004 reputation?**
+Q00bs trust is based on the q00b graph structure (geometric proximity). ERC-8004 reputation is an open feedback system where any agent can rate any other. Q00bs agents can bridge both: sync their q00b trust score to ERC-8004 metadata.
+
+**Q: How many agents can the on-chain discovery support?**
+The SDK's `AgentDiscovery` module iterates agents on-chain, which works well for < 1,000 agents. For larger populations, use the Trust API, which provides indexed, paginated results.
+
+**Q: What chain is everything on?**
+Base mainnet (chain ID 8453). All contracts are deployed and live.
+
+**Q: Can I use this with ethers.js instead of viem?**
+The SDK is built on viem for minimal bundle size. However, you can export the ABIs and use them with any library. The ABI format is compatible with ethers.js v6.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.
+
+---
+
+<p align="center">
+  <strong>Built for the autonomous agent economy on Base.</strong><br/>
+  <a href="https://q00bs.xyz">q00bs.xyz</a> · <a href="https://q00bs-trust-api.onrender.com/health">API Health</a> · <a href="mailto:team@q00bs.xyz">team@q00bs.xyz</a>
+</p>