@openzeppelin/relayer-plugin-channels 0.2.0

package/dist/config.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * config.ts
+ *
+ * Environment-driven configuration for the channel accounts plugin.
+ */
+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");
+function requireEnv(name) {
+    const v = process.env[name];
+    if (!v || v.trim() === "") {
+        throw (0, relayer_sdk_1.pluginError)(`Missing required environment variable: ${name}`, {
+            code: "CONFIG_MISSING",
+            status: constants_1.HTTP_STATUS.INTERNAL_SERVER_ERROR,
+            details: { name },
+        });
+    }
+    return v.trim();
+}
+/**
+ * Load configuration from environment variables
+ */
+function loadConfig() {
+    const networkRaw = requireEnv("STELLAR_NETWORK").toLowerCase();
+    if (networkRaw !== "testnet" && networkRaw !== "mainnet") {
+        throw (0, relayer_sdk_1.pluginError)('STELLAR_NETWORK must be "testnet" or "mainnet"', {
+            code: "UNSUPPORTED_NETWORK",
+            status: constants_1.HTTP_STATUS.BAD_REQUEST,
+        });
+    }
+    const fundRelayerId = requireEnv("FUND_RELAYER_ID");
+    const rpcUrl = requireEnv("SOROBAN_RPC_URL");
+    return {
+        fundRelayerId,
+        network: networkRaw,
+        rpcUrl,
+    };
+}
+/**
+ * Get the network passphrase based on the configuration
+ */
+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/constants.d.ts

@@ -0,0 +1,46 @@
+/**
+ * constants.ts
+ *
+ * Centralized constants for the channel accounts plugin.
+ */
+export declare const HTTP_STATUS: {
+    readonly BAD_REQUEST: 400;
+    readonly UNAUTHORIZED: 401;
+    readonly FORBIDDEN: 403;
+    readonly CONFLICT: 409;
+    readonly INTERNAL_SERVER_ERROR: 500;
+    readonly BAD_GATEWAY: 502;
+    readonly SERVICE_UNAVAILABLE: 503;
+    readonly GATEWAY_TIMEOUT: 504;
+};
+export declare const CONFIG: {
+    readonly DEFAULT_LOCK_TTL_SECONDS: 30;
+    readonly MIN_LOCK_TTL_SECONDS: 10;
+    readonly MAX_LOCK_TTL_SECONDS: 30;
+    readonly DEFAULT_MAX_FEE: 1000000;
+};
+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;
+};
+export declare const TIME: {
+    readonly MAX_TIME_BOUND_OFFSET_SECONDS: 30;
+};
+export declare const SIMULATION: {
+    readonly DEFAULT_FEE: "100";
+    readonly MIN_TIME_BOUND: 0;
+    readonly MAX_TIME_BOUND_OFFSET_SECONDS: 30;
+    readonly MAX_FUTURE_TIME_BOUND_SECONDS: 30;
+};
+export declare const POLLING: {
+    readonly INTERVAL_MS: 1000;
+    readonly TIMEOUT_MS: 25000;
+};
+export declare const FEE: {
+    readonly MIN_BASE_FEE: 205;
+    readonly MAX_BASE_FEE: 605;
+    readonly RESOURCE_FEE_OFFSET: 60000;
+};
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/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"}

package/dist/constants.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * constants.ts
+ *
+ * Centralized constants for the channel accounts plugin.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FEE = exports.POLLING = exports.SIMULATION = exports.TIME = exports.POOL = exports.CONFIG = exports.HTTP_STATUS = void 0;
+// HTTP Status Codes
+exports.HTTP_STATUS = {
+    BAD_REQUEST: 400,
+    UNAUTHORIZED: 401,
+    FORBIDDEN: 403,
+    CONFLICT: 409,
+    INTERNAL_SERVER_ERROR: 500,
+    BAD_GATEWAY: 502,
+    SERVICE_UNAVAILABLE: 503,
+    GATEWAY_TIMEOUT: 504,
+};
+// Configuration Constants
+exports.CONFIG = {
+    DEFAULT_LOCK_TTL_SECONDS: 30,
+    MIN_LOCK_TTL_SECONDS: 10,
+    MAX_LOCK_TTL_SECONDS: 30,
+    DEFAULT_MAX_FEE: 1000000,
+};
+// 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,
+};
+// Time Constants
+exports.TIME = {
+    MAX_TIME_BOUND_OFFSET_SECONDS: 30,
+};
+// Simulation-related defaults
+exports.SIMULATION = {
+    DEFAULT_FEE: "100",
+    MIN_TIME_BOUND: 0,
+    MAX_TIME_BOUND_OFFSET_SECONDS: 30,
+    MAX_FUTURE_TIME_BOUND_SECONDS: 30,
+};
+// Polling for transactionWait
+exports.POLLING = {
+    INTERVAL_MS: 1000,
+    TIMEOUT_MS: 25000,
+};
+exports.FEE = {
+    MIN_BASE_FEE: 205,
+    MAX_BASE_FEE: 605,
+    RESOURCE_FEE_OFFSET: 60000,
+};

