diff --git a/packages/contracts/docs/modules/ROOT/pages/how-it-works/framework-dao.adoc b/packages/contracts/docs/modules/ROOT/pages/how-it-works/framework-dao.adoc deleted file mode 100644 index e09152fe5..000000000 --- a/packages/contracts/docs/modules/ROOT/pages/how-it-works/framework-dao.adoc +++ /dev/null @@ -1,12 +0,0 @@ -= Protocol Governance - -== Governing the Aragon OSx Framework - -To govern the framework infrastructure, a **Framework DAO** was deployed. - -The Framework DAO controls the permissions of and between the framework-related contracts required to configure and maintain them as well as to replace or upgrade them. - -This Framework DAO constitutes the **governance layer** of the Aragon OSx DAO Framework. - - -// not added to the nav bar in the first iteration consider adding it in the future \ No newline at end of file diff --git a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/dao/action-execution.adoc b/packages/contracts/docs/modules/ROOT/pages/how-to-guides/dao/action-execution.adoc deleted file mode 100644 index 8b5d82950..000000000 --- a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/dao/action-execution.adoc +++ /dev/null @@ -1,144 +0,0 @@ -= Executing actions on behalf of the DAO - -## Using the DAO Executor - -Executing actions on behalf of the DAO is done through the `execute` function from the `DAO.sol` contract. This function allows us to link:https://github.com/aragon/osx/blob/develop/packages/contracts/src/core/dao/DAO.sol[pass an array of actions] to be executed by the DAO contract itself. - -However, for the `execute` call to work, the address calling the function (the `msg.sender`) needs to have the xref:how-it-works/core/permissions/index.adoc#permissions_native_to_the_dao_contract[`EXECUTE_PERMISSION`]. This is to prevent anyone from being able to execute actions on behalf of the DAO and keep your assets safe from malicious actors. - -## How to grant the Execute Permission - -Usually, the `EXECUTE_PERMISSION` is granted to a governance plugin of the DAO so that only the approved proposals can be executed. For example, we'd grant the `EXECUTE_PERMISSION` to the address of the Multisig Plugin. That way, when a proposal is approved by the required members of the multisig, the plugin is able to call the `execute` function on the DAO in order to get the actions executed. - -To grant the `EXECUTE_PERMISSION` to an address, you'll want to call on the `PermissionManager`'s link:https://github.com/aragon/osx/blob/develop/packages/contracts/src/core/permission/PermissionManager.sol#L105[grant function] and pass it 4 parameters: - -- `where`: the address of the contract containing the function `who` wants access to -- `who`: the address (EOA or contract) receiving the permission -- `permissionId`: the permission identifier the caller needs to have in order to be able to execute the action -- `condition`: the address of the condition contract that will be asked (if any) before authorizing the call to happen - -CAUTION: You probably don't want to grant `EXECUTE_PERMISSION` to any random address, since this gives the address access to execute any action on behalf of the DAO. We recommend you only grant `EXECUTE_PERMISSION` to governance plugins to ensure the safety of your assets. Granting `EXECUTE_PERMISSION` to an externally owned account is considered an anti-pattern. - -## Examples - -### Calling a DAO Function - -Imagine you want to call an internal function inside the `DAO` contract, for example, to manually xref:how-it-works/core/permissions/index.adoc[grant or revoke a permission]. The corresponding `Action` and `execute` function call look as follows: - -```solidity -function exampleGrantCall( - DAO dao, - bytes32 _callId, - address _where, - address _who, - bytes32 _permissionId -) { - // Create the action array - IDAO.Action[] memory actions = new IDAO.Action[](1); - actions[0] = IDAO.Action({ - to: address(dao), - value: 0, - data: abi.encodeWithSelector(PermissionManager.grant.selector, _where, _who, _permissionId) - }); - - // Execute the action array - (bytes[] memory execResults, ) = dao.execute({ - _callId: _callId, - _actions: actions, - _allowFailureMap: 0 - }); -} -``` - -Here we use the selector of the TODO:GIORGI [`grant` function](../../03-reference-guide/core/permission/PermissionManager.md#external-function-grant). To revoke the permission, the selector of the [`revoke` function](../../03-reference-guide/core/permission/PermissionManager.md#external-function-revoke) must be used. - -If the caller possesses the xref:how-it-works/core/permissions/index.adoc#permissions_native_to_the_dao_contract[`ROOT_PERMISSION_ID` permission] on the DAO contract, the call becomes simpler and cheaper: - -CAUTION: Granting the `ROOT_PERMISSION_ID` permission to other contracts other than the `DAO` contract is dangerous and considered as an anti-pattern. - -```solidity -function exampleGrantFunction(DAO dao, address _where, address _who, bytes32 _permissionId) { - dao.grant(_where, _who, _permissionId); // For this to work, the `msg.sender` needs the `ROOT_PERMISSION_ID` -} -``` - -### Sending Native Tokens - -Send `0.1 ETH` from the DAO treasury to Alice. -The corresponding `Action` and `execute` function call would look as follows: - -```solidity -function exampleNativeTokenTransfer(IDAO dao, bytes32 _callId, address _receiver) { - // Create the action array - IDAO.Action[] memory actions = new IDAO.Action[](1); - - actions[0] = IDAO.Action({to: _receiver, value: 0.1 ether, data: ''}); - - // Execute the action array - dao.execute({_callId: _callId, _actions: actions, _allowFailureMap: 0}); -} -``` - -### Calling a Function from an External Contract - -Imagine that you want to call an external function, let's say in a `Calculator` contract that adds two numbers for you. The corresponding `Action` and `execute` function call look as follows: - -```solidity -contract ICalculator { - function add(uint256 _a, uint256 _b) external pure returns (uint256 sum); -} - -function exampleFunctionCall( - IDAO dao, - bytes32 _callId, - ICalculator _calculator, - uint256 _a, - uint256 _b -) { - // Create the action array - IDAO.Action[] memory actions = new IDAO.Action[](1); - actions[0] = IDAO.Action({ - to: address(_calculator), - value: 0, // 0 native tokens must be sent with this call - data: abi.encodeCall(_calculator.add, (_a, _b)) - }); - - // Execute the action array - (bytes[] memory execResults, ) = dao.execute({ - _callId: _callId, - _actions: actions, - _allowFailureMap: 0 - }); - - // Decode the action results - uint256 sum = abi.decode(execResults[0], (uint256)); // the result of `add(_a,_b)` -} -``` - -### Calling a Payable Function - -Wrap `0.1 ETH` from the DAO treasury into `wETH` by depositing it into the link:https://goerli.etherscan.io/token/0xb4fbf271143f4fbf7b91a5ded31805e42b2208d6#writeContract[Goerli WETH9 contract]. -The corresponding `Action` and `execute` function call look as follows: - -```solidity -interface IWETH9 { - function deposit() external payable; - - function withdraw(uint256 _amount) external; -} - -function examplePayableFunctionCall(IDAO dao, bytes32 _callId, IWETH9 _wethToken) { - // Create the action array - - IDAO.Action[] memory actions = new IDAO.Action[](1); - - actions[0] = IDAO.Action({ - to: address(_wethToken), - value: 0.1 ether, - data: abi.encodeCall(IWETH9.deposit, ()) - }); - - // Execute the action array - dao.execute({_callId: _callId, _actions: actions, _allowFailureMap: 0}); -} -``` diff --git a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/dao/best-practices.adoc b/packages/contracts/docs/modules/ROOT/pages/how-to-guides/dao/best-practices.adoc deleted file mode 100644 index e121fa427..000000000 --- a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/dao/best-practices.adoc +++ /dev/null @@ -1,20 +0,0 @@ -= Best Practices - -=== Some Advice When Operating your DAO - -### DOs 👌 - -- Make sure that at least one address (typically a governance plugin) has `EXECUTE_PERMISSION_ID` permission so that something can be executed on behalf of the DAO. -- Check every proposal asking to install, update, or uninstall a plugin with utmost care and review. Installation means granting an external contract permissions to do things on behalf of your DAO, so you want to be extra careful about: - - the implementation contract - - the setup contract - - the helper contracts - - the permissions being granted/revoked - -### DON'Ts ✋ - -- Incapacitate your DAO by revoking all `EXECUTE_PERMISSION`. This means your DAO will be blocked and any assets you hold may be locked in forever. This can happen through: - - uninstalling your last governance plugin. - - applying an update to your last governance plugin. -- Don't give permissions to directly call functions from the DAO. Better and safer to use a plugin instead. -- If you're using the Token Voting plugin in your DAO, make sure you don't mint additional tokens without careful consideration. If you mint too many at once, this may lock your DAO, since you will not be able to reach the minimum participation threshold. This happens if there are not enough tokens already on the market to meet the minimum participation percentage and the DAO owns most of the governance tokens. diff --git a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/dao/index.adoc b/packages/contracts/docs/modules/ROOT/pages/how-to-guides/dao/index.adoc deleted file mode 100644 index bd10b753c..000000000 --- a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/dao/index.adoc +++ /dev/null @@ -1,20 +0,0 @@ -= 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. - -## What do you need to know in order to operate your DAO? - -DAOs manage assets through collective decision-making mechanisms. Although a lot can be said of the social, behavioral aspects of operating a DAO, in this guide we will focus on the technical aspects. - -In Aragon OSx, DAOs are a treasury and a permission management system - all other functionality is enabled through "capsules of opt-in functionality allowing the DAO to work in custom ways". These are called Plugins. - -NOTE: Plugins are smart contracts which extend the functionality of what the DAO can do. They are able to execute actions on behalf of the DAO through permissions the DAO grants or revokes them. - -Decision-making mechanisms are one example of Plugins. Treasury management, action bundles, or connections to other smart contracts are others. - -In this section, we'll go through how to operate and maintain your DAO: - -- xref:how-to-guides/dao/best-practices.adoc[A Summary of Best Practices] -- xref:how-to-guides/dao/action-execution.adoc[How to execute actions on behalf of the DAO] -- xref:how-to-guides/dao/managing-plugins.adoc[How to manage a DAO's plugins] -- xref:how-to-guides/dao/protocol-upgrades.adoc[How to upgrade your DAO to a future Aragon OSx Releases] diff --git a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/dao/managing-plugins.adoc b/packages/contracts/docs/modules/ROOT/pages/how-to-guides/dao/managing-plugins.adoc deleted file mode 100644 index 0748687e6..000000000 --- a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/dao/managing-plugins.adoc +++ /dev/null @@ -1,48 +0,0 @@ -= Manage your DAO's Plugins - -=== How to manage the Plugins within your DAO - -You can install, uninstall or update any plugin into your DAO. If you want to dive deeper into plugins, check out xref:how-it-works/core/plugins/index.adoc[how plugins work here]. - -Before diving deeper into this guide, make sure that you understand xref:how-it-works/core/permissions/index.adoc[permissions]and know about the xref:how-it-works/core/dao/index.adoc[DAO executor]. - -#### How to create a DAO with Plugins - -When you create your DAO, you must **install at least one functioning governance plugin** (meaning one plugin having the `EXECUTION_PERMISSION`) so your have a mechanism of executing actions on behalf of your DAO. -This is crucial because otherwise nobody can operate the DAO and it would become incapacitated right after it was created. You would have spent gas for nothing. - -NOTE: If you create your DAO through the link:https://app.aragon.org[Aragon App] or the link:https://devs.aragon.org/docs/sdk[Aragon SDK], this will be checked and you will be warned in case you have not selected a suitable Aragon plugin. - -Although the easiest (and recommended) way to create your DAO is through the link:https://app.aragon.org[Aragon App] or -the link:https://devs.aragon.org/docs/sdk[Aragon SDK], you can also do it directly from the protocol through calling -on the link:https://github.com/aragon/osx/blob/develop/packages/contracts/src/framework/dao/DAOFactory.sol#L63[`createDAO` function] -from the `DAOFactory` contract and passing it the calldata `DAOSettings` for your DAO as well as the `PluginSettings` array -referencing the plugins and the settings to be installed upon DAO creation. - -#### How to change a DAO's Governance Setup after a DAO has been created - -After a DAO is created with at least one plugin installed with `EXECUTE_PERMISSION` on the DAO, it's likely you may want to change change your governance setup later -on by xref:how-it-works/framework/plugin-management/plugin-setup/index.adoc[installing, updating, or uninstalling plugins]. - -Here, it is very important that you **maintain at least one functioning governance plugin** (a contract with `EXECUTE_PERMISSION` on the DAO) so that your -assets are not locked in the future. In that regard, you want to be careful to not accidentally: - -- uninstall every plugin within your DAO, or -- update or upgrade the plugin or otherwise change the internal plugin settings. - -If you do that, nobody would be able to create proposals and execute actions on the DAO anymore. Accordingly, DAOs must review -proposals requesting to change the governance setup with utmost care before voting for them. In the next section, -we explain how to review a proposal properly and what to pay attention too. - -### How to maintain Execution Permission on the DAO - -A very important thing to consider when operating your DAO is to make sure that you do not lock it - meaning, you allow it into a state where the DAO cannot execute actions anymore. - -The accidental loss of the permission to execute actions on your DAO (xref:how-it-works/core/permissions/index.adoc#permissions_native_to_the_dao_contract[the `EXECUTION_PERMISSION_ID` permission]) incapacitates your DAO. -If this happens, you are not able to withdraw funds or act through the DAO, unless you have the `ROOT_PERMISSION_ID` on the DAO. - -IMPORTANT: Do not interact directly with the smart contracts unless you know exactly what you are doing, **especially if this involves granting or revoking permissions**. -Instead, use the Aragon App or Aragon SDK for creating and managing your DAO and interacting with the smart contracts. - -If you interact with the Aragon OSx protocol through the Aragon App frontend or the Aragon SDK and use only audited and verified plugins, -this will not happen. However, diligence and care is required in some situations. diff --git a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/dao/protocol-upgrades.adoc b/packages/contracts/docs/modules/ROOT/pages/how-to-guides/dao/protocol-upgrades.adoc deleted file mode 100644 index 21d1f7b74..000000000 --- a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/dao/protocol-upgrades.adoc +++ /dev/null @@ -1,11 +0,0 @@ -= Upgrade your DAO to future Aragon OSx Versions - -== Upgrading to Future Aragon OSx Protocol Versions - -At Aragon, we are constantly working on improving the Aragon OSx framework. - -To make it easy for your DAO to switch to future Aragon OSx protocol versions, we added the possibility to upgrade our protocol in the future. - -Whenever we provide a new Aragon OSx protocol version, it will be possible to upgrade your DAO and associated plugins through your DAO dashboard. - -link:https://aragondevelopers.substack.com/[Add your email here] if you'd like to receive updates when this happens! diff --git a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/index.adoc b/packages/contracts/docs/modules/ROOT/pages/how-to-guides/index.adoc deleted file mode 100644 index 4ce65adfb..000000000 --- a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/index.adoc +++ /dev/null @@ -1,46 +0,0 @@ -= Tutorials - -== Welcome to our Tutorials on Using the Aragon OSx Protocol! - -With a few lines of code, the Aragon OSx protocol allows you create, manage, and change your on-chain organizations, through extending functionality for DAOs through the installation and uninstallation of plugins. - -The organizations that survive the longest are the ones that easily adapt to changing circumstances. DAOs too need a way to adapt and evolve, even if they’re governed on an immutable blockchain. - -This is where Plugins come in! - -### DAO Plugins - -DAO Plugins are smart contracts extending the functionality for DAOs - -Some examples of DAO Plugins are: - -- 💰 Treasury management tools (i.e. staking, yield distributions, etc), -- 👩🏾‍⚖️ Governance mechanisms for collective decision-making (i.e. NFT voting, multi-sig voting, etc) -- 🔌 Integrations with other ecosystem projects (i.e. Snapshot off-chain voting with Aragon on-chain execution, AI-enabled decision-makers, etc) -- …. basically anything you’d like your DAO to do! - -In the Aragon OSx protocol, everything a DAO does is decided and implemented through plugins. - -Technically speaking, Aragon DAOs are: - -- 💳 A treasury: holding all of the DAO’s assets, and -- 🤝 A permission management system: protecting the assets, through checking that only addresses with x permissions can execute actions on behalf of the DAO. - -All other functionality is enabled through plugins. This allows DAOs to be extremely flexible and modular as they mature, through installing and uninstalling these plugins as needs arise. - -On the technical level, plugins are composed of two key contracts: - -- ⚡️ The Plugin implementation contract: containing all of the logic and functionality for your DAO, and -- 👩🏻‍🏫 The Plugin Setup contract: containing the installation, uninstallation and upgrade instructions for your plugin. - -image::what_is_a_plugin.png[align="center"] - - -Through plugins, we provide a secure, flexible way for on-chain organizations to iterate as they grow. - -We enable everyone to experiment with governance at the speed of software! - -Check out our How-To-Guides on: - -- xref:how-to-guides/plugin-development/index.adoc[How to Develop your own Plugin] -- xref:how-to-guides/dao/index.adoc[How to Operate your DAO] diff --git a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/best-practices.adoc b/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/best-practices.adoc deleted file mode 100644 index e9848359d..000000000 --- a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/best-practices.adoc +++ /dev/null @@ -1,25 +0,0 @@ -= Before Starting - -== Advice for Developing a Plugin - -### DOs 👌 - -- Document your contracts using link:https://docs.soliditylang.org/en/v0.8.17/natspec-format.html[NatSpec]. -- Test your contracts, e.g., using toolkits such as link:https://hardhat.org/hardhat-runner/docs/guides/test-contracts[hardhat (JS)] or link:https://book.getfoundry.sh/forge/tests[Foundry (Rust)]. -- Use the `auth` modifier to control the access to functions in your plugin instead of `onlyOwner` or similar. -- Write plugins implementations that need minimal permissions on the DAO. -- Write `PluginSetup` contracts that remove all permissions on uninstallation that they requested during installation or updates. -- Plan the lifecycle of your plugin (need for upgrades). -- Follow our xref:how-to-guides/plugin-development/publication/versioning.adoc[versioning guidelines]. - -### DON'Ts ✋ - -- Leave any contract uninitialized. -- Grant the `ROOT_PERMISSION_ID` permission to anything or anyone. -- Grant with `who: ANY_ADDR` unless you know what you are doing. -- Expect people to grant or revoke any permissions manually during the lifecycle of a plugin. The `PluginSetup` should take this complexity away from the user and after uninstallation, all permissions should be removed. -- Write upgradeable contracts that: - - Repurpose existing storage (in upgradeable plugins). - - Inherit from previous versions as this can mess up the inheritance chain. Instead, write self-contained contracts. - -In the following sections, you will learn about the details about plugin development. diff --git a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/governance-plugins/index.adoc b/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/governance-plugins/index.adoc deleted file mode 100644 index 2f47967da..000000000 --- a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/governance-plugins/index.adoc +++ /dev/null @@ -1,33 +0,0 @@ -= Governance Plugins - -== How to Build a Governance Plugin - -One of the most common use cases for plugins are governance plugins. Governance plugins are plugins DAOs install to help -them make decisions. - -### What are Governance Plugins - -Governance plugins are characterized by the **ability to execute actions in the DAO** they have been installed to. -Accordingly, the `EXECUTE_PERMISSION_ID` is granted on installation on the installing DAO to the governance plugin contract. - -```solidity -grant({ - where: installingDao, - who: governancePlugin, - permissionId: EXECUTE_PERMISSION_ID -}); -``` - -Beyond this fundamental ability, governance plugins usually implement two interfaces: - -- xref:how-to-guides/plugin-development/governance-plugins/proposals.adoc[The IProposal interface] introducing the **notion of proposals** and how they are created and executed. -- xref:how-to-guides/plugin-development/governance-plugins/proposals.adoc[The IMembership interface] introducing the **notion of membership** to the DAO. - -### Examples of Governance Plugins - -Some examples of governance plugins are: - -- link:https://github.com/aragon/osx/tree/main/packages/contracts/src/plugins/governance/majority-voting/token[A token-voting plugin]: Results are based on what the majority votes and the vote's weight is determined by how many tokens an account holds. Ex: Alice has 10 tokens, Bob 2, and Alice votes yes, the yes wins. -- link:https://github.com/aragon/osx/tree/main/packages/contracts/src/plugins/governance/multisig[Multisig plugin]: A determined set of addresses is able to approve. Once `x` amount of addresses approve (as determined by the plugin settings), then the proposal automatically succeeds. -- link:https://github.com/aragon/osx/tree/main/packages/contracts/src/plugins/governance/admin[Admin plugin]: One address can create and immediately execute proposals on the DAO (full control). - diff --git a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/governance-plugins/membership.adoc b/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/governance-plugins/membership.adoc deleted file mode 100644 index 99c9288fd..000000000 --- a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/governance-plugins/membership.adoc +++ /dev/null @@ -1,91 +0,0 @@ -= Membership - -== The `IMembership` Interface - -The `IMembership` interface defines common functions and events for for plugins that keep track of membership in a DAO. -This plugins can be used to define who can vote on proposals, who can create proposals, etc. The list of members can be defined -in the plugin itself or by a contract that defines the membership like an ERC20 or ERC721 token. - -The interface is defined as follows: - -```solidity title= -/// @notice An interface to be implemented by DAO plugins that define membership. -interface IMembership { - /// @notice Emitted when members are added to the DAO plugin. - /// @param members The list of new members being added. - event MembersAdded(address[] members); - - /// @notice Emitted when members are removed from the DAO plugin. - /// @param members The list of existing members being removed. - event MembersRemoved(address[] members); - - /// @notice Emitted to announce the membership being defined by a contract. - /// @param definingContract The contract defining the membership. - event MembershipContractAnnounced(address indexed definingContract); - - /// @notice Checks if an account is a member of the DAO. - /// @param _account The address of the account to be checked. - /// @return Whether the account is a member or not. - /// @dev This function must be implemented in the plugin contract that introduces the members to the DAO. - function isMember(address _account) external view returns (bool); -} -``` - -The interface contains three events and one function. - -### `MembersAdded` event - -The members added event should be emitted when members are added to the DAO plugin. It only contains one -`address[] members` parameter that references the list of new members being added. - -- `members`: The list of new members being added. - -### `MembersRemoved` event - -The members added event should be emitted when members are removed from the DAO plugin. It only contains one `address[] members` -parameter that references the list of members being removed. - -### `MembershipContractAnnounced` event - -This event should be emitted during the initialization of the membership plugin to announce the membership being defined by a contract. -It contains the defining contract as a parameter. - -### `isMember` function - -This is a simple function that should be implemented in the plugin contract that introduces the members to the DAO. It checks if an -account is a member of the DAO and returns a boolean value. - -## Usage - -```solidity - -contract MyPlugin is IMembership { - address public membershipContract; - - constructor(address tokenAddress) { - // Initialize the membership contract - // ... - membershipContract = tokenAddress; - emit MembershipContractAnnounced(tokenAddress); - } - - function isMember(address _account) external view returns (bool) { - // Check if the account is a member of the DAO - // ... - } - - // Other plugin functions - function addMembers(address[] memory _members) external { - // Add members to the DAO - // ... - emit MembersAdded(_members); - } - - function removeMembers(address[] memory _members) external { - // Remove members from the DAO - // ... - emit MembersRemoved(_members); - } -} - -``` diff --git a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/governance-plugins/proposals.adoc b/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/governance-plugins/proposals.adoc deleted file mode 100644 index 8953aba0b..000000000 --- a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/governance-plugins/proposals.adoc +++ /dev/null @@ -1,95 +0,0 @@ -= Proposals - -== The `IProposal` Interface - -The `IProposal` interface is used to create and execute proposals containing actions and a description. - -The interface is defined as follows: - -```solidity -interface IProposal { - /// @notice Emitted when a proposal is created. - /// @param proposalId The ID of the proposal. - /// @param creator The creator of the proposal. - /// @param startDate The start date of the proposal in seconds. - /// @param endDate The end date of the proposal in seconds. - /// @param metadata The metadata of the proposal. - /// @param actions The actions that will be executed if the proposal passes. - /// @param allowFailureMap A bitmap allowing the proposal to succeed, even if individual actions might revert. If the bit at index `i` is 1, the proposal succeeds even if the `i`th action reverts. A failure map value of 0 requires every action to not revert. - event ProposalCreated( - uint256 indexed proposalId, - address indexed creator, - uint64 startDate, - uint64 endDate, - bytes metadata, - IDAO.Action[] actions, - uint256 allowFailureMap - ); - - /// @notice Emitted when a proposal is executed. - /// @param proposalId The ID of the proposal. - event ProposalExecuted(uint256 indexed proposalId); - - /// @notice Returns the proposal count determining the next proposal ID. - /// @return The proposal count. - function proposalCount() external view returns (uint256); -} -``` - -This interface contains two events and one function - -### `ProposalCreated` event - -This event should be emitted when a proposal is created. It contains the following parameters: - -- `proposalId`: The ID of the proposal. -- `creator`: The creator of the proposal. -- `startDate`: The start block number of the proposal. -- `endDate`: The end block number of the proposal. -- `metadata`: This should contain a metadata ipfs hash or any other type of link to the metadata of the proposal. -- `actions`: The actions that will be executed if the proposal passes. -- `allowFailureMap`: A bitmap allowing the proposal to succeed, even if individual actions might revert. If the bit at index `i` is 1, the proposal succeeds even if the `i`th action reverts. A failure map value of 0 requires every action to not revert. - -### `ProposalExecuted` event - -This event should be emitted when a proposal is executed. It contains the proposal ID as a parameter. - -### `proposalCount` function - -This function should return the proposal count determining the next proposal ID. - -## Usage - -```solidity -contract MyPlugin is IProposal { - uint256 public proposalCount; - - function createProposal( - uint64 _startDate, - uint64 _endDate, - bytes calldata _metadata, - IDAO.Action[] calldata _actions, - uint256 _allowFailureMap - ) external { - proposalCount++; - emit ProposalCreated( - proposalCount, - msg.sender, - _startDate, - _endDate, - _metadata, - _actions, - _allowFailureMap - ); - } - - function proposalCount() external view returns (uint256) { - return proposalCount; - } - - function executeProposal(uint256 _proposalId) external { - // Execute the proposal - emit ProposalExecuted(_proposalId); - } -} -``` diff --git a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/index.adoc b/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/index.adoc deleted file mode 100644 index c7a96f764..000000000 --- a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/index.adoc +++ /dev/null @@ -1,65 +0,0 @@ -= How to build a DAO Plugin - -== Plugin Development Quickstart Guide - -Plugins are how we extend the functionality for DAOs. In Aragon OSx, everything a DAO can do is based on Plugin functionality enabled through permissions. - -In this Quickstart guide, we will use the Aragon Hardhat template to set up a plugin. - -## Setting up your environment - -We recommend using our link:https://github.com/aragon/osx-plugin-template-hardhat[hardhat template] to get started. If you don't have -it installed, you can do so by running: - -```bash -git clone github.com/aragon/osx-plugin-template-hardhat -``` - -Once you have cloned the repository the first step is to add a `.env` file with your `ALCHEMY_API_KEY`, -there is a link:https://github.com/aragon/osx-plugin-template-hardhat/blob/main/.env.example[.env.example] file you can use as a template. - -This file contains more env variables that you may need throughout the development process, but to get started you only need to -add the `ALCHEMY_API_KEY`. - -```bash -# INCOMPLETE - PLEASE FILL IN THE MISSING VALUES -# GENERAL - -## The network used for testing purposes -NETWORK_NAME="sepolia" # ["mainnet", "sepolia", "polygon", "baseMainnet", "arbitrum"] - -# CONTRACTS - -## One or multiple hex encoded private keys separated by commas `,` replacing the hardhat default accounts. -PRIVATE_KEY="0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80" # Default hardhat account 0 private key. DON'T USE FOR DEPLOYMENTS - -## Alchemy RPC endpoint credentials -ALCHEMY_API_KEY="zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz" -``` - -Once the `.env` file is created, you can run the following command to install the dependencies: - -```bash -yarn install && cd packages/contracts && yarn install && yarn build && yarn typechain -``` - -Now you are ready to start developing your plugin. You should have two files called `MyPlugin.sol` and `MyPluginSetup.sol` inside -the `contracts` folder. - -The template is already set up with a basic plugin and plugin setup contract. You can start by modifying these files to create -your own plugin. The tests and deployment scripts are also set up for you to use. - -## Next Steps - -For more information on how to use the template, you can check the link:https://github.com/aragon/osx-plugin-template-hardhat/blob/main/README.md[README] and -the link:https://github.com/aragon/osx-plugin-template-hardhat/blob/main/USAGE_GUIDE.md[USAGE GUIDE]. - -For more information on how to develop a plugin, you can check our plugin development guides: - -- xref:how-to-guides/plugin-development/best-practices.adoc[Best practices and patterns] -- xref:how-to-guides/plugin-development/plugin-types.adoc[Different plugin types] -- xref:how-to-guides/plugin-development/non-upgradeable-plugin/index.adoc[Non-upgradeable plugin] -- xref:how-to-guides/plugin-development/upgradeable-plugin/index.adoc[Upgradeable plugin] -- xref:how-to-guides/plugin-development/governance-plugins/index.adoc[Governance plugin] - -IMPORTANT: This plugin template uses version TODO:GIORGI `1.4.0-alpha.5` of the Aragon OSx protocol. This version is still in development and is not audited yet. diff --git a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/meta-tx-plugins.adoc b/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/meta-tx-plugins.adoc deleted file mode 100644 index 3327bfe56..000000000 --- a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/meta-tx-plugins.adoc +++ /dev/null @@ -1,44 +0,0 @@ -= Meta Transactions - -## Support for Meta Transactions - -Our plugins are compatible with the link:https://eips.ethereum.org/EIPS/eip-2771[ERC-2771 (Meta Transaction)] standard, which allows users to send gasless transactions, also known as meta transactions. -This is possible because we use `_msgSender` and `_msgData` context from OpenZeppelin's `Context` and `ContextUpgradeable` in our `Plugin`, `PluginCloneable`, and `PluginUUPSUpgradeable` classes. - -To support meta transactions, your implementation contract must inherit and override the `Context` implementation with the `_msgSender` and `_msgData` functions provided in OpenGSN's `BaseRelayRecipient`, and use the DAO's trusted forwarder. - -Below we show for the example of the `TokenVoting` plugin how you can make an existing plugin contract meta-transaction compatible. - -```solidity -import {ContextUpgradeable} from '@openzeppelin/contracts-upgradeable/utils/ContextUpgradeable.sol'; -import {BaseRelayRecipient} from '@opengsn/contracts/src/BaseRelayRecipient.sol'; - -contract MyPlugin is PluginUUPSUpgradeable, BaseRelayRecipient { - function initialize(IDAO _dao) external initializer { - __PluginUUPSUpgradeable_init(_dao); - _setTrustedForwarder(dao.getTrustedForwarder()); - } - - // ... the implementation - - function _msgSender() - internal - view - virtual - override(ContextUpgradeable, BaseRelayRecipient) - returns (address) - { - return BaseRelayRecipient._msgSender(); - } - - function _msgData() - internal - view - virtual - override(ContextUpgradeable, BaseRelayRecipient) - returns (bytes calldata) - { - return BaseRelayRecipient._msgData(); - } -} -``` diff --git a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/non-upgradeable-plugin/implementation.adoc b/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/non-upgradeable-plugin/implementation.adoc deleted file mode 100644 index 431dfca1a..000000000 --- a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/non-upgradeable-plugin/implementation.adoc +++ /dev/null @@ -1,89 +0,0 @@ -= Plugin Implementation Contract - -== How to Build a Non-Upgradeable Plugin - -Once we've initialized our plugin (take a look at our guide on xref:how-to-guides/plugin-development/non-upgradeable-plugin/initialization.adoc[how to initialize Non-Upgradeable Plugins here]), -we can start using the Non-Upgradeable Base Template to perform actions on the DAO. - -### 1. Set the Permission Identifier - -Firstly, we want to define a xref:how-it-works/core/permissions/index.adoc#permission-identifiers[permission identifier] `bytes32` constant at the top -of the contract and establish a `keccak256` hash of the permission name we want to choose. -In this example, we're calling it the `ADMIN_EXECUTE_PERMISSION`. - -```solidity -contract SimpleAdmin is PluginCloneable { - /// @notice The ID of the permission required to call the `execute` function. - bytes32 public constant ADMIN_EXECUTE_PERMISSION_ID = keccak256('ADMIN_EXECUTE_PERMISSION'); - - address public admin; - - /// @notice Initializes the contract. - /// @param _dao The associated DAO. - /// @param _admin The address of the admin. - function initialize(IDAO _dao, address _admin) external initializer { - __PluginCloneable_init(_dao); - admin = _admin; - } - - /// @notice Executes actions in the associated DAO. - function execute(IDAO.Action[] calldata _actions) external auth(ADMIN_EXECUTE_PERMISSION_ID) { - revert('Not implemented.'); - } -} -``` - -NOTE: -You are free to choose the permission name however you like. For example, you could also have used `keccak256('SIMPLE_ADMIN_PLUGIN:PERMISSION_1')`. -However, it is important that the permission names are descriptive and cannot be confused with each other. - -Setting this permission is key because it ensures only signers who have been granted that permission are able to execute functions. - -### 2. Add the logic implementation - -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 link:https://github.com/aragon/osx-commons/blob/develop/contracts/src/plugin/PluginCloneable.sol[`PluginCloneable` base contract], -we can now use its features, i.e., the link:https://github.com/aragon/osx-commons/blob/1cf46ff15dbda8481f9ee37558e7ea8b257d51f2/contracts/src/permission/auth/DaoAuthorizable.sol#L30-L35[auth modifier] -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 link:https://github.com/aragon/osx-commons/blob/1cf46ff15dbda8481f9ee37558e7ea8b257d51f2/contracts/src/permission/auth/DaoAuthorizable.sol#L24-L28[dao() getter function from the base contract], -which returns the associated DAO for that plugin. - -```solidity -contract SimpleAdmin is PluginCloneable { - /// @notice The ID of the permission required to call the `execute` function. - bytes32 public constant ADMIN_EXECUTE_PERMISSION_ID = keccak256('ADMIN_EXECUTE_PERMISSION'); - - address public admin; - - /// @notice Initializes the contract. - /// @param _dao The associated DAO. - /// @param _admin The address of the admin. - function initialize(IDAO _dao, address _admin) external initializer { - __PluginCloneable_init(_dao); - admin = _admin; - } - - /// @notice Executes actions in the associated DAO. - /// @param _actions The actions to be executed by the DAO. - function execute(IDAO.Action[] calldata _actions) external auth(ADMIN_EXECUTE_PERMISSION_ID) { - dao().execute({callId: 0x0, actions: _actions, allowFailureMap: 0}); - } -} -``` - -NOTE: In this example, we are building a governance plugin. To increase its capabilities and provide some standardization into the protocol, we recommend completing the governance plugin by -xref:how-to-guides/plugin-development/governance-plugins/index.adoc[implementing the `IProposal` and `IMembership` interfaces]. -Optionally, you can also allow certain actions to fail by using xref:how-it-works/core/dao/actions.adoc#allowing-for-failure[the failure map feature of the DAO executor]. - -For now, we used default values for the `callId` and `allowFailureMap` parameters required by the DAO's `execute` function. -With this, the plugin implementation could be used and deployed already. Feel free to add any additional logic to -your plugin's capabilities here. - -### 3. Plugin done, Setup contract next! - -Now that we have the logic for the plugin implemented, we'll need to define how this plugin should be installed/uninstalled from a DAO. -In the next step, we'll write the `PluginSetup` contract - the one containing the installation, uninstallation, and -upgrading instructions for the plugin. diff --git a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/non-upgradeable-plugin/index.adoc b/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/non-upgradeable-plugin/index.adoc deleted file mode 100644 index 3b54ae013..000000000 --- a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/non-upgradeable-plugin/index.adoc +++ /dev/null @@ -1,22 +0,0 @@ -= Non-Upgradeable Plugins - -== Get Started with Non-Upgradeable Plugins - -A Non-Upgradeable Plugin is a Plugin built on smart contracts that cannot be upgraded. This may or may not be what you want. - -Some observations: - -- Non-Upgradeable contracts are simpler to create, deploy, and manage. -- Instantiation is done via the `new` keyword or deployed via the link:https://eips.ethereum.org/EIPS/eip-1167[minimal proxy pattern (ERC-1167)]. -- The storage is contained within each version. So if your plugin is dependent on state information from previous versions, -you won't have access to it directly in upcoming versions, since every version is a blank new state. If this is a requirement -for your project, we recommend you deploy an xref:how-to-guides/plugin-development/upgradeable-plugin/index.adoc[Upgradeable Plugin]. - -Before moving on with the Guide, make sure you've read our documentation on xref:how-to-guides/plugin-development/plugin-types.adoc[Choosing the Best Type for Your Plugin] to make sure you're selecting the right type of contract for your Plugin. - -Up next, check out our guides on: - -1. xref:how-to-guides/plugin-development/non-upgradeable-plugin/initialization.adoc[How to initialize Non-Upgradeable Plugins] -2. xref:how-to-guides/plugin-development/non-upgradeable-plugin/implementation.adoc[How to build the implementation of a Non-Upgradeable Plugin] -3. xref:how-to-guides/plugin-development/non-upgradeable-plugin/setup.adoc[How to build and deploy a Plugin Setup contract for a Non-Upgradeable Plugin] -4. xref:how-to-guides/plugin-development/publication/index.adoc[How to publish my plugin into the Aragon OSx protocol] diff --git a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/non-upgradeable-plugin/initialization.adoc b/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/non-upgradeable-plugin/initialization.adoc deleted file mode 100644 index 6ca96646d..000000000 --- a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/non-upgradeable-plugin/initialization.adoc +++ /dev/null @@ -1,88 +0,0 @@ -= Initialization - -== How to Initialize Non-Upgradeable Plugins - -Every plugin should receive and store the address of the DAO it is associated with upon initialization. This is how the plugin will be able to interact with the DAO that has installed it. - -In addition, your plugin implementation might want to introduce other storage variables that should be initialized immediately after the contract was created. -For example, in the `SimpleAdmin` plugin example (which sets one address as the full admin of the DAO), we'd want to store the `admin` -address. - -```solidity -contract SimpleAdmin is Plugin { - address public admin; -} -``` - -The way we set up the plugin's `initialize()` function depends on the plugin type selected. To review plugin types in depth, check out -our xref:how-to-guides/plugin-development/plugin-types.adoc[guide here]. - -Additionally, the way we deploy our contracts is directly correlated with how they're initialized. For Non-Upgradeable Plugins, -there's two ways in which we can deploy our plugin: - -- Deployment via Solidity's `new` keyword, OR -- Deployment via the Minimal Proxy Pattern - -### Option A: Deployment via Solidity's `new` Keyword - -To instantiate the contract via Solidity's `new` keyword, you should inherit from the `Plugin` Base Template Aragon created. -You can find it link:https://github.com/aragon/osx-commons/blob/develop/contracts/src/plugin/Plugin.sol[here]. - -In this case, the compiler will force you to write a `constructor` function calling the `Plugin` parent `constructor` and -provide it with a contract of type `IDAO`. Inside the constructor, you might want to initialize the storage variables that you have -added yourself, such as the `admin` address in the example below. - -```solidity -// SPDX-License-Identifier: AGPL-3.0-or-later -pragma solidity 0.8.21; - -import {Plugin, IDAO} from '@aragon/osx/core/plugin/Plugin.sol'; - -contract SimpleAdmin is Plugin { - address public immutable admin; - - /// @notice Initializes the contract. - /// @param _dao The associated DAO. - /// @param _admin The address of the admin. - constructor(IDAO _dao, address _admin) Plugin(_dao) { - admin = _admin; - } -} -``` - -NOTE: The `admin` variable is set as `immutable` so that it can never be changed. Immutable variables can only be initialized in -the constructor. - -This type of constructor implementation stores the `IDAO _dao` reference in the right place. If your plugin is deployed often, w -hich we could expect, we can link:https://blog.openzeppelin.com/workshop-recap-cheap-contract-deployment-through-clones/[save significant amounts of gas by deployment through using the minimal proxy pattern]. - -### Option B: Deployment via the Minimal Proxy Pattern - -To deploy our plugin via the link:https://eips.ethereum.org/EIPS/eip-1167(minimal clones pattern (ERC-1167)), you inherit from the `PluginCloneable` contract introducing the same features as `Plugin`. -The only difference is that you now have to remember to write an `initialize` function. - -```solidity -// SPDX-License-Identifier: AGPL-3.0-or-later -pragma solidity 0.8.21; - -import {PluginCloneable, IDAO} from '@aragon/osx/core/plugin/PluginCloneable.sol'; - -contract SimpleAdmin is PluginCloneable { - address public admin; - - /// @notice Initializes the contract. - /// @param _dao The associated DAO. - /// @param _admin The address of the admin. - function initialize(IDAO _dao, address _admin) external initializer { - __PluginCloneable_init(_dao); - admin = _admin; - } -} -``` - -We must protect it from being called multiple times by using link:https://docs.openzeppelin.com/contracts/4.x/api/proxy#Initializable[OpenZeppelin's `initializer` modifier made available through `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/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/non-upgradeable-plugin/setup.adoc b/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/non-upgradeable-plugin/setup.adoc deleted file mode 100644 index d79a06bd5..000000000 --- a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/non-upgradeable-plugin/setup.adoc +++ /dev/null @@ -1,337 +0,0 @@ -= Plugin Setup Contract - -== What is the 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. - -### 1. Finish the Plugin contract - -Before building your Plugin Setup contract, make sure you have the logic for your plugin implemented. In this case, we're building a simple admin plugin which grants one address permission to execute actions on behalf of the DAO. - -```solidity -contract SimpleAdmin is PluginCloneable { - /// @notice The ID of the permission required to call the `execute` function. - bytes32 public constant ADMIN_EXECUTE_PERMISSION_ID = keccak256('ADMIN_EXECUTE_PERMISSION'); - - address public admin; - - /// @notice Initializes the contract. - /// @param _dao The associated DAO. - /// @param _admin The address of the admin. - function initialize(IDAO _dao, address _admin) external initializer { - __PluginCloneable_init(_dao); - admin = _admin; - } - - /// @notice Executes actions in the associated DAO. - /// @param _actions The actions to be executed by the DAO. - function execute(IDAO.Action[] calldata _actions) external auth(ADMIN_EXECUTE_PERMISSION_ID) { - dao().execute({_callId: 0x0, _actions: _actions, _allowFailureMap: 0}); - } -} -``` - -### 2. How to initialize the Plugin Setup contract - -Each `PluginSetup` contract is deployed only once and we will publish a separate `PluginSetup` instance for each version. Accordingly, we instantiate the `implementation` contract via Solidity's `new` keyword as deployment with the minimal proxy pattern would be more expensive in this case. - -```solidity -// SPDX-License-Identifier: AGPL-3.0-or-later -pragma solidity 0.8.21; - -import {PluginSetup, IPluginSetup} from '@aragon/osx/framework/plugin/setup/PluginSetup.sol'; -import {SimpleAdmin} from './SimpleAdmin.sol'; - -contract SimpleAdminSetup is PluginSetup { - /// @notice The address of `SimpleAdmin` plugin contract to be cloned. - address private immutable simpleAdminImplementation; - - /// @notice The constructor setting the `SimpleAdmin` implementation contract to clone from. - constructor() { - simpleAdminImplementation = address(new SimpleAdmin()); - } - - /// @inheritdoc IPluginSetup - function implementation() external view returns (address) { - return simpleAdminImplementation; - } -} -``` - -### 3. Build the Skeleton - -In order for the Plugin to be easily installed into the DAO, we need to define the permissions the plugin will need. - -We will create a `prepareInstallation()` function, as well as a `prepareUninstallation()` function. These are the functions the `PluginSetupProcessor.sol` (the contract in charge of installing plugins into the DAO) will use to prepare the installation/uninstallation of the plugin into the DAO. - -For example, a skeleton for our `SimpleAdminSetup` contract inheriting from `PluginSetup` looks as follows: - -```solidity -import {PermissionLib} from '@aragon/osx/core/permission/PermissionLib.sol'; - -contract SimpleAdminSetup is PluginSetup { - /// @notice The address of `SimpleAdmin` plugin logic contract to be cloned. - address private immutable simpleAdminImplementation; - - /// @notice The constructor setting the `SimpleAdmin` implementation contract to clone from. - constructor() { - simpleAdminImplementation = address(new SimpleAdmin()); - } - - /// @inheritdoc IPluginSetup - function prepareInstallation( - address _dao, - bytes calldata _data - ) external returns (address plugin, PreparedSetupData memory preparedSetupData) { - revert('Not implemented yet.'); - } - - /// @inheritdoc IPluginSetup - function prepareUninstallation( - address _dao, - SetupPayload calldata _payload - ) external view returns (PermissionLib.MultiTargetPermission[] memory permissions) { - revert('Not implemented yet.'); - } - - /// @inheritdoc IPluginSetup - function implementation() external view returns (address) { - return simpleAdminImplementation; - } -} -``` - -As you can see, we have a constructor storing the implementation contract instantiated via the `new` method in the private immutable variable `implementation` to save gas and a `implementation` function to retrieve it. - -Next, we will add the implementation for the `prepareInstallation` and `prepareUninstallation` functions. - -### 4. Implementing the `prepareInstallation()` function - -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. - -```solidity -import {Clones} from '@openzeppelin/contracts/proxy/Clones.sol'; - -contract SimpleAdminSetup is PluginSetup { - using Clones for address; - - /// @notice Thrown if the admin address is zero. - /// @param admin The admin address. - error AdminAddressInvalid(address admin); - - // ... -} -``` - -Then, we will use link:https://docs.openzeppelin.com/contracts/4.x/api/proxy#Clones[OpenZeppelin's `Clones` library] to clone our Plugin contract and initialize it with the `admin` address. The first line, `using Clones for address;`, allows us to call OpenZeppelin `Clones` library to clone contracts deployed at an address. - -The second line introduces a custom error being thrown if the admin address specified is the zero address. - -```solidity -function prepareInstallation( - address _dao, - bytes calldata _data -) external returns (address plugin, PreparedSetupData memory preparedSetupData) { - // Decode `_data` to extract the params needed for cloning and initializing the `Admin` plugin. - address admin = abi.decode(_data, (address)); - - if (admin == address(0)) { - revert AdminAddressInvalid({admin: admin}); - } - - // Clone plugin contract. - plugin = implementation.clone(); - - // Initialize cloned plugin contract. - SimpleAdmin(plugin).initialize(IDAO(_dao), admin); - - // Prepare permissions - PermissionLib.MultiTargetPermission[] - memory permissions = new PermissionLib.MultiTargetPermission[](2); - - // Grant the `ADMIN_EXECUTE_PERMISSION` of the plugin to the admin. - permissions[0] = PermissionLib.MultiTargetPermission({ - operation: PermissionLib.Operation.Grant, - where: plugin, - who: admin, - condition: PermissionLib.NO_CONDITION, - permissionId: SimpleAdmin(plugin).ADMIN_EXECUTE_PERMISSION_ID() - }); - - // Grant the `EXECUTE_PERMISSION` on the DAO to the plugin. - permissions[1] = PermissionLib.MultiTargetPermission({ - operation: PermissionLib.Operation.Grant, - where: _dao, - who: plugin, - condition: PermissionLib.NO_CONDITION, - permissionId: DAO(payable(_dao)).EXECUTE_PERMISSION_ID() - }); - - preparedSetupData.permissions = permissions; -} -``` - -Finally, we construct and return an array with the permissions that we need for our plugin to work properly. - -- First, we request granting the `ADMIN_EXECUTE_PERMISSION_ID` to the `admin` address received. This is what gives the address access to use `plugin`'s functionality - in this case, call on the plugin's `execute` function so it can execute actions on behalf of the DAO. -- Second, we request that our newly deployed plugin can use the `EXECUTE_PERMISSION_ID` permission on the `_dao`. We don't add conditions to the permissions in this case, so we use the `NO_CONDITION` constant provided by `PermissionLib`. - -### 5. Implementing the `prepareUninstallation()` function - -For the uninstallation, we have to make sure to revoke the two permissions that have been granted during the installation process. -First, we revoke the `ADMIN_EXECUTE_PERMISSION_ID` from the `admin` address that we have stored in the implementation contract. -Second, we revoke the `EXECUTE_PERMISSION_ID` from the `plugin` address that we obtain from the `_payload` calldata. - -```solidity -function prepareUninstallation( - address _dao, - SetupPayload calldata _payload -) external view returns (PermissionLib.MultiTargetPermission[] memory permissions) { - // Collect addresses - address plugin = _payload.plugin; - address admin = SimpleAdmin(plugin).admin(); - - // Prepare permissions - permissions = new PermissionLib.MultiTargetPermission[](2); - - permissions[0] = PermissionLib.MultiTargetPermission({ - operation: PermissionLib.Operation.Revoke, - where: plugin, - who: admin, - condition: PermissionLib.NO_CONDITION, - permissionId: SimpleAdmin(plugin).ADMIN_EXECUTE_PERMISSION_ID() - }); - - permissions[1] = PermissionLib.MultiTargetPermission({ - operation: PermissionLib.Operation.Revoke, - where: _dao, - who: plugin, - condition: PermissionLib.NO_CONDITION, - permissionId: DAO(payable(_dao)).EXECUTE_PERMISSION_ID() - }); -} -``` - -#### 6. Putting Everything Together - -Now, it's time to wrap up everything together. You should have a contract that looks like this: - -```solidity -// SPDX-License-Identifier: AGPL-3.0-or-later -pragma solidity 0.8.21; - -import {Clones} from '@openzeppelin/contracts/proxy/Clones.sol'; - -import {PermissionLib} from '@aragon/osx/core/permission/PermissionLib.sol'; -import {PluginSetup, IPluginSetup} from '@aragon/osx/framework/plugin/setup/PluginSetup.sol'; -import {SimpleAdmin} from './SimpleAdmin.sol'; - -contract SimpleAdminSetup is PluginSetup { - using Clones for address; - - /// @notice The address of `SimpleAdmin` plugin logic contract to be cloned. - address private immutable simpleAdminImplementation; - - /// @notice Thrown if the admin address is zero. - /// @param admin The admin address. - error AdminAddressInvalid(address admin); - - /// @notice The constructor setting the `Admin` implementation contract to clone from. - constructor() { - simpleAdminImplementation = address(new SimpleAdmin()); - } - - /// @inheritdoc IPluginSetup - function prepareInstallation( - address _dao, - bytes calldata _data - ) external returns (address plugin, PreparedSetupData memory preparedSetupData) { - // Decode `_data` to extract the params needed for cloning and initializing the `Admin` plugin. - address admin = abi.decode(_data, (address)); - - if (admin == address(0)) { - revert AdminAddressInvalid({admin: admin}); - } - - // Clone plugin contract. - plugin = implementation.clone(); - - // Initialize cloned plugin contract. - SimpleAdmin(plugin).initialize(IDAO(_dao), admin); - - // Prepare permissions - PermissionLib.MultiTargetPermission[] - memory permissions = new PermissionLib.MultiTargetPermission[](2); - - // Grant the `ADMIN_EXECUTE_PERMISSION` of the plugin to the admin. - permissions[0] = PermissionLib.MultiTargetPermission({ - operation: PermissionLib.Operation.Grant, - where: plugin, - who: admin, - condition: PermissionLib.NO_CONDITION, - permissionId: SimpleAdmin(plugin).ADMIN_EXECUTE_PERMISSION_ID() - }); - - // Grant the `EXECUTE_PERMISSION` on the DAO to the plugin. - permissions[1] = PermissionLib.MultiTargetPermission({ - operation: PermissionLib.Operation.Grant, - where: _dao, - who: plugin, - condition: PermissionLib.NO_CONDITION, - permissionId: DAO(payable(_dao)).EXECUTE_PERMISSION_ID() - }); - - preparedSetupData.permissions = permissions; - } - - /// @inheritdoc IPluginSetup - function prepareUninstallation( - address _dao, - SetupPayload calldata _payload - ) external view returns (PermissionLib.MultiTargetPermission[] memory permissions) { - // Collect addresses - address plugin = _payload.plugin; - address admin = SimpleAdmin(plugin).admin(); - - // Prepare permissions - permissions = new PermissionLib.MultiTargetPermission[](2); - - permissions[0] = PermissionLib.MultiTargetPermission({ - operation: PermissionLib.Operation.Revoke, - where: plugin, - who: admin, - condition: PermissionLib.NO_CONDITION, - permissionId: SimpleAdmin(plugin).ADMIN_EXECUTE_PERMISSION_ID() - }); - - permissions[1] = PermissionLib.MultiTargetPermission({ - operation: PermissionLib.Operation.Revoke, - where: _dao, - who: plugin, - condition: PermissionLib.NO_CONDITION, - permissionId: DAO(payable(_dao)).EXECUTE_PERMISSION_ID() - }); - } - - /// @inheritdoc IPluginSetup - function implementation() external view returns (address) { - return simpleAdminImplementation; - } -} -``` - -Once done, our plugin is ready to be published on the Aragon plugin registry. With the address of the `SimpleAdminSetup` contract, we are ready for creating our `PluginRepo`, the plugin's repository where all plugin versions will live. -Check out our how to guides on xref:how-to-guides/plugin-development/publication/index.adoc[publishing your plugin here]. - -### In the future: Subsequent Builds - -For subsequent builds or releases of your plugin, you'll simply write a new implementation and associated Plugin Setup contract providing a new `prepareInstallation` and `prepareUninstallation` function. - -If a DAO wants to install the new build or release, it must uninstall its current plugin and freshly install the new plugin version, which can happen in the same action array in a governance proposal. However, the plugin storage and event history will be lost since this is a non-upgradeable plugin. If you want to prevent the latter, you can learn xref:how-to-guides/plugin-development/non-upgradeable-plugin/index.adoc[how to write an upgradeable plugin here]. diff --git a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/plugin-types.adoc b/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/plugin-types.adoc deleted file mode 100644 index 514d2209b..000000000 --- a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/plugin-types.adoc +++ /dev/null @@ -1,65 +0,0 @@ -= Choosing the Plugin Type - -== How to Choose the Base Contract for Your Plugin - -Although it is not mandatory to choose one of our interfaces as the base contracts for your plugins, we do offer some options for you to inherit from and speed up development. - -The needs of your plugin determine the type of plugin you may want to choose. This is based on: - -- the need for a plugin's upgradeability -- whether you need it deployed by a specific deployment method -- whether you need it to be compatible with meta transactions - -In this regard, we provide 3 options for base contracts you can choose from: - -- `Plugin` for instantiation via `new` -- `PluginClones` for link:https://eips.ethereum.org/EIPS/eip-1167[minimal proxy pattern (ERC-1167)] deployment. -- `PluginUUPSUpgradeable` for link:https://eips.ethereum.org/EIPS/eip-1822[UUPS pattern (ERC-1822)] deployment. - -Let's take a look at what this means for you. - -### Upgradeability & Deployment - -Upgradeability and the deployment method of a plugin contract go hand in hand. The motivation behind upgrading smart contracts is nicely summarized by OpenZeppelin: - -> Smart contracts in Ethereum are immutable by default. Once you create them there is no way to alter them, effectively acting as an unbreakable contract among participants. -> -> However, for some scenarios, it is desirable to be able to modify them [...] -> -> - to fix a bug [...], -> - to add additional features, or simply to -> - change the rules enforced by it. -> -> Here’s what you’d need to do to fix a bug in a contract you cannot upgrade: -> -> 1. Deploy a new version of the contract -> 2. Manually migrate all state from the old one contract to the new one (which can be very expensive in terms of gas fees!) -> 3. Update all contracts that interacted with the old contract to use the address of the new one -> 4. Reach out to all your users and convince them to start using the new deployment (and handle both contracts being used simultaneously, as users are slow to migrate). - -For more, link:https://docs.openzeppelin.com/learn/upgrading-smart-contracts#whats-in-an-upgrade[See OpenZeppelin's Guide]. - -Some key things to keep in mind: - -- With upgradeable smart contracts, you can modify their code while keep using or even extending the storage (see the guide link:https://docs.openzeppelin.com/upgrades-plugins/1.x/writing-upgradeable[Writing Upgradeable Contracts] by OpenZeppelin). -- To enable upgradeable smart contracts (as well as cheap contract clones), the proxy pattern is used. -- Depending on your upgradeability requirements and the deployment method you choose, you can also greatly reduce the gas costs to distribute your plugin. -However, the upgradeability and deployment method can introduce caveats -during xref:how-it-works/framework/plugin-management/plugin-setup/index.adoc[the plugin setup] especially when updating from an older version to a new one. - -We recommend to use link:https://eips.ethereum.org/EIPS/eip-1167[minimal proxies (ERC-1167)] for non-upgradeable and link:https://eips.ethereum.org/EIPS/eip-1822(UUPS proxies (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: - -- `Plugin` for instantiation via `new` -- `PluginClones` for link:https://eips.ethereum.org/EIPS/eip-1167[minimal proxy pattern (ERC-1167)] deployment. -- `PluginUUPSUpgradeable` for link:https://eips.ethereum.org/EIPS/eip-1822[UUPS pattern (ERC-1822)] deployment. - -#### Caveats of Non-upgradeable Plugins - -Aragon plugins using the non-upgradeable smart contracts bases (`Plugin`, `PluginCloneable`) can be cheap to deploy (i.e., using clones) but **cannot be updated**. - -Updating, in distinction from upgrading, will call Aragon OSx' internal process for switching from an older plugin version to a newer one. - -CAUTION: To switch from an older version of a non-upgradeable contract to a newer one, the underlying contract has to be replaced. -In consequence, the state of the older version is not available in the new version anymore, unless it is migrated or has been made -publicly accessible in the old version through getter functions. diff --git a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/publication/index.adoc b/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/publication/index.adoc deleted file mode 100644 index 9e86956de..000000000 --- a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/publication/index.adoc +++ /dev/null @@ -1,31 +0,0 @@ -= Publication of your Plugin into Aragon OSx - -## How to publish a plugin into Aragon's plugin registry - -Once you've deployed your Plugin Setup contract, you will be able to publish your plugin into Aragon's plugin registry so any -Aragon DAO can install it. - -### 1. Make sure your plugin is deployed in the right network - -Make sure your Plugin Setup contract is deployed in your network of choice (you can find all of the networks we support link:https://github.com/aragon/osx-commons/tree/develop/configs/src/deployments/json[here]). -You will need the address of your Plugin Setup contract to be able to publish the plugin into the protocol. - -### 2. Publishing your plugin - -Every plugin in Aragon can have future versions, so when publishing a plugin to the Aragon protocol, we're really creating a link:https://github.com/aragon/osx/blob/develop/packages/contracts/src/framework/plugin/repo/PluginRepo.sol[PluginRepo] instance for each plugin, -which will contain all of the plugin's versions. - -To publish a plugin, we will use Aragon's `PluginRepoFactory` contract - in charge of creating `PluginRepo` instances containing your plugin's versions. -To do this, we will call its `createPluginRepoWithFirstVersion` function, which will link:https://github.com/aragon/core/blob/develop/packages/contracts/src/framework/plugin/repo/PluginRepoFactory.sol#L48[create the first version of a plugin] -and add that new `PluginRepo` address into the `PluginRepoRegistry` containing all available plugins within the protocol. - -You can find all of the addresses of `PluginRepoFactory` contracts by network link:https://github.com/aragon/osx-commons/tree/develop/configs/src/deployments/json[here]. - -To create more versions of your plugin in the future, you'll call on the link:https://github.com/aragon/osx/blob/develop/packages/contracts/src/framework/plugin/repo/PluginRepo.sol#L128[createVersion function] -from the `PluginRepo` instance of your plugin. When you publish your plugin, you'll be able to find the address of your plugin's `PluginRepo` instance within the transaction data. - -### 3. Publishing subsequent builds - -When publishing subsequent builds, you want to use the `createVersion` function in the `PluginRepo` contract (link:https://github.com/aragon/osx/blob/develop/packages/contracts/src/framework/plugin/repo/PluginRepo.sol#L132[check out the function's source code here]). - -To deploy your plugin, follow the steps in the link:https://github.com/aragon/osx-plugin-template-hardhat/blob/main/README.md#deployment[osx-plugin-template-hardhat README.md]. diff --git a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/publication/metadata.adoc b/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/publication/metadata.adoc deleted file mode 100644 index 250c0b5cd..000000000 --- a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/publication/metadata.adoc +++ /dev/null @@ -1,154 +0,0 @@ -= Plugin Metadata - -== Plugin Metadata Specification - -The plugin metadata is necessary to allow the App frontend to interact with any plugins: - -- Now: generic setup (installation, update, uninstallation) - - Allows the frontend to render the necessary fields for the input being required to setup the plugin (e.g., the list of initial members of the Multisig plugin) -- Future: render a UI in a generic way (buttons, text fields, flows) within the specs of the Open Design System (ODS) (e.g. manage the list of Multisig members or the approval settings) - -Currently, two kinds of metadata exist: - -1. Release metadata -2. Build metadata - -### Release Metadata - -The release metadata is a `.json` file stored on IPFS with its IPFS CID published for each release in the [PluginRepo](../../../01-how-it-works/02-framework/02-plugin-management/01-plugin-repo/index.md) (see also the section about [versioning](../07-publication/01-versioning.md#)). - -The intention is to provide an appealing overview of each releases functionality. -It can be updated with each call to [`createVersion()`](../../../03-reference-guide/framework/plugin/repo/IPluginRepo.md#external-function-createversion) in `IPluginRepo` by the repo maintainer. -It can be replaced at any time with [`updateReleaseMetadata()`](../../../03-reference-guide/framework/plugin/repo/IPluginRepo.md#external-function-updatereleasemetadata) in `IPluginRepo` by the repo maintainer. - -The `release-metadata.json` file consists of the following entries: - -|=== -|Key |Type |Description - -| name -| `string` -| Name of the plugin (e.g. `"Multisig"`) - -| description -| `string` -| Description of the plugin release and its functionality. - -| images -| UNSPECIFIED -| Optional. Contains a series of images advertising the plugins functionality.. - -|=== - - -#### Example - -```json -{ - "name": "Multisig", - "description": "", - "images": {} -} -``` - -### Build Metadata - -The build metadata is a `.json` file stored on IPFS with its IPFS CID published for each build **only once** -in the xref:how-it-works/framework/plugin-management/plugin-repo/index.adoc[PluginRepo] (see also the section about xref:how-to-guides/plugin-development/publication/versioning.adoc[versioning]). - -The intention is to inform about the changes that were introduced in this build compared to the previous one and give instructions to the App frontend and other users on how to interact with the plugin setup and implementation contract. -It can be published **only once** with the call to TODO:GIORGI [`createVersion()`](../../../03-reference-guide/framework/plugin/repo/IPluginRepo.md#external-function-createversion) in `IPluginRepo` by the repo maintainer. - -|=== -|Key |Type |Description - -| ui -| UNSPECIFIED -| A special formatted object containing instructions for the App frontend on how to render the plugin's UI. - -| change -| `string` -| Description of the code and UI changes compared to the previous build of the same release. - -| pluginSetup -| `object` -| Optional. Contains a series of images advertising the plugins functionality. - -|=== - -Each build metadata contains the following fields: - -- one `"prepareInstallation"` object -- one `"prepareUninstallation"` object -- 0 to N `"prepareUpdate"` objects enumerated from 1 to N+1 - -Each `"prepare..."` object contains: - -|=== -|Key |Type |Description - -| description -| `string` -| The description of what this particular setup step is doing and what it requires the input for. - -| inputs -| `object[]` -| A description of the inputs required for this setup step following the link:https://docs.ethers.org/v5/api/utils/abi/formats/#abi-formats--solidity[Solidity JSON ABI] format enriched with an additional `"description"` field for each element. - -|=== - - - -By following the Solidity JSON ABI format for the inputs, we followed an established standard, have support for complex types (tuples, arrays, nested versions of the prior) and allow for future extensibility (such as the human readable description texts that we have added). - -#### Example - -```json -{ - "ui": {}, - "change": "- The ability to create a proposal now depends on the membership status of the current instead of the snapshot block.\n- Added a check ensuring that the initial member list cannot overflow.", - "pluginSetup": { - "prepareInstallation": { - "description": "The information required for the installation.", - "inputs": [ - { - "internalType": "address[]", - "name": "members", - "type": "address[]", - "description": "The addresses of the initial members to be added." - }, - { - "components": [ - { - "internalType": "bool", - "name": "onlyListed", - "type": "bool", - "description": "Whether only listed addresses can create a proposal or not." - }, - { - "internalType": "uint16", - "name": "minApprovals", - "type": "uint16", - "description": "The minimal number of approvals required for a proposal to pass." - } - ], - "internalType": "struct Multisig.MultisigSettings", - "name": "multisigSettings", - "type": "tuple", - "description": "The initial multisig settings." - } - ], - "prepareUpdate": { - "1": { - "description": "No input is required for the update.", - "inputs": [] - } - }, - "prepareUninstallation": { - "description": "No input is required for the uninstallation.", - "inputs": [] - } - } - } -} -``` diff --git a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/publication/versioning.adoc b/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/publication/versioning.adoc deleted file mode 100644 index f5722acda..000000000 --- a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/publication/versioning.adoc +++ /dev/null @@ -1,52 +0,0 @@ -= New Plugin Version - -== How to add a new version of your plugin - -The Aragon OSx protocol has an on-chain versioning system built-in, which distinguishes between releases and builds. - -- **Releases** contain breaking changes, which are incompatible with preexisting installations. Updates to a different release are -not possible. Instead, you must install the new plugin release and uninstall the old one. -- **Builds** are minor/patch versions within a release, and they are meant for compatible upgrades only -(adding a feature or fixing a bug without changing anything else). - -Builds are particularly important for `UUPSUpgradeable` plugins, whereas a non-upgradeable plugin will work off of only releases. - -Given a version tag `RELEASE.BUILD`, we can infer that: - -TODO:GIORGI nested list fix. - -1. We are doing a `RELEASE` version when we apply breaking changes affecting the interaction with other contracts on the blockchain to: - - - The `Plugin` implementation contract such as the - - change or removal of storage variables - - removal of external functions - - change of external function headers - -2. We are doing a `BUILD` version when we apply backward compatible changes not affecting the interaction with other contracts on the blockchain to: - - - The `Plugin` implementation contract such as the - - addition of - - storage variables - - external functions - - - change of - - external function bodies - - - addition, change, or removal of - - internal functions - - constants - - immutables - - events - - errors - - - The `PluginSetup` contract such as - - addition, change, or removal of - - input parameters - - helper contracts - - requested permissions - - - The release and build `metadata` URIs such as the - - change of - - the plugin setup ABI - - the plugin UI components - - the plugin description diff --git a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/upgradeable-plugin/implementation.adoc b/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/upgradeable-plugin/implementation.adoc deleted file mode 100644 index 8a91c82a7..000000000 --- a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/upgradeable-plugin/implementation.adoc +++ /dev/null @@ -1,42 +0,0 @@ -= Plugin Implementation Contract - -== How to build an Upgradeable Plugin implementation contract - -In this guide, we'll build a `SimpleStorage` Upgradeable plugin which all it does is storing a number. - -The Plugin contract is the one containing all the logic we'd like to implement on the DAO. - -### 1. Set up the initialize function - -Make sure you have the initializer of your plugin well set up. Please review xref:how-to-guides/plugin-development/upgradeable-plugin/initialization.adoc[our guide on how to do that here] if you haven't already. - -Once you this is done, let's dive into several implementations and builds, as can be expected for Upgradeable plugins. - -### 2. Adding your plugin implementation logic - -In our first build, we want to add an authorized `storeNumber` function to the contract - allowing a caller holding the `STORE_PERMISSION_ID` permission to change the stored value similar to what we did for xref:how-to-guides/plugin-development/non-upgradeable-plugin/implementation.adoc[the non-upgradeable `SimpleAdmin` Plugin]. - -```solidity -import {PluginUUPSUpgradeable, IDAO} '@aragon/osx/core/plugin/PluginUUPSUpgradeable.sol'; - -/// @title SimpleStorage build 1 -contract SimpleStorageBuild1 is PluginUUPSUpgradeable { - bytes32 public constant STORE_PERMISSION_ID = keccak256('STORE_PERMISSION'); - - uint256 public number; // added in build 1 - - /// @notice Initializes the plugin when build 1 is installed. - function initializeBuild1(IDAO _dao, uint256 _number) external initializer { - __PluginUUPSUpgradeable_init(_dao); - number = _number; - } - - function storeNumber(uint256 _number) external auth(STORE_PERMISSION_ID) { - number = _number; - } -} -``` - -### 3. Plugin done, PluginSetup contract next! - -Now that we have the logic for the plugin implemented, we'll need to define how this plugin should be installed/uninstalled from a DAO. In the next step, we'll write the `PluginSetup` contract - the one containing the installation, uninstallation, and upgrading instructions for the plugin. diff --git a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/upgradeable-plugin/index.adoc b/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/upgradeable-plugin/index.adoc deleted file mode 100644 index 270afa238..000000000 --- a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/upgradeable-plugin/index.adoc +++ /dev/null @@ -1,33 +0,0 @@ -= Upgradeable Plugins - -== How to develop an Upgradeable Plugin - -Upgradeable contracts offer advantages because you can cheaply change or fix the logic of your contract without losing the storage of your contract. -If you want to review plugin types in depth, check out our xref:how-to-guides/plugin-development/plugin-types.adoc[guide on plugin types here]. - -The drawbacks however, are that: - -- there are plenty of ways to make a mistake, and -- the changeable logic poses a new attack surface. - -Although we've abstracted away most of the complications of the upgrade process through our `PluginUUPSUpgradeable` base class, -please know that writing an upgradeable contract is an advanced topic. - -### Prerequisites - -- You have read about the different xref:how-to-guides/plugin-development/plugin-types.adoc[plugin types] and decided to develop an upgradeable plugin being deployed via the link:https://eips.ethereum.org/EIPS/eip-1822[UUPS pattern (ERC-1822)]. -- You know how to write a [non-upgradeable plugin](../03-non-upgradeable-plugin/index.md). -- You know about the difficulties and pitfalls of link:https://docs.openzeppelin.com/upgrades-plugins/1.x/writing-upgradeable[Writing Upgradeable Contracts] that come with - - modifying the storage layout - - initialization - - inheritance - - leaving storage gaps - -Up next, check out our guides on: - -1. xref:how-to-guides/plugin-development/upgradeable-plugin/initialization.adoc[How to initialize an Upgradeable Plugins] -2. xref:how-to-guides/plugin-development/upgradeable-plugin/implementation.adoc[How to build the implementation of an Upgradeable Plugin] -3. xref:how-to-guides/plugin-development/upgradeable-plugin/setup.adoc[How to build and deploy a Plugin Setup contract for an Upgradeable Plugin] -4. xref:how-to-guides/plugin-development/upgradeable-plugin/subsequent-builds.adoc[How to create a subsequent build implementation to an Upgradeable Plugin] -5. xref:how-to-guides/plugin-development/upgradeable-plugin/updating-versions.adoc[How to upgrade an Upgradeable Plugin] -6. xref:how-to-guides/plugin-development/publication/index.adoc[How to publish my plugin into the Aragon OSx protocol] diff --git a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/upgradeable-plugin/initialization.adoc b/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/upgradeable-plugin/initialization.adoc deleted file mode 100644 index 9748a2339..000000000 --- a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/upgradeable-plugin/initialization.adoc +++ /dev/null @@ -1,82 +0,0 @@ -= Initialization - -== How to Initialize Upgradeable Plugins - -To deploy your implementation contract via the link:https://eips.ethereum.org/EIPS/eip-1822[UUPS pattern (ERC-1822)], you inherit from the `PluginUUPSUpgradeable` contract. - -We must protect it from being set up multiple times by using link:https://docs.openzeppelin.com/contracts/4.x/api/proxy#Initializable[OpenZeppelin's initializer modifier made available through 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. - -```solidity -// SPDX-License-Identifier: AGPL-3.0-or-later -pragma solidity 0.8.21; - -import {PluginUUPSUpgradeable, IDAO} '@aragon/osx/core/plugin/PluginUUPSUpgradeable.sol'; - -/// @title SimpleStorage build 1 -contract SimpleStorageBuild1 is PluginUUPSUpgradeable { - uint256 public number; // added in build 1 - - /// @notice Initializes the plugin when build 1 is installed. - function initializeBuild1(IDAO _dao, uint256 _number) external initializer { - __PluginUUPSUpgradeable_init(_dao); - number = _number; - } -} -``` - -NOTE: Keep in mind that in order to discriminate between the different initialize functions of your different builds, -we name the initialize function `initializeBuild1`. This becomes more demanding for subsequent builds of your plugin. - -### Initializing Subsequent Builds - -Since you have chosen to build an upgradeable plugin, you can publish subsequent builds of plugin and **allow the users to -update from an earlier build without losing the storage**. - -CAUTION: Do not inherit from previous versions as this can mess up the inheritance chain. Instead, write self-contained -contracts by simply copying the code or modifying the file in your git repo. - -In this example, we wrote a `SimpleStorageBuild2` contract and added a new storage variable `address public account;`. -Because users can freshly install the new version or update from build 1, we now have to write two initializer -functions: `initializeBuild2` and `initializeFromBuild1` in our Plugin implementation contract. - -```solidity -/// @title SimpleStorage build 2 -contract SimpleStorageBuild2 is PluginUUPSUpgradeable { - uint256 public number; // added in build 1 - address public account; // added in build 2 - - /// @notice Initializes the plugin when build 2 is installed. - function initializeBuild2( - IDAO _dao, - uint256 _number, - address _account - ) external reinitializer(2) { - __PluginUUPSUpgradeable_init(_dao); - number = _number; - account = _account; - } - - /// @notice Initializes the plugin when the update from build 1 to build 2 is applied. - /// @dev The initialization of `SimpleStorageBuild1` has already happened. - function initializeFromBuild1(IDAO _dao, address _account) external reinitializer(2) { - account = _account; - } -} -``` - -In general, for each version for which you want to support updates from, you have to provide a separate `initializeFromBuildX` -function taking care of initializing the storage and transferring the `helpers` and `permissions` of the previous version into -the same state as if it had been freshly installed. - -Each `initializeBuildX` must be protected with a modifier that allows it to be only called once. - -In contrast to build 1, we now must use link:https://docs.openzeppelin.com/contracts/4.x/api/proxy#Initializable-reinitializer-uint8-[OpenZeppelin's `modifier reinitializer(uint8 build)`] -for build 2 instead of `modifier initializer` because it allows us to execute 255 subsequent initializations. -More specifically, we used `reinitializer(2)` here for our build 2. Note that we could also have used -`function initializeBuild1(IDAO _dao, uint256 _number) external reinitializer(1)` for build 1 because -`initializer` and `reinitializer(1)` are equivalent statements. For build 3, we must use `reinitializer(3)`, -for build 4 `reinitializer(4)` and so on. diff --git a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/upgradeable-plugin/setup.adoc b/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/upgradeable-plugin/setup.adoc deleted file mode 100644 index 99b52e67f..000000000 --- a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/upgradeable-plugin/setup.adoc +++ /dev/null @@ -1,215 +0,0 @@ -= Plugin Setup Contract - -== How to build the Plugin Setup Contract for Upgradeable Plugins - -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. - -### 1. Finish the Plugin contract's first build - -Before building the Plugin Setup contract, make sure you have the logic for your plugin implemented. In this case, - we're building a simple storage plugin which stores a number. - -```solidity -// SPDX-License-Identifier: AGPL-3.0-or-later -pragma solidity 0.8.21; - -import {IDAO, PluginUUPSUpgradeable} from '@aragon/osx/core/plugin/PluginUUPSUpgradeable.sol'; - -/// @title SimpleStorage build 1 -contract SimpleStorageBuild1 is PluginUUPSUpgradeable { - bytes32 public constant STORE_PERMISSION_ID = keccak256('STORE_PERMISSION'); - - uint256 public number; // added in build 1 - - /// @notice Initializes the plugin when build 1 is installed. - function initializeBuild1(IDAO _dao, uint256 _number) external initializer { - __PluginUUPSUpgradeable_init(_dao); - number = _number; - } - - function storeNumber(uint256 _number) external auth(STORE_PERMISSION_ID) { - number = _number; - } -} -``` - -### 2. Add the `prepareInstallation()` and `prepareUninstallation()` functions - -Each `PluginSetup` contract is deployed only once and each plugin version will have its own `PluginSetup` contract deployed. -Accordingly, we instantiate the `implementation` contract via Solidity's `new` keyword as deployment with the minimal proxy -pattern would be more expensive in this case. - -In order for the Plugin to be easily installed into the DAO, we need to define the instructions for the plugin to work effectively. -We have to tell the DAO's Permission Manager which permissions it needs to grant or revoke. - -Hence, we will create a `prepareInstallation()` function, as well as a `prepareUninstallation()` function. These are the functions -the `PluginSetupProcessor.sol` (the contract in charge of installing plugins into the DAO) will use. - -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. -Similarly, the `prepareUninstallation()` function takes in a `payload`. - -```solidity -// SPDX-License-Identifier: AGPL-3.0-or-later - -pragma solidity 0.8.21; - -import {PermissionLib} from '@aragon/osx/core/permission/PermissionLib.sol'; -import {PluginSetup, IPluginSetup} from '@aragon/osx/framework/plugin/setup/PluginSetup.sol'; -import {SimpleStorageBuild1} from './SimpleStorageBuild1.sol'; - -/// @title SimpleStorageSetup build 1 -contract SimpleStorageBuild1Setup is PluginSetup { - address private immutable simpleStorageImplementation; - - constructor() { - simpleStorageImplementation = address(new SimpleStorageBuild1()); - } - - /// @inheritdoc IPluginSetup - function prepareInstallation( - address _dao, - bytes memory _data - ) external returns (address plugin, PreparedSetupData memory preparedSetupData) { - uint256 number = abi.decode(_data, (uint256)); - - plugin = createERC1967Proxy( - simpleStorageImplementation, - abi.encodeCall(SimpleStorageBuild1.initializeBuild1, (IDAO(_dao), number)) - ); - - PermissionLib.MultiTargetPermission[] - memory permissions = new PermissionLib.MultiTargetPermission[](1); - - permissions[0] = PermissionLib.MultiTargetPermission({ - operation: PermissionLib.Operation.Grant, - where: plugin, - who: _dao, - condition: PermissionLib.NO_CONDITION, - permissionId: SimpleStorageBuild1(this.implementation()).STORE_PERMISSION_ID() - }); - - preparedSetupData.permissions = permissions; - } - - /// @inheritdoc IPluginSetup - function prepareUninstallation( - address _dao, - SetupPayload calldata _payload - ) external view returns (PermissionLib.MultiTargetPermission[] memory permissions) { - permissions = new PermissionLib.MultiTargetPermission[](1); - - permissions[0] = PermissionLib.MultiTargetPermission({ - operation: PermissionLib.Operation.Revoke, - where: _payload.plugin, - who: _dao, - condition: PermissionLib.NO_CONDITION, - permissionId: SimpleStorageBuild1(this.implementation()).STORE_PERMISSION_ID() - }); - } - - /// @inheritdoc IPluginSetup - function implementation() external view returns (address) { - return simpleStorageImplementation; - } -} -``` - -As you can see, we have a constructor storing the implementation contract instantiated via the `new` method in the private immutable -variable `implementation` to save gas and an `implementation` function to return it. - -NOTE: Specifically important for this type of plugin is the `prepareUpdate()` function. Since we don't know the parameters we will require when updating the plugin to the next version, we can't add the `prepareUpdate()` function just yet. However, keep in mind that we will need to deploy new Plugin Setup contracts in subsequent builds to add in the `prepareUpdate()` function with each build requirements. -We see this in depth in the xref:how-to-guides/plugin-development/upgradeable-plugin/updating-versions.adoc[How to update an Upgradeable Plugin] section. - -### 3. Deployment - -Once you're done with your Plugin Setup contract, we'll need to deploy it so we can publish it into the Aragon OSx protocol. -You can deploy your contract with a basic deployment script. - -Firstly, we'll make sure our preferred network is well setup within our `hardhat.config.js` file, which should look something like: - -```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. -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'; - -module.exports = { - defaultNetwork: 'hardhat', - networks: { - hardhat: {}, - goerli: { - url: `https://eth-goerli.g.alchemy.com/v2/${goerliAlchemyKey}`, - accounts: [privateKeyGoerli], - }, - }, - solidity: { - version: '0.8.17', - settings: { - optimizer: { - enabled: true, - runs: 200, - }, - }, - }, - paths: { - sources: './contracts', - tests: './test', - cache: './cache', - artifacts: './artifacts', - }, - mocha: { - timeout: 40000, - }, -}; -``` - -Then, create a `scripts/deploy.js` file and add a simple deploy script. We'll only be deploying the PluginSetup contract, -since this should deploy the Plugin contract within its constructor. - -```js -import {ethers} from 'hardhat'; - -async function main() { - const [deployer] = await ethers.getSigners(); - - console.log('Deploying contracts with the account:', deployer.address); - console.log('Account balance:', (await deployer.getBalance()).toString()); - - const getSimpleStorageSetup = - await ethers.getContractFactory('SimpleStorageSetup'); - const SimpleStorageSetup = await SimpleStorageSetup.deploy(); - - await SimpleStorageSetup.deployed(); - - console.log('SimpleStorageSetup address:', SimpleStorageSetup.address); -} - -// We recommend this pattern to be able to use async/await everywhere -// and properly handle errors. -main().catch(error => { - console.error(error); - process.exitCode = 1; -}); -``` - -Finally, run this in your terminal to execute the command: - -```bash -npx hardhat run scripts/deploy.ts -``` - -### 4. Publishing the Plugin to the Aragon OSx Protocol - -Once done, our plugin is ready to be published on the Aragon plugin registry. With the address of the `SimpleAdminSetup` -contract deployed, we're almost ready for creating our `PluginRepo`, the plugin's repository where all plugin versions will live. -Check out our how to guides on xref:how-to-guides/plugin-development/publication/index.adoc[publishing your plugin here]. diff --git a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/upgradeable-plugin/subsequent-builds.adoc b/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/upgradeable-plugin/subsequent-builds.adoc deleted file mode 100644 index 443091004..000000000 --- a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/upgradeable-plugin/subsequent-builds.adoc +++ /dev/null @@ -1,164 +0,0 @@ -= Subsequent Builds - -== How to create a subsequent build to an Upgradeable Plugin - -A build is a new implementation of your Upgradeable Plugin. Upgradeable contracts offer advantages because you can cheaply change -or fix the logic of your contract without losing the storage of your contract. - -The Aragon OSx protocol has an on-chain versioning system built-in, which distinguishes between releases and builds. - -- **Releases** contain breaking changes, which are incompatible with preexisting installations. Updates to a different release are -not possible. Instead, you must install the new plugin release and uninstall the old one. -- **Builds** are minor/patch versions within a release, and they are meant for compatible upgrades -only (adding a feature or fixing a bug without changing anything else). - -In this how to guide, we'll go through how we can create these builds for our plugins. Specifically, we'll showcase two specific -types of builds - one that modifies the storage of the plugins, another one which modifies its bytecode. Both are possible and -can be implemented within the same build implementation as well. - -### 1. Make sure your previous build is deployed and published - -Make sure you have at least one build already deployed and published into the Aragon protocol. Make sure to check out our -xref:how-to-guides/plugin-development/publication/index.adoc[publishing guide] to ensure this step is done. - -### 2. Create a new build implementation - -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. - -```solidity -import {PluginUUPSUpgradeable, IDAO} '@aragon/osx/core/plugin/PluginUUPSUpgradeable.sol'; - -/// @title SimpleStorage build 2 -contract SimpleStorageBuild2 is PluginUUPSUpgradeable { - bytes32 public constant STORE_PERMISSION_ID = keccak256('STORE_PERMISSION'); - - uint256 public number; // added in build 1 - address public account; // added in build 2 - - /// @notice Initializes the plugin when build 2 is installed. - function initializeBuild2( - IDAO _dao, - uint256 _number, - address _account - ) external reinitializer(2) { - __PluginUUPSUpgradeable_init(_dao); - number = _number; - account = _account; - } - - /// @notice Initializes the plugin when the update from build 1 to build 2 is applied. - /// @dev The initialization of `SimpleStorageBuild1` has already happened. - function initializeFromBuild1(address _account) external reinitializer(2) { - account = _account; - } - - function storeNumber(uint256 _number) external auth(STORE_PERMISSION_ID) { - number = _number; - } - - function storeAccount(address _account) external auth(STORE_PERMISSION_ID) { - account = _account; - } -} -``` - -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 link:https://docs.openzeppelin.com/contracts/4.x/api/proxy#UUPSUpgradeable[OpenZeppelin's UUPSUpgradeability implementation here]. - -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 link:https://docs.openzeppelin.com/upgrades-plugins/1.x/writing-upgradeable#storage-gaps[here]. - -### 3. Alternatively, a build implementation modifying bytecode - -Updates for your contracts don't necessarily need to affect the storage, they can also modify the plugin's bytecode. -Modifying the contract's bytecode, means making changes to: - -- functions -- constants -- immutables -- events -- errors - -For this third build, then, we want to change the bytecode of our implementation as an example, so we 've introduced two -separate permissions for the `storeNumber` and `storeAccount` functions and named them `STORE_NUMBER_PERMISSION_ID` and `STORE_ACCOUNT_PERMISSION_ID` permission, respectively. -Additionally, we decided to add the `NumberStored` and `AccountStored` events as well as an error preventing users from setting the -same value twice. All these changes only affect the contract bytecode and not the storage. - -Here, it is important to remember how Solidity stores `constant`s (and `immutable`s). In contrast to normal variables, they are directly -written into the bytecode on contract creation so that we don't need to worry that the second `bytes32` constant that we added -shifts down the storage so that the value in `uint256 public number` gets lost. It is also important to note that, the `initializeFromBuild2` -could be left empty. Here, we just emit the events with the currently stored values. - -```solidity -import {PluginUUPSUpgradeable, IDAO} '@aragon/osx/core/plugin/PluginUUPSUpgradeable.sol'; - -/// @title SimpleStorage build 3 -contract SimpleStorageBuild3 is PluginUUPSUpgradeable { - bytes32 public constant STORE_NUMBER_PERMISSION_ID = keccak256('STORE_NUMBER_PERMISSION'); // changed in build 3 - bytes32 public constant STORE_ACCOUNT_PERMISSION_ID = keccak256('STORE_ACCOUNT_PERMISSION'); // added in build 3 - - uint256 public number; // added in build 1 - address public account; // added in build 2 - - // added in build 3 - event NumberStored(uint256 number); - event AccountStored(address number); - error AlreadyStored(); - - /// @notice Initializes the plugin when build 3 is installed. - function initializeBuild3( - IDAO _dao, - uint256 _number, - address _account - ) external reinitializer(3) { - __PluginUUPSUpgradeable_init(_dao); - number = _number; - account = _account; - - emit NumberStored({number: _number}); - emit AccountStored({account: _account}); - } - - /// @notice Initializes the plugin when the update from build 2 to build 3 is applied. - /// @dev The initialization of `SimpleStorageBuild2` has already happened. - function initializeFromBuild2() external reinitializer(3) { - emit NumberStored({number: number}); - emit AccountStored({account: account}); - } - - /// @notice Initializes the plugin when the update from build 1 to build 3 is applied. - /// @dev The initialization of `SimpleStorageBuild1` has already happened. - function initializeFromBuild1(address _account) external reinitializer(3) { - account = _account; - - emit NumberStored({number: number}); - emit AccountStored({account: _account}); - } - - function storeNumber(uint256 _number) external auth(STORE_NUMBER_PERMISSION_ID) { - if (_number == number) revert AlreadyStored(); - - number = _number; - - emit NumberStored({number: _number}); - } - - function storeAccount(address _account) external auth(STORE_ACCOUNT_PERMISSION_ID) { - if (_account == account) revert AlreadyStored(); - - account = _account; - - emit AccountStored({account: _account}); - } -} -``` - -NOTE: Despite no storage-related changes happening in build 3, we must apply the `reinitializer(3)` modifier to all `initialize` functions so that -none of them can be called twice or in the wrong order. diff --git a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/upgradeable-plugin/updating-versions.adoc b/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/upgradeable-plugin/updating-versions.adoc deleted file mode 100644 index 2c3157a98..000000000 --- a/packages/contracts/docs/modules/ROOT/pages/how-to-guides/plugin-development/upgradeable-plugin/updating-versions.adoc +++ /dev/null @@ -1,369 +0,0 @@ -= Upgrade a DAO Plugin - -## How to upgrade an Upgradeable Plugin - -Updating an Upgradeable plugin means we want to direct the implementation of our functionality to a new build, rather than -the existing one. - -In this tutorial, we will go through how to update the version of an Upgradeable plugin and each component needed. - -### 1. Create the new build implementation contract - -Firstly, you want to create the new build implementation contract the plugin should use. You can read more about how to do -this in the xref:how-to-guides/plugin-development/upgradeable-plugin/subsequent-builds.adoc[How to create a subsequent build implementation to an Upgradeable Plugin] guide. - -```solidity -// SPDX-License-Identifier: AGPL-3.0-or-later -pragma solidity 0.8.21; - -import {IDAO, PluginUUPSUpgradeable} from '@aragon/osx/core/plugin/PluginUUPSUpgradeable.sol'; - -/// @title SimpleStorage build 2 -contract SimpleStorageBuild2 is PluginUUPSUpgradeable { - bytes32 public constant STORE_PERMISSION_ID = keccak256('STORE_PERMISSION'); - - uint256 public number; // added in build 1 - address public account; // added in build 2 - - /// @notice Initializes the plugin when build 2 is installed. - function initializeBuild2( - IDAO _dao, - uint256 _number, - address _account - ) external reinitializer(2) { - __PluginUUPSUpgradeable_init(_dao); - number = _number; - account = _account; - } - - /// @notice Initializes the plugin when the update from build 1 to build 2 is applied. - /// @dev The initialization of `SimpleStorageBuild1` has already happened. - function initializeFromBuild1(address _account) external reinitializer(2) { - account = _account; - } - - function storeNumber(uint256 _number) external auth(STORE_PERMISSION_ID) { - number = _number; - } - - function storeAccount(address _account) external auth(STORE_PERMISSION_ID) { - account = _account; - } -} -``` - -### 2. Write a new Plugin Setup contract - -In order to do update a plugin, we need a `prepareUpdate()` function in our Plugin Setup contract which points the functionality to a -new build, as we described in the xref:how-to-guides/plugin-development/upgradeable-plugin/subsequent-builds.adoc[How to create a subsequent build implementation to an Upgradeable Plugin] guide. -The `prepareUpdate()` function must transition the plugin from the old build state into the new one so that it ends up having the -same permissions (and helpers) as if it had been freshly installed. - -In contrast to the original build 1, build 2 requires two input arguments: `uint256 _number` and `address _account` that we decode -from the bytes-encoded input `_data`. - -```solidity -// SPDX-License-Identifier: AGPL-3.0-or-later - -pragma solidity 0.8.21; - -import {PermissionLib} from '@aragon/osx/core/permission/PermissionLib.sol'; -import {PluginSetup, IPluginSetup} from '@aragon/osx/framework/plugin/setup/PluginSetup.sol'; -import {SimpleStorageBuild2} from './SimpleStorageBuild2.sol'; - -/// @title SimpleStorageSetup build 2 -contract SimpleStorageBuild2Setup is PluginSetup { - address private immutable simpleStorageImplementation; - - constructor() { - simpleStorageImplementation = address(new SimpleStorageBuild2()); - } - - /// @inheritdoc IPluginSetup - function prepareInstallation( - address _dao, - bytes memory _data - ) external returns (address plugin, PreparedSetupData memory preparedSetupData) { - (uint256 _number, address _account) = abi.decode(_data, (uint256, address)); - - plugin = createERC1967Proxy( - simpleStorageImplementation, - abi.encodeWithSelector(SimpleStorageBuild2.initializeBuild2.selector, _dao, _number, _account) - ); - - PermissionLib.MultiTargetPermission[] - memory permissions = new PermissionLib.MultiTargetPermission[](1); - - permissions[0] = PermissionLib.MultiTargetPermission({ - operation: PermissionLib.Operation.Grant, - where: plugin, - who: _dao, - condition: PermissionLib.NO_CONDITION, - permissionId: SimpleStorageBuild2(this.implementation()).STORE_PERMISSION_ID() - }); - - preparedSetupData.permissions = permissions; - } - - /// @inheritdoc IPluginSetup - function prepareUpdate( - address _dao, - uint16 _currentBuild, - SetupPayload calldata _payload - ) - external - pure - override - returns (bytes memory initData, PreparedSetupData memory preparedSetupData) - { - (_dao, preparedSetupData); - - if (_currentBuild == 0) { - address _account = abi.decode(_payload.data, (address)); - initData = abi.encodeWithSelector( - SimpleStorageBuild2.initializeFromBuild1.selector, - _account - ); - } - } - - /// @inheritdoc IPluginSetup - function prepareUninstallation( - address _dao, - SetupPayload calldata _payload - ) external view returns (PermissionLib.MultiTargetPermission[] memory permissions) { - permissions = new PermissionLib.MultiTargetPermission[](1); - - permissions[0] = PermissionLib.MultiTargetPermission({ - operation: PermissionLib.Operation.Revoke, - where: _payload.plugin, - who: _dao, - condition: PermissionLib.NO_CONDITION, - permissionId: SimpleStorageBuild2(this.implementation()).STORE_PERMISSION_ID() - }); - } - - /// @inheritdoc IPluginSetup - function implementation() external view returns (address) { - return simpleStorageImplementation; - } -} -``` - -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 _data` and pass -it to the `initializeFromBuild1` function taking care of initializing the storage that was added in this build. - -### 3. Future builds - -For each build we add, we will need to add a `prepareUpdate()` function with any parameters needed to update to that implementation. - -In this third build, for example, we are modifying the bytecode of the plugin. - -**Third plugin build example, modifying the plugin's bytecode.** - -```solidity -// SPDX-License-Identifier: AGPL-3.0-or-later -pragma solidity 0.8.21; - -import {IDAO, PluginUUPSUpgradeable} from '@aragon/osx/core/plugin/PluginUUPSUpgradeable.sol'; - -/// @title SimpleStorage build 3 -contract SimpleStorageBuild3 is PluginUUPSUpgradeable { - bytes32 public constant STORE_NUMBER_PERMISSION_ID = keccak256('STORE_NUMBER_PERMISSION'); // changed in build 3 - bytes32 public constant STORE_ACCOUNT_PERMISSION_ID = keccak256('STORE_ACCOUNT_PERMISSION'); // added in build 3 - - uint256 public number; // added in build 1 - address public account; // added in build 2 - - // added in build 3 - event NumberStored(uint256 number); - event AccountStored(address account); - error AlreadyStored(); - - /// @notice Initializes the plugin when build 3 is installed. - function initializeBuild3( - IDAO _dao, - uint256 _number, - address _account - ) external reinitializer(3) { - __PluginUUPSUpgradeable_init(_dao); - number = _number; - account = _account; - - emit NumberStored({number: _number}); - emit AccountStored({account: _account}); - } - - /// @notice Initializes the plugin when the update from build 2 to build 3 is applied. - /// @dev The initialization of `SimpleStorageBuild2` has already happened. - function initializeFromBuild2() external reinitializer(3) { - emit NumberStored({number: number}); - emit AccountStored({account: account}); - } - - /// @notice Initializes the plugin when the update from build 1 to build 3 is applied. - /// @dev The initialization of `SimpleStorageBuild1` has already happened. - function initializeFromBuild1(address _account) external reinitializer(3) { - account = _account; - - emit NumberStored({number: number}); - emit AccountStored({account: _account}); - } - - function storeNumber(uint256 _number) external auth(STORE_NUMBER_PERMISSION_ID) { - if (_number == number) revert AlreadyStored(); - - number = _number; - - emit NumberStored({number: _number}); - } - - function storeAccount(address _account) external auth(STORE_ACCOUNT_PERMISSION_ID) { - if (_account == account) revert AlreadyStored(); - - account = _account; - - emit AccountStored({account: _account}); - } -} -``` - - -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. - -**Third plugin setup example, modifying `prepareUpdate` function**. - -```solidity -// SPDX-License-Identifier: AGPL-3.0-or-later - -pragma solidity 0.8.21; - -import {PermissionLib} from '@aragon/osx/core/permission/PermissionLib.sol'; -import {PluginSetup, IPluginSetup} from '@aragon/osx/framework/plugin/setup/PluginSetup.sol'; -import {SimpleStorageBuild2} from '../build2/SimpleStorageBuild2.sol'; -import {SimpleStorageBuild3} from './SimpleStorageBuild3.sol'; - -/// @title SimpleStorageSetup build 3 -contract SimpleStorageBuild3Setup is PluginSetup { - address private immutable simpleStorageImplementation; - - constructor() { - simpleStorageImplementation = address(new SimpleStorageBuild3()); - } - - /// @inheritdoc IPluginSetup - function prepareInstallation( - address _dao, - bytes memory _data - ) external returns (address plugin, PreparedSetupData memory preparedSetupData) { - (uint256 _number, address _account) = abi.decode(_data, (uint256, address)); - - plugin = createERC1967Proxy( - simpleStorageImplementation, - abi.encodeWithSelector(SimpleStorageBuild3.initializeBuild3.selector, _dao, _number, _account) - ); - - PermissionLib.MultiTargetPermission[] - memory permissions = new PermissionLib.MultiTargetPermission[](2); - - permissions[0] = PermissionLib.MultiTargetPermission({ - operation: PermissionLib.Operation.Grant, - where: plugin, - who: _dao, - condition: PermissionLib.NO_CONDITION, - permissionId: SimpleStorageBuild3(this.implementation()).STORE_NUMBER_PERMISSION_ID() - }); - - permissions[1] = permissions[0]; - permissions[1].permissionId = SimpleStorageBuild3(this.implementation()) - .STORE_ACCOUNT_PERMISSION_ID(); - - preparedSetupData.permissions = permissions; - } - - /// @inheritdoc IPluginSetup - function prepareUpdate( - address _dao, - uint16 _currentBuild, - SetupPayload calldata _payload - ) - external - view - override - returns (bytes memory initData, PreparedSetupData memory preparedSetupData) - { - if (_currentBuild == 0) { - address _account = abi.decode(_payload.data, (address)); - initData = abi.encodeWithSelector( - SimpleStorageBuild3.initializeFromBuild1.selector, - _account - ); - } else if (_currentBuild == 1) { - initData = abi.encodeWithSelector(SimpleStorageBuild3.initializeFromBuild2.selector); - } - - PermissionLib.MultiTargetPermission[] - memory permissions = new PermissionLib.MultiTargetPermission[](3); - permissions[0] = PermissionLib.MultiTargetPermission({ - operation: PermissionLib.Operation.Revoke, - where: _dao, - who: _payload.plugin, - condition: PermissionLib.NO_CONDITION, - permissionId: keccak256('STORE_PERMISSION') - }); - - permissions[1] = permissions[0]; - permissions[1].operation = PermissionLib.Operation.Grant; - permissions[1].permissionId = SimpleStorageBuild3(this.implementation()) - .STORE_NUMBER_PERMISSION_ID(); - - permissions[2] = permissions[1]; - permissions[2].permissionId = SimpleStorageBuild3(this.implementation()) - .STORE_ACCOUNT_PERMISSION_ID(); - - preparedSetupData.permissions = permissions; - } - - /// @inheritdoc IPluginSetup - function prepareUninstallation( - address _dao, - SetupPayload calldata _payload - ) external view returns (PermissionLib.MultiTargetPermission[] memory permissions) { - permissions = new PermissionLib.MultiTargetPermission[](2); - - permissions[0] = PermissionLib.MultiTargetPermission({ - operation: PermissionLib.Operation.Revoke, - where: _payload.plugin, - who: _dao, - condition: PermissionLib.NO_CONDITION, - permissionId: SimpleStorageBuild3(this.implementation()).STORE_NUMBER_PERMISSION_ID() - }); - - permissions[1] = permissions[1]; - permissions[1].permissionId = SimpleStorageBuild3(this.implementation()) - .STORE_ACCOUNT_PERMISSION_ID(); - } - - /// @inheritdoc IPluginSetup - function implementation() external view returns (address) { - return simpleStorageImplementation; - } -} -``` - - -In this case, the `prepareUpdate()` function only contains a condition checking from which build number the update is transitioning -to build 2. Here, we can update from build 0 or build 1 and different operations must happen for each case to transition to -`SimpleAdminBuild3`. - -In the first case, `initializeFromBuild1` is called taking care of initializing `address _account` that was added in build 1 and -emitting the events added in build 2. - -In the second case, `initializeFromBuild2` is called taking care of initializing the build. Here, only the two events will be emitted. - -Lastly, the `prepareUpdate()` function takes care of modifying the permissions by revoking the `STORE_PERMISSION_ID` and granting -the more specific `STORE_NUMBER_PERMISSION_ID` and `STORE_ACCOUNT_PERMISSION_ID` permissions, that are also granted if build 2 is -freshly installed. This must happen for both update paths so this code is outside the `if` statements.