Improve documentation on `LegacyBridge.sol` and the new `StarknetTokenBridge.sol` & `token_bridge.cairo`

[9oelM]

Is your feature request related to a problem? Please describe. When it comes to token transfers across L1 and L2, there are three contracts we need to look at:

• LegacyBridge.sol: the legacy version of token bridge at L1. Only can serve a token per bridge deployed. The existing tokens listed at https://github.com/starknet-io/starknet-addresses/blob/master/bridged_tokens/mainnet.json all have different L1 and L2 bridge addresses, which means they are all using LegacyBridge.
• StarknetTokenBridge.sol: the newest version of token bridge at L1. Can serve multiple ERC20 tokens. Any newer ERC20 tokens intending to bridge across L1 and L2 should use this instead of LegacyBridge.sol.
• token_bridge.cairo: bridge at L2. The bridge is backwards compatible and has legacy methods in it. The existing tokens use this bridge per token address; the newer tokens will use the newest version of this bridge deployed on Starknet at 0x0616757a151c21f9be8775098d591c2807316d992bbc3bb1a5c1821630589256 that can handle multiple tokens at once.

Altogether, the newer version of the bridges at L1 and L2 are called 'MultiBridge', because it supports bridging multiple tokens unlike LegacyBridge.

However, the current documentation about using L1↔L2 bridge is rather a bit confusing.

To start with, some parts of the current documentation about Starkgate bridge is primarily focused on using LegacyBridge only. For example, under L2 function reference, there is only initiate_withdraw which is meant to be used by LegacyBridge, and there is no initiate_token_withdraw which is meant to be used by MultiBridge.

On the other hand, some references in the documentation seem to be well up-to-date, which is also problematic because the documentation about the existing LegacyBridge functions seems to have vanished. LegacyBridge is still very much in use by ETH and other prominent tokens, so the documentation on this should not go away. For example, L1 function signature of withdraw is only for the newest StarknetTokenBridge which is withdraw(address token, uint256 amount, address recipient). But still there are tokens that are using LegacyBridge in production, which has withdraw(uint256 amount, address recipient).

Describe the solution you'd like

There are other bits and pieces that don't quite make sense in a similar sense which seem to need a bit of improvement. Overall, the documentation should make a clear distinction between LegacyBridge and MultiBridge and how to use either of them.

[stoobie]

@9oelM Thanks for the great comments and ideas! Since you seem to have a good understanding of this, are you interested in creating a PR?

[9oelM]

@9oelM Thanks for the great comments and ideas! Since you seem to have a good understanding of this, are you interested in creating a PR?

Happy to help. Will do

[stoobie]

@9oelM Please make sure you scan over the documentation guidelines and the style guidelines mentioned on the home page of the repo. It'll save me a lot of time if you keep those in mind. In particular, please stay away from the passive voice as much as possible. That is, if you can phrase something in the active voice, please do.

There are other important guidelines as well, but I find that the passive voice is the one that I spend the most time correcting..

[9oelM]

@9oelM Please make sure you scan over the documentation guidelines and the style guidelines mentioned on the home page of the repo. It'll save me a lot of time if you keep those in mind. In particular, please stay away from the passive voice as much as possible. That is, if you can phrase something in the active voice, please do.

There are other important guidelines as well, but I find that the passive voice is the one that I spend the most time correcting..

Sure will do, thanks for the guidance. Will probs work on it during this week

[stoobie]

@9oelM Do you think that you'll submit a PR in the near future? I'd like to provide a reward via OnlyDust.xyz, but I can't promise how much without seeing your PR.

Also we have a Telegram channel now that you can join.

[9oelM]

Hey @stoobie thanks for the comment. Sorry about the delay. I was actually working on an extensive overview of Starknet messaging/bridging which is now published at https://research.lazer1.xyz/blog/making-sense-of-starknet-architecture-and-l1-l2-messaging/#l1-l2-messaging because I felt like an explanation of inner workings of the bridge is necessary in order to understand how different pieces come together at the end user level.

So I was wondering if there is any way to incorporate the important/good parts from my writing into the official docs.

I have joined the tg group, let's talk more there!

[cybermazi]

Hello. Is this PR still open @9oelM @stoobie .

Can you please update the documentation issues