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

package/dist/cjs/postgres/sync.js

@@ -0,0 +1,221 @@
+"use strict";
+/**
+ * @module postgres/sync
+ * @description Real-time and scheduled sync engine for the SAP PostgreSQL
+ * adapter. Provides cron-like periodic sync and WebSocket-based
+ * live event streaming.
+ *
+ * @category Postgres
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * import { SapSyncEngine } from "@synapse-sap/sdk/postgres";
+ * import { SapPostgres }   from "@synapse-sap/sdk/postgres";
+ * import { SapClient }     from "@synapse-sap/sdk";
+ * import { Pool }          from "pg";
+ *
+ * const pool = new Pool({ connectionString: "postgresql://..." });
+ * const sap  = SapClient.from(provider);
+ * const pg   = new SapPostgres(pool, sap);
+ * const sync = new SapSyncEngine(pg, sap);
+ *
+ * // One-shot full sync
+ * await sync.run();
+ *
+ * // Periodic sync (every 60 seconds)
+ * sync.start(60_000);
+ *
+ * // Live event streaming via WebSocket
+ * await sync.startEventStream();
+ *
+ * // Graceful shutdown
+ * await sync.stop();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SapSyncEngine = void 0;
+const events_1 = require("../events");
+// ═══════════════════════════════════════════════════════════════════
+//  Sync Engine
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name SapSyncEngine
+ * @description Orchestrates periodic and real-time sync between
+ * Solana on-chain state and the PostgreSQL mirror.
+ *
+ * Two operational modes:
+ *
+ * 1. **Periodic sync** — polls all account types at a configurable
+ *    interval and upserts into PostgreSQL.
+ *
+ * 2. **Event streaming** — subscribes to SAP program logs via
+ *    WebSocket and inserts events in real-time.
+ *
+ * Both modes can run simultaneously.
+ *
+ * @category Postgres
+ * @since v0.1.0
+ */
+class SapSyncEngine {
+    pg;
+    client;
+    debug;
+    intervalId = null;
+    logSubId = null;
+    running = false;
+    constructor(pg, client, debug = false) {
+        this.pg = pg;
+        this.client = client;
+        this.debug = debug;
+    }
+    // ═════════════════════════════════════════════
+    //  One-shot Sync
+    // ═════════════════════════════════════════════
+    /**
+     * @name run
+     * @description Execute a single full sync cycle.
+     * @param options - Optional sync configuration.
+     * @returns Sync result summary.
+     * @since v0.1.0
+     */
+    async run(options) {
+        this.log("Starting one-shot sync...");
+        const result = await this.pg.syncAll(options);
+        this.log(`One-shot sync complete: ${result.totalRecords} records`);
+        return result;
+    }
+    // ═════════════════════════════════════════════
+    //  Periodic Sync
+    // ═════════════════════════════════════════════
+    /**
+     * @name start
+     * @description Start periodic sync at the given interval.
+     * Safe to call when already running — resets the interval.
+     *
+     * @param intervalMs - Sync interval in milliseconds (default: 60_000).
+     * @param options - Optional sync configuration.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * // Sync every 30 seconds
+     * sync.start(30_000);
+     * ```
+     */
+    start(intervalMs = 60_000, options) {
+        this.stopInterval();
+        this.running = true;
+        this.log(`Starting periodic sync every ${intervalMs}ms`);
+        // Run immediately, then repeat
+        this.pg.syncAll(options).catch((err) => this.log(`Sync error: ${err}`));
+        this.intervalId = setInterval(() => {
+            if (!this.running)
+                return;
+            this.pg.syncAll(options).catch((err) => this.log(`Sync error: ${err}`));
+        }, intervalMs);
+    }
+    /**
+     * @name stop
+     * @description Stop all sync activity (periodic + event stream).
+     * @since v0.1.0
+     */
+    async stop() {
+        this.running = false;
+        this.stopInterval();
+        await this.stopEventStream();
+        this.log("Sync engine stopped");
+    }
+    stopInterval() {
+        if (this.intervalId) {
+            clearInterval(this.intervalId);
+            this.intervalId = null;
+        }
+    }
+    // ═════════════════════════════════════════════
+    //  Real-time Event Stream
+    // ═════════════════════════════════════════════
+    /**
+     * @name startEventStream
+     * @description Subscribe to SAP program logs via WebSocket and
+     * insert parsed events into the `sap_events` table in real-time.
+     *
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * // Start streaming events
+     * await sync.startEventStream();
+     *
+     * // Later, stop the stream
+     * await sync.stopEventStream();
+     * ```
+     */
+    async startEventStream() {
+        if (this.logSubId !== null) {
+            this.log("Event stream already running");
+            return;
+        }
+        const connection = this.client.program.provider.connection;
+        const programId = this.client.program.programId;
+        const eventParser = new events_1.EventParser(this.client.program);
+        this.logSubId = connection.onLogs(programId, async (logInfo) => {
+            try {
+                const events = eventParser.parseLogs(logInfo.logs);
+                for (const event of events) {
+                    const data = event.data;
+                    const agentPda = data.agent ?? data.agentPda ?? undefined;
+                    const wallet = data.wallet ?? data.owner ?? undefined;
+                    await this.pg.syncEvent(event.name, logInfo.signature, 0, // slot populated from getSlot if needed
+                    data, agentPda, wallet);
+                }
+            }
+            catch (err) {
+                this.log(`Event parse error: ${err}`);
+            }
+        }, "confirmed");
+        this.log("Event stream started");
+    }
+    /**
+     * @name stopEventStream
+     * @description Unsubscribe from the program log stream.
+     * @since v0.1.0
+     */
+    async stopEventStream() {
+        if (this.logSubId !== null) {
+            const connection = this.client.program.provider.connection;
+            await connection.removeOnLogsListener(this.logSubId);
+            this.logSubId = null;
+            this.log("Event stream stopped");
+        }
+    }
+    // ═════════════════════════════════════════════
+    //  Status
+    // ═════════════════════════════════════════════
+    /**
+     * @name isRunning
+     * @description Check whether the periodic sync is active.
+     * @since v0.1.0
+     */
+    isRunning() {
+        return this.running;
+    }
+    /**
+     * @name isStreaming
+     * @description Check whether the event stream is active.
+     * @since v0.1.0
+     */
+    isStreaming() {
+        return this.logSubId !== null;
+    }
+    // ═════════════════════════════════════════════
+    //  Internal
+    // ═════════════════════════════════════════════
+    log(msg) {
+        if (this.debug) {
+            console.log(`[SapSyncEngine] ${msg}`);
+        }
+    }
+}
+exports.SapSyncEngine = SapSyncEngine;
+//# sourceMappingURL=sync.js.map

