Truffle Integration - Tenderly CLI

Overview

Tenderly CLI provides native support for Truffle projects, automatically detecting your project structure and reading build artifacts from your Truffle compilation process. This enables seamless contract verification and deployment tracking.

Prerequisites

Before integrating Tenderly with your Truffle project:

Have a Truffle project initialized
Install Truffle globally or locally
Install and authenticate Tenderly CLI
Have an active Tenderly account

Supported Configuration Files

Tenderly CLI supports both Truffle configuration file naming conventions:

truffle-config.js (recommended, new format)
truffle.js (legacy format)

Tenderly CLI automatically detects which configuration file your project uses and reads the compiler settings, networks, and build directory path.

Installation

Install Truffle

Install Truffle globally if you haven’t already:

npm install -g truffle

Install Tenderly CLI

Install the Tenderly CLI for your operating system:

macOS
Linux
Windows

Using Homebrew:

brew tap tenderly/tenderly
brew install tenderly

Or using cURL:

curl https://raw.githubusercontent.com/Tenderly/tenderly-cli/master/scripts/install-macos.sh | sh

curl https://raw.githubusercontent.com/Tenderly/tenderly-cli/master/scripts/install-linux.sh | sh

Authenticate with Tenderly

tenderly login

You can authenticate using email or access key:

# Using email authentication
tenderly login --authentication-method email

# Using access key
tenderly login --authentication-method access-key --access-key YOUR_KEY

Initialize Your Project

Navigate to your Truffle project directory and initialize Tenderly:

cd /path/to/your/truffle/project
tenderly init

This creates a tenderly.yaml configuration file in your project root.

Truffle Configuration

Your truffle-config.js should contain standard Truffle configuration:

truffle-config.js

module.exports = {
  networks: {
    development: {
      host: "127.0.0.1",
      port: 8545,
      network_id: "*"
    },
    sepolia: {
      provider: () => new HDWalletProvider(
        process.env.MNEMONIC,
        `https://sepolia.infura.io/v3/${process.env.INFURA_KEY}`
      ),
      network_id: 11155111,
      gas: 4500000,
      gasPrice: 10000000000
    },
    mainnet: {
      provider: () => new HDWalletProvider(
        process.env.MNEMONIC,
        `https://mainnet.infura.io/v3/${process.env.INFURA_KEY}`
      ),
      network_id: 1,
      gas: 4500000,
      gasPrice: 10000000000
    }
  },

  compilers: {
    solc: {
      version: "0.8.19",
      settings: {
        optimizer: {
          enabled: true,
          runs: 200
        }
      }
    }
  }
};

Tenderly CLI reads your compiler configuration directly from this file to ensure verification uses the exact same settings.

Contract Deployment Workflow

Write Your Contracts

Create your Solidity contracts in the contracts/ directory:

contracts/MyToken.sol

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

import "@openzeppelin/contracts/token/ERC20/ERC20.sol";

contract MyToken is ERC20 {
    constructor(uint256 initialSupply) ERC20("MyToken", "MTK") {
        _mint(msg.sender, initialSupply);
    }
}

Create Migration Scripts

Add migration scripts in the migrations/ directory:

migrations/2_deploy_contracts.js

const MyToken = artifacts.require("MyToken");

module.exports = function (deployer) {
  // Deploy with 1 million tokens
  deployer.deploy(MyToken, web3.utils.toWei("1000000", "ether"));
};

Compile Contracts

Compile your Solidity contracts:

truffle compile

This generates build artifacts in the build/contracts/ directory.

Deploy to Network

Deploy your contracts to your target network:

# Deploy to local development network
truffle migrate --network development

# Deploy to testnet
truffle migrate --network sepolia

# Deploy to mainnet
truffle migrate --network mainnet

Verify on Tenderly

After deployment, verify your contracts on Tenderly:

tenderly contracts verify

Verify specific networks only:

# Verify only mainnet and sepolia
tenderly contracts verify --networks 1,11155111

Tenderly Configuration

The tenderly.yaml file stores your project configuration:

Basic Configuration

tenderly.yaml

account_id: "your-account-id"
project_slug: "my-truffle-project"

Multi-Project Configuration

You can push contracts to multiple Tenderly projects by configuring the projects map:

tenderly.yaml

projects:
  my-mainnet-project:
    networks:
      - "1"      # Ethereum Mainnet
      - "137"    # Polygon Mainnet
  
  my-testnet-project:
    networks:
      - "11155111"  # Sepolia
      - "80001"     # Mumbai
  
  shared-project:
    # Empty networks means all detected networks
  
  company-account/shared-team-project:
    # Use full identifier for shared projects
    networks:
      - "1"

When using multi-project configuration, remove the project_slug property and use the projects map instead.

