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

package/README.md

@@ -1,986 +0,0 @@
-# @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)