@oobe-protocol-labs/synapse-client-sdk 1.0.0-beta → 1.0.2

package/README.md

@@ -1,1393 +1,579 @@
-# Synapse Client SDK
+# @oobe-protocol-labs/synapse-client-sdk
 
-TypeScript SDK for Solana blockchain with advanced features including AI integration, real-time WebSocket support, DeFi tools, NFT management, and intelligent caching.
+Typed Solana RPC gateway SDK for Node.js and the browser.
+Covers JSON-RPC, WebSocket PubSub, gRPC/Geyser streaming, DAS (Digital Asset Standard),
+AI agent tooling (LangChain + Zod), and the x402 HTTP payment protocol --
+all behind a single `SynapseClient` entry point.
 
-> **Note:** This SDK is specifically designed to be perfectly aligned with the Synapse Gateway and Oobe Protocol architecture, ensuring optimal compatibility, high performance, and native integration with all gateway enterprise features (rate limiting, distributed caching, load balancing, circuit breaker).
+| | |
+|-|-|
+| **Version** | 1.0.1 |
+| **License** | MIT |
+| **Node** | >= 18.0.0 |
+| **TypeScript** | >= 5.0 |
+| **Registry** | `npm i @oobe-protocol-labs/synapse-client-sdk` |
 
-## Architecture Overview
-
-```
-┌──────────────────────────────────────────────────────────────────────┐
-│                        Synapse Client SDK                            │
-├──────────────────────────────────────────────────────────────────────┤
-│                                                                      │
-│  ┌─────────────┐  ┌──────────────┐  ┌────────────┐  ┌────────────┐   │
-│  │   Client    │  │   Advanced   │  │  WebSocket │  │ Analytics  │   │
-│  │   Core      │  │   Features   │  │   Client   │  │  Engine    │   │
-│  └─────────────┘  └──────────────┘  └────────────┘  └────────────┘   │
-│                                                                      │
-│  ┌─────────────┐  ┌──────────────┐  ┌────────────┐  ┌────────────┐   │
-│  │    DeFi     │  │     NFT      │  │     AI     │  │    RPC     │   │
-│  │   Module    │  │   Module     │  │   Module   │  │  Methods   │   │
-│  └─────────────┘  └──────────────┘  └────────────┘  └────────────┘   │
-│                                                                      │
-├──────────────────────────────────────────────────────────────────────┤
-│                    Solana RPC Gateway Layer                          │
-└──────────────────────────────────────────────────────────────────────┘
-```
+---
 