package/dist/cjs/postgres/sync.js.map

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

package/dist/cjs/postgres/types.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * @module postgres/types
+ * @description PostgreSQL adapter type definitions for SAP v2.
+ *
+ * Defines configuration, row shapes, and query result types
+ * for the PostgreSQL off-chain mirror.
+ *
+ * @category Postgres
+ * @since v0.1.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SAP_TABLE_MAP = void 0;
+/**
+ * @name SapTableName
+ * @description Mapping of account types to PostgreSQL table names.
+ * @category Postgres
+ * @since v0.1.0
+ */
+exports.SAP_TABLE_MAP = {
+    global_registry: "sap_global_registry",
+    agents: "sap_agents",
+    agent_stats: "sap_agent_stats",
+    feedbacks: "sap_feedbacks",
+    capability_indexes: "sap_capability_indexes",
+    protocol_indexes: "sap_protocol_indexes",
+    plugin_slots: "sap_plugin_slots",
+    memory_entries: "sap_memory_entries",
+    memory_chunks: "sap_memory_chunks",
+    memory_vaults: "sap_memory_vaults",
+    sessions: "sap_sessions",
+    epoch_pages: "sap_epoch_pages",
+    vault_delegates: "sap_vault_delegates",
+    tools: "sap_tools",
+    checkpoints: "sap_checkpoints",
+    escrows: "sap_escrows",
+    tool_category_indexes: "sap_tool_category_indexes",
+    attestations: "sap_attestations",
+    memory_buffers: "sap_memory_buffers",
+    memory_digests: "sap_memory_digests",
+    memory_ledgers: "sap_memory_ledgers",
+    ledger_pages: "sap_ledger_pages",
+};
+//# sourceMappingURL=types.js.map

