Refactored token types & whitelising process

docs/bridge/token-types.md

@@ -0,0 +1,72 @@
+---
+id: token-types
+title: Token Types
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+import ThemedImage from '@theme/ThemedImage';
+
+[comment]: # (mx-abstract)
+
+# Token Types
+
+With the release of the bridge v3.0 & v3.1 different token types are allowed to be bridged. By token type, we refer to how the
+tokens are locked/burnt or unlocked/minted along with the chain side on which they are native. The decision of how the token should
+be configured in the bridge depends on the availability of the minter/burner role on the EVM-compatible chain side along with
+the marketing decision of "on which chain the token should be native (a.k.a. where it was first minted)"
+
+[comment]: # (mx-abstract)
+
+**1. Mint/Burn & Native on MultiversX < - > EVM-chain has Mint/Burn & Non-Native**
+
+This bridge token-type configuration has the advantage of not holding a single token in the bridge.
+The swapped tokens are minted/burned on both sides. The total token quantity on both chains equals the (minted - burned) on MultiversX
+added with the (minted - burned) on the EVM-compatible chain side. The initial supply & mint is done on MultiversX.
+
+<!--- source file reference: /static/xbridge/xbridge-dark/light.drawio --->
+<ThemedImage
+    alt="mint/burn tokens"
+    sources={{
+        light: useBaseUrl('/xbridge/mint-burn-tokens-light.png'),
+        dark: useBaseUrl('/xbridge/mint-burn-tokens-dark.png'),
+    }}
+/>
+
+[comment]: # (mx-abstract)
+
+**2. Mint/Burn & Non-Native on MultiversX < - > EVM-chain has Mint/Burn & Native**
+
+This has the same advantages as 1. but the initial minting is done on the EVM-compatible chain side.
+
+[comment]: # (mx-abstract)
+
+**3. Mint/Burn & Non-Native on MultiversX < - > EVM-chain has Locked/Unlocked & Native**
+
+This bridge token configuration type will need to be initiated on the EVM-compatible chain side and the tokens transferred to
+MultiversX will be locked in the bridge contract (no minter role is needed on the EVM-compatible chain as opposed to 1 & 2) and
+will be unlocked when swaps from MultiversX to the EVM-compatible chain are done. On the MultiversX side, there will be mint/burn
+actions. The total quantity of tokens on both chains will be equal to the supply on the EVM-compatible chain. Everything that is
+locked in the bridge contract will equal to what was minted - burned on MultiversX side.
+
+:::warning
+This configuration will also require an intermediate token as to allow the bridging on more than one EVM-compatible chain. 
+It also can create discrepancies between the allowed supplies to bridge between multiple chains.
+:::
+
+Example: if tokens are being brought to MultiversX from EVM-compatible chain 1 and then the tokens are bridged out from
+MultiversX to EVM-compatible chain 2, then the bridge for EVM-compatible chain 2, at some point, will be unable to process
+swaps because it will run out of its intermediary tokens. The solution here is to manually bridge in the reversed order
+as described (an operation that consumes time & fees).
+
+<!--- source file reference: /static/xbridge/xbridge-dark/light.drawio --->
+<ThemedImage
+    alt="mint/burn with lock/unlock tokens"
+    sources={{
+        light: useBaseUrl('/xbridge/lock-unlock-tokens-light.png'),
+        dark: useBaseUrl('/xbridge/lock-unlock-tokens-dark.png'),
+    }}
+/>
+
+**Note:** The diagram above is a little bit misleading because the ERC20 contracts hold the address/balance ledgers inside 
+them. For the sake of simplicity, the tokens are depicted stored inside the bridge **Safe** contracts 
+(just as MultiversX ESDTs).

docs/bridge/whitelist-requirements.md

@@ -1,19 +1,65 @@
 ---
 id: whitelist-requirements
-title: Whitelist requirements
+title: Whitelist Requirements
 ---
 
 [comment]: # (mx-abstract)
 
