Document design goals and protocol features

README.md

@@ -1,6 +1,6 @@
 # Multi-bridge Message Aggregation (MMA)
 
-> **Technical Documentation:** https://multi-message-aggregation.gitbook.io/multi-message-aggregation/
+> Additional Technical documentation can be found on [Gitbook here.](https://multi-message-aggregation.gitbook.io/multi-message-aggregation/)
 
 ## Introduction
 Multi-bridge Message Aggregation (MMA) is an additive security module for cross-chain communication across different EVM chains. It uses multiple [Arbitrary Messaging Bridges](https://blog.li.fi/navigating-arbitrary-messaging-bridges-a-comparison-framework-8720f302e2aa) to send messages, rather than relying on a single AMB. This approach significantly improves security and resilience of cross-chain communication. Even if a small subset of AMBs is compromised, invalid messages cannot be executed on the destination chain, which enhances the [safety property](https://crosschainriskframework.github.io/framework/20categories/20architecture/architecture/#messaging-protocol) of the protocol. Likewise, the failure of a small subset of AMBs will also not disrupt the protocol's ability to send messages, thus improving its [liveness and censorship resistance](https://crosschainriskframework.github.io/framework/20categories/20architecture/architecture/#messaging-protocol) properties.
@@ -13,36 +13,46 @@ Specifically, the protocol offers the following benefits:
 
 3.**Increase Flexibility** by allowing dApps a more seamless integration with new cross-chain protocols and a less disruptive phasing-out of defunct protocols over time.
 
-## Features
+## Design
+The design of MMA is guided by the following goals:
+- **Simplicity**: MMA provides a thin layer of abstraction over existing cross-chain protocols, adding minimal complexity and significantly reducing implementation risk.
+- **Extensibility**: The design of MMA allows for the seamless integration of new AMBs, and accommodates changes to the design and implementation of AMBs without requiring modifications to the core protocol.
+- **Flexibility**: The protocol offers flexibility, enabling dApps to choose the set of bridges and validation parameters to use for different chains and for specific messages.
 
-### Core MMA architecture
-- **Minimized Feature Sets**: barebone implementation, low level of complexity.
-- **Configurable**: during deployment, individual project can configure their own parameters to fit their specific use case and risk tolerance.
-### Adapter
-- **Standardization**: Implements EIP-5164 for all APIs on the sending and receiving end.
-- **Industry buyin**: currently more than **SIX** bridge providers have their adapters for MMA.
+The protocol comprises core contracts and adapters. The core contracts implement the protocol's central logic, which includes sending and receiving messages across chains using multiple bridges for enhanced security and resilience. Adapters facilitate interaction between the core components and specific AMBs. They follow a standard interface (EIP-5164) for easy integration with the core protocol. The core contracts are designed for simplicity, while the adapters are designed for flexibility. This design approach allows for easy integration of new AMBs. It also accommodates changes in the design and implementation details of AMBs without necessitating modifications to the core protocol.
 
-## Workflow for crosschain governance
+## Features
+**The current version of MMA is specifically tailored to address the cross-chain governance use case of the Uniswap protocol.** 
+As a result, the capabilities are intentionally in the following two ways:
+1. Uni-directional communication: Only a single sender chain is supported, allowing communication solely from the designated sender chain to other recipient chains.
+2. Only EVM Chains are supported.
+3. Timelock on destination chain. Messages are executed on the destination chain only after a specified timelock period has elapsed.
 
-Assume, we use 3 bridges to relay governance message from Ethereum mainnet to a destination chain. (This number can be changed during actual deployment or via a later governance vote.)
+The core features of the protocol are:
+1. Sending and receive messages across EVM chains using multiple bridges.
+1. Adding and removing bridges.
+1. Configuring message validation parameters.
+1. Administering adapter-specific parameters.
 
+A [different fork](https://github.com/lifinance/MMAxERC20) of this repository is expanding the current capabilities of MMA to support a broader range of cross-chain interaction patterns, additional use-cases, and non-EVM chains.
 
-On the destination chain, if 2 of the 3 AMB agree with each other, we would consider the message.
+## Life-cycle of a Message
+The diagram below illustrates a typical scenario for the MMA protocol in the context of Uniswap's cross-chain governance workflow. 
 
-The flow of the message and how it is transformed and relayed is detailed below:
+The Uniswap DAO wants to send a governance action message to a remote chain for execution. An example of such a message could be changing fee parameters on the Uniswap deployment on the destination chain. The life cycle of a cross-chain governance transaction proceeds as follows, once it has passed the standard process of on-chain voting and time-lock queue on the governance chain (Ethereum):
+1. The governance message is sent from the Uniswap V2 Timelock contract to the `MultiBridgeMessageSender` contract
+1. The `MultiBridgeMessageSender` sends the message to all available AMB sender adapters (a caller could choose to exclude one or more AMBs in this process)
+1. The AMB sender adapters (`IMessageSenderAdapter`) send the message to AMB-specific components to relay the message to the intended destination
+1. AMB receiver adapters receive the message from off-chain components (e.g. bridge validators or relayers) and forward them to the `MultiBridgeMessageReceiver`
+1. Once enough AMBs have relayed a specific message (i.e. a quorum has been achieved), anyone can call `scheduleMessageExecution()` on the `MultiBridgeMessageReceiver` which then queues the message for execution on the governance timelock.
+1. Once a configured delay period has elapsed on the governance timelock, anyone can execute a time-locked message, which performs the intended execution on the target contract on the destination chain.
 
-1. Uniswap Ethereum governance structure, `src`, approves to execute a message `msg` on destination chain `dst`.
-2. Uniswap governance sends `msg` to `MultiBridgeMessageSender`.
-3. `MultiBridgeMessageSender` relays `msg` to different adapters `adapter`.
-4. `adapter` encodes `msg` into the corresponding formatted message, `formatted_msg`, and sends it to the hardcoded AMB contracts `AMB`.
-5. Each `AMB` independently carries `formatted_msg` to `dst`.
-6. On the destination chain, another set of `adapters` decodes `formatted_msgs` into the original `msg`.
-7. `msg` is collected inside the `MultiBridgeMessageReceiver` contract.
-8. If 2 out of 3 `msg` is the same, the `msg` will be executed on `dst`.
+![Illustration of ](https://314948482-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyWOfgotvwuIBhzylK0ud%2Fuploads%2FYrd16Z8BdyejNqvCF5eO%2FScreenshot%202023-09-25%20at%207.57.32%20pm.png?alt=media&token=eb3ef911-1f44-4657-b234-8acbd55ddf1c)
 
-![Illustration of ](https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyWOfgotvwuIBhzylK0ud%2Fuploads%2Fco073eKSrR7xUmhObi7v%2FMMA_Highlevel.png?alt=media&token=bff8ec55-c04f-4ab9-b362-caae601154db)
 
 ## Local Development
+**Pre-requisites:** 
+- Install [foundry](https://github.com/foundry-rs/foundry)
 
 **Step 1:** Clone the repository
 
@@ -77,33 +87,8 @@ Once you have set these values, you can run both the unit and integration tests
 ```sh
 $  forge test
 ```
-
 **note:** We use [pigeon](https://github.com/exp-table/pigeon/tree/docs) to simulate the cross-chain behavior on forked mainnets.
 
-## Contribution guidelines
-Thank you for your interest in contributing to MMA! We welcome all contributions to make our project better!
-
-### Before you start
-Before you start contributing to the project, please make sure you have read and understood the project's [Gitbook documentation](https://multi-message-aggregation.gitbook.io/multi-message-aggregation/). If you have any questions, drop Kydo a DM on [Twitter](https://twitter.com/0xkydo).
-
-### How to contribute
-#### Reporting bugs and issues
-If you find any bugs or issues with the project, please create a GitHub issue and include as much detail as possible.
-
-#### Code contribution
-If you want to contribute code to the project, please follow these guidelines:
-
-1. Fork the project repository and clone it to your local machine.
-1. Create a new branch for your changes.
-1. Make your changes and test them thoroughly.
-1. Ensure that your changes are well-documented.
-1. Create a pull request and explain your changes in detail.
-1. Code review
-1. All code changes will be reviewed by the project maintainers. The maintainers may ask for additional changes, and once the changes have been approved, they will be merged into the main branch.
-
-#### Testing
-All code changes must be thoroughly tested. Please ensure that your tests cover all new functionality and edge cases.
-
 ## Contracts
 ```
 src