299 create bridge documentation

docs/massaBridge/architecture-security.mdx

@@ -0,0 +1,112 @@
+# 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. 
+
+### 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 address: [0x1234567890abcdef1234567890abcdef12345678](https://gnosis-safe.io/app/#/safes/0x1234567890abcdef1234567890abcdef12345678)
+
+| Signer Name | Address                                   | Status   |
+|-------------|-------------------------------------------|----------|
+| Damir       | 0xAbC1234...EfgH5678                      | Active   |
+| Adrien      | 0xIjk9012...LmnO3456                      | Active   |
+| SRE         | 0xPqr7890...StuV1234                      | Inactive |
+
+
+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.
+
+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://drive.google.com/file/d/1onla7nqsow26RZYXfJE2ju0vGwdjfttA/view?usp=sharing).
+
+
+![Bridge flow](bridge-flow.png)
+
+#### Lock-Mint Use Case
+
+##### User Interaction:
+
+- A **User** accesses the **Bridge Website** via a browser connected to wallets.
+- The **User** opts to transfer assets from an **EVM blockchain** to the **Massa blockchain**.
+- The **User** signs and sends an approval transaction and then a lock transaction to the **EVM blockchain** using their wallet provider.
+
+##### Blockchain and Relayer network Interaction:
+
+- The **EVM blockchain** executes the transaction and notifies the **Relayer network**.
+- Each instance receives the lock event and signs transaction data.
+
+##### Massa blockchain interaction:
+
+- Once sufficient **Relayer network** signatures are collected, the **Relayer network** sends the mint transaction to the **Massa blockchain**.
+- The **User** receives notification upon successful execution of the transaction on the **Massa blockchain**.
+
+#### Burn-Redeem Use Case
+
+##### User Interaction:
+
+- A **User** accesses the **Bridge website** via a browser connected to wallets.
+- The **User** opts to transfer assets from the **Massa blockchain** to an **EVM blockchain**.
+- The **User** signs and sends an approval transaction and then sends a burn transaction to the **Massa blockchain** using their wallet provider.
+
+##### Blockchain and Relayer network interaction:
+
+- The **Massa blockchain** processes the burn transaction and notifies the **Relayer network**.
+- Each instance receives the burn event and signs a redeem transaction.
+
+##### EVM blockchain interaction:
+
+- Once sufficient **Relayer network** signatures are collected, the **Bridge website** prepares the corresponding transaction.
+- The **User** signs and sends the redeem transaction to the **EVM blockchain** using their wallet provider.
+- Once the redeem transaction is executed on the **EVM blockchain**, the **User** is notified of its completion.
+
+
+### Off-chain Relayer Network
+![Off chain architecture](off-chain-architecture.png)
+
+### On-chain Smart Contracts
+![On chain architecture](on-chain-architecture.png)
+
+
+## Security Measures
+
+### Multisig and TimeLock Mechanisms
+
+- The system employs multisig schemes for critical operations, requiring multiple signatures from authorized entities to execute sensitive actions, enhancing security against unauthorized access or compromises.
+- TimeLock is implemented for administrative actions, introducing a mandatory delay between the initiation and execution of such actions, providing a window for intervention if suspicious activity is detected.
+
+### Relayer Security
+
+- Relayers are selected based on strict criteria to ensure reliability and security. Each relayer operates independently, with each instance hosted on separate cloud providers to avoid common points of compromise.
+- The relayer network employs fallback mechanisms and redundant RPC connections to maintain operational resilience against network failures or targeted attacks.
+
+### Smart Contract Security
+
+- Contracts utilize established libraries like OpenZeppelin for foundational security features, including role-based access control and secure transfer mechanisms.
+- Regular audits and continuous monitoring are in place to identify and mitigate potential vulnerabilities, ensuring the integrity of contract logic and operations.
+
+## Conclusion
+
+The architecture and security framework of our bridge between the Ethereum and Massa blockchains is built on the principles of decentralization, redundancy, and rigorous security practices. Through a combination of smart contract immutability, distributed operations, and advanced security mechanisms, we provide a secure, efficient, and reliable bridge service that users can trust for their cross-chain transactions.

docs/massaBridge/home.mdx

@@ -0,0 +1,29 @@
+# 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 | _add token contract link_ |
+| Ethereum | WETH | _add token contract link_ |
+| Ethereum | DAI | _add token contract link_ |
+| Massa | USDC.e | _add token contract link_ |
+| Massa | WETH.e | _add token contract link_ |
+| Massa | DAI.e | _add token contract link_ |
+
+## 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/).

docs/massaBridge/instructions.mdx

@@ -0,0 +1,40 @@
+# 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 FAQ](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.

docusaurus.config.js

@@ -76,7 +76,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",
         },
@@ -111,6 +111,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 }) {