@openzeppelin/relayer-plugin-channels 0.17.0 → 0.18.0

package/dist/plugin/config.d.ts

@@ -19,6 +19,8 @@ export interface ChannelAccountsConfig {
     inclusionFeeLimited: number;
     sequenceNumberCacheMaxAgeMs: number;
     minSignatureExpirationLedgerBuffer: number;
+    globalTimeoutMs: number;
+    pollingTimeoutMs: number;
 }
 /**
  * Load configuration from environment variables

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

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/plugin/config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAUH,MAAM,WAAW,qBAAqB;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,wFAAwF;IACxF,qBAAqB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACnC,OAAO,EAAE,SAAS,GAAG,SAAS,CAAC;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,2BAA2B,EAAE,MAAM,CAAC;IACpC,kCAAkC,EAAE,MAAM,CAAC;CAC5C;AAsHD;;GAEG;AACH,wBAAgB,UAAU,IAAI,qBAAqB,CA2BlD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,CAE3E"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/plugin/config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAUH,MAAM,WAAW,qBAAqB;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,wFAAwF;IACxF,qBAAqB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACnC,OAAO,EAAE,SAAS,GAAG,SAAS,CAAC;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,2BAA2B,EAAE,MAAM,CAAC;IACpC,kCAAkC,EAAE,MAAM,CAAC;IAC3C,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAoID;;GAEG;AACH,wBAAgB,UAAU,IAAI,qBAAqB,CA6BlD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,CAE3E"}

package/dist/plugin/config.js

@@ -117,6 +117,20 @@ function parseAllowedFundRelayerIds() {
     }
     return ids;
 }
+function parseGlobalTimeoutMs() {
+    const raw = process.env.PLUGIN_GLOBAL_TIMEOUT_MS;
+    if (!raw)
+        return constants_1.TIMEOUT.DEFAULT_GLOBAL_TIMEOUT_MS;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : constants_1.TIMEOUT.DEFAULT_GLOBAL_TIMEOUT_MS;
+}
+function parsePollingTimeoutMs() {
+    const raw = process.env.PLUGIN_POLLING_TIMEOUT_MS;
+    if (!raw)
+        return constants_1.POLLING.DEFAULT_TIMEOUT_MS;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : constants_1.POLLING.DEFAULT_TIMEOUT_MS;
+}
 function parseContractCapacityRatio() {
     const raw = process.env.CONTRACT_CAPACITY_RATIO;
     if (!raw)
@@ -154,6 +168,8 @@ function loadConfig() {
         inclusionFeeLimited: parseInclusionFee('INCLUSION_FEE_LIMITED', DEFAULT_INCLUSION_FEE_LIMITED),
         sequenceNumberCacheMaxAgeMs: parseSequenceNumberCacheMaxAge(),
         minSignatureExpirationLedgerBuffer: parseMinAuthExpiryLedgerBuffer(),
+        globalTimeoutMs: parseGlobalTimeoutMs(),
+        pollingTimeoutMs: parsePollingTimeoutMs(),
     };
 }
 /**

package/dist/plugin/constants.d.ts

@@ -23,10 +23,12 @@ export declare const CONFIG: {
     readonly DEFAULT_MIN_SIGNATURE_EXPIRATION_LEDGER_BUFFER: 2;
 };
 export declare const POOL: {
-    readonly MUTEX_TTL_SECONDS: 1;
-    readonly MUTEX_MAX_SPINS: 30;
-    readonly MUTEX_RETRY_MIN_MS: 10;
-    readonly MUTEX_RETRY_MAX_MS: 30;
+    readonly CLAIM_LOCK_TTL_SECONDS: 3;
+    readonly ACQUIRE_MAX_SPINS: 30;
+    readonly ACQUIRE_RETRY_MIN_MS: 10;
+    readonly ACQUIRE_RETRY_MAX_MS: 30;
+    readonly CHANNEL_COOLDOWN_MS: 6000;
+    readonly LRU_MAP_TTL_SECONDS: 86400;
 };
 export declare const TIME: {
     readonly MAX_TIME_BOUND_OFFSET_SECONDS: 60;
@@ -41,12 +43,12 @@ export declare const SIMULATION: {
     readonly MIN_SIGNATURE_EXPIRATION_LEDGER_BUFFER: 2;
 };
 export declare const TIMEOUT: {
-    readonly GLOBAL_TIMEOUT_MS: 30000;
+    readonly DEFAULT_GLOBAL_TIMEOUT_MS: 30000;
     readonly BUFFER_MS: 2000;
 };
 export declare const POLLING: {
     readonly INTERVAL_MS: 1000;
-    readonly TIMEOUT_MS: 25000;
+    readonly DEFAULT_TIMEOUT_MS: 25000;
 };
 export declare const FEE: {
     readonly NON_SOROBAN_FEE: 100000;

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;;;;;;;;;;CAUd,CAAC;AAGX,eAAO,MAAM,MAAM;;;;;;;CAOT,CAAC;AAGX,eAAO,MAAM,IAAI;;;;;CAOP,CAAC;AAGX,eAAO,MAAM,IAAI;;CAEP,CAAC;AAGX,eAAO,MAAM,UAAU;;;;;;IAMrB,uLAAuL;;CAE/K,CAAC;AAGX,eAAO,MAAM,OAAO;;;CAGV,CAAC;AAGX,eAAO,MAAM,OAAO;;;CAGV,CAAC;AAEX,eAAO,MAAM,GAAG;;CAGN,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;;;;;;;CAOT,CAAC;AAGX,eAAO,MAAM,IAAI;;;;;;;CAYP,CAAC;AAGX,eAAO,MAAM,IAAI;;CAEP,CAAC;AAGX,eAAO,MAAM,UAAU;;;;;;IAMrB,uLAAuL;;CAE/K,CAAC;AAGX,eAAO,MAAM,OAAO;;;CAGV,CAAC;AAGX,eAAO,MAAM,OAAO;;;CAGV,CAAC;AAEX,eAAO,MAAM,GAAG;;CAGN,CAAC"}

package/dist/plugin/constants.js

@@ -29,12 +29,17 @@ exports.CONFIG = {
 };
 // Pool Constants
 exports.POOL = {
-    // TTL for the short global mutex guarding acquire()
-    MUTEX_TTL_SECONDS: 1,
-    // Retry policy when mutex is busy
-    MUTEX_MAX_SPINS: 30,
-    MUTEX_RETRY_MIN_MS: 10,
-    MUTEX_RETRY_MAX_MS: 30,
+    // Per-channel claim lock TTL — must exceed worst-case callback latency
+    // to prevent TTL expiry allowing a second worker into the same claim section
+    CLAIM_LOCK_TTL_SECONDS: 3,
+    // Retry policy when all candidates busy
+    ACQUIRE_MAX_SPINS: 30,
+    ACQUIRE_RETRY_MIN_MS: 10,
+    ACQUIRE_RETRY_MAX_MS: 30,
+    // Hard-block cooldown for uncertain-outcome channels (~1 Stellar ledger with margin)
+    CHANNEL_COOLDOWN_MS: 6000,
+    // Housekeeping TTL for the single LRU map document
+    LRU_MAP_TTL_SECONDS: 86400,
 };
 // Time Constants
 exports.TIME = {
@@ -52,13 +57,13 @@ exports.SIMULATION = {
 };
 // Global plugin timeout budget
 exports.TIMEOUT = {
-    GLOBAL_TIMEOUT_MS: 30000,
+    DEFAULT_GLOBAL_TIMEOUT_MS: 30000,
     BUFFER_MS: 2000,
 };
 // Polling for transactionWait
 exports.POLLING = {
     INTERVAL_MS: 1000,
-    TIMEOUT_MS: 25000,
+    DEFAULT_TIMEOUT_MS: 25000,
 };
 exports.FEE = {
     // For non-Soroban txs: 100,000 stroops (0.01 XLM) per Stellar best practice

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;AASvE,OAAO,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAC;AA2BxD;;;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;AA4SD;;GAEG;AACH,wBAAsB,OAAO,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,CAElE"}
+{"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;AA2BxD;;;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;AAyTD;;GAEG;AACH,wBAAsB,OAAO,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,CAElE"}

package/dist/plugin/handler.js

@@ -74,7 +74,7 @@ async function handleXdrSubmit(xdrStr, ctx, skipWait) {
         contractId,
         isLimited: contractId ? ctx.acquireOptions.limitedContracts.has(contractId) : false,
     };
-    return (0, submit_1.submitWithFeeBumpAndWait)(ctx.fundRelayer, validated.toXDR(), ctx.network, maxFee, ctx.api, ctx.startTime, ctx.tracker, submitContext, skipWait);
+    return (0, submit_1.submitWithFeeBumpAndWait)(ctx.fundRelayer, validated.toXDR(), ctx.network, maxFee, ctx.api, ctx.startTime, ctx.tracker, submitContext, skipWait, ctx.config);
 }
 async function handleFuncAuthSubmit(func, auth, ctx, skipWait) {
     // Simulate once — used for both read-only detection and transaction assembly
@@ -90,6 +90,7 @@ async function handleFuncAuthSubmit(func, auth, ctx, skipWait) {
         };
     }
     let poolLock;
+    let needsCooldown = false;
     try {
         poolLock = await ctx.pool.acquire(ctx.acquireOptions);
         const channelRelayer = ctx.api.useRelayer(poolLock.relayerId);
@@ -123,9 +124,8 @@ async function handleFuncAuthSubmit(func, auth, ctx, skipWait) {
             isLimited: contractId ? ctx.acquireOptions.limitedContracts.has(contractId) : false,
         };
         try {
-            const result = await (0, submit_1.submitWithFeeBumpAndWait)(ctx.fundRelayer, signedTx.toXDR(), ctx.network, maxFee, ctx.api, ctx.startTime, ctx.tracker, submitContext, skipWait);
+            const result = await (0, submit_1.submitWithFeeBumpAndWait)(ctx.fundRelayer, signedTx.toXDR(), ctx.network, maxFee, ctx.api, ctx.startTime, ctx.tracker, submitContext, skipWait, ctx.config);
             if (result.status === 'pending' || result.status === 'sent' || result.status === 'submitted') {
-                // extend lock and clear sequence
                 console.log(`[channels]: extending lock and clearing sequence`);
                 await ctx.pool.extendLock(poolLock);
                 await (0, sequence_1.clearSequence)(ctx.kv, ctx.network, channelInfo.address);
@@ -135,7 +135,9 @@ async function handleFuncAuthSubmit(func, auth, ctx, skipWait) {
                 await (0, sequence_1.commitSequence)(ctx.kv, ctx.network, channelInfo.address, sequence);
             }
             else {
+                // Unknown status — uncertain outcome → release with cooldown
                 await (0, sequence_1.clearSequence)(ctx.kv, ctx.network, channelInfo.address);
+                needsCooldown = true;
             }
             return result;
         }
@@ -146,12 +148,22 @@ async function handleFuncAuthSubmit(func, auth, ctx, skipWait) {
                 await ctx.pool.extendLock(poolLock);
                 poolLock = undefined; // skip release in finally
             }
+            else if (error.code === 'ONCHAIN_FAILED') {
+                // Sequence was consumed (tx landed on chain) — cooldown prevents
+                // next acquirer from hitting stale RPC and reusing old sequence
+                needsCooldown = true;
+            }
             throw error;
         }
     }
     finally {
         if (poolLock) {
-            await ctx.pool.release(poolLock);
+            if (needsCooldown) {
+                await ctx.pool.releaseWithCooldown(poolLock);
+            }
+            else {
+                await ctx.pool.release(poolLock);
+            }
         }
     }
 }

package/dist/plugin/management.js

@@ -171,12 +171,8 @@ async function setChannelAccounts(kv, network, payload) {
     const current = await readStoredRelayerIds(kv, listKey);
     // Check for locked removals
     const removals = current.filter((id) => !relayerIds.includes(id));
-    const locked = [];
-    for (const id of removals) {
-        if (await isRelayerIdLocked(kv, network, id)) {
-            locked.push(id);
-        }
-    }
+    const lockedSet = await getLockedRelayerIds(kv, network);
+    const locked = removals.filter((id) => lockedSet.has(id));
     if (locked.length > 0) {
         throw (0, relayer_sdk_1.pluginError)('Locked relayer IDs cannot be removed', {
             code: 'LOCKED_CONFLICT',
@@ -211,12 +207,12 @@ async function getPoolStats(config, kv) {
             status: constants_1.HTTP_STATUS.INTERNAL_SERVER_ERROR,
         });
     }
-    // 2. Check all locks in parallel (N KV calls) — best-effort
+    // 2. Check locks via single listKeys scan — best-effort
     let locked;
     let available;
     try {
-        const results = await Promise.all(relayerIds.map((id) => kv.exists(`${network}:channel:in-use:${id}`)));
-        locked = results.filter(Boolean).length;
+        const lockedSet = await getLockedRelayerIds(kv, network);
+        locked = relayerIds.filter((id) => lockedSet.has(id)).length;
         available = relayerIds.length - locked;
     }
     catch {
@@ -268,16 +264,17 @@ async function readStoredRelayerIds(kv, key) {
         });
     }
 }
-async function isRelayerIdLocked(kv, network, id) {
-    const key = `${network}:channel:in-use:${id}`;
+async function getLockedRelayerIds(kv, network) {
+    const prefix = `${network}:channel:in-use:`;
     try {
-        return await kv.exists(key);
+        const keys = await kv.listKeys(`${prefix}*`);
+        return new Set(keys.map((k) => k.slice(prefix.length)));
     }
     catch (error) {
-        throw (0, relayer_sdk_1.pluginError)('KV error while checking relayer lock', {
+        throw (0, relayer_sdk_1.pluginError)('KV error while checking relayer locks', {
             code: 'KV_ERROR',
             status: constants_1.HTTP_STATUS.INTERNAL_SERVER_ERROR,
-            details: { relayerId: id, key, message: error instanceof Error ? error.message : String(error) },
+            details: { prefix, pattern: `${prefix}*`, message: error instanceof Error ? error.message : String(error) },
         });
     }
 }

package/dist/plugin/pool.d.ts

@@ -4,7 +4,7 @@
  * KV-backed, stateless channel pool.
  * - Membership comes from KV: <network>:channel:relayer-ids
  * - Per-relayer locks with tokens: <network>:channel:in-use:<relayerId>
- * - Uses a short global mutex to make acquire atomic across workers.
+ * - Uses per-channel claim locks to make acquire safe across workers.
  */
 import { PluginKVStore } from '@openzeppelin/relayer-sdk';
 export type PoolLock = {
@@ -18,21 +18,27 @@ export type AcquireOptions = {
 };
 export declare class ChannelPool {
     private readonly network;
-    private readonly globalLockKey;
     private readonly channelLockTtlSec;
-    private readonly mutexTtlSec;
     private readonly kv;
     constructor(network: 'testnet' | 'mainnet', kv: PluginKVStore, lockTtlSeconds: number);
     /** Acquire a relayerId with a token lock */
     acquire(options: AcquireOptions): Promise<PoolLock>;
-    private withGlobalMutex;
-    private tryLockAnyRelayer;
+    /** Read phase + claim phase (no global mutex) */
+    private tryAcquire;
+    /** Attempt to claim a single channel under its per-channel lock */
+    private tryClaimChannel;
     /** Extend the lock TTL if we still own it (e.g. after WAIT_TIMEOUT) */
     extendLock(lock: PoolLock, ttlSec?: number): Promise<void>;
     /** Release the lock if we own it */
     release(lock: PoolLock): Promise<void>;
+    /** Release with cooldown: keeps lock alive with short TTL to hard-block the channel. */
+    releaseWithCooldown(lock: PoolLock, cooldownMs?: 6000): Promise<void>;
     private membershipKey;
+    private lockKeyPrefix;
     private lockKey;
+    private claimKey;
+    private lruMapKey;
+    private updateLruMap;
     private getRelayerIdsFromKV;
     private getPoolCapacityDetails;
 }

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;AAIvE,MAAM,MAAM,QAAQ,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5D,MAAM,MAAM,cAAc,GAAG;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAUF,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,EAAE,cAAc,EAAE,MAAM;IAQrF,4CAA4C;IACtC,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC;YAyB3C,eAAe;YAKf,iBAAiB;IA2B/B,uEAAuE;IACjE,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBhE,oCAAoC;IAC9B,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAY5C,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,OAAO;YAID,mBAAmB;YAYnB,sBAAsB;CAUrC"}
+{"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;AAE5D,MAAM,MAAM,cAAc,GAAG;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAUF,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAgB;gBAEvB,OAAO,EAAE,SAAS,GAAG,SAAS,EAAE,EAAE,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM;IAMrF,4CAA4C;IACtC,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC;IAuBzD,iDAAiD;YACnC,UAAU;IAqDxB,mEAAmE;YACrD,eAAe;IAsB7B,uEAAuE;IACjE,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBhE,oCAAoC;IAC9B,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAY5C,wFAAwF;IAClF,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,UAAU,OAA2B,GAAG,OAAO,CAAC,IAAI,CAAC;IAa/F,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,SAAS;YAIH,YAAY;YAWZ,mBAAmB;YAYnB,sBAAsB;CAUrC"}

package/dist/plugin/pool.js

@@ -5,7 +5,7 @@
  * KV-backed, stateless channel pool.
  * - Membership comes from KV: <network>:channel:relayer-ids
  * - Per-relayer locks with tokens: <network>:channel:in-use:<relayerId>
- * - Uses a short global mutex to make acquire atomic across workers.
+ * - Uses per-channel claim locks to make acquire safe across workers.
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
@@ -19,21 +19,18 @@ class ChannelPool {
     constructor(network, kv, lockTtlSeconds) {
         this.network = network;
         this.kv = kv;
-        this.globalLockKey = `${this.network}:channel-pool-lock`;
         this.channelLockTtlSec = lockTtlSeconds;
-        this.mutexTtlSec = constants_1.POOL.MUTEX_TTL_SECONDS;
     }
     /** Acquire a relayerId with a token lock */
     async acquire(options) {
-        const maxSpins = constants_1.POOL.MUTEX_MAX_SPINS;
+        const maxSpins = constants_1.POOL.ACQUIRE_MAX_SPINS;
         for (let i = 0; i < maxSpins; i++) {
-            const r = await this.withGlobalMutex(() => this.tryLockAnyRelayer(options));
-            if (r === null) {
-                const jitter = constants_1.POOL.MUTEX_RETRY_MIN_MS + Math.floor(Math.random() * (constants_1.POOL.MUTEX_RETRY_MAX_MS - constants_1.POOL.MUTEX_RETRY_MIN_MS + 1));
-                await sleep(jitter);
-                continue;
-            }
-            return r;
+            const result = await this.tryAcquire(options);
+            if (result)
+                return result;
+            const jitter = constants_1.POOL.ACQUIRE_RETRY_MIN_MS +
+                Math.floor(Math.random() * (constants_1.POOL.ACQUIRE_RETRY_MAX_MS - constants_1.POOL.ACQUIRE_RETRY_MIN_MS + 1));
+            await sleep(jitter);
         }
         const diagnostics = await this.getPoolCapacityDetails(options, maxSpins);
         console.warn('[channels] Pool capacity exhausted', diagnostics);
@@ -43,12 +40,9 @@ class ChannelPool {
             details: diagnostics,
         });
     }
-    // Run a function under the short-lived global mutex; returns null if busy
-    async withGlobalMutex(fn) {
-        return this.kv.withLock(this.globalLockKey, fn, { ttlSec: this.mutexTtlSec, onBusy: 'skip' });
-    }
-    // Inside the mutex: pick an available relayer and set its channel lock
-    async tryLockAnyRelayer(options) {
+    /** Read phase + claim phase (no global mutex) */
+    async tryAcquire(options) {
+        // --- READ PHASE (no lock) ---
         let ids = await this.getRelayerIdsFromKV();
         if (ids.length === 0) {
             throw (0, relayer_sdk_1.pluginError)('No channel accounts configured. Use the management API to set channel accounts.', {
@@ -56,23 +50,58 @@ class ChannelPool {
                 status: constants_1.HTTP_STATUS.SERVICE_UNAVAILABLE,
             });
         }
-        // If contract is limited, filter to allowed subset
         if (options.contractId && options.limitedContracts.has(options.contractId)) {
             ids = filterChannelsForLimitedContract(ids, options.capacityRatio);
         }
-        shuffle(ids);
-        for (const relayerId of ids) {
-            const key = this.lockKey(relayerId);
-            const exists = await this.kv.exists(key);
-            if (exists)
-                continue;
-            const token = randomToken();
-            const entry = { token, lockedAt: new Date().toISOString() };
-            await this.kv.set(key, entry, { ttlSec: this.channelLockTtlSec });
-            return { relayerId, token };
+        const lockPrefix = this.lockKeyPrefix();
+        let lruMap = {};
+        try {
+            lruMap = (await this.kv.get(this.lruMapKey())) ?? {};
+        }
+        catch (err) {
+            console.warn('[channels] LRU map read failed, using empty ordering map', err);
+        }
+        let lockedSet;
+        try {
+            const lockedKeys = await this.kv.listKeys(`${lockPrefix}*`);
+            lockedSet = new Set(lockedKeys.map((k) => k.slice(lockPrefix.length)));
+        }
+        catch (err) {
+            // Fallback: if listKeys fails, degrade to O(N) per-channel exists checks.
+            // This is expensive with many channels — log so persistent failures are observable.
+            console.warn('[channels] listKeys failed, falling back to per-channel exists checks', err);
+            const results = await Promise.all(ids.map((id) => this.kv.exists(this.lockKey(id))));
+            lockedSet = new Set(ids.filter((_, i) => results[i]));
+        }
+        const unlocked = ids.filter((id) => !lockedSet.has(id));
+        if (unlocked.length === 0)
+            return null;
+        // Sort by LRU ascending — oldest channel is always first (deterministic).
+        // Shuffle-then-stable-sort: tie-break among equal timestamps is random,
+        // spreading contention when multiple channels share the same LRU value.
+        shuffle(unlocked);
+        unlocked.sort((a, b) => (lruMap[a] ?? 0) - (lruMap[b] ?? 0));
+        const candidates = unlocked;
+        // --- CLAIM PHASE (per-channel lock) ---
+        for (const candidate of candidates) {
+            const result = await this.tryClaimChannel(candidate);
+            if (result)
+                return result;
         }
         return null;
     }
+    /** Attempt to claim a single channel under its per-channel lock */
+    async tryClaimChannel(relayerId) {
+        return this.kv.withLock(this.claimKey(relayerId), async () => {
+            // Double-check: another worker may have claimed it between our scan and this lock
+            if (await this.kv.exists(this.lockKey(relayerId)))
+                return null;
+            const token = randomToken();
+            await this.kv.set(this.lockKey(relayerId), { token, lockedAt: new Date().toISOString() }, { ttlSec: this.channelLockTtlSec });
+            await this.updateLruMap(relayerId);
+            return { relayerId, token };
+        }, { ttlSec: constants_1.POOL.CLAIM_LOCK_TTL_SECONDS, onBusy: 'skip' });
+    }
     /** Extend the lock TTL if we still own it (e.g. after WAIT_TIMEOUT) */
     async extendLock(lock, ttlSec) {
         try {
@@ -99,11 +128,45 @@ class ChannelPool {
             // ignore release errors
         }
     }
+    /** Release with cooldown: keeps lock alive with short TTL to hard-block the channel. */
+    async releaseWithCooldown(lock, cooldownMs = constants_1.POOL.CHANNEL_COOLDOWN_MS) {
+        try {
+            const key = this.lockKey(lock.relayerId);
+            const current = await this.kv.get(key);
+            if (current?.token === lock.token) {
+                const cooldownSec = Math.max(1, Math.ceil(cooldownMs / 1000));
+                await this.kv.set(key, current, { ttlSec: cooldownSec });
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
     membershipKey() {
         return `${this.network}:channel:relayer-ids`;
     }
+    lockKeyPrefix() {
+        return `${this.network}:channel:in-use:`;
+    }
     lockKey(relayerId) {
-        return `${this.network}:channel:in-use:${relayerId}`;
+        return `${this.lockKeyPrefix()}${relayerId}`;
+    }
+    claimKey(relayerId) {
+        return `${this.network}:channel:claim:${relayerId}`;
+    }
+    lruMapKey() {
+        return `${this.network}:channel:lru-map`;
+    }
+    async updateLruMap(relayerId) {
+        try {
+            const lruMap = (await this.kv.get(this.lruMapKey())) ?? {};
+            lruMap[relayerId] = Date.now();
+            await this.kv.set(this.lruMapKey(), lruMap, { ttlSec: constants_1.POOL.LRU_MAP_TTL_SECONDS });
+        }
+        catch (err) {
+            console.debug('[channels] failed to update LRU map', err);
+            // Best-effort: stale LRU map only affects ordering, not correctness
+        }
     }
     async getRelayerIdsFromKV() {
         try {
@@ -121,7 +184,7 @@ class ChannelPool {
     async getPoolCapacityDetails(options, maxSpins) {
         const isLimited = !!(options.contractId && options.limitedContracts.has(options.contractId));
         return {
-            reason: isLimited ? 'limited_contract_capacity' : 'all_channels_busy_or_mutex_contention',
+            reason: isLimited ? 'limited_contract_capacity' : 'all_channels_busy_or_claim_contention',
             contractId: options.contractId,
             capacityRatio: options.capacityRatio,
             maxSpins,

package/dist/plugin/submit.d.ts

@@ -5,6 +5,7 @@
  */
 import { Transaction } from '@stellar/stellar-sdk';
 import { Relayer, PluginAPI } from '@openzeppelin/relayer-sdk';
+import type { ChannelAccountsConfig } from './config';
 import { ChannelAccountsResponse } from './types';
 import { FeeTracker } from './fee-tracking';
 export interface SubmitContext {
@@ -25,7 +26,7 @@ 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, startTime: number, tracker?: FeeTracker, context?: SubmitContext, skipWait?: boolean): Promise<ChannelAccountsResponse>;
+export declare function submitWithFeeBumpAndWait(fundRelayer: Relayer, signedXdr: string, network: 'testnet' | 'mainnet', maxFee: number, api: PluginAPI, startTime: number, tracker?: FeeTracker, context?: SubmitContext, skipWait?: boolean, config?: Pick<ChannelAccountsConfig, 'globalTimeoutMs' | 'pollingTimeoutMs'>): Promise<ChannelAccountsResponse>;
 /** Try to decode a transaction result XDR from the reason string */
 export declare function decodeTransactionResult(reason: string): DecodedTransactionResult | null;
 export declare function buildStellarLabTransactionUrl(network: 'testnet' | 'mainnet', txHash: string): string;

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,EAAO,MAAM,sBAAsB,CAAC;AACxD,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,MAAM,WAAW,aAAa;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,UAAU,wBAAwB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;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,CAuBtB;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,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,UAAU,EACpB,OAAO,CAAC,EAAE,aAAa,EACvB,QAAQ,CAAC,EAAE,OAAO,GACjB,OAAO,CAAC,uBAAuB,CAAC,CAiHlC;AASD,oEAAoE;AACpE,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,wBAAwB,GAAG,IAAI,CAkCvF;AAeD,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAepG;AAED,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAOrD"}
+{"version":3,"file":"submit.d.ts","sourceRoot":"","sources":["../../src/plugin/submit.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAO,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAEL,OAAO,EAGP,SAAS,EACV,MAAM,2BAA2B,CAAC;AAEnC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE5C,MAAM,WAAW,aAAa;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,UAAU,wBAAwB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;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,CAuBtB;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,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,UAAU,EACpB,OAAO,CAAC,EAAE,aAAa,EACvB,QAAQ,CAAC,EAAE,OAAO,EAClB,MAAM,CAAC,EAAE,IAAI,CAAC,qBAAqB,EAAE,iBAAiB,GAAG,kBAAkB,CAAC,GAC3E,OAAO,CAAC,uBAAuB,CAAC,CAmHlC;AASD,oEAAoE;AACpE,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,wBAAwB,GAAG,IAAI,CAkCvF;AAeD,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAepG;AAED,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAOrD"}

package/dist/plugin/submit.js

@@ -42,7 +42,7 @@ async function signWithChannelAndFund(transaction, channelRelayer, _fundRelayer,
 /**
  * Submit transaction with fee bump and wait for confirmation
  */
-async function submitWithFeeBumpAndWait(fundRelayer, signedXdr, network, maxFee, api, startTime, tracker, context, skipWait) {
+async function submitWithFeeBumpAndWait(fundRelayer, signedXdr, network, maxFee, api, startTime, tracker, context, skipWait, config) {
     // Submit with fee bump
     console.debug(`[channels] Sending fee bump tx: network=${network}, maxFee=${maxFee}, xdr_len=${signedXdr.length}`);
     const payload = {
@@ -66,8 +66,10 @@ async function submitWithFeeBumpAndWait(fundRelayer, signedXdr, network, maxFee,
         };
     }
     // Compute dynamic timeout from remaining global budget
+    const globalTimeout = config?.globalTimeoutMs ?? constants_1.TIMEOUT.DEFAULT_GLOBAL_TIMEOUT_MS;
+    const pollingTimeout = config?.pollingTimeoutMs ?? constants_1.POLLING.DEFAULT_TIMEOUT_MS;
     const elapsedMs = Date.now() - startTime;
-    const remainingMs = constants_1.TIMEOUT.GLOBAL_TIMEOUT_MS - constants_1.TIMEOUT.BUFFER_MS - elapsedMs;
+    const remainingMs = globalTimeout - constants_1.TIMEOUT.BUFFER_MS - elapsedMs;
     if (remainingMs <= 0) {
         throw (0, relayer_sdk_1.pluginError)('No time remaining for transaction wait', {
             code: 'WAIT_TIMEOUT',
@@ -79,7 +81,7 @@ async function submitWithFeeBumpAndWait(fundRelayer, signedXdr, network, maxFee,
             },
         });
     }
-    const timeout = Math.min(remainingMs, constants_1.POLLING.TIMEOUT_MS);
+    const timeout = Math.min(remainingMs, pollingTimeout);
     console.debug(`[channels] Transaction wait: elapsed=${elapsedMs}ms, timeout=${timeout}ms`);
     // Wait for confirmation
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openzeppelin/relayer-plugin-channels",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "OpenZeppelin Relayer Plugin for Stellar Channel Accounts",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",