@oobe-protocol-labs/synapse-sap-sdk 0.14.0 → 0.15.0

package/dist/esm/utils/endpoint-validator.js

@@ -0,0 +1,226 @@
+/**
+ * @module utils/endpoint-validator
+ * @description Endpoint validation utilities for SAP agent discovery.
+ *
+ * Fetches advertised endpoints and verifies they respond with JSON,
+ * proper CORS headers, and SAP-compatible behavior. Designed to
+ * fail fast when an endpoint 404s, requires CSRF tokens, or
+ * serves HTML instead of JSON.
+ *
+ * Used by:
+ *   - CLI `discovery validate` command
+ *   - SDK programmatic validation before x402 calls
+ *   - Integration test harnesses
+ *
+ * @category Utils
+ * @since v0.6.0
+ */
+// ═══════════════════════════════════════════════════════════════════
+//  Core Validator
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name validateEndpoint
+ * @description Validate a single endpoint URL for SAP compatibility.
+ *
+ * Performs the following checks:
+ *   1. URL is reachable (no 4xx/5xx)
+ *   2. Response Content-Type is JSON
+ *   3. CORS headers are present (if checkCors enabled)
+ *   4. No redirect to HTML login pages
+ *   5. Measures response latency
+ *
+ * @param url - The endpoint URL to validate.
+ * @param opts - Validation options.
+ * @returns An {@link EndpointValidationResult} with detailed check results.
+ *
+ * @category Utils
+ * @since v0.6.0
+ *
+ * @example
+ * ```ts
+ * const result = await validateEndpoint("https://api.example.com/x402");
+ * if (!result.reachable) console.error(result.error);
+ * ```
+ */
+export async function validateEndpoint(url, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 10_000;
+    const retries = opts.retries ?? 1;
+    const method = opts.method ?? "HEAD";
+    const warnings = [];
+    let lastError;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        try {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            const start = Date.now();
+            const response = await fetch(url, {
+                method,
+                signal: controller.signal,
+                headers: {
+                    Accept: "application/json",
+                    ...(opts.headers ?? {}),
+                },
+                redirect: "follow",
+            });
+            clearTimeout(timer);
+            const latencyMs = Date.now() - start;
+            const contentType = response.headers.get("content-type") ?? "";
+            const isJson = contentType.includes("application/json") || contentType.includes("text/json");
+            const hasCors = !!response.headers.get("access-control-allow-origin");
+            // Check for HTML responses (login pages, CSRF gates)
+            if (contentType.includes("text/html")) {
+                warnings.push("Endpoint returns HTML — may require CSRF or browser session");
+            }
+            // Check for redirect chains
+            if (response.redirected) {
+                warnings.push(`Endpoint redirected to ${response.url}`);
+            }
+            // Check for common error statuses
+            if (response.status === 403) {
+                warnings.push("403 Forbidden — may require authentication or CSRF tokens");
+            }
+            if (response.status === 404) {
+                warnings.push("404 Not Found — endpoint URL may be incorrect");
+            }
+            if (response.status === 405) {
+                warnings.push(`405 Method Not Allowed — endpoint may not accept ${method}`);
+            }
+            // Determine SAP capability
+            const isSapCapable = isJson &&
+                response.status < 400 &&
+                !contentType.includes("text/html");
+            // CORS check if requested
+            if (opts.checkCors && !hasCors) {
+                warnings.push("No CORS headers — cross-origin requests will fail");
+            }
+            return {
+                url,
+                reachable: response.status < 500,
+                statusCode: response.status,
+                latencyMs,
+                isJson,
+                hasCors,
+                isSapCapable,
+                error: response.status >= 400
+                    ? `HTTP ${response.status}: ${response.statusText}`
+                    : undefined,
+                warnings,
+            };
+        }
+        catch (err) {
+            lastError =
+                err instanceof Error ? err.message : String(err);
+            if (attempt < retries)
+                continue;
+        }
+    }
+    return {
+        url,
+        reachable: false,
+        statusCode: 0,
+        latencyMs: 0,
+        isJson: false,
+        hasCors: false,
+        isSapCapable: false,
+        error: lastError ?? "Unknown error",
+        warnings,
+    };
+}
+/**
+ * @name validateEndpointDescriptor
+ * @description Validate an {@link EndpointDescriptor} with context-aware checks.
+ *
+ * Uses the descriptor's method, auth requirements, and other metadata to
+ * perform a more targeted validation than raw URL checking.
+ *
+ * @param descriptor - The endpoint descriptor to validate.
+ * @param opts - Additional options.
+ * @returns An {@link EndpointValidationResult}.
+ *
+ * @category Utils
+ * @since v0.6.0
+ */
+export async function validateEndpointDescriptor(descriptor, opts = {}) {
+    const headers = {
+        ...(opts.headers ?? {}),
+        ...(descriptor.requiredHeaders ?? {}),
+    };
+    // Use the descriptor's method, falling back to HEAD for safety
+    const method = opts.method ?? (descriptor.method === "GET" ? "GET" : "HEAD");
+    const result = await validateEndpoint(descriptor.url, {
+        ...opts,
+        method,
+        headers,
+    });
+    // Add descriptor-specific warnings
+    const warnings = [...result.warnings];
+    if (descriptor.requiresCSRF) {
+        warnings.push("Endpoint declares requiresCSRF — automated calls may need token management");
+    }
+    if (descriptor.requiresCookies) {
+        warnings.push("Endpoint declares requiresCookies — stateless calls may fail");
+    }
+    if (descriptor.requiresAuth && !descriptor.authType) {
+        warnings.push("Endpoint requires auth but no authType specified");
+    }
+    return { ...result, warnings };
+}
+/**
+ * @name validateHealthCheck
+ * @description Validate an agent's health-check endpoint.
+ *
+ * @param health - The health-check descriptor.
+ * @returns An {@link EndpointValidationResult}.
+ *
+ * @category Utils
+ * @since v0.6.0
+ */
+export async function validateHealthCheck(health) {
+    const result = await validateEndpoint(health.url, {
+        timeoutMs: health.timeoutMs,
+        method: health.method ?? "GET",
+    });
+    const warnings = [...result.warnings];
+    if (result.reachable && result.statusCode !== health.expectedStatus) {
+        warnings.push(`Expected status ${health.expectedStatus}, got ${result.statusCode}`);
+    }
+    return {
+        ...result,
+        isSapCapable: result.reachable && result.statusCode === health.expectedStatus,
+        warnings,
+    };
+}
+/**
+ * @name validateAgentEndpoints
+ * @description Validate all endpoints for an agent (primary + health + tool overrides).
+ *
+ * @param params - Object containing the endpoints to validate.
+ * @param params.endpoint - Primary endpoint descriptor.
+ * @param params.healthCheck - Optional health-check descriptor.
+ * @param params.toolEndpoints - Optional array of tool-specific endpoint overrides.
+ * @param opts - Validation options.
+ * @returns A map of `label → EndpointValidationResult`.
+ *
+ * @category Utils
+ * @since v0.6.0
+ */
+export async function validateAgentEndpoints(params, opts = {}) {
+    const results = new Map();
+    // Validate primary endpoint
+    const primary = await validateEndpointDescriptor(params.endpoint, opts);
+    results.set("primary", primary);
+    // Validate health check
+    if (params.healthCheck) {
+        const health = await validateHealthCheck(params.healthCheck);
+        results.set("health", health);
+    }
+    // Validate tool-specific endpoints
+    if (params.toolEndpoints) {
+        for (const { name, endpoint } of params.toolEndpoints) {
+            const toolResult = await validateEndpointDescriptor(endpoint, opts);
+            results.set(`tool:${name}`, toolResult);
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=endpoint-validator.js.map

package/dist/esm/utils/endpoint-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint-validator.js","sourceRoot":"","sources":["../../../src/utils/endpoint-validator.ts"],"names":[],"mappings":"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"}

package/dist/esm/utils/escrow-validation.d.ts

@@ -0,0 +1,145 @@
+/**
+ * @module utils/escrow-validation
+ * @description Server-side escrow validation pipeline.
+ *
+ * Provides typed helpers to validate escrow state before settlement
+ * and to build the correct SPL `AccountMeta[]` for token escrows.
+ *
+ * @category Utils
+ * @since v0.6.4
+ */
+import { PublicKey, type Connection, type AccountMeta } from "@solana/web3.js";
+import { SapError } from "../errors";
+import type { EscrowAccountData } from "../types";
+/**
+ * @interface SplAccountMeta
+ * @description Typed SPL account metadata for escrow operations.
+ * @category Utils
+ * @since v0.6.4
+ */
+export interface SplAccountMeta {
+    /** Account role in the escrow pipeline. */
+    readonly kind: "escrowAta" | "depositorAta" | "tokenMint" | "tokenProgram";
+    /** Account public key. */
+    readonly pubkey: PublicKey;
+    /** Whether this account is writable. */
+    readonly writable: boolean;
+}
+/**
+ * @interface EscrowValidationResult
+ * @description Result of server-side escrow state validation.
+ * @category Utils
+ * @since v0.6.4
+ */
+export interface EscrowValidationResult {
+    /** Whether the escrow is valid for settlement. */
+    readonly valid: boolean;
+    /** Escrow account data (if found). */
+    readonly escrow: EscrowAccountData | null;
+    /** Escrow PDA address. */
+    readonly escrowPda: PublicKey;
+    /** Agent PDA address. */
+    readonly agentPda: PublicKey;
+    /** Whether this is an SPL token escrow (vs SOL). */
+    readonly isSplEscrow: boolean;
+    /** Generated SPL account metas (empty for SOL escrows). */
+    readonly splAccounts: SplAccountMeta[];
+    /** Validation errors (empty when valid). */
+    readonly errors: string[];
+}
+/**
+ * @name MissingEscrowAtaError
+ * @description Thrown when an SPL escrow operation is missing required
+ * Associated Token Accounts.
+ * @category Errors
+ * @since v0.6.4
+ */
+export declare class MissingEscrowAtaError extends SapError {
+    /** The ATA address that is missing. */
+    readonly ataAddress: string;
+    /** Which side is missing: depositor or escrow. */
+    readonly side: "depositor" | "escrow";
+    constructor(ataAddress: string, side: "depositor" | "escrow");
+}
+/**
+ * @name validateEscrowState
+ * @description Validates that an escrow is in a correct state for settlement.
+ *
+ * Checks:
+ * - Escrow PDA exists on-chain
+ * - If SPL: depositor ATA exists, escrow ATA exists, token mint matches
+ * - Balance >= requested settlement amount
+ * - Escrow is not expired
+ * - Max calls not exceeded
+ *
+ * @param connection  - Solana RPC connection.
+ * @param agentWallet - The agent's wallet public key.
+ * @param depositorWallet - The depositor's wallet public key.
+ * @param fetchEscrow - Callback to fetch escrow data (avoids coupling to SapProgram).
+ * @param opts
+ * @param opts.callsToSettle - Number of calls to validate affordability for.
+ *
+ * @returns A detailed {@link EscrowValidationResult}.
+ *
+ * @category Utils
+ * @since v0.6.4
+ *
+ * @example
+ * ```ts
+ * const result = await validateEscrowState(
+ *   connection,
+ *   agentWallet,
+ *   depositorWallet,
+ *   (pda) => client.escrow.fetchByPda(pda),
+ *   { callsToSettle: 5 },
+ * );
+ *
+ * if (!result.valid) {
+ *   console.error("Escrow validation failed:", result.errors);
+ * }
+ * ```
+ */
+export declare function validateEscrowState(connection: Connection, agentWallet: PublicKey, depositorWallet: PublicKey, fetchEscrow: (escrowPda: PublicKey) => Promise<EscrowAccountData | null>, opts?: {
+    callsToSettle?: number;
+}): Promise<EscrowValidationResult>;
+/**
+ * @name attachSplAccounts
+ * @description Build the typed `SplAccountMeta[]` for an SPL token escrow operation.
+ * Does NOT validate existence — use {@link validateEscrowState} for full validation.
+ *
+ * @param escrowPda      - The escrow PDA address.
+ * @param depositorWallet - The depositor's wallet public key.
+ * @param tokenMint      - The SPL token mint.
+ * @returns An array of typed {@link SplAccountMeta} for SPL escrow operations.
+ *
+ * @category Utils
+ * @since v0.6.4
+ *
+ * @example
+ * ```ts
+ * const splMetas = attachSplAccounts(escrowPda, depositorWallet, usdcMint);
+ *
+ * // Convert to Anchor-compatible AccountMeta[]
+ * const accountMetas = splMetas.map(m => ({
+ *   pubkey: m.pubkey,
+ *   isWritable: m.writable,
+ *   isSigner: false,
+ * }));
+ *
+ * await client.escrow.settle(depositor, calls, hash, accountMetas);
+ * ```
+ */
+export declare function attachSplAccounts(escrowPda: PublicKey, depositorWallet: PublicKey, tokenMint: PublicKey): SplAccountMeta[];
+/**
+ * @name toAccountMetas
+ * @description Convert typed {@link SplAccountMeta} to Anchor-compatible
+ * `AccountMeta[]` for use with `.remainingAccounts()`.
+ *
+ * @param splMetas - Array of typed SPL account metas.
+ * @returns `AccountMeta[]` compatible with Anchor's `remainingAccounts`.
+ *
+ * @category Utils
+ * @since v0.6.4
+ */
+export declare function toAccountMetas(splMetas: SplAccountMeta[]): AccountMeta[];
+//# sourceMappingURL=escrow-validation.d.ts.map

package/dist/esm/utils/escrow-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escrow-validation.d.ts","sourceRoot":"","sources":["../../../src/utils/escrow-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,SAAS,EACT,KAAK,UAAU,EACf,KAAK,WAAW,EACjB,MAAM,iBAAiB,CAAC;AAIzB,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAMlD;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,cAAc,GAAG,WAAW,GAAG,cAAc,CAAC;IAC3E,0BAA0B;IAC1B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,sCAAsC;IACtC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC1C,0BAA0B;IAC1B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,yBAAyB;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,oDAAoD;IACpD,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,EAAE,cAAc,EAAE,CAAC;IACvC,4CAA4C;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;CAC3B;AAMD;;;;;;GAMG;AACH,qBAAa,qBAAsB,SAAQ,QAAQ;IACjD,uCAAuC;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,QAAQ,CAAC;gBAE1B,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,QAAQ;CAU7D;AASD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,UAAU,EACtB,WAAW,EAAE,SAAS,EACtB,eAAe,EAAE,SAAS,EAC1B,WAAW,EAAE,CAAC,SAAS,EAAE,SAAS,KAAK,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,EACxE,IAAI,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GAChC,OAAO,CAAC,sBAAsB,CAAC,CAgGjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,SAAS,EACpB,eAAe,EAAE,SAAS,EAC1B,SAAS,EAAE,SAAS,GACnB,cAAc,EAAE,CAOlB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,WAAW,EAAE,CAMxE"}

package/dist/esm/utils/escrow-validation.js

@@ -0,0 +1,212 @@
+/**
+ * @module utils/escrow-validation
+ * @description Server-side escrow validation pipeline.
+ *
+ * Provides typed helpers to validate escrow state before settlement
+ * and to build the correct SPL `AccountMeta[]` for token escrows.
+ *
+ * @category Utils
+ * @since v0.6.4
+ */
+import { PublicKey, } from "@solana/web3.js";
+import { BN } from "@coral-xyz/anchor";
+import { findATA } from "./rpc-strategy";
+import { deriveAgent, deriveEscrow } from "../pda";
+import { SapError } from "../errors";
+// ═══════════════════════════════════════════════════════════════════
+//  Error
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name MissingEscrowAtaError
+ * @description Thrown when an SPL escrow operation is missing required
+ * Associated Token Accounts.
+ * @category Errors
+ * @since v0.6.4
+ */
+export class MissingEscrowAtaError extends SapError {
+    /** The ATA address that is missing. */
+    ataAddress;
+    /** Which side is missing: depositor or escrow. */
+    side;
+    constructor(ataAddress, side) {
+        super(`Missing ${side} ATA: ${ataAddress}. ` +
+            `Settlement mode is Escrow/SPL but the Associated Token Account does not exist. ` +
+            `The ${side} must create the ATA before escrow operations.`);
+        this.name = "MissingEscrowAtaError";
+        this.ataAddress = ataAddress;
+        this.side = side;
+    }
+}
+// ═══════════════════════════════════════════════════════════════════
+//  Validation
+// ═══════════════════════════════════════════════════════════════════
+/** Standard SPL Token program ID. */
+const TOKEN_PROGRAM_ID_STR = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
+/**
+ * @name validateEscrowState
+ * @description Validates that an escrow is in a correct state for settlement.
+ *
+ * Checks:
+ * - Escrow PDA exists on-chain
+ * - If SPL: depositor ATA exists, escrow ATA exists, token mint matches
+ * - Balance >= requested settlement amount
+ * - Escrow is not expired
+ * - Max calls not exceeded
+ *
+ * @param connection  - Solana RPC connection.
+ * @param agentWallet - The agent's wallet public key.
+ * @param depositorWallet - The depositor's wallet public key.
+ * @param fetchEscrow - Callback to fetch escrow data (avoids coupling to SapProgram).
+ * @param opts
+ * @param opts.callsToSettle - Number of calls to validate affordability for.
+ *
+ * @returns A detailed {@link EscrowValidationResult}.
+ *
+ * @category Utils
+ * @since v0.6.4
+ *
+ * @example
+ * ```ts
+ * const result = await validateEscrowState(
+ *   connection,
+ *   agentWallet,
+ *   depositorWallet,
+ *   (pda) => client.escrow.fetchByPda(pda),
+ *   { callsToSettle: 5 },
+ * );
+ *
+ * if (!result.valid) {
+ *   console.error("Escrow validation failed:", result.errors);
+ * }
+ * ```
+ */
+export async function validateEscrowState(connection, agentWallet, depositorWallet, fetchEscrow, opts) {
+    const [agentPda] = deriveAgent(agentWallet);
+    const [escrowPda] = deriveEscrow(agentPda, depositorWallet);
+    const errors = [];
+    // 1. Fetch escrow
+    const escrow = await fetchEscrow(escrowPda);
+    if (!escrow) {
+        return {
+            valid: false,
+            escrow: null,
+            escrowPda,
+            agentPda,
+            isSplEscrow: false,
+            splAccounts: [],
+            errors: [`Escrow not found at ${escrowPda.toBase58()}`],
+        };
+    }
+    // 2. Check expiry
+    if (escrow.expiresAt.gt(new BN(0))) {
+        const now = Math.floor(Date.now() / 1000);
+        if (escrow.expiresAt.lt(new BN(now))) {
+            errors.push(`Escrow expired at ${escrow.expiresAt.toString()}`);
+        }
+    }
+    // 3. Check balance / calls
+    const callsToSettle = opts?.callsToSettle ?? 1;
+    const costForCalls = escrow.pricePerCall.mul(new BN(callsToSettle));
+    if (escrow.balance.lt(costForCalls)) {
+        errors.push(`Insufficient balance: ${escrow.balance.toString()} < ${costForCalls.toString()} (${callsToSettle} calls × ${escrow.pricePerCall.toString()})`);
+    }
+    // 4. Check max calls
+    if (escrow.maxCalls.gt(new BN(0))) {
+        const remaining = escrow.maxCalls.sub(escrow.totalCallsSettled);
+        if (remaining.lt(new BN(callsToSettle))) {
+            errors.push(`Max calls exceeded: ${remaining.toString()} remaining but needs ${callsToSettle}`);
+        }
+    }
+    // 5. Determine if SPL
+    const isSplEscrow = escrow.tokenMint !== null &&
+        escrow.tokenMint.toBase58() !== "11111111111111111111111111111111";
+    // 6. Build SPL accounts (if SPL escrow)
+    const splAccounts = [];
+    if (isSplEscrow) {
+        const mint = escrow.tokenMint;
+        const depositorAta = findATA(depositorWallet, mint);
+        const escrowAta = findATA(escrowPda, mint);
+        // Verify depositor ATA exists
+        const depositorAtaInfo = await connection.getAccountInfo(depositorAta);
+        if (!depositorAtaInfo) {
+            errors.push(`Depositor ATA does not exist: ${depositorAta.toBase58()}`);
+        }
+        // Verify escrow ATA exists
+        const escrowAtaInfo = await connection.getAccountInfo(escrowAta);
+        if (!escrowAtaInfo) {
+            errors.push(`Escrow ATA does not exist: ${escrowAta.toBase58()}`);
+        }
+        // Verify mint matches
+        if (depositorAtaInfo) {
+            // SPL token account data: bytes 0-32 = mint
+            const ataMint = depositorAtaInfo.data.subarray(0, 32);
+            if (Buffer.from(ataMint).toString("hex") !== mint.toBuffer().toString("hex")) {
+                errors.push(`Depositor ATA mint mismatch: expected ${mint.toBase58()}`);
+            }
+        }
+        splAccounts.push({ kind: "depositorAta", pubkey: depositorAta, writable: true }, { kind: "escrowAta", pubkey: escrowAta, writable: true }, { kind: "tokenMint", pubkey: mint, writable: false }, { kind: "tokenProgram", pubkey: new PublicKey(TOKEN_PROGRAM_ID_STR), writable: false });
+    }
+    return {
+        valid: errors.length === 0,
+        escrow,
+        escrowPda,
+        agentPda,
+        isSplEscrow,
+        splAccounts,
+        errors,
+    };
+}
+/**
+ * @name attachSplAccounts
+ * @description Build the typed `SplAccountMeta[]` for an SPL token escrow operation.
+ * Does NOT validate existence — use {@link validateEscrowState} for full validation.
+ *
+ * @param escrowPda      - The escrow PDA address.
+ * @param depositorWallet - The depositor's wallet public key.
+ * @param tokenMint      - The SPL token mint.
+ * @returns An array of typed {@link SplAccountMeta} for SPL escrow operations.
+ *
+ * @category Utils
+ * @since v0.6.4
+ *
+ * @example
+ * ```ts
+ * const splMetas = attachSplAccounts(escrowPda, depositorWallet, usdcMint);
+ *
+ * // Convert to Anchor-compatible AccountMeta[]
+ * const accountMetas = splMetas.map(m => ({
+ *   pubkey: m.pubkey,
+ *   isWritable: m.writable,
+ *   isSigner: false,
+ * }));
+ *
+ * await client.escrow.settle(depositor, calls, hash, accountMetas);
+ * ```
+ */
+export function attachSplAccounts(escrowPda, depositorWallet, tokenMint) {
+    return [
+        { kind: "depositorAta", pubkey: findATA(depositorWallet, tokenMint), writable: true },
+        { kind: "escrowAta", pubkey: findATA(escrowPda, tokenMint), writable: true },
+        { kind: "tokenMint", pubkey: tokenMint, writable: false },
+        { kind: "tokenProgram", pubkey: new PublicKey(TOKEN_PROGRAM_ID_STR), writable: false },
+    ];
+}
+/**
+ * @name toAccountMetas
+ * @description Convert typed {@link SplAccountMeta} to Anchor-compatible
+ * `AccountMeta[]` for use with `.remainingAccounts()`.
+ *
+ * @param splMetas - Array of typed SPL account metas.
+ * @returns `AccountMeta[]` compatible with Anchor's `remainingAccounts`.
+ *
+ * @category Utils
+ * @since v0.6.4
+ */
+export function toAccountMetas(splMetas) {
+    return splMetas.map((m) => ({
+        pubkey: m.pubkey,
+        isWritable: m.writable,
+        isSigner: false,
+    }));
+}
+//# sourceMappingURL=escrow-validation.js.map

package/dist/esm/utils/escrow-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escrow-validation.js","sourceRoot":"","sources":["../../../src/utils/escrow-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,SAAS,GAGV,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,EAAE,EAAE,MAAM,mBAAmB,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AA6CrC,sEAAsE;AACtE,SAAS;AACT,sEAAsE;AAEtE;;;;;;GAMG;AACH,MAAM,OAAO,qBAAsB,SAAQ,QAAQ;IACjD,uCAAuC;IAC9B,UAAU,CAAS;IAC5B,kDAAkD;IACzC,IAAI,CAAyB;IAEtC,YAAY,UAAkB,EAAE,IAA4B;QAC1D,KAAK,CACH,WAAW,IAAI,SAAS,UAAU,IAAI;YACpC,iFAAiF;YACjF,OAAO,IAAI,gDAAgD,CAC9D,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,sEAAsE;AACtE,cAAc;AACd,sEAAsE;AAEtE,qCAAqC;AACrC,MAAM,oBAAoB,GAAG,6CAA6C,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,UAAsB,EACtB,WAAsB,EACtB,eAA0B,EAC1B,WAAwE,EACxE,IAAiC;IAEjC,MAAM,CAAC,QAAQ,CAAC,GAAG,WAAW,CAAC,WAAW,CAAC,CAAC;IAC5C,MAAM,CAAC,SAAS,CAAC,GAAG,YAAY,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;IAC5D,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,kBAAkB;IAClB,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,SAAS,CAAC,CAAC;IAC5C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,MAAM,EAAE,IAAI;YACZ,SAAS;YACT,QAAQ;YACR,WAAW,EAAE,KAAK;YAClB,WAAW,EAAE,EAAE;YACf,MAAM,EAAE,CAAC,uBAAuB,SAAS,CAAC,QAAQ,EAAE,EAAE,CAAC;SACxD,CAAC;IACJ,CAAC;IAED,kBAAkB;IAClB,IAAI,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACnC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;QAC1C,IAAI,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YACrC,MAAM,CAAC,IAAI,CAAC,qBAAqB,MAAM,CAAC,SAAS,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QAClE,CAAC;IACH,CAAC;IAED,2BAA2B;IAC3B,MAAM,aAAa,GAAG,IAAI,EAAE,aAAa,IAAI,CAAC,CAAC;IAC/C,MAAM,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC;IACpE,IAAI,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC;QACpC,MAAM,CAAC,IAAI,CACT,yBAAyB,MAAM,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,YAAY,CAAC,QAAQ,EAAE,KAAK,aAAa,YAAY,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,GAAG,CAC/I,CAAC;IACJ,CAAC;IAED,qBAAqB;IACrB,IAAI,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAClC,MAAM,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;QAChE,IAAI,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC;YACxC,MAAM,CAAC,IAAI,CACT,uBAAuB,SAAS,CAAC,QAAQ,EAAE,wBAAwB,aAAa,EAAE,CACnF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,sBAAsB;IACtB,MAAM,WAAW,GACf,MAAM,CAAC,SAAS,KAAK,IAAI;QACzB,MAAM,CAAC,SAAS,CAAC,QAAQ,EAAE,KAAK,kCAAkC,CAAC;IAErE,wCAAwC;IACxC,MAAM,WAAW,GAAqB,EAAE,CAAC;IACzC,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,IAAI,GAAG,MAAM,CAAC,SAAU,CAAC;QAC/B,MAAM,YAAY,GAAG,OAAO,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC;QACpD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QAE3C,8BAA8B;QAC9B,MAAM,gBAAgB,GAAG,MAAM,UAAU,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;QACvE,IAAI,CAAC,gBAAgB,EAAE,CAAC;YACtB,MAAM,CAAC,IAAI,CAAC,iCAAiC,YAAY,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QAC1E,CAAC;QAED,2BAA2B;QAC3B,MAAM,aAAa,GAAG,MAAM,UAAU,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;QACjE,IAAI,CAAC,aAAa,EAAE,CAAC;YACnB,MAAM,CAAC,IAAI,CAAC,8BAA8B,SAAS,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QACpE,CAAC;QAED,sBAAsB;QACtB,IAAI,gBAAgB,EAAE,CAAC;YACrB,4CAA4C;YAC5C,MAAM,OAAO,GAAG,gBAAgB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACtD,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC7E,MAAM,CAAC,IAAI,CAAC,yCAAyC,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;YAC1E,CAAC;QACH,CAAC;QAED,WAAW,CAAC,IAAI,CACd,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,EAC9D,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,EACxD,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,EACpD,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,IAAI,SAAS,CAAC,oBAAoB,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CACvF,CAAC;IACJ,CAAC;IAED,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC;QAC1B,MAAM;QACN,SAAS;QACT,QAAQ;QACR,WAAW;QACX,WAAW;QACX,MAAM;KACP,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,iBAAiB,CAC/B,SAAoB,EACpB,eAA0B,EAC1B,SAAoB;IAEpB,OAAO;QACL,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,OAAO,CAAC,eAAe,EAAE,SAAS,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE;QACrF,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE;QAC5E,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE;QACzD,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,IAAI,SAAS,CAAC,oBAAoB,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE;KACvF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAC,QAA0B;IACvD,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC1B,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,UAAU,EAAE,CAAC,CAAC,QAAQ;QACtB,QAAQ,EAAE,KAAK;KAChB,CAAC,CAAC,CAAC;AACN,CAAC"}

package/dist/esm/utils/hash.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @module utils/hash
+ * @description Cryptographic hashing utilities.
+ *
+ * @category Utils
+ * @since v0.1.0
+ */
+/**
+ * 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 declare const sha256: (input: string | Buffer | Uint8Array) => Uint8Array;
+/**
+ * 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 declare const hashToArray: (hash: Uint8Array) => number[];
+/**
+ * Compute the deterministic batch root used by `settle_batch` (v0.10.0).
+ *
+ * The on-chain program enforces:
+ *   `batch_root == sha256(s_0 || s_1 || ... || s_{N-1})`
+ * where each `s_i` is a 32-byte service hash, in the same order as the
+ * `settlements: Settlement[]` array passed to the instruction.
+ *
+ * Use this helper to derive the seed for the {@link deriveSettlementReceipt}
+ * PDA when batching settlements.
+ *
+ * @name computeBatchRoot
+ * @param serviceHashes - Array of 32-byte service hashes (Buffer/Uint8Array/number[]).
+ * @returns {Uint8Array} 32-byte batch root.
+ * @throws If any `serviceHashes[i]` is not exactly 32 bytes long.
+ * @category Utils
+ * @since v0.10.0
+ *
+ * @example
+ * ```ts
+ * import { computeBatchRoot, hashToArray } from "@synapse-sap/sdk/utils";
+ *
+ * const root = computeBatchRoot([h1, h2, h3]);
+ * await client.escrow.settleBatch(depositor, settlements, root);
+ * ```
+ */
+export declare const computeBatchRoot: (serviceHashes: ReadonlyArray<Uint8Array | Buffer | number[]>) => Uint8Array;
+//# sourceMappingURL=hash.d.ts.map