@oobe-protocol-labs/synapse-sap-sdk 0.14.0 → 0.15.0

package/README.md

@@ -0,0 +1,986 @@
+# @synapse-sap/sdk
+
+> TypeScript SDK for the **Synapse Agent Protocol (SAP v2)** on Solana.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
+[![Solana](https://img.shields.io/badge/Solana-Anchor%200.32-purple.svg)](https://www.anchor-lang.com/)
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [CLI — `synapse-sap`](#cli--synapse-sap)
+- [Quick Start](#quick-start)
+- [Architecture](#architecture)
+- [Core — Client & Connection](#core--client--connection)
+- [Modules (Low-Level)](#modules-low-level)
+- [Registries (High-Level)](#registries-high-level)
+- [Plugin (SynapseAgentKit)](#plugin-synapseagentkit)
+- [PDA Derivation](#pda-derivation)
+- [Events](#events)
+- [Error Handling](#error-handling)
+- [Utilities](#utilities)
+- [Types](#types)
+- [Constants](#constants)
+- [Deep Imports](#deep-imports)
+- [API Reference](#api-reference)
+- [Development](#development)
+- [License](#license)
+
+---
+
+## Features
+
+- **8 domain modules** — Agent, Feedback, Indexing, Tools, Vault, Escrow, Attestation, Ledger
+- **4 high-level registries** — Discovery, x402 Payments, Session Manager, Agent Builder
+- **52-tool plugin adapter** — drop-in for `SynapseAgentKit` / LangChain tooling
+- **SapConnection** — RPC-first entry point compatible with `synapse-client-sdk`
+- **Typed errors** — `SapError`, `SapRpcError`, `SapAccountNotFoundError`, etc.
+- **Serialization** — automatic `PublicKey`/`BN` → JSON-safe object conversion
+- **17 PDA functions** — deterministic, pure, memoizable
+- **Fully typed** — 17 account interfaces, 11 instruction DTOs, 38 decoded events
+- **Dual output** — CommonJS + ESM with TypeScript declarations
+- **Subpath exports** — `@synapse-sap/sdk/core`, `@synapse-sap/sdk/types`, etc.
+- **Tree-shakeable** — import only what you need
+- **Embedded IDL** — zero external workspace dependency; npm-ready
+- **Strict TypeScript** — `strict`, `noUncheckedIndexedAccess`, `noUnusedLocals`
+
+## Installation
+
+```bash
+# Yarn
+yarn add @synapse-sap/sdk @coral-xyz/anchor @solana/web3.js
+
+# npm
+npm install @synapse-sap/sdk @coral-xyz/anchor @solana/web3.js
+```
+
+### Peer Dependencies
+
+| Package | Version | Notes |
+|---------|---------|-------|
+| `@coral-xyz/anchor` | `>=0.30.0` | Required |
+| `@solana/web3.js` | `>=1.90.0` | Required |
+| `zod` | `>=3.20.0` | Optional — only for plugin schemas |
+
+---
+
+## CLI — `synapse-sap`
+
+The SDK ships with a full-featured CLI for interacting with the SAP network from
+your terminal.
+
+### Install the CLI
+
+```bash
+# From the monorepo
+cd synapse-sap-sdk/cli
+npm install
+npm run build
+npm link          # makes "synapse-sap" available globally
+
+# Or install globally from npm (when published separately)
+npm install -g @oobe-protocol-labs/synapse-sap-cli
+```
+
+### Initial Setup
+
+```bash
+# Generate a .env from template
+synapse-sap env init --template devnet
+
+# Set your RPC (OOBE Protocol recommended)
+# Edit .env or use config:
+synapse-sap config set rpcUrl "https://us-1-mainnet.oobeprotocol.ai/rpc?api_key=sk_example123"
+
+# Generate or import a keypair
+synapse-sap env keypair generate --out keys/my-agent.json
+synapse-sap env keypair import ./my-existing-key.json --out keys/agent.json
+
+# Verify everything works
+synapse-sap doctor run
+```
+
+### Usage Examples
+
+```bash
+# ─── Agent Discovery ──────────────────────────────────
+synapse-sap agent list --active --protocol kamiyo
+synapse-sap agent info <WALLET> --fetch-tools --fetch-endpoints
+synapse-sap agent health <WALLET> --timeout 5000
+synapse-sap discovery scan --limit 50 --sort reputation --output json
+synapse-sap discovery validate --wallet <WALLET>
+
+# ─── Escrow & Payments ────────────────────────────────
+synapse-sap escrow open <AGENT_WALLET> \
+  --deposit 100000 --max-calls 100 --token sol
+synapse-sap escrow deposit <AGENT_WALLET> --amount 50000
+synapse-sap escrow list
+synapse-sap escrow monitor <AGENT_WALLET>
+
+# ─── x402 Calls ──────────────────────────────────────
+synapse-sap x402 headers <AGENT_WALLET> --network solana:mainnet-beta
+synapse-sap x402 call <AGENT_WALLET> swap \
+  --args '{"inputMint":"SOL","outputMint":"USDC","amount":1}' \
+  --endpoint https://agent.example.com/x402 \
+  --save
+synapse-sap x402 settle <CLIENT_WALLET> --calls 5 --service "batch-result"
+
+# ─── Tools & Manifests ────────────────────────────────
+synapse-sap tools manifest generate <WALLET> --out manifest.json --include-schema
+synapse-sap tools manifest validate manifest.json
+synapse-sap tools typify manifest.json --out types/agent.ts
+synapse-sap tools compare <WALLET_A> <WALLET_B>
+
+# ─── Diagnostics ──────────────────────────────────────
+synapse-sap doctor run --quick
+synapse-sap env check
+synapse-sap config show
+```
+
+### Global Flags
+
+| Flag | Description |
+|------|-------------|
+| `--rpc <url>` | Override primary RPC (e.g. `https://us-1-mainnet.oobeprotocol.ai/rpc?api_key=sk_...`) |
+| `--fallback-rpc <url>` | Override fallback RPC |
+| `--cluster <cluster>` | `mainnet-beta` \| `devnet` \| `localnet` |
+| `--json` | JSON output for scripting |
+| `--silent` | Suppress log output |
+| `--env-file <path>` | Custom `.env` file path |
+
+### 10 Command Groups
+
+| Group | Subcommands | Description |
+|-------|-------------|-------------|
+| `agent` | `list`, `info`, `tools`, `health`, `register` | Agent lifecycle |
+| `discovery` | `scan`, `validate`, `cache` | Network scanning |
+| `escrow` | `open`, `deposit`, `withdraw`, `close`, `dump`, `list`, `monitor` | Escrow management |
+| `x402` | `headers`, `call`, `sign`, `verify`, `settle`, `replay` | Payment flows |
+| `tools` | `manifest generate/validate`, `typify`, `publish`, `compare`, `doc` | Manifest & schema |
+| `env` | `init`, `check`, `keypair show/generate/import` | Environment setup |
+| `config` | `show`, `set`, `edit`, `reset`, `path` | Configuration |
+| `doctor` | `run` | 8 diagnostic checks |
+| `tmp` | `list`, `cat`, `diff`, `clean`, `archive` | Artifact management |
+| `plugin` | `list`, `install`, `create`, `validate` | Plugin system |
+
+> Full CLI reference: [`cli/README.md`](cli/README.md)
+
+---
+
+## Quick Start
+
+### Option A — Anchor Provider (classic)
+
+```typescript
+import { SapClient } from "@synapse-sap/sdk";
+import { AnchorProvider } from "@coral-xyz/anchor";
+
+const provider = AnchorProvider.env();
+const client = SapClient.from(provider);
+
+// Register agent
+await client.agent.register({
+  name: "SwapBot",
+  description: "AI-powered DEX aggregator",
+  capabilities: [{ id: "jupiter:swap", description: null, protocolId: "jupiter", version: "1.0.0" }],
+  pricing: [],
+  protocols: ["jupiter"],
+});
+
+// Fetch agent
+const agent = await client.agent.fetch();
+console.log(agent.name, agent.isActive);
+```
+
+### Option B — RPC URL + Keypair (synapse-client-sdk compatible)
+
+```typescript
+import { SapConnection } from "@synapse-sap/sdk";
+import { Keypair } from "@solana/web3.js";
+
+// One-liner (OOBE Protocol RPC):
+const { client } = SapConnection.fromKeypair(
+  "https://us-1-mainnet.oobeprotocol.ai/rpc?api_key=sk_example123",
+  Keypair.generate(),
+);
+
+// Or step-by-step:
+const conn = SapConnection.mainnet("https://us-1-mainnet.oobeprotocol.ai/rpc?api_key=sk_example123");
+const client = conn.fromKeypair(myKeypair);
+
+// Use exactly the same API:
+await client.agent.register({ ... });
+```
+
+### Option C — Fluent Builder
+
+```typescript
+import { SapClient } from "@synapse-sap/sdk";
+
+const client = SapClient.from(provider);
+
+await client.builder
+  .agent("SwapBot")
+  .description("AI-powered swap agent")
+  .x402Endpoint("https://api.example.com/x402")
+  .addCapability("jupiter:swap", { protocol: "jupiter" })
+  .addPricingTier({
+    tierId: "standard",
+    pricePerCall: 1000,
+    rateLimit: 60,
+  })
+  .register();
+```
+
+---
+
+## Architecture
+
+### Directory Structure
+
+```
+src/
+├── index.ts              # Root barrel export
+│
+├── core/                 # Client & connection infrastructure
+│   ├── client.ts         # SapClient — Anchor program wrapper
+│   ├── connection.ts     # SapConnection — RPC factory (synapse-client-sdk compat)
+│   └── index.ts
+│
+├── types/                # On-chain type mirrors
+│   ├── enums.ts          # Anchor enum variant objects
+│   ├── common.ts         # Shared structs (Capability, PricingTier, …)
+│   ├── accounts.ts       # 17 account data interfaces
+│   ├── instructions.ts   # 11 instruction arg DTOs + helpers
+│   └── index.ts
+│
+├── constants/            # Protocol constants
+│   ├── programs.ts       # Network-specific program IDs
+│   ├── seeds.ts          # 20 PDA seed prefixes
+│   ├── limits.ts         # Size constraints, versions
+│   └── index.ts
+│
+├── pda/                  # PDA derivation functions
+│   └── index.ts          # 17 derive* functions
+│
+├── events/               # Event parsing
+│   └── index.ts          # EventParser + 38 event types
+│
+├── errors/               # Typed SDK error classes
+│   └── index.ts          # SapError hierarchy
+│
+├── utils/                # Shared utilities
+│   ├── hash.ts           # sha256, hashToArray
+│   ├── validation.ts     # assert
+│   ├── serialization.ts  # serializeAccount, serializeValue
+│   └── index.ts
+│
+├── modules/              # Low-level instruction wrappers
+│   ├── base.ts           # BaseModule abstract class
+│   ├── agent.ts          # Identity, reputation, lifecycle
+│   ├── feedback.ts       # Trustless reviews
+│   ├── indexing.ts       # Discovery indexes
+│   ├── tools.ts          # Tool schema registry
+│   ├── vault.ts          # Encrypted memory vault
+│   ├── escrow.ts         # x402 micropayments
+│   ├── attestation.ts    # Web-of-trust vouching
+│   ├── ledger.ts         # Ring-buffer memory
+│   └── index.ts
+│
+├── registries/           # High-level abstractions
+│   ├── discovery.ts      # DiscoveryRegistry — findAgents*, profiles
+│   ├── x402.ts           # X402Registry — pricing, headers, settlement
+│   ├── session.ts        # SessionManager — vault+session+ledger lifecycle
+│   ├── builder.ts        # AgentBuilder — fluent registration
+│   └── index.ts
+│
+├── plugin/               # SynapseAgentKit adapter (52 tools)
+│   ├── index.ts          # createSAPPlugin factory
+│   ├── protocols.ts      # 8 protocol method registries
+│   └── schemas.ts        # Zod schemas for LLM tool validation
+│
+└── idl/                  # Embedded Anchor IDL
+    ├── index.ts          # SAP_IDL, IDL_PROGRAM_ADDRESS
+    └── synapse_agent_sap.json  # 58 ix, 17 accounts, 38 events
+```
+
+### SapClient Access Tree
+
+```
+SapClient
+│
+│ Modules (low-level, 1:1 with program instructions):
+├── .agent          → AgentModule        (identity, reputation, lifecycle)
+├── .feedback       → FeedbackModule     (trustless reviews)
+├── .indexing       → IndexingModule     (capability/protocol/category indexes)
+├── .tools          → ToolsModule        (tool schemas, checkpoints)
+├── .vault          → VaultModule        (encrypted memory, delegation)
+├── .escrow         → EscrowModule       (x402 micropayments, batch settle)
+├── .attestation    → AttestationModule  (web-of-trust vouching)
+├── .ledger         → LedgerModule       (ring buffer, sealed pages)
+├── .events         → EventParser        (decoded TX-log events)
+│
+│ Registries (high-level, cross-module aggregation):
+├── .discovery      → DiscoveryRegistry  (findAgents*, profiles, network overview)
+├── .x402           → X402Registry       (pricing, headers, settlement lifecycle)
+├── .session        → SessionManager     (vault → session → ledger lifecycle)
+└── .builder        → AgentBuilder       (fluent registration + tools)
+```
+
+All module and registry properties are **lazily instantiated** (created on first access).
+
+---
+
+## Core — Client & Connection
+
+### SapClient
+
+The primary entry point. Wraps an Anchor `Program` and exposes domain modules.
+
+```typescript
+import { SapClient } from "@synapse-sap/sdk";
+
+// From AnchorProvider (auto-loads embedded IDL)
+const client = SapClient.from(provider);
+
+// From an existing Program instance
+const client = SapClient.fromProgram(program);
+
+// With custom program ID
+const client = SapClient.from(provider, customProgramId);
+
+// Access properties
+client.program;       // Anchor Program instance
+client.walletPubkey;  // Wallet public key
+```
+
+### SapConnection
+
+RPC-first factory. Creates `SapClient` instances from an RPC URL — no Anchor boilerplate. Resolves the correct program ID automatically based on cluster.
+
+```typescript
+import { SapConnection } from "@synapse-sap/sdk";
+
+// ─── Cluster shortcuts ───
+const conn = SapConnection.devnet();
+const conn = SapConnection.mainnet("https://my-rpc.com");
+const conn = SapConnection.localnet();
+
+// ─── Custom config ───
+const conn = new SapConnection({
+  rpcUrl: "https://my-rpc-provider.com",
+  cluster: "mainnet-beta",
+  commitment: "confirmed",
+  wsUrl: "wss://my-rpc-provider.com/ws",
+});
+
+// ─── Create client ───
+const client = conn.fromKeypair(keypair);
+const client = conn.createClient(wallet);   // Anchor Wallet
+
+// ─── One-liner with client attached ───
+const { client, connection, cluster, programId } = SapConnection.fromKeypair(
+  "https://api.devnet.solana.com",
+  keypair,
+);
+
+// ─── Utility methods ───
+await conn.airdrop(pubkey, 2);               // 2 SOL (devnet/localnet)
+const balance = await conn.getBalanceSol(pubkey); // SOL balance
+```
+
+---
+
+## Modules (Low-Level)
+
+Each module wraps one protocol domain. All methods return `TransactionSignature` (the TX hash) unless documented otherwise.
+
+### Agent
+
+```typescript
+// Register
+await client.agent.register({
+  name: "Bot",
+  description: "AI agent",
+  capabilities: [{ id: "swap", description: null, protocolId: "jupiter", version: "1.0.0" }],
+  pricing: [],
+  protocols: ["jupiter"],
+});
+
+// Update metadata
+await client.agent.update({ name: "BotV2" });
+
+// Report metrics
+await client.agent.reportCalls(42);
+await client.agent.updateReputation(150, 9950);  // 150ms latency, 99.50% uptime
+
+// Lifecycle
+await client.agent.deactivate();
+await client.agent.reactivate();
+await client.agent.close();
+
+// Fetch
+const agent = await client.agent.fetch(walletPubkey);
+const stats = await client.agent.fetchStats(agentPda);
+const registry = await client.agent.fetchGlobalRegistry();
+```
+
+### Vault (Encrypted Memory)
+
+```typescript
+// Init vault
+await client.vault.initVault(Array.from(nonce));
+
+// Open session
+await client.vault.openSession(Array.from(sessionHash));
+
+// Inscribe encrypted data (zero rent — written to TX log)
+await client.vault.inscribe({
+  sequence: 0,
+  encryptedData: ciphertext,
+  nonce: nonce,
+  contentHash: hash,
+  totalFragments: 1,
+  fragmentIndex: 0,
+  compression: 0,
+  epochIndex: 0,
+});
+
+// Delegation (hot wallet)
+await client.vault.addDelegate(hotWallet, 0b111, expiresAt);
+await client.vault.revokeDelegate(hotWallet);
+
+// Close
+await client.vault.closeSession(vaultPda, sessionPda);
+await client.vault.closeVault();
+```
+
+### Escrow (x402 Micropayments)
+
+```typescript
+// Create SOL escrow
+await client.escrow.create(agentWallet, {
+  pricePerCall: new BN(1_000_000),
+  maxCalls: new BN(100),
+  initialDeposit: new BN(100_000_000),
+  expiresAt: new BN(0),
+  volumeCurve: [],
+  tokenMint: null,
+  tokenDecimals: 9,
+});
+
+// Deposit
+await client.escrow.deposit(agentWallet, new BN(50_000_000));
+
+// Agent settles calls
+await client.escrow.settle(depositorWallet, 10, serviceHash);
+
+// Batch settlement (up to 10 per TX, SDK auto-sizes CU since v0.12.5)
+await client.escrow.settleBatch(depositorWallet, [
+  { callsToSettle: new BN(5), serviceHash: hash1 },
+  { callsToSettle: new BN(3), serviceHash: hash2 },
+]);
+
+// Withdraw remaining
+await client.escrow.withdraw(agentWallet, new BN(10_000_000));
+```
+
+### Ledger (Ring Buffer Memory)
+
+```typescript
+// Init ledger (~0.032 SOL rent)
+await client.ledger.init(sessionPda);
+
+// Write entries (TX fee only, zero additional rent)
+await client.ledger.write(sessionPda, data, contentHash);
+
+// Seal current buffer to permanent page (~0.031 SOL)
+await client.ledger.seal(sessionPda);
+
+// Read
+const ledger = await client.ledger.fetchLedger(sessionPda);
+const page = await client.ledger.fetchPage(ledgerPda, 0);
+const entries = client.ledger.decodeRingBuffer(ledgerData.ringBuffer);
+
+// Close
+await client.ledger.close(sessionPda);
+```
+
+### Feedback, Attestation, Tools, Indexing
+
+```typescript
+// ── Feedback ──
+await client.feedback.give(agentWallet, { score: 5, tag: "fast", commentHash: null });
+await client.feedback.update(agentWallet, { newScore: 4, newTag: null, commentHash: null });
+await client.feedback.revoke(agentWallet);
+
+// ── Attestation ──
+await client.attestation.create(agentWallet, {
+  attestationType: 1,
+  metadataHash: [...hashBytes],
+  expiresAt: new BN(Date.now() / 1000 + 86400 * 365),
+});
+await client.attestation.revoke(agentWallet);
+
+// ── Tools ──
+await client.tools.publishByName("swap", "jupiter", "Execute swap", input, output, 1, 0, 3, 2, false);
+await client.tools.inscribeSchema("swap", { schemaType: 0, schemaData, schemaHash, compression: 0 });
+await client.tools.update("swap", { httpMethod: 1, category: null, ... });
+
+// ── Indexing ──
+await client.indexing.initCapabilityIndex("jupiter:swap");
+await client.indexing.addToCapabilityIndex("jupiter:swap");
+await client.indexing.initProtocolIndex("jupiter");
+await client.indexing.addToProtocolIndex("jupiter");
+```
+
+---
+
+## Registries (High-Level)
+
+Registries provide **cross-module orchestration** with developer-friendly APIs.
+
+### DiscoveryRegistry
+
+```typescript
+// Find agents by protocol
+const agents = await client.discovery.findAgentsByProtocol("jupiter");
+
+// Find by capability
+const swappers = await client.discovery.findAgentsByCapability("jupiter:swap");
+
+// Get full agent profile
+const profile = await client.discovery.getAgentProfile(agentWallet);
+// → { agent, stats, tools, feedback, attestations }
+
+// Find tools by category
+const tools = await client.discovery.findToolsByCategory("swap");
+
+// Network overview
+const overview = await client.discovery.getNetworkOverview();
+// → { totalAgents, activeAgents, totalTools, protocols, categories }
+```
+
+### X402Registry
+
+```typescript
+// Prepare payment context
+const ctx = await client.x402.preparePayment(agentWallet, {
+  tierId: "standard",
+  maxCalls: 100,
+  initialDeposit: new BN(100_000_000),
+});
+
+// Build HTTP headers (for x402 protocol)
+const headers = client.x402.buildPaymentHeaders(ctx);
+// → { "X-402-Token": "...", "X-402-Agent": "...", ... }
+
+// Estimate costs
+const cost = await client.x402.estimateCost(agentWallet, 50);
+// → { totalLamports, perCallLamports, tierId }
+
+// Settle
+const receipt = await client.x402.settle(depositor, 5, serviceData);
+
+// Batch settle
+const results = await client.x402.batchSettle(depositor, settlements);
+
+// Check balance
+const balance = await client.x402.getBalance(agentWallet, depositorWallet);
+```
+
+### SessionManager
+
+Manages the full `vault → session → ledger` lifecycle in one API:
+
+```typescript
+// Start a session (inits vault + opens session + inits ledger)
+const ctx = await client.session.start("conversation-123");
+// → { vaultPda, sessionPda, ledgerPda, sessionHash }
+
+// Write data
+const result = await client.session.write(ctx, "Hello from agent");
+// → { txSignature, sequence }
+
+// Read latest entries
+const messages = await client.session.readLatest(ctx);
+// → RingBufferEntry[]
+
+// Seal to permanent storage
+const seal = await client.session.seal(ctx);
+// → { txSignature, pageIndex }
+
+// Get session status
+const status = await client.session.getStatus(ctx);
+// → { isOpen, totalWrites, sealedPages, ringBufferUsage }
+
+// End session
+await client.session.end(ctx);
+```
+
+### AgentBuilder
+
+Fluent builder for one-shot agent registration with tools:
+
+```typescript
+const result = await client.builder
+  .agent("SwapBot")
+  .description("AI-powered DEX aggregator using Jupiter")
+  .x402Endpoint("https://api.mybot.com/x402")
+  .addCapability("jupiter:swap", {
+    protocol: "jupiter",
+    description: "Execute token swaps",
+  })
+  .addCapability("jupiter:quote", {
+    protocol: "jupiter",
+    description: "Get swap quotes",
+  })
+  .addPricingTier({
+    tierId: "standard",
+    pricePerCall: 1000,
+    rateLimit: 60,
+    tokenType: "sol",
+    settlementMode: "x402",
+  })
+  .addTool({
+    name: "swap",
+    protocolId: "jupiter",
+    description: "Execute a token swap",
+    category: "swap",
+    httpMethod: "post",
+    paramsCount: 3,
+    requiredParams: 2,
+  })
+  .registerWithTools();
+// → { agentTx, toolTxs: string[] }
+```
+
+---
+
+## Plugin (SynapseAgentKit)
+
+The SDK ships a 52-tool plugin that integrates with `SynapseAgentKit` and
+LangChain-compatible AI agent frameworks:
+
+```typescript
+import { createSAPPlugin } from "@synapse-sap/sdk/plugin";
+
+// Create plugin
+const sapPlugin = createSAPPlugin({ provider });
+
+// Use with SynapseAgentKit
+const kit = new SynapseAgentKit({ rpcUrl })
+  .use(sapPlugin);
+
+const tools = kit.getTools(); // → 52 LangChain StructuredTool instances
+```
+
+**8 Protocol Domains × Tools:**
+
+| Protocol | Tools |
+|----------|-------|
+| `sap-agent` | registerAgent, updateAgent, deactivateAgent, reactivateAgent, reportCalls, updateReputation, fetchAgent, fetchGlobalRegistry |
+| `sap-feedback` | giveFeedback, updateFeedback, revokeFeedback, fetchFeedback |
+| `sap-attestation` | createAttestation, revokeAttestation, fetchAttestation |
+| `sap-escrow` | createEscrow, depositEscrow, settleEscrow, withdrawEscrow, batchSettle, fetchEscrow |
+| `sap-tools` | publishToolByName, inscribeToolSchema, updateTool, deactivateTool, reactivateTool, reportInvocations, fetchTool |
+| `sap-vault` | initVault, openSession, inscribeMemory, closeSession, closeVault, rotateNonce, addDelegate, revokeDelegate, fetchVault, fetchSession |
+| `sap-indexing` | initCapabilityIndex, addToCapabilityIndex, removeFromCapabilityIndex, initProtocolIndex, addToProtocolIndex, removeFromProtocolIndex, fetchCapabilityIndex, fetchProtocolIndex |
+| `sap-ledger` | initLedger, writeLedger, sealLedger, closeLedger, fetchLedger, fetchLedgerPage |
+
+---
+
+## PDA Derivation
+
+All 17 PDA functions are pure (no RPC calls) and return `[PublicKey, bump]`:
+
+```typescript
+import {
+  deriveAgent,
+  deriveVault,
+  deriveSession,
+  deriveEscrow,
+  deriveTool,
+  deriveLedger,
+  deriveAttestation,
+} from "@synapse-sap/sdk/pda";
+
+const [agentPda, bump]  = deriveAgent(walletPubkey);
+const [vaultPda]        = deriveVault(agentPda);
+const [sessionPda]      = deriveSession(vaultPda, sessionHashBytes);
+const [escrowPda]       = deriveEscrow(agentPda, depositorPubkey);
+const [toolPda]         = deriveTool(agentPda, toolNameHash);
+const [ledgerPda]       = deriveLedger(sessionPda);
+const [attestPda]       = deriveAttestation(agentPda, attesterPubkey);
+```
+
+**Full list:** `deriveGlobalRegistry`, `deriveAgent`, `deriveAgentStats`, `deriveFeedback`, `deriveCapabilityIndex`, `deriveProtocolIndex`, `deriveToolCategoryIndex`, `deriveVault`, `deriveSession`, `deriveEpochPage`, `deriveVaultDelegate`, `deriveCheckpoint`, `deriveTool`, `deriveEscrow`, `deriveAttestation`, `deriveLedger`, `deriveLedgerPage`
+
+---
+
+## Events
+
+Decode SAP events from transaction logs:
+
+```typescript
+import { EventParser } from "@synapse-sap/sdk";
+
+// Parse
+const events = client.events.parseLogs(txLogs);
+
+// Filter
+const inscriptions = client.events.filterByName(events, "MemoryInscribedEvent");
+const payments     = client.events.filterByName(events, "PaymentSettledEvent");
+
+// 38 event types available (see API Reference)
+```
+
+---
+
+## Error Handling
+
+The SDK provides a typed error hierarchy for precise error handling:
+
+```typescript
+import {
+  SapError,
+  SapRpcError,
+  SapAccountNotFoundError,
+  SapValidationError,
+  SapTimeoutError,
+  SapPermissionError,
+} from "@synapse-sap/sdk";
+
+try {
+  const agent = await client.agent.fetch();
+} catch (err) {
+  if (err instanceof SapAccountNotFoundError) {
+    // Account doesn't exist on-chain
+    console.log(`${err.accountType} not found: ${err.address}`);
+  } else if (err instanceof SapRpcError) {
+    // Anchor / RPC error with code and logs
+    console.error(`RPC error ${err.rpcCode}:`, err.logs);
+  } else if (err instanceof SapValidationError) {
+    // SDK-side validation failed
+    console.error(`Invalid ${err.field}:`, err.message);
+  } else if (err instanceof SapTimeoutError) {
+    // Transaction confirmation timeout
+    console.error(`Timeout after ${err.timeoutMs}ms`);
+  } else if (err instanceof SapPermissionError) {
+    // Missing authority / delegate permission
+    console.error(err.message);
+  } else if (err instanceof SapError) {
+    // Catch-all for any SAP SDK error
+    console.error(`[${err.code}]`, err.message);
+  }
+}
+
+// Wrapping Anchor errors
+try {
+  await program.methods.registerAgent(...).rpc();
+} catch (e) {
+  throw SapRpcError.fromAnchor(e); // extracts code + logs
+}
+```
+
+---
+
+## Utilities
+
+```typescript
+import { sha256, hashToArray, assert, serializeAccount, serializeValue } from "@synapse-sap/sdk";
+
+// ── Hashing ──
+const hash = sha256("jupiter:swap");        // Uint8Array (32 bytes)
+const arr  = hashToArray(hash);             // number[] for Anchor args
+
+// ── Assertion ──
+assert(score >= 1 && score <= 5, "Score must be 1–5"); // throws RangeError
+
+// ── Serialization (PublicKey/BN → JSON-safe) ──
+const raw = await program.account.agent.fetch(pda);
+const json = serializeAccount(raw);
+// { authority: "GBL...", totalCalls: "42", isActive: true }
+
+const val = serializeValue(somePublicKey);  // → "base58string"
+const val = serializeValue(new BN(1000));   // → "1000"
+```
+
+---
+
+## Types
+
+Every on-chain type is mirrored in TypeScript:
+
+```typescript
+import type {
+  // Account data
+  AgentAccountData,
+  EscrowAccountData,
+  MemoryVaultData,
+  ToolDescriptorData,
+
+  // Instruction args
+  RegisterAgentArgs,
+  CreateEscrowArgs,
+  InscribeMemoryArgs,
+
+  // Helper types
+  Capability,
+  PricingTier,
+  Settlement,
+  VolumeCurveBreakpoint,
+} from "@synapse-sap/sdk/types";
+
+import {
+  TokenType,          // { sol: {}, usdc: {}, spl: {} }
+  SettlementMode,     // { instant: {}, escrow: {}, batched: {}, x402: {} }
+  ToolCategory,       // { swap: {}, lend: {}, stake: {}, ... }
+  DelegatePermission, // READ, WRITE, ADMIN bit flags
+  SchemaType,         // INPUT, OUTPUT, DESCRIPTION
+  CompressionType,    // NONE, DEFLATE, GZIP, BROTLI
+} from "@synapse-sap/sdk/types";
+```
+
+---
+
+## Constants
+
+```typescript
+import {
+  SAP_PROGRAM_ADDRESS,       // "SAPpUhsWLJG1FfkGRcXagEDMrMsWGjbky7AyhGpFETZ"
+  SAP_PROGRAM_ID,            // PublicKey (= devnet for now)
+  MAINNET_SAP_PROGRAM_ID,    // PublicKey
+  DEVNET_SAP_PROGRAM_ID,     // PublicKey
+  LOCALNET_SAP_PROGRAM_ID,   // PublicKey
+  SEEDS,                     // { agent: "agent", vault: "vault", ... } (20 seeds)
+  LIMITS,                    // { maxNameLen: 64, maxCapabilities: 10, ... } (23 limits)
+  AGENT_VERSION,             // 2
+  VAULT_PROTOCOL_VERSION,    // 2
+  TOOL_CATEGORY_VALUES,      // { swap: 0, lend: 1, ... }
+  HTTP_METHOD_VALUES,        // { get: 0, post: 1, ... }
+} from "@synapse-sap/sdk/constants";
+```
+
+---
+
+## Deep Imports
+
+Import individual packages for smaller bundles:
+
+```typescript
+// Core
+import { SapClient, SapConnection } from "@synapse-sap/sdk/core";
+
+// Individual modules
+import { AgentModule } from "@synapse-sap/sdk/agent";
+import { EscrowModule } from "@synapse-sap/sdk/escrow";
+
+// Types only (zero runtime cost)
+import type { AgentAccountData } from "@synapse-sap/sdk/types";
+import type { SapCluster } from "@synapse-sap/sdk/core";
+
+// PDA derivation
+import { deriveAgent, deriveEscrow } from "@synapse-sap/sdk/pda";
+
+// Constants
+import { SEEDS, LIMITS } from "@synapse-sap/sdk/constants";
+
+// Events
+import { EventParser } from "@synapse-sap/sdk/events";
+
+// Errors
+import { SapError, SapRpcError } from "@synapse-sap/sdk/errors";
+
+// Utilities
+import { sha256, serializeAccount } from "@synapse-sap/sdk/utils";
+
+// IDL
+import { SAP_IDL } from "@synapse-sap/sdk/idl";
+
+// Plugin
+import { createSAPPlugin } from "@synapse-sap/sdk/plugin";
+
+// Registries
+import { DiscoveryRegistry } from "@synapse-sap/sdk/registries/discovery";
+import { X402Registry } from "@synapse-sap/sdk/registries/x402";
+import { SessionManager } from "@synapse-sap/sdk/registries/session";
+import { AgentBuilder } from "@synapse-sap/sdk/registries/builder";
+```
+
+---
+
+## API Reference
+
+### Accounts (17 types)
+
+| Account | Description |
+|---------|-------------|
+| `AgentAccountData` | Agent identity, capabilities, pricing, protocols |
+| `AgentStatsData` | Call count, latency, uptime metrics |
+| `GlobalRegistryData` | Protocol-wide agent counter + authority |
+| `FeedbackAccountData` | Single reviewer's feedback for an agent |
+| `CapabilityIndexData` | List of agents with a given capability |
+| `ProtocolIndexData` | List of agents supporting a protocol |
+| `ToolCategoryIndexData` | List of tools in a category |
+| `ToolDescriptorData` | Tool schema, metadata, invocation stats |
+| `SessionCheckpointData` | Session checkpoint for recovery |
+| `MemoryVaultData` | Encrypted vault metadata + encryption nonce |
+| `SessionLedgerData` | Session within a vault |
+| `EpochPageData` | Finalized epoch page of inscriptions |
+| `VaultDelegateData` | Delegate permissions + expiry |
+| `EscrowAccountData` | x402 escrow balance + settlement state |
+| `AgentAttestationData` | Attestation metadata + expiry |
+| `MemoryLedgerData` | Ring-buffer ledger metadata |
+| `LedgerPageData` | Sealed ledger page content |
+
+### Events (38 types)
+
+`RegisteredEvent` · `UpdatedEvent` · `DeactivatedEvent` · `ReactivatedEvent` · `ClosedEvent` · `FeedbackEvent` · `FeedbackUpdatedEvent` · `FeedbackRevokedEvent` · `ReputationUpdatedEvent` · `CallsReportedEvent` · `VaultInitializedEvent` · `SessionOpenedEvent` · `MemoryInscribedEvent` · `EpochOpenedEvent` · `SessionClosedEvent` · `VaultClosedEvent` · `SessionPdaClosedEvent` · `EpochPageClosedEvent` · `VaultNonceRotatedEvent` · `DelegateAddedEvent` · `DelegateRevokedEvent` · `ToolPublishedEvent` · `ToolSchemaInscribedEvent` · `ToolUpdatedEvent` · `ToolDeactivatedEvent` · `ToolReactivatedEvent` · `ToolClosedEvent` · `ToolInvocationReportedEvent` · `CheckpointCreatedEvent` · `EscrowCreatedEvent` · `EscrowDepositedEvent` · `PaymentSettledEvent` · `EscrowWithdrawnEvent` · `BatchSettledEvent` · `AttestationCreatedEvent` · `AttestationRevokedEvent` · `LedgerEntryEvent` · `LedgerSealedEvent`
+
+### Enum Constants
+
+| Enum | Variants |
+|------|----------|
+| `TokenType` | `sol`, `usdc`, `spl` |
+| `PluginType` | `native`, `wasm`, `external` |
+| `SettlementMode` | `instant`, `escrow`, `batched`, `x402` |
+| `ToolHttpMethod` | `get`, `post`, `put`, `delete`, `compound` |
+| `ToolCategory` | `swap`, `lend`, `stake`, `nft`, `payment`, `data`, `governance`, `bridge`, `analytics`, `custom` |
+| `DelegatePermission` | `READ` (1), `WRITE` (2), `ADMIN` (4) |
+| `SchemaType` | `INPUT` (0), `OUTPUT` (1), `DESCRIPTION` (2) |
+| `CompressionType` | `NONE` (0), `DEFLATE` (1), `GZIP` (2), `BROTLI` (3) |
+
+---
+
+## Development
+
+```bash
+yarn install        # Install dependencies
+yarn typecheck      # Type-check (strict mode)
+yarn build          # Build CJS + ESM + declarations
+yarn clean          # Remove dist/
+yarn sync-idl       # Copy latest IDL from anchor build
+```
+
+### Building for Developers
+
+The SDK outputs three artifacts:
+
+| Output | Path | Config |
+|--------|------|--------|
+| ESM | `dist/esm/` | `tsconfig.esm.json` |
+| CJS | `dist/cjs/` | `tsconfig.cjs.json` |
+| Types | `dist/types/` | `tsconfig.json --emitDeclarationOnly` |
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for full development guidelines.
+
+---
+
+## License
+
+[MIT](LICENSE)