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

package/src/types/common.ts

@@ -0,0 +1,187 @@
+/**
+ * @module types/common
+ * @description Shared helper structs used across accounts and instructions.
+ *
+ * These types appear as nested fields in both on-chain account data
+ * and instruction argument DTOs.
+ *
+ * @category Types
+ * @since v0.1.0
+ */
+
+import type { PublicKey } from "@solana/web3.js";
+import type BN from "bn.js";
+import type { PluginTypeKind, SettlementModeKind, TokenTypeKind } from "./enums";
+
+// ═══════════════════════════════════════════════════════════════════
+//  Agent Capability
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @interface Capability
+ * @description Agent capability descriptor declaring what the agent can do.
+ *
+ * Capabilities use a namespaced identifier format (e.g. `"jupiter:swap"`).
+ * They are indexed on-chain via the `CapabilityIndex` PDA for scalable discovery.
+ *
+ * @category Types
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * const cap: Capability = {
+ *   id: "jupiter:swap",
+ *   description: "Token swap via Jupiter aggregator",
+ *   protocolId: "jupiter",
+ *   version: "1.0",
+ * };
+ * ```
+ */
+export interface Capability {
+  /** Unique identifier (e.g. `"jupiter:swap"`). */
+  readonly id: string;
+  /** Human-readable description of the capability. */
+  readonly description: string | null;
+  /** Protocol namespace this capability belongs to. */
+  readonly protocolId: string | null;
+  /** Semantic version of the capability. */
+  readonly version: string | null;
+}
+
+// ═══════════════════════════════════════════════════════════════════
+//  Pricing
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @interface VolumeCurveBreakpoint
+ * @description A single breakpoint in a volume-based pricing curve.
+ *
+ * After a consumer exceeds `afterCalls` total invocations, the effective
+ * price drops to `pricePerCall`. Multiple breakpoints form a tiered
+ * discount schedule (ERC-8004–style).
+ *
+ * @category Types
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * const curve: VolumeCurveBreakpoint[] = [
+ *   { afterCalls: 100, pricePerCall: new BN(90_000) },
+ *   { afterCalls: 500, pricePerCall: new BN(70_000) },
+ * ];
+ * ```
+ */
+export interface VolumeCurveBreakpoint {
+  /** Number of cumulative calls after which this price tier activates. */
+  readonly afterCalls: number;
+  /** Price per call (in token base units) once `afterCalls` is exceeded. */
+  readonly pricePerCall: BN;
+}
+
+/**
+ * @interface PricingTier
+ * @description Full pricing tier for agent services, including rate limits,
+ *   supported token, settlement mode, and optional volume discounts.
+ *
+ * Agents can expose multiple tiers (e.g. free, pro) each with independent
+ * rate-limiting and pricing parameters.
+ *
+ * @category Types
+ * @since v0.1.0
+ * @see {@link SettlementMode} for settlement strategies.
+ * @see {@link VolumeCurveBreakpoint} for volume-based discounts.
+ *
+ * @example
+ * ```ts
+ * import { TokenType, SettlementMode } from "@synapse-sap/sdk";
+ *
+ * const tier: PricingTier = {
+ *   tierId: "pro",
+ *   pricePerCall: new BN(100_000),
+ *   minPricePerCall: null,
+ *   maxPricePerCall: null,
+ *   rateLimit: 60,
+ *   maxCallsPerSession: 1000,
+ *   burstLimit: 10,
+ *   tokenType: TokenType.Usdc,
+ *   tokenMint: USDC_MINT,
+ *   tokenDecimals: 6,
+ *   settlementMode: SettlementMode.Escrow,
+ *   minEscrowDeposit: new BN(1_000_000),
+ *   batchIntervalSec: null,
+ *   volumeCurve: null,
+ * };
+ * ```
+ */
+export interface PricingTier {
+  /** Unique identifier for this tier (e.g. `"free"`, `"pro"`). */
+  readonly tierId: string;
+  /** Default price per call in token base units. */
+  readonly pricePerCall: BN;
+  /** Floor price guard (optional). */
+  readonly minPricePerCall: BN | null;
+  /** Ceiling price guard (optional). */
+  readonly maxPricePerCall: BN | null;
+  /** Maximum calls per second allowed. */
+  readonly rateLimit: number;
+  /** Maximum calls allowed within a single session. */
+  readonly maxCallsPerSession: number;
+  /** Burst capacity above steady-state rate limit. */
+  readonly burstLimit: number | null;
+  /** Token type accepted for payment. */
+  readonly tokenType: TokenTypeKind;
+  /** SPL token mint address (required when `tokenType` is `Spl`). */
+  readonly tokenMint: PublicKey | null;
+  /** Decimal places for the token. */
+  readonly tokenDecimals: number | null;
+  /** Settlement strategy for this tier. */
+  readonly settlementMode: SettlementModeKind | null;
+  /** Minimum escrow deposit required (for escrow settlement). */
+  readonly minEscrowDeposit: BN | null;
+  /** Batch settlement interval in seconds (for batched settlement). */
+  readonly batchIntervalSec: number | null;
+  /** Optional volume discount breakpoints. */
+  readonly volumeCurve: VolumeCurveBreakpoint[] | null;
+}
+
+// ═══════════════════════════════════════════════════════════════════
+//  Plugin Reference
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @interface PluginRef
+ * @description Reference to an active plugin PDA attached to an agent.
+ *
+ * Stored in the agent's `activePlugins` array to track which extensions
+ * are currently enabled.
+ *
+ * @category Types
+ * @since v0.1.0
+ */
+export interface PluginRef {
+  /** Discriminant identifying the plugin extension type. */
+  readonly pluginType: PluginTypeKind;
+  /** PDA address of the plugin account. */
+  readonly pda: PublicKey;
+}
+
+// ═══════════════════════════════════════════════════════════════════
+//  Settlement
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @interface Settlement
+ * @description Individual settlement entry used in batch settlement instructions.
+ *
+ * Each entry describes how many calls to settle for a given service, identified
+ * by its 32-byte hash.
+ *
+ * @category Types
+ * @since v0.1.0
+ */
+export interface Settlement {
+  /** Number of calls to settle in this batch entry. */
+  readonly callsToSettle: BN;
+  /** SHA-256 hash identifying the service being settled. */
+  readonly serviceHash: number[]; // [u8; 32]
+}