package/dist/fee.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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
+ */
+import { Transaction } from "@stellar/stellar-sdk";
+export declare function calculateMaxFee(transaction: Transaction): number;
+//# sourceMappingURL=fee.d.ts.map

package/dist/fee.d.ts.map

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

package/dist/fee.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * 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
+ */
+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;
+    if (envelope.switch() === stellar_sdk_1.xdr.EnvelopeType.envelopeTypeTx()) {
+        const sorobanData = envelope.v1().tx().ext().sorobanData();
+        if (sorobanData) {
+            resourceFee = sorobanData.resourceFee().toBigInt();
+        }
+    }
+    const baseInclusion = getRandomInt(constants_1.FEE.MIN_BASE_FEE, constants_1.FEE.MAX_BASE_FEE);
+    let dynamic = 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);
+}
+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/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * index.ts
+ *
+ * Main entry point for the channel accounts plugin.
+ * Orchestrates the transaction processing pipeline using channel accounts with fee bumping.
+ */
+import { PluginContext } from "@openzeppelin/relayer-sdk";
+export declare function handler(context: PluginContext): Promise<any>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * index.ts
+ *
+ * Main entry point for the channel accounts plugin.
+ * Orchestrates the transaction processing pipeline using channel accounts with fee bumping.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handler = handler;
+const relayer_sdk_1 = require("@openzeppelin/relayer-sdk");
+const pool_1 = require("./pool");
+const config_1 = require("./config");
+const validation_1 = require("./validation");
+const management_1 = require("./management");
+const submit_1 = require("./submit");
+const constants_1 = require("./constants");
+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 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);
+}
+async function handleFuncAuthSubmit(func, auth, api, pool, fundRelayer, fundAddress, network, networkPassphrase, rpc) {
+    let poolLock;
+    try {
+        poolLock = await pool.acquire();
+        const channelRelayer = api.useRelayer(poolLock.relayerId);
+        const channelInfo = await channelRelayer.getRelayer();
+        console.log(`[channels] Acquired channel: ${poolLock.relayerId}`);
+        if (!channelInfo || !channelInfo.address) {
+            throw (0, relayer_sdk_1.pluginError)("Channel relayer not found", {
+                code: "RELAYER_UNAVAILABLE",
+                status: constants_1.HTTP_STATUS.BAD_GATEWAY,
+                details: { relayerId: poolLock.relayerId },
+            });
+        }
+        const channelStatus = await channelRelayer.getRelayerStatus();
+        if (channelStatus.network_type !== "stellar") {
+            throw (0, relayer_sdk_1.pluginError)("Channel relayer network type must be stellar", {
+                code: "UNSUPPORTED_NETWORK",
+                status: constants_1.HTTP_STATUS.BAD_REQUEST,
+                details: {
+                    network_type: channelStatus.network_type,
+                    relayerId: poolLock.relayerId,
+                },
+            });
+        }
+        const built = await (0, simulation_1.simulateAndBuildWithChannel)(func, auth, { address: channelInfo.address, sequence: channelStatus.sequence_number }, fundAddress, rpc, 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);
+    }
+    finally {
+        if (poolLock) {
+            await pool.release(poolLock);
+        }
+    }
+}
+async function channelAccounts(context) {
+    const { api, kv, params } = 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 networkPassphrase = (0, config_1.getNetworkPassphrase)(config.network);
+    const rpc = new stellar_sdk_1.SorobanRpc.Server(config.rpcUrl);
+    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, rpc);
+    }
+    finally {
+        // Nothing to cleanup here; func-auth path releases locks internally
+    }
+}
+// Error-catching wrapper and main export
+async function handler(context) {
+    const result = await channelAccounts(context);
+    return result;
+}

package/dist/management.d.ts

@@ -0,0 +1,11 @@
+/**
+ * management.ts
+ *
+ * Payload-based management API for channel relayerIds.
+ * - listChannelAccounts: returns relayerIds from KV
+ * - setChannelAccounts: replaces relayerIds array in KV (checks lock conflicts)
+ */
+import type { PluginContext } from "@openzeppelin/relayer-sdk";
+export declare function isManagementRequest(params: any): boolean;
+export declare function handleManagement(context: PluginContext): Promise<any>;
+//# sourceMappingURL=management.d.ts.map

package/dist/management.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"management.d.ts","sourceRoot":"","sources":["../src/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"}

package/dist/management.js

