@openzeppelin/relayer-plugin-channels 0.4.0 → 0.6.0

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;;;;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"}
+{"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;;CAGN,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,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
@@ -49,8 +50,6 @@ exports.POLLING = {
     TIMEOUT_MS: 25000,
 };
 exports.FEE = {
-    MIN_BASE_FEE: 205,
-    MAX_BASE_FEE: 605,
     // 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

@@ -1,10 +1,14 @@
 /**
  * fee.ts
  *
- * Dynamic fee calculation for fee bump submissions.
- * - For Soroban transactions: use resourceFee + random inclusion fee
- * - For non-Soroban: use NON_SOROBAN_FEE
+ * Static fee calculation for fee bump submissions matching launchtube.
+ * - For Soroban transactions: use resourceFee + inclusion fee (BASE_FEE * 2 + 3)
+ * - For non-Soroban: use NON_SOROBAN_FEE + inclusion fee
+ * - KALE contract gets reduced fee (BASE_FEE * 2 + 1)
  */
 import { Transaction } from "@stellar/stellar-sdk";
+export declare const KALE_CONTRACT = "CDL74RF5BLYR2YBLCCI7F5FB6TPSCLKEJUBSD2RSVWZ4YHF3VMFAIGWA";
+export declare const INCLUSION_FEE_DEFAULT: number;
+export declare const INCLUSION_FEE_KALE: number;
 export declare function calculateMaxFee(transaction: Transaction): number;
 //# sourceMappingURL=fee.d.ts.map

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

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"fee.d.ts","sourceRoot":"","sources":["../../src/plugin/fee.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAEL,WAAW,EAIZ,MAAM,sBAAsB,CAAC;AAG9B,eAAO,MAAM,aAAa,6DACkC,CAAC;AAC7D,eAAO,MAAM,qBAAqB,QAA2B,CAAC;AAC9D,eAAO,MAAM,kBAAkB,QAA2B,CAAC;AA8B3D,wBAAgB,eAAe,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,CAsBhE"}

package/dist/plugin/fee.js

@@ -2,14 +2,41 @@
 /**
  * fee.ts
  *
- * Dynamic fee calculation for fee bump submissions.
- * - For Soroban transactions: use resourceFee + random inclusion fee
- * - For non-Soroban: use NON_SOROBAN_FEE
+ * Static fee calculation for fee bump submissions matching launchtube.
+ * - For Soroban transactions: use resourceFee + inclusion fee (BASE_FEE * 2 + 3)
+ * - For non-Soroban: use NON_SOROBAN_FEE + inclusion fee
+ * - KALE contract gets reduced fee (BASE_FEE * 2 + 1)
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.INCLUSION_FEE_KALE = exports.INCLUSION_FEE_DEFAULT = exports.KALE_CONTRACT = void 0;
 exports.calculateMaxFee = calculateMaxFee;
 const stellar_sdk_1 = require("@stellar/stellar-sdk");
 const constants_1 = require("./constants");
+exports.KALE_CONTRACT = "CDL74RF5BLYR2YBLCCI7F5FB6TPSCLKEJUBSD2RSVWZ4YHF3VMFAIGWA";
+exports.INCLUSION_FEE_DEFAULT = Number(stellar_sdk_1.BASE_FEE) * 2 + 3;
+exports.INCLUSION_FEE_KALE = Number(stellar_sdk_1.BASE_FEE) * 2 + 1;
+function getInclusionFee(transaction) {
+    try {
+        if (transaction.operations.length !== 1)
+            return exports.INCLUSION_FEE_DEFAULT;
+        const op = transaction.operations[0];
+        if (op.type !== "invokeHostFunction")
+            return exports.INCLUSION_FEE_DEFAULT;
+        const invokeOp = op;
+        if (invokeOp.func.switch() !==
+            stellar_sdk_1.xdr.HostFunctionType.hostFunctionTypeInvokeContract()) {
+            return exports.INCLUSION_FEE_DEFAULT;
+        }
+        const invokeContract = invokeOp.func.invokeContract();
+        const contract = stellar_sdk_1.StrKey.encodeContract(invokeContract.contractAddress().contractId());
+        return contract === exports.KALE_CONTRACT
+            ? exports.INCLUSION_FEE_KALE
+            : exports.INCLUSION_FEE_DEFAULT;
+    }
+    catch {
+        return exports.INCLUSION_FEE_DEFAULT;
+    }
+}
 function calculateMaxFee(transaction) {
     const envelope = transaction.toEnvelope();
     let resourceFee = 0n;
@@ -19,15 +46,10 @@ function calculateMaxFee(transaction) {
             resourceFee = sorobanData.resourceFee().toBigInt();
         }
     }
-    const baseInclusion = getRandomInt(constants_1.FEE.MIN_BASE_FEE, constants_1.FEE.MAX_BASE_FEE);
+    const inclusionFee = getInclusionFee(transaction);
     const fee = resourceFee > 0n
-        ? resourceFee + BigInt(baseInclusion)
-        : BigInt(constants_1.FEE.NON_SOROBAN_FEE + baseInclusion);
-    console.debug(`[channels] Calculated max_fee: ${Number(fee)} stroops (resourceFee: ${resourceFee}, baseInclusion: ${baseInclusion})`);
+        ? resourceFee + BigInt(inclusionFee)
+        : BigInt(constants_1.FEE.NON_SOROBAN_FEE + inclusionFee);
+    console.debug(`[channels] Calculated max_fee: ${Number(fee)} stroops (resourceFee: ${resourceFee}, inclusionFee: ${inclusionFee})`);
     return Number(fee);
 }
-function getRandomInt(min, max) {
-    const mn = Math.ceil(min);
-    const mx = Math.floor(max);
-    return Math.floor(Math.random() * (mx - mn + 1)) + mn;
-}

package/dist/plugin/handler.d.ts

@@ -5,6 +5,15 @@
  * Orchestrates the transaction processing pipeline using channel accounts with fee bumping.
  */
 import { PluginContext } from "@openzeppelin/relayer-sdk";
+import { Transaction, xdr } from "@stellar/stellar-sdk";
+/**
+ * Extracts func and auth from an unsigned Soroban transaction.
+ * Returns null if the transaction is not a single invokeHostFunction operation.
+ */
+export declare function extractFuncAuthFromUnsignedXdr(tx: Transaction): {
+    func: xdr.HostFunction;
+    auth: xdr.SorobanAuthorizationEntry[];
+} | null;
 /**
  * Main plugin handler exported for OpenZeppelin Relayer
  */

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;AASvE,OAAO,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAC;AAcxD;;;GAGG;AACH,wBAAgB,8BAA8B,CAC5C,EAAE,EAAE,WAAW,GACd;IAAE,IAAI,EAAE,GAAG,CAAC,YAAY,CAAC;IAAC,IAAI,EAAE,GAAG,CAAC,yBAAyB,EAAE,CAAA;CAAE,GAAG,IAAI,CAkB1E;AAiOD;;GAEG;AACH,wBAAsB,OAAO,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,CAElE"}

package/dist/plugin/handler.js

@@ -6,6 +6,7 @@
  * Orchestrates the transaction processing pipeline using channel accounts with fee bumping.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractFuncAuthFromUnsignedXdr = extractFuncAuthFromUnsignedXdr;
 exports.handler = handler;
 const relayer_sdk_1 = require("@openzeppelin/relayer-sdk");
 const pool_1 = require("./pool");
@@ -18,13 +19,55 @@ 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;
+}
+/**
+ * Extracts func and auth from an unsigned Soroban transaction.
+ * Returns null if the transaction is not a single invokeHostFunction operation.
+ */
+function extractFuncAuthFromUnsignedXdr(tx) {
+    const ops = tx.operations;
+    if (ops.length !== 1) {
+        return null;
+    }
+    const envelope = tx.toEnvelope();
+    const rawOp = envelope.v1().tx().operations()[0].body();
+    if (rawOp.switch() !== stellar_sdk_1.xdr.OperationType.invokeHostFunction()) {
+        return null;
+    }
+    const invokeHostFn = rawOp.invokeHostFunctionOp();
+    return {
+        func: invokeHostFn.hostFunction(),
+        auth: invokeHostFn.auth(),
+    };
+}
+async function handleXdrSubmit(xdrStr, fundRelayer, fundAddress, network, networkPassphrase, api, pool, tracker) {
     const tx = new stellar_sdk_1.Transaction(xdrStr, networkPassphrase);
+    // Unsigned XDR: extract func+auth and route through channel path
+    if (tx.signatures.length === 0) {
+        const extracted = extractFuncAuthFromUnsignedXdr(tx);
+        if (!extracted) {
+            throw (0, relayer_sdk_1.pluginError)("Unsigned XDR must contain exactly one invokeHostFunction operation", {
+                code: "INVALID_UNSIGNED_XDR",
+                status: constants_1.HTTP_STATUS.BAD_REQUEST,
+                details: {
+                    operationCount: tx.operations.length,
+                    operationType: tx.operations[0]?.type,
+                },
+            });
+        }
+        console.log(`[channels] Unsigned XDR detected, extracting func+auth and routing through channel path`);
+        return handleFuncAuthSubmit(extracted.func, extracted.auth, api, pool, fundRelayer, fundAddress, network, networkPassphrase, tracker);
+    }
     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 +95,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,56 +105,69 @@ 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);
-    try {
-        // 1. Validate and parse request (xdr OR func+auth)
-        const request = (0, validation_1.validateAndParseRequest)(params);
-        console.debug(`[channels] Request type: ${request.type}, auth entries: ${request.type === "func-auth" ? request.auth.length : "N/A"}`);
-        // 2. Get fund relayer
-        const fundRelayer = api.useRelayer(config.fundRelayerId);
-        const fundInfo = await fundRelayer.getRelayer();
-        if (!fundInfo || !fundInfo.address) {
-            throw (0, relayer_sdk_1.pluginError)("Fund relayer not found", {
-                code: "RELAYER_UNAVAILABLE",
-                status: constants_1.HTTP_STATUS.BAD_GATEWAY,
-                details: { relayerId: config.fundRelayerId },
-            });
-        }
-        const fundStatus = await fundRelayer.getRelayerStatus();
-        if (fundStatus.network_type !== "stellar") {
-            throw (0, relayer_sdk_1.pluginError)("Fund relayer network type must be stellar", {
-                code: "UNSUPPORTED_NETWORK",
-                status: constants_1.HTTP_STATUS.BAD_REQUEST,
-                details: {
-                    network_type: fundStatus.network_type,
-                    relayerId: config.fundRelayerId,
-                },
-            });
-        }
-        // 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);
-        }
-        console.log(`[channels] Flow: func+auth with channel account`);
-        return await handleFuncAuthSubmit(request.func, request.auth, api, pool, fundRelayer, fundInfo.address, config.network, networkPassphrase);
+    // 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,
+        });
     }
