Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

design-doc: liquidity migration #35

Merged
merged 2 commits into from
Jul 31, 2024
Merged

design-doc: liquidity migration #35

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9a5bcba
design-doc: liquidity migration
0xParticle Jun 20, 2024
0984351
design-doc: fixed comments and links
0xParticle Jun 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 60 additions & 0 deletions protocol/superc20/liquidity-migration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
# Liquidity Migration

## Purpose

_The document presented below is part of the [Interoperability project](https://github.com/ethereum-optimism/optimism/issues/10899)._

This document proposes a solution for migrating the liquidity of tokens locked in L1, deployed through the current and legacy `OptimismMintableERC20` Factories in L2 (also known as _legacy tokens_), to make them fungible and compatible with Superchain interoperability.

## Summary

We must deploy new token representations because the current L2 tokens can't be upgraded to be compatible with Superchain interoperability. The main goal is to minimize any issues with liquidity migration.

In this document, we will explore three approaches to create a representation that complies with `ISuperchainERC20`: Wrap, Convert, and Mirror. Among these, Mirror seems to be the best option as it doesn't force users to migrate to new token contracts.

## Problem Statement + Context
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does anyone have concrete data on the following things:

  • TVL of immutable bridged tokens created with the OptimismMintableERC20Factory
  • TVL of native L2 tokens
  • TVL of bridged tokens that are upgradeable

This would be highly valuable IMO.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TVL of bridged tokens that are upgradeable:
TVL of immutable bridged tokens created with the OptimismMintableERC20Factory:
TVL of native L2 tokens: https://l2beat.com/scaling/projects/optimism/tvl-breakdown
TVL of L1StandardBridge: https://etherscan.io/address/0x99C9fc46f92E8a1c0deC1b1747d010903E884bE1#multichain-portfolio

Copy link

@MSilb7 MSilb7 Jun 21, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One metapoint: Want to clarify when we mean TVL versus Assets Onchain

The L2Beat and Etherscan links to do show assets on chain, I can work on app TVL (assuming these are the assets that will actually move vs being stuck in CEXs / wallets) -> Can likely show the breakdown of each.

Second, is the bridged tokens that are upgradeable / immutable bridged tokens distinction just if they're behind a proxy?

--

I also imagine we're talking about as many Superchain members as we can get, not just OP Mainnet right?

Copy link

@zainbacchus zainbacchus Jun 21, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@MSilb7 context of the question is: how much of assets bridged are upgradable / non-upgradable. If majority is non-upgradable then we need to prioritize mirroring, if its upgradable we might not need to pri mirroring for the initial release.

We care about assets on chain.

Re members - starting with Base, OPM would be great as that's the majority of liquidity to inform the above.

Proxy would work to determine upgradable!

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok yeah, if you all have a good way to identify which tokens are proxies vs not, you can match that up against L2Beat.

I know USDC is a proxy as an example. We could ~try to approximate it like "did the token ever emit an upgrade event."

Copy link

@MSilb7 MSilb7 Jun 21, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What contract(s) are the OptimismMintableERC20Factory?

I was looking at 0x4200000000000000000000000000000000000012 on OPM and Base, but I'm seeing some tokens on L2Beat that were minted on Base via 0xf23d369d7471bD9f6487E198723eEa023389f1d4. Are the custom ERC20 factories, or are these custom ones not valid?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

per Base docs, seems like this is another token factory 0xF10122D428B4bc8A9d050D06a2037259b4c4B83B

If chains are rolling their own token factories, we'll likely need a registry of this.

Copy link

@MSilb7 MSilb7 Jun 22, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Assuming the Custom ERC20 factories are legitimate
https://github.com/ethereum-optimism/op-analytics/blob/main/misc_analysis/get_aoc_by_token_type.ipynb

Looked at Assets Onchain for Base and OPM

  • Proxy Tokens, Non-Proxy, Native (ETH) even about 25% each (~30% each excl. predeploys)
  • Immutable token factory 8%
  • OP (Predeploy) 14.7%
image [Sheet Link](https://docs.google.com/spreadsheets/d/1U-2RpZGJDgPz5Lig_EUROaUJFKR1n2ocLockPXugq6A/edit?gid=1988079523#gid=1988079523)
  • Base rolled custom minting factories.
  • Assets Onchain value sourced from L2Beat & Mapped to the L2 token address.
  • Tokens created on OP Mainnet pre-regenesis were labeled as "Unknown," unless a proxy event was observed post-regenesis.
  • Tokens without an onchain L2<>L1 mapping were also marked as unknown.

Data Issues:

  • Some L1 tokens map to multiple L2 tokens by bridge events. In this case, we used amount of dex swaps as the indicator for which version of the token to treat as the adopted version.
  • The immutable token factory events seem to be spoofable, which will cause token classification errors, if you go off of factory events (i.e. Native USDC appears to be factory created, when it is not). I manually overrode USDC, but there may be other bugs.
  • ^ Request: Can we make sure there's no ability for people to spoof token creations like this going forward?


The current design of the `StandardBridge` allows for the transfer of standard ERC20 tokens between L1 and each L2 using a lock and mint mechanism. Token representations aren't fungible across different OP chains. We need a way to allow current liquidity to adopt the new `SuperchainERC20` standard to be Interop compatible.

One possible approach is to create a new `SharedStandardBridge` from scratch. This would involve building a single contract connected to each `CrossDomainMessenger` of the Superchain, consolidating all liquidity. It could be implemented as a new contract for users to migrate their liquidity, or via a forced migration on L1 to the new contract. However, a manual migration could take months and a forced migration would introduce significant liability.

Another approach is to make changes only on the L2 side to make the current `OptimismMintableERC20` tokens interoperable without many protocol-level changes. This could involve using the burn/mint permissions of the `L2StandardBridge` and introducing new token contracts to work alongside the existing legacy tokens. While this is not the only way to achieve interoperability, we believe it is the simplest, as the `L2StandardBridge` is upgradable and `OptimismMintableERC20` tokens are not.
0xParticle marked this conversation as resolved.
Show resolved Hide resolved

## Alternatives Considered

We have considered multiple approaches:

### Wrap

Introduce a new contract that wraps one or multiple legacy tokens into an `ISuperchainERC20`.

### Convert

Create a new `ISuperchainERC20` extension for the legacy tokens that can be exchanged with the legacy representation using the burn and mint rights of `L2StandardBridge` .

### Mirror

Create an `ISuperchainERC20` representation that behaves (with some exceptions) like the legacy "mirrored" token while allowing compatibility with Interop. Users will not realize that these are two distinct tokens, as the two contracts (legacy and Mirror) will act as secondary entry points to each other.

## Tradeoffs and Comments

- The Convert and Wrap approaches require users to migrate to the new representation to support interoperability, while mirror representation requires no additional action from the user.
- The Mirror approach could lead to some UX confusion, especially in displaying double balances.
- For Wrap and Convert `SuperchainERC20` should only work with trusted `OptimismMintableERC20` tokens, without hardcoding legacy token addresses into it. For that, we would need to upgrade the legacy `OptimismMintableERC20Factory` to keep track of legacy tokens for each L1 token. However, verifying these legacy tokens, especially those from unofficial factories, is complex and poses security challenges. The Mirror representation does not face this issue.
- When accepting multiple legacy tokens for the same interoperability representation, the Convert method is a bit cleaner than Wrap. This is because Wrap locks liquidity and differentiates each valid source, whereas Convert doesn't. Since legacy tokens are burned and minted, convert doesn't lock liquidity. Mirror can, in theory, support multiple representations, but we suggest sticking to a single one.

### **Considerations**

- Withdrawals to L1 will remain problematic when introducing interoperability without making changes to the `L1StandardBridge`. Users might attempt to withdraw an amount greater than what the `L1StandardBridge` can handle. In that case, several options can be considered:
- We can modify `L2StandardBridge` to conduct liquidity checks by comparing the total amount deposited with the total amount withdrawn and canceling the `withdrawal` if the amount is exceeded.
- Bridge UIs could monitor liquidity availability in both `L1StandardBridge` and choose the best path.

## Proposed Solution: Mirror design
0xParticle marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So this is basically a double entry point (DEP) token, where a user can interact with a token either from it's existing OptimismMintableERC20 contract OR from the new MirrorERC20 contract? If so my initial reaction is that this design makes me very nervous—DEP tokens have been the cause of at least two security vulnerabilities:

  • Compound issue: 1, 2
  • Balancer issue: 1, 2

I suspect part of the reason there are "only" two instances of vulnerabilities from DEP tokens is because there aren't many DEP tokens that protocols integrate with. Now we are making every bridged token a DEP token—how many protocols would this introduce vulnerabilities for?

It's also possible I have misunderstood, and that there's something unique about this design that gives us confidence we are not introducing any vulnerabilities?


The Mirror Design is the cleanest solution compared to the Wrap and Convert approaches, as it does not require to perform liquidity migrations. From the point of view of various actors, each will notice the following:

- EOAs: No action is required. Users can continue using the legacy or mirror versions for typical actions. When they want to use new `SuperchainERC20` functions, they should interact with the mirror contract.
- Wallets and explorers: Double balances may appear.
- dApps: If necessary, we will provide advance notice.

The specifications of this solution will be outlined in the Mirror Standard Design Document.