@@ -0,0 +1,166 @@
+"use strict";
+/**
+ * management.ts
+ *
+ * Payload-based management API for channel relayerIds.
+ * - listChannelAccounts: returns relayerIds from KV
+ * - setChannelAccounts: replaces relayerIds array in KV (checks lock conflicts)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isManagementRequest = isManagementRequest;
+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;
+}
+function isManagementRequest(params) {
+    return Boolean(params &&
+        typeof params === "object" &&
+        params.management &&
+        typeof params.management === "object");
+}
+async function handleManagement(context) {
+    const { kv, params } = context;
+    const adminSecretEnv = (0, config_1.getAdminSecret)();
+    if (!adminSecretEnv) {
+        throw (0, relayer_sdk_1.pluginError)("Management API disabled", {
+            code: "MANAGEMENT_DISABLED",
+            status: constants_1.HTTP_STATUS.FORBIDDEN,
+        });
+    }
+    const m = params?.management || {};
+    const provided = (m.adminSecret ?? "").toString();
+    if (!provided || !timingSafeEqual(provided, adminSecretEnv)) {
+        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);
+        case "setChannelAccounts":
+            return await setChannelAccounts(kv, cfg.network, m);
+        default:
+            throw (0, relayer_sdk_1.pluginError)("Invalid management action", {
+                code: "INVALID_ACTION",
+                status: constants_1.HTTP_STATUS.BAD_REQUEST,
+            });
+    }
+}
+async function listChannelAccounts(kv, network) {
+    const key = `${network}:channel:relayer-ids`;
+    try {
+        const doc = await kv.get?.(key);
+        const relayerIds = Array.isArray(doc?.relayerIds)
+            ? doc.relayerIds.map(normalizeId)
+            : [];
+        return { relayerIds };
+    }
+    catch (e) {
+        throw (0, relayer_sdk_1.pluginError)("KV error while listing channel accounts", {
+            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)) {
+        throw (0, relayer_sdk_1.pluginError)("Invalid payload: relayerIds must be an array", {
+            code: "INVALID_PAYLOAD",
+            status: constants_1.HTTP_STATUS.BAD_REQUEST,
+        });
+    }
+    // Normalize, validate, unique
+    const relayerIds = unique(incoming.map(normalizeId).filter(validRelayerId));
+    // Read current
+    const listKey = `${network}:channel:relayer-ids`;
+    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);
+        }
+    }
+    if (locked.length > 0) {
+        throw (0, relayer_sdk_1.pluginError)("Locked relayer IDs cannot be removed", {
+            code: "LOCKED_CONFLICT",
+            status: constants_1.HTTP_STATUS.CONFLICT,
+            details: { locked },
+        });
+    }
+    // Write new list
+    try {
+        await kv.set(listKey, { relayerIds });
+        return { ok: true, appliedRelayerIds: relayerIds };
+    }
+    catch (e) {
+        throw (0, relayer_sdk_1.pluginError)("KV error while saving channel accounts", {
+            code: "KV_ERROR",
+            status: constants_1.HTTP_STATUS.INTERNAL_SERVER_ERROR,
+        });
+    }
+}
+function normalizeId(id) {
+    return String(id).trim().toLowerCase();
+}
+function validRelayerId(id) {
+    if (!id)
+        return false;
+    if (id.length > 128)
+        return false;
+    return /^[a-z0-9:_-]+$/.test(id);
+}
+function unique(arr) {
+    return Array.from(new Set(arr));
+}
+async function readStoredRelayerIds(kv, key) {
+    try {
+        const doc = await kv.get?.(key);
+        return Array.isArray(doc?.relayerIds)
+            ? doc.relayerIds.map(normalizeId)
+            : [];
+    }
+    catch (error) {
+        throw (0, relayer_sdk_1.pluginError)("KV error while reading channel accounts", {
+            code: "KV_ERROR",
+            status: constants_1.HTTP_STATUS.INTERNAL_SERVER_ERROR,
+            details: {
+                key,
+                message: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
+}
+async function isRelayerIdLocked(kv, network, id) {
+    const key = `${network}:channel:in-use:${id}`;
+    try {
+        return await kv.exists(key);
+    }
+    catch (error) {
+        throw (0, relayer_sdk_1.pluginError)("KV error while checking relayer lock", {
+            code: "KV_ERROR",
+            status: constants_1.HTTP_STATUS.INTERNAL_SERVER_ERROR,
+            details: {
+                relayerId: id,
+                key,
+                message: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
+}

package/dist/pool.d.ts

@@ -0,0 +1,31 @@
+/**
+ * pool.ts
+ *
+ * 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.
+ */
+import { PluginKVStore } from "@openzeppelin/relayer-sdk";
+export type PoolLock = {
+    relayerId: string;
+    token: string;
+};
+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);
+    /** Acquire a relayerId with a token lock */
+    acquire(): Promise<PoolLock>;
+    private withGlobalMutex;
+    private tryLockAnyRelayer;
+    /** Release the lock if we own it */
+    release(lock: PoolLock): Promise<void>;
+    private membershipKey;
+    private lockKey;
+    private getRelayerIdsFromKV;
+}
+//# sourceMappingURL=pool.d.ts.map

package/dist/pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../src/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"}