@oobe-protocol-labs/synapse-sap-sdk 0.4.2 → 0.6.0

package/dist/esm/utils/rpc-strategy.js

@@ -0,0 +1,231 @@
+/**
+ * @module utils/rpc-strategy
+ * @description Dual-connection RPC strategy and idempotent ATA creation.
+ *
+ * Solves two interoperability problems:
+ *
+ * 1. **WebSocket 400 loop**: Some authenticated RPCs reject WebSocket
+ *    connections for SPL token operations. This module exposes a
+ *    dual-connection strategy: primary RPC for SAP program calls,
+ *    fallback public RPC for token operations.
+ *
+ * 2. **Idempotent ATA creation**: Wraps `getOrCreateAssociatedTokenAccount`
+ *    with retries so "account already exists" doesn't surface as a
+ *    hard error.
+ *
+ * @category Utils
+ * @since v0.6.0
+ */
+import { Connection, PublicKey, } from "@solana/web3.js";
+// ═══════════════════════════════════════════════════════════════════
+//  Default Public RPCs
+// ═══════════════════════════════════════════════════════════════════
+/** Well-known public fallback RPCs by cluster. */
+const PUBLIC_RPCS = {
+    "mainnet-beta": "https://api.mainnet-beta.solana.com",
+    devnet: "https://api.devnet.solana.com",
+    localnet: "http://localhost:8899",
+};
+// ═══════════════════════════════════════════════════════════════════
+//  Public API
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name getRpcUrl
+ * @description Get the primary RPC URL from environment or config.
+ *
+ * Resolution order:
+ *   1. Explicit `config.primaryUrl`
+ *   2. `SOLANA_RPC_URL` env var
+ *   3. Cluster-appropriate public RPC
+ *
+ * @param config - Optional RPC configuration.
+ * @param cluster - Cluster hint (defaults to "mainnet-beta").
+ * @returns The resolved primary RPC URL.
+ *
+ * @category Utils
+ * @since v0.6.0
+ */
+export function getRpcUrl(config, cluster = "mainnet-beta") {
+    if (config?.primaryUrl)
+        return config.primaryUrl;
+    // Environment variable
+    const envUrl = typeof process !== "undefined" ? process.env?.SOLANA_RPC_URL : undefined;
+    if (envUrl)
+        return envUrl;
+    return PUBLIC_RPCS[cluster] ?? PUBLIC_RPCS["mainnet-beta"];
+}
+/**
+ * @name getFallbackRpcUrl
+ * @description Get the fallback RPC URL for SPL token operations.
+ *
+ * This avoids the WebSocket-400 loop when the primary RPC is
+ * an authenticated endpoint that rejects token-related WebSocket
+ * subscriptions.
+ *
+ * @param config - Optional RPC configuration.
+ * @param cluster - Cluster hint (defaults to "mainnet-beta").
+ * @returns The resolved fallback RPC URL.
+ *
+ * @category Utils
+ * @since v0.6.0
+ */
+export function getFallbackRpcUrl(config, cluster = "mainnet-beta") {
+    if (config?.fallbackUrl)
+        return config.fallbackUrl;
+    // Env fallback
+    const envUrl = typeof process !== "undefined"
+        ? process.env?.SOLANA_FALLBACK_RPC_URL
+        : undefined;
+    if (envUrl)
+        return envUrl;
+    return PUBLIC_RPCS[cluster] ?? PUBLIC_RPCS["mainnet-beta"];
+}
+/**
+ * @name createDualConnection
+ * @description Create a dual-connection pair: primary for SAP program calls,
+ * fallback for SPL token operations.
+ *
+ * @param config - RPC configuration.
+ * @param cluster - Cluster hint.
+ * @returns A {@link DualConnection} with both connections.
+ *
+ * @category Utils
+ * @since v0.6.0
+ *
+ * @example
+ * ```ts
+ * const { primary, fallback } = createDualConnection({
+ *   primaryUrl: "https://my-rpc.example.com",
+ * }, "mainnet-beta");
+ *
+ * // Use primary for SAP calls
+ * const provider = new AnchorProvider(primary, wallet, {});
+ *
+ * // Use fallback for SPL token account creation
+ * const ata = await getOrCreateATA(fallback, mint, owner);
+ * ```
+ */
+export function createDualConnection(config, cluster = "mainnet-beta") {
+    const commitment = config.commitment ?? "confirmed";
+    const primaryUrl = getRpcUrl(config, cluster);
+    const fallbackUrl = getFallbackRpcUrl(config, cluster);
+    return {
+        primary: new Connection(primaryUrl, { commitment }),
+        fallback: new Connection(fallbackUrl, { commitment }),
+    };
+}
+/**
+ * @name findATA
+ * @description Derive the Associated Token Account address.
+ * Uses the standard ATA PDA derivation without importing the full
+ * `@solana/spl-token` package.
+ *
+ * @param owner - The token account owner.
+ * @param mint - The token mint.
+ * @param programId - Token program ID (defaults to TOKEN_PROGRAM_ID).
+ * @returns The derived ATA public key.
+ *
+ * @category Utils
+ * @since v0.6.0
+ */
+export function findATA(owner, mint, programId = new PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA")) {
+    const ASSOCIATED_TOKEN_PROGRAM_ID = new PublicKey("ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL");
+    const [ata] = PublicKey.findProgramAddressSync([owner.toBuffer(), programId.toBuffer(), mint.toBuffer()], ASSOCIATED_TOKEN_PROGRAM_ID);
+    return ata;
+}
+// ═══════════════════════════════════════════════════════════════════
+//  Error Classification
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * Anchor error code to friendly message mapping.
+ * Converts cryptic Anchor errors into actionable messages.
+ */
+const ANCHOR_ERROR_MESSAGES = {
+    6000: "Agent already registered for this wallet",
+    6001: "Agent not found — register first",
+    6002: "Name exceeds maximum length (64 bytes)",
+    6003: "Description exceeds maximum length (256 bytes)",
+    6004: "Too many capabilities (max 10)",
+    6005: "Too many pricing tiers (max 5)",
+    6006: "Too many protocols (max 5)",
+    6007: "Feedback score out of range (0-1000)",
+    6008: "Unauthorized — only the agent owner can perform this action",
+    6009: "Escrow expired",
+    6010: "Insufficient escrow balance",
+    6011: "Max calls exceeded",
+    6012: "Invalid settlement — calls must be > 0",
+    6013: "Escrow not empty — withdraw balance before closing",
+    6014: "Invalid token program — make sure you passed TOKEN_PROGRAM_ID as the 3rd remaining account",
+    6015: "Vault already initialized",
+    6016: "Session already exists",
+    6017: "Session closed — cannot write to closed session",
+    6018: "Data exceeds maximum write size (750 bytes)",
+    6019: "Ring buffer overflow — seal before writing more",
+};
+/**
+ * @name classifyAnchorError
+ * @description Convert an Anchor error code into a friendly, actionable message.
+ *
+ * @param errorCode - The numeric Anchor error code.
+ * @returns A human-readable error message, or a generic message for unknown codes.
+ *
+ * @category Utils
+ * @since v0.6.0
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.escrow.create(...);
+ * } catch (err) {
+ *   const code = extractAnchorErrorCode(err);
+ *   if (code !== null) {
+ *     console.error(classifyAnchorError(code));
+ *   }
+ * }
+ * ```
+ */
+export function classifyAnchorError(errorCode) {
+    return (ANCHOR_ERROR_MESSAGES[errorCode] ??
+        `Unknown SAP program error (code ${errorCode}). Check the IDL for details.`);
+}
+/**
+ * @name extractAnchorErrorCode
+ * @description Attempt to extract an Anchor error code from an Error object.
+ *
+ * Anchor errors typically have the structure `{ code: number, msg: string }`.
+ * This function handles both the direct `error.code` pattern and the
+ * `error.error.errorCode.number` nested pattern.
+ *
+ * @param err - The caught error object.
+ * @returns The numeric error code, or `null` if not an Anchor error.
+ *
+ * @category Utils
+ * @since v0.6.0
+ */
+export function extractAnchorErrorCode(err) {
+    if (err == null || typeof err !== "object")
+        return null;
+    // Direct code property
+    const direct = err.code;
+    if (typeof direct === "number")
+        return direct;
+    // Nested Anchor format: error.error.errorCode.number
+    const nested = err.error;
+    if (nested && typeof nested === "object") {
+        const errorCode = nested.errorCode;
+        if (errorCode && typeof errorCode === "object") {
+            const num = errorCode.number;
+            if (typeof num === "number")
+                return num;
+        }
+    }
+    // AnchorError pattern: { logs: [...], error: { errorCode: { number } } }
+    const msg = err.message;
+    if (typeof msg === "string") {
+        const match = msg.match(/custom program error:\s*0x([0-9a-fA-F]+)/);
+        if (match?.[1])
+            return parseInt(match[1], 16);
+    }
+    return null;
+}
+//# sourceMappingURL=rpc-strategy.js.map