Verification Workflow

Standard Verification

# Verify all contracts on all networks
tenderly contracts verify

Network-Specific Verification

# Verify specific network IDs
tenderly contracts verify --networks 1,5,137

Verification Process

When you run verification, Tenderly CLI:

Detects your Truffle configuration file
Reads compiler settings and optimization parameters
Scans the build/contracts/ directory for artifacts
Extracts deployment addresses from network configurations
Uploads contract source code and bytecode
Verifies contracts on the Tenderly platform

Project Structure

A typical Truffle project integrated with Tenderly:

my-truffle-project/
├── build/
│   └── contracts/           # Build artifacts (generated)
│       ├── MyToken.json
│       └── Migrations.json
├── contracts/               # Solidity source files
│   ├── MyToken.sol
│   └── Migrations.sol
├── migrations/              # Deployment scripts
│   ├── 1_initial_migration.js
│   └── 2_deploy_contracts.js
├── test/                    # Contract tests
├── truffle-config.js        # Truffle configuration
└── tenderly.yaml            # Tenderly configuration

Using with Alternative Providers

Tenderly CLI can work alongside other Truffle deployment providers. The CLI automatically detects Truffle projects based on:

Presence of truffle-config.js or truffle.js
Standard Truffle directory structure
Build artifacts in build/contracts/

Advanced Usage

Tagging Deployments

Tag your contract deployments for better organization:

tenderly contracts push --tag v1.0.0

Project-Specific Push

When using multi-project configuration, push to a specific project:

tenderly contracts push --project-slug my-mainnet-project

Custom Project Directory

Specify a custom project directory:

tenderly contracts verify --project-dir /path/to/truffle/project

Global Configuration Flags

All Tenderly commands support these global flags:

# Enable debug logging
tenderly contracts verify --debug

# Output in JSON format
tenderly contracts verify --output json

# Use custom config file names
tenderly contracts verify --project-config custom-tenderly

Best Practices

Compile Before Verification

Always run truffle compile before verifying to ensure build artifacts are up to date.

Network ID Consistency

Use standard network IDs in your Truffle config to ensure proper verification.

Version Control

Commit tenderly.yaml but consider adding build/ to .gitignore.

Multi-Network Testing

Test verification on testnets before deploying to mainnet.

Troubleshooting

Configuration Not Found

If Tenderly can’t find your Truffle configuration:

Check Configuration File

Ensure you have either truffle-config.js or truffle.js in your project root.

Verify Project Structure

Confirm your project has the standard Truffle directory structure.

Use Project Directory Flag

Explicitly specify the project directory:

tenderly contracts verify --project-dir ./

No Contracts Found

If verification reports no contracts:

Run truffle compile to generate build artifacts
Check that build/contracts/ contains JSON files
Verify contracts are deployed (have network entries in artifacts)

Network Not Supported

If you see network errors:

Verify the network ID is supported by Tenderly
Check that contracts are deployed to that network
Ensure network configuration in truffle-config.js is correct

Next Steps

Push Contracts

Learn how to push contracts to public networks.

Initialize Projects

Explore advanced project initialization options.

Monitor Contracts

Set up monitoring and alerts in the Tenderly Dashboard.

Truffle Documentation

View the official Truffle documentation.

Getting Started

Core Commands

Contract Management

Actions

DevNets

Extensions

Configuration

Guides

​Overview

​Prerequisites

​Supported Configuration Files

​Installation

​Truffle Configuration

​Contract Deployment Workflow

​Tenderly Configuration

​Basic Configuration

​Multi-Project Configuration

​Verification Workflow

​Standard Verification

​Network-Specific Verification

​Verification Process

​Project Structure

​Using with Alternative Providers

​Advanced Usage

​Tagging Deployments

​Project-Specific Push

​Custom Project Directory

​Global Configuration Flags

​Best Practices

Compile Before Verification

Network ID Consistency

Version Control

Multi-Network Testing

​Troubleshooting

​Configuration Not Found

​No Contracts Found

​Network Not Supported

​Next Steps

Push Contracts

Initialize Projects

Monitor Contracts

Truffle Documentation

Build docs developers (and LLMs) love

Overview

Prerequisites

Supported Configuration Files

Installation

Truffle Configuration

Contract Deployment Workflow

Tenderly Configuration

Basic Configuration

Multi-Project Configuration

Verification Workflow

Standard Verification

Network-Specific Verification

Verification Process

Project Structure

Using with Alternative Providers

Advanced Usage

Tagging Deployments

Project-Specific Push

Custom Project Directory

Global Configuration Flags

Best Practices

Troubleshooting

Configuration Not Found

No Contracts Found

Network Not Supported

Next Steps