further cleanup refactor and extend README

README.md

@@ -28,10 +28,18 @@ forge install wormhole-foundation/[email protected]
 
 **EVM Version**
 
-One hazard of developing EVM contracts in a cross-chain environment is that different chains have varying levels EVM-equivalence. This means you have to ensure that all chains that you are planning to deploy to  support all EIPs/opcodes that you rely on.
+One hazard of developing EVM contracts in a cross-chain environment is that different chains have varying levels of "EVM-equivalence". This means you have to ensure that all chains that you are planning to deploy to support all EIPs/opcodes that you rely on.
 
 For example, if you are using a solc version newer than `0.8.19` and are planning to deploy to a chain that does not support [PUSH0 opcode](https://eips.ethereum.org/EIPS/eip-3855) (introduced as part of the Shanghai hardfork), you should set `evm_version = "paris"` in your `foundry.toml`, since the default EVM version of solc was advanced from Paris to Shanghai as part of solc's `0.8.20` release.
 
+**Testing**
+
+It is strongly recommended that you run the forge test suite of this SDK with your own compiler version to catch potential errors that stem from differences in compiler versions early. Yes, strictly speaking the Solidity version pragma should prevent these issues, but better to be safe than sorry, especially given that some components make extensive use of inline assembly.
+
+**IERC20 Remapping**
+
+This SDK comes with its own IERC20 interface. Given that projects tend to combine different SDKs, there's often this annoying issue of clashes of IERC20 interfaces, even though the are effectively the same. We handle this issue by importing `IERC20/IERC20.sol` which allows remapping the `IERC20/` prefix to whatever directory contains `IERC20.sol` in your project, thus providing an override mechanism that should allow dealing with this problem seamlessly until forge allows remapping of individual files.
+
 ## Philosophy/Creeds
 
 In This House We Believe:

foundry.toml

@@ -6,10 +6,16 @@ out = "out"
 libs = ["lib"]
 via_ir = true
 
+#currently, forge does not allow remapping of individual files
+# (see here: https://github.com/foundry-rs/foundry/issues/7527#issuecomment-2269444829)
+#so for now we are using the IERC20 prefix as a workaround that allows users
+# to override the IERC20 interface with whatever they use in their project
+# (well, as long as their file is also called IERC20.sol and is interface compatible)
 remappings = [
   "ds-test/=lib/forge-std/lib/ds-test/src/",
   "forge-std/=lib/forge-std/src/",
   "wormhole-sdk/=src/",
+  "IERC20/=src/interfaces/token/",
 ]
 
 # See more config options https://github.com/foundry-rs/foundry/tree/master/config

src/WormholeRelayer/CCTPAndTokenBase.sol

@@ -1,10 +1,10 @@
 // SPDX-License-Identifier: Apache 2
 pragma solidity ^0.8.19;
 
+import "IERC20/IERC20.sol";
 import "wormhole-sdk/interfaces/IWormholeReceiver.sol";
 import "wormhole-sdk/interfaces/IWormholeRelayer.sol";
 import "wormhole-sdk/interfaces/ITokenBridge.sol";
-import "wormhole-sdk/interfaces/token/IERC20.sol";
 import "wormhole-sdk/interfaces/cctp/ITokenMessenger.sol";
 import "wormhole-sdk/interfaces/cctp/IMessageTransmitter.sol";
 import "wormhole-sdk/Utils.sol";

src/WormholeRelayer/CCTPBase.sol

@@ -1,9 +1,9 @@
 // SPDX-License-Identifier: Apache 2
 pragma solidity ^0.8.19;
 
+import "IERC20/IERC20.sol";
 import "wormhole-sdk/interfaces/IWormholeReceiver.sol";
 import "wormhole-sdk/interfaces/IWormholeRelayer.sol";
-import "wormhole-sdk/interfaces/token/IERC20.sol";
 import "wormhole-sdk/interfaces/cctp/ITokenMessenger.sol";
 import "wormhole-sdk/interfaces/cctp/IMessageTransmitter.sol";
 import "wormhole-sdk/Utils.sol";

src/WormholeRelayer/TokenBase.sol

@@ -1,10 +1,11 @@
 // SPDX-License-Identifier: Apache 2
 pragma solidity ^0.8.19;
 
+import "IERC20/IERC20.sol";
 import "wormhole-sdk/interfaces/IWormholeReceiver.sol";
 import "wormhole-sdk/interfaces/IWormholeRelayer.sol";
 import "wormhole-sdk/interfaces/ITokenBridge.sol";
-import "wormhole-sdk/interfaces/token/IERC20.sol";
+
 import "wormhole-sdk/Utils.sol";
 
 import {Base} from "./Base.sol";

src/interfaces/ITokenBridge.sol

@@ -3,7 +3,6 @@
 
 pragma solidity ^0.8.0;
 
-import "./token/IWETH.sol";
 import "./IWormhole.sol";
 
 interface ITokenBridge {
@@ -149,7 +148,7 @@ interface ITokenBridge {
 
     function tokenImplementation() external view returns (address);
 
-    function WETH() external view returns (IWETH);
+    function WETH() external view returns (address);
 
     function outstandingBridged(address token) external view returns (uint256);
 

src/interfaces/cctp/IMessageTransmitter.sol

@@ -1,87 +1,76 @@
 // SPDX-License-Identifier: Apache 2
-pragma solidity ^0.8.0;
-
-interface IMessageTransmitter {
-	event MessageSent(bytes message);
-
-	/**
-	 * @notice Emitted when tokens are minted
-	 * @param _mintRecipient recipient address of minted tokens
-	 * @param _amount amount of minted tokens
-	 * @param _mintToken contract address of minted token
-	 */
-	event MintAndWithdraw(
-		address _mintRecipient,
-		uint256 _amount,
-		address _mintToken
-	);
-
-	/**
-	 * @notice Receive a message. Messages with a given nonce
-	 * can only be broadcast once for a (sourceDomain, destinationDomain)
-	 * pair. The message body of a valid message is passed to the
-	 * specified recipient for further processing.
-	 *
-	 * @dev Attestation format:
-	 * A valid attestation is the concatenated 65-byte signature(s) of exactly
-	 * `thresholdSignature` signatures, in increasing order of attester address.
-	 * ***If the attester addresses recovered from signatures are not in
-	 * increasing order, signature verification will fail.***
-	 * If incorrect number of signatures or duplicate signatures are supplied,
-	 * signature verification will fail.
-	 *
-	 * Message format:
-	 * Field Bytes Type Index
-	 * version 4 uint32 0
-	 * sourceDomain 4 uint32 4
-	 * destinationDomain 4 uint32 8
-	 * nonce 8 uint64 12
-	 * sender 32 bytes32 20
-	 * recipient 32 bytes32 52
-	 * messageBody dynamic bytes 84
-	 * @param _message Message bytes
-	 * @param _attestation Concatenated 65-byte signature(s) of `_message`, in increasing order
-	 * of the attester address recovered from signatures.
-	 * @return success bool, true if successful
-	 */
-	function receiveMessage(
-		bytes memory _message,
-		bytes calldata _attestation
-	) external returns (bool success);
-
-	function attesterManager() external view returns (address);
-
-	function availableNonces(uint32 domain) external view returns (uint64);
-
-	function getNumEnabledAttesters() external view returns (uint256);
-
-	function isEnabledAttester(address _attester) external view returns (bool);
+// Copyright (c) 2022, Circle Internet Financial Limited.
+//
+// stripped, flattened version of:
+//   https://github.com/circlefin/evm-cctp-contracts/blob/master/src/MessageTransmitter.sol
 
-	function localDomain() external view returns (uint32);
-
-	function maxMessageBodySize() external view returns (uint256);
-
-	function owner() external view returns (address);
-
-	function paused() external view returns (bool);
-
-	function pauser() external view returns (address);
-
-	function rescuer() external view returns (address);
-
-	function version() external view returns (uint32);
+pragma solidity ^0.8.0;
 
-	// owner only methods
-	function transferOwnership(address newOwner) external;
+import {IOwnable2Step} from "./shared/IOwnable2Step.sol";
+import {IPausable} from "./shared/IPausable.sol";
 
-	function updateAttesterManager(address _newAttesterManager) external;
+interface IAttestable {
+  event AttesterEnabled(address indexed attester);
+  event AttesterDisabled(address indexed attester);
 
-	// attester manager only methods
-	function getEnabledAttester(uint256 _index) external view returns (address);
+  event SignatureThresholdUpdated(uint256 oldSignatureThreshold, uint256 newSignatureThreshold);
+  event AttesterManagerUpdated(
+    address indexed previousAttesterManager,
+    address indexed newAttesterManager
+  );
 
-	function disableAttester(address _attester) external;
+  function attesterManager() external view returns (address);
+  function isEnabledAttester(address attester) external view returns (bool);
+  function getNumEnabledAttesters() external view returns (uint256);
+  function getEnabledAttester(uint256 index) external view returns (address);
 
-	function enableAttester(address _attester) external;
+  function updateAttesterManager(address newAttesterManager) external;
+  function setSignatureThreshold(uint256 newSignatureThreshold) external;
+  function enableAttester(address attester) external;
+  function disableAttester(address attester) external;
+}
 
-	function setSignatureThreshold(uint256 newSignatureThreshold) external;
+interface IMessageTransmitter is IAttestable, IPausable, IOwnable2Step {
+  event MessageSent(bytes message);
+
+  event MessageReceived(
+    address indexed caller,
+    uint32 sourceDomain,
+    uint64 indexed nonce,
+    bytes32 sender,
+    bytes messageBody
+  );
+
+  function localDomain() external view returns (uint32);
+  function version() external view returns (uint32);
+  function maxMessageBodySize() external view returns (uint256);
+  function nextAvailableNonce() external view returns (uint64);
+  function usedNonces(bytes32 nonce) external view returns (bool);
+
+  function sendMessage(
+    uint32 destinationDomain,
+    bytes32 recipient,
+    bytes calldata messageBody
+  ) external returns (uint64);
+
+  function sendMessageWithCaller(
+    uint32 destinationDomain,
+    bytes32 recipient,
+    bytes32 destinationCaller,
+    bytes calldata messageBody
+  ) external returns (uint64);
+
+  function replaceMessage(
+    bytes calldata originalMessage,
+    bytes calldata originalAttestation,
+    bytes calldata newMessageBody,
+    bytes32 newDestinationCaller
+  ) external;
+
+  function receiveMessage(
+    bytes calldata message,
+    bytes calldata attestation
+  ) external returns (bool success);
+
+  function setMaxMessageBodySize(uint256 newMaxMessageBodySize) external;
 }

src/interfaces/cctp/ITokenMessenger.sol

@@ -1,84 +1,72 @@
 // SPDX-License-Identifier: Apache 2
+// Copyright (c) 2022, Circle Internet Financial Limited.
+//
+// stripped version of:
+//   https://github.com/circlefin/evm-cctp-contracts/blob/master/src/MessageTransmitter.sol
+
 pragma solidity ^0.8.0;
 
+import {IOwnable2Step} from "./shared/IOwnable2Step.sol";
+
 import {IMessageTransmitter} from "./IMessageTransmitter.sol";
 import {ITokenMinter} from "./ITokenMinter.sol";
 
-interface ITokenMessenger {
-    /**
-     * @notice Deposits and burns tokens from sender to be minted on destination domain.
-     * Emits a `DepositForBurn` event.
-     * @dev reverts if:
-     * - given burnToken is not supported
-     * - given destinationDomain has no CircleBridge registered
-     * - transferFrom() reverts. For example, if sender's burnToken balance or approved allowance
-     * to this contract is less than `amount`.
-     * - burn() reverts. For example, if `amount` is 0.
-     * - MessageTransmitter returns false or reverts.
-     * @param _amount amount of tokens to burn
-     * @param _destinationDomain destination domain (ETH = 0, AVAX = 1)
-     * @param _mintRecipient address of mint recipient on destination domain
-     * @param _burnToken address of contract to burn deposited tokens, on local domain
-     * @return _nonce unique nonce reserved by message
-     */
-    function depositForBurn(
-        uint256 _amount,
-        uint32 _destinationDomain,
-        bytes32 _mintRecipient,
-        address _burnToken
-    ) external returns (uint64 _nonce);
-
-    /**
-     * @notice Deposits and burns tokens from sender to be minted on destination domain. The mint
-     * on the destination domain must be called by `_destinationCaller`.
-     * WARNING: if the `_destinationCaller` does not represent a valid address as bytes32, then it will not be possible
-     * to broadcast the message on the destination domain. This is an advanced feature, and the standard
-     * depositForBurn() should be preferred for use cases where a specific destination caller is not required.
-     * Emits a `DepositForBurn` event.
-     * @dev reverts if:
-     * - given destinationCaller is zero address
-     * - given burnToken is not supported
-     * - given destinationDomain has no CircleBridge registered
-     * - transferFrom() reverts. For example, if sender's burnToken balance or approved allowance
-     * to this contract is less than `amount`.
-     * - burn() reverts. For example, if `amount` is 0.
-     * - MessageTransmitter returns false or reverts.
-     * @param _amount amount of tokens to burn
-     * @param _destinationDomain destination domain
-     * @param _mintRecipient address of mint recipient on destination domain
-     * @param _burnToken address of contract to burn deposited tokens, on local domain
-     * @param _destinationCaller caller on the destination domain, as bytes32
-     * @return _nonce unique nonce reserved by message
-     */
-    function depositForBurnWithCaller(
-        uint256 _amount,
-        uint32 _destinationDomain,
-        bytes32 _mintRecipient,
-        address _burnToken,
-        bytes32 _destinationCaller
-    ) external returns (uint64 _nonce);
+interface ITokenMessenger is IOwnable2Step {
+  event DepositForBurn(
+    uint64 indexed nonce,
+    address indexed burnToken,
+    uint256 amount,
+    address indexed depositor,
+    bytes32 mintRecipient,
+    uint32 destinationDomain,
+    bytes32 destinationTokenMessenger,
+    bytes32 destinationCaller
+  );
 
-    function localMessageTransmitter() external view returns (IMessageTransmitter);
+  event MintAndWithdraw(address indexed mintRecipient, uint256 amount, address indexed mintToken);
 
-    function localMinter() external view returns (ITokenMinter);
+  event RemoteTokenMessengerAdded(uint32 domain, bytes32 tokenMessenger);
+  event RemoteTokenMessengerRemoved(uint32 domain, bytes32 tokenMessenger);
 
-    function messageBodyVersion() external view returns (uint32);
+  event LocalMinterAdded(address localMinter);
+  event LocalMinterRemoved(address localMinter);
 
-    function owner() external view returns (address);
+  function messageBodyVersion() external view returns (uint32);
+  function localMessageTransmitter() external view returns (IMessageTransmitter);
+  function localMinter() external view returns (ITokenMinter);
+  function remoteTokenMessengers(uint32 domain) external view returns (bytes32);
 
-    function pendingOwner() external view returns (address);
+  function depositForBurn(
+    uint256 amount,
+    uint32 destinationDomain,
+    bytes32 mintRecipient,
+    address burnToken
+  ) external returns (uint64 nonce);
 
-    function rescuer() external view returns (address);
+  function depositForBurnWithCaller(
+    uint256 amount,
+    uint32 destinationDomain,
+    bytes32 mintRecipient,
+    address burnToken,
+    bytes32 destinationCaller
+  ) external returns (uint64 nonce);
 
-    function remoteTokenMessengers(uint32 domain) external view returns (bytes32);
+  function replaceDepositForBurn(
+    bytes calldata originalMessage,
+    bytes calldata originalAttestation,
+    bytes32 newDestinationCaller,
+    bytes32 newMintRecipient
+  ) external;
 
-    function addRemoteTokenMessenger(uint32 domain, bytes32 tokenMessenger) external;
+  function handleReceiveMessage(
+    uint32 remoteDomain,
+    bytes32 sender,
+    bytes calldata messageBody
+  ) external returns (bool);
 
-    function handleReceiveMessage(uint32 _remoteDomain, bytes32 _sender, bytes memory messageBody)
-        external
-        view
-        returns (bool);
+  function addRemoteTokenMessenger(uint32 domain, bytes32 tokenMessenger) external;
+  function removeRemoteTokenMessenger(uint32 domain) external;
 
-    // owner only methods
-    function transferOwnership(address newOwner) external;
+  function addLocalMinter(address newLocalMinter) external;
+  function removeLocalMinter() external;
 }