(mostly) format cleanup

.gitignore

@@ -7,8 +7,5 @@ out/
 /broadcast/*/31337/
 /broadcast/**/dry-run/
 
-# Docs
-docs/
-
 # Dotenv file
 .env

README.md

@@ -40,6 +40,10 @@ It is strongly recommended that you run the forge test suite of this SDK with yo
 
 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.
 
+## Components
+
+For additional documentation of components, see the docs directory.
+
 ## Philosophy/Creeds
 
 In This House We Believe:
@@ -49,42 +53,8 @@ In This House We Believe:
 * git gud
 * shut up and suffer
 
-## WormholeRelayer
-
-### Introduction
-
-The WormholeRelayer (also sometimes referred to as the automatic or generic relayer) allows integrators to leverage external parties known as delivery providers, to relay messages emitted on a given source chain to the intended target chain.
-
-This frees integrators, who are building a cross-chain app, from the cumbersome and painful task of having to run relaying infrastructure themselves (and thus e.g. dealing with the headache of having to acquire gas tokens for the target chain).
-
-Messages include, but aren't limited to: Wormhole attestations (VAAs), Circle attestations (CCTP)
-
-Delivery providers provide a quote for the cost of a delivery on the source chain and also take payment there. This means the process is not fully trustless (delivery providers can take payment and then fail to perform the delivery), however the state of the respective chains always makes it clear whether a delivery provider has done their duty for a given delivery and delivery providers can't maliciously manipulate the content of a delivery.
-
-### Example Usage
-
-[HelloWormhole - Simple cross-chain message sending application](https://github.com/wormhole-foundation/hello-wormhole)
-
-[HelloToken - Simple cross-chain token sending application](https://github.com/wormhole-foundation/hello-token)
-
-[HelloUSDC - Simple cross-chain USDC sending application using CCTP](https://github.com/wormhole-foundation/hello-usdc)
-
-### SDK Summary
-
-- Includes interfaces to interact with contracts in the Wormhole ecosystem ([src/interfaces](https://github.com/wormhole-foundation/wormhole-solidity-sdk/tree/main/src/interfaces))
-- Includes the base class ‘Base’ with helpers for common actions that will typically need to be done within ‘receiveWormholeMessages’:
-  - [`onlyWormholeRelayer()`](https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/main/src/WormholeRelayer/Base.sol#L9): Checking that msg.sender is the wormhole relayer contract
-    Sometimes, Cross-chain applications may be set up such that there is one ‘spoke’ contract on every chain, which sends messages to the ‘hub’ contract. If so, we’d ideally only want to allow messages to be sent from these spoke contracts. Included are helpers for this:
-
-    - [`setRegisteredSender(uint16 sourceChain, bytes32 sourceAddress)`](https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/main/src/WormholeRelayer/Base.sol#L45): Setting the specified sender for ‘sourceChain’ to be ‘sourceAddress’
-    - [`isRegisteredSender(uint16 sourceChain, bytes32 sourceAddress)`](https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/main/src/WormholeRelayer/Base.sol#L30): Checking that the sender who requested the delivery is the registered address for that chain
-
-    Look at test/Counter.t.sol for an example usage of Base
-
-- Included are also:
-  - The ‘[TokenSender](https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/main/src/WormholeRelayer/TokenBase.sol#L24)’ and ‘[TokenReceiver](https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/main/src/WormholeRelayer/TokenBase.sol#L158)’ base classes with helpers for smart contracts that wish to send and receive tokens using Wormhole’s TokenBridge. See ‘[HelloToken](https://github.com/wormhole-foundation/hello-token)’ for example usage.
-  - The ‘[CCTPSender](https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/main/src/WormholeRelayer/CCTPBase.sol#L59)’ and ‘[CCTPReceiver](https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/main/src/WormholeRelayer/CCTPBase.sol#L177)’ base classes with helpers for smart contracts that wish to send and receive both tokens using Wormhole’s TokenBridge as well as USDC using CCTP. See ‘[HelloUSDC](https://github.com/wormhole-foundation/hello-usdc)’ for example usage.
-  - Or a combination of both - [CCTPAndTokenBase](https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/main/src/WormholeRelayer/CCTPAndTokenBase.sol).
-  - Helpers for setting up a local forge testing environment. See ‘[HelloWormhole](https://github.com/wormhole-foundation/hello-wormhole)’ for example usage.
+## Notable Solidity Repos
 
-**Note: This code is meant to be used as starter / reference code. Feel free to modify for use in your contracts, and also make sure to audit any code used from here as part of your contracts before deploying to mainnet.**
+* [OpenZeppelin](https://github.com/OpenZeppelin/openzeppelin-contracts)
+* [Solmate](https://github.com/transmissions11/solmate) / [Solady](https://github.com/Vectorized/solady)
+* [Uniswap Permit2](https://github.com/Uniswap/permit2) + [explanation](https://github.com/dragonfly-xyz/useful-solidity-patterns/tree/main/patterns/permit2)

docs/Optimization.md

@@ -0,0 +1,25 @@
+# Compiler Optimization
+
+List of ways to avoid short-comings of the current optimizer which lead to suboptimal byte code
+
+## for loop array length checking
+
+```
+function iterate(uint[] memory myArray) {
+  uint len = myArray.length;
+  for (uint i; i < len; ++i) { /*...*/}
+}
+```
+is more efficient than
+```
+function iterate(uint[] memory myArray) {
+  for (uint i; i < myArray.length; ++i) { /*...*/}
+}
+```
+even if it is trivial for the optimizer to check that `myArray`'s length can't possibly change as part of the loop.
+
+If `myArray` uses `calldata` instead of `memory`, both versions produce the same bytecode.
+
+## prefer `< MAX + 1` over `<= MAX` for const comparison
+
+Given that the EVM only supports `LT` and `GT` but not `LTE` or `GTE`, solc implements `x<=y` as `!(x>y)`. However, given a constant `MAX`, since solc resolves `MAX + 1` at compile time, `< MAX + 1` saves one `ISZERO` opcode.

docs/WormholeRelayer.md

@@ -0,0 +1,37 @@
+# WormholeRelayer
+
+The WormholeRelayer (also sometimes referred to as the automatic or generic relayer) allows integrators to leverage external parties known as delivery providers, to relay messages emitted on a given source chain to the intended target chain.
+
+This frees integrators, who are building a cross-chain app, from the cumbersome and painful task of having to run relaying infrastructure themselves (and thus e.g. dealing with the headache of having to acquire gas tokens for the target chain).
+
+Messages include, but aren't limited to: Wormhole attestations (VAAs), Circle attestations (CCTP)
+
+Delivery providers provide a quote for the cost of a delivery on the source chain and also take payment there. This means the process is not fully trustless (delivery providers can take payment and then fail to perform the delivery), however the state of the respective chains always makes it clear whether a delivery provider has done their duty for a given delivery and delivery providers can't maliciously manipulate the content of a delivery.
+
+## Example Usage
+
+[HelloWormhole - Simple cross-chain message sending application](https://github.com/wormhole-foundation/hello-wormhole)
+
+[HelloToken - Simple cross-chain token sending application](https://github.com/wormhole-foundation/hello-token)
+
+[HelloUSDC - Simple cross-chain USDC sending application using CCTP](https://github.com/wormhole-foundation/hello-usdc)
+
+## SDK Summary
+
+- Includes interfaces to interact with contracts in the Wormhole ecosystem ([src/interfaces](https://github.com/wormhole-foundation/wormhole-solidity-sdk/tree/main/src/interfaces))
+- Includes the base class ‘Base’ with helpers for common actions that will typically need to be done within ‘receiveWormholeMessages’:
+  - [`onlyWormholeRelayer()`](https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/main/src/WormholeRelayer/Base.sol#L9): Checking that msg.sender is the wormhole relayer contract
+    Sometimes, Cross-chain applications may be set up such that there is one ‘spoke’ contract on every chain, which sends messages to the ‘hub’ contract. If so, we’d ideally only want to allow messages to be sent from these spoke contracts. Included are helpers for this:
+
+    - [`setRegisteredSender(uint16 sourceChain, bytes32 sourceAddress)`](https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/main/src/WormholeRelayer/Base.sol#L45): Setting the specified sender for ‘sourceChain’ to be ‘sourceAddress’
+    - [`isRegisteredSender(uint16 sourceChain, bytes32 sourceAddress)`](https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/main/src/WormholeRelayer/Base.sol#L30): Checking that the sender who requested the delivery is the registered address for that chain
+
+    Look at test/Counter.t.sol for an example usage of Base
+
+- Included are also:
+  - The ‘[TokenSender](https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/main/src/WormholeRelayer/TokenBase.sol#L24)’ and ‘[TokenReceiver](https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/main/src/WormholeRelayer/TokenBase.sol#L158)’ base classes with helpers for smart contracts that wish to send and receive tokens using Wormhole’s TokenBridge. See ‘[HelloToken](https://github.com/wormhole-foundation/hello-token)’ for example usage.
+  - The ‘[CCTPSender](https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/main/src/WormholeRelayer/CCTPBase.sol#L59)’ and ‘[CCTPReceiver](https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/main/src/WormholeRelayer/CCTPBase.sol#L177)’ base classes with helpers for smart contracts that wish to send and receive both tokens using Wormhole’s TokenBridge as well as USDC using CCTP. See ‘[HelloUSDC](https://github.com/wormhole-foundation/hello-usdc)’ for example usage.
+  - Or a combination of both - [CCTPAndTokenBase](https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/main/src/WormholeRelayer/CCTPAndTokenBase.sol).
+  - Helpers for setting up a local forge testing environment. See ‘[HelloWormhole](https://github.com/wormhole-foundation/hello-wormhole)’ for example usage.
+
+**Note: This code is meant to be used as starter / reference code. Feel free to modify for use in your contracts, and also make sure to audit any code used from here as part of your contracts before deploying to mainnet.**

src/Utils.sol

@@ -5,14 +5,14 @@ pragma solidity ^0.8.19;
 error NotAnEvmAddress(bytes32);
 
 function toUniversalAddress(address addr) pure returns (bytes32 universalAddr) {
-    universalAddr = bytes32(uint256(uint160(addr)));
+  universalAddr = bytes32(uint256(uint160(addr)));
 }
 
 function fromUniversalAddress(bytes32 universalAddr) pure returns (address addr) {
-    if (bytes12(universalAddr) != 0)
-        revert NotAnEvmAddress(universalAddr);
+  if (bytes12(universalAddr) != 0)
+    revert NotAnEvmAddress(universalAddr);
 
-    assembly ("memory-safe") {
-        addr := universalAddr
-    }
+  assembly ("memory-safe") {
+    addr := universalAddr
+  }
 }

src/WormholeRelayer/Base.sol

@@ -7,49 +7,49 @@ import "wormhole-sdk/interfaces/IWormhole.sol";
 import "wormhole-sdk/Utils.sol";
 
 abstract contract Base {
-    IWormholeRelayer public immutable wormholeRelayer;
-    IWormhole public immutable wormhole;
+  IWormholeRelayer public immutable wormholeRelayer;
+  IWormhole public immutable wormhole;
 
-    address registrationOwner;
-    mapping(uint16 => bytes32) registeredSenders;
+  address registrationOwner;
+  mapping(uint16 => bytes32) registeredSenders;
 
-    constructor(address _wormholeRelayer, address _wormhole) {
-        wormholeRelayer = IWormholeRelayer(_wormholeRelayer);
-        wormhole = IWormhole(_wormhole);
-        registrationOwner = msg.sender;
-    }
+  constructor(address _wormholeRelayer, address _wormhole) {
+    wormholeRelayer = IWormholeRelayer(_wormholeRelayer);
+    wormhole = IWormhole(_wormhole);
+    registrationOwner = msg.sender;
+  }
 
-    modifier onlyWormholeRelayer() {
-        require(
-            msg.sender == address(wormholeRelayer),
-            "Msg.sender is not Wormhole Relayer"
-        );
-        _;
-    }
+  modifier onlyWormholeRelayer() {
+    require(
+      msg.sender == address(wormholeRelayer),
+      "Msg.sender is not Wormhole Relayer"
+    );
+    _;
+  }
 
-    modifier isRegisteredSender(uint16 sourceChain, bytes32 sourceAddress) {
-        require(
-            registeredSenders[sourceChain] == sourceAddress,
-            "Not registered sender"
-        );
-        _;
-    }
+  modifier isRegisteredSender(uint16 sourceChain, bytes32 sourceAddress) {
+    require(
+      registeredSenders[sourceChain] == sourceAddress,
+      "Not registered sender"
+    );
+    _;
+  }
 
-    /**
-     * Sets the registered address for 'sourceChain' to 'sourceAddress'
-     * So that for messages from 'sourceChain', only ones from 'sourceAddress' are valid
-     *
-     * Assumes only one sender per chain is valid
-     * Sender is the address that called 'send' on the Wormhole Relayer contract on the source chain)
-     */
-    function setRegisteredSender(
-        uint16 sourceChain,
-        bytes32 sourceAddress
-    ) public {
-        require(
-            msg.sender == registrationOwner,
-            "Not allowed to set registered sender"
-        );
-        registeredSenders[sourceChain] = sourceAddress;
-    }
+  /**
+   * Sets the registered address for 'sourceChain' to 'sourceAddress'
+   * So that for messages from 'sourceChain', only ones from 'sourceAddress' are valid
+   *
+   * Assumes only one sender per chain is valid
+   * Sender is the address that called 'send' on the Wormhole Relayer contract on the source chain)
+   */
+  function setRegisteredSender(
+    uint16 sourceChain,
+    bytes32 sourceAddress
+  ) public {
+    require(
+      msg.sender == registrationOwner,
+      "Not allowed to set registered sender"
+    );
+    registeredSenders[sourceChain] = sourceAddress;
+  }
 }