+# Whitelist Requirements
+
+[comment]: # (mx-abstract)
+
 Before enabling a token to be sent via the Ad-Astra bridge, the token must be whitelisted.
 The whitelisting process is performed with the help of the MultiversX team.
 
 [comment]: # (mx-context-auto)
 
 ## Whitelist requirements
 
-1. The MultiversX team must whitelist the token on both the Safe(1) and Safe(3) contracts. Only whitelisted tokens can be bridged.
-2. The token issuer must issue the token on the MultiversX network and submit a branding request manually or using [https://assets.multiversx.com](https://assets.multiversx.com).
-3. The token issuer must assign the MINT&BURN role to the BridgedTokensWrapper (6) contract as per the instructions provided at [https://docs.multiversx.com/tokens/fungible-tokens/#setting-and-unsetting-special-roles](/tokens/fungible-tokens/#setting-and-unsetting-special-roles)
+1. The token issuer must issue the token on the MultiversX network and submit a branding request manually or using [https://assets.multiversx.com](https://assets.multiversx.com);
+2. The token issuer must assign the MINT & BURN role to the **BridgedTokensWrapper** or the **Safe** contract, depending on the 
+token type configuration.
+
+```rust
+RolesAssigningTransaction {
+    Sender: <address of the ESDT owner>
+    Receiver: erd1qqqqqqqqqqqqqqqpqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqzllls8a5w6u
+    Value: 0
+    GasLimit: 60000000
+    Data: "setSpecialRole" +
+          "@" + <token identifier in hexadecimal encoding> +
+          "@" + <contract address: wrapper or safe contract> +
+          "@" + <local mint role in hexadecimal encoding> +
+          "@" + <local burn role in hexadecimal encoding>
+}
+```
+
+Example: 
+
+Let's suppose we want to whitelist the token `TKN-001122` on the Ethereum bridge and the token configuration type is 1. 
+(mint/burn tokens on both ends, native on MultiversX)
+
+The transaction will look like:
+
+```rust
+RolesAssigningTransaction {
+    Sender: <address of the ESDT owner>
+    Receiver: erd1qqqqqqqqqqqqqqqpqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqzllls8a5w6u
+    Value: 0
+    GasLimit: 60000000
+    Data: "setSpecialRole" +
+          "@544b4e2d303031313232" +
+          "@000000000000000005004ab1cd3d291159a38df7d2a1c498c9d7a7e3047ccc48" +
+          "@45534454526f6c654c6f63616c4d696e74" +
+          "@45534454526f6c654c6f63616c4275726e"
+}
+```
 
-**Note**: As an alternative approach, MultiversX team can issue an ESDT token on the MultiversX chain with the same properties as on Ethereum, and give the needed roles to the Smart Contracts, as indicated above. The MultiversX team can then give the token issuer the ownership of token management for that specific ESDT token.
+3. Depending on the token configuration (valid for 1. & 2. configuration types), the minter & burner role should be granted on
+the EVM-compatible chain side (depending on the ERC20 contract variant, `addMinter` and `addBurner` endpoints can be used);
+4. MultiversX team will complete the whitelisting process by issuing the required transactions.
+
+For reference, this is the list of the known smart contracts:
+* **Wrapper** `erd1qqqqqqqqqqqqqpgq305jfaqrdxpzjgf9y5gvzh60mergh866yfkqzqjv2h`
+* **Ethereum Safe** `erd1qqqqqqqqqqqqqpgqf2cu60ffz9v68r0h62sufxxf67n7xprue3yq4ap4k2`
+* **BSC Safe** `erd1qqqqqqqqqqqqqpgqa89ts8s3un2tpxcml340phcgypyyr609e3yqv4d8nz`

sidebars.js

@@ -512,7 +512,7 @@ const sidebars = {
         items: [
           "bridge/architecture",
           "bridge/transfer-flows",
-          "bridge/multiple-chains",
+          "bridge/token-types",
           "bridge/whitelist-requirements",],
       },
       {