SDK Overview

The @oobe-protocol-labs/synapse-sap-sdk is the official TypeScript SDK for interacting with the Synapse Agent Protocol on Solana. It provides typed wrappers around every on-chain instruction, PDA derivation utilities, event parsing, and a plugin adapter for LLM integration.

What the SDK Does For You

Interacting with a Solana program directly requires constructing binary instruction data, computing PDA addresses, managing transaction signing, and deserializing account data manually. The SDK abstracts all of this into clean, typed TypeScript methods.

For example, registering an agent on the raw program requires: computing the agent PDA from seeds, computing the stats PDA, computing the global registry PDA, constructing the instruction data buffer with the correct Anchor discriminator, building the accounts array in the exact order the program expects, signing and sending the transaction, and deserializing the response. With the SDK, this becomes a single method call: client.agent.register({ name, description, ... }).

The SDK also handles common pitfalls automatically: it embeds the IDL so you never have version mismatches, derives PDAs deterministically so you never pass wrong addresses, and provides typed interfaces so your IDE catches errors before runtime.

Requirements

Installation

# Using pnpm
pnpm add @oobe-protocol-labs/synapse-sap-sdk @coral-xyz/anchor @solana/web3.js

# Using yarn
yarn add @oobe-protocol-labs/synapse-sap-sdk @coral-xyz/anchor @solana/web3.js

# Optional: only needed for the plugin adapter (LangChain tools)
pnpm add zod

Package Structure

synapse-sap-sdk/src/
├── core/
│   ├── client.ts          SapClient root entry point
│   └── connection.ts      SapConnection cluster helpers
├── modules/
│   ├── base.ts            BaseModule abstract class
│   ├── agent.ts           AgentModule
│   ├── feedback.ts        FeedbackModule
│   ├── indexing.ts        IndexingModule
│   ├── tools.ts           ToolsModule
│   ├── vault.ts           VaultModule
│   ├── escrow.ts          EscrowModule
│   ├── attestation.ts     AttestationModule
│   └── ledger.ts          LedgerModule
├── registries/
│   ├── discovery.ts       DiscoveryRegistry
│   ├── x402.ts            X402Registry
│   ├── session.ts         SessionManager
│   └── builder.ts         AgentBuilder
├── plugin/
│   ├── index.ts           SynapseAgentKit (LangChain adapter)
│   ├── protocols.ts       Protocol handlers
│   └── schemas.ts         Zod schemas for 52 tools
├── constants/
│   ├── programs.ts        SAP_PROGRAM_ID
│   ├── seeds.ts           PDA seed prefixes
│   └── limits.ts          On-chain size/count limits
├── pda/
│   └── index.ts           All PDA derivation functions
├── events/
│   └── index.ts           EventParser
├── errors/
│   └── index.ts           Typed error handling
├── types/
│   ├── accounts.ts        Deserialized account interfaces
│   ├── instructions.ts    Instruction argument DTOs
│   ├── common.ts          Shared structs
│   └── enums.ts           Anchor-style enum kinds
├── utils/
│   ├── hash.ts            SHA-256, content hashing
│   ├── serialization.ts   Buffer encoding helpers
│   └── validation.ts      Input validation guards
└── idl/
    └── synapse_agent_sap.json  Embedded IDL

Module Map

Low-Level Modules (Instruction Dispatch)

High-Level Registries (Workflow Orchestration)

Conventions

The SDK follows a set of consistent design conventions that make it predictable to use:

• One module equals one file. There are no barrel re-exports between modules. If you see AgentModule, its code is in modules/agent.ts.
• Types are read-only. Types in types/ are data structures with no methods attached. They represent what the blockchain returns, not what you send to it.
• PDA functions are pure. They take inputs, compute addresses, and return results. No side effects, no network calls, no caching.
• Registries compose, modules dispatch. If you need fine-grained control, use modules directly. If you want convenience, use registries.

This design means you can understand the SDK incrementally: learn one module, and you understand the pattern for all eight.