Merge branch 'staging' into f/add-dao-docs

aragon · Jun 6, 2024 · 77ee5d6 · 77ee5d6
2 parents 840317b + 20dfc62
commit 77ee5d6
Show file tree

Hide file tree

Showing 49 changed files with 2,884 additions and 810 deletions.
diff --git a/docs/advanced/ens.md b/docs/advanced/ens.md
@@ -4,6 +4,20 @@ sidebar_label: ENS
 sidebar_position: 5
 ---
 
-## ENS
+## Unique DAO and Plugin Repo Names
 
-This section will contain docs.
+To make DAOs and plugin repositories easily identifiable in the Aragon OSx ecosystem, we assign unique ENS names to them upon registration during the [DAO creation](./dao/01-creation/index.md) and [plugin publishing](./plugin/repositories/factory-and-registry.md) processes.
+
+:::info
+You can skip registering an ENS name for your DAO under the `dao.eth` by leaving the [`DAOSettings.subdomain` field](./technical-reference/framework/dao/DAOFactory.md#public-struct-daosettings) empty when calling the [`createDao`](./technical-reference/framework/dao/DAOFactory.md#external-function-createdao) function.
+:::
+
+### Allowed Character Set
+
+We allow the following characters for the subdomain names:
+
+- Lowercase letters `a-z`
+- Digits `0-9`
+- The hyphen `-`
+
+This way, you can name and share the DAO or plugin repo you have created as `my-cool.dao.eth` or `my-handy.plugin.dao.eth` to make their addresses easily shareable and discoverable on ENS-supporting chains.
diff --git a/docs/advanced/technical-reference/_category_.yml b/docs/advanced/technical-reference/_category_.yml
@@ -1,5 +1,3 @@
 collapsible: true
 collapsed: true
-label: Technical Reference
-link: null
 position: 6
diff --git a/docs/advanced/technical-reference/core/dao/DAO.md b/docs/advanced/technical-reference/core/dao/DAO.md
diff --git a/docs/advanced/technical-reference/core/dao/IEIP4824.md b/docs/advanced/technical-reference/core/dao/IEIP4824.md
@@ -0,0 +1,19 @@
+## Description
+
+See https://eips.ethereum.org/EIPS/eip-4824
+
+## Implementation
+
+### external function daoURI
+
+A distinct Uniform Resource Identifier (URI) pointing to a JSON object following the "EIP-4824 DAO JSON-LD Schema". This JSON file splits into four URIs: membersURI, proposalsURI, activityLogURI, and governanceURI. The membersURI should point to a JSON file that conforms to the "EIP-4824 Members JSON-LD Schema". The proposalsURI should point to a JSON file that conforms to the "EIP-4824 Proposals JSON-LD Schema". The activityLogURI should point to a JSON file that conforms to the "EIP-4824 Activity Log JSON-LD Schema". The governanceURI should point to a flatfile, normatively a .md file. Each of the JSON files named above can be statically hosted or dynamically-generated.
+
+```solidity
+function daoURI() external view returns (string _daoURI)
+```
+
+| Output    | Type     | Description  |
+| --------- | -------- | ------------ |
+| `_daoURI` | `string` | The DAO URI. |
+
+<!--CONTRACT_END-->
diff --git a/docs/advanced/technical-reference/core/permission/PermissionManager.md b/docs/advanced/technical-reference/core/permission/PermissionManager.md
diff --git a/docs/advanced/technical-reference/core/utils/CallbackHandler.md b/docs/advanced/technical-reference/core/utils/CallbackHandler.md
@@ -0,0 +1,82 @@
+## Description
+
+This contract handles callbacks by registering a magic number together with the callback function's selector. It provides the `_handleCallback` function that inheriting contracts have to call inside their `fallback()` function (`_handleCallback(msg.callbackSelector, msg.data)`). This allows to adaptively register ERC standards (e.g., [ERC-721](https://eips.ethereum.org/EIPS/eip-721), [ERC-1115](https://eips.ethereum.org/EIPS/eip-1155), or future versions of [ERC-165](https://eips.ethereum.org/EIPS/eip-165)) and returning the required magic numbers for the associated callback functions for the inheriting contract so that it doesn't need to be upgraded.
+
+This callback handling functionality is intented to be used by executor contracts (i.e., `DAO.sol`).
+
+## Implementation
+
+### internal variable callbackMagicNumbers
+
+A mapping between callback function selectors and magic return numbers.
+
+```solidity
+mapping(bytes4 => bytes4) callbackMagicNumbers
+```
+
+### internal variable UNREGISTERED_CALLBACK
+
+The magic number refering to unregistered callbacks.
+
+```solidity
+bytes4 UNREGISTERED_CALLBACK
+```
+
+### error UnkownCallback
+
+Thrown if the callback function is not registered.
+
+```solidity
+error UnkownCallback(bytes4 callbackSelector, bytes4 magicNumber)
+```
+
+| Input              | Type     | Description                                                           |
+| :----------------- | -------- | --------------------------------------------------------------------- |
+| `callbackSelector` | `bytes4` | The selector of the callback function.                                |
+| `magicNumber`      | `bytes4` | The magic number to be registered for the callback function selector. |
+
+### event CallbackReceived
+
+Emitted when `_handleCallback` is called.
+
+```solidity
+event CallbackReceived(address sender, bytes4 sig, bytes data)
+```
+
+| Input    | Type      | Description              |
+| :------- | --------- | ------------------------ |
+| `sender` | `address` | Who called the callback. |
+| `sig`    | `bytes4`  | The function signature.  |
+| `data`   | `bytes`   | The calldata.            |
+
+### internal function \_handleCallback
+
+Handles callbacks to adaptively support ERC standards.
+
+```solidity
+function _handleCallback(bytes4 _callbackSelector, bytes _data) internal virtual returns (bytes4)
+```
+
+| Input               | Type     | Description                                                                    |
+| :------------------ | -------- | ------------------------------------------------------------------------------ |
+| `_callbackSelector` | `bytes4` | The function selector of the callback function.                                |
+| `_data`             | `bytes`  | The calldata.                                                                  |
+| **Output**          |          |
+| `0`                 | `bytes4` | The magic number registered for the function selector triggering the fallback. |
+
+_This function is supposed to be called via `_handleCallback(msg.sig, msg.data)` in the `fallback()` function of the inheriting contract._
+
+### internal function \_registerCallback
+
+Registers a magic number for a callback function selector.
+
+```solidity
+function _registerCallback(bytes4 _callbackSelector, bytes4 _magicNumber) internal virtual
+```
+
+| Input               | Type     | Description                                                           |
+| :------------------ | -------- | --------------------------------------------------------------------- |
+| `_callbackSelector` | `bytes4` | The selector of the callback function.                                |
+| `_magicNumber`      | `bytes4` | The magic number to be registered for the callback function selector. |
+
+<!--CONTRACT_END-->
diff --git a/docs/advanced/technical-reference/framework/dao/DAOFactory.md b/docs/advanced/technical-reference/framework/dao/DAOFactory.md
@@ -0,0 +1,123 @@
+## Description
+
+This contract is used to create a DAO.
+
+## Implementation
+
+### public variable daoBase
+
+The DAO base contract, to be used for creating new `DAO`s via `createERC1967Proxy` function.
+
+```solidity
+address daoBase
+```
+
+### public variable daoRegistry
+
+The DAO registry listing the `DAO` contracts created via this contract.
+
+```solidity
+contract DAORegistry daoRegistry
+```
+
+### public variable pluginSetupProcessor
+
+The plugin setup processor for installing plugins on the newly created `DAO`s.
+
+```solidity
+contract PluginSetupProcessor pluginSetupProcessor
+```
+
+### public struct DAOSettings
+
+```solidity
+struct DAOSettings {
+  address trustedForwarder;
+  string daoURI;
+  string subdomain;
+  bytes metadata;
+}
+```
+
+### public struct PluginSettings
+
+```solidity
+struct PluginSettings {
+  struct PluginSetupRef pluginSetupRef;
+  bytes data;
+}
+```
+
+### error NoPluginProvided
+
+Thrown if `PluginSettings` array is empty, and no plugin is provided.
+
+```solidity
+error NoPluginProvided()
+```
+
+### public function constructor
+
+The constructor setting the registry and plugin setup processor and creating the base contracts for the factory.
+
+```solidity
+constructor(contract DAORegistry _registry, contract PluginSetupProcessor _pluginSetupProcessor) public
+```
+
+| Input                   | Type                            | Description                                       |
+| :---------------------- | ------------------------------- | ------------------------------------------------- |
+| `_registry`             | `contract DAORegistry`          | The DAO registry to register the DAO by its name. |
+| `_pluginSetupProcessor` | `contract PluginSetupProcessor` | The address of PluginSetupProcessor.              |
+
+### public function supportsInterface
+
+Checks if this or the parent contract supports an interface by its ID.
+
+```solidity
+function supportsInterface(bytes4 _interfaceId) public view virtual returns (bool)
+```
+
+| Input          | Type     | Description                                   |
+| :------------- | -------- | --------------------------------------------- |
+| `_interfaceId` | `bytes4` | The ID of the interface.                      |
+| **Output**     |          |
+| `0`            | `bool`   | Returns `true` if the interface is supported. |
+
+### external function createDao
+
+Creates a new DAO, registers it on the DAO registry, and installs a list of plugins via the plugin setup processor.
+
+```solidity
+function createDao(struct DAOFactory.DAOSettings _daoSettings, struct DAOFactory.PluginSettings[] _pluginSettings) external returns (contract DAO createdDao)
+```
+
+| Input             | Type                                 | Description                                                                                                   |
+| :---------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
+| `_daoSettings`    | `struct DAOFactory.DAOSettings`      | The DAO settings to be set during the DAO initialization.                                                     |
+| `_pluginSettings` | `struct DAOFactory.PluginSettings[]` | The array containing references to plugins and their settings to be installed after the DAO has been created. |
+
+### internal function \_createDAO
+
+Deploys a new DAO `ERC1967` proxy, and initialize it with this contract as the intial owner.
+
+```solidity
+function _createDAO(struct DAOFactory.DAOSettings _daoSettings) internal returns (contract DAO dao)
+```
+
+| Input          | Type                            | Description                                                          |
+| :------------- | ------------------------------- | -------------------------------------------------------------------- |
+| `_daoSettings` | `struct DAOFactory.DAOSettings` | The trusted forwarder, name and metadata hash of the DAO it creates. |
+
+### internal function \_setDAOPermissions
+
+Sets the required permissions for the new DAO.
+
+```solidity
+function _setDAOPermissions(contract DAO _dao) internal
+```
+
+| Input  | Type           | Description                    |
+| :----- | -------------- | ------------------------------ |
+| `_dao` | `contract DAO` | The DAO instance just created. |
+
+<!--CONTRACT_END-->
diff --git a/docs/advanced/technical-reference/framework/dao/DAORegistry.md b/docs/advanced/technical-reference/framework/dao/DAORegistry.md
@@ -0,0 +1,82 @@
+## Description
+
+This contract provides the possibility to register a DAO.
+
+## Implementation
+
+### public variable REGISTER_DAO_PERMISSION_ID
+
+The ID of the permission required to call the `register` function.
+
+```solidity
+bytes32 REGISTER_DAO_PERMISSION_ID
+```
+
+### public variable subdomainRegistrar
+
+The ENS subdomain registrar registering the DAO subdomains.
+
+```solidity
+contract ENSSubdomainRegistrar subdomainRegistrar
+```
+
+### error InvalidDaoSubdomain
+
+Thrown if the DAO subdomain doesn't match the regex `[0-9a-z\-]`
+
+```solidity
+error InvalidDaoSubdomain(string subdomain)
+```
+
+### event DAORegistered
+
+Emitted when a new DAO is registered.
+
+```solidity
+event DAORegistered(address dao, address creator, string subdomain)
+```
+
+| Input       | Type      | Description                      |
+| :---------- | --------- | -------------------------------- |
+| `dao`       | `address` | The address of the DAO contract. |
+| `creator`   | `address` | The address of the creator.      |
+| `subdomain` | `string`  | The DAO subdomain.               |
+
+### public function constructor
+
+```solidity
+constructor() public
+```
+
+_Used to disallow initializing the implementation contract by an attacker for extra safety._
+
+### external function initialize
+
+Initializes the contract.
+
+```solidity
+function initialize(contract IDAO _managingDao, contract ENSSubdomainRegistrar _subdomainRegistrar) external
+```
+
+| Input                 | Type                             | Description                                                           |
+| :-------------------- | -------------------------------- | --------------------------------------------------------------------- |
+| `_managingDao`        | `contract IDAO`                  | the managing DAO address.                                             |
+| `_subdomainRegistrar` | `contract ENSSubdomainRegistrar` | The `ENSSubdomainRegistrar` where `ENS` subdomain will be registered. |
+
+### external function register
+
+Registers a DAO by its address. If a non-empty subdomain name is provided that is not taken already, the DAO becomes the owner of the ENS name.
+
+```solidity
+function register(contract IDAO dao, address creator, string subdomain) external
+```
+
+| Input       | Type            | Description                      |
+| :---------- | --------------- | -------------------------------- |
+| `dao`       | `contract IDAO` | The address of the DAO contract. |
+| `creator`   | `address`       | The address of the creator.      |
+| `subdomain` | `string`        | The DAO subdomain.               |
+
+_A subdomain is unique within the Aragon DAO framework and can get stored here._
+
+<!--CONTRACT_END-->
diff --git a/docs/advanced/technical-reference/framework/plugin/repo/IPluginRepo.md b/docs/advanced/technical-reference/framework/plugin/repo/IPluginRepo.md
@@ -0,0 +1,35 @@
+## Description
+
+The interface required for a plugin repository.
+
+## Implementation
+
+### external function updateReleaseMetadata
+
+Updates the metadata for release with content `@fromHex(_releaseMetadata)`.
+
+```solidity
+function updateReleaseMetadata(uint8 _release, bytes _releaseMetadata) external
+```
+
+| Input              | Type    | Description               |
+| :----------------- | ------- | ------------------------- |
+| `_release`         | `uint8` | The release number.       |
+| `_releaseMetadata` | `bytes` | The release metadata URI. |
+
+### external function createVersion
+
+Creates a new plugin version as the latest build for an existing release number or the first build for a new release number for the provided `PluginSetup` contract address and metadata.
+
+```solidity
+function createVersion(uint8 _release, address _pluginSetupAddress, bytes _buildMetadata, bytes _releaseMetadata) external
+```
+
+| Input                 | Type      | Description                               |
+| :-------------------- | --------- | ----------------------------------------- |
+| `_release`            | `uint8`   | The release number.                       |
+| `_pluginSetupAddress` | `address` | The address of the plugin setup contract. |
+| `_buildMetadata`      | `bytes`   | The build metadata URI.                   |
+| `_releaseMetadata`    | `bytes`   | The release metadata URI.                 |
+
+<!--CONTRACT_END-->