@openzeppelin/relayer-plugin-channels 0.3.1 → 0.5.0

package/dist/plugin/config.js

@@ -7,9 +7,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadConfig = loadConfig;
 exports.getNetworkPassphrase = getNetworkPassphrase;
-exports.getLockTtlSeconds = getLockTtlSeconds;
-exports.getMaxFee = getMaxFee;
-exports.getAdminSecret = getAdminSecret;
 const stellar_sdk_1 = require("@stellar/stellar-sdk");
 const relayer_sdk_1 = require("@openzeppelin/relayer-sdk");
 const constants_1 = require("./constants");
@@ -24,6 +21,46 @@ function requireEnv(name) {
     }
     return v.trim();
 }
+function parseOptionalString(name) {
+    const v = process.env[name];
+    if (!v)
+        return undefined;
+    const t = v.trim();
+    return t.length ? t : undefined;
+}
+function parseLockTtl() {
+    const raw = process.env.LOCK_TTL_SECONDS;
+    if (!raw)
+        return constants_1.CONFIG.DEFAULT_LOCK_TTL_SECONDS;
+    const n = Number(raw);
+    if (!Number.isFinite(n) ||
+        n < constants_1.CONFIG.MIN_LOCK_TTL_SECONDS ||
+        n > constants_1.CONFIG.MAX_LOCK_TTL_SECONDS) {
+        return constants_1.CONFIG.DEFAULT_LOCK_TTL_SECONDS;
+    }
+    return Math.floor(n);
+}
+function parseFeeLimit() {
+    const raw = process.env.FEE_LIMIT;
+    if (!raw)
+        return undefined;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 0 ? Math.floor(n) : undefined;
+}
+function parseFeeResetPeriod() {
+    const raw = process.env.FEE_RESET_PERIOD_SECONDS;
+    if (!raw)
+        return undefined;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) * 1000 : undefined;
+}
+function parseApiKeyHeader() {
+    const raw = process.env.API_KEY_HEADER;
+    if (!raw)
+        return "x-api-key";
+    const trimmed = raw.trim().toLowerCase();
+    return trimmed.length > 0 ? trimmed : "x-api-key";
+}
 /**
  * Load configuration from environment variables
  */
@@ -35,12 +72,14 @@ function loadConfig() {
             status: constants_1.HTTP_STATUS.BAD_REQUEST,
         });
     }
-    const fundRelayerId = requireEnv("FUND_RELAYER_ID");
-    const rpcUrl = requireEnv("SOROBAN_RPC_URL");
     return {
-        fundRelayerId,
+        fundRelayerId: requireEnv("FUND_RELAYER_ID"),
         network: networkRaw,
-        rpcUrl,
+        lockTtlSeconds: parseLockTtl(),
+        adminSecret: parseOptionalString("PLUGIN_ADMIN_SECRET"),
+        feeLimit: parseFeeLimit(),
+        feeResetPeriodMs: parseFeeResetPeriod(),
+        apiKeyHeader: parseApiKeyHeader(),
     };
 }
 /**
@@ -49,41 +88,3 @@ function loadConfig() {
 function getNetworkPassphrase(network) {
     return network === "mainnet" ? stellar_sdk_1.Networks.PUBLIC : stellar_sdk_1.Networks.TESTNET;
 }
-/**
- * Get the per-channel lock TTL in seconds (default 30)
- */
-function getLockTtlSeconds() {
-    const raw = process.env.LOCK_TTL_SECONDS;
-    if (!raw)
-        return constants_1.CONFIG.DEFAULT_LOCK_TTL_SECONDS;
-    const n = Number(raw);
-    if (!Number.isFinite(n) ||
-        n < constants_1.CONFIG.MIN_LOCK_TTL_SECONDS ||
-        n > constants_1.CONFIG.MAX_LOCK_TTL_SECONDS) {
-        return constants_1.CONFIG.DEFAULT_LOCK_TTL_SECONDS;
-    }
-    return Math.floor(n);
-}
-/**
- * Get the max fee for fee bump transactions
- */
-function getMaxFee() {
-    const raw = process.env.MAX_FEE;
-    if (!raw)
-        return constants_1.CONFIG.DEFAULT_MAX_FEE;
-    const n = Number(raw);
-    if (!Number.isFinite(n) || n <= 0) {
-        return constants_1.CONFIG.DEFAULT_MAX_FEE;
-    }
-    return Math.floor(n);
-}
-/**
- * Get the admin secret for management API
- */
-function getAdminSecret() {
-    const v = process.env.PLUGIN_ADMIN_SECRET;
-    if (!v)
-        return undefined;
-    const t = v.trim();
-    return t.length ? t : undefined;
-}

