simulateTransaction RPC method guide

interface SimulateTransactionParams {
  transaction: string; // The Stellar transaction to be simulated, serialized as a base64 string.
  resourceConfig?: {
    instructionLeeway: number; // Allow this many extra instructions when budgeting resources.
  };
}

async function simulateTransaction(transactionXDR) {
  const requestBody = {
    jsonrpc: "2.0",
    id: 8675309,
    method: "simulateTransaction",
    params: {
      transaction: transactionXDR,
      resourceConfig: {
        instructionLeeway: 50000,
      },
    },
  };

  const response = await fetch("https://soroban-testnet.stellar.org:443", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify(requestBody),
  });

  const result = await response.json();
  console.log(JSON.parse(result));
}

// Example XDR transaction envelope
// Replace the following placeholder with your actual XDR transaction envelope
const transactionXDR =
  "AAAAAgAAAAAg4dbAxsGAGICfBG3iT2cKGYQ6hK4sJWzZ6or1C5v6GAAAAGQAJsOiAAAAEQAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAGAAAAAAAAAABzAP+dP0PsNzYvFF1pv7a8RQXwH5eg3uZBbbWjE9PwAsAAAAJaW5jcmVtZW50AAAAAAAAAgAAABIAAAAAAAAAACDh1sDGwYAYgJ8EbeJPZwoZhDqEriwlbNnqivULm/oYAAAAAwAAAAMAAAAAAAAAAAAAAAA=";
// An example of where to get the XDR is from TransactionBuilder class from the sdk as shown in the next example.
simulateTransaction(transactionXDR);

import {
  Keypair,
  rpc as StellarRpc,
  scValToNative,
  TransactionBuilder,
  BASE_FEE,
  Networks,
  Operation,
} from "@stellar/stellar-sdk";

const FRIENDBOT_URL = "https://friendbot-testnet.stellar.org/";

const rpc_url = "https://soroban-testnet.stellar.org:443";

// Generate a new keypair for transaction authorization.
const keypair = Keypair.random();
const secret = keypair.secret();
const publicKey = keypair.publicKey();
console.log("publicKey:", publicKey);
// you need to fund the account.
await fetch(`https://friendbot-testnet.stellar.org/?addr=${publicKey}`).then(
  (res) => {
    console.log(`funded account: ${publicKey}`);
  },
);

// Initialize the rpcServer
const RpcServer = new StellarRpc.Server(rpc_url, { allowHttp: true });

// Load the account (getting the sequence number for the account and making an account object.)
const account = await RpcServer.getAccount(publicKey);

// Define the transaction
const transaction = new TransactionBuilder(account, {
  fee: BASE_FEE,
})
  .setNetworkPassphrase(Networks.TESTNET)
  .setTimeout(30)
  .addOperation(
    Operation.invokeContractFunction({
      function: "symbol",
      // the contract function and address need to be set by you.
      contract: "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
      args: [],
    }),
  )
  .build();
// If you want to get this as an XDR string directly, you would use `transaction.toXDR('base64')`

RpcServer.simulateTransaction(transaction).then((sim) => {
  console.log("cost:", sim.cost);
  console.log("result:", sim.result);
  // the result is a ScVal and so we can parse that to human readable output using the sdk's `scValToNative` function:
  console.log("humanReadable Result:", scValToNative(sim.result?.retval));
  console.log("error:", sim.error);
  console.log("latestLedger:", sim.latestLedger);
});

interface RestorePreamble {
  minResourceFee: string; // Absolute minimum resource fee to add when submitting the RestoreFootprint operation.
  transactionData: string; // The recommended Soroban Transaction Data to use when submitting the RestoreFootprint operation.
}

// Make sure to add the necessary imports:
import { Contract } from "@stellar/stellar-sdk/contract";
import {
  Account,
  Keypair,
  Operation,
  SorobanDataBuilder,
  rpc as StellarRpc,
  TimeoutInfinite,
  Transaction,
  TransactionBuilder,
  scValToNative,
  xdr,
} from "@stellar/stellar-sdk";
/**
 * Simulates a restoration transaction to determine if restoration is needed.
 * This function first checks the ledger entry for the given WASM hash. If the entry is found and has expired,
 * it attempts a restoration. If the entry hasn't expired yet but the TTL needs extension, it proceeds with TTL extension.
 * @param contract - The address of the contract to check
 * @param txParams - The transaction parameters including account and signer.
 * @returns A promise that resolves to a simulation response, indicating whether restoration or TTL extension is needed.
 */
export async function simulateRestorationIfNeeded(
  contract: ContractAddress,
  txParams: TxParams,
): Promise<
  StellarRpc.Api.SimulateTransactionRestoreResponse | string | undefined
