@openzeppelin/relayer-plugin-channels 0.19.0 → 0.21.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/fee.d.ts

@@ -20,5 +20,10 @@ export declare function getContractIdFromFunc(func: xdr.HostFunction): string |
  * Extract contract ID from a Transaction (for XDR flow)
  */
 export declare function getContractIdFromTransaction(transaction: Transaction): string | undefined;
+/**
+ * Compute the maximum fee (in stroops) for a transaction: the Soroban resource
+ * fee declared in the envelope's sorobanData (0 for classic transactions) plus
+ * the inclusion fee, which is higher when the invoked contract is rate-limited.
+ */
 export declare function calculateMaxFee(transaction: Transaction, limitedContracts: Set<string>, fees: InclusionFees): number;
 //# sourceMappingURL=fee.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"fee.d.ts","sourceRoot":"","sources":["../../src/plugin/fee.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,WAAW,EAAE,GAAG,EAAqB,MAAM,sBAAsB,CAAC;AAG3E,MAAM,WAAW,aAAa;IAC5B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,GAAG,CAAC,YAAY,GAAG,MAAM,GAAG,SAAS,CAUhF;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS,CAYzF;AASD,wBAAgB,eAAe,CAAC,WAAW,EAAE,WAAW,EAAE,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,aAAa,GAAG,MAAM,CAgCpH"}
+{"version":3,"file":"fee.d.ts","sourceRoot":"","sources":["../../src/plugin/fee.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,WAAW,EAAE,GAAG,EAAqB,MAAM,sBAAsB,CAAC;AAG3E,MAAM,WAAW,aAAa;IAC5B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,GAAG,CAAC,YAAY,GAAG,MAAM,GAAG,SAAS,CAahF;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS,CAYzF;AASD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,WAAW,EAAE,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,aAAa,GAAG,MAAM,CAgCpH"}

package/dist/plugin/fee.js

@@ -19,11 +19,14 @@ const constants_1 = require("./constants");
  */
 function getContractIdFromFunc(func) {
     try {
-        if (func.switch() !== stellar_sdk_1.xdr.HostFunctionType.hostFunctionTypeInvokeContract()) {
+        if (func.type !== 'hostFunctionTypeInvokeContract') {
             return undefined;
         }
-        const invokeContract = func.invokeContract();
-        return stellar_sdk_1.StrKey.encodeContract(invokeContract.contractAddress().contractId());
+        const contractAddress = func.invokeContract.contractAddress;
+        if (contractAddress.type !== 'scAddressTypeContract') {
+            return undefined;
+        }
+        return stellar_sdk_1.StrKey.encodeContract(contractAddress.contractId.toBytes());
     }
     catch {
         return undefined;
@@ -52,13 +55,18 @@ function getInclusionFee(contractId, limitedContracts, fees) {
     }
     return fees.inclusionFeeDefault;
 }
+/**
+ * Compute the maximum fee (in stroops) for a transaction: the Soroban resource
+ * fee declared in the envelope's sorobanData (0 for classic transactions) plus
+ * the inclusion fee, which is higher when the invoked contract is rate-limited.
+ */
 function calculateMaxFee(transaction, limitedContracts, fees) {
     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();
+    if (envelope.type === 'envelopeTypeTx') {
+        const ext = envelope.v1.tx.ext;
+        if (ext.type === 'sorobanData') {
+            resourceFee = ext.sorobanData.resourceFee;
         }
     }
     const contractId = getContractIdFromTransaction(transaction);

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,CAqB1E;AA6UD;;GAEG;AACH,wBAAsB,OAAO,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,CAElE"}