@openzeppelin/relayer-plugin-channels 0.4.0 → 0.5.0

package/dist/plugin/constants.js

@@ -12,6 +12,7 @@ exports.HTTP_STATUS = {
     UNAUTHORIZED: 401,
     FORBIDDEN: 403,
     CONFLICT: 409,
+    TOO_MANY_REQUESTS: 429,
     INTERNAL_SERVER_ERROR: 500,
     BAD_GATEWAY: 502,
     SERVICE_UNAVAILABLE: 503,
@@ -20,7 +21,7 @@ exports.HTTP_STATUS = {
 // Configuration Constants
 exports.CONFIG = {
     DEFAULT_LOCK_TTL_SECONDS: 30,
-    MIN_LOCK_TTL_SECONDS: 10,
+    MIN_LOCK_TTL_SECONDS: 3,
     MAX_LOCK_TTL_SECONDS: 30,
 };
 // Pool Constants

package/dist/plugin/fee-tracking.d.ts

@@ -0,0 +1,81 @@
+/**
+ * fee-tracking.ts
+ *
+ * API key fee tracking for rate limiting.
+ * Supports custom per-key limits with fallback to default.
+ * Supports periodic reset of consumption.
+ */
+import { PluginKVStore } from "@openzeppelin/relayer-sdk";
+/** KV data structure for fee consumption */
+export interface FeeData {
+    consumed: number;
+    periodStart?: number;
+}
+/** Usage info returned by getUsageInfo */
+export interface UsageInfo {
+    consumed: number;
+    limit?: number;
+    remaining?: number;
+    periodStartAt?: string;
+    periodEndsAt?: string;
+}
+/** Configuration for FeeTracker */
+export interface FeeTrackerConfig {
+    kv: PluginKVStore;
+    network: "testnet" | "mainnet";
+    apiKey: string;
+    defaultLimit?: number;
+    resetPeriodMs?: number;
+}
+export declare class FeeTracker {
+    private readonly kv;
+    private readonly network;
+    private readonly apiKey;
+    private readonly defaultLimit?;
+    private readonly resetPeriodMs?;
+    constructor(config: FeeTrackerConfig);
+    /**
+     * Check if API key can afford the given fee.
+     * Throws 429 if not. No-op if unlimited.
+     */
+    checkBudget(fee: number): Promise<void>;
+    /**
+     * Record fee consumption after transaction.
+     * Uses distributed lock for atomicity with retry.
+     * Errors are logged but not thrown (non-blocking).
+     */
+    recordUsage(fee: number): Promise<void>;
+    /**
+     * Get complete usage info for management API.
+     */
+    getUsageInfo(): Promise<UsageInfo>;
+    /**
+     * Get custom limit for this API key.
+     */
+    getCustomLimit(): Promise<number | undefined>;
+    /**
+     * Set custom limit for this API key.
+     */
+    setCustomLimit(limit: number): Promise<void>;
+    /**
+     * Delete custom limit for this API key.
+     */
+    deleteCustomLimit(): Promise<void>;
+    /**
+     * Get effective fee state after applying period expiry.
+     * Returns { consumed: 0 } if no data or period expired.
+     */
+    private getFeeState;
+    /**
+     * Get effective limit (custom ?? default).
+     */
+    private getEffectiveLimit;
+    /**
+     * Check if period has expired.
+     */
+    private isPeriodExpired;
+    private get consumedKey();
+    private get limitKey();
+    private get lockKey();
+}
+//# sourceMappingURL=fee-tracking.d.ts.map

package/dist/plugin/fee-tracking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fee-tracking.d.ts","sourceRoot":"","sources":["../../src/plugin/fee-tracking.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,aAAa,EAAe,MAAM,2BAA2B,CAAC;AAGvE,4CAA4C;AAC5C,MAAM,WAAW,OAAO;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAQD,0CAA0C;AAC1C,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,mCAAmC;AACnC,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,aAAa,CAAC;IAClB,OAAO,EAAE,SAAS,GAAG,SAAS,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAgB;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAS;gBAE5B,MAAM,EAAE,gBAAgB;IAUpC;;;OAGG;IACG,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB7C;;;;OAIG;IACG,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA8B7C;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,SAAS,CAAC;IAqBxC;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAKnD;;OAEG;IACG,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD;;OAEG;IACG,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAMxC;;;OAGG;YACW,WAAW;IASzB;;OAEG;YACW,iBAAiB;IAK/B;;OAEG;IACH,OAAO,CAAC,eAAe;IAKvB,OAAO,KAAK,WAAW,GAEtB;IAED,OAAO,KAAK,QAAQ,GAEnB;IAED,OAAO,KAAK,OAAO,GAElB;CACF"}

package/dist/plugin/fee-tracking.js

@@ -0,0 +1,146 @@
+"use strict";
+/**
+ * fee-tracking.ts
+ *
+ * API key fee tracking for rate limiting.
+ * Supports custom per-key limits with fallback to default.
+ * Supports periodic reset of consumption.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FeeTracker = void 0;
+const relayer_sdk_1 = require("@openzeppelin/relayer-sdk");
+const constants_1 = require("./constants");
+class FeeTracker {
+    constructor(config) {
+        this.kv = config.kv;
+        this.network = config.network;
+        this.apiKey = config.apiKey;
+        this.defaultLimit = config.defaultLimit;
+        this.resetPeriodMs = config.resetPeriodMs;
+    }
+    // === Public API: Transaction Flow ===
+    /**
+     * Check if API key can afford the given fee.
+     * Throws 429 if not. No-op if unlimited.
+     */
+    async checkBudget(fee) {
+        const limit = await this.getEffectiveLimit();
+        if (limit === undefined)
+            return;
+        const { consumed } = await this.getFeeState();
+        if (consumed + fee > limit) {
+            const remaining = limit - consumed;
+            throw (0, relayer_sdk_1.pluginError)(`Transaction fee (${fee} stroops) exceeds remaining budget (${remaining} stroops). Consumed: ${consumed}/${limit} stroops.`, {
+                code: "FEE_LIMIT_EXCEEDED",
+                status: constants_1.HTTP_STATUS.TOO_MANY_REQUESTS,
+                details: { consumed, fee, remaining, limit },
+            });
+        }
+    }
+    /**
+     * Record fee consumption after transaction.
+     * Uses distributed lock for atomicity with retry.
+     * Errors are logged but not thrown (non-blocking).
+     */
+    async recordUsage(fee) {
+        const maxRetries = 3;
+        for (let i = 0; i < maxRetries; i++) {
+            try {
+                const result = await this.kv.withLock(this.lockKey, async () => {
+                    const state = await this.getFeeState();
+                    const now = Date.now();
+                    await this.kv.set(this.consumedKey, {
+                        consumed: state.consumed + fee,
+                        periodStart: state.periodStart ?? now,
+                    });
+                    return true;
+                }, { ttlSec: 5, onBusy: "skip" });
+                if (result !== null)
+                    return;
+                // Lock busy, retry with jitter
+                await new Promise((r) => setTimeout(r, 20 + Math.random() * 50));
+            }
+            catch (err) {
+                console.warn(`[channels] Failed to record fee: ${err}`);
+                return;
+            }
+        }
+        console.warn(`[channels] Failed to record fee after ${maxRetries} retries (lock contention)`);
+    }
+    /**
+     * Get complete usage info for management API.
+     */
+    async getUsageInfo() {
+        const [state, limit] = await Promise.all([
+            this.getFeeState(),
+            this.getEffectiveLimit(),
+        ]);
+        return {
+            consumed: state.consumed,
+            limit,
+            remaining: limit !== undefined ? Math.max(0, limit - state.consumed) : undefined,
+            periodStartAt: state.periodStart
+                ? new Date(state.periodStart).toISOString()
+                : undefined,
+            periodEndsAt: state.periodStart && this.resetPeriodMs
+                ? new Date(state.periodStart + this.resetPeriodMs).toISOString()
+                : undefined,
+        };
+    }
+    /**
+     * Get custom limit for this API key.
+     */
+    async getCustomLimit() {
+        const data = await this.kv.get(this.limitKey);
+        return data?.limit;
+    }
+    /**
+     * Set custom limit for this API key.
+     */
+    async setCustomLimit(limit) {
+        await this.kv.set(this.limitKey, { limit });
+    }
+    /**
+     * Delete custom limit for this API key.
+     */
+    async deleteCustomLimit() {
+        await this.kv.del(this.limitKey);
+    }
+    // === Private ===
+    /**
+     * Get effective fee state after applying period expiry.
+     * Returns { consumed: 0 } if no data or period expired.
+     */
+    async getFeeState() {
+        const data = await this.kv.get(this.consumedKey);
+        if (!data || this.isPeriodExpired(data.periodStart)) {
+            return { consumed: 0 };
+        }
+        return data;
+    }
+    /**
+     * Get effective limit (custom ?? default).
+     */
+    async getEffectiveLimit() {
+        const custom = await this.getCustomLimit();
+        return custom ?? this.defaultLimit;
+    }
+    /**
+     * Check if period has expired.
+     */
+    isPeriodExpired(periodStart) {
+        if (!this.resetPeriodMs || !periodStart)
+            return false;
+        return Date.now() - periodStart >= this.resetPeriodMs;
+    }
+    get consumedKey() {
+        return `${this.network}:api-key-fees:${this.apiKey}`;
+    }
+    get limitKey() {
+        return `${this.network}:api-key-limit:${this.apiKey}`;
+    }
+    get lockKey() {
+        return `${this.network}:fee-lock:${this.apiKey}`;
+    }
+}
+exports.FeeTracker = FeeTracker;

package/dist/plugin/handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/plugin/handler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAe,MAAM,2BAA2B,CAAC;AA6KvE;;GAEG;AACH,wBAAsB,OAAO,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,CAGlE"}
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/plugin/handler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAe,MAAM,2BAA2B,CAAC;AAqNvE;;GAEG;AACH,wBAAsB,OAAO,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,CAGlE"}

package/dist/plugin/handler.js

@@ -18,13 +18,19 @@ const stellar_sdk_1 = require("@stellar/stellar-sdk");
 const simulation_1 = require("./simulation");
 const fee_1 = require("./fee");
 const tx_1 = require("./tx");
-async function handleXdrSubmit(xdrStr, fundRelayer, network, networkPassphrase, api) {
+const fee_tracking_1 = require("./fee-tracking");
+function getApiKey(headers, headerName) {
+    const values = headers[headerName];
+    return values?.[0]?.trim() || undefined;
+}
+async function handleXdrSubmit(xdrStr, fundRelayer, network, networkPassphrase, api, tracker) {
     const tx = new stellar_sdk_1.Transaction(xdrStr, networkPassphrase);
     const validated = (0, tx_1.validateExistingTransactionForSubmitOnly)(tx);
     const maxFee = (0, fee_1.calculateMaxFee)(validated);
-    return (0, submit_1.submitWithFeeBumpAndWait)(fundRelayer, validated.toXDR(), network, maxFee, api);
+    await tracker?.checkBudget(maxFee);
+    return (0, submit_1.submitWithFeeBumpAndWait)(fundRelayer, validated.toXDR(), network, maxFee, api, tracker);
 }
-async function handleFuncAuthSubmit(func, auth, api, pool, fundRelayer, fundAddress, network, networkPassphrase) {
+async function handleFuncAuthSubmit(func, auth, api, pool, fundRelayer, fundAddress, network, networkPassphrase, tracker) {
     let poolLock;
     try {
         poolLock = await pool.acquire();
@@ -52,7 +58,8 @@ async function handleFuncAuthSubmit(func, auth, api, pool, fundRelayer, fundAddr
         const built = await (0, simulation_1.simulateAndBuildWithChannel)(func, auth, { address: channelInfo.address, sequence: channelStatus.sequence_number }, fundAddress, fundRelayer, networkPassphrase);
         const signedTx = await (0, submit_1.signWithChannelAndFund)(built, channelRelayer, fundRelayer, channelInfo.address, fundAddress, networkPassphrase);
         const maxFee = (0, fee_1.calculateMaxFee)(signedTx);
-        return await (0, submit_1.submitWithFeeBumpAndWait)(fundRelayer, signedTx.toXDR(), network, maxFee, api);
+        await tracker?.checkBudget(maxFee);
+        return await (0, submit_1.submitWithFeeBumpAndWait)(fundRelayer, signedTx.toXDR(), network, maxFee, api, tracker);
     }
     finally {
         if (poolLock) {
@@ -61,15 +68,35 @@ async function handleFuncAuthSubmit(func, auth, api, pool, fundRelayer, fundAddr
     }
 }
 async function channelAccounts(context) {
-    const { api, kv, params } = context;
+    const { api, kv, params, headers } = context;
     // Management branch: handle and return immediately
     if ((0, management_1.isManagementRequest)(params)) {
         return await (0, management_1.handleManagement)(context);
     }
     // Load config and initialize per-request dependencies
     const config = (0, config_1.loadConfig)();
-    const pool = new pool_1.ChannelPool(config.network, kv);
+    const pool = new pool_1.ChannelPool(config.network, kv, config.lockTtlSeconds);
     const networkPassphrase = (0, config_1.getNetworkPassphrase)(config.network);
+    // Fee tracking setup
+    let tracker;
+    const apiKey = getApiKey(headers, config.apiKeyHeader);
+    // If default limit is set, require API key
+    if (config.feeLimit !== undefined && !apiKey) {
+        throw (0, relayer_sdk_1.pluginError)("API key required", {
+            code: "API_KEY_REQUIRED",
+            status: constants_1.HTTP_STATUS.BAD_REQUEST,
+        });
+    }
+    // Create tracker if API key is present (for tracking and custom limits)
+    if (apiKey) {
+        tracker = new fee_tracking_1.FeeTracker({
+            kv,
+            network: config.network,
+            apiKey,
+            defaultLimit: config.feeLimit,
+            resetPeriodMs: config.feeResetPeriodMs,
+        });
+    }
     try {
         // 1. Validate and parse request (xdr OR func+auth)
         const request = (0, validation_1.validateAndParseRequest)(params);
@@ -98,10 +125,10 @@ async function channelAccounts(context) {
         // 3. Branch by request type
         if (request.type === "xdr") {
             console.log(`[channels] Flow: XDR submit-only`);
-            return await handleXdrSubmit(request.xdr, fundRelayer, config.network, networkPassphrase, api);
+            return await handleXdrSubmit(request.xdr, fundRelayer, config.network, networkPassphrase, api, tracker);
         }
         console.log(`[channels] Flow: func+auth with channel account`);
-        return await handleFuncAuthSubmit(request.func, request.auth, api, pool, fundRelayer, fundInfo.address, config.network, networkPassphrase);
+        return await handleFuncAuthSubmit(request.func, request.auth, api, pool, fundRelayer, fundInfo.address, config.network, networkPassphrase, tracker);
     }
     finally {
         // Nothing to cleanup here; func-auth path releases locks internally

package/dist/plugin/management.d.ts

@@ -1,9 +1,13 @@
 /**
  * management.ts
  *
- * Payload-based management API for channel relayerIds.
+ * Payload-based management API for channel relayerIds and fee limits.
  * - listChannelAccounts: returns relayerIds from KV
  * - setChannelAccounts: replaces relayerIds array in KV (checks lock conflicts)
+ * - getFeeUsage: returns fee consumption for an API key
+ * - getFeeLimit: returns custom limit for an API key (if set)
+ * - setFeeLimit: sets custom limit for an API key
+ * - deleteFeeLimit: removes custom limit for an API key
  */
 import type { PluginContext } from "@openzeppelin/relayer-sdk";
 export declare function isManagementRequest(params: any): boolean;

package/dist/plugin/management.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"management.d.ts","sourceRoot":"","sources":["../../src/plugin/management.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,2BAA2B,CAAC;AAe9E,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,GAAG,GAAG,OAAO,CAOxD;AAED,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,CAiC3E"}
+{"version":3,"file":"management.d.ts","sourceRoot":"","sources":["../../src/plugin/management.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,2BAA2B,CAAC;AAM9E,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,GAAG,GAAG,OAAO,CAOxD;AAED,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,CA8C3E"}

package/dist/plugin/management.js

@@ -2,9 +2,13 @@
 /**
  * management.ts
  *
- * Payload-based management API for channel relayerIds.
+ * Payload-based management API for channel relayerIds and fee limits.
  * - listChannelAccounts: returns relayerIds from KV
  * - setChannelAccounts: replaces relayerIds array in KV (checks lock conflicts)
+ * - getFeeUsage: returns fee consumption for an API key
+ * - getFeeLimit: returns custom limit for an API key (if set)
+ * - setFeeLimit: sets custom limit for an API key
+ * - deleteFeeLimit: removes custom limit for an API key
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isManagementRequest = isManagementRequest;
@@ -12,16 +16,7 @@ exports.handleManagement = handleManagement;
 const relayer_sdk_1 = require("@openzeppelin/relayer-sdk");
 const config_1 = require("./config");
 const constants_1 = require("./constants");
-function timingSafeEqual(a, b) {
-    // Basic constant-time comparison without crypto dep
-    if (a.length !== b.length)
-        return false;
-    let result = 0;
-    for (let i = 0; i < a.length; i++) {
-        result |= a.charCodeAt(i) ^ b.charCodeAt(i);
-    }
-    return result === 0;
-}
+const fee_tracking_1 = require("./fee-tracking");
 function isManagementRequest(params) {
     return Boolean(params &&
         typeof params === "object" &&
@@ -30,8 +25,8 @@ function isManagementRequest(params) {
 }
 async function handleManagement(context) {
     const { kv, params } = context;
-    const adminSecretEnv = (0, config_1.getAdminSecret)();
-    if (!adminSecretEnv) {
+    const config = (0, config_1.loadConfig)();
+    if (!config.adminSecret) {
         throw (0, relayer_sdk_1.pluginError)("Management API disabled", {
             code: "MANAGEMENT_DISABLED",
             status: constants_1.HTTP_STATUS.FORBIDDEN,
@@ -39,20 +34,26 @@ async function handleManagement(context) {
     }
     const m = params?.management || {};
     const provided = (m.adminSecret ?? "").toString();
-    if (!provided || !timingSafeEqual(provided, adminSecretEnv)) {
+    if (!provided || provided !== config.adminSecret) {
         throw (0, relayer_sdk_1.pluginError)("Unauthorized", {
             code: "UNAUTHORIZED",
             status: constants_1.HTTP_STATUS.UNAUTHORIZED,
         });
     }
     const action = String(m.action || "");
-    // Load config (requires env like STELLAR_NETWORK) after auth
-    const cfg = (0, config_1.loadConfig)();
     switch (action) {
         case "listChannelAccounts":
-            return await listChannelAccounts(kv, cfg.network);
+            return await listChannelAccounts(kv, config.network);
         case "setChannelAccounts":
-            return await setChannelAccounts(kv, cfg.network, m);
+            return await setChannelAccounts(kv, config.network, m);
+        case "getFeeUsage":
+            return await getFeeUsage(kv, config.network, config.feeLimit, config.feeResetPeriodMs, m);
+        case "getFeeLimit":
+            return await getFeeLimit(kv, config.network, config.feeLimit, m);
+        case "setFeeLimit":
+            return await setFeeLimit(kv, config.network, m);
+        case "deleteFeeLimit":
+            return await deleteFeeLimit(kv, config.network, m);
         default:
             throw (0, relayer_sdk_1.pluginError)("Invalid management action", {
                 code: "INVALID_ACTION",
@@ -76,6 +77,100 @@ async function listChannelAccounts(kv, network) {
         });
     }
 }
+async function getFeeUsage(kv, network, defaultLimit, resetPeriodMs, payload) {
+    const apiKey = payload?.apiKey;
+    if (!apiKey || typeof apiKey !== "string") {
+        throw (0, relayer_sdk_1.pluginError)("Invalid payload: apiKey is required", {
+            code: "INVALID_PAYLOAD",
+            status: constants_1.HTTP_STATUS.BAD_REQUEST,
+        });
+    }
+    try {
+        const tracker = new fee_tracking_1.FeeTracker({
+            kv,
+            network,
+            apiKey,
+            defaultLimit,
+            resetPeriodMs,
+        });
+        return await tracker.getUsageInfo();
+    }
+    catch (e) {
+        throw (0, relayer_sdk_1.pluginError)("KV error while reading fee usage", {
+            code: "KV_ERROR",
+            status: constants_1.HTTP_STATUS.INTERNAL_SERVER_ERROR,
+        });
+    }
+}
+async function getFeeLimit(kv, network, defaultLimit, payload) {
+    const apiKey = payload?.apiKey;
+    if (!apiKey || typeof apiKey !== "string") {
+        throw (0, relayer_sdk_1.pluginError)("Invalid payload: apiKey is required", {
+            code: "INVALID_PAYLOAD",
+            status: constants_1.HTTP_STATUS.BAD_REQUEST,
+        });
+    }
+    try {
+        const tracker = new fee_tracking_1.FeeTracker({ kv, network, apiKey, defaultLimit });
+        const customLimit = await tracker.getCustomLimit();
+        return {
+            limit: customLimit ?? defaultLimit,
+        };
+    }
+    catch (e) {
+        throw (0, relayer_sdk_1.pluginError)("KV error while reading fee limit", {
+            code: "KV_ERROR",
+            status: constants_1.HTTP_STATUS.INTERNAL_SERVER_ERROR,
+        });
+    }
+}
+async function setFeeLimit(kv, network, payload) {
+    const apiKey = payload?.apiKey;
+    const limit = payload?.limit;
+    if (!apiKey || typeof apiKey !== "string") {
+        throw (0, relayer_sdk_1.pluginError)("Invalid payload: apiKey is required", {
+            code: "INVALID_PAYLOAD",
+            status: constants_1.HTTP_STATUS.BAD_REQUEST,
+        });
+    }
+    if (typeof limit !== "number" || !Number.isFinite(limit) || limit < 0) {
+        throw (0, relayer_sdk_1.pluginError)("Invalid payload: limit must be a non-negative number", {
+            code: "INVALID_PAYLOAD",
+            status: constants_1.HTTP_STATUS.BAD_REQUEST,
+        });
+    }
+    try {
+        const tracker = new fee_tracking_1.FeeTracker({ kv, network, apiKey });
+        await tracker.setCustomLimit(Math.floor(limit));
+        return { ok: true, limit: Math.floor(limit) };
+    }
+    catch (e) {
+        throw (0, relayer_sdk_1.pluginError)("KV error while setting fee limit", {
+            code: "KV_ERROR",
+            status: constants_1.HTTP_STATUS.INTERNAL_SERVER_ERROR,
+        });
+    }
+}
+async function deleteFeeLimit(kv, network, payload) {
+    const apiKey = payload?.apiKey;
+    if (!apiKey || typeof apiKey !== "string") {
+        throw (0, relayer_sdk_1.pluginError)("Invalid payload: apiKey is required", {
+            code: "INVALID_PAYLOAD",
+            status: constants_1.HTTP_STATUS.BAD_REQUEST,
+        });
+    }
+    try {
+        const tracker = new fee_tracking_1.FeeTracker({ kv, network, apiKey });
+        await tracker.deleteCustomLimit();
+        return { ok: true };
+    }
+    catch (e) {
+        throw (0, relayer_sdk_1.pluginError)("KV error while deleting fee limit", {
+            code: "KV_ERROR",
+            status: constants_1.HTTP_STATUS.INTERNAL_SERVER_ERROR,
+        });
+    }
+}
 async function setChannelAccounts(kv, network, payload) {
     const incoming = payload?.relayerIds;
     if (!Array.isArray(incoming)) {

package/dist/plugin/pool.d.ts

@@ -17,7 +17,7 @@ export declare class ChannelPool {
     private readonly channelLockTtlSec;
     private readonly mutexTtlSec;
     private readonly kv;
-    constructor(network: "testnet" | "mainnet", kv: PluginKVStore);
+    constructor(network: "testnet" | "mainnet", kv: PluginKVStore, lockTtlSeconds: number);
     /** Acquire a relayerId with a token lock */
     acquire(): Promise<PoolLock>;
     private withGlobalMutex;

package/dist/plugin/pool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../../src/plugin/pool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAe,MAAM,2BAA2B,CAAC;AAKvE,MAAM,MAAM,QAAQ,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAI5D,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAgB;gBAEvB,OAAO,EAAE,SAAS,GAAG,SAAS,EAAE,EAAE,EAAE,aAAa;IAQ7D,4CAA4C;IACtC,OAAO,IAAI,OAAO,CAAC,QAAQ,CAAC;YAuBpB,eAAe;YASf,iBAAiB;IAwB/B,oCAAoC;IAC9B,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAY5C,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,OAAO;YAID,mBAAmB;CAWlC"}
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../../src/plugin/pool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAe,MAAM,2BAA2B,CAAC;AAIvE,MAAM,MAAM,QAAQ,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAI5D,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAgB;gBAGjC,OAAO,EAAE,SAAS,GAAG,SAAS,EAC9B,EAAE,EAAE,aAAa,EACjB,cAAc,EAAE,MAAM;IASxB,4CAA4C;IACtC,OAAO,IAAI,OAAO,CAAC,QAAQ,CAAC;YAuBpB,eAAe;YAQf,iBAAiB;IAwB/B,oCAAoC;IAC9B,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAY5C,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,OAAO;YAID,mBAAmB;CAWlC"}

package/dist/plugin/pool.js

@@ -14,14 +14,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ChannelPool = void 0;
 const relayer_sdk_1 = require("@openzeppelin/relayer-sdk");
 const crypto_1 = __importDefault(require("crypto"));
-const config_1 = require("./config");
 const constants_1 = require("./constants");
 class ChannelPool {
-    constructor(network, kv) {
+    constructor(network, kv, lockTtlSeconds) {
         this.network = network;
         this.kv = kv;
         this.globalLockKey = `${this.network}:channel-pool-lock`;
-        this.channelLockTtlSec = (0, config_1.getLockTtlSeconds)();
+        this.channelLockTtlSec = lockTtlSeconds;
         this.mutexTtlSec = constants_1.POOL.MUTEX_TTL_SECONDS;
     }
     /** Acquire a relayerId with a token lock */
@@ -45,11 +44,10 @@ class ChannelPool {
     }
     // Run a function under the short-lived global mutex; returns null if busy
     async withGlobalMutex(fn) {
-        const r = (await this.kv.withLock(this.globalLockKey, fn, {
+        return this.kv.withLock(this.globalLockKey, fn, {
             ttlSec: this.mutexTtlSec,
             onBusy: "skip",
-        }));
-        return r;
+        });
     }
     // Inside the mutex: pick an available relayer and set its channel lock
     async tryLockAnyRelayer() {

package/dist/plugin/submit.d.ts

@@ -6,6 +6,7 @@
 import { Transaction } from "@stellar/stellar-sdk";
 import { Relayer, PluginAPI } from "@openzeppelin/relayer-sdk";
 import { ChannelAccountsResponse } from "./types";
+import { FeeTracker } from "./fee-tracking";
 /**
  * Sign transaction with both channel and fund relayers
  * - First sign with channel account
@@ -16,5 +17,5 @@ export declare function signWithChannelAndFund(transaction: Transaction, channel
 /**
  * Submit transaction with fee bump and wait for confirmation
  */
-export declare function submitWithFeeBumpAndWait(fundRelayer: Relayer, signedXdr: string, network: "testnet" | "mainnet", maxFee: number, api: PluginAPI): Promise<ChannelAccountsResponse>;
+export declare function submitWithFeeBumpAndWait(fundRelayer: Relayer, signedXdr: string, network: "testnet" | "mainnet", maxFee: number, api: PluginAPI, tracker?: FeeTracker): Promise<ChannelAccountsResponse>;
 //# sourceMappingURL=submit.d.ts.map

package/dist/plugin/submit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"submit.d.ts","sourceRoot":"","sources":["../../src/plugin/submit.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAEL,OAAO,EAGP,SAAS,EACV,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAElD;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,WAAW,EAAE,WAAW,EACxB,cAAc,EAAE,OAAO,EACvB,YAAY,EAAE,OAAO,EACrB,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,EACpB,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC,WAAW,CAAC,CA2BtB;AAED;;GAEG;AACH,wBAAsB,wBAAwB,CAC5C,WAAW,EAAE,OAAO,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,SAAS,GAAG,SAAS,EAC9B,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,SAAS,GACb,OAAO,CAAC,uBAAuB,CAAC,CAwDlC"}
+{"version":3,"file":"submit.d.ts","sourceRoot":"","sources":["../../src/plugin/submit.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAEL,OAAO,EAGP,SAAS,EACV,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE5C;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,WAAW,EAAE,WAAW,EACxB,cAAc,EAAE,OAAO,EACvB,YAAY,EAAE,OAAO,EACrB,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,EACpB,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC,WAAW,CAAC,CA2BtB;AAED;;GAEG;AACH,wBAAsB,wBAAwB,CAC5C,WAAW,EAAE,OAAO,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,SAAS,GAAG,SAAS,EAC9B,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,SAAS,EACd,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,uBAAuB,CAAC,CAiElC"}

package/dist/plugin/submit.js

@@ -39,7 +39,7 @@ async function signWithChannelAndFund(transaction, channelRelayer, _fundRelayer,
 /**
  * Submit transaction with fee bump and wait for confirmation
  */
-async function submitWithFeeBumpAndWait(fundRelayer, signedXdr, network, maxFee, api) {
+async function submitWithFeeBumpAndWait(fundRelayer, signedXdr, network, maxFee, api, tracker) {
     // Submit with fee bump
     console.debug(`[channels] Sending fee bump tx: network=${network}, maxFee=${maxFee}, xdr_len=${signedXdr.length}`);
     const payload = {
@@ -58,6 +58,10 @@ async function submitWithFeeBumpAndWait(fundRelayer, signedXdr, network, maxFee,
         }));
         // Check if transaction actually succeeded
         if (final.status === "failed") {
+            // Record fee on on-chain failure (transaction was still submitted and consumed fees)
+            if (tracker) {
+                await tracker.recordUsage(maxFee);
+            }
             throw (0, relayer_sdk_1.pluginError)(final.status_reason || "Transaction failed", {
                 code: "ONCHAIN_FAILED",
                 status: constants_1.HTTP_STATUS.BAD_REQUEST,
@@ -69,6 +73,10 @@ async function submitWithFeeBumpAndWait(fundRelayer, signedXdr, network, maxFee,
                 },
             });
         }
+        // Record fee on success
+        if (tracker) {
+            await tracker.recordUsage(maxFee);
+        }
         return {
             transactionId: final.id,
             status: final.status,
@@ -80,7 +88,7 @@ async function submitWithFeeBumpAndWait(fundRelayer, signedXdr, network, maxFee,
         if (error.code === "ONCHAIN_FAILED") {
             throw error;
         }
-        // Otherwise, it's a timeout
+        // Otherwise, it's a timeout - don't track fees (status unknown)
         throw (0, relayer_sdk_1.pluginError)("Transaction wait timeout. It may still submit.", {
             code: "WAIT_TIMEOUT",
             status: constants_1.HTTP_STATUS.GATEWAY_TIMEOUT,