Skip to content

Commit 88c4a6d

Browse files
nonergodicscnale
nonergodic
and
scnale
authored
testing utils overhaul (#62)
* wormhole override overhaul that stores state on the core bridge * finish and test WormholeOverride, fix tests * add and overhaul CCTP utils, add documentation * Update docs/Testing.md Co-authored-by: scnale <[email protected]> --------- Co-authored-by: scnale <[email protected]>
1 parent 5ae8bf3 commit 88c4a6d

15 files changed

+1136
-524
lines changed

‎docs/Testing.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Testing
2+
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+
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+
7+
## Utils
8+
9+
All Solidity testing utilities can be found in src/testing.
10+
11+
### WormholeOverride
12+
13+
**Purpose**
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.
16+
17+
**Default Guardian Set**
18+
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.
20+
21+
**Log Parsing**
22+
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.
24+
25+
**Message Fee**
26+
27+
Integrators should ensure that their contracts work correctly in case of a non-zero Wormhole message fee. `WormholeOverride` provides `setMessageFee` for this purpose.
28+
29+
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).
33+
34+
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+
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
42+
43+
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+
45+
### CctpMessages
46+
47+
Library to parse CCTP messages composed/emitted by Circle's `TokenMessenger` and `MessageTransmitter` contracts. Used in `CctpOverride` and `WormholeCctpSimulator`.
48+
49+
### ERC20Mock
50+
51+
Copy of SolMate's ERC20 Mock token that uses the overrideable `IERC20` interface of this SDK to guarantee compatibility.
52+
53+
### LogUtils
54+
55+
A library to simplify filtering of logs captured in Forge tests. Used by `WormholeOverride`, `CctpOverride`, ...

‎src/WormholeCctpTokenMessenger.sol‎

