@openzeppelin/relayer-plugin-channels 0.6.0 → 0.8.0

package/dist/plugin/management.js

@@ -18,95 +18,78 @@ const config_1 = require("./config");
 const constants_1 = require("./constants");
 const fee_tracking_1 = require("./fee-tracking");
 function isManagementRequest(params) {
-    return Boolean(params &&
-        typeof params === "object" &&
-        params.management &&
-        typeof params.management === "object");
+    return Boolean(params && typeof params === 'object' && params.management && typeof params.management === 'object');
 }
 async function handleManagement(context) {
     const { kv, params } = context;
     const config = (0, config_1.loadConfig)();
     if (!config.adminSecret) {
-        throw (0, relayer_sdk_1.pluginError)("Management API disabled", {
-            code: "MANAGEMENT_DISABLED",
+        throw (0, relayer_sdk_1.pluginError)('Management API disabled', {
+            code: 'MANAGEMENT_DISABLED',
             status: constants_1.HTTP_STATUS.FORBIDDEN,
         });
     }
     const m = params?.management || {};
-    const provided = (m.adminSecret ?? "").toString();
+    const provided = (m.adminSecret ?? '').toString();
     if (!provided || provided !== config.adminSecret) {
-        throw (0, relayer_sdk_1.pluginError)("Unauthorized", {
-            code: "UNAUTHORIZED",
-            status: constants_1.HTTP_STATUS.UNAUTHORIZED,
-        });
+        throw (0, relayer_sdk_1.pluginError)('Unauthorized', { code: 'UNAUTHORIZED', status: constants_1.HTTP_STATUS.UNAUTHORIZED });
     }
-    const action = String(m.action || "");
+    const action = String(m.action || '');
     switch (action) {
-        case "listChannelAccounts":
+        case 'listChannelAccounts':
             return await listChannelAccounts(kv, config.network);
-        case "setChannelAccounts":
+        case 'setChannelAccounts':
             return await setChannelAccounts(kv, config.network, m);
-        case "getFeeUsage":
+        case 'getFeeUsage':
             return await getFeeUsage(kv, config.network, config.feeLimit, config.feeResetPeriodMs, m);
-        case "getFeeLimit":
+        case 'getFeeLimit':
             return await getFeeLimit(kv, config.network, config.feeLimit, m);
-        case "setFeeLimit":
+        case 'setFeeLimit':
             return await setFeeLimit(kv, config.network, m);
-        case "deleteFeeLimit":
+        case 'deleteFeeLimit':
             return await deleteFeeLimit(kv, config.network, m);
         default:
-            throw (0, relayer_sdk_1.pluginError)("Invalid management action", {
-                code: "INVALID_ACTION",
-                status: constants_1.HTTP_STATUS.BAD_REQUEST,
-            });
+            throw (0, relayer_sdk_1.pluginError)('Invalid management action', { code: 'INVALID_ACTION', status: constants_1.HTTP_STATUS.BAD_REQUEST });
     }
 }
 async function listChannelAccounts(kv, network) {
     const key = `${network}:channel:relayer-ids`;
     try {
         const doc = await kv.get?.(key);
-        const relayerIds = Array.isArray(doc?.relayerIds)
-            ? doc.relayerIds.map(normalizeId)
-            : [];
+        const relayerIds = Array.isArray(doc?.relayerIds) ? doc.relayerIds.map(normalizeId) : [];
         return { relayerIds };
     }
     catch (e) {
-        throw (0, relayer_sdk_1.pluginError)("KV error while listing channel accounts", {
-            code: "KV_ERROR",
+        throw (0, relayer_sdk_1.pluginError)('KV error while listing channel accounts', {
+            code: 'KV_ERROR',
             status: constants_1.HTTP_STATUS.INTERNAL_SERVER_ERROR,
         });
     }
 }
 async function getFeeUsage(kv, network, defaultLimit, resetPeriodMs, payload) {
     const apiKey = payload?.apiKey;
-    if (!apiKey || typeof apiKey !== "string") {
-        throw (0, relayer_sdk_1.pluginError)("Invalid payload: apiKey is required", {
-            code: "INVALID_PAYLOAD",
+    if (!apiKey || typeof apiKey !== 'string') {
+        throw (0, relayer_sdk_1.pluginError)('Invalid payload: apiKey is required', {
+            code: 'INVALID_PAYLOAD',
             status: constants_1.HTTP_STATUS.BAD_REQUEST,
         });
     }
     try {
-        const tracker = new fee_tracking_1.FeeTracker({
-            kv,
-            network,
-            apiKey,
-            defaultLimit,
-            resetPeriodMs,
-        });
+        const tracker = new fee_tracking_1.FeeTracker({ kv, network, apiKey, defaultLimit, resetPeriodMs });
         return await tracker.getUsageInfo();
     }
     catch (e) {
-        throw (0, relayer_sdk_1.pluginError)("KV error while reading fee usage", {
-            code: "KV_ERROR",
+        throw (0, relayer_sdk_1.pluginError)('KV error while reading fee usage', {
+            code: 'KV_ERROR',
             status: constants_1.HTTP_STATUS.INTERNAL_SERVER_ERROR,
         });
     }
 }
 async function getFeeLimit(kv, network, defaultLimit, payload) {
     const apiKey = payload?.apiKey;
-    if (!apiKey || typeof apiKey !== "string") {
-        throw (0, relayer_sdk_1.pluginError)("Invalid payload: apiKey is required", {
-            code: "INVALID_PAYLOAD",
+    if (!apiKey || typeof apiKey !== 'string') {
+        throw (0, relayer_sdk_1.pluginError)('Invalid payload: apiKey is required', {
+            code: 'INVALID_PAYLOAD',
             status: constants_1.HTTP_STATUS.BAD_REQUEST,
         });
     }
@@ -118,8 +101,8 @@ async function getFeeLimit(kv, network, defaultLimit, payload) {
         };
     }
     catch (e) {
-        throw (0, relayer_sdk_1.pluginError)("KV error while reading fee limit", {
-            code: "KV_ERROR",
+        throw (0, relayer_sdk_1.pluginError)('KV error while reading fee limit', {
+            code: 'KV_ERROR',
             status: constants_1.HTTP_STATUS.INTERNAL_SERVER_ERROR,
         });
     }
@@ -127,15 +110,15 @@ async function getFeeLimit(kv, network, defaultLimit, payload) {
 async function setFeeLimit(kv, network, payload) {
     const apiKey = payload?.apiKey;
     const limit = payload?.limit;
-    if (!apiKey || typeof apiKey !== "string") {
-        throw (0, relayer_sdk_1.pluginError)("Invalid payload: apiKey is required", {
-            code: "INVALID_PAYLOAD",
+    if (!apiKey || typeof apiKey !== 'string') {
+        throw (0, relayer_sdk_1.pluginError)('Invalid payload: apiKey is required', {
+            code: 'INVALID_PAYLOAD',
             status: constants_1.HTTP_STATUS.BAD_REQUEST,
         });
     }
-    if (typeof limit !== "number" || !Number.isFinite(limit) || limit < 0) {
-        throw (0, relayer_sdk_1.pluginError)("Invalid payload: limit must be a non-negative number", {
-            code: "INVALID_PAYLOAD",
+    if (typeof limit !== 'number' || !Number.isFinite(limit) || limit < 0) {
+        throw (0, relayer_sdk_1.pluginError)('Invalid payload: limit must be a non-negative number', {
+            code: 'INVALID_PAYLOAD',
             status: constants_1.HTTP_STATUS.BAD_REQUEST,
         });
     }
@@ -145,17 +128,17 @@ async function setFeeLimit(kv, network, payload) {
         return { ok: true, limit: Math.floor(limit) };
     }
     catch (e) {
-        throw (0, relayer_sdk_1.pluginError)("KV error while setting fee limit", {
-            code: "KV_ERROR",
+        throw (0, relayer_sdk_1.pluginError)('KV error while setting fee limit', {
+            code: 'KV_ERROR',
             status: constants_1.HTTP_STATUS.INTERNAL_SERVER_ERROR,
         });
     }
 }
 async function deleteFeeLimit(kv, network, payload) {
     const apiKey = payload?.apiKey;
-    if (!apiKey || typeof apiKey !== "string") {
-        throw (0, relayer_sdk_1.pluginError)("Invalid payload: apiKey is required", {
-            code: "INVALID_PAYLOAD",
+    if (!apiKey || typeof apiKey !== 'string') {
+        throw (0, relayer_sdk_1.pluginError)('Invalid payload: apiKey is required', {
+            code: 'INVALID_PAYLOAD',
             status: constants_1.HTTP_STATUS.BAD_REQUEST,
         });
     }
@@ -165,8 +148,8 @@ async function deleteFeeLimit(kv, network, payload) {
         return { ok: true };
     }
     catch (e) {
-        throw (0, relayer_sdk_1.pluginError)("KV error while deleting fee limit", {
-            code: "KV_ERROR",
+        throw (0, relayer_sdk_1.pluginError)('KV error while deleting fee limit', {
+            code: 'KV_ERROR',
             status: constants_1.HTTP_STATUS.INTERNAL_SERVER_ERROR,
         });
     }
@@ -174,8 +157,8 @@ async function deleteFeeLimit(kv, network, payload) {
 async function setChannelAccounts(kv, network, payload) {
     const incoming = payload?.relayerIds;
     if (!Array.isArray(incoming)) {
-        throw (0, relayer_sdk_1.pluginError)("Invalid payload: relayerIds must be an array", {
-            code: "INVALID_PAYLOAD",
+        throw (0, relayer_sdk_1.pluginError)('Invalid payload: relayerIds must be an array', {
+            code: 'INVALID_PAYLOAD',
             status: constants_1.HTTP_STATUS.BAD_REQUEST,
         });
     }
@@ -193,8 +176,8 @@ async function setChannelAccounts(kv, network, payload) {
         }
     }
     if (locked.length > 0) {
-        throw (0, relayer_sdk_1.pluginError)("Locked relayer IDs cannot be removed", {
-            code: "LOCKED_CONFLICT",
+        throw (0, relayer_sdk_1.pluginError)('Locked relayer IDs cannot be removed', {
+            code: 'LOCKED_CONFLICT',
             status: constants_1.HTTP_STATUS.CONFLICT,
             details: { locked },
         });
@@ -205,8 +188,8 @@ async function setChannelAccounts(kv, network, payload) {
         return { ok: true, appliedRelayerIds: relayerIds };
     }
     catch (e) {
-        throw (0, relayer_sdk_1.pluginError)("KV error while saving channel accounts", {
-            code: "KV_ERROR",
+        throw (0, relayer_sdk_1.pluginError)('KV error while saving channel accounts', {
+            code: 'KV_ERROR',
             status: constants_1.HTTP_STATUS.INTERNAL_SERVER_ERROR,
         });
     }
@@ -227,18 +210,13 @@ function unique(arr) {
 async function readStoredRelayerIds(kv, key) {
     try {
         const doc = await kv.get?.(key);
-        return Array.isArray(doc?.relayerIds)
-            ? doc.relayerIds.map(normalizeId)
-            : [];
+        return Array.isArray(doc?.relayerIds) ? doc.relayerIds.map(normalizeId) : [];
     }
     catch (error) {
-        throw (0, relayer_sdk_1.pluginError)("KV error while reading channel accounts", {
-            code: "KV_ERROR",
+        throw (0, relayer_sdk_1.pluginError)('KV error while reading channel accounts', {
+            code: 'KV_ERROR',
             status: constants_1.HTTP_STATUS.INTERNAL_SERVER_ERROR,
-            details: {
-                key,
-                message: error instanceof Error ? error.message : String(error),
-            },
+            details: { key, message: error instanceof Error ? error.message : String(error) },
         });
     }
 }
@@ -248,14 +226,10 @@ async function isRelayerIdLocked(kv, network, id) {
         return await kv.exists(key);
     }
     catch (error) {
-        throw (0, relayer_sdk_1.pluginError)("KV error while checking relayer lock", {
-            code: "KV_ERROR",
+        throw (0, relayer_sdk_1.pluginError)('KV error while checking relayer lock', {
+            code: 'KV_ERROR',
             status: constants_1.HTTP_STATUS.INTERNAL_SERVER_ERROR,
-            details: {
-                relayerId: id,
-                key,
-                message: error instanceof Error ? error.message : String(error),
-            },
+            details: { relayerId: id, key, message: error instanceof Error ? error.message : String(error) },
         });
     }
 }

package/dist/plugin/pool.d.ts

@@ -6,20 +6,25 @@
  * - Per-relayer locks with tokens: <network>:channel:in-use:<relayerId>
  * - Uses a short global mutex to make acquire atomic across workers.
  */
-import { PluginKVStore } from "@openzeppelin/relayer-sdk";
+import { PluginKVStore } from '@openzeppelin/relayer-sdk';
 export type PoolLock = {
     relayerId: string;
     token: string;
 };
+export type AcquireOptions = {
+    contractId?: string;
+    limitedContracts: Set<string>;
+    capacityRatio: number;
+};
 export declare class ChannelPool {
     private readonly network;
     private readonly globalLockKey;
     private readonly channelLockTtlSec;
     private readonly mutexTtlSec;
     private readonly kv;
-    constructor(network: "testnet" | "mainnet", kv: PluginKVStore, lockTtlSeconds: number);
+    constructor(network: 'testnet' | 'mainnet', kv: PluginKVStore, lockTtlSeconds: number);
     /** Acquire a relayerId with a token lock */
-    acquire(): Promise<PoolLock>;
+    acquire(options: AcquireOptions): Promise<PoolLock>;
     private withGlobalMutex;
     private tryLockAnyRelayer;
     /** Release the lock if we own it */

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;AAI5D,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;gBAGjC,OAAO,EAAE,SAAS,GAAG,SAAS,EAC9B,EAAE,EAAE,aAAa,EACjB,cAAc,EAAE,MAAM;IASxB,4CAA4C;IACtC,OAAO,IAAI,OAAO,CAAC,QAAQ,CAAC;YAuBpB,eAAe;YAQf,iBAAiB;IAwB/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;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"}

package/dist/plugin/pool.js

@@ -24,40 +24,43 @@ class ChannelPool {
         this.mutexTtlSec = constants_1.POOL.MUTEX_TTL_SECONDS;
     }
     /** Acquire a relayerId with a token lock */
-    async acquire() {
+    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());
+            const r = await this.withGlobalMutex(() => this.tryLockAnyRelayer(options));
             if (r === null) {
-                const jitter = constants_1.POOL.MUTEX_RETRY_MIN_MS +
-                    Math.floor(Math.random() *
-                        (constants_1.POOL.MUTEX_RETRY_MAX_MS - constants_1.POOL.MUTEX_RETRY_MIN_MS + 1));
+                const jitter = constants_1.POOL.MUTEX_RETRY_MIN_MS + Math.floor(Math.random() * (constants_1.POOL.MUTEX_RETRY_MAX_MS - constants_1.POOL.MUTEX_RETRY_MIN_MS + 1));
                 await sleep(jitter);
                 continue;
             }
             return r;
         }
-        throw (0, relayer_sdk_1.pluginError)("Too many transactions queued. Please try again later", {
-            code: "POOL_CAPACITY",
+        if (isLimited) {
+            console.log(`[channels] Contract ${options.contractId} limited to ${Math.round(options.capacityRatio * 100)}% capacity - no channels available`);
+        }
+        throw (0, relayer_sdk_1.pluginError)('Too many transactions queued. Please try again later', {
+            code: 'POOL_CAPACITY',
             status: constants_1.HTTP_STATUS.SERVICE_UNAVAILABLE,
         });
     }
     // Run a function under the short-lived global mutex; returns null if busy
     async withGlobalMutex(fn) {
-        return this.kv.withLock(this.globalLockKey, fn, {
-            ttlSec: this.mutexTtlSec,
-            onBusy: "skip",
-        });
+        return this.kv.withLock(this.globalLockKey, fn, { ttlSec: this.mutexTtlSec, onBusy: 'skip' });
     }
     // Inside the mutex: pick an available relayer and set its channel lock
-    async tryLockAnyRelayer() {
-        const ids = await this.getRelayerIdsFromKV();
+    async tryLockAnyRelayer(options) {
+        let ids = await this.getRelayerIdsFromKV();
         if (ids.length === 0) {
-            throw (0, relayer_sdk_1.pluginError)("No channel accounts configured. Use the management API to set channel accounts.", {
-                code: "NO_CHANNELS_CONFIGURED",
+            throw (0, relayer_sdk_1.pluginError)('No channel accounts configured. Use the management API to set channel accounts.', {
+                code: 'NO_CHANNELS_CONFIGURED',
                 status: constants_1.HTTP_STATUS.SERVICE_UNAVAILABLE,
             });
         }
+        // If contract is limited, filter to allowed subset
+        if (options.contractId && options.limitedContracts.has(options.contractId)) {
+            ids = filterChannelsForLimitedContract(ids, options.capacityRatio);
+        }
         shuffle(ids);
         for (const relayerId of ids) {
             const key = this.lockKey(relayerId);
@@ -113,10 +116,10 @@ function shuffle(arr) {
 }
 function randomToken() {
     try {
-        return crypto_1.default.randomBytes(16).toString("hex");
+        return crypto_1.default.randomBytes(16).toString('hex');
     }
     catch {
-        return (Math.random().toString(36).slice(2) + Math.random().toString(36).slice(2));
+        return Math.random().toString(36).slice(2) + Math.random().toString(36).slice(2);
     }
 }
 function normalizeId(id) {
@@ -125,3 +128,28 @@ function normalizeId(id) {
 function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }
+/**
+ * Simple hash for deterministic channel partitioning.
+ * Returns a number 0-99 for modulo-based filtering.
+ */
+function simpleHash(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        hash = (hash << 5) - hash + char;
+        hash = hash & hash; // Convert to 32-bit integer
+    }
+    return Math.abs(hash) % 100;
+}
+/**
+ * Filter channels for limited contracts using deterministic partitioning.
+ * Returns exactly floor(ratio * N) channels, sorted by hash for stability.
+ * Always returns at least 1 channel (min guarantee).
+ */
+function filterChannelsForLimitedContract(ids, ratio) {
+    const k = Math.max(1, Math.floor(ratio * ids.length));
+    return ids
+        .slice()
+        .sort((a, b) => simpleHash(a) - simpleHash(b) || a.localeCompare(b))
+        .slice(0, k);
+}

package/dist/plugin/simulation.d.ts

@@ -1,17 +1,45 @@
 /**
  * simulation.ts
  *
- * Build and simulate a Soroban transaction using a channel account as the source
- * and the fund account as the operation source. Returns an unsigned inner
- * transaction with sorobanData and correct fee set to the resource fee.
+ * Simulate a Soroban transaction once (using a throwaway source account) and
+ * reuse the result to both detect read-only calls and assemble the final
+ * transaction with the real channel account.  This avoids a redundant network
+ * round-trip to the RPC node.
  */
-import { Transaction, xdr } from "@stellar/stellar-sdk";
-import { Relayer } from "@openzeppelin/relayer-sdk";
+import { rpc, Transaction, xdr } from '@stellar/stellar-sdk';
+import { Relayer } from '@openzeppelin/relayer-sdk';
 export interface ChannelAccount {
     address: string;
     sequence: string;
 }
-export declare function simulateAndBuildWithChannel(func: xdr.HostFunction, auth: xdr.SorobanAuthorizationEntry[] | undefined, channel: ChannelAccount, _fundAddress: string, relayer: Relayer, networkPassphrase: string): Promise<Transaction>;
+export interface SimulationResult {
+    /** Whether the call is read-only (no auth + no read-write footprint). */
+    isReadOnly: boolean;
+    /** base64-encoded xdr.ScVal return value, present when isReadOnly is true. */
+    returnValue?: string;
+    /** Latest ledger at simulation time. */
+    latestLedger?: number;
+    /** Raw simulation response — used by buildWithChannel to assemble the tx. */
+    rawSimResult: rpc.Api.RawSimulateTransactionResponse;
+}
+/**
+ * Simulate a transaction to obtain the full simulation response and detect
+ * whether the call is read-only.
+ *
+ * Uses a throwaway source account (sequence "0") because `simulateTransaction`
+ * does not validate sequence numbers.  This lets us simulate before acquiring a
+ * channel pool slot.
+ *
+ * A call is read-only when:
+ * 1. Zero auth entries — no one needs to authorize anything
+ * 2. Zero read-write footprint entries — no ledger state will be modified
+ */
+export declare function simulateTransaction(func: xdr.HostFunction, auth: xdr.SorobanAuthorizationEntry[] | undefined, sourceAddress: string, relayer: Relayer, networkPassphrase: string): Promise<SimulationResult>;
+/**
+ * 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;
 /** 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;;;;;;GAMG;AAEH,OAAO,EAIL,WAAW,EAEX,GAAG,EACJ,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAGL,OAAO,EACR,MAAM,2BAA2B,CAAC;AAGnC,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,2BAA2B,CAC/C,IAAI,EAAE,GAAG,CAAC,YAAY,EACtB,IAAI,EAAE,GAAG,CAAC,yBAAyB,EAAE,GAAG,SAAS,EACjD,OAAO,EAAE,cAAc,EACvB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,OAAO,EAChB,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC,WAAW,CAAC,CAoGtB;AAED,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;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"}

package/dist/plugin/simulation.js

@@ -2,94 +2,131 @@
 /**
  * simulation.ts
  *
- * Build and simulate a Soroban transaction using a channel account as the source
- * and the fund account as the operation source. Returns an unsigned inner
- * transaction with sorobanData and correct fee set to the resource fee.
+ * Simulate a Soroban transaction once (using a throwaway source account) and
+ * reuse the result to both detect read-only calls and assemble the final
+ * transaction with the real channel account.  This avoids a redundant network
+ * round-trip to the RPC node.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.simulateAndBuildWithChannel = simulateAndBuildWithChannel;
+exports.simulateTransaction = simulateTransaction;
+exports.buildWithChannel = buildWithChannel;
 exports.parseSimulationError = parseSimulationError;
 const stellar_sdk_1 = require("@stellar/stellar-sdk");
 const relayer_sdk_1 = require("@openzeppelin/relayer-sdk");
 const constants_1 = require("./constants");
-async function simulateAndBuildWithChannel(func, auth, channel, _fundAddress, relayer, networkPassphrase) {
+/**
+ * Simulate a transaction to obtain the full simulation response and detect
+ * whether the call is read-only.
+ *
+ * Uses a throwaway source account (sequence "0") because `simulateTransaction`
+ * does not validate sequence numbers.  This lets us simulate before acquiring a
+ * channel pool slot.
+ *
+ * A call is read-only when:
+ * 1. Zero auth entries — no one needs to authorize anything
+ * 2. Zero read-write footprint entries — no ledger state will be modified
+ */
+async function simulateTransaction(func, auth, sourceAddress, relayer, networkPassphrase) {
     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, op source = fund)
-    const transaction = new stellar_sdk_1.TransactionBuilder(new stellar_sdk_1.Account(channel.address, channel.sequence), {
+    const transaction = new stellar_sdk_1.TransactionBuilder(new stellar_sdk_1.Account(sourceAddress, '0'), {
         fee: constants_1.SIMULATION.DEFAULT_FEE,
         networkPassphrase,
-        timebounds: {
-            minTime: constants_1.SIMULATION.MIN_TIME_BOUND,
-            maxTime: now + constants_1.SIMULATION.MAX_TIME_BOUND_OFFSET_SECONDS,
-        },
+        timebounds: { minTime: constants_1.SIMULATION.MIN_TIME_BOUND, maxTime: now + constants_1.SIMULATION.MAX_TIME_BOUND_OFFSET_SECONDS },
     })
-        .addOperation(stellar_sdk_1.Operation.invokeHostFunction({
-        func,
-        auth,
-        // No explicit source: default to transaction source (channel account)
-    }))
+        .addOperation(stellar_sdk_1.Operation.invokeHostFunction({ func, auth }))
         .build();
     let rpcResponse;
     try {
         rpcResponse = await relayer.rpc({
-            jsonrpc: "2.0",
+            jsonrpc: '2.0',
             id: Math.floor(Math.random() * 1e8).toString(),
-            method: "simulateTransaction",
-            params: {
-                transaction: transaction.toXDR(),
-            },
+            method: 'simulateTransaction',
+            params: { transaction: transaction.toXDR() },
         });
     }
     catch (err) {
-        throw (0, relayer_sdk_1.pluginError)("Simulation network request failed", {
-            code: "SIMULATION_NETWORK_ERROR",
+        throw (0, relayer_sdk_1.pluginError)('Simulation network request failed', {
+            code: 'SIMULATION_NETWORK_ERROR',
             status: constants_1.HTTP_STATUS.BAD_GATEWAY,
-            details: {
-                message: err instanceof Error ? err.message : String(err),
-            },
+            details: { message: err instanceof Error ? err.message : String(err) },
         });
     }
     if (rpcResponse.error) {
         const { code, message, description, data } = rpcResponse.error;
         console.error(`[channels] RPC error: code=${code}, message=${message}, detail=${description || data}`);
-        throw (0, relayer_sdk_1.pluginError)("Simulation RPC failed", {
-            code: "SIMULATION_RPC_FAILURE",
+        throw (0, relayer_sdk_1.pluginError)('Simulation RPC failed', {
+            code: 'SIMULATION_RPC_FAILURE',
             status: constants_1.HTTP_STATUS.BAD_GATEWAY,
-            details: { message: "RPC provider error" },
+            details: { message: 'RPC provider error' },
         });
     }
     const simResult = {
-        id: String(rpcResponse.id ?? "1"),
+        id: String(rpcResponse.id ?? '1'),
         ...rpcResponse.result,
     };
-    if ("error" in simResult && simResult.error) {
+    if ('error' in simResult && simResult.error) {
         console.error(`[channels] Simulation error: ${simResult.error}`);
-        throw (0, relayer_sdk_1.pluginError)("Simulation failed", {
-            code: "SIMULATION_FAILED",
+        throw (0, relayer_sdk_1.pluginError)('Simulation failed', {
+            code: 'SIMULATION_FAILED',
             status: constants_1.HTTP_STATUS.BAD_REQUEST,
             details: { error: parseSimulationError(simResult.error) },
         });
     }
+    // Read-only detection
+    const results = simResult.results;
+    const hasAuth = (results?.[0]?.auth?.length ?? 0) > 0;
+    let hasReadWrite = false;
+    if (simResult.transactionData) {
+        try {
+            const sorobanData = stellar_sdk_1.xdr.SorobanTransactionData.fromXDR(simResult.transactionData, 'base64');
+            hasReadWrite = sorobanData.resources().footprint().readWrite().length > 0;
+        }
+        catch {
+            // If we can't parse transactionData, treat as not read-only (safe fallback)
+            hasReadWrite = true;
+        }
+    }
+    const isReadOnly = !hasAuth && !hasReadWrite;
+    if (isReadOnly) {
+        console.log(`[channels] Read-only call detected via simulation`);
+    }
+    return {
+        isReadOnly,
+        returnValue: isReadOnly ? results?.[0]?.xdr : undefined,
+        latestLedger: simResult.latestLedger,
+        rawSimResult: simResult,
+    };
+}
+/**
+ * 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) {
+    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)
+    const transaction = new stellar_sdk_1.TransactionBuilder(new stellar_sdk_1.Account(channel.address, channel.sequence), {
+        fee: constants_1.SIMULATION.DEFAULT_FEE,
+        networkPassphrase,
+        timebounds: { minTime: constants_1.SIMULATION.MIN_TIME_BOUND, maxTime: now + constants_1.SIMULATION.MAX_TIME_BOUND_OFFSET_SECONDS },
+    })
+        .addOperation(stellar_sdk_1.Operation.invokeHostFunction({
+        func,
+        auth,
+        // No explicit source: default to transaction source (channel account)
+    }))
+        .build();
     try {
-        // Use SDK's assembleTransaction to apply simulation results
-        const prepared = stellar_sdk_1.rpc
-            .assembleTransaction(transaction, simResult)
-            .build();
-        const resourceFee = prepared
-            .toEnvelope()
-            .v1()
-            .tx()
-            .ext()
-            .sorobanData()
-            ?.resourceFee();
-        console.debug(`[channels] Simulation complete: resourceFee=${resourceFee}`);
+        // Use SDK's assembleTransaction to apply the cached simulation results
+        const prepared = stellar_sdk_1.rpc.assembleTransaction(transaction, simResult).build();
+        const resourceFee = prepared.toEnvelope().v1().tx().ext().sorobanData()?.resourceFee();
+        console.debug(`[channels] Assembly complete: resourceFee=${resourceFee}`);
         return prepared;
     }
     catch (err) {
         console.error(`[channels] Assembly error: ${err instanceof Error ? err.message : String(err)}`);
-        throw (0, relayer_sdk_1.pluginError)("Simulation failed", {
-            code: "SIMULATION_FAILED",
+        throw (0, relayer_sdk_1.pluginError)('Transaction assembly failed', {
+            code: 'ASSEMBLY_FAILED',
             status: constants_1.HTTP_STATUS.INTERNAL_SERVER_ERROR,
             details: {
                 message: err instanceof Error ? err.message : String(err),
@@ -99,7 +136,7 @@ async function simulateAndBuildWithChannel(func, auth, channel, _fundAddress, re
 }
 /** Extract human-readable message + error type from simulation error diagnostic events */
 function parseSimulationError(error) {
-    const firstLine = error.split("\n")[0]?.trim() || "Simulation failed";
+    const firstLine = error.split('\n')[0]?.trim() || 'Simulation failed';
     const errorType = firstLine.match(/Error\(([^)]+)\)/)?.[1];
     const arrayMatch = error.match(/data:\s*\["((?:[^"\\]|\\.)*)"/);
     if (arrayMatch?.[1] && arrayMatch[1].length > 3) {