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

package/src/types/instructions.ts

@@ -0,0 +1,413 @@
+/**
+ * @module types/instructions
+ * @description Instruction argument DTOs and helper enumerations.
+ *
+ * These interfaces map 1:1 to the Anchor instruction argument structs.
+ * Use them when calling SDK module methods.
+ *
+ * @category Types
+ * @since v0.1.0
+ */
+
+import type { PublicKey } from "@solana/web3.js";
+import type BN from "bn.js";
+import type { Capability, PricingTier, VolumeCurveBreakpoint } from "./common";
+
+// ═══════════════════════════════════════════════════════════════════
+//  Agent Instructions
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @interface RegisterAgentArgs
+ * @description Arguments for the `registerAgent` instruction.
+ *
+ * Creates a new on-chain agent identity with the given profile,
+ * capabilities, pricing tiers, and protocol support.
+ *
+ * @category Types
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * import { TokenType } from "@synapse-sap/sdk";
+ *
+ * const args: RegisterAgentArgs = {
+ *   name: "My Agent",
+ *   description: "A helpful Solana agent",
+ *   capabilities: [{ id: "jupiter:swap", description: null, protocolId: "jupiter", version: "1.0" }],
+ *   pricing: [],
+ *   protocols: ["solana-agent-protocol"],
+ * };
+ * ```
+ */
+export interface RegisterAgentArgs {
+  /** Agent display name. */
+  readonly name: string;
+  /** Agent description. */
+  readonly description: string;
+  /** Capabilities the agent exposes. */
+  readonly capabilities: Capability[];
+  /** Pricing tiers for the agent's services. */
+  readonly pricing: PricingTier[];
+  /** Supported protocol identifiers. */
+  readonly protocols: string[];
+  /** Optional off-chain agent identifier. */
+  readonly agentId?: string | null;
+  /** Optional URI to extended metadata. */
+  readonly agentUri?: string | null;
+  /** Optional x402 payment endpoint. */
+  readonly x402Endpoint?: string | null;
+}
+
+/**
+ * @interface UpdateAgentArgs
+ * @description Arguments for the `updateAgent` instruction.
+ *
+ * All fields are optional — pass only the fields you want to change.
+ * `null` values are ignored on-chain.
+ *
+ * @category Types
+ * @since v0.1.0
+ */
+export interface UpdateAgentArgs {
+  readonly name?: string | null;
+  readonly description?: string | null;
+  readonly capabilities?: Capability[] | null;
+  readonly pricing?: PricingTier[] | null;
+  readonly protocols?: string[] | null;
+  readonly agentId?: string | null;
+  readonly agentUri?: string | null;
+  readonly x402Endpoint?: string | null;
+}
+
+// ═══════════════════════════════════════════════════════════════════
+//  Feedback Instructions
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @interface GiveFeedbackArgs
+ * @description Arguments for the `giveFeedback` instruction.
+ *
+ * Submits a reputation score and tag for the target agent.
+ * Each reviewer can only submit one feedback per agent.
+ *
+ * @category Types
+ * @since v0.1.0
+ */
+export interface GiveFeedbackArgs {
+  /** Reputation score (1–100). */
+  readonly score: number;
+  /** Freeform tag / category for the feedback. */
+  readonly tag: string;
+  /** Optional SHA-256 hash of an off-chain comment. */
+  readonly commentHash?: number[] | null; // [u8; 32]
+}
+
+/**
+ * @interface UpdateFeedbackArgs
+ * @description Arguments for the `updateFeedback` instruction.
+ *
+ * Allows the original reviewer to revise their score and/or tag.
+ *
+ * @category Types
+ * @since v0.1.0
+ */
+export interface UpdateFeedbackArgs {
+  /** Updated reputation score (1–100). */
+  readonly newScore: number;
+  /** Updated tag (optional). */
+  readonly newTag?: string | null;
+  /** Updated off-chain comment hash (optional). */
+  readonly commentHash?: number[] | null; // [u8; 32]
+}
+
+// ═══════════════════════════════════════════════════════════════════
+//  Tool Instructions
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @interface PublishToolArgs
+ * @description Arguments for the `publishTool` instruction.
+ *
+ * Registers a new tool descriptor on-chain with hashed metadata.
+ * Hash fields are SHA-256 digests of the corresponding off-chain content.
+ *
+ * @category Types
+ * @since v0.1.0
+ */
+export interface PublishToolArgs {
+  /** Human-readable tool name. */
+  readonly toolName: string;
+  /** SHA-256 hash of the tool name (PDA seed). */
+  readonly toolNameHash: number[];    // [u8; 32]
+  /** SHA-256 hash of the protocol identifier. */
+  readonly protocolHash: number[];    // [u8; 32]
+  /** SHA-256 hash of the tool description. */
+  readonly descriptionHash: number[]; // [u8; 32]
+  /** SHA-256 hash of the input JSON schema. */
+  readonly inputSchemaHash: number[]; // [u8; 32]
+  /** SHA-256 hash of the output JSON schema. */
+  readonly outputSchemaHash: number[];// [u8; 32]
+  /** HTTP method discriminant index. */
+  readonly httpMethod: number;
+  /** Tool category discriminant index. */
+  readonly category: number;
+  /** Total number of parameters. */
+  readonly paramsCount: number;
+  /** Number of required parameters. */
+  readonly requiredParams: number;
+  /** Whether the tool is a compound (multi-step) operation. */
+  readonly isCompound: boolean;
+}
+
+/**
+ * @interface UpdateToolArgs
+ * @description Arguments for the `updateTool` instruction.
+ *
+ * All fields are optional — only pass the fields to update.
+ *
+ * @category Types
+ * @since v0.1.0
+ */
+export interface UpdateToolArgs {
+  readonly descriptionHash?: number[] | null;
+  readonly inputSchemaHash?: number[] | null;
+  readonly outputSchemaHash?: number[] | null;
+  readonly httpMethod?: number | null;
+  readonly category?: number | null;
+  readonly paramsCount?: number | null;
+  readonly requiredParams?: number | null;
+}
+
+/**
+ * @interface InscribeToolSchemaArgs
+ * @description Arguments for the `inscribeToolSchema` instruction.
+ *
+ * Writes a tool’s JSON schema (input, output, or description) on-chain
+ * as an inscription, with optional compression.
+ *
+ * @category Types
+ * @since v0.1.0
+ * @see {@link SchemaType} for schema type discriminants.
+ * @see {@link CompressionType} for compression discriminants.
+ */
+export interface InscribeToolSchemaArgs {
+  /** Schema type discriminant (input / output / description). */
+  readonly schemaType: number;
+  /** Raw (optionally compressed) schema bytes. */
+  readonly schemaData: Buffer;
+  /** SHA-256 hash of the uncompressed schema. */
+  readonly schemaHash: number[]; // [u8; 32]
+  /** Compression algorithm discriminant. */
+  readonly compression: number;
+}
+
+// ═══════════════════════════════════════════════════════════════════
+//  Memory Vault Instructions
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @interface InscribeMemoryArgs
+ * @description Arguments for the `inscribeMemory` instruction.
+ *
+ * Writes an encrypted memory fragment into a vault session.
+ * Supports multi-fragment inscriptions and epoch-based partitioning.
+ *
+ * @category Types
+ * @since v0.1.0
+ */
+export interface InscribeMemoryArgs {
+  /** Sequence number within the session. */
+  readonly sequence: number;
+  /** NaCl-encrypted payload. */
+  readonly encryptedData: Buffer;
+  /** Encryption nonce (12 bytes). */
+  readonly nonce: number[];      // [u8; 12]
+  /** SHA-256 hash of the plaintext content. */
+  readonly contentHash: number[];// [u8; 32]
+  /** Total fragments in this inscription. */
+  readonly totalFragments: number;
+  /** Zero-based index of this fragment. */
+  readonly fragmentIndex: number;
+  /** Compression algorithm discriminant. */
+  readonly compression: number;
+  /** Target epoch index. */
+  readonly epochIndex: number;
+}
+
+/**
+ * @interface CompactInscribeArgs
+ * @description Arguments for the `compactInscribe` instruction.
+ *
+ * A simplified inscription variant that omits fragmentation and epoch
+ * fields — ideal for small, single-fragment payloads.
+ *
+ * @category Types
+ * @since v0.1.0
+ */
+export interface CompactInscribeArgs {
+  /** Sequence number within the session. */
+  readonly sequence: number;
+  /** NaCl-encrypted payload. */
+  readonly encryptedData: Buffer;
+  /** Encryption nonce (12 bytes). */
+  readonly nonce: number[];       // [u8; 12]
+  /** SHA-256 hash of the plaintext content. */
+  readonly contentHash: number[]; // [u8; 32]
+}
+
+// ═══════════════════════════════════════════════════════════════════
+//  Escrow Instructions
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @interface CreateEscrowArgs
+ * @description Arguments for the `createEscrow` instruction.
+ *
+ * Creates a pre-funded escrow account for micropayments to an agent,
+ * optionally with volume-based discount breakpoints.
+ *
+ * @category Types
+ * @since v0.1.0
+ * @see {@link VolumeCurveBreakpoint} for discount curve details.
+ */
+export interface CreateEscrowArgs {
+  /** Base price per call in token base units. */
+  readonly pricePerCall: BN;
+  /** Maximum number of calls the escrow should fund. */
+  readonly maxCalls: BN;
+  /** Initial deposit amount. */
+  readonly initialDeposit: BN;
+  /** Unix timestamp when the escrow expires. */
+  readonly expiresAt: BN;
+  /** Volume discount breakpoints (pass `[]` for none). */
+  readonly volumeCurve: VolumeCurveBreakpoint[];
+  /** SPL token mint (pass `null` for native SOL). */
+  readonly tokenMint: PublicKey | null;
+  /** Decimal places for the token. */
+  readonly tokenDecimals: number;
+}
+
+// ═══════════════════════════════════════════════════════════════════
+//  Attestation Instructions
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @interface CreateAttestationArgs
+ * @description Arguments for the `createAttestation` instruction.
+ *
+ * Issues a web-of-trust attestation for a target agent.
+ *
+ * @category Types
+ * @since v0.1.0
+ */
+export interface CreateAttestationArgs {
+  /** Freeform attestation type (e.g. `"kyc"`, `"audit"`). */
+  readonly attestationType: string;
+  /** SHA-256 hash of off-chain attestation metadata. */
+  readonly metadataHash: number[]; // [u8; 32]
+  /** Unix timestamp when the attestation expires. */
+  readonly expiresAt: BN;
+}
+
+// ═══════════════════════════════════════════════════════════════════
+//  Permission & Schema Helpers
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @name DelegatePermission
+ * @description Bitmask constants for vault delegate permissions.
+ *
+ * Combine with bitwise OR to grant multiple permissions.
+ *
+ * | Bit | Value | Permission          |
+ * | --- | ----- | ------------------- |
+ * | 0   | 1     | Inscribe memories   |
+ * | 1   | 2     | Close sessions      |
+ * | 2   | 4     | Open sessions       |
+ * | —   | 7     | All permissions     |
+ *
+ * @category Types
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * import { DelegatePermission } from "@synapse-sap/sdk";
+ *
+ * // Grant inscribe + open session
+ * const perms = DelegatePermission.Inscribe | DelegatePermission.OpenSession;
+ * ```
+ */
+export const DelegatePermission = {
+  Inscribe: 1,
+  CloseSession: 2,
+  OpenSession: 4,
+  All: 7,
+} as const;
+
+/**
+ * @name DelegatePermissionBit
+ * @description Union of valid {@link DelegatePermission} bit values.
+ */
+export type DelegatePermissionBit =
+  (typeof DelegatePermission)[keyof typeof DelegatePermission];
+
+/**
+ * @name SchemaType
+ * @description Numeric discriminants for tool schema types.
+ *
+ * Used in the `inscribeToolSchema` instruction to specify which schema
+ * is being written on-chain.
+ *
+ * @category Types
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * import { SchemaType } from "@synapse-sap/sdk";
+ *
+ * const args = { schemaType: SchemaType.Input, ... };
+ * ```
+ */
+export const SchemaType = {
+  Input: 0,
+  Output: 1,
+  Description: 2,
+} as const;
+
+/**
+ * @name SchemaTypeValue
+ * @description Union of valid {@link SchemaType} discriminant values.
+ */
+export type SchemaTypeValue = (typeof SchemaType)[keyof typeof SchemaType];
+
+/**
+ * @name CompressionType
+ * @description Numeric discriminants for compression algorithms.
+ *
+ * Used in inscription instructions to declare the compression format
+ * of the payload so consumers can decompress correctly.
+ *
+ * @category Types
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * import { CompressionType } from "@synapse-sap/sdk";
+ *
+ * const args = { compression: CompressionType.Gzip, ... };
+ * ```
+ */
+export const CompressionType = {
+  None: 0,
+  Deflate: 1,
+  Gzip: 2,
+  Brotli: 3,
+} as const;
+
+/**
+ * @name CompressionTypeValue
+ * @description Union of valid {@link CompressionType} discriminant values.
+ */
+export type CompressionTypeValue =
+  (typeof CompressionType)[keyof typeof CompressionType];

