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 all commits
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
58 changes: 58 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,58 @@
# 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

The current L2 tokens can't be upgraded to be compatible with Superchain interoperability. The main goal is to achieve compatibility whie minimizing liquidity migration issues.

This desgin doc will explore multiple approaches to create a representation that complies with `ISuperchainERC20`. Among these, [Mirror](https://github.com/ethereum-optimism/design-docs/pull/36) 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. `OptimismMintableERC20` representations aren't fungible across different OP chains. These tokens need a way to adopt the new `SuperchainERC20` standard to be Interop compatible.

## Alternatives Considered

### L1 migration

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.

### L2 migration

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.

**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.

A more detailed design doc can be found [here](https://github.com/ethereum-optimism/design-docs/pull/36).

## Tradeoffs and conclusion

- The migration flow in L1 is very complex to achieve. An L2 migration seems like a simpler approach.
- 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.
- Wrap is the traditional approach to extend functionalities for an asset, as it works in any case. Convert requires a way of minting and burning the token, which legacy representations will have in the `L2StandardBridge`.
- For Wrap and Convert `SuperchainERC20` should only work with trusted `OptimismMintableERC20` tokens, without hardcoding legacy token addresses into it. For that, it is necessary 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, also support multiple representations.
- The Mirror approach could lead to some UX confusion, especially in displaying double balances.

All things considered, the [Mirror Design](https://github.com/ethereum-optimism/design-docs/pull/36) seems to be the cleanest solution, as it does not require to perform any Liquidity Migrations. It is necessary, however, to be very careful with any integration issues. Protocols must be aware of the new design and look for potential bugs before having a new standard in production.

## Additional 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:
- Modifying the `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.
- Let the Bridge UIs monitor liquidity availability in both `L1StandardBridge` and choose the best path.