​

How to Add Transaction Preview to a MetaMask Snap Using Tenderly Simulation API

​

Project overview

​

Prerequisites

• MetaMask Flask browser extension installed
• Node.js (version 16 or later)
• Yarn (version 3)

​

Step 1: Setting up a MetaMask Snap project

yarn create @metamask/snap project-name

OR

npm create @metamask/snap project-name

yarn

yarn start

​

Setting the correct permissions

{
  // ...
  "initialPermissions": {
    "snap_dialog": {},
    "endowment:rpc": {
      "dapps": true,
      "snaps": false
    },
    "endowment:transaction-insight": {
      "allowTransactionOrigin": true
    },
    "endowment:network-access": {},
    "snap_manageState": {},
    "endowment:ethereum-provider": {
      "dapps": true,
      "snaps": true
    }
  }
}

​

Step 2: Generating Tenderly API access tokens

1. Log into Tenderly or create a free account here.
2. Go to the Authorization page and click on the Generate Access Token button.

​

Step 3: Writing the logic for the Snap

• Credentials Access (credentials-access.ts): Manages the Tenderly API authentication and access.
• Simulation (simulation.ts): The core logic for interacting with the Tenderly API to simulate transactions and fetch simulation results.
• Formatter (formatter.ts): Logic for parsing simulation results and formatting them in a user-friendly way in the MetaMask UI.

​

Credentials Access

• fetchCredentials(): This function retrieves the credentials of a Tenderly project. If no credentials are stored, it triggers handleUpdateTenderlyCredentials to request new ones.
• handleUpdateTenderlyCredentials(): This function handles the process of updating Tenderly project credentials. It gets new credentials by calling requestNewTenderlyCredentials and then saves them using the snap_manageState method with an 'update' operation.
• requestNewTenderlyCredentials(): This function requests new Tenderly credentials. It calls requestCredentials to receive the raw credentials data and verifies its correctness before returning an object with accountId, projectId, and accessToken.

​

Simulation

• simulate(): This is the main function that handles the simulation of a transaction. It fetches the API access credentials, submits the transaction data to the Tenderly Simulation API, and handles any errors returned by the API.

export async function simulate(
  transaction: { [key: string]: Json },
  transactionOrigin: string,
): Promise<Panel> {
  const credentials = await fetchCredentials(transactionOrigin);

  if (!credentials) {
    return panel([text('🚨 Tenderly access token updated. Please try again.')]);
  }

  const simulationResponse = await submitSimulation(transaction, credentials);
  const err = catchError(simulationResponse, credentials);

  return err || formatResponse(simulationResponse, credentials);
}

• submitSimulation(): This function sends a request to the API along with the transaction data to be simulated.

async function submitSimulation(
  transaction: { [key: string]: Json },
  credentials: TenderlyCredentials,
) {
  const chainId = await ethereum.request({ method: 'eth_chainId' });
  const response = await fetch(
    `https://api.tenderly.co/api/v1/account/${credentials.accountId}/project/${credentials.projectId}/simulate`,
    {
      method: 'POST',
      body: JSON.stringify({
        from: transaction.from,
        to: transaction.to,
        input: transaction.data,
        gas: hex2int(transaction.gas),
        value: hex2int(transaction.value),
        network_id: hex2int(chainId as string),
        save: true,
        save_if_fails: true,
        simulation_type: 'full',
        generate_access_list: false,
        source: 'tenderly-metamask-snap',
      }),
      headers: {
        'Content-Type': 'application/json',
        'X-Access-Key': credentials.accessToken,
      },
    },
  );

  const parsedResponse = await response.json();

  // Make the simulation publicly accessible
  if (parsedResponse?.simulation?.id) {
    await fetch(
      `https://api.tenderly.co/api/v1/account/${credentials.accountId}/project/${credentials.projectId}/simulations/${parsedResponse.simulation.id}/share`,
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-Access-Key': credentials.accessToken,
        },
      },
    );
  }

  return parsedResponse;
}

