From 74e56cb78ed5d3b11b8336c1210fce4cafb221ac Mon Sep 17 00:00:00 2001 From: Michael Amadi Date: Wed, 30 Oct 2024 10:52:35 +0100 Subject: [PATCH 1/2] move cannon and dispute folders to L1 folder --- ...cannon-and-dispute-folders-to-L1-folder.md | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 protocol/move-cannon-and-dispute-folders-to-L1-folder.md diff --git a/protocol/move-cannon-and-dispute-folders-to-L1-folder.md b/protocol/move-cannon-and-dispute-folders-to-L1-folder.md new file mode 100644 index 00000000..462b4ef3 --- /dev/null +++ b/protocol/move-cannon-and-dispute-folders-to-L1-folder.md @@ -0,0 +1,35 @@ +# Proposal to move Cannon and Dispute folders to L1 folder + +## Context + +Currently the Cannon and Dispute contracts of the OP Stack are located in their own folders: `L2/cannon/` and `L2/dispute/` respectively. These contracts are critical components of the OP Stack's fault proof system: + +- The Cannon contracts holds the fault proof VM implementation and related contracts and libraries that execute a single instruction after bisecting over the L2 execution trace. +- The Dispute contracts holds the fault dispute game implementation and related contracts and libraries that allows parties to dispute/defend invalid state transitions. + +## Problem Statement + +The Cannon and Dispute contracts are L1 contracts that operate on L1 to verify L2 execution. However, they are currently located in their own folders which does not accurately reflect their role in the system. This might lead to confusion about their purpose. + +## Proposed Solution + +There are 3 possible solutions to this problem: + +1. Moving just the Cannon and Dispute contract `files` to the `L1/` folder: + - Pros: The files are in an appropriate folder + - Cons: Loses folder organization benefits. The L1 folder currently has 16 files, flattening cannon and dispute files into it will make these files harder to find. +2. Moving the entire Cannon and Dispute `folders` to the `L1/` folder: + - Pros: + - The files are in an appropriate folder + - Folder structure is preserved +3. Leave everything as is and make no changes: + - Pros: No migration effort needed + - Cons: Continues architectural confusion and technical debt + +The recommended approach is option 2 - moving the complete folders. This provides a clearer organization while preserving the internal structure. + +## Risks, Uncertainties and Considerations + +- All import paths referencing these folders will need to be updated +- Documentation and tooling may need path updates +- The migration should be done atomically to avoid broken references From 19e3590924425c8c897520cbd91ad36f693ac046 Mon Sep 17 00:00:00 2001 From: Michael Amadi Date: Thu, 31 Oct 2024 10:41:13 +0100 Subject: [PATCH 2/2] change to Proposal to reorganize OP Stack contracts folder structure --- ...cannon-and-dispute-folders-to-L1-folder.md | 60 +++++++++++++------ 1 file changed, 43 insertions(+), 17 deletions(-) diff --git a/protocol/move-cannon-and-dispute-folders-to-L1-folder.md b/protocol/move-cannon-and-dispute-folders-to-L1-folder.md index 462b4ef3..f4e812e6 100644 --- a/protocol/move-cannon-and-dispute-folders-to-L1-folder.md +++ b/protocol/move-cannon-and-dispute-folders-to-L1-folder.md @@ -1,32 +1,58 @@ -# Proposal to move Cannon and Dispute folders to L1 folder +# Proposal to reorganize OP Stack contracts folder structure ## Context -Currently the Cannon and Dispute contracts of the OP Stack are located in their own folders: `L2/cannon/` and `L2/dispute/` respectively. These contracts are critical components of the OP Stack's fault proof system: +Currently, the OP Stack contracts are organized across multiple top level folders: -- The Cannon contracts holds the fault proof VM implementation and related contracts and libraries that execute a single instruction after bisecting over the L2 execution trace. -- The Dispute contracts holds the fault dispute game implementation and related contracts and libraries that allows parties to dispute/defend invalid state transitions. +- `cannon/`: Fault proof VM implementation and single instruction execution contracts +- `dispute/`: Fault dispute game contracts for challenging invalid blocks and output root +- `governance/`: Protocol governance contracts +- `L1/`: Contracts deployed on L1 +- `L2/`: Contracts deployed on L2 +- `legacy/`: Deprecated contracts +- `libraries/`: Shared library contracts +- `periphery/`: Non core auxiliary contracts +- `safe/`: Safe related contracts and modules +- `universal/`: Contracts used on both L1 and L2 +- `vendors/`: Third-party developed contracts ## Problem Statement -The Cannon and Dispute contracts are L1 contracts that operate on L1 to verify L2 execution. However, they are currently located in their own folders which does not accurately reflect their role in the system. This might lead to confusion about their purpose. +The current organization has several drawbacks: + +1. Too many top-level folders make navigation difficult +2. Folder names don't always reflect contract purposes: + - Cannon and Dispute contracts run on L1 but live in separate folders + - Governance contracts run on L2 but are in a governance folder + - Safe contracts are used on both L1/L2 but have their own folder + - Legacy and periphery contracts have their own folders and files are flattened rather than organized by layer ## Proposed Solution -There are 3 possible solutions to this problem: +We propose reorganizing contracts based on their deployment layer: + +1. Move layer specific contracts to their respective folders: + + - `cannon/` → `L1/cannon/` + - `dispute/` → `L1/dispute/` + - `governance/` → `L2/governance/` + +2. Organize shared contracts: + - `safe/` → `universal/safe/` + - Split `legacy/` into `L1/legacy/`, `L2/legacy/`, `universal/legacy/` + - Split `periphery/` into `L1/periphery/`, `L2/periphery/`, `universal/periphery/` + +Afterwards, the `src/` folder will be organized as such: + +- `L1/` +- `L2/` +- `universal/` +- `vendors/` -1. Moving just the Cannon and Dispute contract `files` to the `L1/` folder: - - Pros: The files are in an appropriate folder - - Cons: Loses folder organization benefits. The L1 folder currently has 16 files, flattening cannon and dispute files into it will make these files harder to find. -2. Moving the entire Cannon and Dispute `folders` to the `L1/` folder: - - Pros: - - The files are in an appropriate folder - - Folder structure is preserved -3. Leave everything as is and make no changes: - - Pros: No migration effort needed - - Cons: Continues architectural confusion and technical debt +This restructuring will: -The recommended approach is option 2 - moving the complete folders. This provides a clearer organization while preserving the internal structure. +- Make contract purposes more immediately apparent +- Simplify navigation ## Risks, Uncertainties and Considerations