Skip to main content

​
Overview

The Tenderly CLI integrates seamlessly with Hardhat projects through the @tenderly/hardhat-tenderly plugin. This integration enables automatic tracking of contract deployments, making them available for verification and monitoring in the Tenderly Dashboard.
For complete contract verification workflows, refer to the Hardhat verification guide in the official Tenderly documentation.

​
Prerequisites

Before integrating Tenderly with your Hardhat project, ensure you have:
  • A Hardhat project initialized
  • Node.js and npm/yarn installed
  • Tenderly CLI installed and authenticated
  • An active Tenderly account

​
Installation

1

Install the Hardhat Tenderly Plugin

Install the @tenderly/hardhat-tenderly package as a development dependency:
npm install --save-dev @tenderly/hardhat-tenderly
2

Configure Your Hardhat Project

Add the plugin to your Hardhat configuration file:
Add this line to your hardhat.config.js:
hardhat.config.js
require("@tenderly/hardhat-tenderly");

module.exports = {
  solidity: "0.8.0",
  networks: {
    // Your network configurations
  }
};
3

Initialize Tenderly in Your Project

Run the Tenderly initialization command to connect your local project with your Tenderly Dashboard:
tenderly init
This command will:
  • Prompt you to select or create a Tenderly project
  • Generate a tenderly.yaml configuration file
  • Set up the project connection

​
Usage in Deployment Scripts

​
Tracking Single Contract Deployments

When deploying contracts, use the persistArtifacts method to track them in Tenderly:
scripts/deploy.js
const hre = require("hardhat");

async function main() {
  // Deploy your contract using ethers
  const Greeter = await ethers.getContractFactory("Greeter");
  const greeter = await Greeter.deploy("Hello, Hardhat!");

  await greeter.deployed();

  console.log("Greeter deployed to:", greeter.address);

  // Track the deployment in Tenderly
  await hre.tenderly.persistArtifacts({
    name: "Greeter",
    address: greeter.address,
  });

  console.log("Contract tracked in Tenderly");
}

main()
  .then(() => process.exit(0))
  .catch((error) => {
    console.error(error);
    process.exit(1);
  });

​
Tracking Multiple Contract Deployments

The persistArtifacts method accepts variadic parameters, allowing you to track multiple contracts in a single call:
scripts/deploy-multiple.js
const hre = require("hardhat");

async function main() {
  // Deploy multiple contracts
  const Greeter = await ethers.getContractFactory("Greeter");
  const greeter = await Greeter.deploy("Hello, Hardhat!");
  await greeter.deployed();

  const Token = await ethers.getContractFactory("Token");
  const token = await Token.deploy("MyToken", "MTK");
  await token.deployed();

  // Track all contracts at once
  const contracts = [
    {
      name: "Greeter",
      address: greeter.address
    },
    {
      name: "Token",
      address: token.address
    }
  ];

  await hre.tenderly.persistArtifacts(...contracts);

  console.log("All contracts tracked in Tenderly");
}

main()
  .then(() => process.exit(0))
  .catch((error) => {
    console.error(error);
    process.exit(1);
  });

​
Complete Integration Workflow

1

Compile Your Contracts

Compile your Solidity contracts to generate build artifacts:
npx hardhat compile
2

Start Local Node (Optional)

If testing locally, start a Hardhat node:
npx hardhat node --network hardhat
3

Deploy and Track Contracts

Run your deployment script with the persistArtifacts calls:
npx hardhat run scripts/deploy.js --network localhost
For testnet or mainnet deployments:
npx hardhat run scripts/deploy.js --network sepolia
4

Verify Contracts (Optional)

After deployment tracking creates the deployments directory, you can verify contracts:
tenderly contracts verify
Or verify specific networks:
tenderly contracts verify --networks 1,5,11155111

​
Project Structure

After integration, your project will include: 
my-hardhat-project/
├── contracts/
├── scripts/
├── deployments/          # Generated by persistArtifacts
│   ├── contract1.json
│   └── contract2.json
├── hardhat.config.js
├── tenderly.yaml         # Generated by tenderly init
└── package.json

​
Configuration File

The tenderly.yaml file created by tenderly init contains your project configuration:
tenderly.yaml
account_id: ""
project_slug: "my-project"

​
Best Practices

Always Call persistArtifacts

Ensure you call persistArtifacts after every contract deployment to maintain tracking consistency.

Deploy Before Verification

The deployments directory must exist before running verification commands. Always deploy first.

Network-Specific Deployments

Use the --network flag to track deployments on different networks separately.

Version Control

Commit tenderly.yaml to version control, but consider adding deployments/ to .gitignore for local testing.

​
Troubleshooting

​
No deployments Directory

If you see errors about missing deployment artifacts:
1

Verify Plugin Import

Ensure the plugin is imported in your hardhat.config.js or hardhat.config.ts.
2

Check persistArtifacts Calls

Confirm that hre.tenderly.persistArtifacts() is called in your deployment scripts.
3

Recompile and Redeploy

npx hardhat clean
npx hardhat compile
npx hardhat run scripts/deploy.js --network localhost

​
Verification Fails

If contract verification fails:
  • Ensure you’re authenticated: tenderly login
  • Verify the project is initialized: check for tenderly.yaml
  • Confirm contracts are deployed to supported networks
  • Check that build artifacts are up to date

​
Next Steps

Verify Contracts

Learn how to verify contracts on Tenderly after deployment.

Push Contracts

Explore pushing contracts to multiple projects and networks.

Monitor Transactions

Set up transaction monitoring and alerts in the Tenderly Dashboard.

Hardhat Plugin Docs

View the complete hardhat-tenderly plugin documentation.

Build docs developers (and LLMs) love

Get started for freeTalk to us