package/src/types/enums.ts

@@ -0,0 +1,214 @@
+/**
+ * @module types/enums
+ * @description Anchor-compatible enum variant objects for SAP v2.
+ *
+ * Each enum mirrors the Rust discriminant format used by Anchor:
+ * `{ variant: {} }` — e.g. `{ sol: {} }` for `TokenType::Sol`.
+ *
+ * Use the `*Kind` types for function signatures.
+ *
+ * @category Types
+ * @since v0.1.0
+ * @see {@link https://solana.com/docs | Solana Docs}
+ */
+
+// ═══════════════════════════════════════════════════════════════════
+//  Token Type
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @name TokenType
+ * @description Anchor-compatible enum variants for token types accepted by agent pricing and escrow.
+ *
+ * - `Sol` — Native SOL.
+ * - `Usdc` — USDC stablecoin.
+ * - `Spl` — Arbitrary SPL token (requires `tokenMint`).
+ *
+ * @category Types
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * import { TokenType } from "@synapse-sap/sdk";
+ *
+ * const tier = { tokenType: TokenType.Sol };
+ * ```
+ */
+export const TokenType = {
+  Sol: { sol: {} },
+  Usdc: { usdc: {} },
+  Spl: { spl: {} },
+} as const;
+
+/**
+ * @name TokenTypeKind
+ * @description Union of all {@link TokenType} variant shapes.
+ *   Use this as the type for any parameter that accepts a token type discriminant.
+ */
+export type TokenTypeKind = (typeof TokenType)[keyof typeof TokenType];
+
+// ═══════════════════════════════════════════════════════════════════
+//  Plugin Type
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @name PluginType
+ * @description Anchor-compatible enum variants for plugin extension types.
+ *
+ * Plugins extend agent functionality and are feature-gated on-chain.
+ *
+ * - `Memory` — Encrypted memory / vault storage.
+ * - `Validation` — Custom validation logic.
+ * - `Delegation` — Hot-wallet delegation.
+ * - `Analytics` — Metrics & analytics.
+ * - `Governance` — DAO / governance participation.
+ * - `Custom` — User-defined plugin type.
+ *
+ * @category Types
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * import { PluginType } from "@synapse-sap/sdk";
+ *
+ * const ref = { pluginType: PluginType.Memory, pda: vaultPda };
+ * ```
+ */
+export const PluginType = {
+  Memory: { memory: {} },
+  Validation: { validation: {} },
+  Delegation: { delegation: {} },
+  Analytics: { analytics: {} },
+  Governance: { governance: {} },
+  Custom: { custom: {} },
+} as const;
+
+/**
+ * @name PluginTypeKind
+ * @description Union of all {@link PluginType} variant shapes.
+ */
+export type PluginTypeKind = (typeof PluginType)[keyof typeof PluginType];
+
+// ═══════════════════════════════════════════════════════════════════
+//  Settlement Mode
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @name SettlementMode
+ * @description Anchor-compatible enum variants for payment settlement strategies.
+ *
+ * - `Instant` — Pay-per-call, settled immediately on invocation.
+ * - `Escrow` — Pre-funded escrow account with per-call drawdown.
+ * - `Batched` — Aggregated settlement at fixed intervals.
+ * - `X402` — HTTP 402-based micropayment protocol settlement.
+ *
+ * @category Types
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * import { SettlementMode } from "@synapse-sap/sdk";
+ *
+ * const tier = { settlementMode: SettlementMode.Escrow };
+ * ```
+ */
+export const SettlementMode = {
+  Instant: { instant: {} },
+  Escrow: { escrow: {} },
+  Batched: { batched: {} },
+  X402: { x402: {} },
+} as const;
+
+/**
+ * @name SettlementModeKind
+ * @description Union of all {@link SettlementMode} variant shapes.
+ */
+export type SettlementModeKind =
+  (typeof SettlementMode)[keyof typeof SettlementMode];
+
+// ═══════════════════════════════════════════════════════════════════
+//  Tool HTTP Method
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @name ToolHttpMethod
+ * @description Anchor-compatible enum variants for the HTTP method exposed by a tool.
+ *
+ * - `Get` / `Post` / `Put` / `Delete` — Standard REST verbs.
+ * - `Compound` — Multi-step tool (calls several sub-operations).
+ *
+ * @category Types
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * import { ToolHttpMethod } from "@synapse-sap/sdk";
+ *
+ * const args = { httpMethod: ToolHttpMethod.Post };
+ * ```
+ */
+export const ToolHttpMethod = {
+  Get: { get: {} },
+  Post: { post: {} },
+  Put: { put: {} },
+  Delete: { delete: {} },
+  Compound: { compound: {} },
+} as const;
+
+/**
+ * @name ToolHttpMethodKind
+ * @description Union of all {@link ToolHttpMethod} variant shapes.
+ */
+export type ToolHttpMethodKind =
+  (typeof ToolHttpMethod)[keyof typeof ToolHttpMethod];
+
+// ═══════════════════════════════════════════════════════════════════
+//  Tool Category
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @name ToolCategory
+ * @description Anchor-compatible enum variants for classifying tools in the on-chain registry.
+ *
+ * Categories power cross-agent tool discovery via the `ToolCategoryIndex` PDA.
+ *
+ * - `Swap` — Token swap / DEX tools.
+ * - `Lend` — Lending protocol tools.
+ * - `Stake` — Staking / validator tools.
+ * - `Nft` — NFT minting / marketplace tools.
+ * - `Payment` — Payment & invoicing tools.
+ * - `Data` — Data feeds / oracles.
+ * - `Governance` — DAO & governance tools.
+ * - `Bridge` — Cross-chain bridge tools.
+ * - `Analytics` — On-chain analytics.
+ * - `Custom` — User-defined category.
+ *
+ * @category Types
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * import { ToolCategory } from "@synapse-sap/sdk";
+ *
+ * const args = { category: ToolCategory.Swap };
+ * ```
+ */
+export const ToolCategory = {
+  Swap: { swap: {} },
+  Lend: { lend: {} },
+  Stake: { stake: {} },
+  Nft: { nft: {} },
+  Payment: { payment: {} },
+  Data: { data: {} },
+  Governance: { governance: {} },
+  Bridge: { bridge: {} },
+  Analytics: { analytics: {} },
+  Custom: { custom: {} },
+} as const;
+
+/**
+ * @name ToolCategoryKind
+ * @description Union of all {@link ToolCategory} variant shapes.
+ */
+export type ToolCategoryKind =
+  (typeof ToolCategory)[keyof typeof ToolCategory];

package/src/types/index.ts

@@ -0,0 +1,92 @@
+/**
+ * @module types
+ * @description Strongly-typed domain models for SAP v2.
+ *
+ * Every type mirrors the onchain Rust struct / enum exactly.
+ * Types are organized into four layers:
+ *
+ * - **enums** — Anchor-style enum variant objects (`TokenType`, `ToolCategory`, …)
+ * - **common** — Shared helper structs (`Capability`, `PricingTier`, `Settlement`, …)
+ * - **accounts** — Deserialized on-chain PDA account data (`AgentAccountData`, …)
+ * - **instructions** — Instruction argument DTOs + permission/schema helpers
+ *
+ * @category Types
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * import type { AgentAccountData, RegisterAgentArgs } from "@synapse-sap/sdk/types";
+ * import { TokenType, SettlementMode } from "@synapse-sap/sdk/types";
+ * ```
+ */
+
+// ── Enums ────────────────────────────────────────────
+export {
+  TokenType,
+  PluginType,
+  SettlementMode,
+  ToolHttpMethod,
+  ToolCategory,
+} from "./enums";
+
+export type {
+  TokenTypeKind,
+  PluginTypeKind,
+  SettlementModeKind,
+  ToolHttpMethodKind,
+  ToolCategoryKind,
+} from "./enums";
+
+// ── Common Structs ───────────────────────────────────
+export type {
+  Capability,
+  VolumeCurveBreakpoint,
+  PricingTier,
+  PluginRef,
+  Settlement,
+} from "./common";
+
+// ── Account Data ─────────────────────────────────────
+export type {
+  AgentAccountData,
+  AgentStatsData,
+  FeedbackAccountData,
+  CapabilityIndexData,
+  ProtocolIndexData,
+  ToolCategoryIndexData,
+  GlobalRegistryData,
+  MemoryVaultData,
+  SessionLedgerData,
+  EpochPageData,
+  VaultDelegateData,
+  SessionCheckpointData,
+  ToolDescriptorData,
+  EscrowAccountData,
+  AgentAttestationData,
+  MemoryLedgerData,
+  LedgerPageData,
+} from "./accounts";
+
+// ── Instruction Args ─────────────────────────────────
+export type {
+  RegisterAgentArgs,
+  UpdateAgentArgs,
+  GiveFeedbackArgs,
+  UpdateFeedbackArgs,
+  PublishToolArgs,
+  UpdateToolArgs,
+  InscribeToolSchemaArgs,
+  InscribeMemoryArgs,
+  CompactInscribeArgs,
+  CreateEscrowArgs,
+  CreateAttestationArgs,
+  DelegatePermissionBit,
+  SchemaTypeValue,
+  CompressionTypeValue,
+} from "./instructions";
+
+export {
+  DelegatePermission,
+  SchemaType,
+  CompressionType,
+} from "./instructions";