@openzeppelin/relayer-plugin-channels 0.9.0 → 0.11.0

package/README.md

@@ -229,6 +229,10 @@ export API_KEY_HEADER="x-api-key"         # Header name to extract API key (defa
 # Contract capacity limits (optional)
 export LIMITED_CONTRACTS="CDL74RF5BLYR2YBLCCI7F5FB6TPSCLKEJUBSD2RSVWZ4YHF3VMFAIGWA"  # Comma-separated contract addresses
 export CONTRACT_CAPACITY_RATIO=0.8        # Max ratio of pool for limited contracts (default: 0.8 = 80%)
+
+# Inclusion fee overrides (optional)
+export INCLUSION_FEE_DEFAULT=203           # Inclusion fee in stroops for regular contracts (default: BASE_FEE * 2 + 3 = 203)
+export INCLUSION_FEE_LIMITED=201           # Inclusion fee in stroops for limited contracts (default: BASE_FEE * 2 + 1 = 201)
 ```
 
 Your Relayer should now contain:
@@ -510,6 +514,49 @@ curl -X POST http://localhost:8080/api/v1/plugins/channels/call \
 }
 ```
 
+### Get Pool Stats
+
+Returns pool health metrics, configuration, and fee info.
+
+```bash
+curl -X POST http://localhost:8080/... \
+  -H "Content-Type: application/json" \
+  -d '{
+    "params": {
+      "management": {
+        "action": "stats",
+        "adminSecret": "your-secret-here"
+      }
+    }
+  }'
+```
+
+**Response:**
+
+```json
+{
+  "pool": {
+    "size": 5,
+    "locked": 2,
+    "available": 3
+  },
+  "config": {
+    "network": "testnet",
+    "lockTtlSeconds": 30,
+    "feeLimit": 10000,
+    "feeResetPeriodSeconds": 3600,
+    "contractCapacityRatio": 0.8,
+    "limitedContracts": []
+  },
+  "fees": {
+    "inclusionFeeDefault": 203,
+    "inclusionFeeLimited": 201
+  }
+}
+```
+
+> **Note:** If lock checks fail, `locked` and `available` will be `undefined` rather than causing the request to fail. The `size` and config info are always returned.
+
 **Important Notes:**
 
 - You must configure at least one channel account before the plugin can process transactions
