diff --git a/docs/deploy-hyperlane.mdx b/docs/deploy-hyperlane.mdx index 63aac707..f9f2793f 100644 --- a/docs/deploy-hyperlane.mdx +++ b/docs/deploy-hyperlane.mdx @@ -17,7 +17,7 @@ There are five steps in this guide: 2. [Deploy contracts](#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. [Run validators and relayers ](#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. [Send a test message](#4-send-test-messages) to confirm that your relayer is able to deliver messages to and from each pair of chains -5. [Deploy a warp route](#5-deploy-a-warp-route) to send token value, not just messages, across chains +5. [Deploy a warp route](#deploy-a-warp-route) to send token value, not just messages, across chains ## Getting Started @@ -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. @@ -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. diff --git a/docs/guides/deploy-warp-route-UI.mdx b/docs/guides/deploy-warp-route-UI.mdx index 09de822f..eaec3755 100644 --- a/docs/guides/deploy-warp-route-UI.mdx +++ b/docs/guides/deploy-warp-route-UI.mdx @@ -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', @@ -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 @@ -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. \ No newline at end of file +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. \ No newline at end of file diff --git a/docs/guides/deploy-warp-route.mdx b/docs/guides/deploy-warp-route.mdx index 7af4873d..52115ff2 100644 --- a/docs/guides/deploy-warp-route.mdx +++ b/docs/guides/deploy-warp-route.mdx @@ -4,25 +4,36 @@ _Create an interchain route for your token_ A Warp Route is a type of [router](../reference/libraries/router.mdx) application, requiring a `HypERC20` or `HypERC721` token contract to be deployed on each chain you wish to support. -The [CLI](../deploy-hyperlane.mdx) includes a command to configure and deploy a Warp Route for your desired token. +## Prerequisites -## 1. Setup +* [Hyperlane CLI](https://www.npmjs.com/package/@hyperlane-xyz/cli) +* A private key for contract transaction signing -Complete the [CLI](../deploy-hyperlane.mdx) steps and deploy hyperlane `core` and `warp` contracts. - -## 2. Configuration +## 1. Configuration ### Warp Route config -You will need to create a `WarpRouteConfig` in [`hyperlane-deploy/config/warp_tokens.ts`](https://github.com/hyperlane-xyz/hyperlane-deploy/blob/main/config/warp_tokens.ts) to define your Warp Route. This will include information such as: - +To deploy the route, you will need a warp route config file. A valid config will specify: * Which token, on which chain, is this Warp Route being created for? * _Optional:_ Hyperlane connection details including contract addresses for the [mailbox](../reference/messaging/messaging-interface.mdx), [interchain gas](../reference/hooks/interchain-gas.mdx), and [interchain security modules](../reference/ISM/specify-your-ISM.mdx). * _Optional:_ The token standard - fungible tokens using ERC20 or NFTs using ERC721. Defaults to ERC20. +The easiest way to create one is with the CLI's config comamnd: + +```bash +hyperlane config create warp +``` + +:::tip + +If your config looks correct, you can now skip to [Step 2: Deployment](#2-deployment). +Or see below for details on how to define your config manually. + +::: + #### Base -Your `WarpRouteConfig` must have exactly one `base` entry. Here you will configure details about the token for which you are creating a warp route. +Your config must have exactly one `base` entry. Here you will configure details about the token for which you are creating a warp route. * **chainName**: Set this equal to the chain on which your token exists * **type**: Set this to `TokenType.collateral` to create a warp route for an ERC20/ERC721 token, or `TokenType.native` to create a warp route for a native token (e.g. ether) @@ -31,121 +42,69 @@ Your `WarpRouteConfig` must have exactly one `base` entry. Here you will configu #### Synthetics -Your `WarpRouteConfig` must have at least one `synthetics` entry. Here you will configure details about the remote chains supported by your warp route. +Your config must have at least one `synthetics` entry. Here you will configure details about the remote chains supported by your warp route. * **chainName:** Set this equal to the chain on which you want a wrapped version of your token -#### Options +#### Optional fields -You may specify the following optional values in your `base` and `synthetics` entries. If no values are provided, defaults will be populated from `hyperlane-deploy/artifacts/addresses.json` and the [SDK](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/main/typescript/sdk/src/consts/environments/mainnet.json) (if present). +You may specify the following optional values in your `base` and `synthetics` entries. If no values are provided, values from core deployment artifacts will be used, either yours (if provided) or the [SDK's](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/main/typescript/sdk/src/consts/environments/mainnet.json). -* **mailbox:** The address of the the [mailbox](../reference/messaging/messaging-interface.mdx)contract to use to send and receive messages +* **mailbox:** The address of the the [mailbox](../reference/messaging/messaging-interface.mdx) contract to use to send and receive messages * **interchainSecurityModule:** The address of an [interchain security modules](../reference/ISM/specify-your-ISM.mdx) to verify interchain messages * **interchainGasPaymaster:** The address of a [interchain gas payments](../reference/hooks/interchain-gas.mdx) to pay for the gas needed to deliver interchain messages #### Example -An example `WarpRouteConfig` is provided in [`hyperlane-deploy/config/warp_tokens.ts`](https://github.com/hyperlane-xyz/hyperlane-deploy/blob/main/config/warp_tokens.ts)that defines a warp route for a native token between two local chains. - -This Warp Route is secured by the default [interchain security modules](../reference/ISM/specify-your-ISM.mdx) that are set on the `Mailboxes` for those chains. - -```typescript -import { TokenType } from '@hyperlane-xyz/hyperlane-token'; - -import type { WarpRouteConfig } from '../src/warp/config'; - -export const warpRouteConfig: WarpRouteConfig = { - base: { - // Chain name must be in the Hyperlane SDK or in the chains.ts config - chainName: 'anvil1', - type: TokenType.native, // TokenType.native or TokenType.collateral - // If type is collateral, a token address is required: - // address: '0x123...' - - // Optionally, specify owner, mailbox, and interchainGasPaymaster addresses - // If not specified, the Permissionless Deployment artifacts or the SDK's defaults will be used - }, - synthetics: [ - { - chainName: 'anvil2', - - // Optionally, specify owner, mailbox, and interchainGasPaymaster addresses - // If not specified, the Permissionless Deployment artifacts or the SDK's defaults will be used - }, - ], -}; -``` +For a minimal warp config example using local anvil chains, see [`warp-tokens.yaml`](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/main/typescript/cli/examples/warp-tokens.yaml). ### Chain config -The Warp Route deployer will be aware of the connection details (e.g. RPC URL) for many standard chains. +The Warp Route deployment will require basic information about any chains it will be interacting with. If the target chains include any not already in the Hyperlane SDK, you must specify chain metadata for it. -If you would like to deploy a Warp Route to a chain that is not included in the Hyperlane SDK, you can specify a [`ChainMetadata`](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/main/typescript/sdk/src/consts/chainMetadata.ts#L21) entry in [`hyperlane-deploy/config/chains.ts`](https://github.com/hyperlane-xyz/hyperlane-deploy/blob/main/config/chains.ts). +To see what chains are in the SDK, run the following command: -An example has been populated for you for [`anvil`](https://book.getfoundry.sh/anvil/). +```bash +hyperlane chains list +``` -#### Example +To create a chain metadata config for any other chains, run the following command: -An example chain config for a Warp Route is shown below. The `blocks` and `blockExplorers` properties are optional. - -```typescript -export const chains: ChainMap = { - // ----------- Your chains here ----------------- - anvil1: { - name: 'anvil1', - // anvil default chain id - chainId: 31337, - publicRpcUrls: [ - { - http: 'http://localhost:8545', - }, - ], - }, -}; +```bash +hyperlane config create chain ``` -## 3. Deployment +Or you can define the config manually. See the [ChainMetadata type](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/main/typescript/sdk/src/metadata/chainMetadataTypes.ts#L62) for its schema. A minimal example can be found in [`anvil-chains.yaml`](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/main/typescript/cli/examples/anvil-chains.yaml). -Run the following script to deploy your Warp Route. You will need to provide the following arguments: +## 2. Deployment -* `key`: A hexadecimal private key for transaction signing +Run the following command to initiate the warp route deployment: ```bash -DEBUG=hyperlane* yarn ts-node scripts/deploy-warp-routes.ts - --key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 +hyperlane deploy warp ``` -When the command finishes, it will output the list of contracts addresses to `hyperlane-deploy/artifacts/warp-token-addresses.json.` - -The deployer will also output a token list file to `hyperlane-deploy/artifacts/warp-ui-token-list.ts` which can be used to [deploy the UI for your warp route.](deploy-warp-route-UI.mdx). +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. -## 4. Testing +## 3. Testing -Run the following script to test your Warp Route by transferring tokens from one chain to another. You will need to provide the following arguments: - -* `origin`: The name of the chain that you are sending tokens from -* `destination`: The name of the chain that you are sending tokens to -* `wei`: The value of tokens to transfer, in wei -* `recipient`: The address to send the tokens to on the destination chain -* `key`: A hexadecimal private key for transaction signing +You can initiate a test transfer of a single wei with the following command: ```bash -yarn ts-node scripts/test-warp-transfer.ts - --origin anvil1 --destination anvil2 --wei 1 - --recipient 0xac0974bec39a17e36ba4a6b4d238ff944bacb4a5 - --key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 +hyperlane send transfer ``` -If everything goes well, you should see the following output: +If everything goes well, you should see the output similar to the following: ``` Waiting for message delivery on destination chain Waiting for message delivery on destination chain Waiting for message delivery on destination chain -Waiting for message delivery on destination chain -Waiting for message delivery on destination chain -Waiting for message delivery on destination chain Message delivered on destination chain! Confirmed balance increase Warp test transfer complete -``` \ No newline at end of file +``` + +## 4. (Optional) Warp UI + +The Warp UI is a DApp template for interacting with Warp Routes. See the [Warp UI docs](./deploy-warp-route-UI.mdx) for details on how to set it up. diff --git a/docs/reference/applications/warp-routes.mdx b/docs/reference/applications/warp-routes.mdx index 44b75016..395ff63c 100644 --- a/docs/reference/applications/warp-routes.mdx +++ b/docs/reference/applications/warp-routes.mdx @@ -1,18 +1,18 @@ --- -description: Move your token between chains +description: Create token routes between any chains --- # Warp Route Interface -Developers can use Hyperlane's Warp Route Interface to permissionlessly deploy Warp Routes - contracts that allow ERC20 tokens to move effortlessly between chains. +Developers can use Hyperlane to permissionlessly deploy Warp Routes - contracts that allow any ERC20, ERC721, or native tokens to move effortlessly between chains. Unlike other token wrapping protocols, Warp Routes are secured by Hyperlane's modular security protocol, allowing developers to specify the security model that governs the minting, burning, and unwrapping of their interchain token. ### Overview -A Hyperlane Warp Route allows a particular token to be moved between chains according to a security model specified by the deployer. +A Hyperlane Warp Route allows a particular token to be moved between chains according to a security model specified by the deployer. -Each Warp Route consists of one contract deployed on every chain that the token can move between. These contracts use the [Mailbox](../messaging/messaging-interface.mdx) to send interchain messages to one another. +Each Warp Route consists of one contract deployed on every chain that the token can move between. These contracts use the [Mailbox](../messaging/messaging-interface.mdx) to send interchain messages to one another. When a user transfers from the _canonical_ origin chain to a _non-canonical_ destination chain, their tokens are locked in a `HypERC20Collateral` contract, which sends a message to the destination chain to mint wrapped tokens. @@ -45,9 +45,9 @@ interface IHypERC20 is IERC20 { The deployer of a Warp Route can optionally specify the interchain security modules (ISMs) that are used to verify interchain transfer messages. -This means that each Warp Route may have a unique security configuration. Users transferring interchain tokens should understand the trust assumptions of a Route before using it. +This means that each Warp Route may have a unique security configuration. Users transferring interchain tokens should understand the trust assumptions of a Route before using it. -Similarly, Warp front-ends should maintain a list of known Routes so as to avoid recommending an insecure Route. The reference UI supports a minor modification to the [TokenList](https://tokenlists.org/) standard so that curators can create lists of "safe" Routes. +Similarly, Warp front-ends should maintain a curated list of known good routes so as to avoid supporting insecure ones. See the [Warp UI deployment docs](../../guides/deploy-warp-route-UI.mdx) details. ### Deploy your warp route diff --git a/sidebars.js b/sidebars.js index 0c0e8410..0b9bd6a4 100644 --- a/sidebars.js +++ b/sidebars.js @@ -327,25 +327,23 @@ const sidebars = { id: "guides/v2-to-v3-migration", label: "v2 to v3 Migration", }, - /* { type: "category", - label: "Deploy Warp Route", + label: "Deploy a Warp Route", link: { type: 'doc', id: 'guides/deploy-warp-route', }, collapsible: true, - collapsed: true, + collapsed: false, items: [ { type: "doc", id: "guides/deploy-warp-route-UI", - label: "Deploy a Warp Route UI", + label: "Deploy a Warp UI", }, ], }, - */ { type: "doc", id: "guides/create-your-own-ISM",