package/dist/esm/utils/rpc-strategy.js.map

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

package/dist/esm/utils/schemas.js

@@ -0,0 +1,320 @@
+/**
+ * @module utils/schemas
+ * @description Zod schemas for runtime validation of environment variables,
+ * tool arguments, agent manifests, and x402 payment parameters.
+ *
+ * These schemas enforce correctness at the boundary: CLI scripts refuse
+ * to run if required fields are missing or mis-typed, and SDK methods
+ * validate inputs before hitting the chain.
+ *
+ * Zod is a peer dependency — these schemas are tree-shaken if not imported.
+ *
+ * @category Utils
+ * @since v0.6.0
+ */
+// ═══════════════════════════════════════════════════════════════════
+//  Dynamic Zod import (peer dependency)
+// ═══════════════════════════════════════════════════════════════════
+// We use a lazy getter pattern to avoid hard failures when zod is not installed
+let _z = null;
+function getZod() {
+    if (!_z) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            _z = require("zod");
+        }
+        catch {
+            throw new Error("[SAP SDK] Zod is required for schema validation. Install it: npm install zod");
+        }
+    }
+    return _z;
+}
+// ═══════════════════════════════════════════════════════════════════
+//  Environment Schemas
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name createEnvSchema
+ * @description Create a Zod schema for SAP SDK environment variables.
+ * Validates that all required env vars are present and correctly typed.
+ *
+ * @returns A Zod schema object for env validation.
+ *
+ * @category Utils
+ * @since v0.6.0
+ *
+ * @example
+ * ```ts
+ * import { createEnvSchema } from "@synapse-sap/sdk";
+ *
+ * const schema = createEnvSchema();
+ * const env = schema.parse(process.env);
+ * // env.SOLANA_CLUSTER is typed as "mainnet-beta" | "devnet" | "localnet"
+ * ```
+ */
+export function createEnvSchema() {
+    const z = getZod();
+    return z.object({
+        SOLANA_CLUSTER: z
+            .enum(["mainnet-beta", "devnet", "localnet"])
+            .default("devnet")
+            .describe("Solana cluster"),
+        SOLANA_RPC_URL: z
+            .string()
+            .url()
+            .optional()
+            .describe("Primary RPC endpoint URL"),
+        SOLANA_FALLBACK_RPC_URL: z
+            .string()
+            .url()
+            .optional()
+            .describe("Fallback RPC for SPL token ops"),
+        SOLANA_WS_URL: z
+            .string()
+            .url()
+            .optional()
+            .describe("WebSocket endpoint URL"),
+        WALLET_KEYPAIR_PATH: z
+            .string()
+            .optional()
+            .describe("Path to keypair JSON file"),
+        WALLET_PRIVATE_KEY: z
+            .string()
+            .optional()
+            .describe("Base58 private key (alternative to file)"),
+        SAP_PROGRAM_ID: z
+            .string()
+            .optional()
+            .describe("Custom SAP program ID override"),
+        DATABASE_URL: z
+            .string()
+            .optional()
+            .describe("PostgreSQL connection URL"),
+        LOG_LEVEL: z
+            .enum(["debug", "info", "warn", "error"])
+            .default("info")
+            .describe("Log level"),
+        X402_ENDPOINT: z
+            .string()
+            .url()
+            .optional()
+            .describe("Agent x402 payment endpoint"),
+        AGENT_URI: z
+            .string()
+            .url()
+            .optional()
+            .describe("Agent public API URI"),
+    });
+}
+// ═══════════════════════════════════════════════════════════════════
+//  Endpoint Schemas
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name createEndpointDescriptorSchema
+ * @description Zod schema for {@link EndpointDescriptor}.
+ * @returns A Zod schema for endpoint descriptor validation.
+ * @category Utils
+ * @since v0.6.0
+ */
+export function createEndpointDescriptorSchema() {
+    const z = getZod();
+    return z.object({
+        url: z.string().url(),
+        method: z.enum(["GET", "POST", "PUT", "DELETE"]).default("POST"),
+        contentType: z.string().default("application/json"),
+        requiresAuth: z.boolean().default(false),
+        authType: z.enum(["bearer", "api-key", "x402", "none"]).optional(),
+        requiresCSRF: z.boolean().default(false),
+        requiresCookies: z.boolean().default(false),
+        corsOrigins: z.array(z.string()).optional(),
+        requiredHeaders: z.record(z.string(), z.string()).optional(),
+    });
+}
+/**
+ * @name createHealthCheckSchema
+ * @description Zod schema for {@link HealthCheckDescriptor}.
+ * @returns A Zod schema for health check validation.
+ * @category Utils
+ * @since v0.6.0
+ */
+export function createHealthCheckSchema() {
+    const z = getZod();
+    return z.object({
+        url: z.string().url(),
+        expectedStatus: z.number().int().min(100).max(599).default(200),
+        timeoutMs: z.number().int().min(100).max(60_000).default(5000),
+        method: z.enum(["GET", "HEAD"]).default("GET"),
+    });
+}
+// ═══════════════════════════════════════════════════════════════════
+//  Tool Manifest Schemas
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name createToolManifestEntrySchema
+ * @description Zod schema for a single tool in an agent manifest.
+ * @returns A Zod schema for tool manifest entry validation.
+ * @category Utils
+ * @since v0.6.0
+ */
+export function createToolManifestEntrySchema() {
+    const z = getZod();
+    return z.object({
+        name: z.string().min(1).max(64),
+        description: z.string().max(256),
+        protocol: z.string().min(1).max(64),
+        category: z.string().min(1),
+        inputSchema: z.record(z.string(), z.unknown()),
+        outputSchema: z.record(z.string(), z.unknown()),
+        httpMethod: z.enum(["GET", "POST", "PUT", "DELETE", "COMPOUND"]).default("POST"),
+        paymentMode: z.enum(["x402", "free", "prepaid", "subscription"]).default("x402"),
+        pricePerCall: z.number().int().min(0).default(0),
+        requiredArgs: z.array(z.string()).default([]),
+        prerequisites: z.array(z.string()).default([]),
+        endpointOverride: createEndpointDescriptorSchema().optional(),
+    });
+}
+/**
+ * @name createAgentManifestSchema
+ * @description Zod schema for a complete agent manifest.
+ * @returns A Zod schema for manifest validation.
+ * @category Utils
+ * @since v0.6.0
+ *
+ * @example
+ * ```ts
+ * import { createAgentManifestSchema } from "@synapse-sap/sdk";
+ *
+ * const schema = createAgentManifestSchema();
+ * const manifest = schema.parse(JSON.parse(fs.readFileSync("manifest.json", "utf-8")));
+ * ```
+ */
+export function createAgentManifestSchema() {
+    const z = getZod();
+    return z.object({
+        version: z.literal("1.0.0"),
+        wallet: z.string().min(32).max(50),
+        name: z.string().min(1).max(64),
+        description: z.string().max(256),
+        endpoint: createEndpointDescriptorSchema(),
+        healthCheck: createHealthCheckSchema().optional(),
+        tools: z.array(createToolManifestEntrySchema()),
+        supportedNetworks: z.array(z.string()).min(1),
+        generatedAt: z.string().datetime(),
+    });
+}
+// ═══════════════════════════════════════════════════════════════════
+//  x402 Payment Schemas
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name createPreparePaymentSchema
+ * @description Zod schema for x402 payment preparation parameters.
+ * @returns A Zod schema for payment option validation.
+ * @category Utils
+ * @since v0.6.0
+ */
+export function createPreparePaymentSchema() {
+    const z = getZod();
+    return z.object({
+        pricePerCall: z.union([z.number(), z.string(), z.bigint()]),
+        maxCalls: z.union([z.number(), z.string(), z.bigint()]).optional(),
+        deposit: z.union([z.number(), z.string(), z.bigint()]),
+        expiresAt: z.union([z.number(), z.string(), z.bigint()]).optional(),
+        volumeCurve: z
+            .array(z.object({
+            afterCalls: z.number().int().min(1),
+            pricePerCall: z.union([z.number(), z.string(), z.bigint()]),
+        }))
+            .optional(),
+        tokenMint: z.string().optional(),
+        tokenDecimals: z.number().int().min(0).max(18).default(9),
+        networkIdentifier: z.string().optional(),
+    });
+}
+// ═══════════════════════════════════════════════════════════════════
+//  Agent Registration Schemas
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name createRegisterAgentSchema
+ * @description Zod schema for agent registration arguments.
+ * @returns A Zod schema for registration validation.
+ * @category Utils
+ * @since v0.6.0
+ */
+export function createRegisterAgentSchema() {
+    const z = getZod();
+    return z.object({
+        name: z.string().min(1).max(64),
+        description: z.string().min(1).max(256),
+        agentId: z.string().max(128).optional().nullable(),
+        agentUri: z.string().max(256).optional().nullable(),
+        x402Endpoint: z.string().url().max(256).optional().nullable(),
+        capabilities: z
+            .array(z.object({
+            id: z.string().min(1),
+            description: z.string().nullable().optional(),
+            protocolId: z.string().nullable().optional(),
+            version: z.string().nullable().optional(),
+        }))
+            .max(10)
+            .default([]),
+        protocols: z.array(z.string()).max(5).default([]),
+        pricing: z
+            .array(z.object({
+            tierId: z.string().min(1),
+            pricePerCall: z.union([z.number(), z.string()]),
+            rateLimit: z.number().int().min(0),
+            tokenType: z.enum(["sol", "usdc", "spl"]).default("sol"),
+            settlementMode: z.enum(["instant", "escrow", "batched", "x402"]).default("x402"),
+        }))
+            .max(5)
+            .default([]),
+    });
+}
+// ═══════════════════════════════════════════════════════════════════
+//  CLI Script Argument Schemas
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name createCallArgsSchema
+ * @description Zod schema for `npm run call` script arguments.
+ * Ensures all required fields are present before executing an x402 call.
+ *
+ * @returns A Zod schema for call argument validation.
+ * @category Utils
+ * @since v0.6.0
+ */
+export function createCallArgsSchema() {
+    const z = getZod();
+    return z.object({
+        agentWallet: z.string().min(32).max(50).describe("Agent wallet (base58)"),
+        tool: z.string().min(1).describe("Tool name to invoke"),
+        args: z.record(z.string(), z.unknown()).default({}).describe("Tool arguments (JSON)"),
+        endpoint: z.string().url().optional().describe("Endpoint URL override"),
+        network: z.string().optional().describe("Network identifier override"),
+        maxRetries: z.number().int().min(0).max(10).default(2),
+        timeoutMs: z.number().int().min(1000).max(120_000).default(30_000),
+    });
+}
+/**
+ * @name validateOrThrow
+ * @description Validate a value against a Zod schema, throwing a SapValidationError
+ * with a friendly message if validation fails.
+ *
+ * @param schema - A Zod schema.
+ * @param value - The value to validate.
+ * @param label - A label for error messages (e.g. "environment", "call args").
+ * @returns The parsed and typed value.
+ * @throws {Error} With formatted validation errors.
+ *
+ * @category Utils
+ * @since v0.6.0
+ */
+export function validateOrThrow(schema, value, label) {
+    const result = schema.safeParse(value);
+    if (result.success)
+        return schema.parse(value);
+    const issues = result.error?.issues ?? [];
+    const formatted = issues
+        .map((i) => `  • ${i.path.join(".")}: ${i.message}`)
+        .join("\n");
+    throw new Error(`[SAP SDK] Invalid ${label}:\n${formatted}`);
+}
+//# sourceMappingURL=schemas.js.map