-    finally {
-        // Nothing to cleanup here; func-auth path releases locks internally
+    // 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,
+        });
+    }
+    // 1. Validate and parse request (xdr OR func+auth)
+    const request = (0, validation_1.validateAndParseRequest)(params);
+    console.debug(`[channels] Request type: ${request.type}, auth entries: ${request.type === "func-auth" ? request.auth.length : "N/A"}`);
+    // 2. Get fund relayer
+    const fundRelayer = api.useRelayer(config.fundRelayerId);
+    const fundInfo = await fundRelayer.getRelayer();
+    if (!fundInfo || !fundInfo.address) {
+        throw (0, relayer_sdk_1.pluginError)("Fund relayer not found", {
+            code: "RELAYER_UNAVAILABLE",
+            status: constants_1.HTTP_STATUS.BAD_GATEWAY,
+            details: { relayerId: config.fundRelayerId },
+        });
+    }
+    if (fundInfo.network_type !== "stellar") {
+        throw (0, relayer_sdk_1.pluginError)("Fund relayer network type must be stellar", {
+            code: "UNSUPPORTED_NETWORK",
+            status: constants_1.HTTP_STATUS.BAD_REQUEST,
+            details: {
+                network_type: fundInfo.network_type,
+                relayerId: config.fundRelayerId,
+            },
+        });
+    }
+    // 3. Branch by request type
+    if (request.type === "xdr") {
+        console.log(`[channels] Flow: XDR submit-only`);
+        return await handleXdrSubmit(request.xdr, fundRelayer, fundInfo.address, config.network, networkPassphrase, api, pool, 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, tracker);
 }
 /**
  * Main plugin handler exported for OpenZeppelin Relayer
  */
 async function handler(context) {
-    const result = await channelAccounts(context);
-    return result;
+    return channelAccounts(context);
 }

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"}