Merge pull request #184 from aragon/f/add-dao-docs

chore: Add DAO Docs to new docuemntation structure

docs/advanced/dao/00-introduction.md

@@ -0,0 +1,87 @@
+---
+title: Introduction
+sidebar_label: Introduction
+sidebar_position: 0
+---
+
+## The DAO Contract: The Identity and Basis of Your Organization
+
+In this section, you will learn about the core functionality of every Aragon OSx DAO.
+
+The `DAO` contract is the identity and basis of your
+organization. It is the address carrying the DAO’s ENS name, metadata,
+and holding the funds. Furthermore, it has **six base functionalities** being commonly found in other DAO frameworks in the ecosystem.
+
+### 1. Execution of Arbitrary Actions
+
+The most important and basic functionality of your DAO is the **execution of arbitrary actions**,
+which allows you to execute the DAO's own functions as well as
+interacting with the rest of the world, i.e., calling methods in other
+contracts and sending assets to other addresses.
+
+:::note
+
+Typically, actions are scheduled in a proposal in a governance [plugin installed to your DAO](/docs/advanced/plugin/index.md).
+:::
+
+Multiple `Action` structs can be put into one `Action[]` array and executed in a single transaction via the `execute` function. To learn more about actions and advanced features of the DAO executor, visit the [A Deep Dive Into Actions](/1.3.0/osx/how-it-works/core/dao/actions) section.
+
+### 2. Asset Management
+
+The DAO provides basic **asset management** functionality to deposit, withdraw, and keep track of
+
+- native
+- [ERC-20 (Token Standard)](https://eips.ethereum.org/EIPS/eip-20),
+- [ERC-721 (NFT Standard)](https://eips.ethereum.org/EIPS/eip-721), and
+- [ERC-1155 (Multi Token Standard)](https://eips.ethereum.org/EIPS/eip-1155)
+
+tokens in the treasury.
+In the future, more advanced asset management and finance functionality can be added to your DAO in the form of [plugins](/docs/advanced/plugin/index.md).
+
+### 3. Upgradeability
+
+Your DAO contract has the ability to be upgraded to a newer version (see [Upgrade your DAO](/1.3.0/osx/how-to-guides/dao/protocol-upgrades))
+if a new version of Aragon OSx is released in the future. These
+upgrades allow your DAO to smoothly transition to a new protocol version
+unlocking new features.
+
+### 4. Callback Handling
+
+To interact with the DAO, external contracts might require certain callback functions to be present.
+Examples are the `onERC721Received` and `onERC1155Received` / `onERC1155BatchReceived` functions required by the [ERC-721 (NFT Standard)](https://eips.ethereum.org/EIPS/eip-721) and [ERC-1155 (Multi Token Standard)](https://eips.ethereum.org/EIPS/eip-1155) tokens.
+Our `CallbackHandler` allows to register the required callback responses dynamically so that the DAO contract does not need to be upgraded.
+
+### 5. Signature Validation
+
+Currently,
+externally owned accounts (EOAs) can sign messages with their
+associated private keys, but contracts cannot.
+An exemplary use case is a decentralized exchange with an off-chain
+order book, where buy/sell orders are signed messages.
+To accept such a request, both, the external service provider and caller
+need to follow a standard with which the signed message of the caller
+can be validated.
+
+By supporting the [ERC-1271](https://eips.ethereum.org/EIPS/eip-1271) standard, your DAO can validate signatures via its `isValidSignature` function that forwards the call to a signature validator contract.
+
+### 6. Permission Management
+
+Lastly,
+it is essential that only the right entities (e.g., the DAO itself or
+trusted addresses) have permission to use the above-mentioned
+functionalities. This is why Aragon OSx DAOs contain a flexible and
+battle-tested **permission manager** being able to assign
+permissions for the above functionalities to specific addresses.
+Although possible, the permissions to execute arbitrary actions or
+upgrade the DAO should not be given to EOAs as this poses a security
+risk to the organization if the account is compromised or acts
+adversarial. Instead, the permissions for the above-mentioned
+functionalities are better restricted to the `DAO` contract itself and triggered through governance [plugins](/docs/advanced/plugin/index.md) that you can install on your DAO.
+
+To learn more, visit the [Permission Manager](/1.3.0/osx/how-it-works/core/permissions/) section.
+
+<!-- todo update links when all the documentation is migrated
+     todo  - A Deep Dive Into Actions link
+     todo  - Upgrade your DAO link
+     todo  - Permission Manager link
+ -->

docs/advanced/dao/01-creation.md

@@ -0,0 +1,103 @@
+---
+title: Creation
+sidebar_label: Creation
+sidebar_position: 1
+---
+
+# Dao Creation
+
+Two framework contracts manage the `DAO` contract creation process:
+
+- The [`DAOFactory`](docs/osx/reference-guide/framework/dao/DAOFactory).
+- The [`DAORegistry`](docs/osx/reference-guide/framework/dao/DAORegistry).
+
+The `DAOFactory` is the contract that creates and sets up a `DAO` for you. The `DAORegistry` is used by the `DAOFactory` to register the DAOs that are created. Plugins are installed in the DAO by the `PluginSetupProcessor`.
+
+![Creation Schema](/optimized-svg/advanced/dao/aragon-osx-dao-creation.drawio.svg)
+
+## `DAOFactory`
+
+The `DAOFactory` creates and sets up a `DAO` for you in four steps with the `createDao` function. The function requires the `DAOSettings` including:
+
+- The trusted forwarder address for future [ERC-2771 (Meta Transaction)](https://eips.ethereum.org/EIPS/eip-2771) compatibility that is set to `address(0)` for now
+- The ENS name (to be registered under the `dao.eth` domain)
+- The [ERC-4824 (Common Interfaces for DAOs)](https://eips.ethereum.org/EIPS/eip-4824) `daoURI`
+- Optional metadata
+
+The DAO also requires an array of `PluginSettings` containing `PluginSetup` and its respective setup data for the plugins to be installed in the DAO.
+
+When the `createDao` function is called in the `DAOFactory` this triggers a four step process for creating a DAO:
+
+1. Creates a new DAO by deploying an [ERC-1967](https://eips.ethereum.org/EIPS/eip-1967) proxy pointing to the latest Aragon OSx `DAO` implementation and becomes the initial owner.
+2. Registers the new contract in the [`DAORegistry`](/docs/advanced/dao/01-creation.md#daoregistry).
+3. Installs the plugins using the `PluginSetupProcessor` (see also the section about [the plugin setup process](/docs/advanced/psp/index.md)).
+4. Sets the [native permissions](/docs/advanced/dao/02-permissions.md) of the `DAO` and revokes its own ownership.
+
+### Plugins
+
+When calling `createDao` an array of `PluginSettings` are requested. A DAO cannot be created without at least one plugin. The DAO contract works as a permission manager system but it is agnostic to the type of governance that you want to use to manage the DAO. We currently provide two plugins that can be used for governing your DAO:
+
+<!--  todo add link when respective documentation is added  -->
+
+- `Multisig`
+- `TokenVoting`
+
+If none of this options meet your requirements you can also build your own governance plugin, check our tutorial on ["How to build a plugin?"](/1.3.0/osx/how-to-guides/plugin-development/) to get started.
+
+## `DAORegistry`
+
+The `DAORegistry` is used by the `DAOFactory` and contains the `register` function
+
+@aragon/framework/dao/DAORegistry.sol
+
+```solidity
+function register(
+  IDAO dao,
+  address creator,
+  string calldata subdomain
+) external auth(REGISTER_DAO_PERMISSION_ID);
+
+```
+
+the `register` function requires the `REGISTER_DAO_PERMISSION_ID`, this permission currently held only by the `DAOFactory`. This implies that the only way of creating DAOs that get registered in our `DAORegistry` is via the `createDao` function in the `DaoFactory` contract.
+
+If the requested ENS `subdomain` name [is valid](/docs/advanced/ens.md) and not taken, the `DAORegistry` registers the subdomain and adds the `DAO` contract address to the `DAORegistry`.
+If the `subdomain` parameter is non-empty (not `""`) and still available, the ENS name will be registered. If the registration was successful, an event a `DAORegistered` event is emitted. This event contains the DAO address, the creator address and the subdomain.
+
+In case you want to verify that you DAO got registered in the `DAORegistry` you can call `entries(address)` and it will return `true` if the DAO is registered
+
+For more details visit the [`DAORegistry` reference guide entry](/docs/advanced/technical-reference/framework/dao/DAORegistry.md).
+
+## Events
+
+When creating a DAO there is two main events that you'll be looking for:
+
+- `DAORegistered`
+- `InstallationApplied`
+
+When the `createDao` function is called in the `DAORegistry` emits the `DaoRegistered` event. This event contains the DAO address, the creator address and the subdomain.
+
+```solidity
+event DAORegistered(
+  address indexed dao,
+  address indexed creator,
+  string subdomain
+);
+```
+
+The `InstallationApplied` event is emitted when the `PluginSetupProcessor` finishes installing the plugins in the DAO.
+
+```solidity
+event InstallationApplied(
+  address indexed dao,
+  address indexed plugin,
+  bytes32 preparedSetupId,
+  bytes32 appliedSetupId
+);
+```
+
+There are a set of events emitted by the `DAO` contract itself, you can find more information about them in the [`DAO` reference guide entry](/docs/advanced/technical-reference/core/dao/DAO.md).
+
+<!-- todo update links when all the documentation is migrated 
+     todo  - How to build a plugin? link
+ -->

docs/advanced/dao/02-permissions.md

@@ -0,0 +1,20 @@
+---
+title: Permissions
+sidebar_label: Permissions
+sidebar_position: 2
+---
+
+# Dao Permissions
+
+The following functions in the DAO are permissioned:
+
+| Functions                               | Permission Identifier                      | Description                                                                                                     |
+| --------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `grant`, `grantWithCondition`, `revoke` | `ROOT_PERMISSION_ID`                       | Required to manage permissions of the DAO and associated plugins.                                               |
+| `execute`                               | `EXECUTE_PERMISSION_ID`                    | Required to execute arbitrary actions.                                                                          |
+| `_authorizeUpgrade`                     | `UPGRADE_DAO_PERMISSION_ID`                | Required to upgrade the DAO (via the [UUPS](https://eips.ethereum.org/EIPS/eip-1822)).                          |
+| `setMetadata`                           | `SET_METADATA_PERMISSION_ID`               | Required to set the DAO’s metadata and [DAOstar.one DAO URI](https://eips.ethereum.org/EIPS/eip-4824).          |
+| `setTrustedForwarder`                   | `SET_TRUSTED_FORWARDER_PERMISSION_ID`      | Required to set the DAO’s trusted forwarder for meta transactions.                                              |
+| `registerStandardCallback`              | `REGISTER_STANDARD_CALLBACK_PERMISSION_ID` | Required to register a standard callback for an [ERC-165](https://eips.ethereum.org/EIPS/eip-165) interface ID. |
+
+Plugins installed on the DAO might introduce other permissions and associated permission identifiers, these additional permissions are specified by the plugin itself.