Merge pull request #236 from Yusufolosun/fix/optimize-cross-contract-call-overhead

fix: optimize factory deploy cross-contract call overhead

Author: adams813

README.md

@@ -1169,6 +1169,17 @@ Builds a Stellar transaction for deploying a Soroban smart contract. Supports tw
 
 **Input:**
 
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `mode` | `string` | Yes | `direct` (built-in deployer) or `factory` (via factory contract) |
+| `source_account` | `string` | Yes | Stellar public key (`G...`) that will pay fees |
+| `wasm_hash` | `string` | No | 64-char hex WASM hash. **Required for direct mode.** |
+| `salt` | `string` | No | 64-char hex salt for deterministic address. Random if omitted. |
+| `factory_contract_id` | `string` | No | Factory contract ID (`C...`). **Required for factory mode.** |
+| `deploy_function` | `string` | No | Factory deploy function name. Default: `deploy` |
+| `deploy_args` | `array` | No | Typed SCVal arguments: `[{ type?: 'symbol'\|'string'\|'u32'\|'i32'\|'u64'\|'i64'\|'u128'\|'i128'\|'bool'\|'address'\|'bytes'\|'void', value: any }]` |
+| `optimize_cross_contract_call` | `boolean` | No | Factory mode only. If `true`, simulates and assembles the transaction to minimize cross-contract resource overhead before returning XDR. Default: `false` |
+| `network` | `string` | No | Override network: `mainnet`, `testnet`, `futurenet`, `custom` |
 | Parameter             | Type     | Required | Description                                                                                                                                          |
 | --------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `mode`                | `string` | Yes      | `direct` (built-in deployer) or `factory` (via factory contract)                                                                                     |
@@ -1198,6 +1209,11 @@ Builds a Stellar transaction for deploying a Soroban smart contract. Supports tw
 {
   "mode": "factory",
   "transaction_xdr": "AAAAAgAAAAE...",
+  "optimization": {
+    "min_resource_fee": "2500",
+    "cpu_instructions": "345",
+    "memory_bytes": "678"
+  },
   "network": "testnet",
   "source_account": "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5"
 }

src/index.ts