package/dist/plugin/constants.d.ts

@@ -8,6 +8,7 @@ export declare const HTTP_STATUS: {
     readonly UNAUTHORIZED: 401;
     readonly FORBIDDEN: 403;
     readonly CONFLICT: 409;
+    readonly TOO_MANY_REQUESTS: 429;
     readonly INTERNAL_SERVER_ERROR: 500;
     readonly BAD_GATEWAY: 502;
     readonly SERVICE_UNAVAILABLE: 503;
@@ -15,9 +16,8 @@ export declare const HTTP_STATUS: {
 };
 export declare const CONFIG: {
     readonly DEFAULT_LOCK_TTL_SECONDS: 30;
-    readonly MIN_LOCK_TTL_SECONDS: 10;
+    readonly MIN_LOCK_TTL_SECONDS: 3;
     readonly MAX_LOCK_TTL_SECONDS: 30;
-    readonly DEFAULT_MAX_FEE: 1000000;
 };
 export declare const POOL: {
     readonly MUTEX_TTL_SECONDS: 1;
@@ -41,6 +41,6 @@ export declare const POLLING: {
 export declare const FEE: {
     readonly MIN_BASE_FEE: 205;
     readonly MAX_BASE_FEE: 605;
-    readonly RESOURCE_FEE_OFFSET: 60000;
+    readonly NON_SOROBAN_FEE: 100000;
 };
 //# sourceMappingURL=constants.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/plugin/constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,eAAO,MAAM,WAAW;;;;;;;;;CASd,CAAC;AAGX,eAAO,MAAM,MAAM;;;;;CAKT,CAAC;AAGX,eAAO,MAAM,IAAI;;;;;CAOP,CAAC;AAGX,eAAO,MAAM,IAAI;;CAEP,CAAC;AAGX,eAAO,MAAM,UAAU;;;;;CAKb,CAAC;AAGX,eAAO,MAAM,OAAO;;;CAGV,CAAC;AAEX,eAAO,MAAM,GAAG;;;;CAIN,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/plugin/constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,eAAO,MAAM,WAAW;;;;;;;;;;CAUd,CAAC;AAGX,eAAO,MAAM,MAAM;;;;CAIT,CAAC;AAGX,eAAO,MAAM,IAAI;;;;;CAOP,CAAC;AAGX,eAAO,MAAM,IAAI;;CAEP,CAAC;AAGX,eAAO,MAAM,UAAU;;;;;CAKb,CAAC;AAGX,eAAO,MAAM,OAAO;;;CAGV,CAAC;AAEX,eAAO,MAAM,GAAG;;;;CAKN,CAAC"}

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,9 +21,8 @@ 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,
-    DEFAULT_MAX_FEE: 1000000,
 };
 // Pool Constants
 exports.POOL = {
@@ -52,5 +52,6 @@ exports.POLLING = {
 exports.FEE = {
     MIN_BASE_FEE: 205,
     MAX_BASE_FEE: 605,
-    RESOURCE_FEE_OFFSET: 60000,
+    // For non-Soroban txs: 100,000 stroops (0.01 XLM) per Stellar best practice
+    NON_SOROBAN_FEE: 100000,
 };

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/fee.d.ts

@@ -2,9 +2,8 @@
  * fee.ts
  *
  * Dynamic fee calculation for fee bump submissions.
- * - For Soroban transactions, use resourceFee + random inclusion fee
- * - For non-Soroban, add a fixed offset for safety
- * - Optionally clamp to env MAX_FEE via config helper
+ * - For Soroban transactions: use resourceFee + random inclusion fee
+ * - For non-Soroban: use NON_SOROBAN_FEE
  */
 import { Transaction } from "@stellar/stellar-sdk";
 export declare function calculateMaxFee(transaction: Transaction): number;

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

@@ -1 +1 @@
-{"version":3,"file":"fee.d.ts","sourceRoot":"","sources":["../../src/plugin/fee.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAO,MAAM,sBAAsB,CAAC;AAIxD,wBAAgB,eAAe,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,CA2BhE"}
+{"version":3,"file":"fee.d.ts","sourceRoot":"","sources":["../../src/plugin/fee.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,WAAW,EAAO,MAAM,sBAAsB,CAAC;AAGxD,wBAAgB,eAAe,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,CAsBhE"}

package/dist/plugin/fee.js

@@ -3,15 +3,13 @@
  * fee.ts
  *
  * Dynamic fee calculation for fee bump submissions.
- * - For Soroban transactions, use resourceFee + random inclusion fee
- * - For non-Soroban, add a fixed offset for safety
- * - Optionally clamp to env MAX_FEE via config helper
+ * - For Soroban transactions: use resourceFee + random inclusion fee
+ * - For non-Soroban: use NON_SOROBAN_FEE
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.calculateMaxFee = calculateMaxFee;
 const stellar_sdk_1 = require("@stellar/stellar-sdk");
 const constants_1 = require("./constants");
-const config_1 = require("./config");
 function calculateMaxFee(transaction) {
     const envelope = transaction.toEnvelope();
     let resourceFee = 0n;
@@ -22,17 +20,11 @@ function calculateMaxFee(transaction) {
         }
     }
     const baseInclusion = getRandomInt(constants_1.FEE.MIN_BASE_FEE, constants_1.FEE.MAX_BASE_FEE);
-    let dynamic = resourceFee > 0n
+    const fee = resourceFee > 0n
         ? resourceFee + BigInt(baseInclusion)
-        : BigInt(constants_1.FEE.RESOURCE_FEE_OFFSET + baseInclusion);
-    // Optional cap from env
-    const cap = (0, config_1.getMaxFee)();
-    if (typeof cap === "number" && Number.isFinite(cap) && cap > 0) {
-        if (dynamic > BigInt(cap))
-            dynamic = BigInt(cap);
-    }
-    console.debug(`[channels] Calculated max_fee: ${Number(dynamic)} stroops (resourceFee: ${resourceFee}, baseInclusion: ${baseInclusion})`);
-    return Number(dynamic);
+        : BigInt(constants_1.FEE.NON_SOROBAN_FEE + baseInclusion);
+    console.debug(`[channels] Calculated max_fee: ${Number(fee)} stroops (resourceFee: ${resourceFee}, baseInclusion: ${baseInclusion})`);
+    return Number(fee);
 }
 function getRandomInt(min, max) {
     const mn = Math.ceil(min);

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;AAgLvE;;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, rpc) {
+async function handleFuncAuthSubmit(func, auth, api, pool, fundRelayer, fundAddress, network, networkPassphrase, tracker) {
     let poolLock;
     try {
         poolLock = await pool.acquire();
@@ -49,10 +55,11 @@ 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, rpc, networkPassphrase);
+        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,16 +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);
-    const rpc = new stellar_sdk_1.SorobanRpc.Server(config.rpcUrl);
+    // 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);
@@ -99,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, rpc);
+        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"}