package/src/utils/hash.ts

@@ -0,0 +1,57 @@
+/**
+ * @module utils/hash
+ * @description Cryptographic hashing utilities.
+ *
+ * @category Utils
+ * @since v0.1.0
+ */
+
+import { createHash } from "crypto";
+
+/**
+ * Compute the SHA-256 hash of a UTF-8 string or byte buffer.
+ *
+ * Returns a 32-byte `Uint8Array` suitable for PDA seeds
+ * and Anchor instruction arguments.
+ *
+ * @name sha256
+ * @description Hashes the input using Node’s `crypto.createHash("sha256")`.
+ * @param input - A UTF-8 string, `Buffer`, or `Uint8Array` to hash.
+ * @returns {Uint8Array} 32-byte SHA-256 digest.
+ * @category Utils
+ * @since v0.1.0
+ * @example
+ * ```ts
+ * import { sha256 } from "@synapse-sap/sdk/utils";
+ *
+ * const hash = sha256("jupiter:swap"); // Uint8Array (32 bytes)
+ * ```
+ */
+export const sha256 = (input: string | Buffer | Uint8Array): Uint8Array => {
+  const hash = createHash("sha256");
+  hash.update(
+    typeof input === "string" ? Buffer.from(input, "utf-8") : input,
+  );
+  return new Uint8Array(hash.digest());
+};
+
+/**
+ * Convert a `Uint8Array` hash to a plain `number[]`.
+ *
+ * Anchor instruction argument types expect `number[]` for hash fields
+ * rather than typed arrays.
+ *
+ * @name hashToArray
+ * @description Converts a byte array (typically 32 bytes) to a plain JavaScript `number[]`.
+ * @param hash - The byte array to convert.
+ * @returns {number[]} Shallow copy as a plain array of numbers.
+ * @category Utils
+ * @since v0.1.0
+ * @example
+ * ```ts
+ * import { sha256, hashToArray } from "@synapse-sap/sdk/utils";
+ *
+ * const arr = hashToArray(sha256("jupiter:swap")); // number[]
+ * ```
+ */
+export const hashToArray = (hash: Uint8Array): number[] => Array.from(hash);