package/dist/cjs/postgres/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/postgres/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAwEH;;;;;GAKG;AACU,QAAA,aAAa,GAAmC;IAC3D,eAAe,EAAE,qBAAqB;IACtC,MAAM,EAAE,YAAY;IACpB,WAAW,EAAE,iBAAiB;IAC9B,SAAS,EAAE,eAAe;IAC1B,kBAAkB,EAAE,wBAAwB;IAC5C,gBAAgB,EAAE,sBAAsB;IACxC,YAAY,EAAE,kBAAkB;IAChC,cAAc,EAAE,oBAAoB;IACpC,aAAa,EAAE,mBAAmB;IAClC,aAAa,EAAE,mBAAmB;IAClC,QAAQ,EAAE,cAAc;IACxB,WAAW,EAAE,iBAAiB;IAC9B,eAAe,EAAE,qBAAqB;IACtC,KAAK,EAAE,WAAW;IAClB,WAAW,EAAE,iBAAiB;IAC9B,OAAO,EAAE,aAAa;IACtB,qBAAqB,EAAE,2BAA2B;IAClD,YAAY,EAAE,kBAAkB;IAChC,cAAc,EAAE,oBAAoB;IACpC,cAAc,EAAE,oBAAoB;IACpC,cAAc,EAAE,oBAAoB;IACpC,YAAY,EAAE,kBAAkB;CACjC,CAAC"}

package/dist/cjs/registries/builder.js