​

Formatter

• formatResponse(): This function receives the raw data and credentials of a Tenderly project simulation, calls the individual formatter functions for each relevant section (like balance changes, output value, asset changes, etc.), and returns a panel with all the formatted outputs.
• formatBalanceDiff(): This function generates a panel showing balance changes for each account involved in the transaction.
• formatOutputValue(): This function creates a panel that presents the output values of the transaction if any exist. It also decodes the output, if possible.
• formatAssetChanges(): This function formats a panel to show any asset changes, differentiating between ERC20, ERC721, and other changes.
• formatStorageChanges(): This function creates a panel that lists any changes to storage that occurred during the transaction. It uniquely formats addresses and nested data structures for clarity.
• formatEventLogs(): This function presents the event logs, if they exist, for each transaction. The logs are formatted for readability and include input values.
• formatCallTrace(): This function produces a formatted visual hierarchy of call traces, showing nested calls recursively.
• formatSimulationUrl(): This function returns a link to the full details of the simulation on the Tenderly Dashboard and a separate shareable link.

​

Step 4: Displaying simulation data in the MetaMask UI

• Successful transaction simulation with a predefined payload (successful ERC-20 transfer and NFT transfer)
• Failed transaction simulation with a predefined payload
• Custom transaction simulation with any payload

​

Successful simulation with a predefined payload

// packages/site/src/utils/snap.ts

export const sendTransaction = async (data: any): Promise<any> => {
  try {
    const [from] = (await window.ethereum.request({
      method: 'eth_requestAccounts',
    })) as string[];

    if (!from) {
      return Promise.reject(Error('Failed to get an account'));
    }

    // https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_sendtransaction
    return window.ethereum.request({
      method: 'eth_sendTransaction',
      params: [
        {
          ...data,
          from,
        },
      ],
    });
  } catch (e) {
    console.error(e);
    return e;
  }
};

// packages/snap/src/index.ts

export const onTransaction: OnTransactionHandler = async ({ transaction, transactionOrigin }) => {
  if (!isObject(transaction) || !hasProperty(transaction, 'to')) {
    return {
      content: {
        value: 'Unknown transaction type',
        type: NodeType.Text,
      },
    };
  }

  const simulationResponse = await simulate(transaction, transactionOrigin || '');

  return {
    content: {
      children: simulationResponse.children,
      type: NodeType.Panel,
    },
  };
};

export function formatSimulationUrl(data: any, credentials: TenderlyCredentials): Component[] {
  const simulationUrl = `https://dashboard.tenderly.co/${credentials.accountId}/${credentials.projectId}/simulator/${data.simulation?.id}`;
  const sharedSimulationUrl = `https://tdly.co/shared/simulation/${data.simulation?.id}`;

  return [
    heading('Tenderly Dashboard:'),
    text('See full simulation details in Tenderly.'),
    text(`**Status:** ${data.transaction?.status ? 'Success ✅' : 'Failed ❌'}`),
    copyable(`${simulationUrl}`),
    text('Share simulation details with others! 🤗'),
    copyable(`${sharedSimulationUrl}`),
  ];
}

​

Failed transaction with a predefined payload

​

Simulation with a custom payload

• from: DATA, 20 Bytes - The address the transaction is sent from.
• to: DATA, 20 Bytes - (optional when creating a new contract) The address the transaction is directed to.
• gas: QUANTITY - (optional, default: 90000) Integer of the gas provided for the transaction execution. It will return unused gas.
• gasPrice: QUANTITY - (optional, default: To-Be-Determined) Integer of the gasPrice used for each paid gas.
• value: QUANTITY - (optional) Integer of the value sent with this transaction.
• data: DATA - The compiled code of a contract OR the hash of the invoked method signature and encoded parameters.
• nonce: QUANTITY - (optional) Integer of a nonce. This allows you to overwrite your own pending transactions that use the same nonce.

​

Next steps