|
1 | | -# Testing |
| 1 | +# Introduction |
2 | 2 |
|
3 | 3 | As a general point, your testing environment should match your real world environment as much as possible. Therefore, fork testing is generally encouraged over running standalone tests, despite the RPC provider dependency and its associated headaches. |
4 | 4 |
|
5 | 5 | Besides fork testing, forge also offers [mockCall](https://book.getfoundry.sh/cheatcodes/mock-call), [mockCallRevert](https://book.getfoundry.sh/cheatcodes/mock-call-revert), and [mockFunction](https://book.getfoundry.sh/cheatcodes/mock-function) cheat-codes, which should typically be preferred over writing and deploying mock contracts due to their more explicit nature. |
6 | 6 |
|
7 | | -## Utils |
| 7 | +# Utils |
8 | 8 |
|
9 | 9 | All Solidity testing utilities can be found in src/testing. |
10 | 10 |
|
11 | | -### WormholeOverride |
| 11 | +## WormholeForkTest |
12 | 12 |
|
13 | 13 | **Purpose** |
14 | 14 |
|
15 | | -The `WormholeOverride` library is the main way to fork test integrations. It allows overriding the current guardian set of the core bridge with a newly generated one which can then be used to sign messages and thus create VAAs. |
| 15 | +The `WormholeForkTest` contract serves as a base class for fork testing Wormhole (and CCTP) integrations. It provides utilities for setting up and managing multiple forks, taking control of each chain's CoreBridge and CCTP MessageTransmitter using the respective override libraries, and various other common tasks. |
| 16 | + |
| 17 | +**Fork Handling** |
| 18 | + |
| 19 | +The contract comes with built-in default RPC URLs for each chain, but these can be overridden by explicitly specifying a custom RPC URL when calling `setUpFork()`. By default, it forks against mainnet chains, but this can be changed by setting `isMainnet` to false in the constructor. The `selectFork(uint16)` function is used to switch between forks using the Wormhole chain id. |
| 20 | + |
| 21 | +**Utilities** |
| 22 | + |
| 23 | +- Provides addresses of all Wormhole and CCTP contracts and other useful constants |
| 24 | +- Creates a TokenBridge attestation for a token on a given chain and automatically submits it on all other forks |
| 25 | +- USDC minting through the `UsdcDealer` library |
| 26 | +- Fetching and parsing of both Wormhole and CCTP messages from Forge logs |
| 27 | +- Creating VAAs/Circle attestations for Wormhole/CCTP messages |
| 28 | + |
| 29 | +## WormholeRelayerTest |
| 30 | + |
| 31 | +The `WormholeRelayerTest` contract extends `WormholeForkTest`, by providing additional utils for testing WormholeRelayer integrations. Namely picking up and delivering of WormholeRelayer messages to their intended targets and checking the delivery result afterwards. See test/WormholeRelayer.t.sol for an example. |
| 32 | + |
| 33 | +## WormholeOverride |
| 34 | + |
| 35 | +**Purpose** |
| 36 | + |
| 37 | +The `WormholeOverride` library allows taking control of the CoreBridge on a given chain by overriding the current guardian set with a newly generated one, which can then be used to sign published messages and thus create VAAs. |
16 | 38 |
|
17 | 39 | **Default Guardian Set** |
18 | 40 |
|
19 | | -By default the new guardian set has the same size as the old one, again to match the forked network's setup as closely as possible and keep message sizes and gas costs accurate. Since this can bloat traces and make them harder to read due to the VAAs' sizes, overriding with a single guardian when debugging tests can be helpful. This can be achieved by setting the environment variable `DEFAULT_TO_DEVNET_GUARDIAN` to true. |
| 41 | +By default, the new guardian set has the same size as the old one, again to match the forked network's setup as closely as possible and keep message sizes and gas costs accurate. Since this can bloat traces and make them harder to read due to the VAAs' sizes, overriding with a single guardian when debugging tests can be helpful. This can be achieved by setting the environment variable `DEFAULT_TO_DEVNET_GUARDIAN` to true. |
| 42 | + |
| 43 | +Also by default, the addresses and private keys of the new guardians are deterministically derived using Forge's `makeAddrAndKey` utility with the strings `guardian<i = 1, ..., n>`, naturally giving rise to the same values across all forks that are being overridden. |
20 | 44 |
|
21 | 45 | **Log Parsing** |
22 | 46 |
|
23 | | -Besides signing messages / creating VAAs, `WormholeOverride` also provides convenient forge log parsing capabilities to ensure that the right number of messages with the correct content are emitted by the core bridge. Be sure to call `vm.recordLogs();` beforehand to capture emitted events so that they are available for parsing. |
| 47 | +Besides signing messages / creating VAAs, `WormholeOverride` also provides convenient forge log parsing capabilities to ensure that the right number of messages with the correct content are emitted by the core bridge. Be sure to call `vm.recordLogs()` beforehand to capture emitted events so that they are available for parsing. |
24 | 48 |
|
25 | 49 | **Message Fee** |
26 | 50 |
|
27 | 51 | Integrators should ensure that their contracts work correctly in case of a non-zero Wormhole message fee. `WormholeOverride` provides `setMessageFee` for this purpose. |
28 | 52 |
|
| 53 | +## CctpOverride |
29 | 54 |
|
30 | | -### CctpOverride |
31 | | - |
32 | | -The `CctpOverride` library, is somewhat similar to `WormholeOverride` in that it allows overriding Circle's attester in their CCTP [MessageTransmitter](https://github.com/circlefin/evm-cctp-contracts/blob/master/src/MessageTransmitter.sol) contract (which is comparable in its functionality to Wormhole's core bridge). |
| 55 | +The `CctpOverride` library is somewhat similar to `WormholeOverride` in that it allows overriding Circle's attester in their CCTP [MessageTransmitter](https://github.com/circlefin/evm-cctp-contracts/blob/master/src/MessageTransmitter.sol) contract (which is comparable in its functionality to Wormhole's core bridge). |
33 | 56 |
|
34 | 57 | However, `CctpOverride`, rather than providing generic signing and log parsing functionality like `WormholeOverride`, is more specialized and only deals with signing and log-parsing `CctpTokenBurnMessage`s emitted through Circle's [TokenMessenger](https://github.com/circlefin/evm-cctp-contracts/blob/master/src/TokenMessenger.sol) contract (which is roughly comparable to Wormhole's token bridge). |
35 | 58 |
|
36 | | - |
37 | | -### WormholeCctpSimulator |
38 | | - |
39 | | -The `WormholeCctpSimulator` contract can be deployed to simulate a virtual `WormholeCctpTokenMessenger` instance on some made-up foreign chain. It uses `0xDDDDDDDD` as the circle domain of that chain, and also simulates virtual instances of Circle's TokenMessenger and USDC contract, which are correctly registered with the instances on the forked chain. The foreign Wormhole chain id and the address of the foreign sender can be set during construction. Uses `WormholeOverride` and `CctpOverride`. |
40 | | - |
41 | | -### UsdcDealer |
| 59 | +## UsdcDealer |
42 | 60 |
|
43 | 61 | Forge's `deal` cheat code does not work for USDC. `UsdcDealer` is another override library that implements a `deal` function that allows minting of USDC. |
44 | 62 |
|
45 | | -### ERC20Mock |
| 63 | +## ERC20Mock |
46 | 64 |
|
47 | 65 | Copy of SolMate's ERC20 Mock token that uses the overrideable `IERC20` interface of this SDK to guarantee compatibility. |
48 | 66 |
|
49 | | -### LogUtils |
| 67 | +## LogUtils |
50 | 68 |
|
51 | | -A library to simplify filtering of logs captured in Forge tests. Used by `WormholeOverride`, `CctpOverride`, ... |
| 69 | +A library to simplify filtering of logs captured in Forge tests via `vm.recordLogs()`. Used by `WormholeOverride`, `CctpOverride`, ... |
0 commit comments