@@ -0,0 +1,414 @@
+"use strict";
+/**
+ * @module registries/builder
+ * @description Fluent agent registration builder.
+ *
+ * Provides a chainable API for registering a fully-configured agent
+ * in a single flow — identity, capabilities, pricing tiers, tools,
+ * x402 endpoint, and discovery indexes.
+ *
+ * Instead of calling 5+ separate instructions manually, developers
+ * use a single builder chain that validates inputs and batches
+ * the registration cleanly.
+ *
+ * @category Registries
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * const result = await client.builder
+ *   .agent("SwapBot")
+ *   .description("AI-powered Jupiter swap agent")
+ *   .x402Endpoint("https://swapbot.example.com/x402")
+ *   .addCapability("jupiter:swap", { protocol: "jupiter", version: "6.0" })
+ *   .addCapability("jupiter:quote", { protocol: "jupiter", version: "6.0" })
+ *   .addPricingTier({
+ *     tierId: "standard",
+ *     pricePerCall: 1000,
+ *     rateLimit: 60,
+ *     tokenType: "sol",
+ *     settlementMode: "x402",
+ *   })
+ *   .addProtocol("jupiter")
+ *   .register();
+ *
+ * // Or register with tools:
+ * const result = await client.builder
+ *   .agent("DataBot")
+ *   .description("Real-time DeFi data feeds")
+ *   .addTool({ name: "getPrice", protocol: "pyth", category: "data", ... })
+ *   .registerWithTools();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentBuilder = void 0;
+const web3_js_1 = require("@solana/web3.js");
+const anchor_1 = require("@coral-xyz/anchor");
+const pda_1 = require("../pda");
+const utils_1 = require("../utils");
+const constants_1 = require("../constants");
+const types_1 = require("../types");
+// ═══════════════════════════════════════════════════════════════════
+//  Agent Builder
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name AgentBuilder
+ * @description Fluent builder for registering a fully-configured agent on-chain.
+ *
+ * Chains identity setters, capability/pricing/protocol adders, and tool
+ * definitions into a single validated registration flow. Validates all
+ * inputs against on-chain limits before sending transactions.
+ *
+ * @category Registries
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * const result = await client.builder
+ *   .agent("SwapBot")
+ *   .description("AI-powered Jupiter swap agent")
+ *   .x402Endpoint("https://swapbot.example.com/x402")
+ *   .addCapability("jupiter:swap", { protocol: "jupiter", version: "6.0" })
+ *   .addPricingTier({ tierId: "standard", pricePerCall: 1000, rateLimit: 60 })
+ *   .register();
+ * ```
+ */
+class AgentBuilder {
+    program;
+    wallet;
+    _name = "";
+    _description = "";
+    _agentId = null;
+    _agentUri = null;
+    _x402Endpoint = null;
+    _capabilities = [];
+    _pricing = [];
+    _protocols = [];
+    _tools = [];
+    constructor(program) {
+        this.program = program;
+        this.wallet = program.provider.wallet.publicKey;
+    }
+    // ── Fluent Setters ───────────────────────────────────
+    /**
+     * @name agent
+     * @description Set the agent display name.
+     * @param name - Display name (max 64 characters).
+     * @returns `this` for chaining.
+     * @since v0.1.0
+     */
+    agent(name) {
+        (0, utils_1.assert)(name.length <= constants_1.LIMITS.MAX_NAME_LEN, `Name exceeds ${constants_1.LIMITS.MAX_NAME_LEN} chars`);
+        this._name = name;
+        return this;
+    }
+    /**
+     * @name description
+     * @description Set the agent description.
+     * @param desc - Description text (max 256 characters).
+     * @returns `this` for chaining.
+     * @since v0.1.0
+     */
+    description(desc) {
+        (0, utils_1.assert)(desc.length <= constants_1.LIMITS.MAX_DESC_LEN, `Description exceeds ${constants_1.LIMITS.MAX_DESC_LEN} chars`);
+        this._description = desc;
+        return this;
+    }
+    /**
+     * @name agentId
+     * @description Set a DID-style agent identifier.
+     * @param id - Agent identifier string.
+     * @returns `this` for chaining.
+     * @since v0.1.0
+     */
+    agentId(id) {
+        (0, utils_1.assert)(id.length <= constants_1.LIMITS.MAX_AGENT_ID_LEN, `Agent ID exceeds ${constants_1.LIMITS.MAX_AGENT_ID_LEN} chars`);
+        this._agentId = id;
+        return this;
+    }
+    /**
+     * @name agentUri
+     * @description Set an agent metadata URI.
+     * @param uri - Metadata URI string.
+     * @returns `this` for chaining.
+     * @since v0.1.0
+     */
+    agentUri(uri) {
+        (0, utils_1.assert)(uri.length <= constants_1.LIMITS.MAX_URI_LEN, `URI exceeds ${constants_1.LIMITS.MAX_URI_LEN} chars`);
+        this._agentUri = uri;
+        return this;
+    }
+    /**
+     * @name x402Endpoint
+     * @description Set the x402 payment endpoint URL.
+     * @param url - The x402 endpoint URL for the agent.
+     * @returns `this` for chaining.
+     * @since v0.1.0
+     */
+    x402Endpoint(url) {
+        (0, utils_1.assert)(url.length <= constants_1.LIMITS.MAX_URI_LEN, `x402 endpoint exceeds ${constants_1.LIMITS.MAX_URI_LEN} chars`);
+        this._x402Endpoint = url;
+        return this;
+    }
+    /**
+     * @name addCapability
+     * @description Add a capability to the agent.
+     *
+     * @param id - Capability identifier string (e.g. `"jupiter:swap"`).
+     * @param opts - Optional capability metadata.
+     * @param opts.protocol - Protocol the capability belongs to.
+     * @param opts.version - Capability version string.
+     * @param opts.description - Human-readable capability description.
+     * @returns `this` for chaining.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * builder.addCapability("jupiter:swap", { protocol: "jupiter", version: "6.0" })
+     * ```
+     */
+    addCapability(id, opts) {
+        (0, utils_1.assert)(this._capabilities.length < constants_1.LIMITS.MAX_CAPABILITIES, `Max ${constants_1.LIMITS.MAX_CAPABILITIES} capabilities`);
+        this._capabilities.push({
+            id,
+            description: opts?.description ?? null,
+            protocolId: opts?.protocol ?? null,
+            version: opts?.version ?? null,
+        });
+        return this;
+    }
+    /**
+     * @name addPricingTier
+     * @description Add a pricing tier for the agent's services.
+     * Supports flat-rate, volume-curve, and configurable settlement modes.
+     *
+     * @param input - Pricing tier configuration.
+     * @returns `this` for chaining.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * builder.addPricingTier({
+     *   tierId: "standard",
+     *   pricePerCall: 1000,
+     *   rateLimit: 60,
+     *   tokenType: "sol",
+     *   settlementMode: "x402",
+     * })
+     * ```
+     */
+    addPricingTier(input) {
+        (0, utils_1.assert)(this._pricing.length < constants_1.LIMITS.MAX_PRICING_TIERS, `Max ${constants_1.LIMITS.MAX_PRICING_TIERS} pricing tiers`);
+        const tokenType = this.resolveTokenType(input.tokenType ?? "sol");
+        const settlementMode = input.settlementMode
+            ? this.resolveSettlementMode(input.settlementMode)
+            : null;
+        const volumeCurve = input.volumeCurve
+            ? input.volumeCurve.map((v) => ({
+                afterCalls: v.afterCalls,
+                pricePerCall: new anchor_1.BN(v.pricePerCall.toString()),
+            }))
+            : null;
+        this._pricing.push({
+            tierId: input.tierId,
+            pricePerCall: new anchor_1.BN(input.pricePerCall.toString()),
+            minPricePerCall: input.minPricePerCall
+                ? new anchor_1.BN(input.minPricePerCall.toString())
+                : null,
+            maxPricePerCall: input.maxPricePerCall
+                ? new anchor_1.BN(input.maxPricePerCall.toString())
+                : null,
+            rateLimit: input.rateLimit,
+            maxCallsPerSession: input.maxCallsPerSession ?? 0,
+            burstLimit: input.burstLimit ?? null,
+            tokenType,
+            tokenMint: input.tokenMint ?? null,
+            tokenDecimals: input.tokenDecimals ?? null,
+            settlementMode,
+            minEscrowDeposit: input.minEscrowDeposit
+                ? new anchor_1.BN(input.minEscrowDeposit.toString())
+                : null,
+            batchIntervalSec: input.batchIntervalSec ?? null,
+            volumeCurve,
+        });
+        return this;
+    }
+    /**
+     * @name addProtocol
+     * @description Add a protocol the agent supports.
+     * Duplicates are silently ignored.
+     *
+     * @param protocolId - Protocol identifier string (e.g. `"jupiter"`).
+     * @returns `this` for chaining.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * builder.addProtocol("jupiter")
+     * ```
+     */
+    addProtocol(protocolId) {
+        (0, utils_1.assert)(this._protocols.length < constants_1.LIMITS.MAX_PROTOCOLS, `Max ${constants_1.LIMITS.MAX_PROTOCOLS} protocols`);
+        if (!this._protocols.includes(protocolId)) {
+            this._protocols.push(protocolId);
+        }
+        return this;
+    }
+    /**
+     * @name addTool
+     * @description Add a tool to be published after registration.
+     * Only used with {@link AgentBuilder.registerWithTools}.
+     *
+     * @param tool - Tool configuration.
+     * @returns `this` for chaining.
+     * @since v0.1.0
+     */
+    addTool(tool) {
+        this._tools.push(tool);
+        return this;
+    }
+    // ── Registration ─────────────────────────────────────
+    /**
+     * @name register
+     * @description Register the agent on-chain.
+     * Validates all inputs before sending the transaction.
+     *
+     * @returns A {@link RegisterResult} with the transaction signature and derived PDAs.
+     * @throws If validation fails (missing name, description, or limit exceeded).
+     * @since v0.1.0
+     */
+    async register() {
+        this.validate();
+        const [agentPda] = (0, pda_1.deriveAgent)(this.wallet);
+        const [statsPda] = (0, pda_1.deriveAgentStats)(agentPda);
+        const [globalPda] = (0, pda_1.deriveGlobalRegistry)();
+        const txSignature = await this.methods
+            .registerAgent(this._name, this._description, this._capabilities, this._pricing, this._protocols, this._agentId, this._agentUri, this._x402Endpoint)
+            .accounts({
+            wallet: this.wallet,
+            agent: agentPda,
+            agentStats: statsPda,
+            globalRegistry: globalPda,
+            systemProgram: web3_js_1.SystemProgram.programId,
+        })
+            .rpc();
+        return { txSignature, agentPda, statsPda };
+    }
+    /**
+     * @name registerWithTools
+     * @description Register the agent AND publish all configured tools.
+     * Sends agent registration first, then tool publications sequentially.
+     *
+     * @returns A {@link RegisterWithToolsResult} with agent and tool transaction signatures.
+     * @throws If validation fails or any tool publication fails.
+     * @since v0.1.0
+     */
+    async registerWithTools() {
+        const result = await this.register();
+        const toolSignatures = [];
+        const [globalPda] = (0, pda_1.deriveGlobalRegistry)();
+        for (const tool of this._tools) {
+            const toolNameHash = (0, utils_1.hashToArray)((0, utils_1.sha256)(tool.name));
+            const [toolPda] = (0, pda_1.deriveTool)(result.agentPda, new Uint8Array(toolNameHash));
+            const httpMethod = constants_1.HTTP_METHOD_VALUES[(tool.httpMethod ?? "post")] ?? 1;
+            const category = constants_1.TOOL_CATEGORY_VALUES[(tool.category ?? "Custom")] ?? 9;
+            const txSignature = await this.methods
+                .publishTool(tool.name, toolNameHash, (0, utils_1.hashToArray)((0, utils_1.sha256)(tool.protocol)), (0, utils_1.hashToArray)((0, utils_1.sha256)(tool.description)), (0, utils_1.hashToArray)((0, utils_1.sha256)(tool.inputSchema)), (0, utils_1.hashToArray)((0, utils_1.sha256)(tool.outputSchema)), httpMethod, category, tool.paramsCount, tool.requiredParams, tool.isCompound ?? false)
+                .accounts({
+                wallet: this.wallet,
+                agent: result.agentPda,
+                tool: toolPda,
+                globalRegistry: globalPda,
+                systemProgram: web3_js_1.SystemProgram.programId,
+            })
+                .rpc();
+            toolSignatures.push({ name: tool.name, txSignature });
+        }
+        return { ...result, toolSignatures };
+    }
+    // ── Reset ────────────────────────────────────────────
+    /**
+     * @name reset
+     * @description Reset the builder to its initial state.
+     * Clears all configured values so the builder can be reused.
+     *
+     * @returns `this` for chaining.
+     * @since v0.1.0
+     */
+    reset() {
+        this._name = "";
+        this._description = "";
+        this._agentId = null;
+        this._agentUri = null;
+        this._x402Endpoint = null;
+        this._capabilities = [];
+        this._pricing = [];
+        this._protocols = [];
+        this._tools = [];
+        return this;
+    }
+    // ── Validation ───────────────────────────────────────
+    /**
+     * @name validate
+     * @description Validate all builder inputs against on-chain limits.
+     * @throws If any required field is missing or any limit is exceeded.
+     * @private
+     */
+    validate() {
+        (0, utils_1.assert)(this._name.length > 0, "Agent name is required");
+        (0, utils_1.assert)(this._description.length > 0, "Agent description is required");
+        (0, utils_1.assert)(this._capabilities.length <= constants_1.LIMITS.MAX_CAPABILITIES, `Max ${constants_1.LIMITS.MAX_CAPABILITIES} capabilities`);
+        (0, utils_1.assert)(this._pricing.length <= constants_1.LIMITS.MAX_PRICING_TIERS, `Max ${constants_1.LIMITS.MAX_PRICING_TIERS} pricing tiers`);
+        (0, utils_1.assert)(this._protocols.length <= constants_1.LIMITS.MAX_PROTOCOLS, `Max ${constants_1.LIMITS.MAX_PROTOCOLS} protocols`);
+    }
+    // ── Helpers ──────────────────────────────────────────
+    /**
+     * @name resolveTokenType
+     * @description Resolve a token type string to the on-chain enum variant.
+     * @param t - Token type string (`"sol"`, `"usdc"`, or `"spl"`).
+     * @returns The corresponding {@link TokenTypeKind} enum value.
+     * @private
+     */
+    resolveTokenType(t) {
+        switch (t) {
+            case "sol":
+                return types_1.TokenType.Sol;
+            case "usdc":
+                return types_1.TokenType.Usdc;
+            case "spl":
+                return types_1.TokenType.Spl;
+        }
+    }
+    /**
+     * @name resolveSettlementMode
+     * @description Resolve a settlement mode string to the on-chain enum variant.
+     * @param m - Settlement mode string (`"instant"`, `"escrow"`, `"batched"`, or `"x402"`).
+     * @returns The corresponding {@link SettlementModeKind} enum value.
+     * @private
+     */
+    resolveSettlementMode(m) {
+        switch (m) {
+            case "instant":
+                return types_1.SettlementMode.Instant;
+            case "escrow":
+                return types_1.SettlementMode.Escrow;
+            case "batched":
+                return types_1.SettlementMode.Batched;
+            case "x402":
+                return types_1.SettlementMode.X402;
+        }
+    }
+    /**
+     * @name methods
+     * @description Accessor for the Anchor program methods namespace.
+     * @returns The program methods object for building RPC calls.
+     * @private
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    get methods() {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+        return this.program.methods;
+    }
+}
+exports.AgentBuilder = AgentBuilder;
+//# sourceMappingURL=builder.js.map