-## Features Matrix
+## Table of Contents
+
+1. [Installation](#installation)
+2. [Quick Start](#quick-start)
+3. [Architecture](#architecture)
+4. [Module Reference](#module-reference)
+   - [core/](#core)
+   - [rpc/](#rpc)
+   - [das/](#das)
+   - [websocket/](#websocket)
+   - [grpc/](#grpc)
+   - [ai/](#ai)
+   - [utils/](#utils)
+5. [Endpoints and Regions](#endpoints-and-regions)
+6. [Branded Types](#branded-types)
+7. [AI Agent Integration](#ai-agent-integration)
+   - [Zod Schemas and LangChain Tools](#zod-schemas-and-langchain-tools)
+   - [Protocol Tools (Jupiter, Raydium, Metaplex)](#protocol-tools)
+   - [Agent Commerce Gateway](#agent-commerce-gateway)
+   - [x402 Payment Protocol](#x402-payment-protocol)
+8. [Testing](#testing)
+9. [Build and Development](#build-and-development)
+10. [Package Exports](#package-exports)
+11. [Documentation](#documentation)
+12. [Contributing](#contributing)
+13. [License](#license)
 
-| Module | Capabilities | Status | Performance |
-|--------|--------------|--------|-------------|
-| **Core Client** | RPC calls, batching, rotation, statistics | Production | 10k+ req/s |
-| **Advanced** | Circuit breaker, smart caching, load balancing | Production | 99.9% uptime |
-| **WebSocket** | Real-time subscriptions, auto-reconnect | Production | <50ms latency |
-| **DeFi** | Jupiter, Jito, token data, price feeds | Production | Sub-second execution |
-| **NFT** | Metadata, rarity, marketplace aggregation | Production | <100ms queries |
-| **AI** | OOBE Protocol, Zero-Combine, PDA management | Production | ML-powered |
-| **Analytics** | Metrics, predictions, anomaly detection | Production | Real-time insights |
-| **Methods** | 70+ Solana RPC methods | Production | Type-safe |
+---
 
 ## Installation
 
 ```bash
-npm install @synapse/client-sdk
-# or
-pnpm add @synapse/client-sdk
-# or
-yarn add @synapse/client-sdk
-```
-
-## Quick Start
-
-### Basic Client Initialization
+# pnpm (recommended)
+pnpm add @oobe-protocol-labs/synapse-client-sdk
 
-```typescript
-import { SynapseClient } from '@synapse/client-sdk';
+# npm
+npm install @oobe-protocol-labs/synapse-client-sdk
 
-const client = new SynapseClient({
-  endpoint: 'https://your-synapse-gateway.com',
-  apiKey: process.env.SYNAPSE_API_KEY,
-  timeout: 30000,
-  debug: false,
-});
-
-// Execute RPC call
-const balance = await client.call('getBalance', ['YourPublicKeyHere']);
-console.log('Balance (SOL):', balance / 1e9);
-
-// Batch multiple RPC calls
-const results = await client.batch([
-  { method: 'getBalance', params: ['address1'] },
-  { method: 'getAccountInfo', params: ['address2', { encoding: 'jsonParsed' }] },
-  { method: 'getBlockHeight', params: [] },
-]);
-
-console.log('Batch results:', results);
+# yarn
+yarn add @oobe-protocol-labs/synapse-client-sdk
 ```
 
-### Client Statistics
-
-```typescript
-const stats = client.getStats();
+TypeScript is a peer dependency. Ensure `typescript >= 5.0` is installed in your project.
 
-console.log('Performance Metrics:', {
-  requestCount: stats.requestCount,
-  errorCount: stats.errorCount,
-  errorRate: (stats.errorCount / stats.requestCount * 100).toFixed(2) + '%',
-  averageLatency: stats.averageLatency.toFixed(2) + 'ms',
-  cacheHitRate: (stats.cacheHitRate * 100).toFixed(2) + '%',
-  activeConnections: stats.activeConnections,
-  pendingRequests: stats.pendingRequests,
-  uptime: Math.floor((Date.now() - stats.uptime) / 1000) + 's',
-});
-```
+---
 
-### Endpoint Rotation
+## Quick Start
 
-The client automatically rotates between multiple endpoints for high availability:
+```ts
+import { SynapseClient, Pubkey } from '@oobe-protocol-labs/synapse-client-sdk';
 
-```typescript
 const client = new SynapseClient({
-  endpoint: [
-    'https://rpc1.synapse.com',
-    'https://rpc2.synapse.com',
-    'https://rpc3.synapse.com',
-  ],
-  apiKey: process.env.SYNAPSE_API_KEY,
-  timeout: 30000,
+  endpoint: 'https://rpc.synapse.com',
+  apiKey: 'sk-...',
 });
 
-// Client automatically uses next endpoint on failure
-client.on('endpoint-rotate', ({ oldEndpoint, newEndpoint, reason }) => {
-  console.log(`Rotated from ${oldEndpoint} to ${newEndpoint}: ${reason}`);
-});
-```
+// JSON-RPC
+const balance = await client.rpc.getBalance(Pubkey('So11111111111111111111111111111111'));
+console.log(balance.value); // lamports
 
----
+// DAS (compressed NFTs)
+const asset = await client.das.getAsset(Pubkey('...'));
+console.log(asset.content.metadata?.name);
 
-## Core Client
+// WebSocket
+client.ws.onSlotChange((slot) => console.log('slot', slot));
 
-### Configuration
-
-```typescript
-interface SynapseConfig {
-  endpoint: string | string[];  // Single or multiple RPC endpoints
-  apiKey?: string;             // Optional API key for authentication
-  timeout?: number;            // Request timeout in milliseconds (default: 30000)
-  debug?: boolean;             // Enable debug logging (default: false)
-}
+// Cleanup
+client.destroy();
 ```
 
-### Core Methods
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `call<T>` | `(method: string, params?: any[], options?: RequestOptions) => Promise<T>` | Execute single RPC call |
-| `batch` | `(requests: RpcRequest[]) => Promise<RpcResponse[]>` | Execute multiple RPC calls in parallel |
-| `getStats` | `() => ClientStats` | Get client performance statistics |
-| `setEndpoint` | `(endpoint: string \| string[]) => void` | Update RPC endpoint(s) |
-| `clearCache` | `() => void` | Clear internal request cache |
-| `destroy` | `() => Promise<void>` | Cleanup resources and connections |
+### Factory helpers
 
-### Event System
-
-```typescript
-// Request lifecycle events
-client.on('request', ({ method, params, id }) => {
-  console.log(`[${id}] ${method}`, params);
-});
-
-client.on('response', ({ method, result, latency, id }) => {
-  console.log(`[${id}] ${method} completed in ${latency}ms`);
-});
-
-client.on('error', ({ method, error, attempt, id }) => {
-  console.error(`[${id}] ${method} failed (attempt ${attempt}):`, error.message);
-});
-
-// Retry and rotation events
-client.on('retry', ({ method, attempt, maxAttempts, delay }) => {
-  console.log(`Retrying ${method}: ${attempt}/${maxAttempts} after ${delay}ms`);
-});
+```ts
+import { createSynapse } from '@oobe-protocol-labs/synapse-client-sdk';
 
-client.on('endpoint-rotate', ({ oldEndpoint, newEndpoint, reason }) => {
-  console.log(`Endpoint rotation: ${oldEndpoint} → ${newEndpoint} (${reason})`);
-});
-
-// Cache events
-client.on('cache-hit', ({ key, ttl, layer }) => {
-  console.log(`Cache hit: ${key} from ${layer} (TTL: ${ttl}ms)`);
-});
-
-client.on('cache-miss', ({ key }) => {
-  console.log(`Cache miss: ${key}`);
-});
+const client = createSynapse({ endpoint: 'https://rpc.synapse.com' });
 ```
 
----
-
-## Module Documentation
-
-### 1. Advanced Features Module
-
-**Location:** [`src/advanced/`](./src/advanced/README.md)
+```ts
+import { SynapseClient, SynapseNetwork, SynapseRegion } from '@oobe-protocol-labs/synapse-client-sdk';
 
-Enterprise-grade resilience and performance optimization.
-
-#### Components
-
-| Component | Purpose | Key Features |
-|-----------|---------|--------------|
-| **Circuit Breaker** | Prevent cascade failures | State machine (closed/open/half-open), automatic recovery, fallback support |
-| **Smart Caching** | Multi-layer intelligent caching | L1 (memory), L2 (extended), L3 (Redis), ML predictive loading, compression |
-| **Load Balancer** | Request distribution | Round-robin, weighted, least-connections, IP hash, EWMA strategies |
-
-#### Quick Example
-
-```typescript
-import { SmartCaching, CircuitBreaker, LoadBalancer } from '@synapse/client-sdk/advanced';
-
-// Multi-layer caching
-const cache = new SmartCaching({
-  maxSize: 10000,
-  enableL2: true,
-  enableDistributed: true,
-  enablePredictive: true,
-});
-
-// Circuit breaker protection
-const breaker = new CircuitBreaker({
-  failureThreshold: 5,
-  timeout: 60000,
-  retryInterval: 30000,
-  enableFallback: true,
+// Auto-resolved endpoint by network and region
+const client = SynapseClient.fromEndpoint({
+  network: SynapseNetwork.Mainnet,
+  region: SynapseRegion.US,
+  apiKey: 'sk-...',
 });
-
-// Load balancing
-const balancer = new LoadBalancer({
-  endpoints: ['rpc1', 'rpc2', 'rpc3'],
-  strategy: 'ewma', // Latency-aware
-  healthCheckInterval: 30000,
-});
-
-// Combined usage
-const result = await breaker.execute(
-  async () => {
-    const endpoint = balancer.getNextEndpoint();
-    const cached = await cache.get(cacheKey);
-    if (cached) return cached;
-    
-    const data = await fetchFromEndpoint(endpoint);
-    await cache.set(cacheKey, data, { ttl: 60000 });
-    return data;
-  },
-  async () => {
-    // Fallback to stale cache
-    return await cache.get(cacheKey, { allowStale: true });
-  }
-);
 ```
 
-**[Read Full Documentation →](./src/advanced/README.md)**
-
 ---
 
-### 2. WebSocket Client Module
-
-**Location:** [`src/websocket/`](./src/websocket/README.md)
-
-Real-time Solana blockchain data streaming with intelligent reconnection.
-
-#### Subscription Types
-
-| Type | Method | Use Case | Commitment Options |
-|------|--------|----------|-------------------|
-| **Account** | `accountSubscribe` | Monitor account changes | processed, confirmed, finalized |
-| **Program** | `programSubscribe` | Track program accounts | processed, confirmed, finalized |
-| **Slot** | `slotSubscribe` | Block production tracking | N/A |
-| **Signature** | `signatureSubscribe` | Transaction confirmation | processed, confirmed, finalized |
-| **Logs** | `logsSubscribe` | Transaction logs | processed, confirmed, finalized |
-
-#### Quick Example
+## Architecture
 
-```typescript
-import { WebSocketClient } from '@synapse/client-sdk/websocket';
-
-const wsClient = new WebSocketClient({
-  endpoint: 'wss://your-synapse-gateway.com',
-  apiKey: process.env.SYNAPSE_API_KEY,
-  autoReconnect: true,
-  maxReconnectAttempts: 10,
-  reconnectDelay: 5000,
-  enableSmartCaching: true,
-  enableCircuitBreaker: true,
-});
-
-await wsClient.connect();
-
-// Subscribe to account changes
-const subId = await wsClient.accountSubscribe(
-  'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC mint
-  (accountInfo) => {
-    console.log('Account lamports:', accountInfo.lamports);
-    console.log('Account owner:', accountInfo.owner);
-  },
-  {
-    commitment: 'confirmed',
-    encoding: 'jsonParsed',
-    enableCache: true,
-    resilient: true, // Auto-restore on reconnect
-  }
-);
-
-// Monitor metrics
-wsClient.on('metrics-update', (metrics) => {
-  console.log('Subscriptions active:', metrics.subscriptionsActive);
-  console.log('Average latency:', metrics.averageLatency);
-});
-
-// Cleanup
-await wsClient.accountUnsubscribe(subId);
-await wsClient.disconnect();
 ```
-
-**[Read Full Documentation →](./src/websocket/README.md)**
-
----
-
-### 3. DeFi Module
-
-**Location:** [`src/defi/`](./src/defi/README.md)
-
-Production-ready DeFi integrations for Solana.
-
-#### Integrations Matrix
-
-| Integration | Protocol | Features | Performance |
-|-------------|----------|----------|-------------|
-| **Jupiter** | Jupiter V6 API | Swap aggregation, route optimization, price discovery | <200ms quotes |
-| **Jito** | Jito Block Engine | MEV protection, bundle submission, 8 regional endpoints | <50ms bundle |
-| **Token Data** | Solana RPC | SPL token accounts, supply, holders, balances | <100ms queries |
-| **Price Feed** | Jupiter + Birdeye | Multi-source aggregation, median calculation, streaming | <150ms prices |
-
-#### Advanced Features
-
-| Feature | Description | Complexity |
-|---------|-------------|------------|
-| **MEV Protection** | Sandwich attack prevention via Jito bundles | High |
-| **Arbitrage Detection** | Cross-DEX opportunity scanning | High |
-| **Portfolio Analytics** | Risk assessment and diversification scoring | Medium |
-| **Flash Loan Simulator** | Profitability analysis without execution | Medium |
-| **Yield Farming Finder** | APY discovery across protocols | Low |
-
-#### Quick Example
-
-```typescript
-import { JupiterIntegration, JitoIntegration, TokenDataIntegration } from '@synapse/client-sdk/defi';
-
-// Jupiter swap
-const jupiter = new JupiterIntegration(client);
-const quote = await jupiter.getQuote({
-  inputMint: 'So11111111111111111111111111111111111111112', // SOL
-  outputMint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
-  amount: 1_000_000_000, // 1 SOL
-  slippageBps: 50, // 0.5%
-});
-
-console.log('Quote:', {
-  inAmount: quote.inAmount,
-  outAmount: quote.outAmount,
-  priceImpact: quote.priceImpactPct,
-});
-
-// Jito MEV protection
-const jito = new JitoIntegration(client);
-const tipAccount = jito.getTipAccount('ny'); // New York region
-const bundle = await jito.submitBundle({
-  transactions: [signedTxBase64],
-  tipLamports: 1_000_000, // 0.001 SOL
-});
-
-console.log('Bundle ID:', bundle.bundleId);
-
-// Token data
-const tokenData = new TokenDataIntegration(client);
-const tokens = await tokenData.getTokenAccountsByOwner('YourWalletAddress');
-console.log('Token accounts:', tokens.length);
+SynapseClient
+ |
+ |-- .rpc        SolanaRpc          53 JSON-RPC methods (lazy-loaded)
+ |-- .das        DasClient          11 DAS/Metaplex Read API methods
+ |-- .ws         WsClient           WebSocket PubSub subscriptions
+ |-- .grpc       GrpcTransport      gRPC unary calls + Geyser parser
+ |
+ |-- call()      Raw JSON-RPC call
+ |-- batch()     Batched JSON-RPC calls
+ |-- destroy()   Tear down all connections
 ```
 
-**[Read Full Documentation →](./src/defi/README.md)**
-
----
-
-### 4. NFT Module
-
-**Location:** [`src/nft/`](./src/nft/README.md)
-
-Complete NFT toolkit for Solana with AI-powered features.
-
-#### Features Matrix
-
-| Feature | Description | Data Sources |
-|---------|-------------|--------------|
-| **Metadata Fetching** | NFT metadata parsing and validation | On-chain + Arweave/IPFS |
-| **Rarity Calculation** | Statistical rarity scoring algorithms | Collection traits |
-| **Collection Analytics** | Floor price, volume, trends | Magic Eden, Tensor, Solanart |
-| **Marketplace Aggregation** | Multi-marketplace listing aggregation | 5+ marketplaces |
-| **AI Recommendations** | ML-powered investment suggestions | Historical data + ML models |
+Sub-clients are initialized on first property access.
+If you never touch `client.grpc`, the gRPC module is never loaded.
 
-#### Quick Example
-
-```typescript
-import { NFTEngine, CollectionAnalytics, AIRarityCalculator } from '@synapse/client-sdk/nft';
-
-// Basic NFT operations
-const nft = new NFTEngine(client);
-const metadata = await nft.getNFTMetadata('mintAddress');
-console.log('NFT Name:', metadata.name);
-console.log('Attributes:', metadata.attributes);
-
-// Collection analytics
-const analytics = new CollectionAnalytics(client);
-const stats = await analytics.getCollectionStats('collectionMint');
-console.log('Floor price:', stats.floorPrice, 'SOL');
-console.log('24h volume:', stats.volume24h, 'SOL');
-console.log('Unique holders:', stats.uniqueHolders);
-
-// AI rarity calculation
-const rarityCalc = new AIRarityCalculator(client);
-const rarity = await rarityCalc.calculateRarity(metadata, 'collectionMint');
-console.log('Rarity score:', rarity.score);
-console.log('Rarity rank:', `${rarity.rank}/${rarity.totalSupply}`);
-console.log('Rarity tier:', rarity.tier); // 'common', 'rare', 'legendary', etc.
-```
-
-**[Read Full Documentation →](./src/nft/README.md)**
+All I/O flows through `HttpTransport` (`src/core/transport.ts`), which handles
+JSON-RPC framing, timeout, abort signals, and batch aggregation.
 
 ---
 
-### 5. AI Module
-
-**Location:** [`src/ai/`](./src/ai/README.md)
-
-OOBE Protocol implementation with Zero-Combine and PDA management.
-
-#### Components
-
-| Component | Purpose | Complexity |
-|-----------|---------|------------|
-| **PDA Manager** | Deterministic Program Derived Address generation | Low |
-| **Zero-Combine Fetcher** | Merkle proof reconstruction from on-chain data | High |
-| **Merkle Operations** | Proof generation, validation, and verification | Medium |
-| **OOBE Protocol** | AI agent integration for autonomous trading | High |
-
-#### Quick Example
-
-```typescript
-import { PDAManager, ZeroCombineFetcher, MerkleOperation } from '@synapse/client-sdk/ai';
-
-// PDA derivation
-const pdaManager = new PDAManager(client, walletAddress);
-const pdas = await pdaManager.deriveAllPDAs();
-console.log('User PDAs:', pdas);
-
-// Zero-Combine data fetching
-const fetcher = new ZeroCombineFetcher(client, walletAddress);
-const result = await fetcher.fetchAndReconstruct();
-console.log('Proof records:', result.tools.length);
-console.log('Merkle roots:', result.roots);
-
-// Merkle proof operations
-const merkle = new MerkleOperation();
-const leaves = [
-  { data: Buffer.from('data1'), index: 0 },
-  { data: Buffer.from('data2'), index: 1 },
-];
-const root = merkle.generateMerkleRoot(leaves);
-const proof = merkle.generateProof(leaves, 0);
-const isValid = merkle.verifyProof(proof, leaves[0].data, root);
-console.log('Proof valid:', isValid);
-```
-
-**[Read Full Documentation →](./src/ai/README.md)**
+## Module Reference
+
+### core/
+
+Foundation layer. No external dependencies.
+
+| File | Purpose |
+|------|---------|
+| `src/core/types.ts` | Branded primitive types: `Pubkey`, `Signature`, `Slot`, `Epoch`, `Lamports`, `UnixTimestamp`. RPC wire types, account shapes, transaction metadata, validator info, token amounts, filter types. |
+| `src/core/errors.ts` | Error hierarchy: `SynapseError` (base), `NetworkError`, `TimeoutError`, `RpcMethodNotFoundError`, `UpstreamError`. |
+| `src/core/transport.ts` | `HttpTransport` class -- JSON-RPC HTTP transport. `request()` for single calls, `batch()` for aggregated calls. |
+| `src/core/client.ts` | `SynapseClient` class -- top-level orchestrator. Lazy getters for `.rpc`, `.das`, `.ws`, `.grpc`. Static `fromEndpoint()` factory. |
+
+### rpc/
+
+53 Solana JSON-RPC methods. Each method lives in its own file under `src/rpc/methods/` for tree-shaking.
+
+| File | Purpose |
+|------|---------|
+| `src/rpc/solana-rpc.ts` | `SolanaRpc` facade class. Delegates to standalone functions. |
+| `src/rpc/methods/*.ts` | One file per RPC method. Each exports a typed async function and optional `Opts` interface. |
+| `src/rpc/methods/index.ts` | Barrel re-export. |
+
+Method categories:
+
+| Category | Methods |
+|----------|---------|
+| Account | `getAccountInfo`, `getBalance`, `getMultipleAccounts`, `getProgramAccounts` |
+| Block | `getBlock`, `getBlockHeight`, `getBlockTime`, `getBlockProduction`, `getBlocks`, `getBlocksWithLimit`, `getBlockCommitment` |
+| Transaction | `getTransaction`, `getSignaturesForAddress`, `getSignatureStatuses`, `sendTransaction`, `simulateTransaction`, `requestAirdrop` |
+| Blockhash | `getLatestBlockhash`, `isBlockhashValid` |
+| Cluster / Epoch | `getSlot`, `getSlotLeader`, `getSlotLeaders`, `getEpochInfo`, `getEpochSchedule`, `getInflationGovernor`, `getInflationRate`, `getInflationReward`, `getVoteAccounts`, `getClusterNodes`, `getSupply`, `getRecentPerformanceSamples`, `getHealth`, `getVersion`, `getGenesisHash`, `getIdentity`, `getMinimumBalanceForRentExemption`, `minimumLedgerSlot`, `getFirstAvailableBlock`, `getHighestSnapshotSlot`, `getLeaderSchedule`, `getMaxRetransmitSlot`, `getMaxShredInsertSlot`, `getTransactionCount`, `getStakeMinimumDelegation`, `getRecentPrioritizationFees` |
+| Token | `getTokenAccountBalance`, `getTokenAccountsByOwner`, `getTokenAccountsByDelegate`, `getTokenLargestAccounts`, `getTokenSupply`, `getLargestAccounts`, `getStakeActivation` (deprecated), `getFeeForMessage` |
+
+### das/
+
+11 DAS (Digital Asset Standard) methods for NFT/cNFT via the Metaplex Read API.
+
+| File | Purpose |
+|------|---------|
+| `src/das/types.ts` | DAS type definitions: `DasAsset`, `DasContent`, `DasCompression`, `DasOwnership`, `DasProof`, `DasPage`, `DasSearchParams`, and 10+ supporting interfaces. |
+| `src/das/client.ts` | `DasClient` facade class. |
+| `src/das/methods/*.ts` | `getAsset`, `getAssetProof`, `getAssetBatch`, `getAssetProofBatch`, `getAssetsByOwner`, `getAssetsByGroup`, `getAssetsByCreator`, `getAssetsByAuthority`, `searchAssets`, `getSignaturesForAsset`, `getTokenAccounts`. |
+
+### websocket/
+
+Real-time Solana PubSub over WebSocket.
+
+| File | Purpose |
+|------|---------|
+| `src/websocket/types.ts` | `WsConfig`, subscription parameter interfaces, notification types, `WsNotification` union. |
+| `src/websocket/client.ts` | `WsClient` class. Methods: `onAccountChange`, `onProgramAccountChange`, `onLogs`, `onSignature`, `onSlotChange`, `onRootChange`, `unsubscribe`, `close`. |
+
+### grpc/
+
+Optional gRPC transport and Geyser streaming parser.
+Requires `@grpc/grpc-js` and `@grpc/proto-loader` as optional peer dependencies.
+
+| File | Purpose |
+|------|---------|
+| `src/grpc/types.ts` | `GrpcTransportConfig`, `GrpcCallOptions`, `UnaryMethod`. |
+| `src/grpc/transport.ts` | `GrpcTransport` class. Lazy proto loading, service resolution, typed unary calls. |
+| `src/grpc/parser/types.ts` | Raw Geyser gRPC protobuf shapes and parsed output types (20+ interfaces). |
+| `src/grpc/parser/programs.ts` | Known-program registry (80+ programs). `resolveProgram`, `resolveProgramBatch`, `isProgramInCategory`. |
+| `src/grpc/parser/decoder.ts` | Low-level decoders: `decodeTransaction`, `decodeAccountUpdate`, `decodeSlotUpdate`, `decodeBlockMeta`, `decodeEntry`, and balance/token-balance diff utilities. |
+| `src/grpc/parser/geyser-parser.ts` | `GeyserParser` class. High-level stream parsing with event emitter, statistics tracking, batch processing, and configurable filters (skip votes, skip zero balances). |
+
+### ai/
+
+AI agent commerce layer. Zod schemas, LangChain tools, protocol integrations, gateway, x402.
+
+| File | Purpose |
+|------|---------|
+| `src/ai/tools/zod/types.ts` | `AgentMethodDef` interface -- Zod input/output schema pair. |
+| `src/ai/tools/zod/index.ts` | `agentRpcMethods` registry (53 method schemas) and `createExecutableSolanaTools()` factory. |
+| `src/ai/tools/protocols/shared.ts` | `ProtocolHttpClient`, `createMethodRegistry`, `buildProtocolTools` -- shared protocol infrastructure. |
+| `src/ai/tools/protocols/jupiter/` | Jupiter DEX: 21 methods (swap, quote, route, limit orders, DCA, token list, price). Schemas in `schemas.ts`, tool factory in `tools.ts`. |
+| `src/ai/tools/protocols/raydium/` | Raydium DEX: 16 methods (pools, liquidity, farming, swaps, CLMM). |
+| `src/ai/tools/protocols/metaplex/` | Metaplex NFT: 12 methods (DAS queries, resolve collection). |
+| `src/ai/tools/protocols/index.ts` | `createProtocolTools()` super-factory -- creates all protocol toolkits in one call. |
+| `src/ai/gateway/types.ts` | Gateway type definitions: `PaymentIntent`, `PricingTier`, `ToolListing`, `SessionReceipt`, events. |
+| `src/ai/gateway/session.ts` | `AgentSession` -- budget tracking, rate limiting, TTL enforcement, call counting. |
+| `src/ai/gateway/pricing.ts` | `PricingEngine` -- tier resolution, dynamic congestion pricing, bundle discounts. |
+| `src/ai/gateway/validator.ts` | `ResponseValidator` -- SHA-256 attestation, integrity verification, attestation log. |
+| `src/ai/gateway/marketplace.ts` | `ToolMarketplace` -- listing, search, filtering, reputation scoring, bundle registry. |
+| `src/ai/gateway/index.ts` | `AgentGateway` class -- session lifecycle, execution pipeline, settlement, event system. |
+| `src/ai/gateway/x402/types.ts` | x402 protocol types: `PaymentRequirements`, `PaymentPayload`, `SettlementResult`, network constants. |
+| `src/ai/gateway/x402/paywall.ts` | `X402Paywall` -- seller-side HTTP 402 middleware. |
+| `src/ai/gateway/x402/client.ts` | `X402BuyerClient` -- buyer-side payment header construction. |
+| `src/ai/gateway/x402/facilitator.ts` | `FacilitatorClient` -- on-chain settlement verification. |
+| `src/ai/gateway/x402/registry.ts` | `FACILITATOR_REGISTRY` -- pre-configured endpoints for known facilitators (PayAI, Dexter, RelAI, CDP). |
+
+### utils/
+
+| File | Purpose |
+|------|---------|
+| `src/utils/helpers.ts` | `lamportsToSol`, `solToLamports`, `isValidPubkey`, `isValidSignature`, `sleep`, `chunk`, `retry`. |
+| `src/utils/synapse.ts` | `SynapseNetwork`, `SynapseRegion` enums, `resolveEndpoint`, `probeLatency`, `autoSelectRegion`, pre-resolved constants (`SYNAPSE_MAINNET_US`, etc.). |
 
 ---
 
-### 6. Analytics Engine Module
+## Endpoints and Regions
 
-**Location:** [`src/analytics/`](./src/analytics/README.md)
+The SDK ships with a typed endpoint registry. Each endpoint includes `rpc`, `wss`, and `grpc` URLs.
 
-Real-time metrics collection with AI-powered predictions.
+```ts
+import {
+  SynapseNetwork,
+  SynapseRegion,
+  resolveEndpoint,
+  autoSelectRegion,
+} from '@oobe-protocol-labs/synapse-client-sdk';
 
-#### Capabilities
+// Explicit resolution
+const ep = resolveEndpoint(SynapseNetwork.Mainnet, SynapseRegion.EU);
+// ep.rpc  -> 'https://mainnet.eu.synapse.com'
+// ep.wss  -> 'wss://mainnet.eu.synapse.com/ws'
+// ep.grpc -> 'https://mainnet.eu.synapse.com:443'
 
-| Category | Metrics | Analysis |
-|----------|---------|----------|
-| **Performance** | Requests/s, latency, throughput, error rate | Trend analysis, outlier detection |
-| **Predictions** | Latency forecast, load prediction, error probability | ML-based time series |
-| **Anomalies** | Spike detection, degradation alerts, pattern changes | Statistical anomaly detection |
-| **Optimization** | Bottleneck identification, resource recommendations | Rule-based + ML insights |
+// Latency-based auto-selection
+const best = await autoSelectRegion(SynapseNetwork.Mainnet);
+console.log(best.region, best.latencyMs);
+```
 
-#### Quick Example
+Available combinations:
 
-```typescript
-import { AnalyticsEngine } from '@synapse/client-sdk/analytics';
+| Network | Regions |
+|---------|---------|
+| `Mainnet` | US, EU |
+| `Devnet` | US, EU |
+| `Testnet` | US, EU |
 
-const analytics = new AnalyticsEngine({
-  enablePredictions: true,
-  enableAnomalyDetection: true,
-  enableTrendAnalysis: true,
-  sampleRate: 0.1, // 10% sampling
-  retentionDays: 7,
-  alertThresholds: {
-    errorRate: 0.05, // 5%
-    latency: 1000, // 1s
-    volumeSpike: 5, // 5x normal
-  },
-});
+---
 
-// Record metrics
-analytics.recordMetrics({
-  timestamp: Date.now(),
-  requests: 1000,
-  errors: 10,
-  latency: 150,
-  throughput: 200,
-  activeUsers: 50,
-  gasUsed: 1_000_000,
-  blockHeight: 250_000_000,
-});
+## Branded Types
 
-// Get predictions
-const predictions = await analytics.generatePredictions();
-predictions.forEach(pred => {
-  console.log(`${pred.metric} prediction:`, {
-    current: pred.currentValue,
-    predicted: pred.predictedValue,
-    confidence: (pred.confidence * 100).toFixed(1) + '%',
-    trend: pred.trend,
-  });
-});
+The SDK uses branded types for compile-time safety. Primitive values are
+wrapped at construction and the brand is erased at runtime (zero overhead).
 
-// Detect anomalies
-const anomalies = analytics.detectAnomalies();
-anomalies.forEach(anomaly => {
-  console.log(`Anomaly detected: ${anomaly.metric}`, {
-    value: anomaly.value,
-    severity: anomaly.severity,
-    description: anomaly.description,
-  });
-});
+```ts
+import { Pubkey, Signature, Slot, Lamports } from '@oobe-protocol-labs/synapse-client-sdk';
 
-// Get optimization suggestions
-const suggestions = analytics.getOptimizationSuggestions();
-suggestions.forEach(suggestion => {
-  console.log(`${suggestion.category}: ${suggestion.suggestion}`);
-  console.log(`Expected impact: ${suggestion.impact}`);
-});
+const pk = Pubkey('So11111111111111111111111111111111'); // branded string
+const sig = Signature('5vR3z...');                       // branded string
+const slot = Slot(12345678);                             // branded number
+const lam = Lamports(1_000_000_000);                     // branded number
 ```
 
-**[Read Full Documentation →](./src/analytics/README.md)**
+Passing a raw `string` where `Pubkey` is expected is a compile-time error.
 
 ---
 
-### 7. RPC Methods Module
-
-**Location:** [`src/methods/`](./src/methods/README.md)
+## AI Agent Integration
 
-Type-safe wrapper for 70+ Solana RPC methods.
+### Zod Schemas and LangChain Tools
 
-#### Method Categories
+Every RPC method has a corresponding Zod input/output schema. These schemas
+are used to generate LangChain `DynamicStructuredTool` instances:
 
-| Category | Methods | Description |
-|----------|---------|-------------|
-| **Account** | getAccountInfo, getBalance, getMultipleAccounts, getProgramAccounts | Account data retrieval |
-| **Block** | getBlock, getBlockHeight, getBlockTime, getBlocks, getBlockCommitment | Block information |
-| **Transaction** | getTransaction, getSignatureStatuses, sendTransaction, simulateTransaction | Transaction operations |
-| **Network** | getClusterNodes, getEpochInfo, getVersion, getHealth | Network status |
-| **Token** | getTokenAccountBalance, getTokenSupply, getTokenAccountsByOwner, getTokenLargestAccounts | SPL Token operations |
+```ts
+import { createExecutableSolanaTools } from '@oobe-protocol-labs/synapse-client-sdk';
 
-#### Quick Example
-
-```typescript
-import { SolanaRpcMethods } from '@synapse/client-sdk/methods';
+const transport = new HttpTransport({ endpoint: '...' });
+const { tools, toolMap } = createExecutableSolanaTools(transport);
+// tools: DynamicStructuredTool[] (53 tools, prefixed "solana_")
+// toolMap: Map<string, DynamicStructuredTool>
+```
 
-const rpc = new SolanaRpcMethods(client);
+Options:
+- `prefix` -- custom tool name prefix (default: `"solana_"`)
+- `include` -- whitelist of method names
+- `exclude` -- blacklist of method names
 
-// Account methods
-const accountInfo = await rpc.getAccountInfo('address', {
-  encoding: 'jsonParsed',
-  commitment: 'confirmed',
-});
+### Protocol Tools
 
-const balance = await rpc.getBalance('address', 'confirmed');
-console.log('Balance:', balance / 1e9, 'SOL');
+49 additional tools for on-chain protocols:
 
-// Block methods
-const blockHeight = await rpc.getBlockHeight('finalized');
-const block = await rpc.getBlock(blockHeight, {
-  encoding: 'jsonParsed',
-  transactionDetails: 'full',
-  rewards: true,
-  maxSupportedTransactionVersion: 0,
-});
+```ts
+import { createProtocolTools } from '@oobe-protocol-labs/synapse-client-sdk';
 
-// Transaction methods
-const signature = await rpc.sendTransaction(signedTxBase64, {
-  skipPreflight: false,
-  preflightCommitment: 'confirmed',
-  maxRetries: 3,
+const { jupiter, raydium, metaplex, allTools } = createProtocolTools({
+  jupiter: { apiKey: '...' },
+  raydium: true,
+  metaplex: { transport },
 });
-
-const statuses = await rpc.getSignatureStatuses([signature]);
-console.log('Transaction status:', statuses[0]);
-
-// Token methods
-const tokenAccounts = await rpc.getTokenAccountsByOwner(
-  'ownerAddress',
-  { programId: 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA' },
-  { encoding: 'jsonParsed' }
-);
-
-const tokenSupply = await rpc.getTokenSupply('mintAddress');
-console.log('Total supply:', tokenSupply.value.uiAmount);
+// allTools: DynamicStructuredTool[] (49 tools)
 ```
 
-**[Read Full Documentation →](./src/methods/README.md)**
-
----
-
-### 8. Utils Module
+| Protocol | Tool Count | Categories |
+|----------|-----------|------------|
+| Jupiter | 21 | Ultra Swap, Metis Swap, Quote, Route, Limit Orders, DCA, Token List, Price API |
+| Raydium | 16 | Pools, Liquidity, Farming, Swaps, CLMM Positions, Token Info |
+| Metaplex | 12 | DAS Queries (asset, proof, owner, group, creator, authority, search), Resolve Collection |
 
-**Location:** [`src/utils/`](./src/utils/README.md)
+### Agent Commerce Gateway
 
-Utility functions and constants for common operations.
+Session-based metering and payment infrastructure for monetized AI tool access:
 
-#### Components
+```ts
+import { AgentGateway, createAgentGateway } from '@oobe-protocol-labs/synapse-client-sdk';
 
-```typescript
-// Constants
-import { SynapseConstants } from '@synapse/client-sdk/utils';
+const gw = createAgentGateway({ transport, seller: Pubkey('...') });
 
-console.log('Base URL:', SynapseConstants.BASE_URL);
-console.log('WebSocket URL:', SynapseConstants.WEBSOCKET_URL);
-console.log('Default timeout:', SynapseConstants.DEFAULT_TIMEOUT);
+const session = await gw.openSession(paymentIntent);
+const result = await gw.execute(session.id, 'getBalance', [pubkey]);
+const receipt = await gw.settleSession(session.id);
+```
 
-// Helpers
-import { SynapseUtils } from '@synapse/client-sdk/utils';
+Components:
+- `AgentSession` -- budget tracking, rate limiting, TTL enforcement
+- `PricingEngine` -- tier resolution, dynamic pricing, bundle discounts
+- `ResponseValidator` -- SHA-256 attestation, integrity proofs
+- `ToolMarketplace` -- listing, discovery, reputation scoring
 
-// Format lamports to SOL
-const sol = SynapseUtils.lamportsToSol(1_000_000_000);
-console.log('Amount:', sol, 'SOL'); // 1 SOL
+### x402 Payment Protocol
 
-// Parse SOL to lamports
-const lamports = SynapseUtils.solToLamports(1.5);
-console.log('Lamports:', lamports); // 1500000000
+Native HTTP 402 payment flow (v1/v2):
 
-// Validate Solana address
-const isValid = SynapseUtils.isValidAddress('EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v');
-console.log('Valid address:', isValid); // true
+```ts
+// Seller side
+import { X402Paywall } from '@oobe-protocol-labs/synapse-client-sdk';
+const paywall = new X402Paywall(config);
+const result = await paywall.processRequest(request);
 
-// Format transaction signature
-const shortSig = SynapseUtils.shortenSignature('5j7s6N...', 8);
-console.log('Short signature:', shortSig); // 5j7s6N...(shortened)
+// Buyer side
+import { X402BuyerClient } from '@oobe-protocol-labs/synapse-client-sdk';
+const buyer = new X402BuyerClient(config);
+const response = await buyer.payAndRetry(url, options);
 ```
 
-**[Read Full Documentation →](./src/utils/README.md)**
-
----
-
-## Performance Benchmarks
-
-### Latency Metrics
-
-| Operation | P50 | P95 | P99 | Throughput |
-|-----------|-----|-----|-----|------------|
-| Single RPC call (cached) | <1ms | <2ms | <5ms | 1M req/s |
-| Single RPC call (uncached) | 8ms | 15ms | 25ms | 10k req/s |
-| Batch RPC call (10 calls) | 25ms | 45ms | 80ms | 5k batch/s |
-| WebSocket message delivery | <1ms | <3ms | <10ms | 100k msg/s |
-| Cache hit (L1) | <0.5ms | <1ms | <2ms | 1M ops/s |
-| Cache hit (L2) | <1ms | <2ms | <5ms | 500k ops/s |
-| Cache hit (L3 Redis) | 2ms | 8ms | 15ms | 50k ops/s |
-| Jupiter swap quote | 150ms | 250ms | 400ms | 500 req/s |
-| NFT metadata fetch (cached) | 5ms | 15ms | 30ms | 10k req/s |
-| Circuit breaker overhead | <0.1ms | <0.5ms | <1ms | 1M ops/s |
+Known facilitator registry:
 
-### Load Testing Results
+```ts
+import {
+  KnownFacilitator,
+  resolveKnownFacilitator,
+  findFacilitatorsByNetwork,
+} from '@oobe-protocol-labs/synapse-client-sdk';
 
-```
-Test Configuration:
-- Duration: 5 minutes
-- Concurrent users: 1000
-- RPC endpoints: 3 (load balanced)
-- Operations: Mixed (50% reads, 30% writes, 20% batch)
-
-Results:
-✓ Total requests: 3,315,000
-✓ Successful: 3,312,450 (99.92%)
-✓ Failed: 2,550 (0.08%)
-✓ Average RPS: 11,050
-✓ Peak RPS: 15,230
-✓ Average latency: 12.5ms
-✓ P95 latency: 28ms
-✓ P99 latency: 45ms
-✓ Cache hit rate: 94.3%
-✓ Circuit breaker trips: 3
-✓ Endpoint failovers: 12
+const config = resolveKnownFacilitator(KnownFacilitator.PayAI);
+const solanaFacilitators = findFacilitatorsByNetwork('solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp');
 ```
 
 ---
 
-## Type System
-
-### Core Types
+## Testing
 
-```typescript
-// Client configuration
-export interface SynapseConfig {
-  endpoint: string | string[];
-  apiKey?: string;
-  timeout?: number;
-  debug?: boolean;
-}
-
-// RPC request/response
-export interface RpcRequest {
-  jsonrpc: '2.0';
-  id: number | string;
-  method: string;
-  params?: any[];
-}
-
-export interface RpcResponse<T = any> {
-  jsonrpc: '2.0';
-  id: number | string;
-  result?: T;
-  error?: RpcError;
-}
-
-export interface RpcError {
-  code: number;
-  message: string;
-  data?: any;
-}
+The project uses [Vitest](https://vitest.dev/) with 378 tests across 10 suites.
 
-// Request options
-export interface RequestOptions {
-  commitment?: 'processed' | 'confirmed' | 'finalized';
-  encoding?: 'base58' | 'base64' | 'base64+zstd' | 'jsonParsed';
-  maxSupportedTransactionVersion?: number;
-  skipPreflight?: boolean;
-  preflightCommitment?: 'processed' | 'confirmed' | 'finalized';
-}
+```bash
+# Run all tests
+pnpm test
 
-// Client statistics
-export interface ClientStats {
-  requestCount: number;
-  errorCount: number;
-  averageLatency: number;
-  cacheHitRate: number;
-  uptime: number;
-  activeConnections: number;
-  pendingRequests: number;
-}
+# Watch mode
+pnpm test:watch
 
-// Account info
-export interface AccountInfo {
-  lamports: number;
-  owner: string;
-  data: Buffer | string | any;
-  executable: boolean;
-  rentEpoch: number;
-}
+# Coverage
+pnpm test:coverage
 ```
 
-### Error Types
-
-```typescript
-export class SynapseError extends Error {
-  constructor(
-    message: string,
-    public code?: number,
-    public data?: any
-  ) {
-    super(message);
-    this.name = 'SynapseError';
-  }
-}
-
-export class NetworkError extends SynapseError {
-  constructor(
-    message: string,
-    public statusCode?: number
-  ) {
-    super(message, -32000);
-    this.name = 'NetworkError';
-  }
-}
-
-export class TimeoutError extends SynapseError {
-  constructor(message: string) {
-    super(message, -32001);
-    this.name = 'TimeoutError';
-  }
-}
+Test suites:
 
-export class ValidationError extends SynapseError {
-  constructor(
-    message: string,
-    public field?: string
-  ) {
-    super(message, -32602);
-    this.name = 'ValidationError';
-  }
-}
-
-export class CircuitBreakerError extends SynapseError {
-  constructor(message: string) {
-    super(message, -32003);
-    this.name = 'CircuitBreakerError';
-  }
-}
-```
+| Suite | File | Covers |
+|-------|------|--------|
+| Endpoints | `tests/utils/endpoints.test.ts` | Network/region resolution, auto-select, constants |
+| gRPC Parser | `tests/grpc/parser.test.ts` | Decoders, program registry, GeyserParser class |
+| Session | `tests/ai/session.test.ts` | Budget, rate limits, TTL, pause/resume, events |
+| Gateway | `tests/ai/gateway.test.ts` | Full session lifecycle, execute, settle, metrics |
+| x402 | `tests/ai/x402.test.ts` | Paywall, facilitator, registry, header encoding |
+| Validator | `tests/ai/validator.test.ts` | Attestation, integrity, signature verification |
+| Marketplace | `tests/ai/marketplace.test.ts` | Listing, search, reputation, bundles |
+| Pricing | `tests/ai/pricing.test.ts` | Tiers, dynamic pricing, cost estimation |
+| Protocols | `tests/ai/protocols.test.ts` | Jupiter/Raydium/Metaplex schemas and tools |
+| Tools | `tests/ai/tools.test.ts` | Zod registry, executable tool creation, execution |
 
 ---
 
-## Best Practices
-
-### 1. Connection Management
-
-```typescript
-// ✅ Recommended: Singleton pattern
-class SynapseService {
-  private static instance: SynapseClient;
-  
-  static getInstance(): SynapseClient {
-    if (!this.instance) {
-      this.instance = new SynapseClient({
-        endpoint: process.env.SYNAPSE_ENDPOINT!,
-        apiKey: process.env.SYNAPSE_API_KEY,
-        timeout: 30000,
-      });
-    }
-    return this.instance;
-  }
-}
-
-// Usage
-const client = SynapseService.getInstance();
-
-// ❌ Not recommended: New client per request
-function getBalance(address: string) {
-  const client = new SynapseClient({ endpoint: '...' }); // Avoid this
-  return client.call('getBalance', [address]);
-}
-```
-
-### 2. Error Handling
-
-```typescript
-import { SynapseError, NetworkError, TimeoutError } from '@synapse/client-sdk';
-
-async function robustRpcCall<T>(
-  method: string,
-  params: any[],
-  maxRetries: number = 3
-): Promise<T> {
-  for (let attempt = 1; attempt <= maxRetries; attempt++) {
-    try {
-      return await client.call<T>(method, params);
-    } catch (error) {
-      if (error instanceof TimeoutError) {
-        console.warn(`Timeout on attempt ${attempt}/${maxRetries}`);
-        if (attempt === maxRetries) throw error;
-        await sleep(1000 * attempt); // Exponential backoff
-      } else if (error instanceof NetworkError) {
-        console.error('Network error:', error.statusCode, error.message);
-        if (attempt === maxRetries) throw error;
-        await sleep(2000 * attempt);
-      } else if (error instanceof SynapseError) {
-        console.error('RPC error:', error.code, error.message);
-        throw error; // Don't retry RPC errors
-      } else {
-        throw error; // Unknown error
-      }
-    }
-  }
-  throw new Error('Max retries exceeded');
-}
-```
-
-### 3. Batch Operations
-
-```typescript
-// ✅ Efficient: Batch related calls
-const [balance1, balance2, balance3, accountInfo] = await Promise.all([
-  client.call('getBalance', ['address1']),
-  client.call('getBalance', ['address2']),
-  client.call('getBalance', ['address3']),
-  client.call('getAccountInfo', ['address4']),
-]);
-
-// Or use batch method
-const results = await client.batch([
-  { method: 'getBalance', params: ['address1'] },
-  { method: 'getBalance', params: ['address2'] },
-  { method: 'getBalance', params: ['address3'] },
-  { method: 'getAccountInfo', params: ['address4'] },
-]);
-
-// ❌ Inefficient: Sequential calls
-const balance1 = await client.call('getBalance', ['address1']);
-const balance2 = await client.call('getBalance', ['address2']);
-const balance3 = await client.call('getBalance', ['address3']);
-```
-
-### 4. Caching Strategy
+## Build and Development
 
-```typescript
-import { SmartCaching } from '@synapse/client-sdk/advanced';
+```bash
+# Type-check (no emit)
+pnpm typecheck
 
-const cache = new SmartCaching({
-  maxSize: 10000,
-  enableL2: true,
-  enablePredictive: true,
-});
+# Build CJS + ESM + docs
+pnpm build
 
-async function getAccountInfoCached(address: string): Promise<AccountInfo> {
-  const cacheKey = `account:${address}`;
-  
-  // Check cache first
-  const cached = await cache.get<AccountInfo>(cacheKey);
-  if (cached) return cached;
-  
-  // Fetch from RPC
-  const accountInfo = await client.call<AccountInfo>('getAccountInfo', [address]);
-  
-  // Store in cache with appropriate TTL
-  await cache.set(cacheKey, accountInfo, {
-    ttl: 60000, // 1 minute for account data
-    compress: true,
-    tags: [`user:${address}`],
-  });
-  
-  return accountInfo;
-}
+# Watch mode (TypeScript)
+pnpm dev
 
-// Different TTL strategies
-const TTL_STRATEGIES = {
-  static: 3600000,      // 1 hour (e.g., token metadata)
-  semi_dynamic: 300000, // 5 minutes (e.g., token prices)
-  dynamic: 60000,       // 1 minute (e.g., account balances)
-  realtime: 5000,       // 5 seconds (e.g., slot info)
-};
+# Lint
+pnpm lint
+pnpm lint:check
 ```
 
-### 5. Circuit Breaker Integration
+The build pipeline:
 
-```typescript
-import { CircuitBreaker } from '@synapse/client-sdk/advanced';
+1. `tsc -p tsconfig.cjs.json` -- compile to `dist/cjs/` (CommonJS)
+2. `tsc -p tsconfig.esm.json` -- compile to `dist/esm/` (ES Modules)
+3. `scripts/fix-esm-imports.mjs` -- append `.js` extensions to ESM imports
+4. `typedoc` -- generate API reference in `dist/docs/`
 
-const breaker = new CircuitBreaker({
-  failureThreshold: 5,
-  timeout: 60000,
-  retryInterval: 30000,
-  enableFallback: true,
-});
+Output structure:
 
-async function protectedRpcCall<T>(
-  method: string,
-  params: any[]
-): Promise<T> {
-  return await breaker.execute(
-    // Primary operation
-    async () => {
-      return await client.call<T>(method, params);
-    },
-    // Fallback operation
-    async () => {
-      // Try cache
-      const cacheKey = `${method}:${JSON.stringify(params)}`;
-      const cached = await cache.get<T>(cacheKey, { allowStale: true });
-      
-      if (cached) {
-        console.warn('Using stale cache due to circuit breaker open');
-        return cached;
-      }
-      
-      throw new CircuitBreakerError('Circuit breaker open and no fallback available');
-    }
-  );
-}
 ```
-
-### 6. Monitoring and Observability
-
-```typescript
-// Metrics collection
-setInterval(() => {
-  const stats = client.getStats();
-  
-  // Log metrics
-  console.log('Client Metrics:', {
-    rps: (stats.requestCount / ((Date.now() - stats.uptime) / 1000)).toFixed(2),
-    errorRate: ((stats.errorCount / stats.requestCount) * 100).toFixed(2) + '%',
-    avgLatency: stats.averageLatency.toFixed(2) + 'ms',
-    cacheHitRate: (stats.cacheHitRate * 100).toFixed(2) + '%',
-  });
-  
-  // Alert on anomalies
-  if (stats.averageLatency > 1000) {
-    console.warn('High latency detected:', stats.averageLatency);
-  }
-  
-  if (stats.errorCount / stats.requestCount > 0.05) {
-    console.error('High error rate:', ((stats.errorCount / stats.requestCount) * 100).toFixed(2) + '%');
-  }
-}, 60000); // Every minute
-
-// Event-based monitoring
-client.on('error', (error) => {
-  // Send to monitoring service
-  sendToMonitoring({
-    type: 'rpc_error',
-    error: error.message,
-    code: error.code,
-    timestamp: Date.now(),
-  });
-});
-
-client.on('endpoint-rotate', ({ reason }) => {
-  // Track endpoint health
-  metrics.increment('endpoint.rotation', { reason });
-});
-```
-
----
-
-## Environment Variables
-
-```bash
-# Required
-SYNAPSE_ENDPOINT=https://your-synapse-gateway.com
-SYNAPSE_WS_ENDPOINT=wss://your-synapse-gateway.com
-SYNAPSE_API_KEY=your_api_key_here
-
-# Optional - Client Configuration
-SYNAPSE_TIMEOUT=30000
-SYNAPSE_DEBUG=false
-SYNAPSE_MAX_RETRIES=3
-SYNAPSE_RETRY_DELAY=1000
-
-# Optional - Advanced Features
-SYNAPSE_ENABLE_CACHE=true
-SYNAPSE_CACHE_SIZE=10000
-SYNAPSE_ENABLE_CIRCUIT_BREAKER=true
-SYNAPSE_CIRCUIT_BREAKER_THRESHOLD=5
-
-# Optional - WebSocket Configuration
-SYNAPSE_WS_AUTO_RECONNECT=true
-SYNAPSE_WS_MAX_RECONNECT_ATTEMPTS=10
-SYNAPSE_WS_RECONNECT_DELAY=5000
-SYNAPSE_WS_HEARTBEAT_INTERVAL=30000
-
-# Optional - Redis (for L3 cache)
-SYNAPSE_REDIS_URL=redis://localhost:6379
-SYNAPSE_REDIS_PASSWORD=your_redis_password
-
-# Optional - Analytics
-SYNAPSE_ENABLE_ANALYTICS=true
-SYNAPSE_ANALYTICS_SAMPLE_RATE=0.1
-SYNAPSE_ANALYTICS_RETENTION_DAYS=7
+dist/
+  cjs/       CommonJS build
+  esm/       ES Module build
+  docs/      TypeDoc HTML reference
 ```
 
 ---
 
-## System Requirements
+## Package Exports
 
-### Runtime Requirements
-
-| Component | Minimum | Recommended | Notes |
-|-----------|---------|-------------|-------|
-| **Node.js** | 18.0.0 | 20.x LTS | ESM support required |
-| **TypeScript** | 5.0.0 | 5.3.x | For development only |
-| **Memory** | 512MB | 2GB | Per instance |
-| **CPU** | 2 cores | 4+ cores | For optimal throughput |
-| **Network** | 10 Mbps | 100 Mbps | Stable connection |
-
-### Dependencies
+The package exposes granular entry points for consumers that need only a subset:
 
 ```json
 {
-  "dependencies": {
-    "@solana/web3.js": "^1.87.0",
-    "eventemitter3": "^5.0.1",
-    "lru-cache": "^10.0.0",
-    "ws": "^8.14.0"
-  },
-  "devDependencies": {
-    "typescript": "^5.3.0",
-    "@types/node": "^20.0.0",
-    "@types/ws": "^8.5.0"
-  }
+  ".":            "Full SDK",
+  "./core":       "SynapseClient class only",
+  "./core/types": "Branded types and RPC type definitions",
+  "./rpc":        "SolanaRpc facade + all 53 method functions",
+  "./grpc":       "GrpcTransport + Geyser parser",
+  "./das":        "DasClient + 11 DAS method functions",
+  "./websocket":  "WsClient + subscription types",
+  "./utils":      "Helpers + endpoint resolution"
 }
 ```
 
-### Browser Support
-
-| Browser | Minimum Version | Notes |
-|---------|----------------|-------|
-| Chrome | 90+ | Full support |
-| Firefox | 88+ | Full support |
-| Safari | 14+ | WebSocket compression may be limited |
-| Edge | 90+ | Full support |
-
----
-
-## Migration Guide
-
-### From v1.x to v2.x
-
-Version 2.0 introduces breaking changes for improved performance and type safety.
+Import examples:
 
-#### 1. Client Initialization
+```ts
+// Full SDK
+import { SynapseClient } from '@oobe-protocol-labs/synapse-client-sdk';
 
-```typescript
-// v1.x
-const client = new SynapseClient('https://endpoint.com', 'api-key');
+// Types only (zero runtime)
+import type { Pubkey, Signature, AccountInfo } from '@oobe-protocol-labs/synapse-client-sdk/core/types';
 
-// v2.x
-const client = new SynapseClient({
-  endpoint: 'https://endpoint.com',
-  apiKey: 'api-key',
-});
-```
-
-#### 2. RPC Method Calls
+// Individual RPC method (tree-shakeable)
+import { getBalance } from '@oobe-protocol-labs/synapse-client-sdk/rpc';
 
-```typescript
-// v1.x
-const balance = await client.getBalance('address');
-const accountInfo = await client.getAccountInfo('address');
-
-// v2.x
-const balance = await client.call('getBalance', ['address']);
-const accountInfo = await client.call('getAccountInfo', ['address', { encoding: 'jsonParsed' }]);
-
-// Or use SolanaRpcMethods wrapper
-import { SolanaRpcMethods } from '@synapse/client-sdk/methods';
-const rpc = new SolanaRpcMethods(client);
-const balance = await rpc.getBalance('address');
-const accountInfo = await rpc.getAccountInfo('address', { encoding: 'jsonParsed' });
-```
-
-#### 3. Error Handling
-
-```typescript
-// v1.x
-catch (error) {
-  if (error.code === -32602) {
-    // Handle validation error
-  }
-}
-
-// v2.x
-import { SynapseError, ValidationError, NetworkError } from '@synapse/client-sdk';
-
-catch (error) {
-  if (error instanceof ValidationError) {
-    console.error('Validation error:', error.field, error.message);
-  } else if (error instanceof NetworkError) {
-    console.error('Network error:', error.statusCode, error.message);
-  } else if (error instanceof SynapseError) {
-    console.error('Synapse error:', error.code, error.message);
-  }
-}
-```
-
-#### 4. WebSocket Subscriptions
-
-```typescript
-// v1.x
-ws.accountSubscribe('address', (data) => {
-  console.log(data);
-});
-
-// v2.x
-const subId = await ws.accountSubscribe(
-  'address',
-  (data) => {
-    console.log(data);
-  },
-  {
-    commitment: 'confirmed',
-    encoding: 'jsonParsed',
-  }
-);
-
-// Remember to unsubscribe
-await ws.accountUnsubscribe(subId);
+// WebSocket only
+import { WsClient } from '@oobe-protocol-labs/synapse-client-sdk/websocket';
 ```
 
 ---
 
-## Troubleshooting
+## Documentation
 
-### Common Issues
+| Resource | Location |
+|----------|----------|
+| TypeDoc API reference | `docs/` (HTML, auto-generated) |
+| Changelog | [CHANGELOG.md](./CHANGELOG.md) |
+| Contributing guide | [CONTRIBUTING.md](./CONTRIBUTING.md) |
+| AI skill guides | `src/ai/skills/` (10 markdown files) |
+| Example scripts | `examples/` |
 
-#### 1. High Latency
+Skill guides (in `src/ai/skills/`):
 
-**Symptoms:** Requests taking >1s to complete
+| File | Topic |
+|------|-------|
+| `01-langchain-tools.md` | Creating and using LangChain tools |
+| `02-gateway-sessions.md` | Session lifecycle and management |
+| `03-pricing-metering.md` | Pricing tiers and metering |
+| `04-response-attestation.md` | Response integrity and attestation |
+| `05-tool-marketplace.md` | Listing and discovering tools |
+| `06-x402-seller-paywall.md` | Seller-side x402 integration |
+| `07-x402-buyer-client.md` | Buyer-side x402 integration |
+| `08-full-gateway-orchestration.md` | End-to-end gateway orchestration |
+| `09-events-observability.md` | Event system and observability |
 
-**Diagnosis:**
-```typescript
-const stats = client.getStats();
-console.log('Average latency:', stats.averageLatency);
-console.log('Cache hit rate:', stats.cacheHitRate);
-console.log('Pending requests:', stats.pendingRequests);
-```
-
-**Solutions:**
-- Enable caching for read operations
-- Use batch operations instead of sequential calls
-- Check network connectivity to RPC endpoint
-- Use multiple endpoints with load balancing
-- Verify endpoint proximity (use regional endpoints)
-
-#### 2. Connection Errors
-
-**Symptoms:** `NetworkError` or connection timeouts
+To regenerate the API reference:
 
-**Diagnosis:**
-```typescript
-client.on('error', (error) => {
-  console.error('Connection error:', error);
-});
-
-client.on('endpoint-rotate', ({ reason }) => {
-  console.log('Endpoint rotation reason:', reason);
-});
-```
-
-**Solutions:**
-- Verify endpoint URL and API key
-- Check firewall/proxy settings
-- Implement retry logic with exponential backoff
-- Use circuit breaker for automatic fallback
-- Test endpoint health manually
-
-#### 3. Memory Leaks
-
-**Symptoms:** Increasing memory usage over time
-
-**Diagnosis:**
-```typescript
-setInterval(() => {
-  const used = process.memoryUsage();
-  console.log('Memory usage:', {
-    rss: (used.rss / 1024 / 1024).toFixed(2) + ' MB',
-    heapTotal: (used.heapTotal / 1024 / 1024).toFixed(2) + ' MB',
-    heapUsed: (used.heapUsed / 1024 / 1024).toFixed(2) + ' MB',
-  });
-}, 30000);
-```
-
-**Solutions:**
-- Call `client.destroy()` when done
-- Unsubscribe from WebSocket subscriptions
-- Clear caches periodically: `client.clearCache()`
-- Remove event listeners when not needed
-- Use `--max-old-space-size` flag to increase heap limit
-
-#### 4. WebSocket Disconnections
-
-**Symptoms:** Frequent WebSocket disconnects
-
-**Diagnosis:**
-```typescript
-wsClient.on('disconnected', ({ code, reason }) => {
-  console.log('Disconnect code:', code);
-  console.log('Disconnect reason:', reason);
-});
-
-wsClient.on('reconnecting', ({ attempt, maxAttempts }) => {
-  console.log(`Reconnect attempt ${attempt}/${maxAttempts}`);
-});
-```
-
-**Solutions:**
-- Reduce heartbeat interval for faster detection
-- Increase `maxReconnectAttempts`
-- Check network stability
-- Use resilient subscriptions
-- Implement fallback to HTTP polling
-
-#### 5. Rate Limiting
-
-**Symptoms:** 429 Too Many Requests errors
-
-**Diagnosis:**
-```typescript
-client.on('error', (error) => {
-  if (error.code === 429) {
-    console.error('Rate limit exceeded');
-  }
-});
+```bash
+pnpm docs
 ```
 
-**Solutions:**
-- Implement request throttling
-- Use caching to reduce API calls
-- Batch operations when possible
-- Upgrade API plan for higher limits
-- Implement exponential backoff on rate limit errors
-
-### Debug Mode
-
-Enable debug logging for detailed insights:
-
-```typescript
-const client = new SynapseClient({
-  endpoint: process.env.SYNAPSE_ENDPOINT!,
-  apiKey: process.env.SYNAPSE_API_KEY,
-  debug: true, // Enable debug logs
-});
+---
 
-// Console output:
-// 🚀 Synapse Client initialized: https://...
-// 📤 [1] getBalance ["addr..."]
-// 📥 [1] ✅ 45ms
-// 📤 [2] getAccountInfo ["addr...", {...}]
-// 📥 [2] ✅ 82ms
+## Source Map
+
+```
+src/
+  index.ts                        Main entry point, barrel exports
+  core/
+    types.ts                      Branded types, RPC wire types
+    errors.ts                     Error hierarchy
+    transport.ts                  HttpTransport (JSON-RPC)
+    client.ts                     SynapseClient orchestrator
+  rpc/
+    solana-rpc.ts                 SolanaRpc facade (53 methods)
+    methods/                      One file per RPC method (53 files)
+  das/
+    types.ts                      DAS type definitions
+    client.ts                     DasClient facade (11 methods)
+    methods/                      One file per DAS method (11 files)
+  websocket/
+    types.ts                      Subscription and notification types
+    client.ts                     WsClient (6 subscription methods)
+  grpc/
+    types.ts                      gRPC transport types
+    transport.ts                  GrpcTransport class
+    parser/
+      types.ts                    Geyser protobuf types
+      programs.ts                 Known-program registry (80+)
+      decoder.ts                  Low-level stream decoders
+      geyser-parser.ts            GeyserParser high-level class
+  ai/
+    tools/
+      zod/                        Zod schemas for 53 RPC methods
+      protocols/
+        shared.ts                 Protocol infrastructure
+        jupiter/                  Jupiter DEX (21 methods)
+        raydium/                  Raydium DEX (16 methods)
+        metaplex/                 Metaplex NFT (12 methods)
+    gateway/
+      types.ts                    Gateway type definitions
+      session.ts                  AgentSession
+      pricing.ts                  PricingEngine
+      validator.ts                ResponseValidator
+      marketplace.ts              ToolMarketplace
+      index.ts                    AgentGateway
+      x402/
+        types.ts                  x402 protocol types
+        paywall.ts                Seller-side paywall
+        client.ts                 Buyer-side client
+        facilitator.ts            Settlement verification
+        registry.ts               Known facilitators
+    skills/                       10 markdown skill guides
+  utils/
+    helpers.ts                    lamportsToSol, sleep, chunk, retry
+    synapse.ts                    Endpoint registry, auto-select
 ```
 
 ---
 
 ## Contributing
 
-Contributions are welcome! Please follow these guidelines:
-
-### Development Setup
-
-```bash
-# Clone repository
-git clone https://github.com/CryptoFamilyNFT/synapse.git
-cd synapse/packages/synapse-client-sdk
-
-# Install dependencies
-pnpm install
-
-# Build project
-pnpm build
-
-# Run tests
-pnpm test
-
-# Run linter
-pnpm lint
-
-# Type check
-pnpm type-check
-```
-
-### Guidelines
-
-1. **Code Style:** Follow TypeScript best practices and existing code style
-2. **Testing:** Add tests for new features (`pnpm test`)
-3. **Documentation:** Update relevant README files
-4. **Type Safety:** Ensure full TypeScript coverage
-5. **Performance:** Benchmark changes if applicable (`pnpm benchmark`)
-6. **Commit Messages:** Use conventional commits format
-
-### Pull Request Process
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Make your changes
-4. Add tests and documentation
-5. Run tests and linter (`pnpm test && pnpm lint`)
-6. Commit your changes (`git commit -m 'feat: add amazing feature'`)
-7. Push to branch (`git push origin feature/amazing-feature`)
-8. Open a Pull Request
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the branching strategy, commit conventions, and development setup.
 
 ---
 
 ## License
 
-MIT License - See [LICENSE](./LICENSE) for complete terms.
-
-Copyright (c) 2024 CryptoFamilyNFT
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
----
-
-## Support
-
-- **Documentation:** [https://docs.synapse.com](https://docs.synapse.com)
-- **GitHub Issues:** [https://github.com/CryptoFamilyNFT/synapse/issues](https://github.com/CryptoFamilyNFT/synapse/issues)
-- **Discord:** [https://discord.gg/synapse](https://discord.gg/synapse)
-- **Email:** support@synapse.com
-
----
-
-**Synapse Client SDK** - Enterprise-grade Solana development toolkit
+MIT -- see [LICENSE](./LICENSE).
 
-Built with precision by the Synapse Team
+Copyright (c) OOBE Protocol Labs -- [oobeprotocol.ai](https://oobeprotocol.ai)