diff --git a/GLOSSARY.md b/GLOSSARY.md index ad225ef9..6a9a8ce5 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -27,7 +27,7 @@ An entity that monitors L1 **and** L2 to understand token supply. ERC-20 type token for the Movement Network with the source contract on L1. See also \$MOVE. > [MG-39](./MG/mg-39/README.md) **\$L2MOVE** -Native token on L2. Used to pay for L2 gas. > [MG-39](./MG/mg-39/README.md) +Native token on L2. Used to pay for L2 gas. Wrapped version of the \$L1MOVE token. > [MG-39](./MG/mg-39/README.md) **L2Block** A block of transactions that is processed by the FFS protocol. It contains information about the state root produced by the transactions in the block. @@ -36,7 +36,7 @@ A block of transactions that is processed by the FFS protocol. It contains infor ERC-20 type token for the Movement Network with the source contract on L1. See also \$L1MOVE. > [MG-39](./MG/mg-39/README.md) **Native Bridge** -Native bridge that permits to exchange of \$L1MOVE into \$L2MOVE, and vice versa. This bridge mints \$L2MOVE. +The bridge that allows the transfer of tokens between L1 and L2, which hold \$L1MOVE and \$L2MOVE token, respectively. The native bridge has the capability to mint \$L2MOVE tokens. > [MG-39](./MG/mg-39/README.md) **Postconfirmation** The process of confirming a (sequence of) blocks after it has been processed by the FFS protocol on L1. diff --git a/MD/md-0/README.md b/MD/md-0/README.md index 09019b94..c78bf4c9 100644 --- a/MD/md-0/README.md +++ b/MD/md-0/README.md @@ -2,16 +2,8 @@ - **Description**: Provide formal structure for proposing non-trivial improvements to Movement. - **Authors**: [Liam Monninger](mailto:liam@movementlabs.xyz) - - - ## Overview + Provide formal structure for proposing non-trivial improvements to Movement. This should be used for specifying complex changes to Movement technologies--particularly those that may require third-parties to adjust their usage of said technologies. ## Definitions @@ -20,51 +12,20 @@ Provide definitions that you think will empower the reader to quickly dive into ## Desiderata - ### D1: Draft and publish standardized proposals + **User Journey**: Proposer/Researcher can adhere to a standardized template for proposing changes to Movement technologies. **Justification**: Offering a standardized means for researching a proposing changes to Movement technologies will help guide research both in written structure and by facilitating engagement. The likelihood of producing successful proposals from such a structure should be expected to be higher than otherwise. ### D2: Implement against clear and accountable specifications + **User Journey**: Developers can confidently implement complex systems against a clear and accountable specification. **Justification**: The standardization and review process should produce clearer specifications. The contributors responsible for these specifications should be--encouraging higher quality. **Guidance and suggestions**: -- As referenced above, the formalized proposals supported by the desired process should be reserved for changes to Movement technologies that are of the highest complexity and quality. Otherwise, the effort of the standardization will likely be counterproductive. - -## Errata - +## Changelog diff --git a/MD/md-15/README.md b/MD/md-15/README.md index aa3ef569..97eb0b84 100644 --- a/MD/md-15/README.md +++ b/MD/md-15/README.md @@ -48,15 +48,4 @@ In order to communicate with more specificity in all contexts, Movement Labs sho **Recommendations**: - MD can also introduce MG to further aid in clarity, but they will not be ratified until they have been supported in an MIP. -## Errata - +## Changelog diff --git a/MD/md-3/README.md b/MD/md-3/README.md index 2bf21a14..1f5f93d4 100644 --- a/MD/md-3/README.md +++ b/MD/md-3/README.md @@ -67,15 +67,4 @@ These and other phenomena are listed in the desiderata below. **Recommendations**: - Start by reviewing the [Asynchronous Upgrades, Fork Creation, and Fork Stake Problems](./asychronous-upgrades-problem.md). -## Errata - +## Changelog \ No newline at end of file diff --git a/MG/mg-0/README.md b/MG/mg-0/README.md index 20bd6136..02a81457 100644 --- a/MG/mg-0/README.md +++ b/MG/mg-0/README.md @@ -1,4 +1,4 @@ -# MG-0: gloss +# MG-0: Gloss Example - **Authors**: [Liam Monninger](liam@movementlabs.xyz) - **Introducing Document: [MIP-0](../../MIP/mip-0/README.md)** @@ -10,19 +10,12 @@ A **gloss** is a short description of a term as would feature as an entry in a g ### Related Work - 1. [Merriam-Webster's Definition of "gloss"](https://www.merriam-webster.com/dictionary/gloss) ### Example Usages - 1. He updated the **gloss** to include a more detailed explanation. ### Changelog - \ No newline at end of file + +2025-01-15: Updated the **gloss** to include a more detailed explanation. [#45](https://github.com/movementlabsxyz/MIP/pull/45) diff --git a/MIP/mip-0/README.md b/MIP/mip-0/README.md index 61f81a6c..fd0c5bae 100644 --- a/MIP/mip-0/README.md +++ b/MIP/mip-0/README.md @@ -1,11 +1,11 @@ -# MIP-0: MIPs -- **Description**: Movement Improvement Proposals standardize and formalize specifications for Movement technologies. -- **Authors**: [Liam Monninger](mailto:liam@movementlabs.xyz) +# MIP-0: Formalize Movement Proposals +- **Description**: A process through with Movement Improvement Proposals standardize and formalize specifications for Movement technologies. +- **Authors**: [Liam Monninger](mailto:liam@movementlabs.xyz), [Andreas Penzkofer](mailto:andreas.penzkofer@movementlabs.xyz) - **Desiderata**: [MD-0](../MD/md-0) ## Abstract -Movement Improvement Proposals (MIPs) serve as a mechanism to propose, discuss, and adopt changes or enhancements to Movement technologies. By providing a standardized and formalized structure for these proposals, MIPs ensure that proposed improvements are well-defined, transparent, and accessible to the wider community. +This document formalizes the process through which Movement Improvement Proposals standardize and formalize specifications for Movement technologies, through MIPs (Movement Improvement Proposals), MDs (Movement Desiderata), and issues. ## Motivation @@ -13,48 +13,119 @@ Movement technologies continually evolve, and there's a need to ensure that the ## Specification -A Movement Improvement Proposal (MIP) is a design document that provides information to the Movement community, describing a new feature or improvement for Movement technologies. - -- **Structure**: Each MIP must adhere to the given template, which requires details like title, description, author, status, and more. A MIP also includes sections like Abstract, Motivation, Specification, Reference Implementation, Verification, Errata, and Appendix. +### Extensions to this MIP - - An md-template is provided in the [MIP Repository](https://github.com/movemntdev/MIP) which further specifies this structure. This MIP is an example of said structure. - -- **Lifecycle**: An MIP starts as a draft, after which it undergoes discussions and revisions. Once agreed upon, it moves to a 'published' status. An MIP can also be deprecated if it becomes obsolete. +We treat the following documents as extensions to this MIP: + +- [root README](../../README.md) +- [MD template](../../md-template.md) +- [MIP template](../../mip-template.md) +- [MG template](../../mg-template.md) + +### High-level Lifecycle + +The lifecycle of a proposal should be + +1. create a [new issue](https://github.com/movementlabsxyz/MIP/issues) to register the intent to write an MD/MIP and its scope. +2. If 1. is approved by governance (this may require some discussions), start writing an MD and create a PR for it using [this Draft](../../md-template.md). +3. The author MAY start an MIP using [this Draft](../../mip-template.md) in the same PR as the MD. However, doing so may slow down the governance approval of the MD. A preferred approach is to start with the MD, then await governance approval and only then start the MIP in a separate PR. + +#### Status terms + +An MIP/MD is proposed through a PR. Each MIP/MD PR should have a status. For additional specification, see the [root README](../../README.md#status-terms). + +### Roles + +#### Governance + +A governance body is responsible for overseeing the Movement Improvement Proposal process. This body is responsible for approving or rejecting proposals, and for ensuring that the process is followed correctly. The governance body is also responsible for maintaining the Movement Improvement Proposal repository, and for ensuring that the proposals are kept up-to-date. + +#### Editor + +The motivation for the role of the editor is to ensure the readability, layout correctness, and easy access of content. The editor is responsible for the final review of the MIPs. The editor is responsible for the following: + +- Ensures a high quality of the MIPs/MDs, e.g. checking language while reviewing. +- Removes content from the MIPs/MDs that is commented out. (e.g. content within brackets) +- Ensures the MIP/MD numbering is correct. +- Ensures the MIP/MD is in the correct status. +- Ensures the authors have added themselves to [CODEOWNERS](./.github/CODEOWNERS), see [Code owners](#code-owners). + +The editor is NOT responsible for the content. + +**Conflict resolution**: In the unlikely case, where an editor requests a change from an author that the author does not agree with and communication does not resolve the situation + +- the editor can mandate that the author implements the changes by getting 2 upvotes from reviewers on their discussion comment mentioning the changes. +- Otherwise the author can merge without the editor requested change. -- **Storage**: MIPs should be stored in the MIPs directory at [MIP Repository](https://github.com/movemntdev/MIP). +#### Code owners -- **Definitions** : Provide definitions that you think will empower the reader to quickly dive into the topic. +An author commits to becoming the owner of the MIP/MD they propose. This means that for any future changes to the MIP/MD the author will be notified. -## Reference Implementation +The author MUST add themselves as a code owner in [CODEWONERS](.github/CODEOWNERS). -A reference implementation or a sample MIP following the MIP template can be provided to guide potential proposers. This MIP (MIP-0) serves as a practical example, aiding in understanding the format and expectations. +### Proposal Stages + +The Movement Improvement Proposal process is divided into three stages: Issue, MD, and MIP. + +#### Stage Issue + +Issues are used to propose trivial changes or improvements to Movement technologies. They are used to discuss and document the rationale behind a proposed change, and to gather feedback from the community. Issues are not formalized and do not require a specific structure. They are used to gauge interest and to start discussions. + +#### Stage MD + +Movement Desiderate (MDs) are used to request new features, highlight new requirements, or propose new ideas. MDs are formalized and require a specific structure. They are used to provide a standardized means for requesting changes to Movement technologies, and to guide in written structure and by facilitating engagement. + +We provide a [template](../../md-template.md) for MDs, which should be used for specifying complex changes to Movement technologies. + +**Lifecycle**: An MD starts as a draft, after which it undergoes discussions and revisions. Once agreed upon, it moves to a 'published' status. An MD can also be deprecated if it becomes obsolete. The available statuses are listed in the [root README](../../README.md). + +**Storage**: MDs should be stored in the [MDs directory](../../MD/). For each MD a separate directory should be created, containing the MD in markdown format, and any additional files required for the MD. + +**Structure**: Each MD must adhere to [this template](../../md-template.md), which requires details like title, description, author, status, and more. An MD also includes sections like Overview, Desiderata and Changelog. + +#### Stage MIP + +Movement Improvement Proposals (MIPs) serve as a mechanism to propose, discuss, and adopt changes or enhancements to Movement technologies. By providing a standardized and formalized structure for these proposals, MIPs ensure that proposed improvements are well-defined, transparent, and accessible to the wider community. + +A Movement Improvement Proposal (MIP) is a design document that provides information to the Movement community, describing a new feature or improvement for Movement technologies. + +**Lifecycle**: An MIP starts as a draft, after which it undergoes discussions and revisions. Once agreed upon, it moves to a 'published' status. An MIP can also be deprecated if it becomes obsolete. The available statuses are listed in the [root README](../../README.md). + +**Storage**: MIPs should be stored in the [MIPs directory](../). For each MIP a separate directory should be created, containing the MIP in markdown format, and any additional files required for the MIP. + +**Structure**: Each MIP must adhere to [this template](../../mip-template.md), which requires details like title, description, author, status, and more. A MIP also includes sections like Abstract, Motivation, Specification, Reference Implementation, Verification, Changelog, and Appendix, see next. + +**Section Reference Implementation**: A reference implementation or a sample MIP following the MIP template can be provided to guide potential proposers. This MIP (MIP-0) serves as a practical example, aiding in understanding the format and expectations. + +**(Optional) Section Definitions**: Provide definitions that you think will empower the reader to quickly dive into the topic. -## Verification +**Section Verification** -1. **Correctness**: Each MIP must convincingly demonstrate its correctness. +1. Correctness: Each MIP must convincingly demonstrate its correctness. This MIP is correct insofar as it uses a structure established by Ethereum for Improvement Proposals which has hitherto been successful. -2. **Security Implications**: Each MIP should be evaluated for any potential security risks it might introduce to Movement technologies. +2. Security Implications: Each MIP should be evaluated for any potential security risks it might introduce to Movement technologies. The primary security concern associated with this MIP is the exposure of proprietary technologies or information via the ill-advised formation of an MIP which the MIP process might encourage. -3. **Performance Impacts**: The implications of the proposal on system performance should be analyzed. +3. Performance Impacts: The implications of the proposal on system performance should be analyzed. The primary performance concern associated with this MIP is its potential for overuse. Only specifications that are non-trivial and very high-quality should be composed as MIPs. -4. **Validation Procedures**: To the extent possible, formal, analytical, or machined-aided validation of the above should be pursued. +4. Procedures: To the extent possible, formal, analytical, or machined-aided validation of the above should be pursued. I'm using spellcheck while writing this MIP. You can verify that I am using valid grammar by pasting this sentence into Google Docs. -5. **Peer Review and Community Feedback**: A section should be included that captures significant feedback from the community, which may influence the final specifications of the MIP. +5. Peer Review and Community Feedback: A section should be included that captures significant feedback from the community, which may influence the final specifications of the MIP. The Movement Labs team is currently reviewing and assessing this process. -## Errata +**Section Appendix**: The Appendix should contain references and notes related to the MIP. -Post-publication corrections, if any, to the MIPs should be documented in this section. This ensures transparency and provides readers with accurate and up-to-date information. +**Section Changelog**: Post-publication changes, if any, to the MIP should be documented in this section. This ensures transparency and provides readers with accurate and up-to-date information. -## Appendix +## Changelog -The Appendix should contain references and notes related to the MIP. Materials referenced in the MIP should be marked with specific labels (e.g., ⟨R1⟩) for easy tracking and understanding. +- 2024-12-18: Add information about the process and structure of MDs. +- 2025-xx-xx: Incorporate updates on the process from SF. [PR#76](https://github.com/movementlabsxyz/MIP/pull/76) diff --git a/MIP/mip-1/README.md b/MIP/mip-1/README.md index 523b2068..7f4691ec 100644 --- a/MIP/mip-1/README.md +++ b/MIP/mip-1/README.md @@ -1,30 +1,33 @@ # MIP-1: ENTL (Enclave Nonce Time-lock) + - **Description**: ENTL proposes a simple challenge-reponse protocol to link Enclave usage to a given program. It additionally proposes a means of time-locking to allow the replacement of said program while maintaining security. - **Authors**: [Liam Monninger](mailto:liam@movementlabs.xyz) -- **Desiderata**: [MD-1](../MD/md-1) +- **Desiderata**: [MD-1](../../MD/md-1) ## Abstract -ENTL proposes a simple challenge-reponse protocol to link Enclave usage to a given program. It additionally proposes a means of time-locking to allow the replacement of said program while maintaining security. This approach is demonstrated to be both generalizable and cryptographically sound. +ENTL proposes a simple challenge-response protocol to link Enclave usage to a given program. It additionally proposes a means of time-locking to allow the replacement of said program while maintaining security. This approach is demonstrated to be both generalizable and cryptographically sound. ## Motivation -This protocol was originally suggested as a solution to minimizing trust assumptions in the Atomic Bridge under [MD-1](../MD/md-1). However, similar problems were encountered under Movement Labs Governance Stage 0 concerning general key usage. +This protocol was originally suggested as a solution to minimizing trust assumptions in the Atomic Bridge under [MD-1](../MD/md-1). However, similar problems were encountered under Movement Labs Governance Stage 0 concerning general key usage. ## Specification The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174. ### Protocol Description -The protocol is a simple challenge-response scheme performed between two parties: the Enclave, a presumed secure compute unit, and the Client, the program requesting the Enclave's services. + +The protocol is a simple challenge-response scheme performed between two parties: the Enclave, a presumed secure compute unit, and the Client, the program requesting the Enclave's services. The following messages types are exchanged between the Enclave and the Client: + - **SYN**: the Client sends a 256-bit nonce to the Enclave. - **SYN-OK**: the Enclave responds indicating it has received and accepted the nonce. This can be sent as a response to either SYN or SYN-CHECK. -- **SYN-TL**: the Enclave responds indicating it has the received the nonce and subjected it to a time-lock and queuer. The time-lock and place in the queue are provided as response. +- **SYN-TL**: the Enclave responds indicating it has the received the nonce and subjected it to a time-lock and queuer. The time-lock and place in the queue are provided as response. - **APP**: the Client sends an application message to the Enclave, a 256-bit nonce for the current message, and a 256-bit nonce for the next message. - **APP-OK**: the Enclave responds indicating it has processed the application message and has updated the nonce for the next message. -- **APP-OK-CON**: the Enclave responds indicating that it has processed the application message, has updated the nonce for the next message, and has aborted a contentious synchronization attempt. +- **APP-OK-CON**: the Enclave responds indicating that it has processed the application message, has updated the nonce for the next message, and has aborted a contentious synchronization attempt. - **APP-REJ**: the Enclave responds indicating it has received the application message but is rejecting it and will not update the nonce for the next message. These messages are exchanged as follows: @@ -36,7 +39,7 @@ These messages are exchanged as follows: - If the Enclave has a record of the nonce, this indicates that another client has attempted to synchronize with the Enclave in the past. It MUST check queue and time-lock conditions: - If the nonce is at the top of the queue and has passed its time-lock, the Enclave MUST accept, store, and respond with a SYN-OK message. - If the nonce is not at the top of the queue or has not passed its time-lock, the Enclave MUST respond with a SYN-TL message. - + **Application Phase** 1. The Client sends an APP message to the Enclave with the application message and the nonce for the current message and the nonce for the next message. 2. The Enclave processes the APP message: @@ -51,9 +54,10 @@ These messages are exchanged as follows: - If the message is APP-REJ, the Client MUST re-send the application message with the "current nonce" it used in the previous message. ### Example Application: Atomic Bridge Service + To demonstrate how this protocol can be used, consider the Atomic Bridge Service. -To minimize trust in MLABSO, an enclave is booted which generates its own signing keys and is prepared to sign transactions to send to bridge contracts. This enclave can additionally be tooled with other application messages handlers to, for example, allow for the replacement of an initial trusted and directly accessible signing key. +To minimize trust in MLABSO, an enclave is booted which generates its own signing keys and is prepared to sign transactions to send to bridge contracts. This enclave can additionally be tooled with other application messages handlers to, for example, allow for the replacement of an initial trusted and directly accessible signing key. Once the enclave has been configured, the MLABSO configures the bridge service software to start signing transactions via ENTL protocol. It synchronizes for a nonce which is immediately accepted as it is the first SYN message. The bridge service then exchanges application messages with the enclave to sign transactions. The bridge service never directly accesses the signing key, only sending application messages to the enclave. @@ -67,35 +71,33 @@ In practice, there are several phenomena regarded as external to the ENTL protoc #### Securing the Nonce In order to avoid the possibility of malicious usage, both the current nonce and the next nonce need to be stored in a manner that is difficult to access except by the current program. We do not intend to impose cryptographically secure requirements on this storage, as that begins to invoke concepts related to the literature on succinct arguments for programs. However, there are several simpler ways that can make accessing the and using the outside nonce difficult. -To describe these, it first helps to consider what enables a nonce attack and to consider the time these operations take. +To describe these, it first helps to consider what enables a nonce attack and to consider the time these operations take. -1. The attacker must first obtain the nonce which takes some duration $d_E = t_E' - t_E$. +1. The attacker must first obtain the nonce which takes some duration $d_E = t_E' - t_E$. 2. The attacker then must use the nonce to send in an APP message which the Enclave will process. This takes some duration $d_S = t_S' - t_S$. -3. In total, we may say the attack takes some duration $d_A = t_S' - t_E'$. -4. Meanwhile, the legitimate Client will have some duration $d_L = t_L' - t_L$ over which the nonce is stored as either the current or next nonce and has not yet been used. -5. The period between when the legitimate Client first stores this nonce and when the Enclave would process it is bounded by a time $t_S'$ wherein the attacker sends the malicious APP message and $t_L$. +3. In total, we may say the attack takes some duration $d_A = t_S' - t_E'$. +4. Meanwhile, the legitimate Client will have some duration $d_L = t_L' - t_L$ over which the nonce is stored as either the current or next nonce and has not yet been used. +5. The period between when the legitimate Client first stores this nonce and when the Enclave would process it is bounded by a time $t_S'$ wherein the attacker sends the malicious APP message and $t_L$. This model of an attack leads to several prevention strategies: -- **High Temporal Resolution**: frequently updating the nonce narrows the window $d_L$ in which the attacker can obtain the nonce and use it before the legitimate Client does. If this exceeds, the time to obtain the nonce and send it, i.e., $d_A$, the attack is impossible. It may thus be ideal for the Client to update the nonce even without a message that corresponds to is APP logic. +- **High Temporal Resolution**: frequently updating the nonce narrows the window $d_L$ in which the attacker can obtain the nonce and use it before the legitimate Client does. If this exceeds, the time to obtain the nonce and send it, i.e., $d_A$, the attack is impossible. It may thus be ideal for the Client to update the nonce even without a message that corresponds to is APP logic. - **Security via Obscurity**: the implication throughout this MIP is that Client stores its nonce in program memory. As program memory is highly-dynamic, particularly on the stack, it would be difficult to identify the location of the nonce in memory, increasing $d_A$. This is a form of security via obscurity which could be further upgraded by data structures which further randomize the location of the nonce in memory. - **ISA-specific Approaches**: there a number of ISA-specific tools which can used to make accessing certain sections of memory very difficult for even though most privileged attackers. Consider reviewing [Intel TSX](https://www.intel.com/content/www/us/en/developer/articles/community/exploring-tsx-with-software-development-emulator.html#:~:text=Intel%C2%AE%20Transactional%20Synchronization%20Extensions%20(Intel%C2%AE%20TSX)%20is%20perhaps,%E2%84%A2%20microarchitecture%20code%20name%20Haswell.) and [ARM PAC](https://www.qualcomm.com/content/dam/qcomm-martech/dm-assets/documents/pointer-auth-v7.pdf). - **ENTL Hot Potato and Generalizations**: the ENTL protocol can be made bidirectional and two-staged such that the Enclave also synchronizes a nonce with the Client which it expects the Client to echo with the eventual APP message. This could further reduce the time the ultimate nonce is stored in the Client's memory and increase the time the attacker must spend to obtain and use the nonce. Generalizations and variations of this protocol could use more parties and commit-reveal schemes like Pedersen commitments to further secure the nonce. #### Crash Resistance and Recovery + Enclave products such as [AWS Nitro Enclaves](https://aws.amazon.com/ec2/nitro/nitro-enclaves/) and [Intel SGX](https://www.intel.com/content/www/us/en/products/docs/accelerator-engines/software-guard-extensions.html)-based products generally [do not allow backups](https://ieeexplore.ieee.org/document/9743462). This means that if you were to generate keys within an enclave, as suggested above, you may not be able to recover them if the enclave crashes. Several suggestions are made to resolve this problem in [MD-2](../MD/md-2). ## Reference Implementation - ## Verification -ENTL assumes a valid Client program is one that (1) can provide the correct nonce and (2) - -## Errata +ENTL assumes a valid Client program is one that (1) can provide the correct nonce and (2) -Post-publication corrections, if any, to the MIPs should be documented in this section. This ensures transparency and provides readers with accurate and up-to-date information. +## Changelog ## Appendix diff --git a/MIP/mip-15/README.md b/MIP/mip-15/README.md index efed721e..50f563ed 100644 --- a/MIP/mip-15/README.md +++ b/MIP/mip-15/README.md @@ -42,7 +42,7 @@ The format is as follows: An MG is a definition of a term that requires detailed explanation. Any term introduced through an MG MUST be declared in the Glossary. -A template for the MG is provided at [mg-template](../../md-template.md). The template covers the requested elements listed in [MD-15.D1](../MD/md-15/README.md). +A template for the MG is provided at [mg-template](../../md-template.md). The template covers the requested elements listed in [MD-15.D1](../../MD/md-15/README.md). An example MG is provided at [mg-0](../../MG/mg-0/README.md). @@ -70,6 +70,6 @@ See the MG document type template at [mg-template](../../md-template.md) and the ## Verification -## Errata +## Changelog ## Appendix diff --git a/MIP/mip-39/README.md b/MIP/mip-39/README.md index 66feaef7..cf5610a7 100644 --- a/MIP/mip-39/README.md +++ b/MIP/mip-39/README.md @@ -1,5 +1,6 @@ # MIP-39: MOVE Token -- HTLC-based Native Bridge Design -- **Description**: Architecture of the HTLC-based Native Bridge for $MOVE token. + +- **Description**: Architecture of the HTLC-based Native Bridge for \$MOVE token. - **Authors**: [Franck Cassez](mailto:franck.cassez@movementlabs.xyz) ## Abstract @@ -17,7 +18,7 @@ This MIP describes the high-level architecture of the [HTLC-based](https://bitco The Movement chain (L2) uses the \$L2MOVE token to pay for gas fees. As a result users need to hold \$L2MOVE tokens to pay for their transactions. > [!IMPORTANT] -> The _native_ \$L1MOVEtoken is an ERC-20 contract on Ethereum (L1). By native, we mean that this is the location where the token is minted and burned and where the total supply is set and possibly modified (inflation/deflation). The **\$L1MOVE token reserve** is in the L1 contract. +> The _native_ \$L1MOVE token is an ERC-20 contract on Ethereum (L1). By native, we mean that this is the location where the token is minted and burned and where the total supply is set and possibly modified (inflation/deflation). The **\$L1MOVE token reserve** is in the L1 contract. To use the Movement chain and pay for gas fees, a user will acquire \$L1MOVE (native) tokens on L1, and _bridge_ them to L2. On the L2 they can use the token to pay for gas fees or with any other dApps that transact the \$L2MOVE token. Later, a user can choose to migrate their \$L2MOVE tokens back to the L1 at any time (thereby converting them to \$L1MOVE). These cross-chain assets's transfers are usually done through a component called a _bridge_. @@ -73,9 +74,9 @@ As can be seen the protocol above has distinct phases, and many things can go wr Many of the possibly issues have been thoroughly studied and bridges have been in operation for several years. However hacks related to bridges account for more than 1/3 of the total hacks value which tends to indicate that bridges are vulnerable, frequently attacked, and should be designed carefully. Infamous attacks are two Ronin bridge attacks and a Nomad bridge attack -- [2022: Crypto Hackers Exploit Ronin Network for $615 Million](https://www.bankinfosecurity.com/crypto-hackers-exploit-ronin-network-for-615-million-a-18810) -- [2024: Ronin Bridge Paused, Restarted After $12M Drained in Whitehat Hack](https://www.coindesk.com/tech/2024/08/06/ronin-bridge-paused-after-9m-drained-in-apparent-whitehat-hack/) -- [August 2022: Hack Analysis: Nomad Bridge ($192M)](https://medium.com/immunefi/hack-analysis-nomad-bridge-august-2022-5aa63d53814a) +- [2022: Crypto Hackers Exploit Ronin Network for \$615 Million](https://www.bankinfosecurity.com/crypto-hackers-exploit-ronin-network-for-615-million-a-18810) +- [2024: Ronin Bridge Paused, Restarted After \$12M Drained in Whitehat Hack](https://www.coindesk.com/tech/2024/08/06/ronin-bridge-paused-after-9m-drained-in-apparent-whitehat-hack/) +- [August 2022: Hack Analysis: Nomad Bridge (\$192M)](https://medium.com/immunefi/hack-analysis-nomad-bridge-august-2022-5aa63d53814a) Some solutions [XChainWatcher](https://arxiv.org/abs/2410.02029) rely on monitoring bridges and detect attacks. @@ -87,7 +88,7 @@ Designing a safe bridge is a hard problem. Let `user1` be a user with an account on L1, and `user2` be a user with an account on L2. -> [!NOTE] +> [!NOTE] > **Simple context (without loss of generality)** > Assume `user1` wants to transfer `1` \$L1MOVE tokens, we refer to as `asset` in the sequel, to `user2` on L2. @@ -95,16 +96,16 @@ Let `user1` be a user with an account on L1, and `user2` be a user with an accou A successful transfer requires the following these steps: -1. _user1_ locks their L1\$L1MOVE tokens in the `AtomicBridgeInitiatorMOVE.sol` contract on L1. The contract emits an event `BridgeTransferPending` to the L1 logs. At this point in time the transfer becomes `INITIALIZED` on L1. +1. _user1_ locks their \$L1MOVE tokens in the `AtomicBridgeInitiatorMOVE.sol` contract on L1. The contract emits an event `BridgeTransferPending` to the L1 logs. At this point in time the transfer becomes `INITIALIZED` on L1. 2. A _relayer_ monitors the L1 logs and when they see the `BridgeTransferPending` event, they send a transaction to the `atomic_bridge_counterparty.move` module on L2 asking the module to prepare the minting of \$L2MOVE tokens. The status of the bridge transfer on L2 becomes `PENDING`. An event `BridgeTransferLocked` is emitted to the L2 logs. -> [!TIP] +> [!TIP] > Check point: This is the end of the first phase. Next phase must be triggered by `user2`. > At that point the bridge transfers details are known by the L1 and the L2. -3. _user2_ (or anybody with the secret) sends a transaction to the `atomic_bridge_counterparty.move` module on L2 asking to _complete the bridge transfer_. If the transfer has been properly initialised (step 2 above), this results in minting tokens and transfers the minted tokens to the `user2` account. If successful, an event `BridgeTransferComplete` is emitted to the L2 logs. The status of the transfer on L2 becomes `COMPLETED`. +3. _user2_ (or anybody with the secret) sends a transaction to the `atomic_bridge_counterparty.move` module on L2 asking to _complete the bridge transfer_. If the transfer has been properly initialized (step 2 above), this results in minting tokens and transfers the minted tokens to the `user2` account. If successful, an event `BridgeTransferComplete` is emitted to the L2 logs. The status of the transfer on L2 becomes `COMPLETED`. -> [!TIP] +> [!TIP] > Check point: The transfer is completed on L2. > At that stage the \$L2MOVE tokens are in the `user2` account on L2. @@ -167,7 +168,7 @@ Contracts's APIs: The permissions are set to ensure that only the user who initiated the transfer can request a refund, and only the relayer can complete the transfer on L2. -Other safety considerations include the use of [EIP-55](https://eips.ethereum.org/EIPS/eip-55) (L1 side) checksums for addresses. There is some code immplemented in the L2 Move contract [ethereum_module]( to check EIP-55 compliance so we may enforce EIP-55 compliance at some stage. +Other safety considerations include the use of [EIP-55](https://eips.ethereum.org/EIPS/eip-55) (L1 side) checksums for addresses. There is some code implemented in the L2 Move contract [ethereum_module]( to check EIP-55 compliance so we may enforce EIP-55 compliance at some stage. ### Bridging from L2 to L1 @@ -182,9 +183,9 @@ A successful transfer from L2 to L1 requires the following these steps: > Check point. `user2' does not have the asset on L2 anymore. > At that point the bridge transfers details are known by the L1 and the L2. -3. _user1_ (or anybody with the secret) sends a transaction to the `AtomicBridgeCounterParty.sol` contract on L1 asking to _complete the bridge transfer_. If the transfer has been properly initialized (step 2 above), this results in transferring $L1MOVE tokens to the `user1` account. If successful, an event `BridgeTransferCompleted` is emitted to the L1 logs. The status of the transfer on L1 becomes `COMPLETED`. +3. _user1_ (or anybody with the secret) sends a transaction to the `AtomicBridgeCounterParty.sol` contract on L1 asking to _complete the bridge transfer_. If the transfer has been properly initialized (step 2 above), this results in transferring \$L1MOVE tokens to the `user1` account. If successful, an event `BridgeTransferCompleted` is emitted to the L1 logs. The status of the transfer on L1 becomes `COMPLETED`. -> [!TIP] +> [!TIP] > Check point. `User1` has the asset on L1. > At that stage the \$L1MOVE tokens are in the `user1` account on L1. @@ -279,7 +280,7 @@ The safety and liveness properties are defined by temporal logics formulas and c The UPPAAL model is available in [this-file](./uppaal-models/bridge-up-v2.xml). To reproduce the results and check the properties on the model, you need a working version of UPPAAL. -The results of the model-checking verification are as follows: let $maxRelayerDelay$ be the **maximum delay** for the relayer to relay an event, and $timeLock1$ and $timeLock2$ be the timelocks on L1 and L2 respectively. +The results of the model-checking verification are as follows: let $maxRelayerDelay $ be the **maximum delay** for the relayer to relay an event, and $timeLock1$ and $timeLock2$ be the timelocks on L1 and L2 respectively. > [!IMPORTANT] > **Verification results** @@ -298,11 +299,13 @@ Note that [safety-2] does hold if the relayer is down for more than $maxRelayerD The only difference between L1 to L2 is the way assets are created/destroyed. However, the formal model abstracts away this difference and the same properties hold for the L2 to L1 bridge. +## Changelog + --- ## Appendix -The UPPAAL models of the L1 to L2 tranfers are available in the [uppaal-models](./uppaal-models) directory. +The UPPAAL models of the L1 to L2 transfers are available in the [uppaal-models](./uppaal-models) directory. The simplest model is [bridge-up-v2.xml](./uppaal-models/bridge-up-v2.xml) and the more complex model is [bridge-up-v3.xml](./uppaal-models/bridge-up-v3.xml) with probabilities. You can request a license to use UPPAAL at [UPPAAL](http://www.uppaal.org/). diff --git a/MIP/mip-53/README.md b/MIP/mip-53/README.md index 0511d595..40b231ac 100644 --- a/MIP/mip-53/README.md +++ b/MIP/mip-53/README.md @@ -58,9 +58,6 @@ All proposed progressive L2 models MUST include a list of pros and cons. This li ## Verification - - -## Errata - +## Changelog ## Appendix diff --git a/README.md b/README.md index 05a7b297..5f1c16b6 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,27 @@ # MIP, MD and MG -We differentiate between MD and MIP. +We differentiate between **issue**, **MD** and **MIP**. An overview of the MIPs and MDs can be found in the [OVERVIEW](https://movementlabsxyz.github.io/MIP/). -The [Glossary](https://github.com/movementlabsxyz/MIP/wiki/glossary) contains an alphabetically ordered list of terms used in this repository. In addition MG serves as a platform to define glossary terms, which are used in the MIPs and MDs. +The lifecycle of a proposal should be: -## Movement Desiderata (MD) +1. create a [new issue](https://github.com/movementlabsxyz/MIP/issues) to register the intent to write an MD/MIP and its scope. +2. If 1. is approved (this may require some discussions), start writing an MD and create a PR for it using [this Draft](../../md-template.md). +3. The author MAY start an MIP using [this Draft](../../mip-template.md) in the same PR as the MD. However, doing so may slow down the governance approval of the MD. A preferred approach is to start with the MD, then await governance approval and only then start the MIP in a separate PR. + +```mermaid +graph LR + A[Idea: issue] --> B[Request: MD] --> C[Solution: MIP] +``` -See [MD-0](./MD/md-0) to get started. A template is provided at [md-template](md-template.md). +The [Glossary](https://github.com/movementlabsxyz/MIP/wiki/glossary) contains an alphabetically ordered list of terms used in this repository. +In addition MG serves as a platform to define glossary terms, which are used in the MIPs and MDs. + +!!! info For more information on the process in this repository, see also[MIP-0](./MIP/mip-0/README.md). + +## Movement Desiderata (MD) MDs serve to capture the **objectives** behind the **introduction** of a particular MIP. Any @@ -19,11 +31,13 @@ MDs serve to capture the **objectives** behind the **introduction** of a particu related to MIPs should be documented as an MD and stored in the MD directory. +A **template with instructions** is provided at [md-template](md-template.md). See [MIP-0](./MIP/mip-0) for a definition of its functionality. + ## Movement Improvement Proposal (MIP) -See [MIP-0](./MIP/mip-0) to get started. A template is provided at [mip-template](mip-template.md). +A **template with instructions** is provided at [mip-template](mip-template.md). See [MIP-0](./MIP/mip-0) for a definition of its functionality. -### Deciding whether to propose +#### Deciding whether to propose You **SHOULD** draft and submit an MIP, if any of the following are true: @@ -39,6 +53,8 @@ You **SHOULD NOT** draft an MIP, if any of the following are true: ## Glossary and Movement Gloss (MG) +A template with instructions is provided at [mg-template](mg-template.md). See [MIP-15](./MIP/mip-15) for a definition of its functionality. See [MG-0](./MG/mg-0) for an example. + An alphabetically ordered list of terms is provided in the [glossary](https://github.com/movementlabsxyz/MIP/wiki/glossary). MGs serve to capture the **definitions** of terms introduced in the MIPs and MDs. The creation of a new MG requires an MIP or MG (since new terms are introduced through the MIP or MG). @@ -53,57 +69,44 @@ An MIP/MD starts as **Draft**s. They DO NOT acquire a number at this point. An MIP/MD is assigned their PR number as soon as they are in the **Review** process. MDs that do not introduce a new MIP/MD are also accepted. Thus, there will be gaps in the MIP/MD number sequence. These gaps will also emerge when MIPs/MDs are deprecated or rejected. -> [!NOTE] -> Update the [OVERVIEW](https://github.com/movementlabsxyz/MIP/wiki/Overview) file with the MIP/MD number, title and other requirements. - PRs that don't introduce a new MIP/MD are also accepted, for example MIPs/MDs can be updated. PRs that **Update** a MIP/MD should state so in the PR title, e.g. `[Update] MIP-....`. ## Status Terms -An MIP/MD is proposed through a PR. Each MIP/MD-introducing PR should have a status in the name in the form `[Status] ...`. +An MIP/MD is proposed through a PR. Each MIP/MD PR should have a status in the name in the form `[status] MIP/MD-x: ...`. An MIP/MG should at all times have one of the following statuses: - **Draft** - (set by author) An MIP/MD that is open for consideration. (It does not yet hold an MIP/MD number) - **Review** - (set by author) The MIP/MD is under peer review. The MIP/MD should receive an **MIP/MD number**, according to the rules described in the [Files and numbering](#files-and-numbering) section. At this point the editor should be involved to ensure the MIP/MD adheres to the guidelines. ->[!Note] -> In case the editors are not available for an unacceptable long period of time, a reviewer should assume the role of the editor interim. +!!! info In case the editors are not available for an unacceptable long period of time, a reviewer should assume the role of the editor interim. After acceptance the MIP/MD is merged into `main` and the branch should be deleted. Additionally, the following statuses are used for MIPs/MDs that are not actively being worked on: -- **Stagnant** - an MIP/MD that has not been updated for 6 months. +- **Stagnant** - an MIP/MD that has not been updated for 6 months. Upon this status the PR will be closed. - **Withdrawn** - an MIP/MD that has been withdrawn. Finally, an MIP/MD can also be updated: - **Update** - (set by author) An MIP/MD is being updated. The title should list the MIP/MD number, e.g. `[Update] MIP-0 ...`. -## Editor - -The motivation for the role of the editor is to ensure the readability and easy access of content, until further means, such as automatic rendering becomes available. +## Governance -Currently the editors are [@apenzk](https://github.com/apenzk). +For more information on the role of the governance, see [MIP-0: Governance](./MIP/mip-0/README.md#governance). -The editor is responsible for the final review of the MIPs. The editor is responsible for the following: +Currently the governance consists of [@franck44](https://github.com/franck44), [@l-monninger](https://github.com/l-monninger), [@apenzk](https://github.com/apenzk), [@0xmovses](https://github.com/0xmovses), [@bhenhsi](https://github.com/bhenhsi). -- Ensures a high quality of the MIPs/MDs, e.g. checking language while reviewing. -- Removes content from the MIPs/MDs that is commented out. (e.g. content within brackets) -- Ensures the MIP/MD numbering is correct. -- Ensures the MIP/MD is in the correct status. -- Ensures the authors have added themselves to [CODEOWNERS](./.github/CODEOWNERS), see [Code owners](#code-owners). - -The editor is not responsible for the content. +## Editor -**Conflict resolution**: In the unlikely case, where an editor requests a change from an author that the author does not agree with and communication does not resolve the situation +For more information on the role of the editor, see [MIP-0: Editor](./MIP/mip-0/README.md#editor). -- the editor can mandate that the author implements the changes by getting 2 upvotes from reviewers on their discussion comment mentioning the changes. -- Otherwise the author can merge without the editor requested change. +Currently the editors are [@apenzk](https://github.com/apenzk). ## Code owners An author commits to becoming the owner of the MIP/MD they propose. This means that for any future changes to the MIP/MD the author will be notified. -This is being implemented by adding the author as a code owner in the `.github/CODEOWNERS` file for a given MIP/MD. +The author MUST add themselves as a code owner in [CODEWONERS](.github/CODEOWNERS). diff --git a/md-template.md b/md-template.md index 14c9d50f..4d5e8f0a 100644 --- a/md-template.md +++ b/md-template.md @@ -1,11 +1,14 @@ # MD-\: \ + - **Description**: A single sentence description summarizing the items in the desiderata. - **Authors**: [Author](mailto:author@email.com) -## Errata +# Changelog + \ No newline at end of file diff --git a/mg-template.md b/mg-template.md index d9be5960..2f101390 100644 --- a/mg-template.md +++ b/mg-template.md @@ -27,8 +27,20 @@ 2. Example 2 3. Example 3 -### Changelog +## Changelog \ No newline at end of file + Document any post-publication changes to the gloss entry. + The changelog should be maintained after publication. + + 1. **Transparency and Clarity**: The changelog acknowledges any corrections made post-publication, ensuring that readers are not misled and are always equipped with the most accurate information. + + 2. **Accountability**: By noting changes openly, we maintain a high level of responsibility and ownership over our content. It’s an affirmation that we value precision and are ready to correct oversights. + + Each changelog should briefly describe each change made, accompanied by a reference to the date, version and PR in which the change was implemented. + + The format should be as follows: + - **YYYY-MM-DD**: Description of change. [PR#](link-to-PR) + + TODO: Maintain this comment. +--> diff --git a/mip-template.md b/mip-template.md index eeb915d9..cdfa8a30 100644 --- a/mip-template.md +++ b/mip-template.md @@ -1,14 +1,15 @@ # MIP-\: \ + - **Description**: A single sentence summarizing the contents of the proposal. - **Authors**: [Author](mailto:author@email.com) -- **Desiderata**: [MIP-\](../MIP/mip-\) +- **Desiderata**: [MD-\](../MD/md-\) ---