- An exemplary DAO setup showing interactions between the three core contract pieces triggered by different user groups: The DAO contract in blue containing the PermissionManager in red, respectively, as well as two Plugin contracts in green.
+ An examplary DAO setup showing interactions between the three core contract pieces triggered by different user groups: The DAO contract in blue containing the PermissionManager in red, respectively, as well as two Plugin contracts in green.
Function calls are visualized as black arrows and require permission checks (red, dashed arrow). In this example, the permission manager determines whether the token voting plugin can execute actions on the DAO, a member can change its settings, or if a DeFi-related plugin is allowed to invest in a certain, external contract.
- An exemplary DAO setup showing interactions between the three core contract pieces triggered by different user groups: The DAO contract in blue containing the PermissionManager in red, respectively, as well as two Plugin contracts in green.
+ An examplary DAO setup showing interactions between the three core contract pieces triggered by different user groups: The DAO contract in blue containing the PermissionManager in red, respectively, as well as two Plugin contracts in green.
Function calls are visualized as black arrows and require permission checks (red, dashed arrow). In this example, the permission manager determines whether the token voting plugin can execute actions on the DAO, a member can change its settings, or if a DeFi-related plugin is allowed to invest in a certain, external contract.
- Overview of the plugin versioning and registry in the Aragon OSx protocol. The `PluginRepoRegistry` contract, which is a curated list of ENS named `PluginRepo` contracts, is shown on the left. Each `PluginRepo` contract maintains a list of versions of the `PluginSetup` contract (internally referencing the `Plugin` implementation contract) and the associated UI building blocks as a URI, exemplarily shown on the right. + Overview of the plugin versioning and registry in the Aragon OSx protocol. The `PluginRepoRegistry` contract, which is a curated list of ENS named `PluginRepo` contracts, is shown on the left. Each `PluginRepo` contract maintains a list of versions of the `PluginSetup` contract (internally referencing the `Plugin` implementation contract) and the associated UI building blocks as a URI, examplarily shown on the right.
diff --git a/docs/osx/01-how-it-works/02-framework/02-plugin-management/02-plugin-setup/01-security-risk-mitigation.md b/docs/osx/01-how-it-works/02-framework/02-plugin-management/02-plugin-setup/01-security-risk-mitigation.md index 1b3433ee..33015ebe 100644 --- a/docs/osx/01-how-it-works/02-framework/02-plugin-management/02-plugin-setup/01-security-risk-mitigation.md +++ b/docs/osx/01-how-it-works/02-framework/02-plugin-management/02-plugin-setup/01-security-risk-mitigation.md @@ -22,7 +22,7 @@ that might be carelessly or intentionally caused, a malicious plugin can hide ** #### Backdoors -- [metamorphic contracts](https://a16zcrypto.com/metamorphic-smart-contract-detector-tool/) (contracts, that can be redeployed with new code to the same address) +- [metamorpic contracts](https://a16zcrypto.com/metamorphic-smart-contract-detector-tool/) (contracts, that can be redeployed with new code to the same address) - malicious repurposing of storage in an update of an upgradeable plugin contract diff --git a/docs/osx/01-how-it-works/02-framework/02-plugin-management/02-plugin-setup/index.md b/docs/osx/01-how-it-works/02-framework/02-plugin-management/02-plugin-setup/index.md index 073261f7..330b81fa 100644 --- a/docs/osx/01-how-it-works/02-framework/02-plugin-management/02-plugin-setup/index.md +++ b/docs/osx/01-how-it-works/02-framework/02-plugin-management/02-plugin-setup/index.md @@ -15,7 +15,7 @@ How this works: - Although a Plugin is composed by the `Plugin` and `PluginSetup` contracts, the Aragon OSx protocol only knows of the `PluginSetup` contract. - Since the `PluginSetup` contract is the one containing the plugin installation instructions, it is the one in charge of deploying the Plugin instance. Each plugin instance is specific to that DAO, deployed with its own unique parameters. You can review how to build a `PluginSetup` contract [here](../../../../02-how-to-guides/02-plugin-development/index.md). -- The `PluginSetup` contract then interacts with the Aragon OSx framework's `PluginSetupProcessor` contract, which is in charge of applying the installation, update, or uninstallation of a plugin into a DAO. +- The `PluginSetup` contract then interacts with the Aragon OSx framework's `PluginSetupProcessor` contract, which is in charge of applying the installion, update, or uninstallation of a plugin into a DAO. - Publishing a Plugin into the Aragon OSx protocol is done through creating the first version of the plugin's `PluginRepo`. The plugin's `PluginRepo` instance stores all plugin versions. You can read more about that [here](../../../../02-how-to-guides/02-plugin-development/07-publication/index.md). - Except for the gas costs required, plugins are completely free to install, unless decided otherwise by the developer. @@ -44,7 +44,7 @@ The preparation of a `PluginSetup` contract proceeds as follows: - deployment of new contracts - initialization of new storage variables - - deprecating/decommissioning outdated (helper) contracts + - deprecating/decomissioning outdated (helper) contracts - governance settings or other attributes - ... diff --git a/docs/osx/01-how-it-works/02-framework/index.md b/docs/osx/01-how-it-works/02-framework/index.md index 042ffa0e..adc424a2 100644 --- a/docs/osx/01-how-it-works/02-framework/index.md +++ b/docs/osx/01-how-it-works/02-framework/index.md @@ -1,6 +1,5 @@ --- title: Framework - How Everything Connects -sidebar_label: Framework --- ## The Infrastructure Running the Aragon OSx Protocol diff --git a/docs/osx/01-how-it-works/_category_.yml b/docs/osx/01-how-it-works/_category_.yml deleted file mode 100644 index 93cea945..00000000 --- a/docs/osx/01-how-it-works/_category_.yml +++ /dev/null @@ -1,2 +0,0 @@ -collapsible: true -collapsed: false diff --git a/docs/osx/02-how-to-guides/01-dao/index.md b/docs/osx/02-how-to-guides/01-dao/index.md index f174353e..e50ec109 100644 --- a/docs/osx/02-how-to-guides/01-dao/index.md +++ b/docs/osx/02-how-to-guides/01-dao/index.md @@ -1,5 +1,5 @@ --- -title: Operating a DAO +title: How to Operate a DAO --- DAOs are decentralized autonomous organizations. They are a group of people managing on-chain assets through a set of smart contracts. diff --git a/docs/osx/02-how-to-guides/02-plugin-development/02-plugin-types.md b/docs/osx/02-how-to-guides/02-plugin-development/02-plugin-types.md index 86cd6d8e..eb2d3191 100644 --- a/docs/osx/02-how-to-guides/02-plugin-development/02-plugin-types.md +++ b/docs/osx/02-how-to-guides/02-plugin-development/02-plugin-types.md @@ -49,11 +49,11 @@ Some key things to keep in mind: The following table compares the different deployment methods with their benefits and drawbacks: -| | `new` Instantiation | Minimal Proxy (Clones) | Transparent Proxy | UUPS Proxy | -| -------------- | --------------------------------------------- | ------------------------------------------------- | ------------------------------------------------ | --------------------------------------------- | -| upgradeability | no | no | yes | yes | -| gas costs | high | very low | moderate | low | -| difficulty | low | low | high | high | +| | `new` Instantiation | Minimal Proxy (Clones) | Transparent Proxy | UUPS Proxy | +| ------------- | --------------------------------------------- | ------------------------------------------------- | ------------------------------------------------ | --------------------------------------------- | +| upgradability | no | no | yes | yes | +| gas costs | high | very low | moderate | low | +| difficulty | low | low | high | high | Accordingly, we recommend to use [minimal proxies (ERC-1167)](https://eips.ethereum.org/EIPS/eip-1167) for non-upgradeable and [UUPS proxies (1822)](https://eips.ethereum.org/EIPS/eip-1822) for upgradeable plugin. To help you with developing and deploying your plugin within the Aragon infrastructure, we provide the following implementation that you can inherit from: diff --git a/docs/osx/02-how-to-guides/02-plugin-development/03-non-upgradeable-plugin/01-initialization.md b/docs/osx/02-how-to-guides/02-plugin-development/03-non-upgradeable-plugin/01-initialization.md index ac83e5cf..ea62070a 100644 --- a/docs/osx/02-how-to-guides/02-plugin-development/03-non-upgradeable-plugin/01-initialization.md +++ b/docs/osx/02-how-to-guides/02-plugin-development/03-non-upgradeable-plugin/01-initialization.md @@ -74,7 +74,7 @@ contract SimpleAdmin is PluginCloneable { } ``` -We must protect it from being called multiple times by using [OpenZeppelin's `initializer` modifier made available through `Initializable`](https://docs.openzeppelin.com/contracts/4.x/api/proxy#Initializable) and call the internal function `__PluginCloneable_init(IDAO _dao)` available through the `PluginCloneable` base contract to store the `IDAO _dao` reference in the right place. +We must protect it from being called multiple times by using [OpenZeppelin's `initializer` modifier made available through `Initalizable`](https://docs.openzeppelin.com/contracts/4.x/api/proxy#Initializable) and call the internal function `__PluginCloneable_init(IDAO _dao)` available through the `PluginCloneable` base contract to store the `IDAO _dao` reference in the right place. :::caution If you forget calling `__PluginCloneable_init(_dao)` inside your `initialize` function, your plugin won't be associated with a DAO and cannot use the DAO's `PermissionManager`. diff --git a/docs/osx/02-how-to-guides/02-plugin-development/03-non-upgradeable-plugin/02-implementation.md b/docs/osx/02-how-to-guides/02-plugin-development/03-non-upgradeable-plugin/02-implementation.md index f8444bd1..d0b8af77 100644 --- a/docs/osx/02-how-to-guides/02-plugin-development/03-non-upgradeable-plugin/02-implementation.md +++ b/docs/osx/02-how-to-guides/02-plugin-development/03-non-upgradeable-plugin/02-implementation.md @@ -42,7 +42,7 @@ Setting this permission is key because it ensures only signers who have been gra Now that we have created the permission, we will use it to protect the implementation. We want to make sure only the authorized callers holding the `ADMIN_EXECUTE_PERMISSION`, can use the function. -Because we have initialized the [`PluginCloneable` base contract](https://github.com/aragon/osx-commons/blob/develop/contracts/src/plugin/PluginCloneable.sol), we can now use its features, i.e., the [`auth` modifier](https://github.com/aragon/osx-commons/blob/1cf46ff15dbda8481f9ee37558e7ea8b257d51f2/contracts/src/permission/auth/DaoAuthorizable.sol#L30-L35) provided through the `DaoAuthorizable` base class. The `auth('ADMIN_EXECUTE_PERMISSION')` returns an error if the address calling on the function has not been granted that permission, effectively protecting from malicious use cases. +Because we have initialized the [`PluginClonable` base contract](https://github.com/aragon/osx-commons/blob/develop/contracts/src/plugin/PluginCloneable.sol), we can now use its features, i.e., the [`auth` modifier](https://github.com/aragon/osx-commons/blob/1cf46ff15dbda8481f9ee37558e7ea8b257d51f2/contracts/src/permission/auth/DaoAuthorizable.sol#L30-L35) provided through the `DaoAuthorizable` base class. The `auth('ADMIN_EXECUTE_PERMISSION')` returns an error if the address calling on the function has not been granted that permission, effectively protecting from malicious use cases. Later, we will also use the [`dao()` getter function from the base contract](https://github.com/aragon/osx-commons/blob/1cf46ff15dbda8481f9ee37558e7ea8b257d51f2/contracts/src/permission/auth/DaoAuthorizable.sol#L24-L28), which returns the associated DAO for that plugin. diff --git a/docs/osx/02-how-to-guides/02-plugin-development/03-non-upgradeable-plugin/03-setup.md b/docs/osx/02-how-to-guides/02-plugin-development/03-non-upgradeable-plugin/03-setup.md index 33940074..12e45a02 100644 --- a/docs/osx/02-how-to-guides/02-plugin-development/03-non-upgradeable-plugin/03-setup.md +++ b/docs/osx/02-how-to-guides/02-plugin-development/03-non-upgradeable-plugin/03-setup.md @@ -6,7 +6,7 @@ title: Plugin Setup Contract The Plugin Setup contract is the contract defining the instructions for installing, uninstalling, or upgrading plugins into DAOs. This contract prepares the permission granting or revoking that needs to happen in order for plugins to be able to perform actions on behalf of the DAO. -You need it for the plugin to be installed into the DAO. +You need it for the plugin to be installed intto the DAO. ### 1. Finish the Plugin contract @@ -116,7 +116,7 @@ The `prepareInstallation()` function should take in two parameters: 1. the `DAO` it prepares the installation for, and 2. the `_data` parameter containing all the information needed for this function to work properly, in this case, the address we want to set as admin of our DAO. -Hence, the first thing we should do when working on the `prepareInstallation()` function is decode the information from the `_data` parameter. We also want to check that the address is not accidentally set to `address(0)`, which would freeze the DAO forever. +Hence, the first thing we should do when working on the `prepareInsallation()` function is decode the information from the `_data` parameter. We also want to check that the address is not accidentally set to `address(0)`, which would freeze the DAO forever. ```solidity import {Clones} from '@openzeppelin/contracts/proxy/Clones.sol'; diff --git a/docs/osx/02-how-to-guides/02-plugin-development/03-non-upgradeable-plugin/index.md b/docs/osx/02-how-to-guides/02-plugin-development/03-non-upgradeable-plugin/index.md index 3672b5ac..bf7da198 100644 --- a/docs/osx/02-how-to-guides/02-plugin-development/03-non-upgradeable-plugin/index.md +++ b/docs/osx/02-how-to-guides/02-plugin-development/03-non-upgradeable-plugin/index.md @@ -14,7 +14,7 @@ Some observations: Before moving on with the Guide, make sure you've read our documentation on [Choosing the Best Type for Your Plugin](../02-plugin-types.md) to make sure you're selecting the right type of contract for your Plugin. -## Building a Non-Upgradable Plugin +## Building a Non-Upgradeble Plugin We will build a plugin which returns "Hello world!" and the amount of times the function has been called. @@ -43,7 +43,7 @@ sudo apt-get install -y nodejs [Here's a tutorial](https://hardhat.org/tutorial/setting-up-the-environment) on installing this if you haven't done so already. -2. Next up, we want to create a Hardhat project in our terminal. This is the Solidity framework we'll use to get our project up and running. +2. Next up, we want to create a Hardhat project in our terminal. This is the Solidity framework we'll use to get our project up and runing. ```bash npm init diff --git a/docs/osx/02-how-to-guides/02-plugin-development/04-upgradeable-plugin/01-initialization.md b/docs/osx/02-how-to-guides/02-plugin-development/04-upgradeable-plugin/01-initialization.md index 1b64cdcb..c843ec27 100644 --- a/docs/osx/02-how-to-guides/02-plugin-development/04-upgradeable-plugin/01-initialization.md +++ b/docs/osx/02-how-to-guides/02-plugin-development/04-upgradeable-plugin/01-initialization.md @@ -1,12 +1,12 @@ --- -title: Initialization +title: Intialization --- ## How to Initialize Upgradeable Plugins To deploy your implementation contract via the [UUPS pattern (ERC-1822)](https://eips.ethereum.org/EIPS/eip-1822), you inherit from the `PluginUUPSUpgradeable` contract. -We must protect it from being set up multiple times by using [OpenZeppelin's `initializer` modifier made available through `Initializable`](https://docs.openzeppelin.com/contracts/4.x/api/proxy#Initializable). In order to do this, we will call the internal function `__PluginUUPSUpgradeable_init(IDAO _dao)` function available through the `PluginUUPSUpgradeable` base contract to store the `IDAO _dao` reference in the right place. +We must protect it from being set up multiple times by using [OpenZeppelin's `initializer` modifier made available through `Initalizable`](https://docs.openzeppelin.com/contracts/4.x/api/proxy#Initializable). In order to do this, we will call the internal function `__PluginUUPSUpgradeable_init(IDAO _dao)` function available through the `PluginUUPSUpgradeable` base contract to store the `IDAO _dao` reference in the right place. :::note This has to be called - otherwise, anyone else could call the plugin's initialization with whatever params they wanted. diff --git a/docs/osx/02-how-to-guides/02-plugin-development/04-upgradeable-plugin/03-setup.md b/docs/osx/02-how-to-guides/02-plugin-development/04-upgradeable-plugin/03-setup.md index b90f1812..4f3fc186 100644 --- a/docs/osx/02-how-to-guides/02-plugin-development/04-upgradeable-plugin/03-setup.md +++ b/docs/osx/02-how-to-guides/02-plugin-development/04-upgradeable-plugin/03-setup.md @@ -47,7 +47,7 @@ The `prepareInstallation()` function takes in two parameters: 1. the `DAO` it should prepare the installation for, and 2. the `_data` parameter containing all the information needed for this function to work properly, encoded as a `bytes memory`. In this case, we get the number we want to store. -Hence, the first thing we should do when working on the `prepareInstallation()` function is decode the information from the `_data` parameter. +Hence, the first thing we should do when working on the `prepareInsallation()` function is decode the information from the `_data` parameter. Similarly, the `prepareUninstallation()` function takes in a `payload`. ```solidity @@ -131,7 +131,7 @@ Firstly, we'll make sure our preferred network is well setup within our `hardhat ```js import '@nomicfoundation/hardhat-toolbox'; -// To find your Alchemy key, go to https://dashboard.alchemy.com/. Infura or any other provider would work here as well. +// To find your Alchemy key, go to https://dashboard.alchemy.com/. Infure or any other provider would work here as well. const goerliAlchemyKey = 'add-your-own-alchemy-key'; // To find a private key, go to your wallet of choice and export a private key. Remember this must be kept secret at all times. const privateKeyGoerli = 'add-your-account-private-key'; @@ -177,8 +177,7 @@ async function main() { console.log('Deploying contracts with the account:', deployer.address); console.log('Account balance:', (await deployer.getBalance()).toString()); - const getSimpleStorageSetup = - await ethers.getContractFactory('SimpleStorageSetup'); + const getSimpleStorageSetup = await ethers.getContractFactory('SimpleStorageSetup'); const SimpleStorageSetup = await SimpleStorageSetup.deploy(); await SimpleStorageSetup.deployed(); diff --git a/docs/osx/02-how-to-guides/02-plugin-development/04-upgradeable-plugin/04-subsequent-builds.md b/docs/osx/02-how-to-guides/02-plugin-development/04-upgradeable-plugin/04-subsequent-builds.md index 3568eaaa..bd2d9bcd 100644 --- a/docs/osx/02-how-to-guides/02-plugin-development/04-upgradeable-plugin/04-subsequent-builds.md +++ b/docs/osx/02-how-to-guides/02-plugin-development/04-upgradeable-plugin/04-subsequent-builds.md @@ -21,7 +21,7 @@ Make sure you have at least one build already deployed and published into the Ar In this second build implementation we want to update the functionality of our plugin - in this case, we want to update the storage of our plugin with new values. Specifically, we will add a second storage variable `address public account;`. Additional to the `initializeFromBuild2` function, we also want to add a second setter function `storeAccount` that uses the same permission as `storeNumber`. -As you can see, we're still inheriting from the `PluginUUPSUpgradeable` contract and simply overriding some implementation from the previous build. The idea is that when someone upgrades the plugin and calls on these functions, they'll use this new upgraded implementation, rather than the older one. +As you can see, we're still inheritting from the `PluginUUPSUpgradeable` contract and simply overriding some implementation from the previous build. The idea is that when someone upgrades the plugin and calls on these functions, they'll use this new upgraded implementation, rather than the older one. ```solidity import {PluginUUPSUpgradeable, IDAO} '@aragon/osx/core/plugin/PluginUUPSUpgradeable.sol'; @@ -60,7 +60,7 @@ contract SimpleStorageBuild2 is PluginUUPSUpgradeable { } ``` -Builds that you publish don't necessarily need to introduce new storage variables of your contracts and don't necessarily need to change the storage. To read more about Upgradeability, check out [OpenZeppelin's UUPSUpgradeability implementation here](https://docs.openzeppelin.com/contracts/4.x/api/proxy#UUPSUpgradeable). +Builds that you publish don't necessarily need to introduce new storage varaibles of your contracts and don't necessarily need to change the storage. To read more about Upgradeability, check out [OpenZeppelin's UUPSUpgradeability implementation here](https://docs.openzeppelin.com/contracts/4.x/api/proxy#UUPSUpgradeable). :::note Note that because these contracts are Upgradeable, keeping storage gaps `uint256 [50] __gap;` in dependencies is a must in order to avoid storage corruption. To learn more about storage gaps, review OpenZeppelin's documentation [here](https://docs.openzeppelin.com/upgrades-plugins/1.x/writing-upgradeable#storage-gaps). diff --git a/docs/osx/02-how-to-guides/02-plugin-development/04-upgradeable-plugin/05-updating-versions.md b/docs/osx/02-how-to-guides/02-plugin-development/04-upgradeable-plugin/05-updating-versions.md index c21935e6..e10e3b44 100644 --- a/docs/osx/02-how-to-guides/02-plugin-development/04-upgradeable-plugin/05-updating-versions.md +++ b/docs/osx/02-how-to-guides/02-plugin-development/04-upgradeable-plugin/05-updating-versions.md @@ -146,7 +146,7 @@ contract SimpleStorageBuild2Setup is PluginSetup { } ``` -The key thing to review in this new Plugin Setup contract is its `prepareUpdate()` function. The function only contains a condition checking from which build number the update is transitioning to build `2`. Here, it is the build number `1` as this is the only update path we support. Inside, we decode the `address _account` input argument provided with `bytes _date` and pass it to the `initializeFromBuild1` function taking care of initializing the storage that was added in this build. +The key thing to review in this new Plugin Setup contract is its `prepareUpdate()` function. The function only contains a condition checking from which build number the update is transitioning to build `2`. Here, it is the build number `1` as this is the only update path we support. Inside, we decode the `address _account` input argument provided with `bytes _date` and pass it to the `initializeFromBuild1` function taking care of intializing the storage that was added in this build. ### 3. Future builds @@ -226,7 +226,7 @@ contract SimpleStorageBuild3 is PluginUUPSUpgradeable { -With each new build implementation, we will need to update the Plugin Setup contract to be able to update to that new version. We do this through updating the `prepareUpdate()` function to support any new features that need to be set up. +With each new build implementation, we will need to udate the Plugin Setup contract to be able to update to that new version. We do this through updating the `prepareUpdate()` function to support any new features that need to be set up.prepareUpdate function