> {
  try {
    const RpcServer = new StellarRpc.Server(
      "https://soroban-testnet.stellar.org",
      { allowHttp: true },
    );
    const account = await RpcServer.getAccount(txParams.account.accountId());
    const contract = new Contract(contract);
    const ledgerKey = contract.getFootprint();
    const response = await RpcServer.getLedgerEntries(ledgerKey);
    // Here we parse the response to make sure we got a response and that the liveUntilLedgerSeq parameter is there to make sure it's the response we want before continuing.
    if (
      response.entries &&
      response.entries.length > 0 &&
      response.entries[0].liveUntilLedgerSeq
    ) {
      const expirationLedger = response.entries[0].liveUntilLedgerSeq;
      const desiredLedgerSeq = response.latestLedger + 500000;
      // Be very aware of how many ledgers you want to extend it by.  It could quickly become extremely pricey in fees.
      let extendLedgers = desiredLedgerSeq - expirationLedger;
      if (extendLedgers < 10000) {
        extendLedgers = 10000;
      }
      console.log("Expiration:", expirationLedger);
      console.log("Desired TTL:", desiredLedgerSeq);
      const sorobanData = new SorobanDataBuilder()
        .setReadWrite([ledgerKey])
        .build();
      const restoreTx = new TransactionBuilder(
        account,
        txParams.txBuilderOptions,
      )
        .setSorobanData(sorobanData)
        .addOperation(Operation.restoreFootprint({})) // The actual restore operation
        .build();
      // Simulate a transaction with a restoration operation to check if it's necessary

      const restorationSimulation: StellarRpc.Api.SimulateTransactionResponse =
        await RpcServer.simulateTransaction(restoreTx);

      //check if restore is necessary. this code also checks if the simulation was successful.
      const restoreNeeded = StellarRpc.Api.isSimulationRestore(
        restorationSimulation,
      );
      console.log(`restoration needed: ${restoreNeeded}`);
      // Check if the simulation indicates a need for restoration
      if (restoreNeeded) {
        return restorationSimulation as StellarRpc.Api.SimulateTransactionRestoreResponse;
      } else {
        console.log("No restoration needed., bumping the ttl.");
        const account1 = await RpcServer.getAccount(
          txParams.account.accountId(),
        );

        const bumpTTLtx = new TransactionBuilder(
          account1,
          txParams.txBuilderOptions,
        )
          .setSorobanData(
            new SorobanDataBuilder().setReadOnly([ledgerKey]).build(),
          )
          .addOperation(
            Operation.extendFootprintTtl({
              extendTo: desiredLedgerSeq,
            }),
          ) // The actual TTL extension operation
          .build();
        const ttlSimResponse: StellarRpc.Api.SimulateTransactionResponse =
          await RpcServer.simulateTransaction(bumpTTLtx);
        const assembledTx = StellarRpc.assembleTransaction(
          bumpTTLtx,
          ttlSimResponse,
        ).build();
        const signedTx = new Transaction(
          await txParams.signerFunction(assembledTx.toXDR()),
          Networks.TESTNET,
        );
        // submit the assembled and signed transaction to bump it.
        try {
          const response = await sendTransaction(signedTx, (result) => {
            console.log(`bump ttl for contract result: ${result}`);
            return result;
          });
          return response;
        } catch (error) {
          console.error("Transaction submission failed with error:", error);
          throw error;
        }
      }
    } else {
      console.log("No ledger entry found for the given WASM hash.");
    }
  } catch (error) {
    console.error("Failed to simulate restoration:", error);
    throw error;
  }
}

/**
 * Handles the restoration of a Soroban contract.
 * @param {StellarRpc.Api.SimulateTransactionRestoreResponse} simResponse - The simulation response containing restoration information.
 * @param {TxParams} txParams - The transaction parameters.
 * @returns {Promise<void>} A promise that resolves when the restoration transaction has been submitted.
 */
export async function handleRestoration(
  simResponse: StellarRpc.Api.SimulateTransactionRestoreResponse,
  txParams: TxParams,
): Promise<void> {
  const RpcServer = new StellarRpc.Server(
    "https://soroban-testnet.stellar.org",
    { allowHttp: true },
  );
  const restorePreamble = simResponse.restorePreamble;
  console.log("Restoring for account:", txParams.account.accountId());
  const account = await RpcServer.getAccount(txParams.account.accountId());
  // Construct the transaction builder with the necessary parameters
  const restoreTx = new TransactionBuilder(account, {
    ...txParams.txBuilderOptions,
    fee: restorePreamble.minResourceFee, // Update fee based on the restoration requirement
  })
    .setSorobanData(restorePreamble.transactionData.build()) // Set Soroban Data from the simulation
    .addOperation(Operation.restoreFootprint({})) // Add the RestoreFootprint operation
    .build(); // Build the transaction

  const simulation: StellarRpc.Api.SimulateTransactionResponse =
    await RpcServer.simulateTransaction(restoreTx);
  const assembledTx = StellarRpc.assembleTransaction(
    restoreTx,
    simulation,
  ).build();

  const signedTx = new Transaction(
    await txParams.signerFunction(assembledTx.toXDR()),
    Networks.TESTNET,
  );

  console.log("Submitting restoration transaction");

  try {
    // Submit the transaction to the network
    const response = await RpcServer.sendTransaction(signedTx);
    console.log(
      "Restoration transaction submitted successfully:",
      response.hash,
    );
  } catch (error) {
    console.error("Failed to submit restoration transaction:", error);
    throw new Error("Restoration transaction failed");
  }
}