@openzeppelin/relayer-plugin-channels 0.19.0 → 0.20.0

package/README.md

@@ -16,7 +16,12 @@ A plugin for OpenZeppelin Relayer that enables parallel transaction submission o
 - [Development](#development)
 - [Overview](#overview)
 - [Architecture](#architecture)
-- [x402 Fund Relayer](#x402-fund-relayer)
+- [Alternative Fund Relayers](#alternative-fund-relayers)
+- [Per-Fund-Relayer Configuration](#per-fund-relayer-configuration)
+  - [Dynamic Inclusion Fees](#dynamic-inclusion-fees)
+  - [Timeout Overrides](#timeout-overrides)
+  - [Transaction Parameter Overrides](#transaction-parameter-overrides)
+  - [Configuration Precedence](#configuration-precedence)
 - [Contract Capacity Limits](#contract-capacity-limits)
 - [Management API](#management-api)
   - [List Channel Accounts](#list-channel-accounts)
@@ -224,7 +229,7 @@ export PLUGIN_ADMIN_SECRET="your-secret-here"  # Required for management API
 # Optional environment variables
 # Comma-separated list of allowed alternative fund relayers (e.g., for x402 or similar flows)
 export ALLOWED_FUND_RELAYER_IDS="x402-channels-fund"
-export LOCK_TTL_SECONDS=10              # default: 30, min: 3, max: 30
+export LOCK_TTL_SECONDS=10              # default: 30, min: 3, max: 60
 
 # Fee tracking (optional)
 export FEE_LIMIT=1000000                  # Default max fee per API key in stroops (disabled if not set)
@@ -244,6 +249,13 @@ export SEQUENCE_NUMBER_CACHE_MAX_AGE_MS=120000  # Max age of cached sequence num
 
 # Auth expiry validation (optional)
 export MIN_SIGNATURE_EXPIRATION_LEDGER_BUFFER=2  # Minimum ledger margin for auth entry signatureExpirationLedger (default: 2)
+
+# Transaction timebounds (optional)
+export MAX_TIME_BOUND_OFFSET_SECONDS=60  # Max future offset for tx maxTime in seconds (default: 60)
+
+# Request timeouts (optional)
+export PLUGIN_GLOBAL_TIMEOUT_MS=30000    # Overall request timeout in ms (default: 30000)
+export PLUGIN_POLLING_TIMEOUT_MS=25000   # Transaction polling timeout in ms (default: 25000)
 ```
 
 Your Relayer should now contain:
@@ -376,6 +388,93 @@ curl -X POST http://localhost:8080/api/v1/plugins/channels/call \
 - `fundRelayerId` must be a non-empty string
 - `getTransaction` requests can also include `fundRelayerId`; polling should use the same relayer selection as submission
 
+## Per-Fund-Relayer Configuration
+
+Individual fund relayers can have custom settings for fees, timeouts, and transaction parameters. This is configured via the plugin's `config` field in the relayer's `config.json`, not via environment variables.
+
+Environment variables define **global defaults**. Per-fund-relayer settings **override** them for requests that use that fund relayer. Requests using fund relayers without overrides (or the default fund relayer) use the global env-var defaults unchanged.
+
+### Setup
+
+Add a `config` block to the plugin definition in your relayer's `config.json`:
+
+```json
+{
+  "plugins": [
+    {
+      "id": "channels",
+      "path": "channels/index.ts",
+      "config": {
+        "fundRelayers": {
+          "x402-fund": {
+            "dynamicFee": {
+              "enabled": true,
+              "percentile": "p50",
+              "cacheTtlMs": 10000
+            },
+            "timeouts": {
+              "globalTimeoutMs": 45000,
+              "pollingTimeoutMs": 40000
+            },
+            "transactionParams": {
+              "maxTimeBoundOffsetSeconds": 120,
+              "minSignatureExpirationLedgerBuffer": 5
+            }
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+All sections (`dynamicFee`, `timeouts`, `transactionParams`) are optional. You can configure any combination.
+
+### Dynamic Inclusion Fees
+
+When enabled, the plugin fetches real-time fee data from Soroban RPC `getFeeStats` and uses a percentile of `sorobanInclusionFee` as the inclusion fee, instead of the static 201/203 stroops.
+
+| Field        | Type    | Default | Description                                                                                                 |
+| ------------ | ------- | ------- | ----------------------------------------------------------------------------------------------------------- |
+| `enabled`    | boolean | —       | Must be `true` to activate dynamic fees                                                                     |
+| `percentile` | string  | `"p50"` | Which percentile to use. Valid: `p10`, `p20`, `p30`, `p40`, `p50`, `p60`, `p70`, `p80`, `p90`, `p95`, `p99` |
+| `cacheTtlMs` | number  | `10000` | How long to cache the fee stats result (ms). Shared across all workers via KV store                         |
+
+When dynamic fees are active, the same fee is used for both limited and non-limited contracts (the limited/non-limited distinction is static tuning that dynamic fees replace).
+
+On any RPC or cache failure, the plugin falls back to the global static fees (`INCLUSION_FEE_DEFAULT` / `INCLUSION_FEE_LIMITED`), preserving the limited/non-limited split.
+
+### Timeout Overrides
+
+Override request timeouts for specific fund relayers. Useful when certain traffic sources (e.g., x402) need longer processing windows.
+
+| Field              | Type   | Default                                 | Description                                    |
+| ------------------ | ------ | --------------------------------------- | ---------------------------------------------- |
+| `globalTimeoutMs`  | number | env `PLUGIN_GLOBAL_TIMEOUT_MS` (30000)  | Overall request timeout in ms                  |
+| `pollingTimeoutMs` | number | env `PLUGIN_POLLING_TIMEOUT_MS` (25000) | Transaction confirmation polling timeout in ms |
+
+### Transaction Parameter Overrides
+
+Override transaction construction and validation parameters per fund relayer.
+
+| Field                                | Type   | Default                                          | Description                                                                             |
+| ------------------------------------ | ------ | ------------------------------------------------ | --------------------------------------------------------------------------------------- |
+| `maxTimeBoundOffsetSeconds`          | number | env `MAX_TIME_BOUND_OFFSET_SECONDS` (60)         | Max future offset for tx `maxTime`. Also controls validation of incoming XDR timebounds |
+| `minSignatureExpirationLedgerBuffer` | number | env `MIN_SIGNATURE_EXPIRATION_LEDGER_BUFFER` (2) | Minimum ledger margin required for auth entry `signatureExpirationLedger`               |
+
+### Configuration Precedence
+
+Settings are resolved per request in this order (first match wins):
+
+1. **Per-fund-relayer override** — from `config.fundRelayers[fundRelayerId]` in `config.json`
+2. **Global env var** — from the corresponding environment variable
+3. **Built-in default** — hardcoded constant in the plugin
+
+Example: a request with `fundRelayerId: "x402-fund"` where the plugin config has `timeouts.globalTimeoutMs: 45000` and the env var `PLUGIN_GLOBAL_TIMEOUT_MS=30000`:
+
+- The x402-fund request uses 45000ms
+- All other requests use 30000ms (env var default)
+
 ## Contract Capacity Limits
 
 High-volume contracts can monopolize the channel pool, starving other traffic. Contract capacity limits allow you to reserve a portion of the pool for non-limited contracts.

package/dist/plugin/config.d.ts

@@ -19,6 +19,7 @@ export interface ChannelAccountsConfig {
     inclusionFeeLimited: number;
     sequenceNumberCacheMaxAgeMs: number;
     minSignatureExpirationLedgerBuffer: number;
+    maxTimeBoundOffsetSeconds: number;
     globalTimeoutMs: number;
     pollingTimeoutMs: number;
 }

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;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"}
+{"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,yBAAyB,EAAE,MAAM,CAAC;IAClC,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AA2ID;;GAEG;AACH,wBAAgB,UAAU,IAAI,qBAAqB,CA8BlD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,CAE3E"}

package/dist/plugin/config.js

@@ -11,8 +11,8 @@ const stellar_sdk_1 = require("@stellar/stellar-sdk");
 const relayer_sdk_1 = require("@openzeppelin/relayer-sdk");
 const constants_1 = require("./constants");
 // Default inclusion fees (matching launchtube)
-const DEFAULT_INCLUSION_FEE_DEFAULT = Number(stellar_sdk_1.BASE_FEE) * 2 + 3; // 203
-const DEFAULT_INCLUSION_FEE_LIMITED = Number(stellar_sdk_1.BASE_FEE) * 2 + 1; // 201
+const DEFAULT_INCLUSION_FEE_DEFAULT = Number(stellar_sdk_1.BASE_FEE) * 2 + constants_1.DYNAMIC_FEE.FEE_BUMP_MARGIN_DEFAULT; // 203
+const DEFAULT_INCLUSION_FEE_LIMITED = Number(stellar_sdk_1.BASE_FEE) * 2 + constants_1.DYNAMIC_FEE.FEE_BUMP_MARGIN_LIMITED; // 201
 function requireEnv(name) {
     const v = process.env[name];
     if (!v || v.trim() === '') {
@@ -131,6 +131,13 @@ function parsePollingTimeoutMs() {
     const n = Number(raw);
     return Number.isFinite(n) && n > 0 ? Math.floor(n) : constants_1.POLLING.DEFAULT_TIMEOUT_MS;
 }
+function parseMaxTimeBoundOffsetSeconds() {
+    const raw = process.env.MAX_TIME_BOUND_OFFSET_SECONDS;
+    if (!raw)
+        return constants_1.TIME.MAX_TIME_BOUND_OFFSET_SECONDS;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : constants_1.TIME.MAX_TIME_BOUND_OFFSET_SECONDS;
+}
 function parseContractCapacityRatio() {
     const raw = process.env.CONTRACT_CAPACITY_RATIO;
     if (!raw)
@@ -168,6 +175,7 @@ function loadConfig() {
         inclusionFeeLimited: parseInclusionFee('INCLUSION_FEE_LIMITED', DEFAULT_INCLUSION_FEE_LIMITED),
         sequenceNumberCacheMaxAgeMs: parseSequenceNumberCacheMaxAge(),
         minSignatureExpirationLedgerBuffer: parseMinAuthExpiryLedgerBuffer(),
+        maxTimeBoundOffsetSeconds: parseMaxTimeBoundOffsetSeconds(),
         globalTimeoutMs: parseGlobalTimeoutMs(),
         pollingTimeoutMs: parsePollingTimeoutMs(),
     };

package/dist/plugin/constants.d.ts

@@ -17,7 +17,7 @@ export declare const HTTP_STATUS: {
 export declare const CONFIG: {
     readonly DEFAULT_LOCK_TTL_SECONDS: 30;
     readonly MIN_LOCK_TTL_SECONDS: 3;
-    readonly MAX_LOCK_TTL_SECONDS: 30;
+    readonly MAX_LOCK_TTL_SECONDS: 60;
     readonly DEFAULT_CONTRACT_CAPACITY_RATIO: 0.8;
     readonly DEFAULT_SEQUENCE_NUMBER_CACHE_MAX_AGE_MS: 120000;
     readonly DEFAULT_MIN_SIGNATURE_EXPIRATION_LEDGER_BUFFER: 2;
@@ -33,13 +33,11 @@ export declare const POOL: {
 };
 export declare const RELAYER_INFO_CACHE_TTL_SECONDS = 1800;
 export declare const TIME: {
+    readonly MIN_TIME_BOUND: 0;
     readonly MAX_TIME_BOUND_OFFSET_SECONDS: 60;
 };
 export declare const SIMULATION: {
     readonly DEFAULT_FEE: "100";
-    readonly MIN_TIME_BOUND: 0;
-    readonly MAX_TIME_BOUND_OFFSET_SECONDS: 60;
-    readonly MAX_FUTURE_TIME_BOUND_SECONDS: 60;
     readonly SIMULATION_AUTH_MODE: "enforce";
     /** Minimum ledger margin required between latestLedger and auth signatureExpirationLedger. Must be > 1 since simulation already validates 1 ledger of validity. ~10s at ~5s/ledger. */
     readonly MIN_SIGNATURE_EXPIRATION_LEDGER_BUFFER: 2;
@@ -55,4 +53,11 @@ export declare const POLLING: {
 export declare const FEE: {
     readonly NON_SOROBAN_FEE: 100000;
 };
+export declare const DYNAMIC_FEE: {
+    readonly DEFAULT_PERCENTILE: "p50";
+    readonly DEFAULT_CACHE_TTL_MS: 10000;
+    readonly VALID_PERCENTILES: readonly ["p10", "p20", "p30", "p40", "p50", "p60", "p70", "p80", "p90", "p95", "p99"];
+    readonly FEE_BUMP_MARGIN_DEFAULT: 3;
+    readonly FEE_BUMP_MARGIN_LIMITED: 1;
+};
 //# 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;;;;;;;;;;CAUd,CAAC;AAGX,eAAO,MAAM,MAAM;;;;;;;CAOT,CAAC;AAGX,eAAO,MAAM,IAAI;;;;;;;;CAcP,CAAC;AAGX,eAAO,MAAM,8BAA8B,OAAQ,CAAC;AAGpD,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;;;;;;;;CAcP,CAAC;AAGX,eAAO,MAAM,8BAA8B,OAAQ,CAAC;AAGpD,eAAO,MAAM,IAAI;;;CAGP,CAAC;AAGX,eAAO,MAAM,UAAU;;;IAGrB,uLAAuL;;CAE/K,CAAC;AAGX,eAAO,MAAM,OAAO;;;CAGV,CAAC;AAGX,eAAO,MAAM,OAAO;;;CAGV,CAAC;AAEX,eAAO,MAAM,GAAG;;CAGN,CAAC;AAGX,eAAO,MAAM,WAAW;;;;;;CAQd,CAAC"}

package/dist/plugin/constants.js

@@ -5,7 +5,7 @@
  * Centralized constants for the channel accounts plugin.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FEE = exports.POLLING = exports.TIMEOUT = exports.SIMULATION = exports.TIME = exports.RELAYER_INFO_CACHE_TTL_SECONDS = exports.POOL = exports.CONFIG = exports.HTTP_STATUS = void 0;
+exports.DYNAMIC_FEE = exports.FEE = exports.POLLING = exports.TIMEOUT = exports.SIMULATION = exports.TIME = exports.RELAYER_INFO_CACHE_TTL_SECONDS = exports.POOL = exports.CONFIG = exports.HTTP_STATUS = void 0;
 // HTTP Status Codes
 exports.HTTP_STATUS = {
     BAD_REQUEST: 400,
@@ -22,7 +22,7 @@ exports.HTTP_STATUS = {
 exports.CONFIG = {
     DEFAULT_LOCK_TTL_SECONDS: 30,
     MIN_LOCK_TTL_SECONDS: 3,
-    MAX_LOCK_TTL_SECONDS: 30,
+    MAX_LOCK_TTL_SECONDS: 60,
     DEFAULT_CONTRACT_CAPACITY_RATIO: 0.8,
     DEFAULT_SEQUENCE_NUMBER_CACHE_MAX_AGE_MS: 120000,
     DEFAULT_MIN_SIGNATURE_EXPIRATION_LEDGER_BUFFER: 2,
@@ -45,16 +45,14 @@ exports.POOL = {
 };
 // Relayer info cache — address and network_type are effectively immutable
 exports.RELAYER_INFO_CACHE_TTL_SECONDS = 1800; // 30 minutes
-// Time Constants
+// Time constants — used for both simulation tx construction and incoming tx validation
 exports.TIME = {
+    MIN_TIME_BOUND: 0,
     MAX_TIME_BOUND_OFFSET_SECONDS: 60,
 };
 // Simulation-related defaults
 exports.SIMULATION = {
     DEFAULT_FEE: '100',
-    MIN_TIME_BOUND: 0,
-    MAX_TIME_BOUND_OFFSET_SECONDS: 60,
-    MAX_FUTURE_TIME_BOUND_SECONDS: 60,
     SIMULATION_AUTH_MODE: 'enforce',
     /** Minimum ledger margin required between latestLedger and auth signatureExpirationLedger. Must be > 1 since simulation already validates 1 ledger of validity. ~10s at ~5s/ledger. */
     MIN_SIGNATURE_EXPIRATION_LEDGER_BUFFER: 2,
@@ -73,3 +71,13 @@ exports.FEE = {
     // For non-Soroban txs: 100,000 stroops (0.01 XLM) per Stellar best practice
     NON_SOROBAN_FEE: 100000,
 };
+// Dynamic fee estimation defaults
+exports.DYNAMIC_FEE = {
+    DEFAULT_PERCENTILE: 'p50',
+    DEFAULT_CACHE_TTL_MS: 10000,
+    VALID_PERCENTILES: ['p10', 'p20', 'p30', 'p40', 'p50', 'p60', 'p70', 'p80', 'p90', 'p95', 'p99'],
+    // Margins above the fee-bump minimum (BASE_FEE * 2) to avoid landing exactly
+    // at the protocol floor. Used by both static defaults and dynamic fee computation.
+    FEE_BUMP_MARGIN_DEFAULT: 3,
+    FEE_BUMP_MARGIN_LIMITED: 1,
+};

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

@@ -0,0 +1,17 @@
+/**
+ * fee-stats.ts
+ *
+ * Fetches dynamic inclusion fees from Soroban RPC `getFeeStats` with KV-backed
+ * caching so all worker processes share the same cached value.
+ * On any error, returns `null` so the caller can fall back to static fees.
+ */
+import type { PluginKVStore, Relayer } from '@openzeppelin/relayer-sdk';
+/**
+ * Fetch the dynamic inclusion fee for the given percentile from Soroban RPC.
+ *
+ * Returns a KV-cached value when fresh; otherwise calls `getFeeStats` via
+ * `relayer.rpc()` and stores the result in KV with a TTL.
+ * Returns `null` on any failure so the caller can apply its own fallback logic.
+ */
+export declare function fetchDynamicInclusionFee(relayer: Relayer, kv: PluginKVStore, network: string, percentile: string, cacheTtlMs: number): Promise<number | null>;
+//# sourceMappingURL=fee-stats.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fee-stats.d.ts","sourceRoot":"","sources":["../../src/plugin/fee-stats.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAWxE;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,OAAO,EAChB,EAAE,EAAE,aAAa,EACjB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAoDxB"}

package/dist/plugin/fee-stats.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * fee-stats.ts
+ *
+ * Fetches dynamic inclusion fees from Soroban RPC `getFeeStats` with KV-backed
+ * caching so all worker processes share the same cached value.
+ * On any error, returns `null` so the caller can fall back to static fees.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchDynamicInclusionFee = fetchDynamicInclusionFee;
+function cacheKey(network, percentile) {
+    return `${network}:fee-stats:${percentile}`;
+}
+/**
+ * Fetch the dynamic inclusion fee for the given percentile from Soroban RPC.
+ *
+ * Returns a KV-cached value when fresh; otherwise calls `getFeeStats` via
+ * `relayer.rpc()` and stores the result in KV with a TTL.
+ * Returns `null` on any failure so the caller can apply its own fallback logic.
+ */
+async function fetchDynamicInclusionFee(relayer, kv, network, percentile, cacheTtlMs) {
+    const key = cacheKey(network, percentile);
+    const cacheTtlSec = Math.max(1, Math.ceil(cacheTtlMs / 1000));
+    try {
+        const cached = await kv.get(key);
+        if (cached && Date.now() - cached.storedAt < cacheTtlMs) {
+            return cached.fee;
+        }
+    }
+    catch {
+        // KV read failure — proceed to RPC fetch
+    }
+    try {
+        const rpcResponse = await relayer.rpc({
+            jsonrpc: '2.0',
+            id: Math.floor(Math.random() * 1e8).toString(),
+            method: 'getFeeStats',
+            params: {},
+        });
+        if (rpcResponse.error) {
+            console.warn('[channels] getFeeStats RPC error, falling back to static fee');
+            return null;
+        }
+        const result = rpcResponse.result;
+        const feeStr = result?.sorobanInclusionFee?.[percentile];
+        if (!feeStr) {
+            console.warn(`[channels] getFeeStats missing ${percentile}, falling back to static fee`);
+            return null;
+        }
+        const fee = Number(feeStr);
+        if (!Number.isFinite(fee) || fee < 0) {
+            console.warn(`[channels] getFeeStats invalid value for ${percentile}: ${feeStr}`);
+            return null;
+        }
+        try {
+            await kv.set(key, { fee, storedAt: Date.now() }, { ttlSec: cacheTtlSec });
+        }
+        catch {
+            // KV write failure is non-fatal — the value was already computed
+        }
+        console.debug(`[channels] Dynamic inclusion fee: ${fee} stroops (${percentile})`);
+        return fee;
+    }
+    catch (err) {
+        console.warn(`[channels] getFeeStats failed: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}

package/dist/plugin/fund-relayer-config.d.ts

@@ -0,0 +1,64 @@
+/**
+ * fund-relayer-config.ts
+ *
+ * Parse and validate per-fund-relayer overrides from the plugin config
+ * (`context.config` in PluginContext, sourced from config.json `plugins[].config`).
+ *
+ * When no per-fund config is present, all behaviour falls back to the global
+ * env-var-based defaults in ChannelAccountsConfig.
+ */
+import type { PluginKVStore, Relayer } from '@openzeppelin/relayer-sdk';
+import type { ChannelAccountsConfig } from './config';
+import type { InclusionFees } from './fee';
+import { DYNAMIC_FEE } from './constants';
+export type FeePercentile = (typeof DYNAMIC_FEE.VALID_PERCENTILES)[number];
+export interface DynamicFeeConfig {
+    enabled: boolean;
+    percentile: FeePercentile;
+    cacheTtlMs: number;
+}
+export interface FundRelayerTimeouts {
+    globalTimeoutMs?: number;
+    pollingTimeoutMs?: number;
+}
+export interface FundRelayerTransactionParams {
+    maxTimeBoundOffsetSeconds?: number;
+    minSignatureExpirationLedgerBuffer?: number;
+}
+export interface FundRelayerOverrides {
+    dynamicFee?: DynamicFeeConfig;
+    timeouts?: FundRelayerTimeouts;
+    transactionParams?: FundRelayerTransactionParams;
+}
+/**
+ * Extract and validate per-fund-relayer overrides from plugin config.
+ * Returns `undefined` when no overrides exist for the given fund relayer,
+ * which signals the caller to use global env-var defaults.
+ */
+export declare function parseFundRelayerOverrides(pluginConfig: Record<string, any> | undefined, fundRelayerId: string): FundRelayerOverrides | undefined;
+/**
+ * Resolve the inclusion fees for this request.
+ *
+ * When the fund relayer has `dynamicFee.enabled`, a single dynamic fee is
+ * used for both limited and non-limited contracts (the limited/non-limited
+ * distinction is static tuning that dynamic fees replace).
+ *
+ * On any dynamic-fee error the global static defaults are returned.
+ */
+export declare function resolveInclusionFees(overrides: FundRelayerOverrides | undefined, globalConfig: ChannelAccountsConfig, relayer: Relayer, kv: PluginKVStore): Promise<InclusionFees>;
+/**
+ * Resolve effective transaction params (timebounds, auth expiry) by merging
+ * per-fund overrides with global defaults.
+ */
+export declare function resolveTransactionParams(overrides: FundRelayerOverrides | undefined, globalConfig: ChannelAccountsConfig): {
+    maxTimeBoundOffsetSeconds: number;
+    minSignatureExpirationLedgerBuffer: number;
+};
+/**
+ * Resolve effective timeouts by merging per-fund overrides with global defaults.
+ */
+export declare function resolveTimeouts(overrides: FundRelayerOverrides | undefined, globalConfig: ChannelAccountsConfig): {
+    globalTimeoutMs: number;
+    pollingTimeoutMs: number;
+};
+//# sourceMappingURL=fund-relayer-config.d.ts.map

package/dist/plugin/fund-relayer-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fund-relayer-config.d.ts","sourceRoot":"","sources":["../../src/plugin/fund-relayer-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAExE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAE3C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAM1C,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,WAAW,CAAC,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3E,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,aAAa,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,4BAA4B;IAC3C,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,kCAAkC,CAAC,EAAE,MAAM,CAAC;CAC7C;AAED,MAAM,WAAW,oBAAoB;IACnC,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B,iBAAiB,CAAC,EAAE,4BAA4B,CAAC;CAClD;AAuDD;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,EAC7C,aAAa,EAAE,MAAM,GACpB,oBAAoB,GAAG,SAAS,CAelC;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,oBAAoB,GAAG,SAAS,EAC3C,YAAY,EAAE,qBAAqB,EACnC,OAAO,EAAE,OAAO,EAChB,EAAE,EAAE,aAAa,GAChB,OAAO,CAAC,aAAa,CAAC,CAuBxB;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,oBAAoB,GAAG,SAAS,EAC3C,YAAY,EAAE,qBAAqB,GAClC;IAAE,yBAAyB,EAAE,MAAM,CAAC;IAAC,kCAAkC,EAAE,MAAM,CAAA;CAAE,CAQnF;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,oBAAoB,GAAG,SAAS,EAC3C,YAAY,EAAE,qBAAqB,GAClC;IAAE,eAAe,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAE,CAKvD"}

package/dist/plugin/fund-relayer-config.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * fund-relayer-config.ts
+ *
+ * Parse and validate per-fund-relayer overrides from the plugin config
+ * (`context.config` in PluginContext, sourced from config.json `plugins[].config`).
+ *
+ * When no per-fund config is present, all behaviour falls back to the global
+ * env-var-based defaults in ChannelAccountsConfig.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseFundRelayerOverrides = parseFundRelayerOverrides;
+exports.resolveInclusionFees = resolveInclusionFees;
+exports.resolveTransactionParams = resolveTransactionParams;
+exports.resolveTimeouts = resolveTimeouts;
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+const fee_stats_1 = require("./fee-stats");
+const constants_1 = require("./constants");
+// ---------------------------------------------------------------------------
+// Parsing helpers
+// ---------------------------------------------------------------------------
+const validPercentiles = new Set(constants_1.DYNAMIC_FEE.VALID_PERCENTILES);
+function isValidPercentile(v) {
+    return typeof v === 'string' && validPercentiles.has(v);
+}
+function parsePositiveNumber(v) {
+    if (typeof v !== 'number' || !Number.isFinite(v) || v <= 0)
+        return undefined;
+    return v;
+}
+function parseDynamicFee(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const obj = raw;
+    if (typeof obj.enabled !== 'boolean' || !obj.enabled)
+        return undefined;
+    const percentile = isValidPercentile(obj.percentile) ? obj.percentile : constants_1.DYNAMIC_FEE.DEFAULT_PERCENTILE;
+    const cacheTtlMs = parsePositiveNumber(obj.cacheTtlMs) ?? constants_1.DYNAMIC_FEE.DEFAULT_CACHE_TTL_MS;
+    return { enabled: true, percentile, cacheTtlMs };
+}
+function parseTransactionParams(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const obj = raw;
+    const maxTimeBoundOffsetSeconds = parsePositiveNumber(obj.maxTimeBoundOffsetSeconds);
+    const minSignatureExpirationLedgerBuffer = parsePositiveNumber(obj.minSignatureExpirationLedgerBuffer);
+    if (maxTimeBoundOffsetSeconds === undefined && minSignatureExpirationLedgerBuffer === undefined)
+        return undefined;
+    return { maxTimeBoundOffsetSeconds, minSignatureExpirationLedgerBuffer };
+}
+function parseTimeouts(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const obj = raw;
+    const globalTimeoutMs = parsePositiveNumber(obj.globalTimeoutMs);
+    const pollingTimeoutMs = parsePositiveNumber(obj.pollingTimeoutMs);
+    if (globalTimeoutMs === undefined && pollingTimeoutMs === undefined)
+        return undefined;
+    return { globalTimeoutMs, pollingTimeoutMs };
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Extract and validate per-fund-relayer overrides from plugin config.
+ * Returns `undefined` when no overrides exist for the given fund relayer,
+ * which signals the caller to use global env-var defaults.
+ */
+function parseFundRelayerOverrides(pluginConfig, fundRelayerId) {
+    if (!pluginConfig)
+        return undefined;
+    const fundRelayers = pluginConfig.fundRelayers;
+    if (!fundRelayers || typeof fundRelayers !== 'object')
+        return undefined;
+    const raw = fundRelayers[fundRelayerId];
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const dynamicFee = parseDynamicFee(raw.dynamicFee);
+    const timeouts = parseTimeouts(raw.timeouts);
+    const transactionParams = parseTransactionParams(raw.transactionParams);
+    if (!dynamicFee && !timeouts && !transactionParams)
+        return undefined;
+    return { dynamicFee, timeouts, transactionParams };
+}
+/**
+ * Resolve the inclusion fees for this request.
+ *
+ * When the fund relayer has `dynamicFee.enabled`, a single dynamic fee is
+ * used for both limited and non-limited contracts (the limited/non-limited
+ * distinction is static tuning that dynamic fees replace).
+ *
+ * On any dynamic-fee error the global static defaults are returned.
+ */
+async function resolveInclusionFees(overrides, globalConfig, relayer, kv) {
+    if (overrides?.dynamicFee?.enabled) {
+        const fee = await (0, fee_stats_1.fetchDynamicInclusionFee)(relayer, kv, globalConfig.network, overrides.dynamicFee.percentile, overrides.dynamicFee.cacheTtlMs);
+        if (fee !== null) {
+            // getFeeStats reports inner-tx inclusion fees. Fee-bump wrapping adds one
+            // extra virtual operation at BASE_FEE, plus a small margin to avoid
+            // landing exactly at the protocol minimum.
+            const feeBumpFee = fee + Number(stellar_sdk_1.BASE_FEE) + constants_1.DYNAMIC_FEE.FEE_BUMP_MARGIN_DEFAULT;
+            return { inclusionFeeDefault: feeBumpFee, inclusionFeeLimited: feeBumpFee };
+        }
+        // Dynamic fee fetch failed — fall through to static defaults
+    }
+    return {
+        inclusionFeeDefault: globalConfig.inclusionFeeDefault,
+        inclusionFeeLimited: globalConfig.inclusionFeeLimited,
+    };
+}
+/**
+ * Resolve effective transaction params (timebounds, auth expiry) by merging
+ * per-fund overrides with global defaults.
+ */
+function resolveTransactionParams(overrides, globalConfig) {
+    return {
+        maxTimeBoundOffsetSeconds: overrides?.transactionParams?.maxTimeBoundOffsetSeconds ?? globalConfig.maxTimeBoundOffsetSeconds,
+        minSignatureExpirationLedgerBuffer: overrides?.transactionParams?.minSignatureExpirationLedgerBuffer ??
+            globalConfig.minSignatureExpirationLedgerBuffer,
+    };
+}
+/**
+ * Resolve effective timeouts by merging per-fund overrides with global defaults.
+ */
+function resolveTimeouts(overrides, globalConfig) {
+    return {
+        globalTimeoutMs: overrides?.timeouts?.globalTimeoutMs ?? globalConfig.globalTimeoutMs,
+        pollingTimeoutMs: overrides?.timeouts?.pollingTimeoutMs ?? globalConfig.pollingTimeoutMs,
+    };
+}

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;AACvE,OAAO,KAAK,EAA4B,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAQnF,OAAO,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAC;AAOxD,8EAA8E;AAC9E,KAAK,iBAAiB,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC;AAUnE,kDAAkD;AAClD,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAanC;AAsBD;;;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"}
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/plugin/handler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAe,MAAM,2BAA2B,CAAC;AACvE,OAAO,KAAK,EAA4B,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAQnF,OAAO,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAC;AAaxD,8EAA8E;AAC9E,KAAK,iBAAiB,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC;AAUnE,kDAAkD;AAClD,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAanC;AAiCD;;;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;AA6UD;;GAEG;AACH,wBAAsB,OAAO,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,CAElE"}

package/dist/plugin/handler.js

@@ -20,6 +20,7 @@ const constants_1 = require("./constants");
 const stellar_sdk_1 = require("@stellar/stellar-sdk");
 const simulation_1 = require("./simulation");
 const fee_1 = require("./fee");
+const fund_relayer_config_1 = require("./fund-relayer-config");
 const tx_1 = require("./tx");
 const fee_tracking_1 = require("./fee-tracking");
 const sequence_1 = require("./sequence");
@@ -56,6 +57,16 @@ function getApiKey(headers, headerName) {
     const values = headers[headerName];
     return values?.[0]?.trim() || undefined;
 }
+/**
+ * Compute how long a channel lock should be extended based on remaining tx validity.
+ * The tx maxTime was set to ~(txBuildTime + maxTimeBoundOffsetSeconds) at build time.
+ * We add one ledger cooldown as margin for the tx to finalize after expiry.
+ */
+function computeExtendTtlSec(txBuildTime, maxTimeBoundOffsetSeconds) {
+    const txExpiryMs = txBuildTime + maxTimeBoundOffsetSeconds * 1000;
+    const remainingMs = txExpiryMs - Date.now() + constants_1.POOL.CHANNEL_COOLDOWN_MS;
+    return Math.max(1, Math.ceil(remainingMs / 1000));
+}
 /**
  * Extracts func and auth from an unsigned Soroban transaction.
  * Returns null if the transaction is not a single invokeHostFunction operation.
@@ -97,7 +108,7 @@ async function handleXdrSubmit(xdrStr, ctx, skipWait) {
         const updatedOptions = { ...ctx.acquireOptions, contractId };
         return handleFuncAuthSubmit(extracted.func, extracted.auth, { ...ctx, acquireOptions: updatedOptions }, skipWait);
     }
-    const validated = (0, tx_1.validateExistingTransactionForSubmitOnly)(tx);
+    const validated = (0, tx_1.validateExistingTransactionForSubmitOnly)(tx, ctx.config);
     const maxFee = (0, fee_1.calculateMaxFee)(validated, ctx.acquireOptions.limitedContracts, ctx.fees);
     const contractId = (0, fee_1.getContractIdFromTransaction)(validated);
     await ctx.tracker?.checkBudget(maxFee);
@@ -109,7 +120,7 @@ async function handleXdrSubmit(xdrStr, ctx, skipWait) {
 }
 async function handleFuncAuthSubmit(func, auth, ctx, skipWait) {
     // Simulate once — used for both read-only detection and transaction assembly
-    const simulation = await (0, simulation_1.simulateTransaction)(func, auth, ctx.fundAddress, ctx.fundRelayer, ctx.networkPassphrase);
+    const simulation = await (0, simulation_1.simulateTransaction)(func, auth, ctx.fundAddress, ctx.fundRelayer, ctx.networkPassphrase, ctx.config.maxTimeBoundOffsetSeconds);
     if (simulation.isReadOnly) {
         console.log(`[channels] Read-only call detected, returning simulation result`);
         return {
@@ -143,7 +154,8 @@ async function handleFuncAuthSubmit(func, auth, ctx, skipWait) {
         }
         const sequence = await (0, sequence_1.getSequence)(ctx.kv, ctx.network, channelRelayer, channelInfo.address, ctx.config.sequenceNumberCacheMaxAgeMs);
         // Assemble the transaction using the cached simulation result — no second RPC call
-        const built = (0, simulation_1.buildWithChannel)(func, auth, { address: channelInfo.address, sequence }, ctx.networkPassphrase, simulation.rawSimResult, ctx.config.minSignatureExpirationLedgerBuffer);
+        const txBuildTime = Date.now();
+        const built = (0, simulation_1.buildWithChannel)(func, auth, { address: channelInfo.address, sequence }, ctx.networkPassphrase, simulation.rawSimResult, ctx.config.minSignatureExpirationLedgerBuffer, ctx.config.maxTimeBoundOffsetSeconds);
         console.debug(`[channels] After assembly: built.fee=${built.fee}, minResourceFee=${simulation.rawSimResult.minResourceFee}`);
         const signedTx = await (0, submit_1.signWithChannelAndFund)(built, channelRelayer, ctx.fundRelayer, channelInfo.address, ctx.fundAddress, ctx.networkPassphrase);
         const maxFee = (0, fee_1.calculateMaxFee)(signedTx, ctx.acquireOptions.limitedContracts, ctx.fees);
@@ -157,8 +169,9 @@ async function handleFuncAuthSubmit(func, auth, ctx, skipWait) {
         try {
             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') {
-                console.log(`[channels]: extending lock and clearing sequence`);
-                await ctx.pool.extendLock(poolLock);
+                const extendSec = computeExtendTtlSec(txBuildTime, ctx.config.maxTimeBoundOffsetSeconds);
+                console.log(`[channels]: extending lock (${extendSec}s) and clearing sequence`);
+                await ctx.pool.extendLock(poolLock, extendSec);
                 await (0, sequence_1.clearSequence)(ctx.kv, ctx.network, channelInfo.address);
                 poolLock = undefined; // skip release in finally
             }
@@ -175,8 +188,9 @@ async function handleFuncAuthSubmit(func, auth, ctx, skipWait) {
         catch (error) {
             await (0, sequence_1.clearSequence)(ctx.kv, ctx.network, channelInfo.address);
             if (error.code === 'WAIT_TIMEOUT' && poolLock) {
-                console.log(`[channels] Extending lock for WAIT_TIMEOUT error`);
-                await ctx.pool.extendLock(poolLock);
+                const extendSec = computeExtendTtlSec(txBuildTime, ctx.config.maxTimeBoundOffsetSeconds);
+                console.log(`[channels] Extending lock for WAIT_TIMEOUT (${extendSec}s)`);
+                await ctx.pool.extendLock(poolLock, extendSec);
                 poolLock = undefined; // skip release in finally
             }
             else if (error.code === 'ONCHAIN_FAILED') {
@@ -200,7 +214,7 @@ async function handleFuncAuthSubmit(func, auth, ctx, skipWait) {
 }
 async function channelAccounts(context) {
     const startTime = Date.now();
-    const { api, kv, params, headers } = context;
+    const { api, kv, params, headers, config: pluginConfig } = context;
     // Management branch: handle and return immediately
     if ((0, management_1.isManagementRequest)(params)) {
         return await (0, management_1.handleManagement)(context);
@@ -255,7 +269,12 @@ async function channelAccounts(context) {
             hash: stellar.hash ?? null,
         };
     }
-    const fundInfo = await getCachedRelayerInfo(config.network, fundRelayerId, fundRelayer);
+    // 3. Resolve per-fund-relayer overrides and fetch fund relayer info in parallel
+    const fundOverrides = (0, fund_relayer_config_1.parseFundRelayerOverrides)(pluginConfig, fundRelayerId);
+    const [fundInfo, fees] = await Promise.all([
+        getCachedRelayerInfo(config.network, fundRelayerId, fundRelayer),
+        (0, fund_relayer_config_1.resolveInclusionFees)(fundOverrides, config, fundRelayer, kv),
+    ]);
     if (!fundInfo || !fundInfo.address) {
         throw (0, relayer_sdk_1.pluginError)('Fund relayer not found', {
             code: 'RELAYER_UNAVAILABLE',
@@ -270,16 +289,21 @@ async function channelAccounts(context) {
             details: { network_type: fundInfo.network_type, relayerId: fundRelayerId },
         });
     }
-    // 3. Build acquire options for contract capacity limits
+    // 4. Build acquire options and resolve remaining overrides
     const acquireOptions = {
         limitedContracts: config.limitedContracts,
         capacityRatio: config.contractCapacityRatio,
     };
-    const fees = {
-        inclusionFeeDefault: config.inclusionFeeDefault,
-        inclusionFeeLimited: config.inclusionFeeLimited,
+    const timeouts = (0, fund_relayer_config_1.resolveTimeouts)(fundOverrides, config);
+    const txParams = (0, fund_relayer_config_1.resolveTransactionParams)(fundOverrides, config);
+    const effectiveConfig = {
+        ...config,
+        globalTimeoutMs: timeouts.globalTimeoutMs,
+        pollingTimeoutMs: timeouts.pollingTimeoutMs,
+        maxTimeBoundOffsetSeconds: txParams.maxTimeBoundOffsetSeconds,
+        minSignatureExpirationLedgerBuffer: txParams.minSignatureExpirationLedgerBuffer,
     };
-    // 4. Build pipeline context
+    // 5. Build pipeline context
     const ctx = {
         api,
         kv,
@@ -291,10 +315,10 @@ async function channelAccounts(context) {
         acquireOptions,
         fees,
         tracker,
-        config,
+        config: effectiveConfig,
         startTime,
     };
-    // 5. Branch by request type
+    // 6. Branch by request type
     if (request.type === 'xdr') {
         console.log(`[channels] Flow: XDR submit-only`);
         return await handleXdrSubmit(request.xdr, ctx, request.skipWait);

package/dist/plugin/simulation.d.ts

@@ -34,12 +34,12 @@ export interface SimulationResult {
  * 1. Zero auth entries — no one needs to authorize anything
  * 2. Zero read-write footprint entries — no ledger state will be modified
  */
-export declare function simulateTransaction(func: xdr.HostFunction, auth: xdr.SorobanAuthorizationEntry[] | undefined, sourceAddress: string, relayer: Relayer, networkPassphrase: string): Promise<SimulationResult>;
+export declare function simulateTransaction(func: xdr.HostFunction, auth: xdr.SorobanAuthorizationEntry[] | undefined, sourceAddress: string, relayer: Relayer, networkPassphrase: string, maxTimeBoundOffsetSeconds?: number): Promise<SimulationResult>;
 /**
  * Build and assemble a transaction using a channel account and an already-
  * obtained simulation result.  No additional network calls are made.
  */
-export declare function buildWithChannel(func: xdr.HostFunction, auth: xdr.SorobanAuthorizationEntry[] | undefined, channel: ChannelAccount, networkPassphrase: string, simResult: rpc.Api.RawSimulateTransactionResponse, minSignatureExpirationLedgerBuffer?: number): Transaction;
+export declare function buildWithChannel(func: xdr.HostFunction, auth: xdr.SorobanAuthorizationEntry[] | undefined, channel: ChannelAccount, networkPassphrase: string, simResult: rpc.Api.RawSimulateTransactionResponse, minSignatureExpirationLedgerBuffer?: number, maxTimeBoundOffsetSeconds?: number): Transaction;
 /** Extract human-readable message + error type from simulation error diagnostic events */
 export declare function parseSimulationError(error: string): string;
 //# sourceMappingURL=simulation.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"simulation.d.ts","sourceRoot":"","sources":["../../src/plugin/simulation.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAsB,GAAG,EAAE,WAAW,EAAsB,GAAG,EAAE,MAAM,sBAAsB,CAAC;AACrG,OAAO,EAAgD,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAGlG,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,UAAU,EAAE,OAAO,CAAC;IACpB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,YAAY,EAAE,GAAG,CAAC,GAAG,CAAC,8BAA8B,CAAC;CACtD;AAOD;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,GAAG,CAAC,YAAY,EACtB,IAAI,EAAE,GAAG,CAAC,yBAAyB,EAAE,GAAG,SAAS,EACjD,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,OAAO,EAChB,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC,gBAAgB,CAAC,CAiF3B;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,GAAG,CAAC,YAAY,EACtB,IAAI,EAAE,GAAG,CAAC,yBAAyB,EAAE,GAAG,SAAS,EACjD,OAAO,EAAE,cAAc,EACvB,iBAAiB,EAAE,MAAM,EACzB,SAAS,EAAE,GAAG,CAAC,GAAG,CAAC,8BAA8B,EACjD,kCAAkC,GAAE,MAA0D,GAC7F,WAAW,CA+Fb;AA4CD,0FAA0F;AAC1F,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAe1D"}
+{"version":3,"file":"simulation.d.ts","sourceRoot":"","sources":["../../src/plugin/simulation.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAsB,GAAG,EAAE,WAAW,EAAsB,GAAG,EAAE,MAAM,sBAAsB,CAAC;AACrG,OAAO,EAAgD,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAGlG,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,UAAU,EAAE,OAAO,CAAC;IACpB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,YAAY,EAAE,GAAG,CAAC,GAAG,CAAC,8BAA8B,CAAC;CACtD;AAOD;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,GAAG,CAAC,YAAY,EACtB,IAAI,EAAE,GAAG,CAAC,yBAAyB,EAAE,GAAG,SAAS,EACjD,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,OAAO,EAChB,iBAAiB,EAAE,MAAM,EACzB,yBAAyB,GAAE,MAA2C,GACrE,OAAO,CAAC,gBAAgB,CAAC,CAiF3B;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,GAAG,CAAC,YAAY,EACtB,IAAI,EAAE,GAAG,CAAC,yBAAyB,EAAE,GAAG,SAAS,EACjD,OAAO,EAAE,cAAc,EACvB,iBAAiB,EAAE,MAAM,EACzB,SAAS,EAAE,GAAG,CAAC,GAAG,CAAC,8BAA8B,EACjD,kCAAkC,GAAE,MAA0D,EAC9F,yBAAyB,GAAE,MAA2C,GACrE,WAAW,CA+Fb;AA4CD,0FAA0F;AAC1F,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAe1D"}

package/dist/plugin/simulation.js

@@ -26,12 +26,12 @@ const constants_1 = require("./constants");
  * 1. Zero auth entries — no one needs to authorize anything
  * 2. Zero read-write footprint entries — no ledger state will be modified
  */
-async function simulateTransaction(func, auth, sourceAddress, relayer, networkPassphrase) {
+async function simulateTransaction(func, auth, sourceAddress, relayer, networkPassphrase, maxTimeBoundOffsetSeconds = constants_1.TIME.MAX_TIME_BOUND_OFFSET_SECONDS) {
     const now = Math.floor(Date.now() / 1000);
     const transaction = new stellar_sdk_1.TransactionBuilder(new stellar_sdk_1.Account(sourceAddress, '0'), {
         fee: constants_1.SIMULATION.DEFAULT_FEE,
         networkPassphrase,
-        timebounds: { minTime: constants_1.SIMULATION.MIN_TIME_BOUND, maxTime: now + constants_1.SIMULATION.MAX_TIME_BOUND_OFFSET_SECONDS },
+        timebounds: { minTime: constants_1.TIME.MIN_TIME_BOUND, maxTime: now + maxTimeBoundOffsetSeconds },
     })
         .addOperation(stellar_sdk_1.Operation.invokeHostFunction({ func, auth }))
         .build();
@@ -104,7 +104,7 @@ async function simulateTransaction(func, auth, sourceAddress, relayer, networkPa
  * Build and assemble a transaction using a channel account and an already-
  * obtained simulation result.  No additional network calls are made.
  */
-function buildWithChannel(func, auth, channel, networkPassphrase, simResult, minSignatureExpirationLedgerBuffer = constants_1.SIMULATION.MIN_SIGNATURE_EXPIRATION_LEDGER_BUFFER) {
+function buildWithChannel(func, auth, channel, networkPassphrase, simResult, minSignatureExpirationLedgerBuffer = constants_1.SIMULATION.MIN_SIGNATURE_EXPIRATION_LEDGER_BUFFER, maxTimeBoundOffsetSeconds = constants_1.TIME.MAX_TIME_BOUND_OFFSET_SECONDS) {
     if (!simResult.transactionData) {
         throw (0, relayer_sdk_1.pluginError)('Simulation response missing transactionData', {
             code: 'SIMULATION_INVALID_RESPONSE',
@@ -168,7 +168,7 @@ function buildWithChannel(func, auth, channel, networkPassphrase, simResult, min
     const transaction = new stellar_sdk_1.TransactionBuilder(new stellar_sdk_1.Account(channel.address, channel.sequence), {
         fee: constants_1.SIMULATION.DEFAULT_FEE,
         networkPassphrase,
-        timebounds: { minTime: constants_1.SIMULATION.MIN_TIME_BOUND, maxTime: now + constants_1.SIMULATION.MAX_TIME_BOUND_OFFSET_SECONDS },
+        timebounds: { minTime: constants_1.TIME.MIN_TIME_BOUND, maxTime: now + maxTimeBoundOffsetSeconds },
         sorobanData,
     })
         .addOperation(stellar_sdk_1.Operation.invokeHostFunction({

package/dist/plugin/tx.d.ts

@@ -4,5 +4,6 @@
  * Transaction validation helpers for the XDR submit-only path.
  */
 import { Transaction } from '@stellar/stellar-sdk';
-export declare function validateExistingTransactionForSubmitOnly(tx: Transaction): Transaction;
+import type { ChannelAccountsConfig } from './config';
+export declare function validateExistingTransactionForSubmitOnly(tx: Transaction, config: Pick<ChannelAccountsConfig, 'maxTimeBoundOffsetSeconds'>): Transaction;
 //# sourceMappingURL=tx.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"tx.d.ts","sourceRoot":"","sources":["../../src/plugin/tx.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAO,MAAM,sBAAsB,CAAC;AAIxD,wBAAgB,wCAAwC,CAAC,EAAE,EAAE,WAAW,GAAG,WAAW,CAkDrF"}
+{"version":3,"file":"tx.d.ts","sourceRoot":"","sources":["../../src/plugin/tx.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAO,MAAM,sBAAsB,CAAC;AAExD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAGtD,wBAAgB,wCAAwC,CACtD,EAAE,EAAE,WAAW,EACf,MAAM,EAAE,IAAI,CAAC,qBAAqB,EAAE,2BAA2B,CAAC,GAC/D,WAAW,CAmDb"}

package/dist/plugin/tx.js

@@ -9,7 +9,8 @@ exports.validateExistingTransactionForSubmitOnly = validateExistingTransactionFo
 const stellar_sdk_1 = require("@stellar/stellar-sdk");
 const relayer_sdk_1 = require("@openzeppelin/relayer-sdk");
 const constants_1 = require("./constants");
-function validateExistingTransactionForSubmitOnly(tx) {
+function validateExistingTransactionForSubmitOnly(tx, config) {
+    const { maxTimeBoundOffsetSeconds } = config;
     const now = Math.floor(Date.now() / 1000);
     // Reject fee-bump envelopes
     const envelope = tx.toEnvelope();
@@ -42,8 +43,8 @@ function validateExistingTransactionForSubmitOnly(tx) {
                 details: { maxTime, now },
             });
         }
-        if (maxTime - now > constants_1.SIMULATION.MAX_FUTURE_TIME_BOUND_SECONDS) {
-            throw (0, relayer_sdk_1.pluginError)(`Transaction \`timeBounds.maxTime\` too far into the future. Must be no greater than ${constants_1.SIMULATION.MAX_FUTURE_TIME_BOUND_SECONDS} seconds`, {
+        if (maxTime - now > maxTimeBoundOffsetSeconds) {
+            throw (0, relayer_sdk_1.pluginError)(`Transaction \`timeBounds.maxTime\` too far into the future. Must be no greater than ${maxTimeBoundOffsetSeconds} seconds`, {
                 code: 'TIMEBOUNDS_TOO_FAR',
                 status: constants_1.HTTP_STATUS.BAD_REQUEST,
             });

package/package.json

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