Edit Permissions doc to have a more straightforward example [skip ci]

Author: gichiba

docs/_Docs_Extensions.md

@@ -4,9 +4,9 @@ section: Docs
 order: 6
 ---
 
-`glider` provides the option of "extensions" to the basic functionality of a colony through the use of _extensions_.
+`glider` provides the option of expanding the basic functionality of a colony through the use of _extensions_.
 
-Extensions are other smart contracts that have been given permissions to interact with a colony in a specified domain. Extensions can be used for many purposes, such as bundling transactions, automating certain actions, or something else entirely. Their implementations are intentionally disconected from the colonyNetwork codebase (stored in the [/contracts/extensions](https://github.com/JoinColony/colonyNetwork/tree/develop/contracts/extensions) folder in the network) to allow for greater design flexibility unbounded by the network protocol.
+Extensions are other smart contracts that have been given permissions to interact with a colony in a specified domain. Extensions can be used for many purposes, such as bundling transactions, automating certain actions, or something else entirely. Their implementations are intentionally disconnected from the colonyNetwork codebase (stored in the [/contracts/extensions](https://github.com/JoinColony/colonyNetwork/tree/develop/contracts/extensions) folder in the network) to allow for greater design flexibility unbounded by the network protocol.
 
 Currently there are two extensions 'officially' supported, but more may be added in the future. These extensions are written with dapp support in mind, and emit events to inform a user interface whether a colony has an extension enabled or not. Adding and removing an extension from a colony is restricted to those with `Root` permissions on the colony.
 
@@ -47,4 +47,4 @@ In earlier versions of the colonyNetwork, only two roles existed for permissione
 
 The `OldRoles` extension bundles the roles in the `glider` release together into super-roles that have the same abilities as the original "Founder" (root) and "Admin" (funding, administration, architecture) roles.
 
-Extension requires `Root` role to function.
+Extension requires `Root` role to function.

docs/_Docs_Permissions.md

@@ -6,7 +6,7 @@ order: 4
 
 In the full implementation of the Colony protocol, decision making will be determined by the reputation score of an account. Actions that are currently permissioned, such as moving shared funds and creating a task, will be allowed proportionate to an account's reputation score. This functionality is planned for later releases.
 
-In the current `glider` release, network state changes are authorised by dedicated "authority" contracts e.g. `ColonyAuthority.sol`. These are based on the `DSRoles` implementation from [dappsys library](https://github.com/dapphub/dappsys-monolithic). Functions decorated with the `auth` and `authDomain` modifiers will perform an authorization check via the authority contracts before granting access. In future releases, this pattern will also allow us to switch to a reputation-mediated authority in colonies.
+In the current `glider` release, network state changes are authorized by dedicated "authority" contracts e.g. `ColonyAuthority.sol`. These are based on the `DSRoles` implementation from [dappsys](https://github.com/dapphub/dappsys-monolithic). Functions decorated with the `auth` and `authDomain` modifiers will perform an authorization check via the authority contracts before granting access. In future releases, this pattern will also allow us to switch to a reputation-mediated authority in colonies.
 
 Roles are defined within `ColonyRole` struct and grant permission to call certain functions within a specific domain of the colony. These are initialized in `ColonyAuthority.sol`. An account may be given one or more of the available pre-defined roles:
 
@@ -20,10 +20,12 @@ Note: Currently, the existing `auth` modifier is preserved and checks for permis
 
 Note: Currently `Arbitration` role grants permission for no functions. It is a placeholder for the dispute resolution system, to be implemented in later releases.
 
-For example, within the 'logistics' domain, any address with the `Administration` role may call the `addPayment` function to create a new payment. But to add funding for the payment, an address with the `Funding` role must call `moveFundsBetweenPots` for the payment. These two functions can be called by the same address (even in the same transaction), provided that the address has both `Administration` and `Funding` permissions.
+## Domain permission transitivity
+*Note: Domains are currently restricted to one level below the root domain. This restriction will be removed after release.*
 
-**Domain permission inheritance**
-Domain permissions flow down in the domain tree. As an example of how domain permissions propagate, consider this tree of domains in a colony (using domainIds as identifiers):
+Domain permissions extend from the root domain. Permissions held in a domain are held in all child sub-domains, but not in parent domains.
+
+As an example, consider this tree of domains in a colony (using domainIds as identifiers):
 
 ```
       1
@@ -33,42 +35,45 @@ Domain permissions flow down in the domain tree. As an example of how domain per
 3   5
 ```
 
-If you have funding permission in `3`, and funding permission in `6`, you shouldn't be able to move funds from `3` to `6`, because that would be taking them out of `2`, which you don't have the permission for. If you have funding permission in `1`, however, you should be able to move from `3` to `6`, because that's all under 'one roof'.
+Authority in domain `2` to call a permissioned function is valid in domains `3` and `5`, but not `6`. Authority in domain `1` to call a permissioned function is valid in all subdomains.
 
-**Using permissioned functions**
+## Using permissioned functions
+Permissioned functions check two arguments, which are by convention the first and second ones expected in all permissioned functions:
 
-In order to provide the necessary inputs to the authorisation logic, we have added two arguments to every permissioned function, which by convention are the first two arguments. The first is the permission domain id (`_permissionDomainId`), and the second is an index (`_childSkillIndex`) telling us where in the child array of the permission domain we can find the "domain of action". The "domain of action" itself is the domain in which state is being changed.
+`_permissionDomainId`: The domain that gives the caller the authority to execute an action
+`_childSkillIndex`: an index that specifies where to find the domain in which the action occurs.
 
-For example is a colony with the domain tree below,
+New domains are given a unique skillId upon creation, so a colony with the following domain structure
 ```
       1
    /  |  \
   2   4   6
  / \  
 3   5
 ```
-which has representative local skills Id as follows:
+might have local skillIds assigned as:
 ```
        142
     /   |   \
   147  254  696
   / \  
 159  307
 ```
-Skill `142` has the following `children`: `[147, 159, 254, 307, 696]`
 
-if we want to grant user `USER2` permission to create tasks and payments in domain `5`, and we ourselves are user `USER1` have root permissions. We need to give them permissions in that specific domain as follows:
+In this example,
+Skill `142` has children: `[147, 159, 254, 307, 696]`
+Skill `147` has children: `[159, 307]`
+Skill `254` has children: `[]`
+
+If a user with "Admininstration" authority in domain `2` wants to finalize a payment in domain `5`, they would call:
 
 ```
-colony.setAdministrationRole(1, 3, USER2, 5, true, { from: USER1 });
+colony.finalizePayment(2, 1, _paymentId);
 ```
 
-Essentially the two additional parameters are used to perform the following checks:
-
-1) Whether `USER1` has the permission to assign a new `Administrator` in `_permissionDomainId`, which is domain `1` in this case.
-
-2) Whether the domain of action, if this case domain `5`, is actually a child of the permission domain `1`. This is done using `_childSkillIndex`, here passed as `3` meaning the permission domain (`1`) `skill.children` array's third member should match domain `5` skill.
+The `authDomain` modifier performs the following checks:
 
-And for the architecture permission, checks to see that the domain is strictly a child of the permission domain (i.e. not the permission domain itself).
+1) Whether `msg.sender` has the "Administration" or "Root" permission in domain `2`
+2) Whether the domain of action (in this case domain `5`) is indeed a child of the permission domain `2`, by checking that the second item in the `childSkillIndex` matches the local skill associated with the domain, whatever that may be.   
 
-Note: Within `ColonyAuthority.sol` you will see this role implemented as both`Architecture` and `ArchitectureSubdomain` roles. This is in order to prohibit an architect from modifying the domain in which the role was given (which would allow them to, for example, remove their co-architect's role). Architects may alter permissions in sub-domains only.
+Note: Functions authorized by the "Architecture" role check to see that the domain is strictly a child of the permission domain exclusively (not the permission domain itself). Within `ColonyAuthority.sol` you will see this role implemented as both`Architecture` and `ArchitectureSubdomain` roles. This is in order to prohibit an architect from modifying the domain in which the role was given (which would allow them to, for example, remove their co-architect's role). Architects may alter permissions in sub-domains only.