@openzeppelin/relayer-plugin-channels 0.11.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

@@ -16,6 +16,7 @@ export interface ChannelAccountsConfig {
     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;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"}
+{"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,13 @@ 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)
@@ -132,6 +139,7 @@ function loadConfig() {
         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

@@ -20,6 +20,7 @@ export declare const CONFIG: {
     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;
@@ -36,6 +37,8 @@ export declare const SIMULATION: {
     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;;;;;;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"}
+{"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

@@ -25,6 +25,7 @@ exports.CONFIG = {
     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 = {
@@ -46,6 +47,8 @@ exports.SIMULATION = {
     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.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;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"}
+{"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

@@ -109,9 +109,9 @@ async function handleFuncAuthSubmit(func, auth, ctx) {
                 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);
+        const sequence = await (0, sequence_1.getSequence)(ctx.kv, ctx.network, channelRelayer, channelInfo.address, ctx.config.sequenceNumberCacheMaxAgeMs);
         // Assemble the transaction using the cached simulation result — no second RPC call
-        const built = (0, simulation_1.buildWithChannel)(func, auth, { address: channelInfo.address, sequence }, ctx.networkPassphrase, simulation.rawSimResult);
+        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);
@@ -212,7 +212,7 @@ async function channelAccounts(context) {
         acquireOptions,
         fees,
         tracker,
-        sequenceNumberCacheMaxAgeMs: config.sequenceNumberCacheMaxAgeMs,
+        config,
     };
     // 5. Branch by request type
     if (request.type === 'xdr') {

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;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"}
+{"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

@@ -104,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)
@@ -137,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';

package/package.json

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