Skip to content

Commit

Permalink
Merge pull request #27 from hyperlane-xyz/rossy/warp-deploy-updates
Browse files Browse the repository at this point in the history 
Update warp deploy instructions
  • Loading branch information
@jmrossy
jmrossy authored Dec 5, 2023
2 parents 08f9055 + f6ef9f6 commit f1b7e25
Show file tree
Hide file tree
Showing 5 changed files with 102 additions and 160 deletions.
51 changes: 17 additions & 34 deletions docs/deploy-hyperlane.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ There are five steps in this guide:
2. [<b>Deploy contracts</b>](#2-deploy-contracts) to the local chain and to every remote chain with which the local chain will be able to send and receive messages.
3. [<b>Run validators and relayers </b>](#3-run-validators-relayers) using [Kurtosis](https://cloud.kurtosis.com). Validators provide the signatures needed for the Interchain Security Modules you deployed in step 2 and relayers send and receive messages between chains you deployed contracts to in step 2.
4. [<b>Send a test message</b>](#4-send-test-messages) to confirm that your relayer is able to deliver messages to and from each pair of chains
5. [<b>Deploy a warp route</b>](#5-deploy-a-warp-route) to send token value, not just messages, across chains
5. [<b>Deploy a warp route</b>](#deploy-a-warp-route) to send token value, not just messages, across chains

## Getting Started

Expand Down Expand Up @@ -110,16 +110,11 @@ hyperlane config create chain

Now the CLI will know how to interact with all your chains, but it will also need to know how to configure your Interchain Security Module (ISM).

:::info

Note, currently only Multisig-based ISMs are supported by the CLI. More complex ISMs will require manual deployments.

:::

To create a multisig ISM configs, you can define it manually using JSON or YAML (see [example config here](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/v3/typescript/cli/examples/multisig-ism.yaml)), or create it with the following command:

```bash
hyperlane config create multisig
hyperlane config create ism
```

When asked about the multisig type, choose `message id ism`. In the context of this guide, we will be using a 1/1 multisig, so choose a threshold of `1` and enter the address of your key.
Expand Down Expand Up @@ -196,45 +191,33 @@ You can also [run the validators](./operate/validators/run-validators.mdx) and [

## 4. Send test messages

You can check everything is working correctly by sending a test message between each pair of chains.
Use the Hyperlane CLI again to send the message:
You can check everything is working correctly by sending a test message between pairs of chains.
Initiate the message with the CLI. It will ask for a set of core deployment artifacts to use. Select the `core-deployments` JSON file from Step 2.

```
hyperlane send message \
--origin YOUR_ORIGIN
--destination YOUR_DEST
--core PATH_TO_STEP2_ARTIFACTS
--key $PRIVATE_KEY
```bash
hyperlane send message --key $PRIVATE_KEY
```

The `send message` command will inform you when the message is dispatched. After a short wait, a confirmation of delivery will be displayed. If the message delivery times out, it is likely that there's an issue with the Validator or Relayer setup in steps 3 and 4 above.
To troubleshoot start by looking at the origin chain relayer logs. If you need further help, reach out on [Discord](https://discord.gg/hyperlane).
The `send message` command will inform you when the message is dispatched. After a short wait, a confirmation of delivery will be displayed. If the message delivery times out, it is likely that there's an issue with the Validator or Relayer setup in steps 3 and 4 above. To troubleshoot start by looking at the origin chain relayer logs. If you need further help, reach out on [Discord](https://discord.gg/hyperlane).

## Deploy a warp route
## 5. (Optional) Deploy a warp route

Warp routes are a way to send tokens between chains. You can create a simple configuration file such as:
Once messages are being delivered, you can optionally deploy a [Warp Route](./reference/applications/warp-routes.mdx). Warp is toolkit for permissionlessly bridging tokens between any chains. The routes can use native currencies (like `Eth`), or ERC20 tokens (like `USDC`).

```yaml
base:
chainName: goerli
type: native
# address: 0x123... # Required for collateral types
synthetics:
- chainName: ancient8test
# You can optionally set the token metadata, otherwise the base token's will be used
# name: "MySyntheticToken"
# symbol: "MST"
# totalSupply: 10000000
To begin, create a new route config.

```bash
hyperlane config create warp
```

Then all you have to do is deploy the warp route by referencing the existing chain and core artifacts with:
Next, you can deploy the route. As before, the CLI will prompt for a core deployment artifacts file.

```bash
hyperlane deploy warp --key $PRIVATE_KEY --chains ./configs/chain-config.yaml --config ../cli/examples/warp-tokens.yaml --core ./artifacts/core-deployment-2023-11-17-9-36-53.json
hyperlane deploy warp --key $PRIVATE_KEY
```

This command will output a warp-ui config file that you need to use in the next step.
Once finished, the CLI will create two new JSON artifact files: `warp-deployment` and `warp-ui-token-config`. The first contains just addresses for the newly deployed warp router contracts. The second is a config file for the Warp UI, which you can use for the next optional step.

### Deploy the warp UI

We have a template UI for interacting with your warp routes. You can clone the repo at [https://github.com/hyperlane-xyz/hyperlane-warp-ui-template](https://github.com/hyperlane-xyz/hyperlane-warp-ui-template) and follow the instructions in the README to deploy the warp UI. You just have to add the entry from Step 6 warp ui config in the `src/tokens.ts` file, as well as add your chain to the `src/chains.ts` file.
The Warp UI is a DApp template for interacting with Warp Routes. You can clone the [Warp UI repo](https://github.com/hyperlane-xyz/hyperlane-warp-ui-template) and follow the instructions in CUSTOMIZE.md to configure and a new instance. In short, use the `chains.yaml` and `warp-ui-token-config.json` files from the previous steps to provide the UI with the information it needs.
58 changes: 30 additions & 28 deletions docs/guides/deploy-warp-route-UI.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,40 +1,42 @@
# Deploy a UI for your Warp Route

After you [deploy warp route](./deploy-warp-route.mdx), you may want to deploy a front-end UI for interchain token transfers. You can use the [UI template](https://github.com/hyperlane-xyz/hyperlane-warp-ui-template) and customize it to fit your needs.
After you've successfully [deployed a warp route](./deploy-warp-route.mdx), you may want to deploy a front-end UI to faciliate interchain token transfers. You can fork the [Hyperlane Warp UI template](https://github.com/hyperlane-xyz/hyperlane-warp-ui-template) and customize it to fit your needs.

## Configure & Customize the UI

Follow these [instructions](https://github.com/hyperlane-xyz/hyperlane-warp-ui-template/blob/main/CUSTOMIZE.md) for details on how to configure the UI's tokens and change the default branding assets/theme.
Follow the [customization instructions](https://github.com/hyperlane-xyz/hyperlane-warp-ui-template/blob/main/CUSTOMIZE.md) for details on how to configure the UI's tokens and change the default branding assets/theme.

#### Configure Tokens
### Token Config Example

As mentioned in the [customization instructions](https://github.com/hyperlane-xyz/hyperlane-warp-ui-template/blob/main/CUSTOMIZE.md), the UI repo contains a token list (see `./src/consts/tokens.ts)`which must be updated. Here's an example:
Here's an example of a token config for a Warp Route that connects WETH on Goerli (chain ID 5). You can use Typescript, JSON, or YAML configs for your token configs.

```typescript
import { WarpTokenConfig } from '../features/tokens/types';

export const tokenList: WarpTokenConfig = [
{
chainId: 5,
address: '0xb4fbf271143f4fbf7b91a5ded31805e42b2208d6',
hypCollateralAddress: '0x145de8760021c4ac6676376691b78038d3DE9097',
type: 'collateral' // or 'native'
name: 'Weth',
symbol: 'WETH',
decimals: 18,
logoURI: '/logos/weth.png',
},
];

{
// The chain ID of the base chain
chainId: 5,
// The address of the underlying token
address: '0xb4fbf271143f4fbf7b91a5ded31805e42b2208d6',
// The address of the HypERC20Token contract
hypCollateralAddress: '0x145de8760021c4ac6676376691b78038d3DE9097',
// The type, either 'collateral' or 'native'
type: 'collateral'
// The base token name
name: 'Weth',
// The base token symbol
symbol: 'WETH',
// The base token decimals
decimals: 18,
// A path to a token logo image
logoURI: '/logos/weth.png'
}
```

You can replace the `tokens` entry with the output that was written to `hyperlane-deploy/artifacts/warp-ui-token-list.ts` from the [deploy warp route](./deploy-warp-route.mdx) instructions.

#### Configure Chain
#### Chain Config Example

In addition, custom chains also need to be configured, in `./src/consts/chains.ts`. This should be the same configuration as the one used in the [setup](../deploy-hyperlane.mdx) step when deploying Hyperlane as well as the Warp Route. Here's an example:
Chain metadata can also be configured as needed. These are the same configs as the those used with the CLI for any of its deploy or send command (for example, those from the [deploy guide](../deploy-hyperlane.mdx)).

```typescript
{
anvil1: {
chainId: 31337,
name: 'anvil1',
Expand All @@ -46,14 +48,14 @@ anvil1: {
reorgPeriod: 0,
estimateBlockTime: 10,
},
logoURI: '/logo.svg',
},
};
logoURI: '/logo.svg'
}
}
```

### Deploy the UI

Since the UI is a Next.js app, you can use your favorite hosting service to host it. We recommend [Vercel](https://vercel.com), which works very well with Next. [Netlify](https://www.netlify.com) and [Fleek](https://fleek.co) are also a good options.
Since the UI is a Next.js app, you can use your favorite hosting service to host it. We recommend [Vercel](https://vercel.com), which works very well with Next. [AWS Amplify](https://aws.amazon.com/amplify) is another popular option.

* Sign up for [Vercel](https://vercel.com/)
* Create a new project
Expand All @@ -64,4 +66,4 @@ And that's it! Now you and your users can use the UI to send tokens from the col

#### Stranded Whale Problem

A common problem with token bridges like Warp Routes is that a user may transfer a token like USDC to a new chain, but only afterwords realize that they do not have the native gas token to move those tokens anywhere including back. You may consider modifying the UI to warn the users of this situation, or better faucet them some dust of native gas token so improve their experience. You can either do so by modifying the warp route contracts where it holds some balance of the native token and can share that with recipients, or you could build an off-chain service which just observes the[ `ReceivedTransferRemote`](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/11d9d0bf0d5ac9f2f57141e0e7549dd415e0325e/typescript/token/contracts/libs/TokenRouter.sol#L90)transfer the native gas token to the recipient.
A common problem with token bridges like Warp Routes is that a user may transfer a token like USDC to a new chain, but only afterwords realize that they do not have the native gas token to move those tokens anywhere including back. You may consider modifying the UI to warn the users of this situation, or better faucet them some dust of native gas token so improve their experience. You can either do so by modifying the warp route contracts where it holds some balance of the native token and can share that with recipients, or you could build an off-chain service which just observes for [`ReceivedTransferRemote events`](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/main/solidity/contracts/token/libs/TokenRouter.sol) and transfers the native gas token to the recipient.
Loading

0 comments on commit f1b7e25

Please sign in to comment.