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 and in particular the EVM platform implementation.

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

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 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 (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 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 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 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
• Solmate / Solady
• Uniswap Permit2 + explanation