From 5c49bd217cad5ebbb6cfb53049fab739235c3727 Mon Sep 17 00:00:00 2001
From: Le Yu <6251863+ltyu@users.noreply.github.com>
Date: Wed, 25 Sep 2024 14:02:58 -0400
Subject: [PATCH 1/5] Rename sidebar title
---
sidebars.js | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/sidebars.js b/sidebars.js
index 8450dfc5..e7af425b 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -389,7 +389,7 @@ const sidebars = {
{
type: "doc",
id: "protocol/warp-routes/warp-routes-yield-routes",
- label: "Warp Routes for Yield Routes",
+ label: "Deploy Yield Routes",
},
{
type: "doc",
From 8dc1bdb45531ad8b69605b0c914463dd96615538 Mon Sep 17 00:00:00 2001
From: Le Yu <6251863+ltyu@users.noreply.github.com>
Date: Wed, 25 Sep 2024 14:03:25 -0400
Subject: [PATCH 2/5] Rework warp route walkthrough. Update yield route
contract names
---
.../warp-routes/warp-routes-types.mdx | 4 +-
.../warp-routes/warp-routes-yield-routes.mdx | 87 ++++++++++---------
2 files changed, 48 insertions(+), 43 deletions(-)
diff --git a/docs/protocol/warp-routes/warp-routes-types.mdx b/docs/protocol/warp-routes/warp-routes-types.mdx
index 5a142bf3..ed51d7fb 100644
--- a/docs/protocol/warp-routes/warp-routes-types.mdx
+++ b/docs/protocol/warp-routes/warp-routes-types.mdx
@@ -90,9 +90,9 @@ See [the implementation](https://github.com/hyperlane-xyz/hyperlane-monorepo/blo
Combines fast transfer capabilities with collateral-backed ERC20 functionality. See [the implementation](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/main/solidity/contracts/token/extensions/FastHypERC20Collateral.sol) for more details.
-### 2. Vault Integration (HypERC20CollateralVaultDeposit)
+### 2. Vault Integration (HypERC4626OwnerCollateral)
-Allows for yield generation on collateral by integrating with ERC-4626 vaults. See [the implementation](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/main/solidity/contracts/token/extensions/HypERC20CollateralVaultDeposit.sol) for more details.
+Allows for yield generation on collateral by integrating with ERC-4626 vaults. See [the implementation](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/main/solidity/contracts/token/extensions/HypERC4626OwnerCollateral.sol) for more details.
### 3. Fiat-Backed Tokens (HypFiatToken)
diff --git a/docs/protocol/warp-routes/warp-routes-yield-routes.mdx b/docs/protocol/warp-routes/warp-routes-yield-routes.mdx
index 564bdea6..5c887989 100644
--- a/docs/protocol/warp-routes/warp-routes-yield-routes.mdx
+++ b/docs/protocol/warp-routes/warp-routes-yield-routes.mdx
@@ -1,67 +1,72 @@
-# Warp Routes: Yield Routes
+# Deploy Yield Routes
-The goal of this guide is to illustrate how you can use Hyperlane warp routes to create yield-generating bridges, ensuring idle bridged assets are still productive by compounding yield over time.
+The goal of this guide is to illustrate how you can use Hyperlane warp routes to create yield-generating bridges, ensuring idle bridged assets are productive by compounding yield over time.
## Primary Motives
-1. Enable yield-generating warp routes via yield-bearing collateral vaults.
+Enable yield-generating warp routes via yield-bearing collateral vaults.
## Pre-Requisites
To complete the following walkthrough, you should have the following available:
1. An origin and destination network of choice, between which you’d like to deploy the yield route.
-2. The address of a funded [ERC-4626 vault](https://ethereum.org/en/developers/docs/standards/tokens/erc-4626/) on the origin network. This vault’s underlying asset will also be set as the collateral for the warp route (e.g. if vault is USDC funded, the warp route will also support USDC transfer).
+2. The address of an [ERC-4626 vault](https://ethereum.org/en/developers/docs/standards/tokens/erc-4626/) on the origin network from which you want yield to be generated. This vault’s underlying asset will be set as the collateral for the warp route (e.g. if vault is USDC funded, the warp route will also support USDC transfer).
3. An installed instance of the [Hyperlane CLI](https://docs.hyperlane.xyz/docs/reference/cli) and a wallet private key set as the `HYP_KEY` env var funded on your origin and destination networks.
## Walkthrough: Create a Yield Route
### Concepts
-- **ERC-4626 Vault**: The Ethereum standard for tokenized yield-bearing vaults, representing shares of an single ERC20 token of choice.
-- **EvmHypCollateralVault (HypERC20CollateralVaultDeposit)**: The Hyperlane representation of a yield-bearing EVM collateral token. Note that the yield route’s vault’s deposited asset address is used as the warp routes collateral token.
+- **ERC-4626 Vault**: The Ethereum standard for tokenized yield-bearing vaults. Upon deposit, share tokens are minted representing ownership of the underlying asset.
+- **Yield Route (EvmHypOwnerCollateral & EvmHypSynthetic)**: The Hyperlane representation of a yield-bearing EVM collateral token. Note that the yield route’s vault’s deposited asset address is used as the warp routes collateral token.
:::info
-For the sake of this example, the “origin” network will refer to the network on which the vault is present (e.g. yourchain is the origin with a USDC vault).
+For the sake of this walkthrough, the “origin” network will refer to the network on which the yield is generated (e.g. ethereum has a USDC lending vault that has claimable yield. A synthetic USDC is minted on the destination chain called yourchain).
:::
-### Steps
-
-Using the Hyperlane CLI, deploy a yourchain `USDC` EvmHypCollateralVault ↔ ethereum `USDC` EvmHypSynthetic warp route:
- 1. Run `hyperlane warp init` and complete the following flow:
+Below is the bridging flow between ethereum and yourchain
+
+**Bridge USDC: ethereum → yourchain**
+
+```mermaid
+flowchart LR
+ A[ethereum:
Alice] -->|Deposit USDC| B[yourchain:
EvmHypOwnerCollateral]
+ B -->|USDC Deposit into Vault| C[ethereum:
ERC-4626 Vault]
+ C -->|Yield Generation| C
+ B ==>|Bridge| E[yourchain:
EvmHypSynthetic]
+ E -->|Mint Synthetic USDC| F[yourchain:
Alice]
+ C[ethereum:
ERC-4626 Vault] -->|Withdraw Yield| G[ethereum:
Vault Owner]
+```
+In this example, Alice wants to bridge USDC between ethereum and yourchain. The yield route will transfer her USDC to a yield-bearing ERC-4626 vault, and then mint her synthetic USDC on yourchain. Notice that the yield route owner can claim yields generated from that vault.
+
+**Bridge USDC: yourchain → ethereum**
+
+```mermaid
+flowchart LR
+ A[yourchain:
Alice] -->|Burn Synthetic USDC| B[yourchain:
EvmHypSynthetic]
+ B ==>|Bridge| C[ethereum:
EvmHypOwnerCollateral]
+ D[ethereum:
ERC-4626 Vault] -->|USDC Withdraw from Vault| C
+ C -->|Withdraw USDC| F[ethereum:
Alice]
+
+```
+When Alice wants to bridge back to ethereum, the reverse happens. The yield route will burn her synthetic USDC, withdraw the USDC from the vault on ethereum, and return her USDC.
+
+### Yield Route Deployment Steps
+
+Using the Hyperlane CLI, deploy a USDC EvmHypOwnerCollateral and EvmHypSynthetic tokens on ethereum and yourchain, respectively:
+ 1. Run `hyperlane warp init` to generate a warp route config:
1. Select `yourchain` and `ethereum` using space, and hit enter.
- 2. For yourchain, select `collateralVault`, accept the mailbox, and enter the USDC vault address on yourchain.
- 3. For ethereum, select `synthetic` and accept the mailbox.
- 2. Run `hyperlane warp deploy` and confirm the warp deploy config is as expected.
- 3. Your newly deployed yield route can now accomplish the following:
- 1. Transfer USDC: yourchain → ethereum
-
- ```mermaid
- flowchart LR
- A[yourchain:
Alice] -->|Deposit USDC| B[yourchain:
EvmHypCollateralVault]
- B -->|Deposit into Vault| C[yourchain:
ERC-4626 Vault]
- C -->|Yield Generation| C
- B ==>|Bridge| E[ethereum:
EvmHypSynthetic]
- E -->|Mint Synthetic USDC| F[ethereum:
Alice]
- C[yourchain:
ERC-4626 Vault] <-->|Withdraw Yield| G[yourchain:
Vault Owner]
- ```
-
- 2. Transfer USDC: ethereum → yourchain
-
- ```mermaid
- flowchart LR
- A[ethereum:
Alice] -->|Burn Synthetic USDC| B[ethereum:
EvmHypSynthetic]
- B ==>|Bridge| C[yourchain:
EvmHypCollateralVault]
- D[yourchain:
ERC-4626 Vault] -->|Withdraw from Vault| C
- C -->|Withdraw USDC| F[yourchain:
Alice]
- G[yourchain:
Vault Owner] <-->|Withdraw Yield| D
- ```
-
+ 2. For ethereum, select `collateralVault`, accept the mailbox, and enter the USDC vault address on yourchain.
+ - Alternatively, you can select `collateralVaultRebase` which is a yield route variant that distribute yields to users by increasing their holding amount.
+ 3. For yourchain, select `synthetic` and accept the mailbox.
+ - If you selected `collateralVaultRebase`, you must pair it with a `syntheticRebase`
+ 2. Run `hyperlane warp deploy` to deploy the warp route.
-:::info
-💡 Please note that (at the time of writing) it is only possible for the owner to collect vault generated yield, and pro-rata user claims on yield are coming to yield routes soon.
-:::
+For more in-depth details on these steps, follow the [Bridge a Token](/docs/guides/deploy-warp-route) guide.
+### Claiming Yield
+Depending on the yield route variant, yield can be claimed by either calling `HypERC4626OwnerCollateral.sweep()` or `HypERC4626Collateral.rebase()` on their respective contracts.
**🎉 Congrats! You have now created a new yield route with your vault. Bridged user assets can now earn passive yield while present in the origin warp route.**
From e514753ee1a0c1d43b9f9127db326793d354bb66 Mon Sep 17 00:00:00 2001
From: Le Yu <6251863+ltyu@users.noreply.github.com>
Date: Wed, 25 Sep 2024 14:10:55 -0400
Subject: [PATCH 3/5] Add rebasing variant to types
---
docs/protocol/warp-routes/warp-routes-types.mdx | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/protocol/warp-routes/warp-routes-types.mdx b/docs/protocol/warp-routes/warp-routes-types.mdx
index ed51d7fb..e0b2465a 100644
--- a/docs/protocol/warp-routes/warp-routes-types.mdx
+++ b/docs/protocol/warp-routes/warp-routes-types.mdx
@@ -90,9 +90,9 @@ See [the implementation](https://github.com/hyperlane-xyz/hyperlane-monorepo/blo
Combines fast transfer capabilities with collateral-backed ERC20 functionality. See [the implementation](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/main/solidity/contracts/token/extensions/FastHypERC20Collateral.sol) for more details.
-### 2. Vault Integration (HypERC4626OwnerCollateral)
+### 2. Vault Integration (HypERC4626OwnerCollateral, HypERC4626Collateral)
-Allows for yield generation on collateral by integrating with ERC-4626 vaults. See [the implementation](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/main/solidity/contracts/token/extensions/HypERC4626OwnerCollateral.sol) for more details.
+Allows for yield generation on collateral by integrating with ERC-4626 vaults. See [the implementation](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/main/solidity/contracts/token/extensions/HypERC4626OwnerCollateral.sol) & [rebasing variant](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/main/solidity/contracts/token/extensions/HypERC4626Collateral.sol) and for more details.
### 3. Fiat-Backed Tokens (HypFiatToken)
From 23d9db6d3c0b5cdeca959024785e56dd38a65796 Mon Sep 17 00:00:00 2001
From: Le Yu <6251863+ltyu@users.noreply.github.com>
Date: Wed, 25 Sep 2024 14:13:57 -0400
Subject: [PATCH 4/5] Remove extranous wording
---
docs/protocol/warp-routes/warp-routes-yield-routes.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/protocol/warp-routes/warp-routes-yield-routes.mdx b/docs/protocol/warp-routes/warp-routes-yield-routes.mdx
index 5c887989..aad1c427 100644
--- a/docs/protocol/warp-routes/warp-routes-yield-routes.mdx
+++ b/docs/protocol/warp-routes/warp-routes-yield-routes.mdx
@@ -14,7 +14,7 @@ To complete the following walkthrough, you should have the following available:
2. The address of an [ERC-4626 vault](https://ethereum.org/en/developers/docs/standards/tokens/erc-4626/) on the origin network from which you want yield to be generated. This vault’s underlying asset will be set as the collateral for the warp route (e.g. if vault is USDC funded, the warp route will also support USDC transfer).
3. An installed instance of the [Hyperlane CLI](https://docs.hyperlane.xyz/docs/reference/cli) and a wallet private key set as the `HYP_KEY` env var funded on your origin and destination networks.
-## Walkthrough: Create a Yield Route
+## Walkthrough
### Concepts
From f1e35186a11fc192ea294db8f2cb551f87a12f4d Mon Sep 17 00:00:00 2001
From: Le Yu <6251863+ltyu@users.noreply.github.com>
Date: Wed, 25 Sep 2024 14:18:59 -0400
Subject: [PATCH 5/5] Add more details for rebasing yield route
---
docs/protocol/warp-routes/warp-routes-yield-routes.mdx | 7 ++-----
1 file changed, 2 insertions(+), 5 deletions(-)
diff --git a/docs/protocol/warp-routes/warp-routes-yield-routes.mdx b/docs/protocol/warp-routes/warp-routes-yield-routes.mdx
index aad1c427..4bdcacb6 100644
--- a/docs/protocol/warp-routes/warp-routes-yield-routes.mdx
+++ b/docs/protocol/warp-routes/warp-routes-yield-routes.mdx
@@ -1,10 +1,6 @@
# Deploy Yield Routes
-The goal of this guide is to illustrate how you can use Hyperlane warp routes to create yield-generating bridges, ensuring idle bridged assets are productive by compounding yield over time.
-
-## Primary Motives
-
-Enable yield-generating warp routes via yield-bearing collateral vaults.
+The goal of this guide is to illustrate how you can use Hyperlane warp routes to create yield-generating bridges, ensuring idle bridged assets are productive by compounding yield over time. Depending on the variant (more details below), yields are distributed to the yield route owner or users.
## Pre-Requisites
@@ -20,6 +16,7 @@ To complete the following walkthrough, you should have the following available:
- **ERC-4626 Vault**: The Ethereum standard for tokenized yield-bearing vaults. Upon deposit, share tokens are minted representing ownership of the underlying asset.
- **Yield Route (EvmHypOwnerCollateral & EvmHypSynthetic)**: The Hyperlane representation of a yield-bearing EVM collateral token. Note that the yield route’s vault’s deposited asset address is used as the warp routes collateral token.
+ - This specific yield route variant distributes vault yields to the **owner**. There is an alternative setup where yields are distributed to the users (EvmHypCollateral & EvmHypSyntheticRebase). For most of this guide, we will refer to the former variants. The concepts remain the same.
:::info
For the sake of this walkthrough, the “origin” network will refer to the network on which the yield is generated (e.g. ethereum has a USDC lending vault that has claimable yield. A synthetic USDC is minted on the destination chain called yourchain).