fix links

This commit is contained in:
Evan Gray 2022-08-26 18:38:36 -04:00
parent 2b03a1199d
commit 1a4ec5a393
12 changed files with 88 additions and 57 deletions

View File

@ -4,7 +4,7 @@
set -euo pipefail
# dev.v2 for now (until we make a release)
DOCKER_IMAGE="ghcr.io/certusone/guardiand:dev.v2"
DOCKER_IMAGE="ghcr.io/wormhole-foundation/guardiand:dev.v2"
DOCKER_FLAGS=
HOST=

View File

@ -4,5 +4,5 @@
# If it doesn't then clone
if [ ! -d "./wormhole" ]
then
git clone https://github.com/certusone/wormhole
git clone https://github.com/wormhole-foundation/wormhole
fi

View File

@ -1,10 +1,11 @@
# Sending Messages: EVM
To send messages from EVM, first we have to download the Core Bridge interfaces.
To send messages from EVM, first we have to download the Core Bridge interfaces.
We need two interfaces, [IWormhole.sol](https://github.com/certusone/wormhole/raw/dev.v2/ethereum/contracts/interfaces/IWormhole.sol) and [Structs.sol](https://github.com/certusone/wormhole/raw/dev.v2/ethereum/contracts/Structs.sol)
We need two interfaces, [IWormhole.sol](https://github.com/wormhole-foundation/wormhole/raw/dev.v2/ethereum/contracts/interfaces/IWormhole.sol) and [Structs.sol](https://github.com/wormhole-foundation/wormhole/raw/dev.v2/ethereum/contracts/Structs.sol)
In your xdapp-starter, place those files in
In your xdapp-starter, place those files in
```
- chains/
- evm/
@ -28,7 +29,7 @@ import "./Structs.sol";
```
Now, let's create a new contract in our src/ folder `Messenger.sol`. In this contract, we'll also create a uint32 nonce. You can think of this nonce like a message id--it's just a number that lets the receiving contract know if it has already processed a message.
Now, let's create a new contract in our src/ folder `Messenger.sol`. In this contract, we'll also create a uint32 nonce. You can think of this nonce like a message id--it's just a number that lets the receiving contract know if it has already processed a message.
Also, we'll set the consistency level here to 1, because we're just testing and want the Guardians to sign this VAA as soon as they see it. If we were deploying to production, we might want to match this level to the deployed chain's finality guarantees.
@ -40,7 +41,7 @@ pragma solidity ^0.8.0;
import "./Wormhole/IWormhole.sol";
contract Messenger {
//This is the Tilt Devnet address constant.
//This is the Tilt Devnet address constant.
//Replace this address with relevant testnet or mainnet address of the chain you're deploying too.
address private wormhole_core_bridge_address = address(0xC89Ce4735882C9F0f0FE26686c53074E09B0D550);

View File

@ -2,9 +2,9 @@
WARNING: To be able to successfully transfer a token from one chain to another, make sure you [attest](./attestingToken.md) it first. Otherwise the Token may be transferred, but you won't be able to claim it until it's attested.
One challenge that arises for new EVM developers is that, because EVM uses unsigned integers, there's no concept of decimals. Therefore, tokens usually have up to 18 zeros behind them to denote up to 18 decimal places. Wormhole normalizes this to *eight* zeros, with transfer amounts rounded down to the nearest 8th decimal.
One challenge that arises for new EVM developers is that, because EVM uses unsigned integers, there's no concept of decimals. Therefore, tokens usually have up to 18 zeros behind them to denote up to 18 decimal places. Wormhole normalizes this to _eight_ zeros, with transfer amounts rounded down to the nearest 8th decimal.
To wrap the Token Bridge functions in your contract, you can use the Token Bridge interfaces provided under [`projects/evm-tokenbridge/chains/evm/src/Wormhole`](https://github.com/certusone/xdapp-book/tree/main/projects/evm-tokenbridge/chains/evm/src/Wormhole) folder of the xDapp Book repository.
To wrap the Token Bridge functions in your contract, you can use the Token Bridge interfaces provided under [`projects/evm-tokenbridge/chains/evm/src/Wormhole`](https://github.com/wormhole-foundation/xdapp-book/tree/main/projects/evm-tokenbridge/chains/evm/src/Wormhole) folder of the xDapp Book repository.
```solidity
//SPDX-License-Identifier: MIT
@ -18,7 +18,7 @@ contract Treasury {
address private token_bridge_address = address(0x0290FB167208Af455bB137780163b7B7a9a10C16);
ITokenBridge token_bridge = ITokenBridge(token_bridge_address);
address private TKN_address = address(0x2D8BE6BF0baA74e0A907016679CaE9190e80dD0A);
address private TKN_address = address(0x2D8BE6BF0baA74e0A907016679CaE9190e80dD0A);
ERC20PresetMinterPauser TKN = ERC20PresetMinterPauser(TKN_address);
uint32 nonce = 0;
@ -26,7 +26,7 @@ contract Treasury {
function bridgeToken(uint256 amt, uint16 receipientChainId, bytes32 recipient) public returns (uint64 sequence) {
nonce += 1;
return token_bridge.transferTokens(TKN_address, amt, receipientChainId, recipient, 0, nonce);
}
}
function approveTokenBridge(uint256 amt) public returns (bool) {
return TKN.approve(token_bridge_address, amt);
@ -35,46 +35,47 @@ contract Treasury {
```
To transfer a token, first we have to *approve* the Token Bridge to be able to spend that token on our behalf (so it can transfer tokens form our contract to itself). Make sure the `bridgeAmt` properly accounts for decimals in the ERC20 token.
To transfer a token, first we have to _approve_ the Token Bridge to be able to spend that token on our behalf (so it can transfer tokens form our contract to itself). Make sure the `bridgeAmt` properly accounts for decimals in the ERC20 token.
```js
// Here we are approving and transfering 50 tokens. The ERC20 token we are transfering has 18 decimal places.
const bridgeAmt = ethers.utils.parseUnits("50", "18");
await treasury.approveTokenBridge(bridgeAmt, {
gasLimit: 2000000,
gasLimit: 2000000,
});
```
Then we simply call `transfer` to create the transfer VAA and fetch it from the Guardians when it's ready. Note that the target receipient is a Wormhole normalized hex address left-padded to 32 bytes.
Then we simply call `transfer` to create the transfer VAA and fetch it from the Guardians when it's ready. Note that the target receipient is a Wormhole normalized hex address left-padded to 32 bytes.
```js
const targetRecepient = Buffer.from(tryNativeToHexString(targetDeployment.deployedAddress, "ethereum"), 'hex');
const targetRecepient = Buffer.from(
tryNativeToHexString(targetDeployment.deployedAddress, "ethereum"),
"hex"
);
const tx = await (await treasury.bridgeToken(
const tx = await (
await treasury.bridgeToken(
bridgeAmt,
targetNetwork.wormholeChainId,
targetRecepient
)).wait();
)
).wait();
const emitterAddr = getEmitterAddressEth(network.tokenBridgeAddress);
const seq = parseSequenceFromLogEth(tx, network.bridgeAddress);
const vaaURL = `${config.wormhole.restAddress}/v1/signed_vaa/${network.wormholeChainId}/${emitterAddr}/${seq}`;
const vaaURL = `${config.wormhole.restAddress}/v1/signed_vaa/${network.wormholeChainId}/${emitterAddr}/${seq}`;
let vaaBytes = await (await fetch(vaaURL)).json();
while(!vaaBytes.vaaBytes){
console.log("VAA not found, retrying in 5s!");
await new Promise((r) => setTimeout(r, 5000)); //Timeout to let Guardiand pick up log and have VAA ready
vaaBytes = await (await fetch(vaaURL)).json();
while (!vaaBytes.vaaBytes) {
console.log("VAA not found, retrying in 5s!");
await new Promise((r) => setTimeout(r, 5000)); //Timeout to let Guardiand pick up log and have VAA ready
vaaBytes = await (await fetch(vaaURL)).json();
}
```
After we've fetched the VAA, we can call the `completeTransfer()` function on the target chain if it's an EVM.
```js
const completeTransferTx = await targetTokenBridge.completeTransfer(Buffer.from(vaaBytes.vaaBytes, "base64"));
const completeTransferTx = await targetTokenBridge.completeTransfer(
Buffer.from(vaaBytes.vaaBytes, "base64")
);
```

View File

@ -1,6 +1,7 @@
# Linux Devnet Setup
### Experimental Setup Script
There's an experimental one command setup script that should install dependencies for you on Linux and configure everything properly. This is only recommended if you're running headless Linux and unable to use Docker Desktop, as with Docker Desktop you don't need `minikube` and can just enable Kubernetes from Docker.
```sh
@ -12,25 +13,30 @@ cd wormhole/
## 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 sure that you set up docker as a NON ROOT USER!
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 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
```
@ -40,6 +46,7 @@ If you reboot your VM you'll need to run the `minikube start` command again befo
### 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
```
@ -47,22 +54,23 @@ curl -fsSL https://raw.githubusercontent.com/tilt-dev/tilt/master/scripts/instal
### 5. Clone the Wormhole Repo and start Tilt
```sh
git clone --branch dev.v2 https://github.com/certusone/wormhole.git
git clone --branch dev.v2 https://github.com/wormhole-foundation/wormhole.git
```
If you're running tilt on your machine
If you're running tilt on your machine
```sh
cd wormhole/
tilt up
```
If you're running tilt in a VM, we need to pass in some extra flags to enable Tilt to listen to incoming traffic from external addresses.
If you're running tilt in a VM, we 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 your `localhost:10350` or `vm_external_ip:10350`.
You can now access the Tilt UI at either your `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.

View File

@ -1,10 +1,13 @@
# macOS Setup
## Prerequisites
You'll need to have `homebrew` on your system if you don't already. You can grab it with:
```sh
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
## Install Go
```sh
@ -12,13 +15,15 @@ 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.
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
```
@ -26,7 +31,7 @@ brew install tilt
## Clone Wormhole Repo and Start Tilt
```sh
git clone --branch dev.v2 https://github.com/certusone/wormhole.git
git clone --branch dev.v2 https://github.com/wormhole-foundation/wormhole.git
```
```sh
@ -34,5 +39,5 @@ cd wormhole/
tilt up
```
You'll be able to access the Tilt UI at
You'll be able to access the Tilt UI at
`localhost:10350`

View File

@ -1,26 +1,32 @@
# Wormhole Local Validator
The Wormhole Local Validator is available [here](https://github.com/certusone/xdapp-book/tree/main/projects/wormhole-local-validator). Along with the Wormhole Local Validator, this also contains code to spin up EVM and Solana local validators, as well as deployment code to add Wormhole contracts to those new chains.
The Wormhole Local Validator is available [here](https://github.com/wormhole-foundation/xdapp-book/tree/main/projects/wormhole-local-validator). Along with the Wormhole Local Validator, this also contains code to spin up EVM and Solana local validators, as well as deployment code to add Wormhole contracts to those new chains.
## Dependencies
You will need Docker; if you're developing on your computer you should get [Docker Desktop](https://docs.docker.com/get-docker/), but if you're in a headless VM, install [Docker Engine](https://docs.docker.com/engine/). Make sure to have Docker running before you run any of the following commands.
To run EVM chains you will need [Ganache](https://github.com/trufflesuite/ganache#command-line-use).
To run Solana chains you will need [Solana](https://docs.solana.com/cli/install-solana-cli-tools) installed.
To run Solana chains you will need [Solana](https://docs.solana.com/cli/install-solana-cli-tools) installed.
## Run EVM Chains
`npm run evm` will start up two EVM chains with Wormhole Chain ID 2 (like ETH) and Wormhole Chain ID 4 (like BSC) and deploy the Wormhole Core Bridge (`0xC89Ce4735882C9F0f0FE26686c53074E09B0D550`), Token Bridge (`0x0290FB167208Af455bB137780163b7B7a9a10C16`), and NFT Bridge (`0x26b4afb60d6c903165150c6f0aa14f8016be4aec`) contracts to them. They'll also deploy a Test Token (TKN at `0x2D8BE6BF0baA74e0A907016679CaE9190e80dD0A`), test NFT (`0x5b9b42d6e4B2e4Bf8d42Eba32D46918e10899B66`), and WETH Contract (`0xDDb64fE46a91D46ee29420539FC25FD07c5FEa3E`) as well.
They'll use the standard Wormhole test mnemonic (`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`))
They'll use the standard Wormhole test mnemonic (`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`))
## Run Solana Chain
`npm run solana` will start up a Solana chain and load in Core Bridge (`Bridge1p5gheXUvJ6jGWGeCsgPKgnE3YgdGKRVCMY9o`) and Token Bridge (`B6RHG3mfcckmrYN1UhmJzyS1XX3fZKbkeUcpJe9Sy3FE`) accounts.
TODO: Add emitter registrations for token bridge.
## Run Wormhole
After you have the dependencies installed and the chains running, you can run Wormhole.
Simply run `npm run wormhole`, which will pull and run the Wormhole Guardian docker image.
### FAQ & Common Problems
- 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 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.

View File

@ -1,25 +1,29 @@
# EVM Messenger
The EVM messenger project is a simple contract that sends messages from one contract on an EVM chain to its sibling contract on another chain.
The EVM messenger project is a simple contract that sends messages from one contract on an EVM chain to its sibling contract on another chain.
Before you get started with this project, make sure you have a local Wormhole Guardian Network running (either [WLV](../../development/wormhole-local-validator.md) or [Tilt](../../development/tilt/overview.md)). If you're running WLV, you'll also need to spin up EVM0 and EVM1 so there are two EVM chains to send messages back and forth.
Let's break down the files you're going to find in the [evm-messenger](https://github.com/certusone/xdapp-book/tree/main/projects/evm-messenger) folder.
Let's break down the files you're going to find in the [evm-messenger](https://github.com/wormhole-foundation/xdapp-book/tree/main/projects/evm-messenger) folder.
### Chains
The `chains/` folder contains the source code that's actually being deployed to the EVM chain. The `evm/` folder found inside was generated using [`forge init`](https://getfoundry.sh). There are two files of note in this folder, `src/Wormhole/IWormhole.sol` and `src/Messenger.sol`.
The `chains/` folder contains the source code that's actually being deployed to the EVM chain. The `evm/` folder found inside was generated using [`forge init`](https://getfoundry.sh). There are two files of note in this folder, `src/Wormhole/IWormhole.sol` and `src/Messenger.sol`.
The IWormhole file is the Wormhole Core Bridge interface, and is required if your app wants to talk to the Wormhole Core Bridge. It outlines the functions and return values you can expect from the Wormhole contract.
The second file, Messenger, is covered in our breakdown of the EVM code [here](./messenger.md).
### Tests
We have a very simple test script written in bash, but it's less of a test script and more of a happy path walkthrough. It makes uses of Orchestrator.js (see below) to call the functions on our EVM contract in order.
To start, deploy the code, register the applications on each chain and then send a message.
We have a very simple test script written in bash, but it's less of a test script and more of a happy path walkthrough. It makes uses of Orchestrator.js (see below) to call the functions on our EVM contract in order.
To start, deploy the code, register the applications on each chain and then send a message.
### Orchestrator
Orchestrator is a js client that takes arguments from the command line to call various functions on our contract. We'll break down everything orchestator does [here](./client.md).
### xdapp.config.json
This maintains some constants about the chains RPC endpoints, private keys used to deploy code, etc. It also includes the Wormhole RPC endpoint.

View File

@ -1,2 +1,3 @@
# Projects
The projects for this repository are located [here](https://github.com/certusone/xdapp-book/tree/main/projects).
The projects for this repository are located [here](https://github.com/wormhole-foundation/xdapp-book/tree/main/projects).

View File

@ -1,8 +1,7 @@
# Repository
The Wormhole core repository can be found [here](https://github.com/certusone/wormhole).
The Wormhole core repository can be found [here](https://github.com/wormhole-foundation/wormhole).
# Design Documents
Wormhole's component design specifications can be found [here](https://github.com/certusone/wormhole/tree/dev.v2/whitepapers). These outline the reasoning behind design decisions with added technical depth.
Wormhole's component design specifications can be found [here](https://github.com/wormhole-foundation/wormhole/tree/dev.v2/whitepapers). These outline the reasoning behind design decisions with added technical depth.

View File

@ -1,17 +1,23 @@
# Tools
There are various tools in the Wormhole ecosystem that can help you in developing xDapps. Here are a few of the most notable:
# Testnet
Wormhole has deployed Core Bridge, Token Bridge and NFT Bridge contracts on various testnets of the chains connected by Wormhole. You can see the deployed addresses [here](./contracts.md). There's only a single Guardian that oversees the testnets, so you might get a higher rate of missed VAAs than you would on mainnet.
Wormhole has deployed Core Bridge, Token Bridge and NFT Bridge contracts on various testnets of the chains connected by Wormhole. You can see the deployed addresses [here](./contracts.md). There's only a single Guardian that oversees the testnets, so you might get a higher rate of missed VAAs than you would on mainnet.
# Wormhole Explorer
Wormhole Explorer is a tool that will help you parse VAAs after they've been picked up the Guardian network. It's available [here](https://wormholenetwork.com/en/explorer).
Wormhole Explorer is a tool that will help you parse VAAs after they've been picked up the Guardian network. It's available [here](https://wormhole.com/explorer).
# Testnet Bridge UI
If you'd like to try out Portal Bridge on Testnet, there's a UI you can use to attest and transfer tokens for testnet, hosted [here](https://certusone.github.io/wormhole).
# Tilt
If you'd like to try out Portal Bridge on Testnet, there's a UI you can use to attest and transfer tokens for testnet, hosted [here](https://wormhole-foundation.github.io/example-token-bridge-ui/).
# Tilt
Tilt is a Kubernetes based tool that runs a copy of every chain along side a guardian node to create a simulated testing environment. To set it up and test against it, start [here](../development/tilt/overview.md).
# Wormhole SDK
The SDK is a set of Javascript tools to help you do Token Bridge transfers, plus fetch and submit VAAs from one chain to another. You can install it via NPM [here](https://www.npmjs.com/package/@certusone/wormhole-sdk).

View File

@ -28,7 +28,7 @@ If Wormhole were to use threshold signatures, the answer would basically be 'as
All these things considered, 19 seems to be the maximum number and a good tradeoff. If 2/3 of the signatures are needed for consensus, then 13 signatures need to be verified on-chain, which remains reasonable from a gas-cost perspective.
Rather than securing the network with tokenomics, it is better to initially secure the network by involving robust companies which are heavily invested in the success of De-Fi as a whole. The 19 Guardians are not anonymous or small--they are many of the largest and most widely-known validator companies in cryptocurrency. The current list of Guardians can be viewed [here](https://wormholenetwork.com/network/)
Rather than securing the network with tokenomics, it is better to initially secure the network by involving robust companies which are heavily invested in the success of De-Fi as a whole. The 19 Guardians are not anonymous or small--they are many of the largest and most widely-known validator companies in cryptocurrency. The current list of Guardians can be viewed [here](https://wormhole.com/network/)
That's how we end up with the network of 19 Guardians, each with an equal stake and joined in a purpose-built Proof of Authority consensus mechanism. As threshold signatures become better supported, the Guardian set can expand, and once ZKPs are ubiquitous, the Guardian Network will become fully trustless.