@oobe-protocol-labs/synapse-sap-sdk 0.1.0

package/package.json

@@ -0,0 +1,178 @@
+{
+  "name": "@oobe-protocol-labs/synapse-sap-sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for the Synapse Agent Protocol (SAP v2) on Solana",
+  "license": "MIT",
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/types/index.d.ts"
+    },
+    "./agent": {
+      "import": "./dist/esm/modules/agent.js",
+      "require": "./dist/cjs/modules/agent.js",
+      "types": "./dist/types/modules/agent.d.ts"
+    },
+    "./feedback": {
+      "import": "./dist/esm/modules/feedback.js",
+      "require": "./dist/cjs/modules/feedback.js",
+      "types": "./dist/types/modules/feedback.d.ts"
+    },
+    "./indexing": {
+      "import": "./dist/esm/modules/indexing.js",
+      "require": "./dist/cjs/modules/indexing.js",
+      "types": "./dist/types/modules/indexing.d.ts"
+    },
+    "./tools": {
+      "import": "./dist/esm/modules/tools.js",
+      "require": "./dist/cjs/modules/tools.js",
+      "types": "./dist/types/modules/tools.d.ts"
+    },
+    "./vault": {
+      "import": "./dist/esm/modules/vault.js",
+      "require": "./dist/cjs/modules/vault.js",
+      "types": "./dist/types/modules/vault.d.ts"
+    },
+    "./escrow": {
+      "import": "./dist/esm/modules/escrow.js",
+      "require": "./dist/cjs/modules/escrow.js",
+      "types": "./dist/types/modules/escrow.d.ts"
+    },
+    "./attestation": {
+      "import": "./dist/esm/modules/attestation.js",
+      "require": "./dist/cjs/modules/attestation.js",
+      "types": "./dist/types/modules/attestation.d.ts"
+    },
+    "./ledger": {
+      "import": "./dist/esm/modules/ledger.js",
+      "require": "./dist/cjs/modules/ledger.js",
+      "types": "./dist/types/modules/ledger.d.ts"
+    },
+    "./pda": {
+      "import": "./dist/esm/pda/index.js",
+      "require": "./dist/cjs/pda/index.js",
+      "types": "./dist/types/pda/index.d.ts"
+    },
+    "./types": {
+      "import": "./dist/esm/types/index.js",
+      "require": "./dist/cjs/types/index.js",
+      "types": "./dist/types/types/index.d.ts"
+    },
+    "./plugin": {
+      "import": "./dist/esm/plugin/index.js",
+      "require": "./dist/cjs/plugin/index.js",
+      "types": "./dist/types/plugin/index.d.ts"
+    },
+    "./plugin/schemas": {
+      "import": "./dist/esm/plugin/schemas.js",
+      "require": "./dist/cjs/plugin/schemas.js",
+      "types": "./dist/types/plugin/schemas.d.ts"
+    },
+    "./registries": {
+      "import": "./dist/esm/registries/index.js",
+      "require": "./dist/cjs/registries/index.js",
+      "types": "./dist/types/registries/index.d.ts"
+    },
+    "./registries/discovery": {
+      "import": "./dist/esm/registries/discovery.js",
+      "require": "./dist/cjs/registries/discovery.js",
+      "types": "./dist/types/registries/discovery.d.ts"
+    },
+    "./registries/x402": {
+      "import": "./dist/esm/registries/x402.js",
+      "require": "./dist/cjs/registries/x402.js",
+      "types": "./dist/types/registries/x402.d.ts"
+    },
+    "./registries/session": {
+      "import": "./dist/esm/registries/session.js",
+      "require": "./dist/cjs/registries/session.js",
+      "types": "./dist/types/registries/session.d.ts"
+    },
+    "./registries/builder": {
+      "import": "./dist/esm/registries/builder.js",
+      "require": "./dist/cjs/registries/builder.js",
+      "types": "./dist/types/registries/builder.d.ts"
+    },
+    "./idl": {
+      "import": "./dist/esm/idl/index.js",
+      "require": "./dist/cjs/idl/index.js",
+      "types": "./dist/types/idl/index.d.ts"
+    },
+    "./constants": {
+      "import": "./dist/esm/constants/index.js",
+      "require": "./dist/cjs/constants/index.js",
+      "types": "./dist/types/constants/index.d.ts"
+    },
+    "./core": {
+      "import": "./dist/esm/core/index.js",
+      "require": "./dist/cjs/core/index.js",
+      "types": "./dist/types/core/index.d.ts"
+    },
+    "./errors": {
+      "import": "./dist/esm/errors/index.js",
+      "require": "./dist/cjs/errors/index.js",
+      "types": "./dist/types/errors/index.d.ts"
+    },
+    "./utils": {
+      "import": "./dist/esm/utils/index.js",
+      "require": "./dist/cjs/utils/index.js",
+      "types": "./dist/types/utils/index.d.ts"
+    },
+    "./events": {
+      "import": "./dist/esm/events/index.js",
+      "require": "./dist/cjs/events/index.js",
+      "types": "./dist/types/events/index.d.ts"
+    },
+    "./postgres": {
+      "import": "./dist/esm/postgres/index.js",
+      "require": "./dist/cjs/postgres/index.js",
+      "types": "./dist/types/postgres/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "src/idl",
+    "src/postgres",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "yarn build:cjs && yarn build:esm && yarn build:types",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:types": "tsc -p tsconfig.json --emitDeclarationOnly",
+    "clean": "rm -rf dist",
+    "sync-idl": "cp ../target/idl/synapse_agent_sap.json src/idl/synapse_agent_sap.json && echo 'IDL synced'",
+    "prepublishOnly": "yarn clean && yarn build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@coral-xyz/anchor": "^0.32.1",
+    "@solana/web3.js": "^1.98.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "@coral-xyz/anchor": ">=0.30.0",
+    "@solana/web3.js": ">=1.90.0",
+    "zod": ">=3.20.0",
+    "pg": ">=8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/constants/index.ts

@@ -0,0 +1,44 @@
+/**
+ * @module constants
+ * @description Protocol constants mirroring the on-chain Rust program.
+ *
+ * Organized into:
+ * - **programs** — Network-specific program IDs
+ * - **seeds** — PDA seed prefix strings
+ * - **limits** — Size constraints, versions, enum numeric values
+ *
+ * @category Constants
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * import {
+ *   MAINNET_SAP_PROGRAM_ID,
+ *   DEVNET_SAP_PROGRAM_ID,
+ *   SEEDS,
+ *   LIMITS,
+ * } from "@synapse-sap/sdk/constants";
+ * ```
+ */
+
+// ── Program IDs ──────────────────────────────────────
+export {
+  SAP_PROGRAM_ADDRESS,
+  MAINNET_SAP_PROGRAM_ID,
+  DEVNET_SAP_PROGRAM_ID,
+  LOCALNET_SAP_PROGRAM_ID,
+  SAP_PROGRAM_ID,
+} from "./programs";
+
+// ── PDA Seeds ────────────────────────────────────────
+export { SEEDS } from "./seeds";
+export type { SeedKey } from "./seeds";
+
+// ── Limits & Versions ────────────────────────────────
+export {
+  LIMITS,
+  AGENT_VERSION,
+  VAULT_PROTOCOL_VERSION,
+  TOOL_CATEGORY_VALUES,
+  HTTP_METHOD_VALUES,
+} from "./limits";

package/src/constants/limits.ts

@@ -0,0 +1,165 @@
+/**
+ * @module constants/limits
+ * @description Protocol size limits, version constants, and enum numeric values.
+ *
+ * All values mirror the on-chain Rust constraints exactly.
+ * Used for client-side validation before sending transactions.
+ *
+ * @category Constants
+ * @since v0.1.0
+ */
+
+// ═══════════════════════════════════════════════════════════════════
+//  Size Limits (mirrors Rust impl blocks)
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * Protocol size constraints mirroring the Rust `impl` blocks.
+ *
+ * Use these values for client-side validation before submitting
+ * transactions — exceeding any limit will cause an on-chain error.
+ *
+ * @name LIMITS
+ * @description A frozen object containing all protocol-enforced size and length bounds.
+ * @category Constants
+ * @since v0.1.0
+ * @example
+ * ```ts
+ * import { LIMITS } from "@synapse-sap/sdk/constants";
+ *
+ * if (name.length > LIMITS.MAX_NAME_LEN) {
+ *   throw new Error("Agent name too long");
+ * }
+ * ```
+ */
+export const LIMITS = {
+  /** Max agent name length in bytes. */
+  MAX_NAME_LEN: 64,
+  /** Max agent description length in bytes. */
+  MAX_DESC_LEN: 256,
+  /** Max URI length (agent_uri, x402_endpoint). */
+  MAX_URI_LEN: 256,
+  /** Max agent DID-style identifier length. */
+  MAX_AGENT_ID_LEN: 128,
+  /** Max capabilities per agent. */
+  MAX_CAPABILITIES: 10,
+  /** Max pricing tiers per agent. */
+  MAX_PRICING_TIERS: 5,
+  /** Max protocol strings per agent. */
+  MAX_PROTOCOLS: 5,
+  /** Max active plugins per agent. */
+  MAX_PLUGINS: 5,
+  /** Max volume curve breakpoints per tier. */
+  MAX_VOLUME_CURVE_POINTS: 5,
+  /** Max feedback tag length. */
+  MAX_TAG_LEN: 32,
+  /** Max agents in a capability/protocol index. */
+  MAX_AGENTS_PER_INDEX: 100,
+  /** Max tool name length. */
+  MAX_TOOL_NAME_LEN: 32,
+  /** Max tools in a category index. */
+  MAX_TOOLS_PER_CATEGORY: 100,
+  /** Max attestation type length. */
+  MAX_ATTESTATION_TYPE_LEN: 32,
+  /** Max inscription size (encrypted_data per fragment). */
+  MAX_INSCRIPTION_SIZE: 750,
+  /** Inscriptions per epoch page. */
+  INSCRIPTIONS_PER_EPOCH: 1000,
+  /** Max memory chunk size (legacy). */
+  MAX_CHUNK_SIZE: 900,
+  /** Max write size per buffer append (legacy). */
+  MAX_BUFFER_WRITE_SIZE: 750,
+  /** Max total buffer page size (legacy). */
+  MAX_BUFFER_TOTAL_SIZE: 10_000,
+  /** Ring buffer capacity for MemoryLedger. */
+  RING_CAPACITY: 4096,
+  /** Max ledger write size per call. */
+  MAX_LEDGER_WRITE_SIZE: 750,
+  /** Max settlements in a batch. */
+  MAX_BATCH_SETTLEMENTS: 10,
+  /** Feedback score range: 0–1000. */
+  MAX_FEEDBACK_SCORE: 1000,
+} as const;
+
+// ═══════════════════════════════════════════════════════════════════
+//  Protocol Versions
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * Current on-chain protocol version for `AgentAccount`.
+ *
+ * @name AGENT_VERSION
+ * @description Integer version stamped into every agent account on registration.
+ * @category Constants
+ * @since v0.1.0
+ */
+export const AGENT_VERSION = 1;
+
+/**
+ * Current on-chain protocol version for `MemoryVault`.
+ *
+ * @name VAULT_PROTOCOL_VERSION
+ * @description Integer version stamped into every vault account on initialisation.
+ * @category Constants
+ * @since v0.1.0
+ */
+export const VAULT_PROTOCOL_VERSION = 1;
+
+// ═══════════════════════════════════════════════════════════════════
+//  Numeric Enum Values
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * Tool category to `u8` discriminant mapping.
+ *
+ * Mirrors the Rust `ToolCategory` enum ordinals. Use these values
+ * when constructing or filtering tool-related instructions.
+ *
+ * @name TOOL_CATEGORY_VALUES
+ * @description Frozen mapping of tool category names to their on-chain `u8` discriminants.
+ * @category Constants
+ * @since v0.1.0
+ * @example
+ * ```ts
+ * import { TOOL_CATEGORY_VALUES } from "@synapse-sap/sdk/constants";
+ *
+ * const categoryByte = TOOL_CATEGORY_VALUES.Swap; // 0
+ * ```
+ */
+export const TOOL_CATEGORY_VALUES = {
+  Swap: 0,
+  Lend: 1,
+  Stake: 2,
+  Nft: 3,
+  Payment: 4,
+  Data: 5,
+  Governance: 6,
+  Bridge: 7,
+  Analytics: 8,
+  Custom: 9,
+} as const;
+
+/**
+ * HTTP method to `u8` discriminant mapping.
+ *
+ * Mirrors the Rust `HttpMethod` enum ordinals. Used when publishing
+ * or filtering tool endpoints.
+ *
+ * @name HTTP_METHOD_VALUES
+ * @description Frozen mapping of HTTP method names to their on-chain `u8` discriminants.
+ * @category Constants
+ * @since v0.1.0
+ * @example
+ * ```ts
+ * import { HTTP_METHOD_VALUES } from "@synapse-sap/sdk/constants";
+ *
+ * const method = HTTP_METHOD_VALUES.Post; // 1
+ * ```
+ */
+export const HTTP_METHOD_VALUES = {
+  Get: 0,
+  Post: 1,
+  Put: 2,
+  Delete: 3,
+  Compound: 4,
+} as const;

package/src/constants/programs.ts

@@ -0,0 +1,83 @@
+/**
+ * @module constants/programs
+ * @description SAP v2 program IDs for each Solana cluster.
+ *
+ * The canonical program address is shared across mainnet, devnet,
+ * and localnet. If you deploy a custom instance, override the
+ * program ID in `SapClient.from(provider, customProgramId)`.
+ *
+ * @category Constants
+ * @since v0.1.0
+ */
+
+import { PublicKey } from "@solana/web3.js";
+
+// ═══════════════════════════════════════════════════════════════════
+//  Program Address
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * SAP v2 program address string (base58).
+ *
+ * Vanity keypair derived from the `SAPTU7a…` prefix.
+ *
+ * @name SAP_PROGRAM_ADDRESS
+ * @description The canonical on-chain program address shared by all Solana clusters.
+ * @category Constants
+ * @since v0.1.0
+ * @see {@link SAP_PROGRAM_ID}
+ */
+export const SAP_PROGRAM_ADDRESS =
+  "SAPTU7aUXk2AaAdktexae1iuxXpokxzNDBAYYhaVyQL";
+
+// ═══════════════════════════════════════════════════════════════════
+//  Per-Network PublicKeys
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * SAP v2 mainnet-beta program ID.
+ *
+ * @name MAINNET_SAP_PROGRAM_ID
+ * @description `PublicKey` instance of {@link SAP_PROGRAM_ADDRESS} for mainnet-beta.
+ * @category Constants
+ * @since v0.1.0
+ * @see {@link SAP_PROGRAM_ADDRESS}
+ */
+export const MAINNET_SAP_PROGRAM_ID = new PublicKey(SAP_PROGRAM_ADDRESS);
+
+/**
+ * SAP v2 devnet program ID.
+ *
+ * @name DEVNET_SAP_PROGRAM_ID
+ * @description `PublicKey` instance of {@link SAP_PROGRAM_ADDRESS} for devnet.
+ * @category Constants
+ * @since v0.1.0
+ * @see {@link SAP_PROGRAM_ADDRESS}
+ */
+export const DEVNET_SAP_PROGRAM_ID = new PublicKey(SAP_PROGRAM_ADDRESS);
+
+/**
+ * Localnet / solana-test-validator program ID.
+ *
+ * Override with your own keypair if deploying locally at a different address.
+ *
+ * @name LOCALNET_SAP_PROGRAM_ID
+ * @description `PublicKey` instance of {@link SAP_PROGRAM_ADDRESS} for localnet / `solana-test-validator`.
+ * @category Constants
+ * @since v0.1.0
+ * @see {@link SAP_PROGRAM_ADDRESS}
+ */
+export const LOCALNET_SAP_PROGRAM_ID = new PublicKey(SAP_PROGRAM_ADDRESS);
+
+/**
+ * Default program ID used by `SapClient.from()` when no explicit ID is provided.
+ *
+ * Alias for {@link MAINNET_SAP_PROGRAM_ID}.
+ *
+ * @name SAP_PROGRAM_ID
+ * @description Convenience alias pointing to the mainnet-beta program ID.
+ * @category Constants
+ * @since v0.1.0
+ * @see {@link MAINNET_SAP_PROGRAM_ID}
+ */
+export const SAP_PROGRAM_ID = MAINNET_SAP_PROGRAM_ID;

package/src/constants/seeds.ts

@@ -0,0 +1,66 @@
+/**
+ * @module constants/seeds
+ * @description PDA seed prefix constants.
+ *
+ * Every seed string mirrors the Rust `#[account(seeds = [...])]` definitions.
+ *
+ * @category Constants
+ * @since v0.1.0
+ */
+
+// ═══════════════════════════════════════════════════════════════════
+//  PDA Seed Prefixes
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * PDA seed prefix lookup table.
+ *
+ * Each key corresponds to an on-chain account type, and the value is the
+ * UTF-8 string used as the first seed segment in
+ * `PublicKey.findProgramAddressSync`.
+ *
+ * @name SEEDS
+ * @description Maps logical account names to their Rust-defined PDA seed prefix strings.
+ * @category Constants
+ * @since v0.1.0
+ * @example
+ * ```ts
+ * import { SEEDS } from "@synapse-sap/sdk/constants";
+ *
+ * Buffer.from(SEEDS.AGENT); // => "sap_agent"
+ * ```
+ * @see {@link SeedKey}
+ */
+export const SEEDS = {
+  AGENT: "sap_agent",
+  FEEDBACK: "sap_feedback",
+  CAPABILITY_INDEX: "sap_cap_idx",
+  PROTOCOL_INDEX: "sap_proto_idx",
+  GLOBAL: "sap_global",
+  PLUGIN: "sap_plugin",
+  MEMORY: "sap_memory",
+  MEMORY_CHUNK: "sap_mem_chunk",
+  VAULT: "sap_vault",
+  SESSION: "sap_session",
+  EPOCH: "sap_epoch",
+  DELEGATE: "sap_delegate",
+  TOOL: "sap_tool",
+  CHECKPOINT: "sap_checkpoint",
+  ESCROW: "sap_escrow",
+  STATS: "sap_stats",
+  TOOL_CATEGORY: "sap_tool_cat",
+  ATTESTATION: "sap_attest",
+  LEDGER: "sap_ledger",
+  LEDGER_PAGE: "sap_page",
+} as const;
+
+/**
+ * Union type of all valid keys in the {@link SEEDS} object.
+ *
+ * @name SeedKey
+ * @description String literal union derived from `keyof typeof SEEDS`.
+ * @category Constants
+ * @since v0.1.0
+ * @see {@link SEEDS}
+ */
+export type SeedKey = keyof typeof SEEDS;