@@ -683,6 +730,19 @@ const result = await adminClient.deleteFeeLimit('client-api-key');
 console.log(result.ok); // true
 ```
 
+#### Get Pool Stats (Management)
+
+```typescript
+// Get pool health metrics (requires adminSecret)
+const stats = await adminClient.getStats();
+
+console.log(stats.pool.size); // total channels
+console.log(stats.pool.locked); // currently in-use
+console.log(stats.pool.available); // size - locked
+console.log(stats.config.network); // 'testnet' or 'mainnet'
+console.log(stats.fees); // inclusion fee values
+```
+
 ### Error Handling
 
 The client provides three types of errors:

package/dist/client/channels-client.d.ts

@@ -1,4 +1,4 @@
-import type { ChannelsClientConfig, ChannelsXdrRequest, ChannelsFuncAuthRequest, ChannelsTransactionResponse, ListChannelAccountsResponse, SetChannelAccountsResponse, GetFeeUsageResponse, GetFeeLimitResponse, SetFeeLimitResponse, DeleteFeeLimitResponse } from './types';
+import type { ChannelsClientConfig, ChannelsXdrRequest, ChannelsFuncAuthRequest, ChannelsTransactionResponse, ListChannelAccountsResponse, SetChannelAccountsResponse, GetFeeUsageResponse, GetFeeLimitResponse, SetFeeLimitResponse, DeleteFeeLimitResponse, GetStatsResponse } from './types';
 /**
  * Client for interacting with the Channels plugin
  *
@@ -137,6 +137,20 @@ export declare class ChannelsClient {
      * @throws {PluginUnexpectedError} Malformed response or client-side errors
      */
     deleteFeeLimit(apiKey: string): Promise<DeleteFeeLimitResponse>;
+    /**
+     * Get pool health stats including capacity, config, and fees (requires adminSecret)
+     *
+     * @returns Pool stats with size, locked/available counts, config, and fee info
+     * @throws {Error} If adminSecret not provided in config
+     * @throws {PluginTransportError} Network/HTTP failures
+     * @throws {PluginExecutionError} Plugin rejected the request
+     * @throws {PluginUnexpectedError} Malformed response or client-side errors
+     *
+     * @example
+     * const stats = await client.getStats();
+     * console.log(stats.pool.available);
+     */
+    getStats(): Promise<GetStatsResponse>;
     /**
      * Ensures adminSecret is configured
      *

package/dist/client/channels-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"channels-client.d.ts","sourceRoot":"","sources":["../../src/client/channels-client.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,oBAAoB,EACpB,kBAAkB,EAClB,uBAAuB,EACvB,2BAA2B,EAC3B,2BAA2B,EAC3B,0BAA0B,EAC1B,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,sBAAsB,EAEvB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAgB;IAC7C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAa;IACzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAS;gBAEvB,MAAM,EAAE,oBAAoB;IAiCxC;;;;;;;;;;;;;OAaG;IACG,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,2BAA2B,CAAC;IAI1F;;;;;;;;;;;;;;;OAeG;IACG,wBAAwB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,2BAA2B,CAAC;IAItG;;;;;;;;;;;;OAYG;IACG,mBAAmB,IAAI,OAAO,CAAC,2BAA2B,CAAC;IASjE;;;;;;;;;;;;;;;OAeG;IACG,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,0BAA0B,CAAC;IAUnF;;;;;;;;;;;;;OAaG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAU/D;;;;;;;;;OASG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAU/D;;;;;;;;;;OAUG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAW9E;;;;;;;;;OASG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAUrE;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAO1B;;;;;;;OAOG;IAEH,OAAO,CAAC,eAAe;IAgBvB;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;IAcxB;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IAUrB;;;;;;;;OAQG;YACW,IAAI;IAwBlB;;;;;;OAMG;YACW,QAAQ;CASvB"}
+{"version":3,"file":"channels-client.d.ts","sourceRoot":"","sources":["../../src/client/channels-client.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,oBAAoB,EACpB,kBAAkB,EAClB,uBAAuB,EACvB,2BAA2B,EAC3B,2BAA2B,EAC3B,0BAA0B,EAC1B,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,sBAAsB,EACtB,gBAAgB,EAEjB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAgB;IAC7C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAa;IACzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAS;gBAEvB,MAAM,EAAE,oBAAoB;IAiCxC;;;;;;;;;;;;;OAaG;IACG,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,2BAA2B,CAAC;IAI1F;;;;;;;;;;;;;;;OAeG;IACG,wBAAwB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,2BAA2B,CAAC;IAItG;;;;;;;;;;;;OAYG;IACG,mBAAmB,IAAI,OAAO,CAAC,2BAA2B,CAAC;IASjE;;;;;;;;;;;;;;;OAeG;IACG,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,0BAA0B,CAAC;IAUnF;;;;;;;;;;;;;OAaG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAU/D;;;;;;;;;OASG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAU/D;;;;;;;;;;OAUG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAW9E;;;;;;;;;OASG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAUrE;;;;;;;;;;;;OAYG;IACG,QAAQ,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAS3C;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAO1B;;;;;;;OAOG;IAEH,OAAO,CAAC,eAAe;IAgBvB;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;IAcxB;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IAUrB;;;;;;;;OAQG;YACW,IAAI;IAwBlB;;;;;;OAMG;YACW,QAAQ;CASvB"}

package/dist/client/channels-client.js

@@ -221,6 +221,27 @@ class ChannelsClient {
             },
         });
     }
+    /**
+     * Get pool health stats including capacity, config, and fees (requires adminSecret)
+     *
+     * @returns Pool stats with size, locked/available counts, config, and fee info
+     * @throws {Error} If adminSecret not provided in config
+     * @throws {PluginTransportError} Network/HTTP failures
+     * @throws {PluginExecutionError} Plugin rejected the request
+     * @throws {PluginUnexpectedError} Malformed response or client-side errors
+     *
+     * @example
+     * const stats = await client.getStats();
+     * console.log(stats.pool.available);
+     */
+    async getStats() {
+        return this.call({
+            management: {
+                action: 'stats',
+                adminSecret: this.requireAdminSecret(),
+            },
+        });
+    }
     /**
      * Ensures adminSecret is configured
      *

package/dist/client/index.d.ts

@@ -5,6 +5,6 @@
  * in both direct HTTP mode and OpenZeppelin Relayer mode.
  */
 export { ChannelsClient } from './channels-client';
-export { ChannelsClientConfig, DirectHttpConfig, RelayerConfig, ChannelsXdrRequest, ChannelsFuncAuthRequest, ChannelsTransactionResponse, ListChannelAccountsResponse, SetChannelAccountsResponse, GetFeeUsageResponse, GetFeeLimitResponse, SetFeeLimitResponse, DeleteFeeLimitResponse, } from './types';
+export { ChannelsClientConfig, DirectHttpConfig, RelayerConfig, ChannelsXdrRequest, ChannelsFuncAuthRequest, ChannelsTransactionResponse, ListChannelAccountsResponse, SetChannelAccountsResponse, GetFeeUsageResponse, GetFeeLimitResponse, SetFeeLimitResponse, DeleteFeeLimitResponse, GetStatsResponse, } from './types';
 export { PluginClientError, PluginTransportError, PluginExecutionError, PluginUnexpectedError } from './errors';
 //# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,uBAAuB,EACvB,2BAA2B,EAC3B,2BAA2B,EAC3B,0BAA0B,EAC1B,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,uBAAuB,EACvB,2BAA2B,EAC3B,2BAA2B,EAC3B,0BAA0B,EAC1B,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,sBAAsB,EACtB,gBAAgB,GACjB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC"}

package/dist/client/types.d.ts

@@ -156,6 +156,33 @@ export interface DeleteFeeLimitResponse {
         traces?: any[];
     };
 }
+/**
+ * Response from getting pool stats
+ */
+export interface GetStatsResponse {
+    pool: {
+        size: number;
+        locked?: number;
+        available?: number;
+    };
+    config: {
+        network: 'testnet' | 'mainnet';
+        lockTtlSeconds: number;
+        feeLimit?: number;
+        feeResetPeriodSeconds?: number;
+        contractCapacityRatio: number;
+        limitedContracts: string[];
+    };
+    fees: {
+        inclusionFeeDefault: number;
+        inclusionFeeLimited: number;
+    };
+    /** Optional metadata (logs and traces) */
+    metadata?: {
+        logs?: LogEntry[];
+        traces?: any[];
+    };
+}
 /**
  * Plugin response structure for successful operations
  */

package/dist/client/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"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"}

package/dist/plugin/config.d.ts

@@ -13,6 +13,9 @@ export interface ChannelAccountsConfig {
     apiKeyHeader: string;
     limitedContracts: Set<string>;
     contractCapacityRatio: number;
+    inclusionFeeDefault: number;
+    inclusionFeeLimited: number;
+    sequenceNumberCacheMaxAgeMs: number;
 }
 /**
  * Load configuration from environment variables

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

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/plugin/config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,MAAM,WAAW,qBAAqB;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,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;CAC/B;AAoFD;;GAEG;AACH,wBAAgB,UAAU,IAAI,qBAAqB,CAoBlD;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,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;CACrC;AAmGD;;GAEG;AACH,wBAAgB,UAAU,IAAI,qBAAqB,CAuBlD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,CAE3E"}

package/dist/plugin/config.js

@@ -10,6 +10,9 @@ exports.getNetworkPassphrase = getNetworkPassphrase;
 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
 function requireEnv(name) {
     const v = process.env[name];
     if (!v || v.trim() === '') {
@@ -79,6 +82,22 @@ function parseLimitedContracts() {
     }
     return new Set(contracts);
 }
+function parseInclusionFee(envVar, defaultValue) {
+    const raw = process.env[envVar];
+    if (!raw)
+        return defaultValue;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0)
+        return defaultValue;
+    return Math.floor(n);
+}
+function parseSequenceNumberCacheMaxAge() {
+    const raw = process.env.SEQUENCE_NUMBER_CACHE_MAX_AGE_MS;
+    if (!raw)
+        return constants_1.CONFIG.DEFAULT_SEQUENCE_NUMBER_CACHE_MAX_AGE_MS;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : constants_1.CONFIG.DEFAULT_SEQUENCE_NUMBER_CACHE_MAX_AGE_MS;
+}
 function parseContractCapacityRatio() {
     const raw = process.env.CONTRACT_CAPACITY_RATIO;
     if (!raw)
@@ -110,6 +129,9 @@ function loadConfig() {
         apiKeyHeader: parseApiKeyHeader(),
         limitedContracts: parseLimitedContracts(),
         contractCapacityRatio: parseContractCapacityRatio(),
+        inclusionFeeDefault: parseInclusionFee('INCLUSION_FEE_DEFAULT', DEFAULT_INCLUSION_FEE_DEFAULT),
+        inclusionFeeLimited: parseInclusionFee('INCLUSION_FEE_LIMITED', DEFAULT_INCLUSION_FEE_LIMITED),
+        sequenceNumberCacheMaxAgeMs: parseSequenceNumberCacheMaxAge(),
     };
 }
 /**

package/dist/plugin/constants.d.ts

@@ -19,6 +19,7 @@ export declare const CONFIG: {
     readonly MIN_LOCK_TTL_SECONDS: 3;
     readonly MAX_LOCK_TTL_SECONDS: 30;
     readonly DEFAULT_CONTRACT_CAPACITY_RATIO: 0.8;
+    readonly DEFAULT_SEQUENCE_NUMBER_CACHE_MAX_AGE_MS: 120000;
 };
 export declare const POOL: {
     readonly MUTEX_TTL_SECONDS: 1;
@@ -34,6 +35,7 @@ export declare const SIMULATION: {
     readonly MIN_TIME_BOUND: 0;
     readonly MAX_TIME_BOUND_OFFSET_SECONDS: 120;
     readonly MAX_FUTURE_TIME_BOUND_SECONDS: 120;
+    readonly SIMULATION_AUTH_MODE: "enforce";
 };
 export declare const POLLING: {
     readonly INTERVAL_MS: 1000;

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;;;;;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;;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;;;;;;CAMT,CAAC;AAGX,eAAO,MAAM,IAAI;;;;;CAOP,CAAC;AAGX,eAAO,MAAM,IAAI;;CAEP,CAAC;AAGX,eAAO,MAAM,UAAU;;;;;;CAMb,CAAC;AAGX,eAAO,MAAM,OAAO;;;CAGV,CAAC;AAEX,eAAO,MAAM,GAAG;;CAGN,CAAC"}

package/dist/plugin/constants.js

@@ -24,6 +24,7 @@ exports.CONFIG = {
     MIN_LOCK_TTL_SECONDS: 3,
     MAX_LOCK_TTL_SECONDS: 30,
     DEFAULT_CONTRACT_CAPACITY_RATIO: 0.8,
+    DEFAULT_SEQUENCE_NUMBER_CACHE_MAX_AGE_MS: 120000,
 };
 // Pool Constants
 exports.POOL = {
@@ -44,6 +45,7 @@ exports.SIMULATION = {
     MIN_TIME_BOUND: 0,
     MAX_TIME_BOUND_OFFSET_SECONDS: 120,
     MAX_FUTURE_TIME_BOUND_SECONDS: 120,
+    SIMULATION_AUTH_MODE: 'enforce',
 };
 // Polling for transactionWait
 exports.POLLING = {

package/dist/plugin/fee.d.ts

@@ -2,13 +2,16 @@
  * fee.ts
  *
  * Static fee calculation for fee bump submissions matching launchtube.
- * - For Soroban transactions: use resourceFee + inclusion fee (BASE_FEE * 2 + 3)
+ * - For Soroban transactions: use resourceFee + inclusion fee
  * - For non-Soroban: use NON_SOROBAN_FEE + inclusion fee
- * - Limited contracts (from LIMITED_CONTRACTS env) get reduced fee (BASE_FEE * 2 + 1)
+ * - Limited contracts (from LIMITED_CONTRACTS env) get reduced fee
+ * - Inclusion fees are configurable via INCLUSION_FEE_DEFAULT and INCLUSION_FEE_LIMITED env vars
  */
 import { Transaction, xdr } from '@stellar/stellar-sdk';
-export declare const INCLUSION_FEE_DEFAULT: number;
-export declare const INCLUSION_FEE_LIMITED: number;
+export interface InclusionFees {
+    inclusionFeeDefault: number;
+    inclusionFeeLimited: number;
+}
 /**
  * Extract contract ID from a HostFunction (for func+auth flow)
  */
@@ -17,5 +20,5 @@ 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;
-export declare function calculateMaxFee(transaction: Transaction, limitedContracts?: Set<string>): number;
+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;;;;;;;GAOG;AAEH,OAAO,EAAY,WAAW,EAAE,GAAG,EAAqB,MAAM,sBAAsB,CAAC;AAGrF,eAAO,MAAM,qBAAqB,QAA2B,CAAC;AAC9D,eAAO,MAAM,qBAAqB,QAA2B,CAAC;AAE9D;;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,GAAE,GAAG,CAAC,MAAM,CAAa,GAAG,MAAM,CAoB3G"}
+{"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,CAoBpH"}

package/dist/plugin/fee.js

@@ -3,19 +3,17 @@
  * fee.ts
  *
  * Static fee calculation for fee bump submissions matching launchtube.
- * - For Soroban transactions: use resourceFee + inclusion fee (BASE_FEE * 2 + 3)
+ * - For Soroban transactions: use resourceFee + inclusion fee
  * - For non-Soroban: use NON_SOROBAN_FEE + inclusion fee
- * - Limited contracts (from LIMITED_CONTRACTS env) get reduced fee (BASE_FEE * 2 + 1)
+ * - Limited contracts (from LIMITED_CONTRACTS env) get reduced fee
+ * - Inclusion fees are configurable via INCLUSION_FEE_DEFAULT and INCLUSION_FEE_LIMITED env vars
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.INCLUSION_FEE_LIMITED = exports.INCLUSION_FEE_DEFAULT = void 0;
 exports.getContractIdFromFunc = getContractIdFromFunc;
 exports.getContractIdFromTransaction = getContractIdFromTransaction;
 exports.calculateMaxFee = calculateMaxFee;
 const stellar_sdk_1 = require("@stellar/stellar-sdk");
 const constants_1 = require("./constants");
-exports.INCLUSION_FEE_DEFAULT = Number(stellar_sdk_1.BASE_FEE) * 2 + 3;
-exports.INCLUSION_FEE_LIMITED = Number(stellar_sdk_1.BASE_FEE) * 2 + 1;
 /**
  * Extract contract ID from a HostFunction (for func+auth flow)
  */
@@ -48,13 +46,13 @@ function getContractIdFromTransaction(transaction) {
         return undefined;
     }
 }
-function getInclusionFee(contractId, limitedContracts) {
+function getInclusionFee(contractId, limitedContracts, fees) {
     if (contractId && limitedContracts.has(contractId)) {
-        return exports.INCLUSION_FEE_LIMITED;
+        return fees.inclusionFeeLimited;
     }
-    return exports.INCLUSION_FEE_DEFAULT;
+    return fees.inclusionFeeDefault;
 }
-function calculateMaxFee(transaction, limitedContracts = new Set()) {
+function calculateMaxFee(transaction, limitedContracts, fees) {
     const envelope = transaction.toEnvelope();
     let resourceFee = 0n;
     if (envelope.switch() === stellar_sdk_1.xdr.EnvelopeType.envelopeTypeTx()) {
@@ -64,7 +62,7 @@ function calculateMaxFee(transaction, limitedContracts = new Set()) {
         }
     }
     const contractId = getContractIdFromTransaction(transaction);
-    const inclusionFee = getInclusionFee(contractId, limitedContracts);
+    const inclusionFee = getInclusionFee(contractId, limitedContracts, fees);
     const fee = resourceFee > 0n ? resourceFee + BigInt(inclusionFee) : BigInt(constants_1.FEE.NON_SOROBAN_FEE + inclusionFee);
     console.debug(`[channels] Calculated max_fee: ${Number(fee)} stroops (resourceFee: ${resourceFee}, inclusionFee: ${inclusionFee})`);
     return Number(fee);

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

@@ -1 +1 @@
-{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/plugin/handler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAe,MAAM,2BAA2B,CAAC;AASvE,OAAO,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAC;AAWxD;;;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;AAsOD;;GAEG;AACH,wBAAsB,OAAO,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,CAElE"}
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/plugin/handler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAe,MAAM,2BAA2B,CAAC;AASvE,OAAO,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAC;AA0BxD;;;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;AAqPD;;GAEG;AACH,wBAAsB,OAAO,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,CAElE"}

package/dist/plugin/handler.js

@@ -20,6 +20,7 @@ const simulation_1 = require("./simulation");
 const fee_1 = require("./fee");
 const tx_1 = require("./tx");
 const fee_tracking_1 = require("./fee-tracking");
+const sequence_1 = require("./sequence");
 function getApiKey(headers, headerName) {
     const values = headers[headerName];
     return values?.[0]?.trim() || undefined;
@@ -44,8 +45,8 @@ function extractFuncAuthFromUnsignedXdr(tx) {
         auth: invokeHostFn.auth(),
     };
 }
-async function handleXdrSubmit(xdrStr, fundRelayer, fundAddress, network, networkPassphrase, api, pool, acquireOptions, tracker) {
-    const tx = new stellar_sdk_1.Transaction(xdrStr, networkPassphrase);
+async function handleXdrSubmit(xdrStr, ctx) {
+    const tx = new stellar_sdk_1.Transaction(xdrStr, ctx.networkPassphrase);
     // Unsigned XDR: extract func+auth and route through channel path
     if (tx.signatures.length === 0) {
         const extracted = extractFuncAuthFromUnsignedXdr(tx);
@@ -62,17 +63,22 @@ async function handleXdrSubmit(xdrStr, fundRelayer, fundAddress, network, networ
         console.log(`[channels] Unsigned XDR detected, extracting func+auth and routing through channel path`);
         // Update acquireOptions with contractId from extracted func
         const contractId = (0, fee_1.getContractIdFromFunc)(extracted.func);
-        const updatedOptions = { ...acquireOptions, contractId };
-        return handleFuncAuthSubmit(extracted.func, extracted.auth, api, pool, fundRelayer, fundAddress, network, networkPassphrase, updatedOptions, tracker);
+        const updatedOptions = { ...ctx.acquireOptions, contractId };
+        return handleFuncAuthSubmit(extracted.func, extracted.auth, { ...ctx, acquireOptions: updatedOptions });
     }
     const validated = (0, tx_1.validateExistingTransactionForSubmitOnly)(tx);
-    const maxFee = (0, fee_1.calculateMaxFee)(validated, acquireOptions.limitedContracts);
-    await tracker?.checkBudget(maxFee);
-    return (0, submit_1.submitWithFeeBumpAndWait)(fundRelayer, validated.toXDR(), network, maxFee, api, tracker);
+    const maxFee = (0, fee_1.calculateMaxFee)(validated, ctx.acquireOptions.limitedContracts, ctx.fees);
+    const contractId = (0, fee_1.getContractIdFromTransaction)(validated);
+    await ctx.tracker?.checkBudget(maxFee);
+    const submitContext = {
+        contractId,
+        isLimited: contractId ? ctx.acquireOptions.limitedContracts.has(contractId) : false,
+    };
+    return (0, submit_1.submitWithFeeBumpAndWait)(ctx.fundRelayer, validated.toXDR(), ctx.network, maxFee, ctx.api, ctx.tracker, submitContext);
 }
-async function handleFuncAuthSubmit(func, auth, api, pool, fundRelayer, fundAddress, network, networkPassphrase, acquireOptions, tracker) {
+async function handleFuncAuthSubmit(func, auth, ctx) {
     // Simulate once — used for both read-only detection and transaction assembly
-    const simulation = await (0, simulation_1.simulateTransaction)(func, auth, fundAddress, fundRelayer, networkPassphrase);
+    const simulation = await (0, simulation_1.simulateTransaction)(func, auth, ctx.fundAddress, ctx.fundRelayer, ctx.networkPassphrase);
     if (simulation.isReadOnly) {
         console.log(`[channels] Read-only call detected, returning simulation result`);
         return {
@@ -85,8 +91,8 @@ async function handleFuncAuthSubmit(func, auth, api, pool, fundRelayer, fundAddr
     }
     let poolLock;
     try {
-        poolLock = await pool.acquire(acquireOptions);
-        const channelRelayer = api.useRelayer(poolLock.relayerId);
+        poolLock = await ctx.pool.acquire(ctx.acquireOptions);
+        const channelRelayer = ctx.api.useRelayer(poolLock.relayerId);
         const channelInfo = await channelRelayer.getRelayer();
         console.log(`[channels] Acquired channel: ${poolLock.relayerId}`);
         if (!channelInfo || !channelInfo.address) {
@@ -96,24 +102,42 @@ async function handleFuncAuthSubmit(func, auth, api, pool, fundRelayer, fundAddr
                 details: { relayerId: poolLock.relayerId },
             });
         }
-        const channelStatus = await channelRelayer.getRelayerStatus();
-        if (channelStatus.network_type !== 'stellar') {
+        if (channelInfo.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 },
+                details: { network_type: channelInfo.network_type, relayerId: poolLock.relayerId },
             });
         }
+        const sequence = await (0, sequence_1.getSequence)(ctx.kv, ctx.network, channelRelayer, channelInfo.address, ctx.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: channelStatus.sequence_number }, networkPassphrase, simulation.rawSimResult);
-        const signedTx = await (0, submit_1.signWithChannelAndFund)(built, channelRelayer, fundRelayer, channelInfo.address, fundAddress, networkPassphrase);
-        const maxFee = (0, fee_1.calculateMaxFee)(signedTx, acquireOptions.limitedContracts);
-        await tracker?.checkBudget(maxFee);
-        return await (0, submit_1.submitWithFeeBumpAndWait)(fundRelayer, signedTx.toXDR(), network, maxFee, api, tracker);
+        const built = (0, simulation_1.buildWithChannel)(func, auth, { address: channelInfo.address, sequence }, ctx.networkPassphrase, simulation.rawSimResult);
+        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);
+        const contractId = (0, fee_1.getContractIdFromFunc)(func);
+        await ctx.tracker?.checkBudget(maxFee);
+        const submitContext = {
+            contractId,
+            isLimited: contractId ? ctx.acquireOptions.limitedContracts.has(contractId) : false,
+        };
+        try {
+            const result = await (0, submit_1.submitWithFeeBumpAndWait)(ctx.fundRelayer, signedTx.toXDR(), ctx.network, maxFee, ctx.api, ctx.tracker, submitContext);
+            if (result.status === 'confirmed') {
+                await (0, sequence_1.commitSequence)(ctx.kv, ctx.network, channelInfo.address, sequence);
+            }
+            else {
+                await (0, sequence_1.clearSequence)(ctx.kv, ctx.network, channelInfo.address);
+            }
+            return result;
+        }
+        catch (error) {
+            await (0, sequence_1.clearSequence)(ctx.kv, ctx.network, channelInfo.address);
+            throw error;
+        }
     }
     finally {
         if (poolLock) {
-            await pool.release(poolLock);
+            await ctx.pool.release(poolLock);
         }
     }
 }
@@ -172,16 +196,34 @@ async function channelAccounts(context) {
         limitedContracts: config.limitedContracts,
         capacityRatio: config.contractCapacityRatio,
     };
-    // 4. Branch by request type
+    const fees = {
+        inclusionFeeDefault: config.inclusionFeeDefault,
+        inclusionFeeLimited: config.inclusionFeeLimited,
+    };
+    // 4. Build pipeline context
+    const ctx = {
+        api,
+        kv,
+        pool,
+        fundRelayer: fundRelayer,
+        fundAddress: fundInfo.address,
+        network: config.network,
+        networkPassphrase,
+        acquireOptions,
+        fees,
+        tracker,
+        sequenceNumberCacheMaxAgeMs: config.sequenceNumberCacheMaxAgeMs,
+    };
+    // 5. Branch by request type
     if (request.type === 'xdr') {
         console.log(`[channels] Flow: XDR submit-only`);
-        return await handleXdrSubmit(request.xdr, fundRelayer, fundInfo.address, config.network, networkPassphrase, api, pool, acquireOptions, tracker);
+        return await handleXdrSubmit(request.xdr, ctx);
     }
     // Extract contractId for func+auth flow
     const contractId = (0, fee_1.getContractIdFromFunc)(request.func);
     const funcAcquireOptions = { ...acquireOptions, contractId };
     console.log(`[channels] Flow: func+auth with channel account`);
-    return await handleFuncAuthSubmit(request.func, request.auth, api, pool, fundRelayer, fundInfo.address, config.network, networkPassphrase, funcAcquireOptions, tracker);
+    return await handleFuncAuthSubmit(request.func, request.auth, { ...ctx, acquireOptions: funcAcquireOptions });
 }
 /**
  * Main plugin handler exported for OpenZeppelin Relayer

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

@@ -1 +1 @@
-{"version":3,"file":"management.d.ts","sourceRoot":"","sources":["../../src/plugin/management.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,2BAA2B,CAAC;AAM9E,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,GAAG,GAAG,OAAO,CAIxD;AAED,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,CAkC3E"}
+{"version":3,"file":"management.d.ts","sourceRoot":"","sources":["../../src/plugin/management.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,2BAA2B,CAAC;AAO9E,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,GAAG,GAAG,OAAO,CAIxD;AAED,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,CAoC3E"}

package/dist/plugin/management.js

@@ -48,6 +48,8 @@ async function handleManagement(context) {
             return await setFeeLimit(kv, config.network, m);
         case 'deleteFeeLimit':
             return await deleteFeeLimit(kv, config.network, m);
+        case 'stats':
+            return await getPoolStats(config, kv);
         default:
             throw (0, relayer_sdk_1.pluginError)('Invalid management action', { code: 'INVALID_ACTION', status: constants_1.HTTP_STATUS.BAD_REQUEST });
     }
@@ -194,6 +196,52 @@ async function setChannelAccounts(kv, network, payload) {
         });
     }
 }
+async function getPoolStats(config, kv) {
+    const { network } = config;
+    // 1. Get relayer IDs (1 KV call)
+    const key = `${network}:channel:relayer-ids`;
+    let relayerIds;
+    try {
+        const doc = await kv.get?.(key);
+        relayerIds = Array.isArray(doc?.relayerIds) ? doc.relayerIds : [];
+    }
+    catch (e) {
+        throw (0, relayer_sdk_1.pluginError)('KV error while reading pool stats', {
+            code: 'KV_ERROR',
+            status: constants_1.HTTP_STATUS.INTERNAL_SERVER_ERROR,
+        });
+    }
+    // 2. Check all locks in parallel (N KV calls) — best-effort
+    let locked;
+    let available;
+    try {
+        const results = await Promise.all(relayerIds.map((id) => kv.exists(`${network}:channel:in-use:${id}`)));
+        locked = results.filter(Boolean).length;
+        available = relayerIds.length - locked;
+    }
+    catch {
+        // Non-fatal: return pool size without lock info
+    }
+    return {
+        pool: {
+            size: relayerIds.length,
+            locked,
+            available,
+        },
+        config: {
+            network,
+            lockTtlSeconds: config.lockTtlSeconds,
+            feeLimit: config.feeLimit,
+            feeResetPeriodSeconds: config.feeResetPeriodMs ? config.feeResetPeriodMs / 1000 : undefined,
+            contractCapacityRatio: config.contractCapacityRatio,
+            limitedContracts: Array.from(config.limitedContracts),
+        },
+        fees: {
+            inclusionFeeDefault: config.inclusionFeeDefault,
+            inclusionFeeLimited: config.inclusionFeeLimited,
+        },
+    };
+}
 function normalizeId(id) {
     return String(id).trim().toLowerCase();
 }

package/dist/plugin/pool.d.ts

@@ -32,5 +32,6 @@ export declare class ChannelPool {
     private membershipKey;
     private lockKey;
     private getRelayerIdsFromKV;
+    private getPoolCapacityDetails;
 }
 //# sourceMappingURL=pool.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../../src/plugin/pool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAe,MAAM,2BAA2B,CAAC;AAIvE,MAAM,MAAM,QAAQ,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5D,MAAM,MAAM,cAAc,GAAG;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAIF,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAgB;gBAEvB,OAAO,EAAE,SAAS,GAAG,SAAS,EAAE,EAAE,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM;IAQrF,4CAA4C;IACtC,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC;YA4B3C,eAAe;YAKf,iBAAiB;IA2B/B,oCAAoC;IAC9B,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAY5C,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,OAAO;YAID,mBAAmB;CAWlC"}
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../../src/plugin/pool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAe,MAAM,2BAA2B,CAAC;AAIvE,MAAM,MAAM,QAAQ,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5D,MAAM,MAAM,cAAc,GAAG;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAUF,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAgB;gBAEvB,OAAO,EAAE,SAAS,GAAG,SAAS,EAAE,EAAE,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM;IAQrF,4CAA4C;IACtC,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC;YAyB3C,eAAe;YAKf,iBAAiB;IA2B/B,oCAAoC;IAC9B,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAY5C,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,OAAO;YAID,mBAAmB;YAYnB,sBAAsB;CAUrC"}

package/dist/plugin/pool.js

@@ -26,7 +26,6 @@ class ChannelPool {
     /** Acquire a relayerId with a token lock */
     async acquire(options) {
         const maxSpins = constants_1.POOL.MUTEX_MAX_SPINS;
-        const isLimited = options.contractId && options.limitedContracts.has(options.contractId);
         for (let i = 0; i < maxSpins; i++) {
             const r = await this.withGlobalMutex(() => this.tryLockAnyRelayer(options));
             if (r === null) {
@@ -36,12 +35,12 @@ class ChannelPool {
             }
             return r;
         }
-        if (isLimited) {
-            console.log(`[channels] Contract ${options.contractId} limited to ${Math.round(options.capacityRatio * 100)}% capacity - no channels available`);
-        }
+        const diagnostics = await this.getPoolCapacityDetails(options, maxSpins);
+        console.warn('[channels] Pool capacity exhausted', diagnostics);
         throw (0, relayer_sdk_1.pluginError)('Too many transactions queued. Please try again later', {
             code: 'POOL_CAPACITY',
             status: constants_1.HTTP_STATUS.SERVICE_UNAVAILABLE,
+            details: diagnostics,
         });
     }
     // Run a function under the short-lived global mutex; returns null if busy
@@ -106,6 +105,15 @@ class ChannelPool {
             return [];
         }
     }
+    async getPoolCapacityDetails(options, maxSpins) {
+        const isLimited = !!(options.contractId && options.limitedContracts.has(options.contractId));
+        return {
+            reason: isLimited ? 'limited_contract_capacity' : 'all_channels_busy_or_mutex_contention',
+            contractId: options.contractId,
+            capacityRatio: options.capacityRatio,
+            maxSpins,
+        };
+    }
 }
 exports.ChannelPool = ChannelPool;
 function shuffle(arr) {

package/dist/plugin/sequence.d.ts

@@ -0,0 +1,30 @@
+/**
+ * sequence.ts
+ *
+ * KV-based sequence number cache for channel accounts.
+ * After a transaction is confirmed on-chain, the RPC `getLedgerEntries` can
+ * still return the old (pre-increment) sequence number due to read-after-write
+ * lag.  Caching the next expected sequence in KV avoids `tx_bad_seq` errors.
+ */
+import type { PluginKVStore, Relayer } from '@openzeppelin/relayer-sdk';
+/**
+ * Fetch the current sequence number for an account directly from chain
+ * via `getLedgerEntries` RPC. Throws on any RPC or decoding failure.
+ */
+export declare function getAccountSequence(relayer: Relayer, address: string): Promise<string>;
+/**
+ * Get the current sequence number for a channel account.
+ * Reads from KV cache first; falls back to chain via `getAccountSequence`.
+ */
+export declare function getSequence(kv: PluginKVStore, network: string, relayer: Relayer, address: string, sequenceNumberCacheMaxAgeMs: number): Promise<string>;
+/**
+ * Store the next expected sequence number in KV after a transaction
+ * has been confirmed on-chain.
+ */
+export declare function commitSequence(kv: PluginKVStore, network: string, address: string, usedSequence: string): Promise<void>;
+/**
+ * Clear cached sequence — forces a re-fetch from chain on next request.
+ * Used when transaction outcome is uncertain (e.g. timeout).
+ */
+export declare function clearSequence(kv: PluginKVStore, network: string, address: string): Promise<void>;
+//# sourceMappingURL=sequence.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sequence.d.ts","sourceRoot":"","sources":["../../src/plugin/sequence.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAwBxE;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAsH3F;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,EAAE,EAAE,aAAa,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,EACf,2BAA2B,EAAE,MAAM,GAClC,OAAO,CAAC,MAAM,CAAC,CAwBjB;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,aAAa,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CAaf;AAED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,EAAE,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWtG"}

package/dist/plugin/sequence.js

@@ -0,0 +1,212 @@
+"use strict";
+/**
+ * sequence.ts
+ *
+ * KV-based sequence number cache for channel accounts.
+ * After a transaction is confirmed on-chain, the RPC `getLedgerEntries` can
+ * still return the old (pre-increment) sequence number due to read-after-write
+ * lag.  Caching the next expected sequence in KV avoids `tx_bad_seq` errors.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAccountSequence = getAccountSequence;
+exports.getSequence = getSequence;
+exports.commitSequence = commitSequence;
+exports.clearSequence = clearSequence;
+const relayer_sdk_1 = require("@openzeppelin/relayer-sdk");
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+const constants_1 = require("./constants");
+function seqKey(network, address) {
+    return `${network}:channel:seq:${address}`;
+}
+/**
+ * Validates that a sequence number string is a non-negative integer.
+ * Returns true for strings like "0", "42", "123456789012345".
+ */
+function isValidSequence(seq) {
+    return /^\d+$/.test(seq);
+}
+/**
+ * Fetch the current sequence number for an account directly from chain
+ * via `getLedgerEntries` RPC. Throws on any RPC or decoding failure.
+ */
+async function getAccountSequence(relayer, address) {
+    let accountKey;
+    try {
+        accountKey = stellar_sdk_1.xdr.LedgerKey.account(new stellar_sdk_1.xdr.LedgerKeyAccount({
+            accountId: stellar_sdk_1.Keypair.fromPublicKey(address).xdrPublicKey(),
+        }));
+    }
+    catch (error) {
+        console.error('[channels] Sequence fetch failed', {
+            event: 'invalid_channel_account_address',
+            code: 'FAILED_TO_GET_SEQUENCE',
+            address,
+            message: error instanceof Error ? error.message : String(error),
+        });
+        throw (0, relayer_sdk_1.pluginError)('Invalid channel account address', {
+            code: 'FAILED_TO_GET_SEQUENCE',
+            status: constants_1.HTTP_STATUS.BAD_GATEWAY,
+            details: { address, message: error instanceof Error ? error.message : String(error) },
+        });
+    }
+    let response;
+    try {
+        response = await relayer.rpc({
+            jsonrpc: '2.0',
+            id: Math.floor(Math.random() * 1e8).toString(),
+            method: 'getLedgerEntries',
+            params: {
+                keys: [accountKey.toXDR('base64')],
+            },
+        });
+    }
+    catch (error) {
+        console.error('[channels] Sequence fetch failed', {
+            event: 'sequence_rpc_request_failed',
+            code: 'FAILED_TO_GET_SEQUENCE',
+            address,
+            message: error instanceof Error ? error.message : String(error),
+        });
+        throw (0, relayer_sdk_1.pluginError)('Failed to get sequence from channel relayer', {
+            code: 'FAILED_TO_GET_SEQUENCE',
+            status: constants_1.HTTP_STATUS.BAD_GATEWAY,
+            details: { message: error instanceof Error ? error.message : String(error) },
+        });
+    }
+    if (response.error) {
+        console.error('[channels] Sequence fetch failed', {
+            event: 'sequence_rpc_error_response',
+            code: 'FAILED_TO_GET_SEQUENCE',
+            address,
+            message: response.error.message,
+        });
+        throw (0, relayer_sdk_1.pluginError)('Failed to get sequence from channel relayer', {
+            code: 'FAILED_TO_GET_SEQUENCE',
+            status: constants_1.HTTP_STATUS.BAD_GATEWAY,
+            details: { message: response.error.message },
+        });
+    }
+    const result = response.result;
+    const entries = result?.entries;
+    if (!Array.isArray(entries)) {
+        console.error('[channels] Sequence fetch failed', {
+            event: 'sequence_rpc_invalid_result_shape',
+            code: 'FAILED_TO_GET_SEQUENCE',
+            address,
+        });
+        throw (0, relayer_sdk_1.pluginError)('Invalid RPC response for account sequence', {
+            code: 'FAILED_TO_GET_SEQUENCE',
+            status: constants_1.HTTP_STATUS.BAD_GATEWAY,
+            details: { address },
+        });
+    }
+    if (!entries || entries.length === 0) {
+        console.warn('[channels] Sequence fetch returned no account entries', {
+            event: 'sequence_account_not_found',
+            code: 'ACCOUNT_NOT_FOUND',
+            address,
+        });
+        throw (0, relayer_sdk_1.pluginError)('Channel account not found on ledger', {
+            code: 'ACCOUNT_NOT_FOUND',
+            status: constants_1.HTTP_STATUS.BAD_GATEWAY,
+            details: { address },
+        });
+    }
+    const firstEntryXdr = entries[0]?.xdr;
+    if (typeof firstEntryXdr !== 'string') {
+        console.error('[channels] Sequence fetch failed', {
+            event: 'sequence_rpc_invalid_entry_xdr',
+            code: 'FAILED_TO_GET_SEQUENCE',
+            address,
+        });
+        throw (0, relayer_sdk_1.pluginError)('Invalid RPC response for account sequence', {
+            code: 'FAILED_TO_GET_SEQUENCE',
+            status: constants_1.HTTP_STATUS.BAD_GATEWAY,
+            details: { address },
+        });
+    }
+    try {
+        const accountEntry = stellar_sdk_1.xdr.LedgerEntryData.fromXDR(firstEntryXdr, 'base64');
+        return accountEntry.account().seqNum().toString();
+    }
+    catch (error) {
+        console.error('[channels] Sequence fetch failed', {
+            event: 'sequence_xdr_decode_failed',
+            code: 'FAILED_TO_GET_SEQUENCE',
+            address,
+            message: error instanceof Error ? error.message : String(error),
+        });
+        throw (0, relayer_sdk_1.pluginError)('Failed to decode account sequence from ledger entry', {
+            code: 'FAILED_TO_GET_SEQUENCE',
+            status: constants_1.HTTP_STATUS.BAD_GATEWAY,
+            details: { address, message: error instanceof Error ? error.message : String(error) },
+        });
+    }
+}
+/**
+ * Get the current sequence number for a channel account.
+ * Reads from KV cache first; falls back to chain via `getAccountSequence`.
+ */
+async function getSequence(kv, network, relayer, address, sequenceNumberCacheMaxAgeMs) {
+    const key = seqKey(network, address);
+    try {
+        const cached = await kv.get(key);
+        if (cached?.sequence) {
+            if (!isValidSequence(cached.sequence)) {
+                console.warn(`[channels] Sequence cache invalid: address=${address}, value=${cached.sequence}, refetching`);
+            }
+            else {
+                const age = Date.now() - (cached.storedAt ?? 0);
+                if (age < sequenceNumberCacheMaxAgeMs) {
+                    console.debug(`[channels] Sequence cache hit: address=${address}, seq=${cached.sequence}, age=${age}ms`);
+                    return cached.sequence;
+                }
+                console.debug(`[channels] Sequence cache stale: address=${address}, age=${age}ms, refetching`);
+            }
+        }
+    }
+    catch (err) {
+        console.warn(`[channels] Failed to read sequence from KV, falling back to chain`, {
+            address,
+            key,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+    return getAccountSequence(relayer, address);
+}
+/**
+ * Store the next expected sequence number in KV after a transaction
+ * has been confirmed on-chain.
+ */
+async function commitSequence(kv, network, address, usedSequence) {
+    const next = (BigInt(usedSequence) + 1n).toString();
+    const key = seqKey(network, address);
+    try {
+        await kv.set(key, { sequence: next, storedAt: Date.now() });
+        console.debug(`[channels] Sequence committed: address=${address}, next=${next}`);
+    }
+    catch (err) {
+        console.warn(`[channels] Failed to commit sequence to KV`, {
+            address,
+            next,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+/**
+ * Clear cached sequence — forces a re-fetch from chain on next request.
+ * Used when transaction outcome is uncertain (e.g. timeout).
+ */
+async function clearSequence(kv, network, address) {
+    const key = seqKey(network, address);
+    try {
+        await kv.del(key);
+        console.debug(`[channels] Sequence cleared: address=${address}`);
+    }
+    catch (err) {
+        console.warn(`[channels] Failed to clear sequence from KV`, {
+            address,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}

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;AAED;;;;;;;;;;;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,CA8E3B;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,GAChD,WAAW,CAsCb;AACD,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,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,GAChD,WAAW,CAsCb;AACD,0FAA0F;AAC1F,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAe1D"}

package/dist/plugin/simulation.js

@@ -41,7 +41,8 @@ async function simulateTransaction(func, auth, sourceAddress, relayer, networkPa
             jsonrpc: '2.0',
             id: Math.floor(Math.random() * 1e8).toString(),
             method: 'simulateTransaction',
-            params: { transaction: transaction.toXDR() },
+            // Enforce mode validates auth entry signatures during simulation.
+            params: { transaction: transaction.toXDR(), authMode: constants_1.SIMULATION.SIMULATION_AUTH_MODE },
         });
     }
     catch (err) {
@@ -65,11 +66,13 @@ async function simulateTransaction(func, auth, sourceAddress, relayer, networkPa
         ...rpcResponse.result,
     };
     if ('error' in simResult && simResult.error) {
+        const parsedError = parseSimulationError(simResult.error);
+        const failure = classifySimulationFailure(simResult.error, parsedError);
         console.error(`[channels] Simulation error: ${simResult.error}`);
-        throw (0, relayer_sdk_1.pluginError)('Simulation failed', {
-            code: 'SIMULATION_FAILED',
+        throw (0, relayer_sdk_1.pluginError)(failure.message, {
+            code: failure.code,
             status: constants_1.HTTP_STATUS.BAD_REQUEST,
-            details: { error: parseSimulationError(simResult.error) },
+            details: { error: parsedError, authMode: constants_1.SIMULATION.SIMULATION_AUTH_MODE },
         });
     }
     // Read-only detection
@@ -148,3 +151,25 @@ function parseSimulationError(error) {
     }
     return firstLine;
 }
+function classifySimulationFailure(rawError, parsedError) {
+    const isEnforcedAuthValidation = constants_1.SIMULATION.SIMULATION_AUTH_MODE === 'enforce' &&
+        (/\bError\(Auth,/i.test(rawError) ||
+            /\brequire_auth\b/i.test(rawError) ||
+            /\binvalid\s+signature\b/i.test(rawError) ||
+            /\bsignature\s+has\s+expired\b/i.test(rawError) ||
+            /\bsignature\s+expired\b/i.test(rawError) ||
+            /\bsignature\s+verification\s+failed\b/i.test(rawError) ||
+            /\bbad[_\s]?signature\b/i.test(rawError) ||
+            /\btx_bad_auth\b/i.test(rawError) ||
+            /\bbad[_\s]?auth\b/i.test(rawError));
+    if (isEnforcedAuthValidation) {
+        return {
+            code: 'SIMULATION_SIGNED_AUTH_VALIDATION_FAILED',
+            message: `Signed auth entry validation failed in enforce simulation: ${parsedError}`,
+        };
+    }
+    return {
+        code: 'SIMULATION_FAILED',
+        message: 'Simulation failed',
+    };
+}

package/dist/plugin/submit.d.ts

@@ -7,6 +7,14 @@ import { Transaction } from '@stellar/stellar-sdk';
 import { Relayer, PluginAPI } from '@openzeppelin/relayer-sdk';
 import { ChannelAccountsResponse } from './types';
 import { FeeTracker } from './fee-tracking';
+export interface SubmitContext {
+    contractId?: string;
+    isLimited?: boolean;
+}
+interface DecodedTransactionResult {
+    feeCharged: number;
+    resultCode: string;
+}
 /**
  * Sign transaction with both channel and fund relayers
  * - First sign with channel account
@@ -17,7 +25,11 @@ export declare function signWithChannelAndFund(transaction: Transaction, channel
 /**
  * Submit transaction with fee bump and wait for confirmation
  */
-export declare function submitWithFeeBumpAndWait(fundRelayer: Relayer, signedXdr: string, network: 'testnet' | 'mainnet', maxFee: number, api: PluginAPI, tracker?: FeeTracker): Promise<ChannelAccountsResponse>;
+export declare function submitWithFeeBumpAndWait(fundRelayer: Relayer, signedXdr: string, network: 'testnet' | 'mainnet', maxFee: number, api: PluginAPI, tracker?: FeeTracker, context?: SubmitContext): Promise<ChannelAccountsResponse>;
+/** Try to decode a transaction result XDR from the reason string */
+export declare function decodeTransactionResult(reason: string): DecodedTransactionResult | null;
+export declare function buildStellarLabTransactionUrl(network: 'testnet' | 'mainnet', txHash: string): string;
 /** Strip provider wrapper text, extract last segment (e.g., "TxInsufficientBalance") */
 export declare function sanitizeReason(reason: string): string;
+export {};
 //# sourceMappingURL=submit.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"submit.d.ts","sourceRoot":"","sources":["../../src/plugin/submit.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAEL,OAAO,EAGP,SAAS,EACV,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE5C;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,WAAW,EAAE,WAAW,EACxB,cAAc,EAAE,OAAO,EACvB,YAAY,EAAE,OAAO,EACrB,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,EACpB,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC,WAAW,CAAC,CAuBtB;AAED;;GAEG;AACH,wBAAsB,wBAAwB,CAC5C,WAAW,EAAE,OAAO,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,SAAS,GAAG,SAAS,EAC9B,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,SAAS,EACd,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,uBAAuB,CAAC,CAkElC;AASD,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAOrD"}
+{"version":3,"file":"submit.d.ts","sourceRoot":"","sources":["../../src/plugin/submit.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAO,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAEL,OAAO,EAGP,SAAS,EACV,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE5C,MAAM,WAAW,aAAa;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,UAAU,wBAAwB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,WAAW,EAAE,WAAW,EACxB,cAAc,EAAE,OAAO,EACvB,YAAY,EAAE,OAAO,EACrB,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,EACpB,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC,WAAW,CAAC,CAuBtB;AAED;;GAEG;AACH,wBAAsB,wBAAwB,CAC5C,WAAW,EAAE,OAAO,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,SAAS,GAAG,SAAS,EAC9B,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,SAAS,EACd,OAAO,CAAC,EAAE,UAAU,EACpB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,uBAAuB,CAAC,CAmFlC;AASD,oEAAoE;AACpE,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,wBAAwB,GAAG,IAAI,CAkCvF;AAeD,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAepG;AAED,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAOrD"}

package/dist/plugin/submit.js

@@ -7,6 +7,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.signWithChannelAndFund = signWithChannelAndFund;
 exports.submitWithFeeBumpAndWait = submitWithFeeBumpAndWait;
+exports.decodeTransactionResult = decodeTransactionResult;
+exports.buildStellarLabTransactionUrl = buildStellarLabTransactionUrl;
 exports.sanitizeReason = sanitizeReason;
 const stellar_sdk_1 = require("@stellar/stellar-sdk");
 const relayer_sdk_1 = require("@openzeppelin/relayer-sdk");
@@ -40,7 +42,7 @@ async function signWithChannelAndFund(transaction, channelRelayer, _fundRelayer,
 /**
  * Submit transaction with fee bump and wait for confirmation
  */
-async function submitWithFeeBumpAndWait(fundRelayer, signedXdr, network, maxFee, api, tracker) {
+async function submitWithFeeBumpAndWait(fundRelayer, signedXdr, network, maxFee, api, tracker, context) {
     // Submit with fee bump
     console.debug(`[channels] Sending fee bump tx: network=${network}, maxFee=${maxFee}, xdr_len=${signedXdr.length}`);
     const payload = {
@@ -64,9 +66,25 @@ async function submitWithFeeBumpAndWait(fundRelayer, signedXdr, network, maxFee,
                 await tracker.recordUsage(maxFee);
             }
             const rawReason = final.status_reason || 'Transaction failed';
-            console.error(`[channels] Transaction failed: ${rawReason}`);
+            const decoded = decodeTransactionResult(rawReason);
+            const labUrl = final.hash ? buildStellarLabTransactionUrl(network, final.hash) : null;
+            const contractType = context?.isLimited ? 'limited' : 'default';
+            const base = `[channels] Transaction failed: contractId=${context?.contractId ?? 'unknown'}, contractType=${contractType}, maxFee=${maxFee}`;
+            if (decoded && isTxInsufficientFeeError(decoded.resultCode)) {
+                const feeInfo = decoded.feeCharged != null
+                    ? `, requiredFee=${decoded.feeCharged}, shortfall=${decoded.feeCharged - maxFee}`
+                    : '';
+                console.error(`${base}, reason=txInsufficientFee${feeInfo}`);
+            }
+            else if (decoded) {
+                console.error(`${base}, reason=${decoded.resultCode}`);
+            }
+            else {
+                console.error(`${base}, reason=${rawReason}`);
+            }
             const reason = sanitizeReason(rawReason);
-            throw (0, relayer_sdk_1.pluginError)(reason, {
+            const reasonWithLab = labUrl ? `${reason}. Debug in Stellar Lab (click "Load Transaction"): ${labUrl}` : reason;
+            throw (0, relayer_sdk_1.pluginError)(reasonWithLab, {
                 code: 'ONCHAIN_FAILED',
                 status: constants_1.HTTP_STATUS.BAD_REQUEST,
                 details: {
@@ -74,6 +92,8 @@ async function submitWithFeeBumpAndWait(fundRelayer, signedXdr, network, maxFee,
                     reason,
                     id: final.id,
                     hash: final.hash ?? null,
+                    resultCode: decoded?.resultCode ?? null,
+                    labUrl: labUrl ? `Debug this failure in Stellar Lab (click "Load Transaction"): ${labUrl}` : null,
                 },
             });
         }
@@ -109,6 +129,67 @@ async function submitWithFeeBumpAndWait(fundRelayer, signedXdr, network, maxFee,
 function isSignTransactionResponseStellar(data) {
     return data !== null && typeof data === 'object' && 'signature' in data && 'signedXdr' in data;
 }
+/** Try to decode a transaction result XDR from the reason string */
+function decodeTransactionResult(reason) {
+    const fromReasonText = extractResultCodeFromReasonText(reason);
+    if (fromReasonText) {
+        return {
+            feeCharged: 0,
+            resultCode: fromReasonText,
+        };
+    }
+    try {
+        const match = reason.match(/([A-Za-z0-9+/=]{20,})$/);
+        if (!match)
+            return null;
+        const result = stellar_sdk_1.xdr.TransactionResult.fromXDR(match[1], 'base64');
+        const outerResultCode = String(result.result().switch().name);
+        let resultCode = outerResultCode;
+        // Unwrap fee bump inner failure to get the actual result code
+        if (outerResultCode === 'txFeeBumpInnerFailed') {
+            try {
+                const innerResult = result.result().innerResultPair().result();
+                const innerResultCode = String(innerResult.result().switch().name);
+                resultCode = `${outerResultCode}:${innerResultCode}`;
+            }
+            catch {
+                // keep outer result code if unwrap fails
+            }
+        }
+        return {
+            feeCharged: Number(result.feeCharged().toBigInt()),
+            resultCode,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function extractResultCodeFromReasonText(reason) {
+    const outerMatch = reason.match(/\bSpecific XDR reason:\s*([A-Za-z0-9_]+)\b/i);
+    if (!outerMatch?.[1])
+        return null;
+    const innerMatch = reason.match(/\bInner result:\s*([A-Za-z0-9_]+)\b/i);
+    return innerMatch?.[1] ? `${outerMatch[1]}:${innerMatch[1]}` : outerMatch[1];
+}
+/** Check if the result code indicates an insufficient fee error (case-insensitive). */
+function isTxInsufficientFeeError(resultCode) {
+    return resultCode?.toLowerCase() === 'txinsufficientfee';
+}
+function buildStellarLabTransactionUrl(network, txHash) {
+    const isMainnet = network === 'mainnet';
+    const networkId = isMainnet ? 'mainnet' : 'testnet';
+    const label = isMainnet ? 'Mainnet' : 'Testnet';
+    const horizonUrl = isMainnet ? 'https://horizon.stellar.org' : 'https://horizon-testnet.stellar.org';
+    const rpcUrl = isMainnet ? 'https://mainnet.sorobanrpc.com' : 'https://soroban-testnet.stellar.org';
+    const passphrase = isMainnet ? 'Public Global Stellar Network ; September 2015' : 'Test SDF Network ; September 2015';
+    // Stellar Lab expects protocol values encoded as https://// in query params.
+    // txHash is intentionally left unencoded because it is a hex string.
+    const horizonParam = horizonUrl.replace('https://', 'https:////');
+    const rpcParam = rpcUrl.replace('https://', 'https:////');
+    const passphraseParam = passphrase.replace(/ /g, '%20').replace(/;/g, '%3B');
+    return `https://lab.stellar.org/transaction/dashboard?$=network$id=${networkId}&label=${label}&horizonUrl=${horizonParam}&rpcUrl=${rpcParam}&passphrase=${passphraseParam}&txDashboard$transactionHash=${txHash};;`;
+}
 /** Strip provider wrapper text, extract last segment (e.g., "TxInsufficientBalance") */
 function sanitizeReason(reason) {
     const segments = reason.split(/:\s*/);

package/package.json

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