Merge pull request #302 from massalabs/299-create-bridge-documentation

299 create bridge documentation

docs/massaBridge/architecture-security.mdx

@@ -0,0 +1,49 @@
+# Architecture and Security Overview
+
+This page presents an overview of the architecture and security measures implemented in the bridge between the Ethereum and Massa blockchains. The bridge is designed to facilitate the secure transfer of assets between the two networks, ensuring the integrity and reliability of cross-chain transactions.
+Our system is designed to ensure the secure, efficient, and transparent bridging of assets, leveraging a lock-mint and burn-redeem scheme underpinned by state-of-the-art security practices.
+
+## System Architecture
+
+### Component Overview
+
+The bridge system comprises several key components:
+
+- **Massa Bridge UI**: Serves as the user interface for initiating bridge transactions. It supports wallet connections and transaction initiations for both Ethereum and Massa blockchains.
+- **BridgeVault Contract (Ethereum)**: Acts as the custodian of assets on the Ethereum side. It is responsible for locking assets during the bridge process and executing redeem transactions based on verified requests.
+- **Bridge Contract (Massa)**: Handles the minting of tokens on the Massa blockchain in response to locked assets on Ethereum and manages the burning of tokens for redemption back to Ethereum.
+- **Relayer Network**: A set of independent nodes responsible for monitoring bridge transactions, verifying events, and facilitating the cross-chain communication necessary for asset transfers.
+
+### User flow
+
+To initiate bridging from Ethereum to Massa, a lock transaction is sent to the BridgeVault contract on Ethereum. This lock transaction will transfer the assets from the user's wallet to the BridgeVault contract, locking them in the process. In order to ensure that the bridge operation meet all the requirements, users should always use the Massa bridge UI. Once the lock transaction has received enough confirmations, it will be handled by the relayer network; On detecting a lock event, each individual relayer will produce a signature corresponding to this particular bridge operation. Once all of the three relayers have signed the lock transaction, the relayer network will forward this bridge operation to the Bridge contract on Massa. The Massa Bridge contract will then verify the signatures, and mint the corresponding amount of tokens to the user's wallet on Massa. The user will then receive a notification that the mint operation has been completed.
+
+To initiate bridging from Massa to Ethereum, a burn transaction is sent to the Bridge contract on Massa. This burn transaction will transfer the assets from the user's wallet to the Bridge contract, burning them in the process. Once the burn transaction has received enough confirmations, it will be handled by the relayer network; On detecting a burn event, each individual relayer will produce a signature corresponding to this particular bridge operation. During the process, the Massa Bridge UI will query the relayer network for the signatures. Once all of the three relayers have produced their signatures, the Massa bridge UI will prepare the redeem transaction. The user will then sign and send the redeem transaction to the Ethereum blockchain, triggering the release of the tokens. 
+
+![Bridge flow](bridge-flow.png)
+
+### Security Measures
+
+The BridgeVault contract on Ethereum holds the assets locked during the bridging process. The only way assets can be redeemed is by sending a message signed by the 3 out of 3 nodes of the relayer network. This ensures that the assets are only released when the relayer network has verified the corresponding burn transaction on Massa. The public keys of the relayer nodes are stored in the Bridge contract on Massa, and can only be updated by a gnosis safe multisig wallet controlled by the bridge operators. Moreover, a 48h timeLock from Openzeppelin is implemented in the Bridge contract on Massa, which requires a 48h delay before the relayer network can update the public keys. This ensures that the bridge operators have enough time to intervene in case of a malicious update of the public keys. 
+The BridgeVault contract can charge fees. However they have been set to 0 for the time being.
+
+**Gnosis safe**
+Safe proxy address: [0xDB1a35B0C8Bb727A8ce5314B4fCCa874614138BB](https://etherscan.io/address/0xDB1a35B0C8Bb727A8ce5314B4fCCa874614138BB)
+
+| Signer Name | Address                                   | Status   |
+|-------------|-------------------------------------------|----------|
+| Signer 1    | 0x675Ebdc155e89c31229b0C7aF38D8D355E61F50 | Active   |
+| Signer 2    | 0xB744a01980b2f1ee61ED742df42B21b3AAfE1A31| Active   |
+| Signer 3    | 0xcF6fB27ddC0A0270A36F7E7E5270CB179D2bfD32| Active   |
+
+
+The Bridge contract on Massa is responsible for minting the tokens in response to the locked assets on Ethereum. The Bridge contract can only mint tokens when it receives a message signed by 3 out of 3 nodes of the relayer network. The synthetic token contracts ownership, has yet to be transferred to a multisig wallet after deployment. The public keys of the relayer nodes are hardcoded in the contract and cannot be updated. This contract as well can be paused for maintenance or security.
+The Bridge contract can charge fees but have been set to 0.
+
+![On chain architecture](on-chain-architecture.png)
+
+The relayer network is a set of independent nodes responsible for monitoring bridge transactions, verifying events, and facilitating the cross-chain communication necessary for asset transfers. The three nodes are hosted on different cloud providers to avoid common points of failure. For redundancy, each node has a fallback mechanism and redundant RPC connections.
+
+The Massa Bridge smart contracts have undergone security audits conducted by Certik, the report is publicly available [here](https://skynet.certik.com/projects/massa-labs?auditId=Massa%20Labs%20-%20EVM%20Bridge).
+
+

docs/massaBridge/home.mdx

@@ -0,0 +1,33 @@
+# Introduction
+
+[Massa Bridge](https://bridge.massa.net/) is the first cross-chain bridge that allows you to transfer ERC-20 tokens from EVM networks to Massa, and vice versa.
+
+It comes with two modes: **Mainnet** (starting with Ethereum and Massa) and **Testnet** (using Sepolia Testnet and Massa Buildnet).
+
+Massa Bridge initially enables the bridging of USDC, DAI, and WETH, originating from the Ethereum blockchain. Synthetic assets received on the Massa blockchain contain a suffix in the token names to identify the origin chain. For example, USDC bridged from Ethereum will become USDC.e on Massa.
+
+## Token Addresses
+
+| Network | Token name | Address |
+|---------|-------|---------|
+| Ethereum | USDC | 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 |
+| Ethereum | WETH | 0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 |
+| Ethereum | DAI  | 0x6b175474e89094c44da98b954eedeac495271d0f |
+| Massa | USDC.e | AS1hCJXjndR4c9vekLWsXGnrdigp4AaZ7uYG3UKFzzKnWVsrNLPJ |
+| Massa | WETH.e | AS124vf3YfAJCSCQVYKczzuWWpXrximFpbTmX4rheLs5uNSftiiRY |
+| Massa | DAI.e | AS1ZGF1upwp9kPRvDKLxFAKRebgg7b3RWDnhgV7VvdZkZsUL7Nuv |
+
+## Supported Wallets
+
+For Ethereum:
+- [Metamask](https://metamask.io/) wallet
+
+For Massa:
+- [Massa Station’s Wallet module](https://station.massa.net/) (recommended by Massa Labs)
+- [Bearby wallet](https://bearby.io/) (community-made wallet)
+
+For more details, please refer to the Massa Bridge FAQ: [https://bridge.massa.net/](https://bridge.massa.net/).
+
+## Getting Started 
+- For step-by-step instructions on how to use the bridge go to the [Instructions section](./instructions.mdx).
+- For additional information about Massa Bridge, check out [Frequently Asked Questions](https://bridge.massa.net/faq/).

docs/massaBridge/instructions.mdx

@@ -0,0 +1,49 @@
+# Instructions
+
+This page explains step-by-step instructions on how to bridge tokens to and from Massa networks.
+
+## Connect Wallets
+
+1. Navigate to [Massa Bridge](https://bridge.massa.net/index). Make sure the mode is set to ‘Mainnet’. To try the testnet Bridge, switch the mode to Testnet in the top-right of your screen.
+2. Click on the ‘Connect wallet’ button.
+3. Connect your Metamask wallet on the Ethereum network.
+4. Connect a Massa wallet account:
+   - For Massa Station Wallet (recommended): Ensure the Massa Station desktop app is installed, open, and running. For Massa Station-related questions, please refer to [Massa Station FAQ](https://docs.massa.net/docs/massaStation/faq) and [Massa Wallet instructions](https://docs.massa.net/docs/massaStation/massa-wallet/getting-started).
+   - For Bearby (community-developed): Ensure the extension is installed and activated.
+
+## Bridge Tokens from Ethereum to Massa
+
+:::note
+You will need to sign up to 2 transactions on Ethereum, and none on Massa.
+:::
+
+1. Once both wallets are connected, ensure your "From" network is Ethereum, and "To" network is Massa.
+2. Select the token and the amount you wish to transfer.
+3. Ensure you have enough ETH to pay for the transaction fees on Ethereum. The estimated cost is displayed before you initiate the transfer. Click on the ‘Bridge’ button to proceed.
+4. If bridging tokens for the first time, you must first sign the Allowance transaction. In the Metamask’s sign request screen, you can approve the max. or a custom amount, depending on your preference. Proceed to sign the transaction.
+5. Once the allowance transaction is completed, you will be asked to sign the bridge transaction in your Metamask. Review the transaction and sign it.
+6. Return to the Bridge page and wait for the completion of your transfer.
+7. A success screen will be shown once the Massa operation is finalized. The tokens should now be in your wallet.
+8. Follow the instructions to add the token to your Massa wallet.
+9. Past transfers can be checked on the History page.
+
+## Redeem Tokens from Massa to Ethereum
+
+:::note
+You will need to sign up to 3 transactions: 2 on Massa, and 1 on Ethereum network.
+:::
+
+1. Once both wallets are connected, ensure your "From" network is Massa, and "To" network is Ethereum.
+2. Select the token you wish to redeem back to Ethereum and enter the amount.
+3. Ensure you have enough ETH and MAS in your connected wallets. The estimated cost is displayed before you initiate the transfer. Click on the ‘Redeem’ button to proceed.
+4. If redeeming tokens for the first time, you must first sign the Allowance transaction. Proceed to sign the transaction.
+5. Once the allowance transaction is completed, you will be asked to sign the burn transaction in your Massa wallet. Proceed to sign it.
+6. After the burn transaction is completed, a button will appear on the Bridge screen to initiate a claim transaction on Ethereum. Click the button to proceed.
+7. Review and sign the last transaction in your Metamask to redeem tokens to your wallet.
+8. A success screen will be shown once the transaction is finalized. Check your Metamask wallet balance.
+9. Past transfers can be checked on the History page.
+
+:::tip
+For additional information, please refer to the [Massa Bridge FAQ](https://bridge.massa.net/faq/).
+If you can't find an answer to your issue feel free to drop a ticket to our Discord Support Channel: [Massa Discord](https://discord.com/channels/828270821042159636/1052987210137342042).
+:::

docusaurus.config.js

@@ -77,7 +77,7 @@ const config = {
       navbar: {
         title: "Docs",
         logo: {
-          alt: "My Site Logo",
+          alt: "Massa Logo",
           src: "img/massa_logo.svg",
           srcDark: "img/massa_logo_white.svg",
         },
@@ -112,6 +112,12 @@ const config = {
             position: "left",
             label: "🧩 Massa Station",
           },
+          {
+            type: "docSidebar",
+            sidebarId: "massaBridgeSidebar",
+            position: "left",
+            label: "🌉 Massa Bridge",
+          },
           {
             type: "search",
             position: "right",

sidebars.js

@@ -433,6 +433,20 @@ const sidebars = {
       label: "Tutorials and community resources",
     },
   ],
+  massaBridgeSidebar: [
+    {
+      type: "doc",
+      id: "massaBridge/home",
+    },
+    {
+      type: "doc",
+      id: "massaBridge/instructions",
+    },
+    {
+      type: "doc",
+      id: "massaBridge/architecture-security",
+    },
+  ],
 };
 
 module.exports = sidebars;

src/components/HomepageFeatures/index.tsx

@@ -34,6 +34,12 @@ const FeatureList = [
     docName: "docs/node/home",
     icon: "🖥",
   },
+  {
+    title: "Massa Bridge",
+    content: "Bridge your assets between Massa and other blockchains.",
+    docName: "docs/massaBridge/home",
+    icon: "🌉",
+  },
 ];
 
 function Feature({ docName, title, content, icon }) {