Skip to content

Commit a1d0138

Browse files
ElaNejElaNej
authored
update README.md
1 parent 3517be6 commit a1d0138

File tree

1 file changed

+298
-0
lines changed

1 file changed

+298
-0
lines changed

‎README.md

Lines changed: 298 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,298 @@
1+
![npm (tag)](https://img.shields.io/npm/v/@tenderly/hardhat-tenderly/latest?color=23C197&labelColor=060e18&style=for-the-badge)
2+
3+
# @tenderly/hardhat-tenderly
4+
5+
[Hardhat](http://hardhat.org) plugin for integration with [Tenderly](https://tenderly.co).
6+
7+
This repo represents the hardhat-tenderly plugin. With its functionalities, you can verify contracts on the Tenderly platform.
8+
Verification represents an entry point into Tenderly's functionalities. With verified contracts, you can use various features like [debugger](https://docs.tenderly.co/debugger/how-to-use-tenderly-debugger), [simulations and forks](https://docs.tenderly.co/simulations-and-forks/intro-to-simulations) or [devnets](https://docs.tenderly.co/devnets/intro-to-devnets).
9+
This repo will make it possible to verify your contracts with ease, so you can focus on building your dapp.
10+
11+
You can read about hardhat-tenderly's verification features in detail [here](https://docs.tenderly.co/monitoring/smart-contract-verification/verifying-contracts-using-the-tenderly-hardhat-plugin).
12+
13+
Here's a brief description. There are three modes you can configure to verify your contracts and these are called **Verification Modes**:
14+
- **Private verification mode** - Only you or people who share the project with you may see the source code of the contract and interact with it.
15+
- **Public verification mode** - Anyone can see the source code of the contract and interact with it.
16+
- **Fork verification mode** - Verify deployed contract on a <b>tenderly fork</b>.
17+
- **Devnet verification mode** - Verify deployed contract on a <b>tenderly devnet</b>.
18+
19+
> [!IMPORTANT]
20+
> The Tenderly Hardhat plugin verifies contracts publicly by default, unless you [configure it to use the private mode.](https://docs.tenderly.co/monitoring/smart-contract-verification/verifying-contracts-using-the-tenderly-hardhat-plugin/private-contract-verification)
21+
22+
Also, there are three ways of how you can actually do the verification based on the mode you configured in verification modes. These ways are called **Verification Approaches**:
23+
- **Automatic verification approach** - The plugin will automatically verify your contracts after each deployment.
24+
- **Manual verification approach** - You will have to manually verify the contracts via plugin method calls.
25+
- **Task verification approach** - Verify your contracts via `tenderly:verify` hardhat task.
26+
27+
You can also verify proxy contracts supported by `@openzeppelin/hardhat-upgrades` plugin. For more information on that, you can check out the chapter about [Proxy Contract Verification](#proxy-contract-verification).
28+
29+
## Installation
30+
31+
```bash
32+
npm install --save-dev @tenderly/hardhat-tenderly
33+
```
34+
35+
And add the following statement to your `hardhat.config.js` or `hardhat.config.ts`:
36+
37+
```js
38+
const tdly = require("@tenderly/hardhat-tenderly");
39+
tdly.setup();
40+
```
41+
42+
Or, if you are using typescript:
43+
44+
```ts
45+
import * as tdly from "@tenderly/hardhat-tenderly";
46+
tdly.setup();
47+
```
48+
49+
### Installing tenderly cli
50+
51+
In order to use all the plugin's functionalities, it will be necessary to have a `tenderly config` file.
52+
This file will be automatically created after you install `tenderly cli` and log in with `tenderly login`.
53+
54+
To install `tenderly cli`, follow the installation steps at [tenderly-cli](https://github.com/Tenderly/tenderly-cli). After that, run:
55+
56+
```bash
57+
tenderly login --authentication-method access-key --access-key {your_access_key} --force
58+
```
59+
60+
Access key can be found under **Settings->Authorization->Generate new access key** in your [Tenderly dashboard](https://dashboard.tenderly.co).
61+
62+
63+
# Verification Modes
64+
This section explains three modes you can configure to verify your contracts.
65+
66+
First, you need to add the `tenderly` field inside the `HardhatConfig` structure in `hardhat.config.ts`:
67+
```ts
68+
module.exports = {
69+
solidity: {
70+
...
71+
},
72+
networks: {
73+
...
74+
},
75+
tenderly: {
76+
username: "tenderly", // tenderly username (or organization name)
77+
project: "project", // project name
78+
privateVerification: false // if true, contracts will be verified privately, if false, contracts will be verified publicly
79+
}
80+
}
81+
```
82+
> **Warning**
83+
>: Username can be your own and the username of the organization. Which one, it depends on who is the owner of the project you are trying to verify your contracts on. If the project belongs to the organization you are part of, It should be filled with organization username, otherwise your own username.
84+
> The quickest and most secure way to make sure to which party the project belongs to is to look at the url of the particular project. You will see something like:
85+
https://dashboard.tenderly.co/Tenderly/project/contracts.
86+
You can take the username and project from there. In this case the username is Tenderly and the project is project.
87+
88+
### Private verification mode
89+
In order to configure private verification mode, set `privateVerification` to `true` inside the `tenderly` field inside `hardhat.config.ts`.
90+
Also, the `--network` flag must NOT be set to `tenderly` or `devnet` when running `npx hardhat run` command, or fork/devnet verification mode will be configured.
91+
### Public verification mode
92+
In order to configure public verification mode, set `privateVerification` to `false` inside the `tenderly` field inside `hardhat.config.ts`.
93+
Also, the `--network` flag must NOT be set to `tenderly` or `devnet` when running `npx hardhat run` command, or fork/devnet verification mode will be configured.
94+
### Fork verification mode
95+
In order to configure fork verification mode, set `privateVerification` to `false` inside the `tenderly` field inside `hardhat.config.ts`.
96+
To configure the fork you want to verify the contracts on, set the `tenderly` network inside `HardhatConfig` structure in `hardhat.config.ts`:
97+
```ts
98+
module.exports = {
99+
solidity: {
100+
...
101+
},
102+
networks: {
103+
... // other networks
104+
sepolia: {
105+
url: "https://sepolia.gateway.tenderly.co/...",
106+
accounts: ["0x..."],
107+
},
108+
...,
109+
// -------- CONFIGURE FORK HERE -----------
110+
tenderly: {
111+
url: "https://rpc.tenderly.co/fork/...",
112+
accounts: ["0x..."]
113+
}
114+
// ----------------------------------------
115+
},
116+
tenderly: { // as before
117+
username: "tenderly",
118+
project: "project",
119+
privateVerification: false
120+
}
121+
}
122+
```
123+
Parameters:
124+
- `url` is the fork rpc url that you can find on the dashboard in the info tab of the particular fork you want to verify your contracts on.
125+
- `accounts` field should be your private key or mnemonic as with every other network.
126+
> **Pro Tip**:
127+
> You can set multiple tenderly networks in the `networks` property, just name them differently and assign different urls. For example:
128+
>```ts
129+
>networks: {
130+
> my_tenderly_fork: {
131+
> url: "https://rpc.tenderly.co/fork/...",
132+
> },
133+
> my_tenderly_devnet: {
134+
> url: "https://rpc.vnet.tenderly.co/devnet/...",
135+
> }
136+
>}
137+
>```
138+
139+
### Devnet verification mode
140+
In order to configure devnet verification mode, set `privateVerification` to `false` inside the `tenderly` field inside `hardhat.config.ts`.
141+
To configure the devnet you want to verify the contracts on, set the `tenderly` network inside `HardhatConfig` structure in `hardhat.config.ts`:
142+
```ts
143+
module.exports = {
144+
solidity: {
145+
...
146+
},
147+
networks: {
148+
... // other networks
149+
sepolia: {
150+
url: "https://sepolia.gateway.tenderly.co/...",
151+
accounts: ["0x..."],
152+
},
153+
...,
154+
// -------- CONFIGURE DEVNET HERE -----------
155+
tenderly: {
156+
url: "https://rpc.vnet.tenderly.co/devnet/...",
157+
accounts: ["0x..."]
158+
}
159+
// ----------------------------------------
160+
},
161+
tenderly: { // as before
162+
username: "tenderly",
163+
project: "project",
164+
privateVerification: false
165+
}
166+
}
167+
```
168+
Parameters:
169+
- `url` is the devnet rpc url that you can copy on the dashboard in the Copy RPC link section of the particular devnet you want to verify your contracts on.
170+
- `accounts` field should be your private key or mnemonic as with every other network.
171+
> **Pro Tip**:
172+
> You can set multiple tenderly networks in the `networks` property, just name them differently and assign different urls. For example:
173+
>```ts
174+
>networks: {
175+
> my_tenderly_fork: {
176+
> url: "https://rpc.tenderly.co/fork/...",
177+
> },
178+
> my_tenderly_devnet: {
179+
> url: "https://rpc.vnet.tenderly.co/devnet/...",
180+
> }
181+
>}
182+
>```
183+
184+
# Verification Approaches
185+
This section explains the steps you take to actually verify your contracts.
186+
You can verify your contracts **Automatically**, **Manually** or via **Task**.
187+
188+
You can check the [examples/contract-verification](https://github.com/Tenderly/hardhat-tenderly/tree/master/examples/contract-verification) part of the repo to get more insight into how to use these verification approaches.
189+
190+
For every of these three approaches, you can configure the mode of verification. Either **Private**, **Public**, **Fork** or **Devnet** verification mode. See how to configure these modes in **Verification Modes** section above.
191+
192+
## Automatic verification approach (Recommended)
193+
This approach will automatically verify the contract after deployment. Precisely, when you call the `waitForDeployment()` function as in:
194+
```typescript
195+
import { ethers } from "hardhat";
196+
197+
const greeter = await ethers.deployContract("Greeter", ["Hello, Hardhat!"]);
198+
199+
await greeter.waitForDeployment();
200+
```
201+
The plugin will wait for the contract to be deployed and verify it afterwards.
202+
203+
If you wish to turn off automatic verification, you can do it in `hardhat.config.ts`:
204+
205+
```typescript
206+
import * as tdly from "@tenderly/hardhat-tenderly";
207+
208+
tdly.setup({
209+
automaticVerifications: false,
210+
});
211+
```
212+
213+
## Manual verification approach
214+
This plugin extends the `HardhatRuntimeEnvironment` by adding a `tenderly` field whose type is `Tenderly`.
215+
216+
With this approach, you can use `tenderly.verify` to trigger manual contract verification.
217+
The same method is called when verifying contracts automatically.
218+
219+
This is an example on how you can call it from your deploy script:
220+
221+
```ts
222+
import { ethers, tenderly } from "hardhat";
223+
224+
let greeter = await ethers.deployContract("Greeter", ["Hello, Hardhat!"]);
225+
226+
greeter = await greeter.waitForDeployment();
227+
228+
await tenderly.verify({
229+
name: "Greeter",
230+
address: await greeter.getAddress(),
231+
libraries: {
232+
LibraryName1: "0x...",
233+
LibraryName2: "0x..."
234+
}
235+
});
236+
```
237+
238+
`verify` accepts contracts as variadic arguments, so you can verify multiple contracts at once:
239+
240+
```ts
241+
const contracts = [
242+
{
243+
name: "Greeter",
244+
address: "0x...",
245+
libraries: { ... }
246+
},
247+
{
248+
name: "Greeter2",
249+
address: "0x...",
250+
libraries: { ... }
251+
},
252+
];
253+
```
254+
255+
## Task verification approach
256+
This plugin implements the concept of `hardhat task` to verify your contracts.
257+
The task, `tenderly:verify`, is invoked as:
258+
```bash
259+
npx hardhat tenderly:verify Greeter=0x... --network {network_name}
260+
```
261+
For more information on how to use `tenderly:verify` task, run `npx hardhat help tenderly:verify` command.
262+
263+
## More verification approaches
264+
You can also verify your contracts via exposed API calls. Although this is not recommended, you can fill the request and call some of the following methods:
265+
- `verifyMultiCompilerAPI(request: TenderlyVerifyContractsRequest)`
266+
- `verifyForkMultiCompilerAPI(request: TenderlyVerifyContractsRequest)`
267+
- `verifyDevnetMultiCompilerAPI(request: TenderlyVerifyContractsRequest)`
268+
269+
For more information on how to use these methods, you can check out their javadocs.
270+
271+
# Proxy contract verification
272+
273+
This plugin supports verification of proxy contracts, their implementation and all the related contracts.
274+
In order to successfully verify a proxy contract, please read the chapters about [Verification Modes](#verification-modes) and [Verification Approaches](#verification-approaches) first.
275+
This will lead you to setup the configuration the right way, so you can verify your proxy contracts and their implementation on Tenderly.
276+
277+
After you have successfully configured `hardhat.config.ts`, you need to populate the configuration in the format that `@nomicfoundation/hardhat-verify` plugin expects, given that this plugin uses their verification beneath for verifying proxies.
278+
But luckily, we have provided a way to automatically populate the configuration for you, you just need to set the `TENDERLY_AUTOMATIC_POPULATE_HARDHAT_VERIFY_CONFIG=true` environment variable.
279+
280+
In order to see how this all plays out, you can clone our [@tenderly/hardhat-tenderly](https://github.com/Tenderly/hardhat-tenderly) repo and navigate to the [examples/contract-verification](https://github.com/Tenderly/hardhat-tenderly/tree/master/examples/contract-verification) directory.
281+
This directory contains all the possibilities that you can explore in order to verify your proxy contracts.
282+
Right now we support, both manual and automatic verification of the following proxy contracts:
283+
- BeaconProxy
284+
- TransparentUpgradeableProxy
285+
- UUPSUpgradeableProxy
286+
287+
And we support them on all type of verification modes (e.g. **devnet**, **fork**, **public**, **private**).
288+
289+
# Troubleshooting
290+
If you are having trouble with the plugin and want to contact support, you can run the deploy script with the following ```--verbose``` flag as so:
291+
```bash
292+
npx hardhat run scripts/{your_deploy_script_here.js} --network {network_name} --verbose > tenderly.log 2>&1
293+
```
294+
or you can run the task with the same `--verbose` flag:
295+
```bash
296+
npx hardhat tenderly:verify Greeter=0x... --network {network_name} --verbose > tenderly.log 2>&1
297+
```
298+
This will create a ```tenderly.log``` file that you can send to our customer support engineers for investigation.

0 commit comments

Comments
 (0)