@openzeppelin/relayer-plugin-channels 0.10.0 → 0.12.0

package/README.md

@@ -233,6 +233,12 @@ export CONTRACT_CAPACITY_RATIO=0.8        # Max ratio of pool for limited contra
 # 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)
+
+# Sequence number cache (optional)
+export SEQUENCE_NUMBER_CACHE_MAX_AGE_MS=120000  # Max age of cached sequence numbers in ms (default: 120000)
+
+# Auth expiry validation (optional)
+export MIN_SIGNATURE_EXPIRATION_LEDGER_BUFFER=2  # Minimum ledger margin for auth entry signatureExpirationLedger (default: 2)
 ```
 
 Your Relayer should now contain:
@@ -940,25 +946,67 @@ Plugin error example:
 - **Key**: `<network>:api-key-limit:<apiKey>`
 - **Value**: `{ limit: number }` (custom fee limit in stroops)
 
+### Sequence Number Cache
+
+- **Key**: `<network>:channel:seq:<address>`
+- **Value**: `{ sequence: string, storedAt: number }` (sequence number and cache timestamp in ms)
+
 ## Error Codes
 
+### Configuration
+
 - `CONFIG_MISSING`: Missing required environment variable
+- `CONFIG_INVALID`: Invalid configuration value (e.g., invalid contract address in `LIMITED_CONTRACTS`)
 - `UNSUPPORTED_NETWORK`: Invalid network type
+
+### Request Validation
+
 - `INVALID_PARAMS`: Invalid request parameters
 - `INVALID_XDR`: Failed to parse XDR
 - `INVALID_ENVELOPE_TYPE`: Not a regular transaction envelope
+- `INVALID_UNSIGNED_XDR`: Unsigned XDR must contain exactly one `invokeHostFunction` operation
 - `INVALID_TIME_BOUNDS`: TimeBounds too far in the future
+- `TIMEBOUNDS_EXPIRED`: Transaction timebounds have expired
+- `TIMEBOUNDS_TOO_FAR`: Transaction timebounds maxTime too far in the future
+- `FEE_MISMATCH`: Fee mismatch in signed transaction
+- `INVALID_OPERATION_SOURCE`: Operation source does not match transaction source
+
+### Pool & Channel
+
 - `NO_CHANNELS_CONFIGURED`: No channel accounts have been configured via management API
 - `POOL_CAPACITY`: All channel accounts in use
 - `RELAYER_UNAVAILABLE`: Relayer not found
+- `FAILED_TO_GET_SEQUENCE`: Failed to fetch channel account sequence number
+- `ACCOUNT_NOT_FOUND`: Channel account not found on the ledger
+
+### Simulation & Assembly
+
 - `SIMULATION_FAILED`: Transaction simulation failed
+- `SIMULATION_NETWORK_ERROR`: Simulation network request failed (HTTP 502)
+- `SIMULATION_RPC_FAILURE`: Simulation RPC provider error (HTTP 502)
+- `SIMULATION_SIGNED_AUTH_VALIDATION_FAILED`: Signed auth entry validation failed in enforce-mode simulation
+- `AUTH_EXPIRY_TOO_SHORT`: Auth entry `signatureExpirationLedger` too close to current ledger
+- `ASSEMBLY_FAILED`: Transaction assembly failed
+
+### Submission
+
+- `INVALID_SIGNATURE`: Invalid channel signature response
 - `ONCHAIN_FAILED`: Transaction failed on-chain
 - `WAIT_TIMEOUT`: Transaction wait timeout
+
+### Fee Tracking
+
+- `API_KEY_REQUIRED`: API key header missing when `FEE_LIMIT` is configured
+- `FEE_LIMIT_EXCEEDED`: API key has exceeded its fee limit (HTTP 429)
+
+### Management
+
 - `MANAGEMENT_DISABLED`: Management API not enabled
 - `UNAUTHORIZED`: Invalid admin secret
+- `INVALID_ACTION`: Invalid management action
+- `INVALID_PAYLOAD`: Invalid management request payload
 - `LOCKED_CONFLICT`: Cannot remove locked channel accounts
-- `API_KEY_REQUIRED`: API key header missing when `FEE_LIMIT` is configured (HTTP 403)
-- `FEE_LIMIT_EXCEEDED`: API key has exceeded its fee limit (HTTP 429)
+- `KV_ERROR`: KV store operation failed
 
 ## License
 

package/dist/plugin/config.d.ts

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

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

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/plugin/config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAUH,MAAM,WAAW,qBAAqB;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,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;CAC7B;AA4FD;;GAEG;AACH,wBAAgB,UAAU,IAAI,qBAAqB,CAsBlD;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;IACpC,kCAAkC,EAAE,MAAM,CAAC;CAC5C;AA0GD;;GAEG;AACH,wBAAgB,UAAU,IAAI,qBAAqB,CAwBlD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,CAE3E"}

package/dist/plugin/config.js

@@ -91,6 +91,20 @@ function parseInclusionFee(envVar, defaultValue) {
         return defaultValue;
     return Math.floor(n);
 }
+function parseMinAuthExpiryLedgerBuffer() {
+    const raw = process.env.MIN_SIGNATURE_EXPIRATION_LEDGER_BUFFER;
+    if (!raw)
+        return constants_1.CONFIG.DEFAULT_MIN_SIGNATURE_EXPIRATION_LEDGER_BUFFER;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : constants_1.CONFIG.DEFAULT_MIN_SIGNATURE_EXPIRATION_LEDGER_BUFFER;
+}
+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)
@@ -124,6 +138,8 @@ function loadConfig() {
         contractCapacityRatio: parseContractCapacityRatio(),
         inclusionFeeDefault: parseInclusionFee('INCLUSION_FEE_DEFAULT', DEFAULT_INCLUSION_FEE_DEFAULT),
         inclusionFeeLimited: parseInclusionFee('INCLUSION_FEE_LIMITED', DEFAULT_INCLUSION_FEE_LIMITED),
+        sequenceNumberCacheMaxAgeMs: parseSequenceNumberCacheMaxAge(),
+        minSignatureExpirationLedgerBuffer: parseMinAuthExpiryLedgerBuffer(),
     };
 }
 /**

package/dist/plugin/constants.d.ts

@@ -19,6 +19,8 @@ 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;
+    readonly DEFAULT_MIN_SIGNATURE_EXPIRATION_LEDGER_BUFFER: 2;
 };
 export declare const POOL: {
     readonly MUTEX_TTL_SECONDS: 1;
@@ -34,6 +36,9 @@ 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";
+    /** 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;
 };
 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;;;;;;;CAOT,CAAC;AAGX,eAAO,MAAM,IAAI;;;;;CAOP,CAAC;AAGX,eAAO,MAAM,IAAI;;CAEP,CAAC;AAGX,eAAO,MAAM,UAAU;;;;;;IAMrB,uLAAuL;;CAE/K,CAAC;AAGX,eAAO,MAAM,OAAO;;;CAGV,CAAC;AAEX,eAAO,MAAM,GAAG;;CAGN,CAAC"}

package/dist/plugin/constants.js

@@ -24,6 +24,8 @@ 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,
+    DEFAULT_MIN_SIGNATURE_EXPIRATION_LEDGER_BUFFER: 2,
 };
 // Pool Constants
 exports.POOL = {
@@ -44,6 +46,9 @@ exports.SIMULATION = {
     MIN_TIME_BOUND: 0,
     MAX_TIME_BOUND_OFFSET_SECONDS: 120,
     MAX_FUTURE_TIME_BOUND_SECONDS: 120,
+    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,
 };
 // Polling for transactionWait
 exports.POLLING = {

package/dist/plugin/handler.d.ts

@@ -5,7 +5,6 @@
  * Orchestrates the transaction processing pipeline using channel accounts with fee bumping.
  */
 import { PluginContext } from '@openzeppelin/relayer-sdk';
-import type { Relayer } from '@openzeppelin/relayer-sdk';
 import { Transaction, xdr } from '@stellar/stellar-sdk';
 /**
  * Extracts func and auth from an unsigned Soroban transaction.
@@ -15,7 +14,6 @@ export declare function extractFuncAuthFromUnsignedXdr(tx: Transaction): {
     func: xdr.HostFunction;
     auth: xdr.SorobanAuthorizationEntry[];
 } | null;
-export declare function getAccountSequence(relayer: Relayer, address: string): Promise<string>;
 /**
  * Main plugin handler exported for OpenZeppelin Relayer
  */

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,EAAa,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAQpE,OAAO,EAAW,WAAW,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAC;AAWjE;;;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;AAKD,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAsH3F;AA2PD;;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;AAsPD;;GAEG;AACH,wBAAsB,OAAO,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,CAElE"}

package/dist/plugin/handler.js

@@ -7,7 +7,6 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.extractFuncAuthFromUnsignedXdr = extractFuncAuthFromUnsignedXdr;
-exports.getAccountSequence = getAccountSequence;
 exports.handler = handler;
 const relayer_sdk_1 = require("@openzeppelin/relayer-sdk");
 const pool_1 = require("./pool");
@@ -21,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;
@@ -45,122 +45,8 @@ function extractFuncAuthFromUnsignedXdr(tx) {
         auth: invokeHostFn.auth(),
     };
 }
-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) },
-        });
-    }
-}
-async function handleXdrSubmit(xdrStr, fundRelayer, fundAddress, network, networkPassphrase, api, pool, acquireOptions, fees, 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);
@@ -177,22 +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, fees, 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, fees);
+    const maxFee = (0, fee_1.calculateMaxFee)(validated, ctx.acquireOptions.limitedContracts, ctx.fees);
     const contractId = (0, fee_1.getContractIdFromTransaction)(validated);
-    await tracker?.checkBudget(maxFee);
+    await ctx.tracker?.checkBudget(maxFee);
     const submitContext = {
         contractId,
-        isLimited: contractId ? acquireOptions.limitedContracts.has(contractId) : false,
+        isLimited: contractId ? ctx.acquireOptions.limitedContracts.has(contractId) : false,
     };
-    return (0, submit_1.submitWithFeeBumpAndWait)(fundRelayer, validated.toXDR(), network, maxFee, api, tracker, submitContext);
+    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, fees, 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 {
@@ -205,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) {
@@ -223,22 +109,35 @@ async function handleFuncAuthSubmit(func, auth, api, pool, fundRelayer, fundAddr
                 details: { network_type: channelInfo.network_type, relayerId: poolLock.relayerId },
             });
         }
-        const sequence = await getAccountSequence(channelRelayer, channelInfo.address);
+        const sequence = await (0, sequence_1.getSequence)(ctx.kv, ctx.network, channelRelayer, channelInfo.address, ctx.config.sequenceNumberCacheMaxAgeMs);
         // Assemble the transaction using the cached simulation result — no second RPC call
-        const built = (0, simulation_1.buildWithChannel)(func, auth, { address: channelInfo.address, sequence }, 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, fees);
+        const built = (0, simulation_1.buildWithChannel)(func, auth, { address: channelInfo.address, sequence }, ctx.networkPassphrase, simulation.rawSimResult, ctx.config.minSignatureExpirationLedgerBuffer);
+        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 tracker?.checkBudget(maxFee);
+        await ctx.tracker?.checkBudget(maxFee);
         const submitContext = {
             contractId,
-            isLimited: contractId ? acquireOptions.limitedContracts.has(contractId) : false,
+            isLimited: contractId ? ctx.acquireOptions.limitedContracts.has(contractId) : false,
         };
-        return await (0, submit_1.submitWithFeeBumpAndWait)(fundRelayer, signedTx.toXDR(), network, maxFee, api, tracker, submitContext);
+        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);
         }
     }
 }
@@ -301,16 +200,30 @@ async function channelAccounts(context) {
         inclusionFeeDefault: config.inclusionFeeDefault,
         inclusionFeeLimited: config.inclusionFeeLimited,
     };
-    // 4. Branch by request type
+    // 4. Build pipeline context
+    const ctx = {
+        api,
+        kv,
+        pool,
+        fundRelayer: fundRelayer,
+        fundAddress: fundInfo.address,
+        network: config.network,
+        networkPassphrase,
+        acquireOptions,
+        fees,
+        tracker,
+        config,
+    };
+    // 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, fees, 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, fees, tracker);
+    return await handleFuncAuthSubmit(request.func, request.auth, { ...ctx, acquireOptions: funcAcquireOptions });
 }
 /**
  * Main plugin handler exported for OpenZeppelin Relayer

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

@@ -39,7 +39,7 @@ export declare function simulateTransaction(func: xdr.HostFunction, auth: xdr.So
  * Build and assemble a transaction using a channel account and an already-
  * obtained simulation result.  No additional network calls are made.
  */
-export declare function buildWithChannel(func: xdr.HostFunction, auth: xdr.SorobanAuthorizationEntry[] | undefined, channel: ChannelAccount, networkPassphrase: string, simResult: rpc.Api.RawSimulateTransactionResponse): Transaction;
+export declare function buildWithChannel(func: xdr.HostFunction, auth: xdr.SorobanAuthorizationEntry[] | undefined, channel: ChannelAccount, networkPassphrase: string, simResult: rpc.Api.RawSimulateTransactionResponse, minSignatureExpirationLedgerBuffer?: number): Transaction;
 /** Extract human-readable message + error type from simulation error diagnostic events */
 export declare function parseSimulationError(error: string): string;
 //# sourceMappingURL=simulation.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"simulation.d.ts","sourceRoot":"","sources":["../../src/plugin/simulation.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAsB,GAAG,EAAE,WAAW,EAAsB,GAAG,EAAE,MAAM,sBAAsB,CAAC;AACrG,OAAO,EAAgD,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAGlG,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,UAAU,EAAE,OAAO,CAAC;IACpB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,YAAY,EAAE,GAAG,CAAC,GAAG,CAAC,8BAA8B,CAAC;CACtD;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,EACjD,kCAAkC,GAAE,MAA0D,GAC7F,WAAW,CA4Cb;AA4CD,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
@@ -101,7 +104,12 @@ async function simulateTransaction(func, auth, sourceAddress, relayer, networkPa
  * Build and assemble a transaction using a channel account and an already-
  * obtained simulation result.  No additional network calls are made.
  */
-function buildWithChannel(func, auth, channel, networkPassphrase, simResult) {
+function buildWithChannel(func, auth, channel, networkPassphrase, simResult, minSignatureExpirationLedgerBuffer = constants_1.SIMULATION.MIN_SIGNATURE_EXPIRATION_LEDGER_BUFFER) {
+    // Fail fast: reject auth entries whose signatureExpirationLedger is too close
+    // to latestLedger before doing any assembly work.
+    if (simResult.latestLedger) {
+        validateAuthExpiry(auth, simResult.latestLedger, minSignatureExpirationLedgerBuffer);
+    }
     const now = Math.floor(Date.now() / 1000);
     console.debug(`[channels] Building tx: channel=${channel.address}, seq=${channel.sequence}, auth_count=${auth?.length ?? 0}`);
     // Build inner transaction (source = channel)
@@ -134,6 +142,36 @@ function buildWithChannel(func, auth, channel, networkPassphrase, simResult) {
         });
     }
 }
+/**
+ * Reject transactions where any address-credentialed auth entry has a
+ * signatureExpirationLedger too close to the current ledger.  This catches
+ * tight expiries early instead of failing on-chain with "signature has expired".
+ */
+function validateAuthExpiry(authEntries, latestLedger, minBuffer) {
+    if (!authEntries?.length)
+        return;
+    for (const entry of authEntries) {
+        const creds = entry.credentials();
+        if (creds.switch() !== stellar_sdk_1.xdr.SorobanCredentialsType.sorobanCredentialsAddress()) {
+            continue;
+        }
+        const expiry = creds.address().signatureExpirationLedger();
+        const margin = expiry - latestLedger;
+        if (margin < minBuffer) {
+            console.error(`[channels] Auth entry signatureExpirationLedger too close to current ledger (expires in ${margin} ledgers, minimum ${minBuffer} required)`);
+            throw (0, relayer_sdk_1.pluginError)(`Auth entry signatureExpirationLedger too close to current ledger (expires in ${margin} ledgers, minimum ${minBuffer} required)`, {
+                code: 'AUTH_EXPIRY_TOO_SHORT',
+                status: constants_1.HTTP_STATUS.BAD_REQUEST,
+                details: {
+                    signatureExpirationLedger: expiry,
+                    latestLedger,
+                    margin,
+                    minimumRequired: minBuffer,
+                },
+            });
+        }
+    }
+}
 /** Extract human-readable message + error type from simulation error diagnostic events */
 function parseSimulationError(error) {
     const firstLine = error.split('\n')[0]?.trim() || 'Simulation failed';
@@ -148,3 +186,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

@@ -11,6 +11,10 @@ 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
@@ -23,10 +27,9 @@ export declare function signWithChannelAndFund(transaction: Transaction, channel
  */
 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): {
-    feeCharged: number;
-    resultCode: string;
-} | null;
+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,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;;;;;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,CA6ElC;AASD,oEAAoE;AACpE,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAwBzG;AAED,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAOrD"}
+{"version":3,"file":"submit.d.ts","sourceRoot":"","sources":["../../src/plugin/submit.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAO,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAEL,OAAO,EAGP,SAAS,EACV,MAAM,2BAA2B,CAAC;AAEnC,OAAO,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

@@ -8,6 +8,7 @@ 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");
@@ -66,10 +67,14 @@ async function submitWithFeeBumpAndWait(fundRelayer, signedXdr, network, maxFee,
             }
             const rawReason = final.status_reason || 'Transaction failed';
             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?.resultCode === 'txInsufficientFee') {
-                console.error(`${base}, reason=txInsufficientFee, requiredFee=${decoded.feeCharged}, shortfall=${decoded.feeCharged - 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}`);
@@ -78,7 +83,8 @@ async function submitWithFeeBumpAndWait(fundRelayer, signedXdr, network, maxFee,
                 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: {
@@ -86,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,
                 },
             });
         }
@@ -123,17 +131,26 @@ function isSignTransactionResponseStellar(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');
-        let resultCode = result.result().switch().name;
+        const outerResultCode = String(result.result().switch().name);
+        let resultCode = outerResultCode;
         // Unwrap fee bump inner failure to get the actual result code
-        if (resultCode === 'txFeeBumpInnerFailed') {
+        if (outerResultCode === 'txFeeBumpInnerFailed') {
             try {
                 const innerResult = result.result().innerResultPair().result();
-                resultCode = innerResult.result().switch().name;
+                const innerResultCode = String(innerResult.result().switch().name);
+                resultCode = `${outerResultCode}:${innerResultCode}`;
             }
             catch {
                 // keep outer result code if unwrap fails
@@ -148,6 +165,31 @@ function decodeTransactionResult(reason) {
         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.10.0",
+  "version": "0.12.0",
   "description": "OpenZeppelin Relayer Plugin for Stellar Channel Accounts",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",