From d2f04ecc62b1f14d4538c51a2b23120fad8ca6e4 Mon Sep 17 00:00:00 2001
From: edakturk14 <edakturk96@gmail.com>
Date: Mon, 17 Mar 2025 14:19:12 -0400
Subject: [PATCH 1/6] Multicollateral warp route guide
---
docs/guides/multicollateral-warp-route.mdx | 176 +++++++++++++++++++++
sidebars.js | 5 +
2 files changed, 181 insertions(+)
create mode 100644 docs/guides/multicollateral-warp-route.mdx
diff --git a/docs/guides/multicollateral-warp-route.mdx b/docs/guides/multicollateral-warp-route.mdx
new file mode 100644
index 00000000..31399494
--- /dev/null
+++ b/docs/guides/multicollateral-warp-route.mdx
@@ -0,0 +1,176 @@
+# Multicollateral Warp Route Rebalancing
+
+## Overview
+
+A **Multicollateral Warp Route** is a way to bridge multiple existing tokens across different chains while maintaining liquidity. Instead of introducing a new synthetic asset for every transfer, it allows chains to leverage existing token liquidity in a structured manner.
+
+This is useful when expanding to new chains, ensuring users have access to assets that already exist in the ecosystem. The diagram below shows a setup where canonical USDC exists on Base and Arbitrum, with a synthetic warp route created on a new chain.
+
+```mermaid
+flowchart
+ subgraph base
+ BU((User))
+ BWR[USDC Collateral Warp Route]
+ end
+
+ subgraph arbitrum
+ AU((User))
+ AWR[USDC Collateral Warp Route]
+ end
+
+ subgraph newchain
+ NWR[USDC Synthetic Warp Route]
+ Recipient((Recipient))
+ end
+
+ BU -- "transferRemote(newchain,<br>recipient, amount)" --> BWR
+ BWR -. "{recipient, amount}" .-> NWR
+ AU -- "transferRemote(newchain,<br>recipient, amount)" --> AWR
+ AWR -. "{recipient, amount}" .-> NWR
+ NWR -. "2 \* amount" .-> Recipient
+```
+
+### Collateral Imbalances
+
+If more funds flow in one direction, one of the chains in the route can run out of collateral. This _imbalanced flow_ prevents withdrawals until liquidity is restored.
+
+To fix this and mantain a good user experience we must perform _collateral rebalancing_,collateral must be moved between chains to restore balance. Liquidity providers (LPs) can supply liquidity to address these imbalances.
+
+```mermaid
+flowchart
+ subgraph base
+ BWR[USDC Collateral Warp Route]
+ end
+
+ subgraph arbitrum
+ AWR[USDC Collateral Warp Route]
+ end
+
+ subgraph newchain
+ NWR[USDC Synthetic Warp Route]
+ NU((Recipient))
+ end
+
+ NU -- "transferRemote(arbitrum,<br> recipient, 2 * amount)" --> NWR
+ NWR -. "{recipient, 2 * amount}" .-> AWR
+```
+
+## Liquidity Provider
+
+Currently, Warp Routes don’t have an explicit liquidity provider interface that enables local deposits/withdrawals. However, LPs can manually manage liquidity using the [Hyperlane CLI](https://www.npmjs.com/package/@hyperlane-xyz/cli) to interact with the Warp Routes in the [Hyperlane registry](https://github.com/hyperlane-xyz/hyperlane-registry).
+
+:::warning
+The stopgap procedure defined before requires at least one synthetic chain to exist within the warp route topology.
+:::
+
+- To inspect a warp route’s topology, use the `warp read` command
+
+```
+hyperlane warp read --symbol ETH
+
+ethereum:
+ type: native
+ ...
+base:
+ type: native
+ ...
+bsc:
+ type: synthetic
+ ...
+```
+
+- To send a transfer (`transferRemote`) on a warp route, use the `warp send` command
+
+```
+hyperlane warp send \
+ --symbol ETH \
+ --origin base \
+ --destination bsc \
+ --amount <AMOUNT> \
+ --recipient <ADDRESS>
+```
+
+### Depositing Liquidity
+
+LPs can deposit collateral via a `transferRemote` where:
+
+- the `destination` domain is a chain where the warp route has a `synthetic` type
+- the `recipient` address is controlled by the LP
+- the `amount` is liquidity denominated in the `origin` chains `collateral` token
+
+```mermaid
+flowchart
+ LP((Liquidity Provider))
+
+ subgraph arbitrum
+ AWR[USDC Collateral Warp Route]
+ AUSDC[USDC]
+ end
+
+ subgraph newchain
+ MWR[USDC Synthetic Warp Route]
+ end
+
+ AWR -- "transferFrom(LP, amount)" --> AUSDC
+ LP -. "amount" .-> AWR
+ LP -- "transferRemote(newchain,<br>LP, amount)" --> AWR
+
+ AWR -. "{LP, amount}" .-> MWR
+ MWR -. "amount" .-> LP
+```
+
+### Withdrawing Liquidity
+
+LPs can withdraw via a `transferRemote` where
+
+- the `destination` domain is a chain where the warp route is a `collateral` type
+- the `recipient` address is controlled by the LP
+- the `amount` is denominated in the `destination` chains `collateral` token
+
+```mermaid
+flowchart
+ LP((Liquidity Provider))
+
+ subgraph arbitrum
+ AWR[USDC Collateral Warp Route]
+ AUSDC[USDC]
+ end
+
+ subgraph newchain
+ MWR[USDC Synthetic Warp Route]
+ end
+
+ LP -- "transferRemote(arbitrum, LP, amount)" --> MWR
+ LP -. "amount" .-> MWR
+
+ MWR -. "{LP, amount}" .-> AWR
+ AWR -- "transfer(LP, amount)" --> AUSDC
+ AWR -. "amount" .-> LP
+```
+
+## Admin-Controlled Liquidity Rebalancing
+
+Instead of relying on individual LPs, an admin can rebalance liquidity by moving collateral between warp route contracts. For example, CCTP (Circle’s Cross-Chain Transfer Protocol) can efficiently move USDC between Base and Arbitrum.
+
+```mermaid
+flowchart
+ subgraph base
+ BR((Rebalancer))
+ BWR[USDC Collateral Warp Route]
+ BCCTP[CCTP]
+ BUSDC[USDC]
+ end
+
+ subgraph arbitrum
+ AWR[USDC Collateral Warp Route]
+ ACCTP[CCTP]
+ AUSDC[USDC]
+ end
+
+ BR -- "transferCollateral(arbitrum,<br>amount)" --> BWR
+ BWR -- "send(arbitrum, amount, router)" --> BCCTP
+ BCCTP -- "burn(amount)" --> BUSDC
+ BCCTP -. "{amount, router}" .-> ACCTP
+ ACCTP -- "mint(amount, router}" --> AUSDC
+ AUSDC -. "amount" .-> AWR
+```
diff --git a/sidebars.js b/sidebars.js
index 0ecb658a..08681acc 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -134,6 +134,11 @@ const sidebars = {
id: "guides/manage-warp-route-limits",
label: "Mangaging Warp Route Limits",
},
+ {
+ type: "doc",
+ id: "guides/multicollateral-warp-route",
+ label: "Multicollateral Warp Route Rebalancing",
+ },
],
},
{
From 0486dd199fc86477136cf6ca2ae1d9d881b1e9a7 Mon Sep 17 00:00:00 2001
From: edakturk14 <edakturk96@gmail.com>
Date: Mon, 17 Mar 2025 14:38:42 -0400
Subject: [PATCH 2/6] nitpicks
---
docs/guides/multicollateral-warp-route.mdx | 48 +++++++++++-----------
1 file changed, 25 insertions(+), 23 deletions(-)
diff --git a/docs/guides/multicollateral-warp-route.mdx b/docs/guides/multicollateral-warp-route.mdx
index 31399494..7aca51be 100644
--- a/docs/guides/multicollateral-warp-route.mdx
+++ b/docs/guides/multicollateral-warp-route.mdx
@@ -32,9 +32,7 @@ flowchart
### Collateral Imbalances
-If more funds flow in one direction, one of the chains in the route can run out of collateral. This _imbalanced flow_ prevents withdrawals until liquidity is restored.
-
-To fix this and mantain a good user experience we must perform _collateral rebalancing_,collateral must be moved between chains to restore balance. Liquidity providers (LPs) can supply liquidity to address these imbalances.
+If more funds flow in one direction, one of the chains in the route can run out of collateral. This _imbalanced flow_ prevents withdrawals until the collateral is covered.
```mermaid
flowchart
@@ -55,31 +53,33 @@ flowchart
NWR -. "{recipient, 2 * amount}" .-> AWR
```
+To fix this and mantain a good user experience we must perform _collateral rebalancing_, collateral must be moved between chains to restore balance. An aligned actor may assue a traditional Liquidity Provider (LP) role and provide collateral to address these imbalances using their own inventory.
+
## Liquidity Provider
Currently, Warp Routes don’t have an explicit liquidity provider interface that enables local deposits/withdrawals. However, LPs can manually manage liquidity using the [Hyperlane CLI](https://www.npmjs.com/package/@hyperlane-xyz/cli) to interact with the Warp Routes in the [Hyperlane registry](https://github.com/hyperlane-xyz/hyperlane-registry).
:::warning
-The stopgap procedure defined before requires at least one synthetic chain to exist within the warp route topology.
+The stopgap procedure defined below requires at least one synthetic chain to exist within the warp route topology.
:::
-- To inspect a warp route’s topology, use the `warp read` command
+- To inspect a Warp Route’s topology, use the `warp read` command:
```
hyperlane warp read --symbol ETH
ethereum:
- type: native
- ...
+ type: native
+ ...
base:
- type: native
- ...
+ type: native
+ ...
bsc:
- type: synthetic
- ...
+ type: synthetic
+ ...
```
-- To send a transfer (`transferRemote`) on a warp route, use the `warp send` command
+- To send a transfer (`transferRemote`) on a Warp Route, use the `warp send` command:
```
hyperlane warp send \
@@ -94,9 +94,9 @@ hyperlane warp send \
LPs can deposit collateral via a `transferRemote` where:
-- the `destination` domain is a chain where the warp route has a `synthetic` type
-- the `recipient` address is controlled by the LP
-- the `amount` is liquidity denominated in the `origin` chains `collateral` token
+- `destination` domain is a chain where the warp route has a `synthetic` type
+- `recipient` address is controlled by the LP
+- `amount` is liquidity denominated in the `origin` chains `collateral` token
```mermaid
flowchart
@@ -107,7 +107,7 @@ flowchart
AUSDC[USDC]
end
- subgraph newchain
+ subgraph mychain
MWR[USDC Synthetic Warp Route]
end
@@ -119,13 +119,15 @@ flowchart
MWR -. "amount" .-> LP
```
+This can be done for providing liquidity on many collateral chains and representing a claim on each collateral with a single synthetic asset balance.
+
### Withdrawing Liquidity
LPs can withdraw via a `transferRemote` where
-- the `destination` domain is a chain where the warp route is a `collateral` type
-- the `recipient` address is controlled by the LP
-- the `amount` is denominated in the `destination` chains `collateral` token
+- `destination` domain is a chain where the warp route is a `collateral` type
+- `recipient` address is controlled by the LP
+- `amount` is denominated in the `destination` chains `collateral` token
```mermaid
flowchart
@@ -136,11 +138,11 @@ flowchart
AUSDC[USDC]
end
- subgraph newchain
+ subgraph mychain
MWR[USDC Synthetic Warp Route]
end
- LP -- "transferRemote(arbitrum, LP, amount)" --> MWR
+ LP -- "transferRemote(arbitrum,<br>LP, amount)" --> MWR
LP -. "amount" .-> MWR
MWR -. "{LP, amount}" .-> AWR
@@ -148,9 +150,9 @@ flowchart
AWR -. "amount" .-> LP
```
-## Admin-Controlled Liquidity Rebalancing
+## Future: Admin-Controlled Liquidity Rebalancing
-Instead of relying on individual LPs, an admin can rebalance liquidity by moving collateral between warp route contracts. For example, CCTP (Circle’s Cross-Chain Transfer Protocol) can efficiently move USDC between Base and Arbitrum.
+Depending on the collateral asset and the pair of chains, several different rebalancing paths may be available. For example, CCTP (Circle’s Cross-Chain Transfer Protocol) can efficiently move USDC between Base and Arbitrum. Other assets and pairs may require more complex rebalancing paths (eg L2 withdrawals+deposits). This approach requires a permissioned rebalancer to move the collateral over trusted paths.
```mermaid
flowchart
From fb271fb868d5f7d0f0363b053ef588a76ddc4736 Mon Sep 17 00:00:00 2001
From: edakturk14 <edakturk96@gmail.com>
Date: Wed, 19 Mar 2025 20:15:44 -0400
Subject: [PATCH 3/6] review fixes
---
docs/guides/multicollateral-warp-route.mdx | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/docs/guides/multicollateral-warp-route.mdx b/docs/guides/multicollateral-warp-route.mdx
index 7aca51be..8b3b837b 100644
--- a/docs/guides/multicollateral-warp-route.mdx
+++ b/docs/guides/multicollateral-warp-route.mdx
@@ -53,11 +53,11 @@ flowchart
NWR -. "{recipient, 2 * amount}" .-> AWR
```
-To fix this and mantain a good user experience we must perform _collateral rebalancing_, collateral must be moved between chains to restore balance. An aligned actor may assue a traditional Liquidity Provider (LP) role and provide collateral to address these imbalances using their own inventory.
+To fix this and maintain a good user experience, we must perform _collateral rebalancing_; collateral may need to be moved between chains or sourced from local inventory to restore balance. An aligned actor may assume a traditional Liquidity Provider (LP) role and provide collateral to address these imbalances using their inventory.
## Liquidity Provider
-Currently, Warp Routes don’t have an explicit liquidity provider interface that enables local deposits/withdrawals. However, LPs can manually manage liquidity using the [Hyperlane CLI](https://www.npmjs.com/package/@hyperlane-xyz/cli) to interact with the Warp Routes in the [Hyperlane registry](https://github.com/hyperlane-xyz/hyperlane-registry).
+Currently, Warp Routes don’t have an explicit liquidity provider interface that enables local deposits/withdrawals. However, LPs can manually manage liquidity using the [Hyperlane CLI](https://www.npmjs.com/package/@hyperlane-xyz/cli) or the UI to interact with the Warp Routes in the [Hyperlane registry](https://github.com/hyperlane-xyz/hyperlane-registry).
:::warning
The stopgap procedure defined below requires at least one synthetic chain to exist within the warp route topology.
@@ -119,7 +119,7 @@ flowchart
MWR -. "amount" .-> LP
```
-This can be done for providing liquidity on many collateral chains and representing a claim on each collateral with a single synthetic asset balance.
+This can be done by providing liquidity on many collateral chains and representing a claim on each collateral with a single synthetic asset balance.
### Withdrawing Liquidity
@@ -152,7 +152,7 @@ flowchart
## Future: Admin-Controlled Liquidity Rebalancing
-Depending on the collateral asset and the pair of chains, several different rebalancing paths may be available. For example, CCTP (Circle’s Cross-Chain Transfer Protocol) can efficiently move USDC between Base and Arbitrum. Other assets and pairs may require more complex rebalancing paths (eg L2 withdrawals+deposits). This approach requires a permissioned rebalancer to move the collateral over trusted paths.
+Depending on the collateral asset and the pair of chains, several different rebalancing paths may be available. For example, CCTP (Circle’s Cross-Chain Transfer Protocol) can efficiently move USDC between Base and Arbitrum. Other assets and pairs may require more complex rebalancing paths (e.g.: L2 withdrawals+deposits). This approach requires a permissioned rebalancer to move the collateral over trusted paths.
```mermaid
flowchart
From 3361892b0b53a5f65dca1f41dfe54ec5e25950cd Mon Sep 17 00:00:00 2001
From: edakturk14 <edakturk96@gmail.com>
Date: Thu, 20 Mar 2025 10:08:04 -0400
Subject: [PATCH 4/6] remove future section
---
docs/guides/multicollateral-warp-route.mdx | 27 ----------------------
1 file changed, 27 deletions(-)
diff --git a/docs/guides/multicollateral-warp-route.mdx b/docs/guides/multicollateral-warp-route.mdx
index 8b3b837b..cd643310 100644
--- a/docs/guides/multicollateral-warp-route.mdx
+++ b/docs/guides/multicollateral-warp-route.mdx
@@ -149,30 +149,3 @@ flowchart
AWR -- "transfer(LP, amount)" --> AUSDC
AWR -. "amount" .-> LP
```
-
-## Future: Admin-Controlled Liquidity Rebalancing
-
-Depending on the collateral asset and the pair of chains, several different rebalancing paths may be available. For example, CCTP (Circle’s Cross-Chain Transfer Protocol) can efficiently move USDC between Base and Arbitrum. Other assets and pairs may require more complex rebalancing paths (e.g.: L2 withdrawals+deposits). This approach requires a permissioned rebalancer to move the collateral over trusted paths.
-
-```mermaid
-flowchart
- subgraph base
- BR((Rebalancer))
- BWR[USDC Collateral Warp Route]
- BCCTP[CCTP]
- BUSDC[USDC]
- end
-
- subgraph arbitrum
- AWR[USDC Collateral Warp Route]
- ACCTP[CCTP]
- AUSDC[USDC]
- end
-
- BR -- "transferCollateral(arbitrum,<br>amount)" --> BWR
- BWR -- "send(arbitrum, amount, router)" --> BCCTP
- BCCTP -- "burn(amount)" --> BUSDC
- BCCTP -. "{amount, router}" .-> ACCTP
- ACCTP -- "mint(amount, router}" --> AUSDC
- AUSDC -. "amount" .-> AWR
-```
From 2eb4e53a6fb1a82905e97d956b952917e3d68816 Mon Sep 17 00:00:00 2001
From: edakturk14 <edakturk96@gmail.com>
Date: Wed, 26 Mar 2025 14:05:47 -0400
Subject: [PATCH 5/6] sidebar reorg: move to evm warp routes
---
sidebars.js | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/sidebars.js b/sidebars.js
index 8681004c..dc29fafd 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -141,6 +141,11 @@ const sidebars = {
id: "guides/manage-warp-route-limits",
label: "Mangaging Warp Route Limits",
},
+ {
+ type: "doc",
+ id: "guides/multicollateral-warp-route",
+ label: "Multicollateral Warp Route Rebalancing",
+ },
],
},
{
@@ -166,11 +171,6 @@ const sidebars = {
id: "guides/deploy-warp-route-UI",
label: "Deploy a Bridge UI for Hyperlane Warp Routes",
},
- {
- type: "doc",
- id: "guides/multicollateral-warp-route",
- label: "Multicollateral Warp Route Rebalancing",
- },
],
},
{
From ed29dd20e48dcf04a81346d8eff569207e5f4e6e Mon Sep 17 00:00:00 2001
From: Eda Akturk <edakturk96@gmail.com>
Date: Fri, 11 Apr 2025 12:39:49 -0400
Subject: [PATCH 6/6] update sidebar for consistency
---
sidebars.js | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/sidebars.js b/sidebars.js
index b87ed10c..0c02bd19 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -149,7 +149,7 @@ const sidebars = {
{
type: "doc",
id: "guides/multicollateral-warp-route",
- label: "Multicollateral Warp Route Rebalancing",
+ label: "Multi-Collateral Warp Route Rebalancing",
},
{
type: "doc",