@@ -299,6 +299,8 @@ class PulsarServer {
             'Fetch the ABI/interface spec of a deployed Soroban contract. Returns decoded function signatures, parameter types, and emitted event schemas.',
           description:
             'Fetch the ABI/interface spec of a deployed Soroban contract. Returns decoded function signatures, parameter types, and emitted event schemas.',
+          description:
+            'Fetch the ABI/interface spec of a deployed Soroban contract. Returns decoded function signatures, parameter types, and emitted event schemas.',
           inputSchema: {
             type: 'object',
           description:
@@ -606,6 +608,11 @@ class PulsarServer {
                 description:
                   "Arguments for factory deploy function as typed SCVal objects. Each item: { type?: 'symbol'|'string'|'u32'|'i32'|'u64'|'i64'|'u128'|'i128'|'bool'|'address'|'bytes'|'void', value: any }",
               },
+              optimize_cross_contract_call: {
+                type: 'boolean',
+                default: false,
+                description:
+                  'Factory mode only. Simulate and assemble the transaction to minimize cross-contract call resource overhead before returning XDR.',
               network: {
               address: {
                 type: 'string',
@@ -1729,7 +1736,10 @@ class PulsarServer {
           case 'fetch_contract_spec': {
             const parsed = fetchContractSpecSchema.safeParse(args);
             if (!parsed.success) {
-              throw new PulsarValidationError(`Invalid input for fetch_contract_spec`, parsed.error.format());
+              throw new PulsarValidationError(
+                `Invalid input for fetch_contract_spec`,
+                parsed.error.format()
+              );
             }
             const result = await fetchContractSpec(parsed.data);
             return { content: [{ type: "text", text: JSON.stringify(result) }] };

src/schemas/tools.ts

@@ -336,6 +336,7 @@ export type ComputeVestingScheduleInput = z.infer<typeof ComputeVestingScheduleI
  * - factory_contract_id: Factory contract ID (required for factory)
  * - deploy_function: Factory deploy function name (default: 'deploy')
  * - deploy_args: Array of typed SCVal arguments for factory deploy function
+ * - optimize_cross_contract_call: Optional simulation+assembly for factory mode
  * - network: Optional network override
  */
 export const DeployContractInputSchema = z.object({
@@ -384,6 +385,12 @@ export const DeployContractInputSchema = z.object({
     )
     .optional()
     .describe('Arguments for factory deploy function as typed SCVal objects'),
+  optimize_cross_contract_call: z
+    .boolean()
+    .optional()
+    .describe(
+      'If true in factory mode, simulates and assembles the transaction to minimize cross-contract resource overhead'
+    ),
   network: NetworkSchema.optional(),
 });
 

src/tools/deploy_contract.ts

@@ -6,12 +6,14 @@ import {
   Address,
   hash,
   StrKey,
+  SorobanRpc,
   xdr,
   nativeToScVal,
   Networks,
 } from '@stellar/stellar-sdk';
 
 import { getHorizonServer } from '../services/horizon.js';
+import { getSorobanServer } from '../services/soroban-rpc.js';
 import { config } from '../config.js';
 import { DeployContractInputSchema } from '../schemas/tools.js';
 import type { McpToolHandler } from '../types.js';
@@ -22,6 +24,11 @@ export interface DeployContractOutput {
   mode: 'direct' | 'factory';
   transaction_xdr: string;
   predicted_contract_id?: string;
+  optimization?: {
+    min_resource_fee: string;
+    cpu_instructions: string;
+    memory_bytes: string;
+  };
   network: string;
   source_account: string;
 }
@@ -112,13 +119,17 @@ export const deployContract: McpToolHandler<typeof DeployContractInputSchema> =
     logger.debug({ account: sourceAccount, network }, 'Loading source account for deployment');
     account = await horizonServer.loadAccount(sourceAccount);
   } catch (err: unknown) {
+    const status = (err as { response?: { status?: number } })?.response?.status;
+    if (status === 404) {
     const error = err as { response?: { status?: number }; message?: string };
     if (error.response?.status === 404) {
       throw new PulsarNetworkError(
         `Source account ${sourceAccount} not found. Fund the account before deploying.`,
         { status: 404, account_id: sourceAccount }
       );
     }
+    const message = err instanceof Error ? err.message : String(err);
+    throw new PulsarNetworkError(`Failed to load source account: ${message}`, {
     throw new PulsarNetworkError(`Failed to load source account: ${error.message || String(err)}`, {
       originalError: err,
     });
@@ -188,18 +199,82 @@ export const deployContract: McpToolHandler<typeof DeployContractInputSchema> =
   // ------------------------------------------------------------------
   // 3. Build the transaction
   // ------------------------------------------------------------------
-  const tx = new TransactionBuilder(account, {
+  let tx = new TransactionBuilder(account, {
     fee: (100_000).toString(),
     networkPassphrase,
   })
     .addOperation(operation)
     .setTimeout(30)
     .build();
 
+  let optimization:
+    | {
+        min_resource_fee: string;
+        cpu_instructions: string;
+        memory_bytes: string;
+      }
+    | undefined;
+
+  if (data.mode === 'factory' && (data.optimize_cross_contract_call ?? false)) {
+    const sorobanServer = getSorobanServer(network);
+
+    let simulation;
+    try {
+      simulation = await sorobanServer.simulateTransaction(tx);
+    } catch (err) {
+      throw new PulsarNetworkError(
+        'Failed to simulate factory deployment for cross-contract optimization',
+        { originalError: err }
+      );
+    }
+
+    if (SorobanRpc.Api.isSimulationError(simulation)) {
+      throw new PulsarNetworkError('Failed to optimize factory deployment: simulation error', {
+        simulation_error: simulation.error,
+      });
+    }
+
+    const apiWithRestore = SorobanRpc.Api as unknown as {
+      isSimulationRestore?: (result: unknown) => boolean;
+      isSimulationRestoreNeeded?: (result: unknown) => boolean;
+    };
+
+    if (
+      apiWithRestore.isSimulationRestore?.(simulation) ||
+      apiWithRestore.isSimulationRestoreNeeded?.(simulation)
+    ) {
+      throw new PulsarNetworkError(
+        'Failed to optimize factory deployment: ledger restoration is required',
+        { restore_needed: true }
+      );
+    }
+
+    if (!SorobanRpc.Api.isSimulationSuccess(simulation)) {
+      throw new PulsarNetworkError(
+        'Failed to optimize factory deployment: unexpected simulation response'
+      );
+    }
+
+    try {
+      tx = await sorobanServer.prepareTransaction(tx);
+    } catch (err) {
+      throw new PulsarNetworkError('Failed to assemble optimized factory deployment transaction', {
+        originalError: err,
+      });
+    }
+
+    optimization = {
+      min_resource_fee: simulation.minResourceFee ?? '0',
+      cpu_instructions: simulation.cost?.cpuInsns ?? '0',
+      memory_bytes: simulation.cost?.memBytes ?? '0',
+    };
+  }
+
   return {
     mode: data.mode,
     transaction_xdr: tx.toXDR(),
     predicted_contract_id: predictedContractId,
+    optimization,
     network,
     source_account: sourceAccount,
   };

tests/unit/deploy_contract.test.ts

@@ -1,15 +1,21 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { TransactionBuilder, Networks, Keypair } from '@stellar/stellar-sdk';
+import { TransactionBuilder, Networks, Keypair, SorobanRpc } from '@stellar/stellar-sdk';
 
 import { deployContract } from '../../src/tools/deploy_contract.js';
 import { getHorizonServer } from '../../src/services/horizon.js';
+import { getSorobanServer } from '../../src/services/soroban-rpc.js';
 
 vi.mock('../../src/services/horizon.js', () => ({
   getHorizonServer: vi.fn(),
 }));
 
+vi.mock('../../src/services/soroban-rpc.js', () => ({
+  getSorobanServer: vi.fn(),
+}));
+
 describe('deployContract', () => {
   let mockServer: any;
+  let mockSorobanServer: any;
 
   const SOURCE_ACCOUNT = Keypair.random().publicKey();
   const WASM_HASH = 'a'.repeat(64);
@@ -20,7 +26,12 @@ describe('deployContract', () => {
     mockServer = {
       loadAccount: vi.fn(),
     };
+    mockSorobanServer = {
+      simulateTransaction: vi.fn(),
+      prepareTransaction: vi.fn(),
+    };
     vi.mocked(getHorizonServer).mockReturnValue(mockServer);
+    vi.mocked(getSorobanServer).mockReturnValue(mockSorobanServer);
   });
 
   function mockAccount(sequence = '123456789') {
@@ -234,6 +245,53 @@ describe('deployContract', () => {
       expect(result.transaction_xdr).toBeDefined();
     });
 
+    it('optimizes factory deployment when optimize_cross_contract_call is true', async () => {
+      mockAccount();
+
+      mockSorobanServer.simulateTransaction.mockResolvedValue({
+        cost: { cpuInsns: '345', memBytes: '678' },
+        minResourceFee: '2500',
+      } as any);
+
+      mockSorobanServer.prepareTransaction.mockResolvedValue({
+        toXDR: () => 'optimized-xdr',
+      });
+
+      vi.spyOn(SorobanRpc.Api, 'isSimulationSuccess').mockReturnValue(true);
+      vi.spyOn(SorobanRpc.Api, 'isSimulationError').mockReturnValue(false);
+
+      const result = (await deployContract({
+        mode: 'factory',
+        source_account: SOURCE_ACCOUNT,
+        factory_contract_id: FACTORY_CONTRACT_ID,
+        optimize_cross_contract_call: true,
+      })) as any;
+
+      expect(mockSorobanServer.simulateTransaction).toHaveBeenCalledOnce();
+      expect(mockSorobanServer.prepareTransaction).toHaveBeenCalledOnce();
+      expect(result.transaction_xdr).toBe('optimized-xdr');
+      expect(result.optimization).toEqual({
+        min_resource_fee: '2500',
+        cpu_instructions: '345',
+        memory_bytes: '678',
+      });
+    });
+
+    it('returns a clear error when optimization simulation fails', async () => {
+      mockAccount();
+
+      mockSorobanServer.simulateTransaction.mockRejectedValue(new Error('RPC unavailable'));
+
+      await expect(
+        deployContract({
+          mode: 'factory',
+          source_account: SOURCE_ACCOUNT,
+          factory_contract_id: FACTORY_CONTRACT_ID,
+          optimize_cross_contract_call: true,
+        })
+      ).rejects.toThrow('Failed to simulate factory deployment for cross-contract optimization');
+    });
+
     it('rejects missing factory_contract_id in factory mode', async () => {
       mockAccount();