@wormhole-foundation/wormhole-solidity-sdk 1.0.1

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2022 Wormhole Project Contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,78 @@
+# Wormhole Solidity SDK
+
+The purpose of this SDK is to make on-chain integrations with Wormhole on EVM compatible chains as smooth as possible by providing all necessary Solidity interfaces along with useful libraries and tools for testing.
+
+For off-chain code, please refer to the [TypeScript SDK](https://github.com/wormhole-foundation/wormhole-sdk-ts) and in particular the [EVM platform implementation](https://github.com/wormhole-foundation/wormhole-sdk-ts/tree/main/platforms/evm).
+
+## Releases
+
+> License Reminder
+>
+> The code is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+>
+> So make sure you check / audit any code you use before deploying to mainnet.
+
+The `main` branch is considered the nightly version of the SDK. Stick to tagged releases for a stable experience.
+
+**Note: The SDK is currently on its way to a version 1.0 . Proceed with extra caution until then.**
+
+## Installation
+
+**Foundry and Forge**
+
+```bash
+forge install wormhole-foundation/wormhole-solidity-sdk@v1.0.0
+```
+
+**EVM Version**
+
+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.
+
+**Via-IR Support**
+
+Some of the components of this SDK require the use of intermediate representation to enable more powerful optimization passes that span across functions. This also resolves `stack-too-deep` issues that the standard compiler cannot resolve currently. The tradeoff for enabling this feature is slightly longer compilation times (up to 15 seconds). This functionality is not to be considered experimental (read [comments](https://forum.soliditylang.org/t/can-someone-explain-how-via-ir-works/1898/5) from the Solidity Development Team) but a tradeoff until there is a better handling of the stack by the solidity compiler.
+
+**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 and SafeERC20 Remapping**
+
+This SDK comes with its own IERC20 interface and SafeERC20 implementation. Given that projects tend to combine different SDKs, there's often this annoying issue of clashes of IERC20 interfaces, even though they 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. The same approach is used for SafeERC20.
+
+## Components & Testing
+
+For additional documentation of components and how to test integrations, see the docs directory.
+
+## Security
+
+This repository has been thoroughly reviewed by Wormhole Contributors and key files have been audited by a 3rd party. To ensure you are using production-ready code, always use tagged releases. If you need to use newer code from `main`, please contact the team for any security concerns.
+
+## Style
+
+This SDK largely follows [the Solidity style guide](https://docs.soliditylang.org/en/latest/style-guide.html) with some exceptions/modifications:
+
+-   indentation uses 2 instead of 4 spaces
+-   maximum line length where feasible is 100 characters (urls in comments are an exception)
+-   [order of functions](https://docs.soliditylang.org/en/latest/style-guide.html) is roughly followed but more important functions might be sorted to the top.
+-   additional whitespace is at times added to create more compelling visual blocks (e.g. for a block of related assignments)
+-   function modifiers do not get a separate line each once line length is exceeded
+-   NatSpec is avoided because it favors a "box-checking" approach towards documentation rather than focusing on essentials and rationales
+
+## Philosophy/Creeds
+
+In This House We Believe:
+
+-   clarity breeds security
+-   Do NOT trust in the Lord (i.e. the community, auditors, fellow devs, FOSS, ...) with any of your heart (i.e. with your or your users' security), but lean _hard_ on your own understanding.
+-   _Nothing_ is considered safe unless you have _personally_ verified it as such.
+-   git gud
+-   shut up and suffer
+
+## Notable Solidity Repos
+
+-   [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)

package/contracts/Executor/Integration.sol

@@ -0,0 +1,180 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.19;
+
+import {ICoreBridge}               from "../interfaces/ICoreBridge.sol";
+import {IExecutor, IVaaV1Receiver} from "../interfaces/IExecutor.sol";
+import {CoreBridgeLib}             from "../libraries/CoreBridge.sol";
+import {RequestLib}                from "./Request.sol";
+import {RelayInstructionLib}       from "./RelayInstruction.sol";
+import {toUniversalAddress}        from "../Utils.sol";
+
+//abstract base contracts for typical Executor integrations
+//integrators should inherit from exactly one of:
+// * ExecutorSend
+// * ExecutorReceive
+// * ExecutorSendReceive
+//note: The Impl contracts are a nuisance to deal with the diamond inheritance pattern and
+//      the "Base constructor arguments given twice" error that comes with it.
+
+// ╭─────────────────────────────╮
+// │   WARNING: Receiving VAAs   │
+// ╰─────────────────────────────╯
+//
+// When reciving a VAA, you must ensure:
+//   1. The VAA was emitted by a known peer to prevent spoofing - see _checkPeer
+//   2. The VAA was intended for this chain - see _checkDestination
+//
+// Emitter information is part of the VAA itself, but due to Wormhole's design as an attestion
+//   mechanism, there is no destination chain in the VAA header itself.
+// It is therefore up to the integrator to include such a field in message payloads of messages
+//   with an intended target.
+
+error InvalidPeer();
+error DestinationMismatch();
+
+abstract contract ExecutorSharedBase {
+  ICoreBridge internal immutable _coreBridge;
+  uint16      internal immutable _chainId;
+
+  constructor(address coreBridge) {
+    _coreBridge = ICoreBridge(coreBridge);
+    _chainId = _coreBridge.chainId();
+  }
+
+  //should return bytes32(0) if there is no peer on the given chain
+  function _getPeer(uint16 chainId) internal view virtual returns (bytes32);
+
+  function _getExistingPeer(uint16 chainId) internal view virtual returns (bytes32 peer) {
+    peer = _getPeer(chainId);
+    if (peer == bytes32(0))
+      revert InvalidPeer();
+  }
+}
+
+abstract contract ExecutorSendImpl is ExecutorSharedBase {
+  IExecutor internal immutable _executor;
+
+  constructor(address executor) {
+    _executor = IExecutor(executor);
+  }
+
+  function _publishAndRelay(
+    bytes memory   payload,
+    uint8          consistencyLevel,
+    uint256        totalCost, //must equal execution cost + Wormhole message fee for publishing!
+    uint16         peerChain,
+    address        refundAddress,
+    bytes calldata signedQuote,
+    uint128        gasLimit,
+    uint128        msgVal,
+    bytes memory   extraRelayInstructions
+  ) internal returns (uint64 sequence) { unchecked {
+    uint messageFee = _coreBridge.messageFee();
+    uint32 nonce = 0; //unused
+    sequence = _coreBridge.publishMessage{value: messageFee}(nonce, payload, consistencyLevel);
+
+    bytes memory relayInstructions = RelayInstructionLib.encodeGas(gasLimit, msgVal);
+    if (extraRelayInstructions.length > 0)
+      relayInstructions = abi.encodePacked(relayInstructions, extraRelayInstructions);
+
+    bytes32 peerAddress = _getExistingPeer(peerChain);
+
+    //value calculation is unchecked because call will fail on underflow anyway
+    _executor.requestExecution{value: totalCost - messageFee}(
+      peerChain,
+      peerAddress,
+      refundAddress,
+      signedQuote,
+      RequestLib.encodeVaaMultiSigRequest(_chainId, toUniversalAddress(address(this)), sequence),
+      relayInstructions
+    );
+  }}
+}
+
+abstract contract ExecutorReceiveImpl is ExecutorSharedBase, IVaaV1Receiver {
+  constructor(address coreBridge) {}
+
+  //default impl as safeguard - integrators should override this with an empty impl and perform
+  //  appropriate check in their impl of _executeVaa instead, if they allow for non-zero msg.value
+  function _executeVaaDefaultMsgValueCheck() internal virtual {
+    require(msg.value == 0);
+  }
+
+  //impl via the appropriate replay protection library from ReplayProtectionLib.sol
+  function _replayProtect(
+    uint16  emitterChainId,
+    bytes32 emitterAddress,
+    uint64  sequence,
+    bytes calldata encodedVaa
+  ) internal virtual;
+
+  //WARNING: must correctly handle non-zero msg.value (since invoking function is payable)
+  function _executeVaa(
+    bytes calldata payload,
+    uint32  timestamp,
+    uint16  peerChain,
+    bytes32 peerAddress,
+    uint64  sequence,
+    uint8   consistencyLevel
+  ) internal virtual;
+
+  //ATTENTION: You typically want to ensure that a VAA is intended for this chain
+  //             to protect against VAA submission on other chains.
+  function _checkDestination(uint16 destinationChainId) internal view virtual {
+    if (destinationChainId != _chainId)
+      revert DestinationMismatch();
+  }
+
+  //ATTENTION: You must ensure that the emitter of the VAA does indeed match a known
+  //             peer to prevent spoofing.
+  function _checkPeer(uint16 chainId, bytes32 peerAddress) internal view virtual {
+    if (_getPeer(chainId) != peerAddress)
+      revert InvalidPeer();
+  }
+
+  function executeVAAv1(bytes calldata multiSigVaa) external payable virtual {
+    _executeVaaDefaultMsgValueCheck();
+
+    ( uint32  timestamp,
+      , //nonce is ignored
+      uint16  emitterChainId,
+      bytes32 emitterAddress,
+      uint64  sequence,
+      uint8   consistencyLevel,
+      bytes calldata payload
+    ) = CoreBridgeLib.decodeAndVerifyVaaCd(address(_coreBridge), multiSigVaa);
+
+    _checkPeer(emitterChainId, emitterAddress);
+    _replayProtect(emitterChainId, emitterAddress, sequence, multiSigVaa);
+
+    _executeVaa(
+      payload,
+      timestamp,
+      emitterChainId,
+      emitterAddress,
+      sequence,
+      consistencyLevel
+    );
+  }
+}
+
+abstract contract ExecutorSend is ExecutorSharedBase, ExecutorSendImpl {
+  constructor(address coreBridge, address executor)
+    ExecutorSharedBase(coreBridge)
+    ExecutorSendImpl(executor)
+  {}
+}
+
+abstract contract ExecutorReceive is ExecutorSharedBase, ExecutorReceiveImpl {
+  constructor(address coreBridge)
+    ExecutorSharedBase(coreBridge)
+    ExecutorReceiveImpl(coreBridge)
+  {}
+}
+
+abstract contract ExecutorSendReceive is ExecutorSharedBase, ExecutorSendImpl, ExecutorReceiveImpl {
+  constructor(address coreBridge, address executor)
+    ExecutorSendImpl(executor)
+    ExecutorReceiveImpl(coreBridge)
+    ExecutorSharedBase(coreBridge) {}
+}

package/contracts/Executor/RelayInstruction.sol

@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.19;
+
+import {UncheckedIndexing} from "../libraries/UncheckedIndexing.sol";
+
+//RelayInstructions are concatenated as tightly packed bytes.
+//If the same type of instruction exists multiple times, its values are summed.
+//see https://github.com/wormhole-foundation/wormhole-sdk-ts/blob/main/core/definitions/src/protocols/executor/relayInstruction.ts
+//and also: https://github.com/wormholelabs-xyz/example-executor-ci-test/blob/6bf0e7156bf81d54f3ded707e53815a2ff62555e/src/utils.ts#L37-L71
+
+library RelayInstructionLib {
+  uint8 internal constant RECV_INST_TYPE_GAS      = 1;
+  uint8 internal constant RECV_INST_TYPE_DROP_OFF = 2;
+
+  function encodeGas(uint128 gasLimit, uint128 msgVal) internal pure returns (bytes memory) {
+    return abi.encodePacked(RECV_INST_TYPE_GAS, gasLimit, msgVal);
+  }
+
+  function encodeGasDropOffInstruction(
+    uint128 dropOff,
+    bytes32 recipient
+  ) internal pure returns (bytes memory) {
+    return abi.encodePacked(RECV_INST_TYPE_DROP_OFF, dropOff, recipient);
+  }
+
+  function encodeGasDropOffInstructions(
+    uint128[] memory dropOffs,
+    bytes32[] memory recipients
+  ) internal pure returns (bytes memory instructions) { unchecked {
+    uint instructionCount = dropOffs.length;
+    assert(instructionCount == recipients.length);
+
+    instructions = new bytes(instructionCount * GAS_DROP_OFF_INSTRUCTION_SIZE);
+    encodeGasDropOffInstructionsUnchecked(dropOffs, recipients, instructions, 0);
+  }}
+
+  //more complex implementations for higher gas efficiency below:
+  using UncheckedIndexing for uint128[];
+  using UncheckedIndexing for bytes32[];
+
+  uint256 internal constant GAS_INSTRUCTION_SIZE          = 33;
+  uint256 internal constant GAS_DROP_OFF_INSTRUCTION_SIZE = 49;
+
+  function calcBytesSize(
+    uint gasInstructionCount,
+    uint gasDropOffInstructionCount
+  ) internal pure returns (uint) { unchecked {
+    return gasInstructionCount        * GAS_INSTRUCTION_SIZE +
+           gasDropOffInstructionCount * GAS_DROP_OFF_INSTRUCTION_SIZE;
+  }}
+
+  function encodeGasDropOffInstructionUnchecked(
+    uint128 gasLimit,
+    uint128 msgVal,
+    bytes memory buffer,
+    uint offset
+  ) internal pure returns (uint newOffset) {
+    assembly ("memory-safe") {
+      let ptr := add(buffer, offset)
+      let word := mload(ptr)
+      //store type while keeping higher order bits intact
+      word := or(shl(8, word), RECV_INST_TYPE_GAS)
+      mstore(add(ptr, 1), word)
+
+      //store gas limit and msg val
+      word := or(shl(128, gasLimit), msgVal)
+      newOffset := add(offset, GAS_INSTRUCTION_SIZE) //equal to add(ptr, 32)
+      mstore(add(buffer, newOffset), word)
+    }
+  }
+
+  function encodeGasDropOffInstructionUnchecked(
+    uint128 dropOff,
+    bytes32 recipient,
+    bytes memory buffer,
+    uint offset
+  ) internal pure returns (uint newOffset) {
+    assembly ("memory-safe") {
+      //store type and amount while keeping higher order bits intact
+      let ptr := add(buffer, offset)
+      let word := mload(ptr)
+      word := or(shl(8, word), RECV_INST_TYPE_DROP_OFF)
+      word := or(shl(128, word), dropOff)
+      mstore(add(ptr, 17), word)
+
+      //store recipient
+      newOffset := add(offset, GAS_DROP_OFF_INSTRUCTION_SIZE) //equal to add(ptr, 32)
+      mstore(add(buffer, newOffset), recipient)
+    }
+  }
+
+  function encodeGasDropOffInstructionsUnchecked(
+    uint128[] memory dropOffs,
+    bytes32[] memory recipients,
+    bytes memory buffer,
+    uint offset
+  ) internal pure returns (uint newOffset) { unchecked {
+    uint instructionCount = dropOffs.length;
+    newOffset = offset;
+    for (uint i = 0; i < instructionCount; ++i)
+      newOffset = encodeGasDropOffInstructionUnchecked(
+        dropOffs.readUnchecked(i),
+        recipients.readUnchecked(i),
+        buffer,
+        newOffset
+      );
+  }}
+}

package/contracts/Executor/Request.sol

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.19;
+
+//see: https://github.com/wormholelabs-xyz/example-messaging-executor/blob/ec5daea3c03f8860a62c23e28db5c6dc8771a9ce/evm/src/libraries/ExecutorMessages.sol
+//and also: https://github.com/wormhole-foundation/wormhole-sdk-ts/blob/0379af2b0562c832bf4d2ff3d866ffca2ac92aae/core/definitions/src/protocols/executor/api.ts#L46
+
+library RequestLib {
+  bytes4 internal constant REQ_VAA_V1  = "ERV1";
+  bytes4 internal constant REQ_NTT_V1  = "ERN1";
+  bytes4 internal constant REQ_CCTP_V1 = "ERC1";
+  bytes4 internal constant REQ_CCTP_V2 = "ERC2";
+
+  function encodeVaaMultiSigRequest(
+    uint16  emitterChain,
+    bytes32 emitterAddress,
+    uint64  sequence
+  ) internal pure returns (bytes memory) {
+    return abi.encodePacked(REQ_VAA_V1, emitterChain, emitterAddress, sequence);
+  }
+
+  //messageId specifies the manager message id for the NTT transfer
+  //for VAAs that's just the sequence number
+  function encodeNttRequest(
+    uint16  srcChain,
+    bytes32 srcManager,
+    bytes32 messageId
+  ) internal pure returns (bytes memory) {
+    return abi.encodePacked(REQ_NTT_V1, srcChain, srcManager, messageId);
+  }
+
+  function encodeCctpV1Request(
+    uint32 srcDomain,
+    uint64 nonce
+  ) internal pure returns (bytes memory) {
+    return abi.encodePacked(REQ_CCTP_V1, srcDomain, nonce);
+  }
+
+  //this request currently assumes the Executor will auto detect the event off chain.
+  //that may change in the future, in which case this interface would change.
+  function encodeCctpV2Request() internal pure returns (bytes memory) {
+    return abi.encodePacked(REQ_CCTP_V2, uint8(1));
+  }
+}

package/contracts/RawDispatcher.sol

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.0;
+
+//TL;DR:
+//  Allows implementing custom call dispatching logic that is more efficient both in terms
+//    of gas (only when using the via-IR pipeline!) and calldata size than Solidity's default
+//    encoding and dispatching.
+//
+//  The numbers in the function names of this contract are meaningless and only serve the
+//    purpose of yielding a low selector that will guarantee that these functions will come
+//    first in Solidity's default function sorting _when using the via-IR pipeline_.
+//
+//See docs/RawDispatcher.md for details.
+abstract contract RawDispatcher {
+
+  //selector: 00000eb6
+  function exec768() external payable returns (bytes memory) {
+    return _exec(msg.data[4:]);
+  }
+
+  //selector: 0008a112
+  function get1959() external view returns (bytes memory) {
+    return _get(msg.data[4:]);
+  }
+
+  function _exec(bytes calldata data) internal virtual returns (bytes memory);
+
+  function _get(bytes calldata data) internal view virtual returns (bytes memory);
+}

package/contracts/Utils.sol

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.4;
+
+import {
+  tokenOrNativeTransfer
+} from "./utils/Transfer.sol";
+import {
+  reRevert
+} from "./utils/Revert.sol";
+import {
+  NotAnEvmAddress,
+  toUniversalAddress,
+  fromUniversalAddress
+} from "./utils/UniversalAddress.sol";
+import {
+  keccak256Word,
+  keccak256SliceUnchecked,
+  keccak256Cd
+} from "./utils/Keccak.sol";
+import {
+  eagerAnd,
+  eagerOr
+} from "./utils/EagerOps.sol";
+import {
+  normalizeAmount,
+  deNormalizeAmount
+} from "./utils/DecimalNormalization.sol";

package/contracts/WormholeRelayer/AdditionalMessages.sol

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.19;
+
+import {WORD_SIZE} from "../constants/Common.sol";
+
+// The `additionalMessages` parameter of `receiveWormholeMessages` contains the list of
+//   VAAs, CCTP messages, and potentially other messages that were requested for delivery in
+//   their speficied order.
+//
+// VAAs requested via VaaKey are delivered as normally encoded VAAs, just as one would expect.
+//
+// CCTP messages on the other hand do not include the associated attestation in their format but
+//   instead expect the attestation to be provided separately.
+// So the message associated with a CctpKey is a tuple of (CCTP message, attestation) and
+//   `unpackAdditionalCctpMessage` can be used to extract them.
+//
+// To further decode VAAs or CctpMessages, check out the `VaaLib` and `CctpLib` libraries.
+// To verify VAAs more efficiently, check out the `CoreBridge` library.
+
+function unpackAdditionalCctpMessage(
+  bytes calldata message
+) pure returns (bytes calldata cctpMessage, bytes calldata attestation) {
+  assembly ("memory-safe") {
+    // message.offset points to ABI-encoded struct {bytes cctpMessage, bytes attestation}
+    // First word is offset to cctpMessage bytes (always 0x40)
+    // Second word is offset to attestation bytes
+    let attestationRelativeOffset := calldataload(add(message.offset, WORD_SIZE))
+
+    let cctpMessageLengthOffset := add(message.offset, 0x40)
+    cctpMessage.offset := add(cctpMessageLengthOffset, WORD_SIZE)
+    cctpMessage.length := calldataload(cctpMessageLengthOffset)
+
+    let attestationLengthOffset := add(message.offset, attestationRelativeOffset)
+    attestation.offset := add(attestationLengthOffset, WORD_SIZE)
+    attestation.length := calldataload(attestationLengthOffset)
+  }
+}