certusone
/
xdapp-book
mirror of https://github.com/certusone/xdapp-book.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge branch 'mvp' of https://github.com/wormhole-foundation/xdapp-book into mvp

This commit is contained in:
Eric Wong 2022-09-19 14:04:07 -05:00
parent 9c494949b8 5e5e40cb31
commit 4fa2ce1f84
6 changed files with 177 additions and 98 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
src/SUMMARY.md
View File

@ -39,7 +39,8 @@
- [Environment Setup](./technical/env/environments.md)
- [Tilt](./technical/env/tilt.md)
- [Tilt (Devnet)](./technical/env/tilt.md)
- [Troubleshooting](./technical/env/troubleshooting.md)
- [Wormhole Local Validator](./technical/env/wlv.md)
- [Testnet](./technical/env/testnet.md)
- [Tooling](./technical/env/tooling.md)

42
src/technical/env/environments.md vendored
View File

@ -1,41 +1,19 @@
# Choosing an Environment
# Environment Setup
Sending a cross-chain message through Wormhole involves initiating a message on chain A, the Wormhole contract on chain A, the Guardian network, receiving a message on chain B, and the Wormhole contract on chain B.
The bare minimum Wormhole environment is just a blockchain linked up to a Guardian node. There are quite a few ways of accomplishing this, and if you're just looking to get your feet wet, you should try whichever sounds easiest.
### Devnet
However, as you get deeper into cross-chain development you'll likely find you have a growing number of components, dependencies, and teammates in the picture making your development environment more complex. Here are some of the considerations you should have in mind when choosing a development environment which will be well suited for your xDapp.
Wormhole provides two different local development environments to simulate these different elements. Below are those two options and the high level pros and cons of each.
### What components do I need now? What components will I need in the future?
1. [Wormhole Local Validator](./wlv.md)
- Pros
- Lightweight, low system resource demand
- Good iteration times
- Can be added into an existing blockchain development setup
- You may be able to get a lot done with just an EVM chain and a Guardian. However, as your application gets more sophisticated, components like relayers, frontends, automated tests, databases, explorers, and other blockchains are likely to get added in to the environment.
- Cons
- You may end up reinventing the tilt/testnet environment as you add more components
### What are my dependencies?
2. [Tilt](./tilt.md)
- Pros
- Out of the box support for the many components needed to develop across the heterogenous blockchain space
- Consistent development environment, where contracts deploy deterministically & everything is already linked up
- Ability to easily turn containers on and off as needed
- If your smart contracts have no dependencies, it may be possible for you to develop in a vacuum. However, if you're working on a fledgling blockchain and trying to integrate with other applications which are also in development, you may have no choice but to work in testnet alongside other development teams.
- Cons
- Relatively high system requirements. Specifically is RAM intensive
- Iteration requires docker container rebuilds, which can be slow
- Most blockchains are 'fresh', and thus may require you to deploy your own contract dependencies.
- Just because you have dependencies doesn't mean you automatically have to develop in testnet or mainnet. Often times it's relatively trivial to redeploy your dependencies in Tilt, or to use something like [Foundry](https://github.com/foundry-rs/foundry) to create a development version of an existing testnet or mainnet.
### Testnet
### How am I going to collaborate?
To test your application on the various testnets, there are Wormhole contracts and one Guardian node deployed. You can find the contracts [here](../../reference/contracts.md) and the rpc node [here](../../reference/rpcnodes.md).
There are two main obstacles with testing in testnet:
- Many testnet blockchains are somewhat unstable and unreliable
- Getting testnet tokens is a nuisance
**Note:** There is only one Guardian node deployed for testnet, there is a small chance that your VAA will not be processed. This rate is _not_ indicative of performance on mainnet where there are 19 Guardian nodes watching for transactions.
### Mainnet
To deploy to mainnet, you can find the contracts [here](../../reference/contracts.md) and the rpc node [here](../../reference/rpcnodes.md).
- You should consider how your teammates or collaborators are going to work in this environment from the start. There are some basic considerations like "how will they access it", but also some subtler points such as ensuring that contracts will deploy deterministically and that automated tests can be trusted to run reliably. The two paths to accomplish this are to use a public environment (testnet), or to ensure the local environment is well controlled (like tilt).

18
src/technical/env/testnet.md vendored
View File

@ -1,12 +1,22 @@
# Testnet
Wormhole testnet functions much like mainnet, is spread across many of the most popular testnet platforms
Wormhole testnet is spread across many of the most popular testnet blockchains.
- check reference section for testnet contracts
The primary reason to use Wormhole testnet is in order to simplify the management of your dependent contracts. This will vary from blockchain to blockchain.
For example, some blockchain ecosystems have the standard that their contracts are closed-source, and there are no tools to fork mainnet. Other ecosystems, such as EVM, have tools like [foundry](https://github.com/foundry-rs/foundry), which allow you to hardfork the mainnet ecosystem into a local development node.
In short, testnet tends to be the correct choice only when you have contract dependencies, and those dependencies are difficult to get working in a local environment. In most other cases, testnet tends to be more work than it's worth.
If you elect to use testnet, the Wormhole contracts addresses can be found in the [Reference](../../reference/contracts.md) section.
Pros:
- Many other projects deploy their contracts to testnet.
- In ecosystems without extensive local tooling, this may be the preferred development environment.
Cons:
- Many testnet blockchains are somewhat unstable and unreliable
- Getting testnet tokens is a nuisance
- Many testnets are somewhat unstable and have outages or partitioning events.
- Wormhole Testnet sometimes misses VAAs due to testnet instabilities.
- Testnet tokens are often difficult to acquire.

29
src/technical/env/tilt.md vendored
View File

@ -1,10 +1,10 @@
# Tilt
# Tilt (Devnet)
### What is Tilt?
[Tilt](https://tilt.dev/) is part of the Docker ecosystem. It allows developers to easily configure a Kubernetes environment for development.
[Tilt](https://tilt.dev/) is part of the official Docker ecosystem. It's a tool which allows developers to easily configure a Kubernetes environment for development.
In the context of Wormhole, the 'Tilt' environment is the development environment used by the [Wormhole Core Repository](https://github.com/wormhole-foundation/wormhole). It utilizes Tilt to set up a development environment with all the tools necessary to build across multiple blockchains. It has docker images for all the common items encountered during cross-chain developing, including:
However, in the context of Wormhole, the 'Tilt' usually refers to the development environment used by the [Wormhole Core Repository](https://github.com/wormhole-foundation/wormhole). This environment uses Tilt to stand up all the tools necessary to build across multiple blockchains. It has docker images for all the common items encountered during cross-chain developing, including:
- All the supported blockchains / ecosystems of Wormhole
- A Guardian Node
@ -12,17 +12,18 @@ In the context of Wormhole, the 'Tilt' environment is the development environmen
- Databases, Redis
- Utility frontends
The Tilt environment is meant to be an entire cross-chain ecosystem right out of the box.
The 'Tilt' environment (also referred to as Wormhole 'Devnet') is meant to provide an entire cross-chain development stack right out of the box.
### Is Tilt Right for You?
Tilt is a generally a good starting point for most developers. Here's a succinct list of the pros and cons of the environment, so you can decide if it's the right fit for you.
Tilt is generally a good starting point for most developers. Here's a succinct list of the pros and cons of the environment, so you can decide if it's the right fit for you.
### Pros
- Out-of-the-box support for the many components needed to develop across the heterogenous blockchain space.
- Consistent development environment, where contracts deploy deterministically & everything is already linked up.
- Ability to easily enable/disable contracts as needed.
- Consistent development environment, where contracts deploy deterministically and everything is already linked up.
- Ability to easily enable/disable components as needed.
- Regularly updated as new components join the Wormhole ecosystem.
### Cons
@ -32,7 +33,7 @@ Tilt is a generally a good starting point for most developers. Here's a succinct
# Setting up Tilt
The Tilt environment functions best in a UNIX-style environment. For Windows users, using a WSL environment is recommended.
Tilt functions best in a UNIX-style environment. For Windows users, using a WSL environment is recommended.
In order to run the Tilt environment, you'll first need to make sure you have [Tilt](https://docs.tilt.dev/install.html) and [Go](https://go.dev/doc/install) installed.
@ -46,7 +47,7 @@ cd wormhole
tilt up
```
Be sure to check out the **Tiltfile**, which has much of the configuration and arguments for the development environment. It's relatively straightforward to enable and disable components. For example, you can disable blockchains by setting them to false at startup
Be sure to check out the [**Tiltfile**](https://github.com/wormhole-foundation/wormhole/blob/dev.v2/Tiltfile), which has much of the configuration and arguments for the development environment. It's relatively straightforward to enable and disable components. For example, you can disable blockchains by setting them to false at startup
```
tilt up -- --algorand=false --near=false --solana=false terra_classic=false terra2=false
@ -56,12 +57,18 @@ tilt up -- --algorand=false --near=false --solana=false terra_classic=false terr
Tilt can pretty much be treated as though it's an external environment that you can easily spin up and tear down.
If you've followed the standard setup, all your resources will be bound to various ports on localhost. To see all the endpoints which are being hosted in your Tilt environment, you should check the Tilt dashboard, located at http://localhost:10350/overview.
If you've followed the standard setup, all your resources will be bound to various ports on localhost. To see all the endpoints which are being hosted in your Tilt environment, you should check the Tilt dashboard, located at [http://localhost:10350/overview](http://localhost:10350/overview).
Tilt is actually referred to as 'Devnet' in the Wormhole ecosystem, so anywhere you see information labeled as 'Devnet', you can apply it to Tilt.
Tilt is alos referred to as 'Devnet' in the Wormhole ecosystem, so anywhere you see information labeled as 'Devnet', you can apply it to Tilt.
For example, you can find all the deployed contract addresses in the 'Devnet' [constants](https://github.com/wormhole-foundation/wormhole/blob/dev.v2/sdk/js/src/utils/consts.ts) of the Wormhole Typescript SDK.
Useful information pertaining to funded wallets & useful private keys can also be found in the [devnet.md](https://github.com/wormhole-foundation/wormhole/blob/dev.v2/docs/devnet.md) file of the docs.
From here, Tilt is quite similar to using Testnet, and you should look at the [Tooling](./tooling.md) page for additional resources.
In order to shut down Tilt, simply run
```
tilt down
```

120
src/technical/env/troubleshooting.md vendored Normal file
View File

@ -0,0 +1,120 @@
# Troubleshooting
Tilt, Kubernetes, and Docker may be new tools for developers entering the Wormhole ecosystem. This section is meant to provide some additional support when setting up the Wormhole Tilt environment.
## macOS Install
## Prerequisites
Having `homebrew` on your system makes the installation really straightforward. You can grab it with:
```sh
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
From there, all the other installs are one-liners.
## Install Go
```sh
brew install go
```
## Install Docker
```sh
brew install docker
```
After installation, go into Docker settings and switch ON `kubernetes`. Also configure Docker to have 4 CPUs and ~16GB of RAM.
## Install Tilt
```sh
brew install tilt
```
## Clone Wormhole Repo and Start Tilt
```sh
git clone --branch dev.v2 https://github.com/certusone/wormhole.git
```
```sh
cd wormhole/
tilt up
```
You'll be able to access the Tilt UI at
`localhost:10350`
## Linux & WSL Install
### Setup Script
If you're using a Debian distro, you should run the [dev-setup.sh](https://github.com/wormhole-foundation/wormhole/blob/dev.v2/scripts/dev-setup.sh) script. Even if you're not using Debian, this script still contains the main steps for setup.
## Regular Setup
### 1. Install Go
```sh
wget https://go.dev/dl/go1.18.1.linux-amd64.tar.gz
rm -rf /usr/local/go && tar -C /usr/local -xzf go1.18.1.linux-amd64.tar.gz
```
### 2. Install Docker
If you're using Linux with a window manager, consider getting Docker Desktop instead of the following command. It comes with Kubernetes built in and you won't need to download `minikube`. It's recommended to have at least 4 CPUs and 16GB RAM dedicated to Docker.
Also, make absolutely sure that you set up Docker as a non-root user.
[https://docs.docker.com/engine/install/ubuntu/#installation-methods](https://docs.docker.com/engine/install/ubuntu/#installation-methods)
### 3. (Docker Desktop Install)
Enable Kubernetes by going into Settings > Kubernetes
### 3. (Non Docker Desktop)
Install [`minikube`](https://minikube.sigs.k8s.io/docs/start/).
Configure minikube:
```
minikube start --driver=docker --kubernetes-version=v1.23.3 --cpus=4 --memory=14G --disk-size=10G --namespace=wormhole
```
Minikube needs to be running for tilt to work, so always make sure to run `minikube start` before you bring up tilt.
### 4. Install Tilt
Install Tilt by copy pasting this into the Terminal:
```sh
curl -fsSL https://raw.githubusercontent.com/tilt-dev/tilt/master/scripts/install.sh | bash
```
### 5. Clone the Wormhole Repo and start Tilt
```sh
git clone --branch dev.v2 https://github.com/wormhole-foundation/wormhole.git
```
If you're running Tilt on your machine:
```sh
cd wormhole/
tilt up
```
If you're running Tilt in a VM, you'll need to pass in some extra flags to enable Tilt to listen to incoming traffic from external addresses:
```sh
cd wormhole
tilt up --host=0.0.0.0 -- --webHost=0.0.0.0
```
You can now access the Tilt UI at either `localhost:10350` or `vm_external_ip:10350`.
If the VM's external IP doesn't work, check firewall and port settings to make sure your VM allows incoming traffic.

63
src/technical/env/wlv.md vendored
View File

@ -1,69 +1,32 @@
# Wormhole Local Validator
- wormhole local validator is a development build of the guardian software
- easy to run, easy to configure. Connect it to whatever blockchain you feel like using, and use some provided scripts to deploy the necessary wormhole contracts
- Newer, still has features being added
# Wormhole Local Validator
## What is Wormhole Local Validator (WLV)?
[Wormhole Local Validator](https://github.com/wormhole-foundation/xdapp-book/tree/main/projects/wormhole-local-validator) is a development build of the Guardian software and designed to be the simplest custom environment - there is a single Guardian running on docker and otherwise a BYOB (Bring Your Own Blockchain) setup.
[Wormhole Local Validator](https://github.com/wormhole-foundation/xdapp-book/tree/main/projects/wormhole-local-validator) is meant to be the simplest custom environment. It consists only of a dockerized Guardian image, and some utility tooling to aid with contract management. This allows you to set it up with any blockchain you'd like.
## Is WLV Right for You?
Here's a succinct list of the pros and cons of the environment, so you can decide if it's the right fit for you.
- Pros
- Lightweight, low system resource demand
- Good iteration times
- Can be added into an existing blockchain development setup
- Lightweight, low system resource demand.
- Fast iteration times.
- Can be added into an existing blockchain development setup.
- Cons
- You may end up reinventing the tilt/testnet environment as you add more components
- You may end up reinventing the tilt/testnet environment as you add more components.
## Setting up Wormhole Local Validator
You will **need** Docker running in order to set up WLV. If you're developing on your computer, you should get [Docker Desktop](https://docs.docker.com/get-docker/); if you're in a headless VM, you should install [Docker Engine](https://docs.docker.com/engine/).
You will need Docker running in order to set up WLV. If you're on desktop, [Docker Desktop](https://docs.docker.com/get-docker/) is generally the best choice, though [Docker Engine](https://docs.docker.com/engine/) works fine too.
To simulate the blockchains that are of interest, you are required to install the software for the validator nodes locally on your comupter or somewhere else to run them. Code to spin up EVM and Solana local validators, as well as scripts to deploy the necessary Wormhole contracts to these local instances, are provided in the repo.
From there, you just need nodes for the blockchains you're interested in developing on. There is code to spin up EVM and Solana local validators included in the WLV project repo, as well as scripts to deploy the necessary Wormhole contracts to your local instances.
---
Further information can be found in the project's [README](https://github.com/wormhole-foundation/xdapp-book/blob/main/projects/wormhole-local-validator/README.md).
Below are instructions to set up a local EVM and Solana environment:
## Troubleshooting
**EVM Chains**
Q: Anvil isn't working
`npm run evm` will set up:
- (2) EVM chains
- Wormhole Chain ID 2 (like ETH)
- Wormhole Chain ID 4 (like BSC)
- (3) Wormhole contracts
- Core Bridge at `0xC89Ce4735882C9F0f0FE26686c53074E09B0D550`
- Token Bridge at `0x0290FB167208Af455bB137780163b7B7a9a10C16`
- NFT Bridge at `0x26b4afb60d6c903165150c6f0aa14f8016be4aec`
- (3) utility contracts
- Test Token (TKN) at `0x2D8BE6BF0baA74e0A907016679CaE9190e80dD0A`
- test NFT at `0x5b9b42d6e4B2e4Bf8d42Eba32D46918e10899B66`
- WETH Contract at `0xDDb64fE46a91D46ee29420539FC25FD07c5FEa3E`
These contracts will use the standard Wormhole test mnemoic (`myth like bonus scare over problem client lizard pioneer submit female collect`) and use the first key for deployment and payment (Public Key: `0x90F8bf6A479f320ead074411a4B0e7944Ea8c9C1`, Private Key: `0x4f3edf983ac636a65a842ce7c78d9aa706d3b113bce9c46f30d7d21715b23b1d`)
**Solana Chains**
`npm run solana` will set up:
- (1) Solana chain
- (2) Wormhole contracts
- Core bridge at `Bridge1p5gheXUvJ6jGWGeCsgPKgnE3YgdGKRVCMY9o`
- Token bridge at `B6RHG3mfcckmrYN1UhmJzyS1XX3fZKbkeUcpJe9Sy3FE`
---
Once you have the dependencies for each blockchain installed and have the chains running, you can run Wormhole.
`npm run wormhole` will pull and run the Wormhole Guardian docker image.
The initial setup for Wormhole Local Validator can take upwards of 500 seconds but after the image is built, bringing it up and down usually takes less than 60 seconds.
## FAQ & Common Questions
- Q: Anvil isn't working
- While we recommend Foundry's Forge tool for compiling and deploying code elsewhere in these docs, we do not at this time recommend using anvil for guardiand; this is because guardiand is spec'd against go-ethereum, and anvil is out of spec for how it reports block headers (non left padding to normalize length), which means go-ethereum reacts abnormally and can't read anvil headers.
- While Foundry's 'forge' tool is the generally recommended tool for EVM contract compilation, anvil isn't currently compatible with guardiand. Anvil reports block headers in a way which is non-compliant with go-ethereum, which means the guardian node can't correctly read anvil headers.