e00dan/layerzero-starter-kit

Deprecation notice

Upgradeable contracts and good starter kit is now officially supported by LayerZero team: https://github.com/LayerZero-Labs/devtools/tree/main/examples/oft-upgradeable

Upgradeable LayerZero V2 Foundry Starter Pack 🛠️🚀

This repository can be cloned to quickly start building upgradeable applications on top of LayerZero V2. It includes libraries required for development, contains test setup and working multichain deployment script written in Solidity.

These are the potential advantages of using this repository instead of official LZ V2 repository:

Multichain deployment script written in Solidity
OpenZeppelin V4 upgradeability: OAppUpgradeable, OFTUpgradeable (vide LZ-V2/PR-#9)
Native Foundry config - no NPM dependencies (vide LZ-V2/Issue-#6), no TypeScript
CREATE2 by default for deterministic addresses in multichain deployment
Very simple Counter example just to get started without advanced functionality

I still recommend consulting official repository of LayerZero whenever you need to bring more advanced functionality or different code examples.

Quickstart

git clone https://github.com/Kuzirashi/layerzero-starter-kit.git
cd layerzero-starter-kit
forge install

Note: If you don't have Foundry installed yet please follow installation guide.

Usage

Build

forge build

Test

forge test

Note: if you want to execute single test file you can add a flag, eg.: --match-path ./test/CounterUpgradeability.t.sol.

Deploy

Preparation:

cp .env.example .env

Fill TEST_DEPLOYER_KEY and TEST_OWNER_ADDRESS before running deployment script.

Dry run:

forge script DeployCounter -s "deployCounterTestnet(uint256, uint256)" 1 1 --force --multi

To send transactions and actually deploy just add --broadcast flag to the command above.

Note: 1 1 parameters are respectively: uint256 _counterSalt, uint256 _counterProxySalt. It affects generated addresses. If you have problem with deployment script failing try changing 1 1 to some random numbers instead. You can't deploy with the same salt twice - it fails with message: script failed: <no data>.

Note: Don't use automatic --verify flag because it doesn't seem to work.

Upgrade

Please set TEST_COUNTER_PROXY_ADDRESS in .env to make sure correct proxy is updated.

forge script UpgradeCounter -s "upgradeTestnet()" --force --multi

Add --broadcast when you're ready to send actual transactions (example tx).

Verify

Read VERIFICATION.md.

Demo deployment

Read EXISTING_DEPLOYMENT.md.

Compatibility

Tested with:

forge 0.2.0 (71d8ea5 2024-01-09T14:41:14.837767655Z)

Inspiration 💡

This repository is, to a significant extent, a compilation of other people's work. I just put these separate pieces together to achieve best developer experience possible.

LayerZero libraries and examples are based on: https://github.com/LayerZero-Labs/LayerZero-v2.

Multichain script deployment setup is heavily based on: https://github.com/timurguvenkaya/foundry-multichain by @timurguvenkaya.

LayerZero OApp Upgradeability is taken from: https://github.com/Zodomo/LayerZero-v2/tree/main by @Zodomo.

Note: Initially I have used my own implementation but I think @Zodomo version is slightly better structured. I've noticed that implementation after I created this repository.

License

MIT