package/dist/esm/utils/schemas.js.map

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

package/dist/types/constants/index.d.ts

@@ -24,5 +24,7 @@ export { SAP_PROGRAM_ADDRESS, MAINNET_SAP_PROGRAM_ID, DEVNET_SAP_PROGRAM_ID, LOC
 export { SEEDS } from "./seeds";
 export type { SeedKey } from "./seeds";
 export { LIMITS, AGENT_VERSION, VAULT_PROTOCOL_VERSION, TOOL_CATEGORY_VALUES, HTTP_METHOD_VALUES, } from "./limits";
+export { SapNetwork } from "./network";
+export type { SapNetworkId } from "./network";
 export { SAP_PROGRAM, SAP_UPGRADE_AUTHORITY, GLOBAL_REGISTRY_ADDRESS, GLOBAL_REGISTRY_BUMP, IDL_ACCOUNT_ADDRESS, PROGRAM_METADATA_PROGRAM, TOOL_CATEGORY_ADDRESSES, TOOL_CATEGORY_ADDRESS_LIST, } from "./addresses";
 //# sourceMappingURL=index.d.ts.map

package/dist/types/constants/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/constants/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACvB,cAAc,GACf,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,YAAY,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAGvC,OAAO,EACL,MAAM,EACN,aAAa,EACb,sBAAsB,EACtB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,uBAAuB,EACvB,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,EACxB,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/constants/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACvB,cAAc,GACf,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,YAAY,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAGvC,OAAO,EACL,MAAM,EACN,aAAa,EACb,sBAAsB,EACtB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAG9C,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,uBAAuB,EACvB,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,EACxB,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,aAAa,CAAC"}

package/dist/types/constants/network.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @module constants/network
+ * @description Solana network identifiers for x402 payment headers.
+ *
+ * x402 providers validate the `X-Payment-Network` header against their
+ * own network identifier. Some providers (e.g. Coinbase, Phantom) accept
+ * the human-readable cluster name (`solana:mainnet-beta`), while others
+ * (e.g. Kamiyo, Helius x402) require the Solana genesis-hash form
+ * (`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`).
+ *
+ * Use {@link SapNetwork} to select the correct format, or pass any
+ * custom string where needed.
+ *
+ * @category Constants
+ * @since v0.4.3
+ *
+ * @example
+ * ```ts
+ * import { SapNetwork } from "@synapse-sap/sdk";
+ *
+ * // Standard cluster name (default)
+ * const ctx = await x402.preparePayment(agentWallet, {
+ *   pricePerCall: 1000, deposit: 100_000,
+ *   networkIdentifier: SapNetwork.SOLANA_MAINNET,
+ * });
+ *
+ * // Genesis-hash form for providers that require it
+ * const ctx2 = await x402.preparePayment(agentWallet, {
+ *   pricePerCall: 1000, deposit: 100_000,
+ *   networkIdentifier: SapNetwork.SOLANA_MAINNET_GENESIS,
+ * });
+ * ```
+ */
+/**
+ * @name SapNetwork
+ * @description Network identifier strings for x402 `X-Payment-Network` headers.
+ *
+ * Two mainnet forms exist because x402 providers disagree on the canonical
+ * identifier:
+ *
+ * | Constant                | Value                                        | Accepted by          |
+ * |-------------------------|----------------------------------------------|----------------------|
+ * | `SOLANA_MAINNET`        | `solana:mainnet-beta`                        | Coinbase, Phantom    |
+ * | `SOLANA_MAINNET_GENESIS`| `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`   | Kamiyo, Helius x402  |
+ * | `SOLANA_DEVNET`         | `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1`   | Devnet providers     |
+ * | `SOLANA_DEVNET_NAMED`   | `solana:devnet`                              | Local / test flows   |
+ *
+ * If your provider requires a different format, pass a raw string instead.
+ *
+ * @category Constants
+ * @since v0.4.3
+ */
+export declare const SapNetwork: {
+    /**
+     * Mainnet-beta, human-readable cluster name.
+     * Default value used by the SDK prior to v0.4.3.
+     */
+    readonly SOLANA_MAINNET: "solana:mainnet-beta";
+    /**
+     * Mainnet-beta, genesis-hash form (CAIP-2 compliant).
+     * Required by Kamiyo, Helius x402, and other providers that validate
+     * against the Solana genesis hash.
+     */
+    readonly SOLANA_MAINNET_GENESIS: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+    /**
+     * Devnet, genesis-hash form (CAIP-2 compliant).
+     */
+    readonly SOLANA_DEVNET: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1";
+    /**
+     * Devnet, human-readable cluster name.
+     * Useful for local development and test validators.
+     */
+    readonly SOLANA_DEVNET_NAMED: "solana:devnet";
+};
+/**
+ * @name SapNetworkId
+ * @description Union type of all known {@link SapNetwork} values.
+ * Accept `SapNetworkId | string` where custom identifiers are allowed.
+ */
+export type SapNetworkId = (typeof SapNetwork)[keyof typeof SapNetwork];
+//# sourceMappingURL=network.d.ts.map