package/src/utils/index.ts

@@ -0,0 +1,19 @@
+/**
+ * @module utils
+ * @description Shared utilities used across SDK modules.
+ *
+ * @category Utils
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * import { sha256, hashToArray, assert } from "@synapse-sap/sdk/utils";
+ *
+ * const hash = sha256("jupiter:swap");
+ * const arr  = hashToArray(hash);      // number[] for Anchor args
+ * ```
+ */
+
+export { sha256, hashToArray } from "./hash";
+export { assert } from "./validation";
+export { serializeAccount, serializeValue } from "./serialization";

package/src/utils/serialization.ts

@@ -0,0 +1,98 @@
+/**
+ * @module utils/serialization
+ * @description JSON-safe serialization helpers for on-chain account data.
+ *
+ * On-chain Anchor account objects contain `PublicKey` and `BN` instances
+ * that are not JSON-serializable. These helpers convert them to plain
+ * strings (`base58` and decimal `string`) recursively.
+ *
+ * @category Utils
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * import { serializeAccount } from "@synapse-sap/sdk/utils";
+ *
+ * const raw = await program.account.agent.fetch(pda);
+ * const json = serializeAccount(raw);
+ * // { authority: "GBL...", totalCalls: "42", ... }
+ * ```
+ */
+
+import { PublicKey } from "@solana/web3.js";
+import BN from "bn.js";
+
+/**
+ * Recursively convert a single value for JSON serialization.
+ *
+ * - `PublicKey` → base58 string
+ * - `BN` → decimal string
+ * - `Uint8Array` / `Buffer` → hex string
+ * - `Array` → recursed
+ * - plain `object` → recursed via {@link serializeAccount}
+ * - primitives → identity
+ *
+ * @name serializeValue
+ * @description Transforms a single Anchor-typed value into its JSON-safe equivalent.
+ * @param value - The value to serialize.
+ * @returns The JSON-safe representation of `value`.
+ * @category Utils
+ * @since v0.1.0
+ * @example
+ * ```ts
+ * import { serializeValue } from "@synapse-sap/sdk/utils";
+ *
+ * serializeValue(new PublicKey("11111111111111111111111111111111")); // "1111..."
+ * serializeValue(new BN(42)); // "42"
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function serializeValue(value: unknown): any {
+  if (value === null || value === undefined) return null;
+  if (value instanceof PublicKey) return value.toBase58();
+  if (BN.isBN(value)) return value.toString();
+  if (value instanceof Uint8Array || Buffer.isBuffer(value))
+    return Buffer.from(value).toString("hex");
+  if (Array.isArray(value)) return value.map(serializeValue);
+  if (typeof value === "object") {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return serializeAccount(value as Record<string, any>);
+  }
+  return value;
+}
+
+/**
+ * Serialize an entire on-chain account object to a JSON-safe shape.
+ *
+ * Iterates over each key and delegates to {@link serializeValue}.
+ * Handles `PublicKey` → base58, `BN` → string, and nested
+ * objects / arrays recursively.
+ *
+ * @name serializeAccount
+ * @description Converts all non-primitive fields in an Anchor account record to JSON-safe strings.
+ * @param obj - The raw account object returned by `program.account.<name>.fetch()`.
+ * @returns A new plain object with all values converted.
+ * @category Utils
+ * @since v0.1.0
+ * @example
+ * ```ts
+ * import { serializeAccount } from "@synapse-sap/sdk/utils";
+ *
+ * const raw = await program.account.agent.fetch(pda);
+ * const safe = serializeAccount(raw);
+ * console.log(JSON.stringify(safe));
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function serializeAccount(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  obj: Record<string, any>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): Record<string, any> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const result: Record<string, any> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    result[key] = serializeValue(value);
+  }
+  return result;
+}

package/src/utils/validation.ts

@@ -0,0 +1,36 @@
+/**
+ * @module utils/validation
+ * @description Runtime assertion helpers.
+ *
+ * @category Utils
+ * @since v0.1.0
+ */
+
+/**
+ * Assert that a condition holds, throwing a descriptive error otherwise.
+ *
+ * Uses TypeScript’s `asserts condition` return type so the compiler
+ * narrows the guarded value after the call.
+ *
+ * @name assert
+ * @description Runtime guard — throws `RangeError` with a `[SAP SDK]` prefix when the condition is falsy.
+ * @param condition - The boolean expression to verify.
+ * @param message   - Human-readable message included in the thrown error.
+ * @throws {RangeError} When `condition` is `false`.
+ * @category Utils
+ * @since v0.1.0
+ * @example
+ * ```ts
+ * import { assert } from "@synapse-sap/sdk/utils";
+ *
+ * assert(name.length <= 64, "Agent name exceeds MAX_NAME_LEN");
+ * ```
+ */
+export function assert(
+  condition: boolean,
+  message: string,
+): asserts condition {
+  if (!condition) {
+    throw new RangeError(`[SAP SDK] ${message}`);
+  }
+}