Add docs/sequences.md with deposit, withdraw, and exit sequences

[sergerad]

Description

Suggesting to add sequence diagrams under docs/ section.

The diagrams render on github so they could be very helpful. See https://github.com/0xPolygon/polygon-edge/blob/424ae7fb723365c0ef245fd731f76645e2920d92/docs/sequences.md

I have been using these when I am debugging deployments as the flows are quite complicated.

Limitations

The sequences there are based on my understanding and likely contain errors and lack some important information.

If Polygon team thinks these would be helpful to others, please contribute to this PR.

[sergerad]

@Stefan-Ethernal please consider whether you would contribute to this PR to help myself and others understand the system better.

Link to rendered diagrams:
https://github.com/0xPolygon/polygon-edge/blob/424ae7fb723365c0ef245fd731f76645e2920d92/docs/sequences.md

[Stefan-Ethernal]

Nice one and pretty useful. Thanks for your contribution 🙌
Leaving a couple of comments to consider.

Btw, maybe move the file itself to docs/bridge/sequences.md.

[sergerad]

Thanks @Stefan-Ethernal, appreciate it. Have made the changes you suggested.
https://github.com/0xPolygon/polygon-edge/blob/bb52c352859dae158ad4b25cb17e141de8b16af8/docs/bridge/sequences.md

One thing I am still confused about is at what point in the withdraw sequence child native tokens should be transferred out of an address. I am observing the following on my deployment:

1. The following commands succeed:

# deposit 1000 wei
polygon-edge bridge deposit-erc20 ...
# withdraw 1000 wei
polygon-edge bridge withdraw-erc20 ...

polygon-edge bridge 'exit' ...

2. Using eth_getBalance JSON RPC request via Postman after exit shows us the balance is still 1000 wei.

This is for native token. Am I missing something with the ChlidERC20Predicate.sol burn() etc? Thanks!

[Stefan-Ethernal]

One thing I am still confused about is at what point in the withdraw sequence child native tokens should be transferred out of an address. I am observing the following on my deployment:

1. The following commands succeed:

# deposit 1000 wei
polygon-edge bridge deposit-erc20 ...
# withdraw 1000 wei
polygon-edge bridge withdraw-erc20 ...

polygon-edge bridge 'exit' ...

2. Using eth_getBalance JSON RPC request via Postman after exit shows us the balance is still 1000 wei.

This is for native token. Am I missing something with the ChlidERC20Predicate.sol burn() etc? Thanks!

As soon as withdraw-erc20 is called, a specified amount is burnt on the child chain (by the ChildERC20Predicate: https://github.com/0xPolygon/core-contracts/blob/dev/contracts/child/ChildERC20Predicate.sol#L135).

Are you sure that you are querying the correct account address (the private key which is provided when sending the withdraw transaction must be the one you are querying eth_getBalance)? Other than that I cannot think of any reason why it wouldn't reduce its balance. I can try to test it once again on my end with some EOA (because until now, we were using some of the validator's accounts to send withdrawal transactions).

[Stefan-Ethernal]

LGTM 🚀

[goran-ethernal]

Apart from the small comment, this is great. Hats down to you good sir 🎩

[sergerad]

(because until now, we were using some of the validator's accounts to send withdrawal transactions).

Thanks, this clarified things for me