Lines changed: 323 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,323 @@
1+
// SPDX-License-Identifier: Apache 2
2+
pragma solidity ^0.8.19;
3+
4+
import {IERC20} from "IERC20/IERC20.sol";
5+
6+
import {IWormhole} from "wormhole-sdk/interfaces/IWormhole.sol";
7+
import {IMessageTransmitter} from "wormhole-sdk/interfaces/cctp/IMessageTransmitter.sol";
8+
import {ITokenMessenger} from "wormhole-sdk/interfaces/cctp/ITokenMessenger.sol";
9+
import {ITokenMinter} from "wormhole-sdk/interfaces/cctp/ITokenMinter.sol";
10+
11+
import {toUniversalAddress} from "wormhole-sdk/Utils.sol";
12+
import {WormholeCctpMessages} from "wormhole-sdk/libraries/WormholeCctpMessages.sol";
13+
import {CONSISTENCY_LEVEL_FINALIZED} from "wormhole-sdk/constants/ConsistencyLevel.sol";
14+
15+
/**
16+
* @notice A way to associate a CCTP token burn message with a Wormhole message.
17+
* @dev To construct the contract, the addresses to the Wormhole Core Bridge and CCTP Token
18+
* Messenger must be provided. Using the CCTP Token Messenger, the Message Transmitter and Token
19+
* Minter are derived.
20+
*
21+
* NOTE: For more information on CCTP message formats, please refer to the following:
22+
* https://developers.circle.com/stablecoins/docs/message-format.
23+
*/
24+
abstract contract WormholeCctpTokenMessenger {
25+
using { toUniversalAddress } for address;
26+
27+
/// @dev Parsing and verifying VAA reverted at the Wormhole Core Bridge contract level.
28+
error InvalidVaa();
29+
30+
/**
31+
* @dev The CCTP message's source domain, destination domain and nonce must match the VAA's.
32+
* NOTE: This nonce is the one acting as the CCTP message sequence (and not the arbitrary one
33+
* specified when publishing Wormhole messages).
34+
*/
35+
error CctpVaaMismatch(uint32, uint32, uint64);
36+
37+
/// @dev The emitter of the VAA must match the expected emitter.
38+
error UnexpectedEmitter(bytes32, bytes32);
39+
40+
/// @dev Wormhole Core Bridge contract address.
41+
IWormhole immutable _wormhole;
42+
43+
/// @dev Wormhole Chain ID. NOTE: This is NOT the EVM chain ID.
44+
uint16 immutable _chainId;
45+
46+
/// @dev CCTP Message Transmitter contract interface.
47+
IMessageTransmitter immutable _messageTransmitter;
48+
49+
/// @dev CCTP Token Messenger contract interface.
50+
ITokenMessenger immutable _tokenMessenger;
51+
52+
/// @dev CCTP Token Minter contract interface.
53+
ITokenMinter immutable _tokenMinter;
54+
55+
/// @dev CCTP domain for this network (configured by the CCTP Message Transmitter).
56+
uint32 immutable _localCctpDomain;
57+
58+
constructor(address wormhole, address cctpTokenMessenger) {
59+
_wormhole = IWormhole(wormhole);
60+
_chainId = _wormhole.chainId();
61+
62+
_tokenMessenger = ITokenMessenger(cctpTokenMessenger);
63+
_messageTransmitter = _tokenMessenger.localMessageTransmitter();
64+
_tokenMinter = _tokenMessenger.localMinter();
65+
_localCctpDomain = _messageTransmitter.localDomain();
66+
}
67+
68+
/**
69+
* @dev A convenience method to set the token spending allowance for the CCTP Token Messenger,
70+
* who will ultimately be burning the tokens.
71+
*/
72+
function setTokenMessengerApproval(address token, uint256 amount) internal {
73+
IERC20(token).approve(address(_tokenMessenger), amount);
74+
}
75+
76+
/**
77+
* @dev Method to burn tokens via CCTP Token Messenger and publish a Wormhole message associated
78+
* with the CCTP Token Burn message. The Wormhole message encodes a `Deposit` (ID == 1), which
79+
* has the same source domain, destination domain and nonce as the CCTP Token Burn message.
80+
*
81+
* NOTE: This method does not protect against re-entrancy here because it relies on the CCTP
82+
* Token Messenger to protect against any possible re-entrancy. We are leaning on the fact that
83+
* the Token Messenger keeps track of its local tokens, which are the only tokens it allows to
84+
* burn (and in turn, mint on another network).
85+
*
86+
* NOTE: The wormhole message fee is not required to be paid by the transaction sender (so an
87+
* integrator can use ETH funds in his contract to pay for this fee if he wants to).
88+
*/
89+
function burnAndPublish(
90+
bytes32 destinationCaller,
91+
uint32 destinationCctpDomain,
92+
address token,
93+
uint256 amount,
94+
bytes32 mintRecipient,
95+
uint32 wormholeNonce,
96+
bytes memory payload,
97+
uint256 wormholeFee
98+
) internal returns (uint64 wormholeSequence, uint64 cctpNonce) {
99+
// Invoke Token Messenger to burn tokens and emit a CCTP token burn message.
100+
cctpNonce = _tokenMessenger.depositForBurnWithCaller(
101+
amount, destinationCctpDomain, mintRecipient, token, destinationCaller
102+
);
103+
104+
// Publish deposit message via Wormhole Core Bridge.
105+
wormholeSequence = _wormhole.publishMessage{value: wormholeFee}(
106+
wormholeNonce,
107+
WormholeCctpMessages.encodeDeposit(
108+
token.toUniversalAddress(),
109+
amount,
110+
_localCctpDomain, // sourceCctpDomain
111+
destinationCctpDomain,
112+
cctpNonce,
113+
msg.sender.toUniversalAddress(), // burnSource
114+
mintRecipient,
115+
payload
116+
),
117+
CONSISTENCY_LEVEL_FINALIZED
118+
);
119+
}
120+
121+
/**
122+
* @dev Method to verify and reconcile CCTP and Wormhole messages in order to mint tokens for
123+
* the encoded mint recipient. This method will revert with custom errors.
124+
* NOTE: This method does not require the caller to be the mint recipient. If your contract
125+
* requires that the mint recipient is the caller, you should add a check after calling this
126+
* method to see if msg.sender.toUniversalAddress() == mintRecipient.
127+
*/
128+
function verifyVaaAndMint(
129+
bytes calldata encodedCctpMessage,
130+
bytes calldata cctpAttestation,
131+
bytes calldata encodedVaa
132+
) internal returns (
133+
IWormhole.VM memory vaa,
134+
bytes32 token,
135+
uint256 amount,
136+
bytes32 burnSource,
137+
bytes32 mintRecipient,
138+
bytes memory payload
139+
) {
140+
// First parse and verify VAA.
141+
vaa = _parseAndVerifyVaa( encodedVaa, true /*revertCustomErrors*/);
142+
143+
// Decode the deposit message so we can match the Wormhole message with the CCTP message.
144+
uint32 sourceCctpDomain;
145+
uint32 destinationCctpDomain;
146+
uint64 cctpNonce;
147+
(
148+
token,
149+
amount,
150+
sourceCctpDomain,
151+
destinationCctpDomain,
152+
cctpNonce,
153+
burnSource,
154+
mintRecipient,
155+
payload
156+
) = WormholeCctpMessages.decodeDeposit(vaa.payload);
157+
158+
// Finally reconcile messages and mint tokens to the mint recipient.
159+
token = _matchMessagesAndMint(
160+
encodedCctpMessage,
161+
cctpAttestation,
162+
sourceCctpDomain,
163+
destinationCctpDomain,
164+
cctpNonce,
165+
token,
166+
true // revertCustomErrors
167+
);
168+
}
169+
170+
/**
171+
* @dev PLEASE USE `verifyVaaAndMint` INSTEAD. Method to verify and reconcile CCTP and Wormhole
172+
* messages in order to mint tokens for the encoded mint recipient. This method will revert with
173+
* Solidity's built-in Error(string).
174+
* NOTE: This method does not require the caller to be the mint recipient. If your contract
175+
* requires that the mint recipient is the caller, you should add a check after calling this
176+
* method to see if msg.sender.toUniversalAddress() == mintRecipient.
177+
*/
178+
function verifyVaaAndMintLegacy(
179+
bytes calldata encodedCctpMessage,
180+
bytes calldata cctpAttestation,
181+
bytes calldata encodedVaa
182+
) internal returns (
183+
IWormhole.VM memory vaa,
184+
bytes32 token,
185+
uint256 amount,
186+
uint32 sourceCctpDomain,
187+
uint32 destinationCctpDomain,
188+
uint64 cctpNonce,
189+
bytes32 burnSource,
190+
bytes32 mintRecipient,
191+
bytes memory payload
192+
) {
193+
// First parse and verify VAA.
194+
vaa = _parseAndVerifyVaa(encodedVaa, false /*revertCustomErrors*/);
195+
196+
// Decode the deposit message so we can match the Wormhole message with the CCTP message.
197+
(
198+
token,
199+
amount,
200+
sourceCctpDomain,
201+
destinationCctpDomain,
202+
cctpNonce,
203+
burnSource,
204+
mintRecipient,
205+
payload
206+
) = WormholeCctpMessages.decodeDeposit(vaa.payload);
207+
208+
// Finally reconcile messages and mint tokens to the mint recipient.
209+
token = _matchMessagesAndMint(
210+
encodedCctpMessage,
211+
cctpAttestation,
212+
sourceCctpDomain,
213+
destinationCctpDomain,
214+
cctpNonce,
215+
token,
216+
false // revertCustomErrors
217+
);
218+
}
219+
220+
/**
221+
* @dev For a given remote domain and token, fetch the corresponding local token, for which the
222+
* CCTP Token Minter has minting authority.
223+
*/
224+
function fetchLocalToken(
225+
uint32 remoteDomain,
226+
bytes32 remoteToken
227+
) internal view returns (bytes32 localToken) {
228+
localToken = _tokenMinter.remoteTokensToLocalTokens(
229+
keccak256(abi.encodePacked(remoteDomain, remoteToken))
230+
).toUniversalAddress();
231+
}
232+
233+
/**
234+
* @dev We encourage an integrator to use this method to make sure the VAA is emitted from one
235+
* that his contract trusts. Usually foreign emitters are stored in a mapping keyed off by
236+
* Wormhole Chain ID (uint16).
237+
*
238+
* NOTE: Reverts with `UnexpectedEmitter(bytes32, bytes32)`.
239+
*/
240+
function requireEmitter(IWormhole.VM memory vaa, bytes32 expectedEmitter) internal pure {
241+
if (expectedEmitter != 0 && vaa.emitterAddress != expectedEmitter)
242+
revert UnexpectedEmitter(vaa.emitterAddress, expectedEmitter);
243+
}
244+
245+
/**
246+
* @dev We encourage an integrator to use this method to make sure the VAA is emitted from one
247+
* that his contract trusts. Usually foreign emitters are stored in a mapping keyed off by
248+
* Wormhole Chain ID (uint16).
249+
*
250+
* NOTE: Reverts with built-in Error(string).
251+
*/
252+
function requireEmitterLegacy(IWormhole.VM memory vaa, bytes32 expectedEmitter) internal pure {
253+
require(expectedEmitter != 0 && vaa.emitterAddress == expectedEmitter, "unknown emitter");
254+
}
255+
256+
// private
257+
258+
function _parseAndVerifyVaa(
259+
bytes calldata encodedVaa,
260+
bool revertCustomErrors
261+
) private view returns (IWormhole.VM memory vaa) {
262+
bool valid;
263+
string memory reason;
264+
(vaa, valid, reason) = _wormhole.parseAndVerifyVM(encodedVaa);
265+
266+
if (!valid) {
267+
if (revertCustomErrors)
268+
revert InvalidVaa();
269+
else
270+
require(false, reason);
271+
}
272+
}
273+
274+
function _matchMessagesAndMint(
275+
bytes calldata encodedCctpMessage,
276+
bytes calldata cctpAttestation,
277+
uint32 vaaSourceCctpDomain,
278+
uint32 vaaDestinationCctpDomain,
279+
uint64 vaaCctpNonce,
280+
bytes32 burnToken,
281+
bool revertCustomErrors
282+
) private returns (bytes32 mintToken) {
283+
// Confirm that the caller passed the correct message pair.
284+
{
285+
uint32 sourceDomain;
286+
uint32 destinationDomain;
287+
uint64 nonce;
288+
289+
assembly ("memory-safe") {
290+
// NOTE: First four bytes is the CCTP message version.
291+
let ptr := calldataload(encodedCctpMessage.offset)
292+
293+
// NOTE: There is no need to mask here because the types defined outside of this
294+
// block will already perform big-endian masking.
295+
296+
// Source domain is bytes 4..8, so shift 24 bytes to the right.
297+
sourceDomain := shr(192, ptr)
298+
// Destination domain is bytes 8..12, so shift 20 bytes to the right.
299+
destinationDomain := shr(160, ptr)
300+
// Nonce is bytes 12..20, so shift 12 bytes to the right.
301+
nonce := shr(96, ptr)
302+
}
303+
304+
if (
305+
vaaSourceCctpDomain != sourceDomain ||
306+
vaaDestinationCctpDomain != destinationDomain||
307+
vaaCctpNonce != nonce
308+
) {
309+
if (revertCustomErrors)
310+
revert CctpVaaMismatch(sourceDomain, destinationDomain, nonce);
311+
else
312+
require(false, "invalid message pair");
313+
}
314+
}
315+
316+
// Call the circle bridge to mint tokens to the recipient.
317+
_messageTransmitter.receiveMessage(encodedCctpMessage, cctpAttestation);
318+
319+
// We should trust that this getter will not return the zero address because the TokenMinter
320+
// will have already minted the valid token for the mint recipient.
321+
mintToken = fetchLocalToken(vaaSourceCctpDomain, burnToken);
322+
}
323+
}

‎src/WormholeRelayer/CCTPAndTokenBase.sol‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -105,10 +105,7 @@ abstract contract CCTPAndTokenSender is CCTPAndTokenBase {
105105
USDC,
106106
targetAddressBytes32
107107
);
108-
return MessageKey(
109-
CCTPMessageLib.CCTP_KEY_TYPE,
110-
abi.encodePacked(getCCTPDomain(wormhole.chainId()), nonce)
111-
);
108+
return MessageKey(CCTP_KEY_TYPE, abi.encodePacked(getCCTPDomain(wormhole.chainId()), nonce));
112109
}
113110

114111
// Publishes a CCTP transfer of 'amount' of USDC

0 commit comments

Comments
 (0)