poanetwork
/
quorum
mirror of https://github.com/poanetwork/quorum.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Minor styling fixes for documentation including code highlights and relative links

This commit is contained in:
namtruong 2019-05-15 13:17:02 +01:00
parent 479a047868
commit 1079e3a23f
4 changed files with 157 additions and 141 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
docs/Permissioning/Permissioning apis.md
View File

@ -3,7 +3,7 @@
* Input: None
* Output: Returns the list of all organizations and their status
* Example:
```
```javascript
> quorumPermission.orgList
[{
fullOrgId: "INITORG",
@ -20,7 +20,7 @@ Please click [here](#organization-status-types) for the complete list of organiz
* Input: None
* Output: Returns the list of all accounts across organizations
* Example:
```
```javascript
> quorumPermission.acctList
[{
acctId: "0xed9d02e382b34818e88b88a309c7fe71e65f419d",
@ -41,7 +41,7 @@ Please click [here](#account-status-types) for the complete list of account stat
* Input: None
* Output: Returns the list of all nodes across organizations
* Example:
```
```javascript
> quorumPermission.nodeList
[{
orgId: "INITORG",
@ -67,7 +67,7 @@ Please click [here](#node-status-types) for the complete list of node statuses.
* Input: None
* Output: Returns the list of all roles across organizations and their details
* Example:
```
```javascript
> quorumPermission.roleList
[{
access: 3,
@ -82,10 +82,11 @@ Please click [here](#account-access-types) for the complete list of different va
### quorumPermission.getOrgDetails
This returns the list of accounts, nodes, roles, and sub organizations linked to an organization
* Input: organization id or sub organization id
* Output: list of all accounts, nodes, roles, and sub orgs
* Example:
```
```javascript
> quorumPermission.getOrgDetails("INITORG")
{
acctList: [{
@ -131,10 +132,11 @@ This returns the list of accounts, nodes, roles, and sub organizations linked to
```
### quorumPermission.addOrg
This api can be executed by a network admin account (`from:` in transactions args) only for proposing a new organization into the network
* Input: Unique alphanumeric organization id, enode id, account id (org admin account)
* Output: Status of the operation
* Example:
```
```javascript
> quorumPermission.addOrg("ABC", "enode://3d9ca5956b38557aba991e31cf510d4df641dce9cc26bfeb7de082f0c07abb6ede3a58410c8f249dabeecee4ad3979929ac4c7c496ad20b8cfdd061b7401b4f5@127.0.0.1:21003?discport=0&raftport=50404", "0x0638e1574728b6d862dd5d3a3e0942c3be47d996", {from: eth.accounts[0]})
{
msg: "Action completed successfully",
@ -142,7 +144,7 @@ This api can be executed by a network admin account (`from:` in transactions arg
}
```
If there are any pending items for approval, proposal of any new organization will fail. Also the enode id and accounts can be linked to one organization only.
```
```javascript
> quorumPermission.addOrg("ABC", "enode://3d9ca5956b38557aba991e31cf510d4df641dce9cc26bfeb7de082f0c07abb6ede3a58410c8f249dabeecee4ad3979929ac4c7c496ad20b8cfdd061b7401b4f5@127.0.0.1:21003?discport=0&raftport=50404", "0x0638e1574728b6d862dd5d3a3e0942c3be47d996", {from: eth.accounts[0]})
{
msg: "Pending approvals for the organization. Approve first",
@ -163,10 +165,11 @@ If there are any pending items for approval, proposal of any new organization wi
### quorumPermission.approveOrg
This api can be executed by a network admin account (`from:` in transactions args) only for approving a proposed organization into the network.
* Input: Unique organization id, enode id, account id (org admin account)
* Output: Status of the operation
* Example:
```
```javascript
quorumPermission.approveOrg("ABC", "enode://3d9ca5956b38557aba991e31cf510d4df641dce9cc26bfeb7de082f0c07abb6ede3a58410c8f249dabeecee4ad3979929ac4c7c496ad20b8cfdd061b7401b4f5@127.0.0.1:21003?discport=0&raftport=50404", "0x0638e1574728b6d862dd5d3a3e0942c3be47d996", {from: eth.accounts[0]})
{
msg: "Action completed successfully",
@ -179,7 +182,7 @@ This api can only be executed by a network admin account and is used for tempora
* Input: organization id, action (1 for suspending the organization and 2 for activating a suspended organization)
* Output: Status of the operation
* Example:
```
```javascript
> quorumPermission.updateOrgStatus("ABC", 1, {from:eth.accounts[0]})
{
msg: "Action completed successfully",
@ -188,10 +191,11 @@ This api can only be executed by a network admin account and is used for tempora
```
### quorumPermission.approveOrgStatus
This api can only be executed by a network admin account and is used for approving the org status change proposal. Once majority approval is received from network admins, the org status is updated.
* Input: organization id, action (1 for suspending the organization and 2 for activating a suspended organization)
* Output: Status of the operation
* Example:
```
```javascript
> quorumPermission.approveOrgStatus("ABC", 1, {from: eth.accounts[0]})
{
msg: "Action completed successfully",
@ -202,10 +206,11 @@ When an organization is in suspended status, no transactions or contract deploy
### quorumPermission.addSubOrg
This api can be executed by a organization admin account to create a sub organization under the master org.
* Input: parent org id, alphanumeric sub organization id, enode id (not mandatory and can be null), account id (not mandatory and can be 0x0)
* Output: Status of the operation
* Example:
```
```javascript
> quorumPermission.addSubOrg("ABC", "SUB1", "", "0x0000000000000000000000000000000000000000", {from: eth.accounts[0]})
{
@ -214,7 +219,7 @@ This api can be executed by a organization admin account to create a sub organiz
}
```
It should be noted that, parent org id should contain the complete org hierarchy from master org id to the immediate parent. The org hierarchy is separated by `.`. For example, if master org `ABC` has a sub organization `SUB1`, then while creating the sub organization at `SUB1` level, the parent org should be given as `ABC.SUB1`. Please see the examples below:
```
```javascript
> quorumPermission.addSubOrg("ABC.SUB1", "SUB2","", "0x0000000000000000000000000000000000000000", {from: eth.accounts[0]})
{
msg: "Action completed successfully",
@ -232,7 +237,7 @@ This api can be executed by an organization admin account to create a new role f
* Input: organization id or sub organization id, alphanumeric role id, account access ([access values](#account-access-types))(, isVoter, isAdminRole
* Output: Status of the operation
* Example:
```
```javascript
> quorumPermission.addNewRole("ABC", "TRANSACT", 1, false, false,{from: eth.accounts[0]})
{
msg: "Action completed successfully",
@ -250,7 +255,7 @@ This api can be executed by an organization admin account to create a new role f
* Input: organization id or sub organization id, role id
* Output: Status of the operation
* Example:
```
```javascript
> quorumPermission.removeRole("ABC.SUB1.SUB2.SUB3", "TRANSACT", {from: eth.accounts[1]})
{
msg: "Action completed successfully",
@ -263,7 +268,7 @@ This api can be executed by an organization admin to add an account to an organi
* Input: Account id, organization id or sub organization id, role to be assigned
* Output: Status of the operation
* Example:
```
```javascript
> quorumPermission.addAccountToOrg("0xf017976fdf1521de2e108e63b423380307f501f8", "ABC", "TRANSACT", {from: eth.accounts[1]})
{
msg: "Action completed successfully",
@ -271,7 +276,7 @@ This api can be executed by an organization admin to add an account to an organi
}
```
The account can at best be linked to a single organization or sub organization and cannot belong to multiple organizations or sub organizations
```
```javascript
> quorumPermission.assignAccountRole("0xf017976fdf1521de2e108e63b423380307f501f8", "ABC.SUB1", "TRANSACT", {from: eth.accounts[1]})
{
msg: "Account already in use in another organization",
@ -284,7 +289,7 @@ This api can be executed by an organization admin account to assign a role to an
* Input: Account id, organization id or sub organization id, role to be assigned
* Output: Status of the operation
* Example:
```
```javascript
> quorumPermission.changeAccountRole("0xf017976fdf1521de2e108e63b423380307f501f8", "ABC", "TRANSACT", {from: eth.accounts[1]})
{
msg: "Action completed successfully",
@ -298,7 +303,7 @@ This api can be executed by an organization admin account to update the account
* Input: organization id or sub organization id, Account id, action (1 for suspending the account, 2 for activating a suspended account, 3 for blacklisting the account)
* Output: Status of the operation
* Example:
```
```javascript
> quorumPermission.updateAccountStatus("ABC", "0xf017976fdf1521de2e108e63b423380307f501f8", 1, {from: eth.accounts[1]})
{
msg: "Action completed successfully",
@ -313,7 +318,7 @@ This api can be executed by the network admin to add a new account as network ad
* Input: organization id to which the account belongs, account id, role id (it can be either org admin role or network admin role)
* Output: Status of the operation
* Example:
```
```javascript
> quorumPermission.assignAdminRole("ABC", "0xf017976fdf1521de2e108e63b423380307f501f8", "NWADMIN", {from: eth.accounts[0]})
{
msg: "Action completed successfully",
@ -327,7 +332,7 @@ This api can be executed by the network admin to approve the organization admin
* Input: organization id to which the account belongs, account id
* Output: Status of the operation
* Example:
```
```javascript
> quorumPermission.approveAdminRole("ABC", "0xf017976fdf1521de2e108e63b423380307f501f8", {from: eth.accounts[0]})
{
@ -342,7 +347,7 @@ This api can be executed by the organization admin account to add a node to the
* Input: organization id or sub organization id, enode id
* Output: Status of the operation
* Example:
```
```javascript
> quorumPermission.addNode("ABC.SUB1.SUB2.SUB3", "enode://239c1f044a2b03b6c4713109af036b775c5418fe4ca63b04b1ce00124af00ddab7cc088fc46020cdc783b6207efe624551be4c06a994993d8d70f684688fb7cf@127.0.0.1:21006?discport=0&raftport=50407", {from: eth.accounts[1]})
{
msg: "Action completed successfully",
@ -357,7 +362,7 @@ This api can be executed by the organization admin account to update the status
* Input: organization id or sub organization id, enode id, action (1 for deactivating the node, 2 for activating a deactivated node and 3 for blacklisting a node)
* Output: Status of the operation
* Example:
```
```javascript
> quorumPermission.updateNodeStatus("ABC.SUB1.SUB2.SUB3", "enode://239c1f044a2b03b6c4713109af036b775c5418fe4ca63b04b1ce00124af00ddab7cc088fc46020cdc783b6207efe624551be4c06a994993d8d70f684688fb7cf@127.0.0.1:21006?discport=0&raftport=50407",3, {from: eth.accounts[1]})
{
msg: "Action completed successfully",

215
docs/Permissioning/Usage.md
View File

@ -1,4 +1,5 @@
This section describes the usage of permission model for creation of a network, initial set up and management of network. The network management activities can be broadly categorized into:
* [Initial network set up](#initial-network-set-up)
* [Proposing a new organization into the network](#proposing-a-new-organization-into-the-network)
* [Organization admin managing the organization level permissions](#organization-admin-managing-the-organization-level-permissions)
@ -7,7 +8,8 @@ This section describes the usage of permission model for creation of a network,
* [Assigning admin privileges at organization and network level](#assigning-admin-privileges-at-organization-and-network-level)
### Initial network set up
Please refer to [set up](./setup.md). For an existing network running in older version of Quorum,
Please refer to [set up](../setup). For an existing network running in older version of Quorum,
* Deploy the contracts
* Execute the `init` method of `PermissionsUpgradable.sol` from the custodian account
* Upgrade Quorum to latest version
@ -15,6 +17,7 @@ Please refer to [set up](./setup.md). For an existing network running in older v
* Bring `geth` up in `--permissioned` mode.
For new network starting in the latest version of Quorum
* Bring up the initial set of nodes
* Deploy the contracts
* Execute the `init` method of `PermissionsUpgradable.sol` from the custodian account
@ -23,12 +26,13 @@ For new network starting in the latest version of Quorum
* Bring `geth` up in `--permissioned` mode.
As part of network initialization,
* A network admin organization having a name as given for `nwAdminOrg` in `permission-config.json` is created. All nodes which are part of `static-nodes.json` are assigned to this organization.
* A network admin role having a name as given for `nwAdminRole` in the config file is created.
* All accounts given in the `accounts` array of the config file are assigned the network admin role. These accounts will have ability to propose and approve new organizations into the network
Assuming that the network was brought with the `permission-config.json` as given in the [set up](./setup.md) and assuming the network was brought up with a `static-nodes.json` file as given below
```$xslt
Assuming that the network was brought with the `permission-config.json` as given in the [set up](../setup) and assuming the network was brought up with a `static-nodes.json` file as given below
```json
[
"enode://72c0572f7a2492cffb5efc3463ef350c68a0446402a123dacec9db5c378789205b525b3f5f623f7548379ab0e5957110bffcf43a6115e450890f97a9f65a681a@127.0.0.1:21000?discport=0",
"enode://7a1e3b5c6ad614086a4e5fb55b6fe0a7cf7a7ac92ac3a60e6033de29df14148e7a6a7b4461eb70639df9aa379bd77487937bea0a8da862142b12d326c7285742@127.0.0.1:21001?discport=0",
@ -37,7 +41,7 @@ Assuming that the network was brought with the `permission-config.json` as given
]
```
the network view once the network is up is as shown below:
```$xslt
```javascript
> quorumPermission.orgList
[{
fullOrgId: "ADMINORG",
@ -93,88 +97,92 @@ the network view once the network is up is as shown below:
```
### Proposing a new organization into the network
Once the network is up, the network admin accounts can then propose a new organization into the network. Majority approval from the network admin accounts is required before an organization is approved. The APIs for [proposing](./Permissioning%20apis.md#quorumpermissionaddorg) and [approving](./Permissioning%20apis.md#quorumpermissionapproveorg) an organization are documented in [permission APIs](./Permissioning%20apis.md)
Once the network is up, the network admin accounts can then propose a new organization into the network. Majority approval from the network admin accounts is required before an organization is approved. The APIs for [proposing](../Permissioning%20apis#quorumpermissionaddorg) and [approving](../Permissioning%20apis#quorumpermissionapproveorg) an organization are documented in [permission APIs](../Permissioning%20apis)
!!! example
A sample example to propose and approve an organization by name `ORG1` is as shown below:
```javascript
> quorumPermission.addOrg("ORG1", "enode://de9c2d5937e599930832cecc1df8cc90b50839bdf635c1a4e68e1dab2d001cd4a11c626e155078cc65958a72e2d72c1342a28909775edd99cc39470172cce0ac@127.0.0.1:21004?discport=0", "0x0638e1574728b6d862dd5d3a3e0942c3be47d996", {from: "0xed9d02e382b34818e88b88a309c7fe71e65f419d"})
{
msg: "Action completed successfully",
status: true
}
```
Once the org is proposed, it will be in `Proposed` state awaiting approval from other network admin accounts. The org status is as shown below:
```javascript
> quorumPermission.orgList[1]
{
fullOrgId: "ORG1",
level: 1,
orgId: "ORG1",
parentOrgId: "",
status: 1,
subOrgList: null,
ultimateParent: "ORG1"
}
```
The network admin accounts can then approve the proposed organizations and once the majority approval is achieved, the organization status is updated as `Approved`
```javascript
> quorumPermission.approveOrg("ORG1", "enode://de9c2d5937e599930832cecc1df8cc90b50839bdf635c1a4e68e1dab2d001cd4a11c626e155078cc65958a72e2d72c1342a28909775edd99cc39470172cce0ac@127.0.0.1:21004?discport=0", "0x0638e1574728b6d862dd5d3a3e0942c3be47d996", {from: "0xca843569e3427144cead5e4d5999a3d0ccf92b8e"})
{
msg: "Action completed successfully",
status: true
}
> quorumPermission.orgList[1]
{
fullOrgId: "ORG1",
level: 1,
orgId: "ORG1",
parentOrgId: "",
status: 2,
subOrgList: null,
ultimateParent: "ORG1"
}
```
The details of the new organization approved are as below:
```javascript
> quorumPermission.getOrgDetails("ORG1")
{
acctList: [{
acctId: "0x0638e1574728b6d862dd5d3a3e0942c3be47d996",
isOrgAdmin: true,
orgId: "ORG1",
roleId: "ORGADMIN",
status: 2
}],
nodeList: [{
orgId: "ORG1",
status: 2,
url: "enode://de9c2d5937e599930832cecc1df8cc90b50839bdf635c1a4e68e1dab2d001cd4a11c626e155078cc65958a72e2d72c1342a28909775edd99cc39470172cce0ac@127.0.0.1:21004?discport=0"
}],
roleList: [{
access: 3,
active: true,
isAdmin: true,
isVoter: true,
orgId: "ORG1",
roleId: "ORGADMIN"
}],
subOrgList: null
}
```
>A sample example to propose and approve an organization by name `ORG1` is as shown below:
```$xslt
> quorumPermission.addOrg("ORG1", "enode://de9c2d5937e599930832cecc1df8cc90b50839bdf635c1a4e68e1dab2d001cd4a11c626e155078cc65958a72e2d72c1342a28909775edd99cc39470172cce0ac@127.0.0.1:21004?discport=0", "0x0638e1574728b6d862dd5d3a3e0942c3be47d996", {from: "0xed9d02e382b34818e88b88a309c7fe71e65f419d"})
{
msg: "Action completed successfully",
status: true
}
```
>Once the org is proposed, it will be in `Proposed` state awaiting approval from other network admin accounts. The org status is as shown below:
```$xslt
> quorumPermission.orgList[1]
{
fullOrgId: "ORG1",
level: 1,
orgId: "ORG1",
parentOrgId: "",
status: 1,
subOrgList: null,
ultimateParent: "ORG1"
}
```
>The network admin accounts can then approve the proposed organizations and once the majority approval is achieved, the organization status is updated as `Approved`
```$xslt
> quorumPermission.approveOrg("ORG1", "enode://de9c2d5937e599930832cecc1df8cc90b50839bdf635c1a4e68e1dab2d001cd4a11c626e155078cc65958a72e2d72c1342a28909775edd99cc39470172cce0ac@127.0.0.1:21004?discport=0", "0x0638e1574728b6d862dd5d3a3e0942c3be47d996", {from: "0xca843569e3427144cead5e4d5999a3d0ccf92b8e"})
{
msg: "Action completed successfully",
status: true
}
> quorumPermission.orgList[1]
{
fullOrgId: "ORG1",
level: 1,
orgId: "ORG1",
parentOrgId: "",
status: 2,
subOrgList: null,
ultimateParent: "ORG1"
}
```
>The details of the new organization approved are as below:
```$xslt
> quorumPermission.getOrgDetails("ORG1")
{
acctList: [{
acctId: "0x0638e1574728b6d862dd5d3a3e0942c3be47d996",
isOrgAdmin: true,
orgId: "ORG1",
roleId: "ORGADMIN",
status: 2
}],
nodeList: [{
orgId: "ORG1",
status: 2,
url: "enode://de9c2d5937e599930832cecc1df8cc90b50839bdf635c1a4e68e1dab2d001cd4a11c626e155078cc65958a72e2d72c1342a28909775edd99cc39470172cce0ac@127.0.0.1:21004?discport=0"
}],
roleList: [{
access: 3,
active: true,
isAdmin: true,
isVoter: true,
orgId: "ORG1",
roleId: "ORGADMIN"
}],
subOrgList: null
}
```
As can be seen from the above, as a part of approval:
* A org admin role with name as given in `orgAdminRole` in `permission-config.json` has been created and linked to the organization `ORG1`
* The account given has been linked to the organization `ORG1` and org admin role. This account acts as the organization admin account and can in turn manage further roles, nodes and accounts at organization level
* The node has been linked to organization and status has been updated as `Approved`
The new node belonging to the organization can now join the network. In case the network is running in `Raft` consensus mode, before the node joins the network, please ensure that:
* The node has been added as a peer using `raft.addPeer(<<enodeId>>)`
* Bring up `geth` for the new node using `--raftjoinexisting` with the peer id as obtained in the above step
### Organization admin managing the organization level permissions
Once the organization is approved and the node of the organization has joined the network, the organization admin can then create sub organizations, roles, add additional nodes at organization level, add accounts to the organization and change roles of existing organization level accounts.
>To add a sub org at `ORG1` level refer to [addSubOrg API](./Permissioning%20apis.md#quorumpermissionaddsuborg)
```$xslt
To add a sub org at `ORG1` level refer to [addSubOrg API](../Permissioning%20apis#quorumpermissionaddsuborg)
```javascript
> quorumPermission.addSubOrg("ORG1", "SUB1", "enode://239c1f044a2b03b6c4713109af036b775c5418fe4ca63b04b1ce00124af00ddab7cc088fc46020cdc783b6207efe624551be4c06a994993d8d70f684688fb7cf@127.0.0.1:21006?discport=0", {from: eth.accounts[0]})
{
msg: "Action completed successfully",
@ -191,8 +199,8 @@ Once the organization is approved and the node of the organization has joined th
subOrgList: null
}
```
For adding a sub org the enode id is not mandatory. For the newly created sub org if the org admin desires to add an administration account, the org admin account will have to first create a role with `isAdmin` flag as `Y` and then assign this role to the account which belongs to the sub org. Once assigned the account will act as org admin at sub org level. Refer to [addNewRole API](./Permissioning%20apis.md#quorumpermissionaddnewrole)
```$xslt
For adding a sub org the enode id is not mandatory. For the newly created sub org if the org admin desires to add an administration account, the org admin account will have to first create a role with `isAdmin` flag as `Y` and then assign this role to the account which belongs to the sub org. Once assigned the account will act as org admin at sub org level. Refer to [addNewRole API](../Permissioning%20apis#quorumpermissionaddnewrole)
```javascript
> quorumPermission.addNewRole("ORG1.SUB1", "SUBADMIN", 3, false, true,{from: eth.accounts[0]})
{
msg: "Action completed successfully",
@ -202,7 +210,7 @@ For adding a sub org the enode id is not mandatory. For the newly created sub or
"0x0638e1574728b6d862dd5d3a3e0942c3be47d996"
```
The role `SUBADMIN` can now be assigned to an account at sub org `SUB1` for making the account admin for the sub org.
```$xslt
```javascript
> quorumPermission.addAccountToOrg("0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0", "ORG1.SUB1", "SUBADMIN", {from: "0x0638e1574728b6d862dd5d3a3e0942c3be47d996"})
{
msg: "Action completed successfully",
@ -234,7 +242,7 @@ The role `SUBADMIN` can now be assigned to an account at sub org `SUB1` for maki
}
```
The account `0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0` is now the admin for sub org `SUB1` and will be able to add roles, accounts and nodes to the sub org. It should be noted that the org admin account at master org level has the admin rights on all the sub organizations below. However the admin account at sub org level has control only in the sub org to which it is linked.
```$xslt
```javascript
> quorumPermission.addNewRole("ORG1.SUB1", "TRANSACT", 1, false, true,{from: "0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0"})
{
msg: "Action completed successfully",
@ -257,8 +265,8 @@ The account `0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0` is now the admin for su
roleId: "TRANSACT"
}]
```
>To add an account to an organization refer to [addAccountToOrg API](./Permissioning%20apis.md#quorumpermissionaddaccounttoorg)
```$xslt
To add an account to an organization refer to [addAccountToOrg API](../Permissioning%20apis#quorumpermissionaddaccounttoorg)
```javascript
> quorumPermission.addAccountToOrg("0x283f3b8989ec20df621166973c93b56b0f4b5455", "ORG1.SUB1", "SUBADMIN", {from: "0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0"})
{
msg: "Action completed successfully",
@ -280,8 +288,8 @@ The account `0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0` is now the admin for su
status: 2
}]
```
>To [suspend an account updateAccountStatus](./Permissioning%20apis.md#quorumpermissionupdateaccountstatus) API can be invoked with action as 1
```$xslt
To suspend an account [updateAccountStatus](../Permissioning%20apis#quorumpermissionupdateaccountstatus) API can be invoked with action as 1
```javascript
> quorumPermission.getOrgDetails("ORG1.SUB1").acctList
[{
acctId: "0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0",
@ -297,8 +305,8 @@ The account `0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0` is now the admin for su
status: 4
}]
```
>To [revoke suspension of an account updateAccountStatus](./Permissioning%20apis.md#quorumpermissionupdateaccountstatus) API can be invoked with action as 2
```$xslt
To revoke suspension of an account [updateAccountStatus](../Permissioning%20apis#quorumpermissionupdateaccountstatus) API can be invoked with action as 2
```javascript
> quorumPermission.updateAccountStatus("ORG1.SUB1", "0x283f3b8989ec20df621166973c93b56b0f4b5455", 2, {from: "0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0"})
{
msg: "Action completed successfully",
@ -320,8 +328,8 @@ The account `0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0` is now the admin for su
status: 2
}]
```
>To [blacklist an account updateAccountStatus](./Permissioning%20apis.md#quorumpermissionupdateaccountstatus) API can be invoked with action as 3. Once blacklisted no further activity will be possible on the account.
```$xslt
To [blacklist an account updateAccountStatus](../Permissioning%20apis#quorumpermissionupdateaccountstatus) API can be invoked with action as 3. Once blacklisted no further activity will be possible on the account.
```javascript
> quorumPermission.updateAccountStatus("ORG1.SUB1", "0x283f3b8989ec20df621166973c93b56b0f4b5455", 3, {from: "0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0"})
{
msg: "Action completed successfully",
@ -343,8 +351,8 @@ The account `0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0` is now the admin for su
status: 5
}]
```
> To [add nodes addNode ](./Permissioning%20apis.md#quorumpermissionaddnode) at organization and sub organization level by the org admin
```$xslt
To [add nodes addNode ](../Permissioning%20apis#quorumpermissionaddnode) at organization and sub organization level by the org admin
```javascript
> quorumPermission.addNode("ORG1.SUB1", "enode://eacaa74c4b0e7a9e12d2fe5fee6595eda841d6d992c35dbbcc50fcee4aa86dfbbdeff7dc7e72c2305d5a62257f82737a8cffc80474c15c611c037f52db1a3a7b@127.0.0.1:21005?discport=0", {from: "0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0"})
{
msg: "Action completed successfully",
@ -361,8 +369,8 @@ The account `0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0` is now the admin for su
url: "enode://eacaa74c4b0e7a9e12d2fe5fee6595eda841d6d992c35dbbcc50fcee4aa86dfbbdeff7dc7e72c2305d5a62257f82737a8cffc80474c15c611c037f52db1a3a7b@127.0.0.1:21005?discport=0"
}]
```
> Org admin can manage the status of the nodes by using [updateNodeStatus](./Permissioning%20apis.md#quorumpermissionupdatenodestatus) API. To deactivate a node the API can be invoked with action 1
```$xslt
Org admin can manage the status of the nodes by using [updateNodeStatus](../Permissioning%20apis#quorumpermissionupdatenodestatus) API. To deactivate a node the API can be invoked with action 1
```javascript
> quorumPermission.getOrgDetails("ORG1.SUB1").nodeList
[{
orgId: "ORG1.SUB1",
@ -374,8 +382,8 @@ The account `0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0` is now the admin for su
url: "enode://eacaa74c4b0e7a9e12d2fe5fee6595eda841d6d992c35dbbcc50fcee4aa86dfbbdeff7dc7e72c2305d5a62257f82737a8cffc80474c15c611c037f52db1a3a7b@127.0.0.1:21005?discport=0"
}]
```
> To activate the node back invoke [updateNodeStatus](./Permissioning%20apis.md#quorumpermissionupdatenodestatus) API with action 2
```$xslt
To activate the node back invoke [updateNodeStatus](../Permissioning%20apis#quorumpermissionupdatenodestatus) API with action 2
```javascript
> quorumPermission.updateNodeStatus("ORG1.SUB1", "enode://eacaa74c4b0e7a9e12d2fe5fee6595eda841d6d992c35dbbcc50fcee4aa86dfbbdeff7dc7e72c2305d5a62257f82737a8cffc80474c15c611c037f52db1a3a7b@127.0.0.1:21005?discport=0",2, {from:"0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0"})
{
msg: "Action completed successfully",
@ -394,8 +402,8 @@ The account `0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0` is now the admin for su
url: "enode://eacaa74c4b0e7a9e12d2fe5fee6595eda841d6d992c35dbbcc50fcee4aa86dfbbdeff7dc7e72c2305d5a62257f82737a8cffc80474c15c611c037f52db1a3a7b@127.0.0.1:21005?discport=0"
}]
```
> To blacklist a node invoke [updateNodeStatus](./Permissioning%20apis.md#quorumpermissionupdatenodestatus) API with action 3. Once blacklisted the node will never be able join the network again.
```$xslt
To blacklist a node invoke [updateNodeStatus](../Permissioning%20apis#quorumpermissionupdatenodestatus) API with action 3. Once blacklisted the node will never be able join the network again.
```javascript
> quorumPermission.getOrgDetails("ORG1.SUB1").nodeList
@ -412,12 +420,13 @@ The account `0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0` is now the admin for su
It should be noted that in case `Raft` consensus mechanism when the node is deactivated the peer id is lost and hence upon activation, the node needs to be added to Raft cluster again using `raft.addPeer` and the node should be brought up with new peer id
Further
* An account can transact from any of the nodes linked to org or sub org with in the same organization
* If a node is deactivated no transaction will be allowed from that node
### Suspending an organization temporarily
> If there is a need to temporarily suspend all activities of an organization [updateOrgStatus](./Permissioning%20apis.md#quorumpermissionupdateorgstatus) API can be invoked with action 1. This can be invoked only by the network admin accounts and will reuiqre majority voting
```$xslt
If there is a need to temporarily suspend all activities of an organization [updateOrgStatus](../Permissioning%20apis#quorumpermissionupdateorgstatus) API can be invoked with action 1. This can be invoked only by the network admin accounts and will reuiqre majority voting
```javascript
> quorumPermission.updateOrgStatus("ORG1", 1, {from: "0xed9d02e382b34818e88b88a309c7fe71e65f419d"})
{
msg: "Action completed successfully",
@ -434,8 +443,8 @@ Further
ultimateParent: "ORG1"
}
```
> To approve the org suspension majority approval from other network admin accounts is required. The api for the same is [approveOrgStatus](./Permissioning%20apis.md#quorumpermissionapproveorgstatus). Once approved the org status is marked as suspended
```$xslt
To approve the org suspension majority approval from other network admin accounts is required. The api for the same is [approveOrgStatus](../Permissioning%20apis#quorumpermissionapproveorgstatus). Once approved the org status is marked as suspended
```javascript
> quorumPermission.approveOrgStatus("ORG1", 1, {from: "0xca843569e3427144cead5e4d5999a3d0ccf92b8e"})
{
msg: "Action completed successfully",
@ -456,8 +465,8 @@ When the org is suspended no transaction from any of the account linked to the o
### Revoking suspension of an organization
> To revoke the suspension of an org [updateOrgStatus](./Permissioning%20apis.md#quorumpermissionupdateorgstatus) can be called with action as 2. This will require majority approval (API [approveOrgStatus](./Permissioning%20apis.md#quorumpermissionapproveorgstatus) with action 2)
```$xslt
To revoke the suspension of an org [updateOrgStatus](../Permissioning%20apis#quorumpermissionupdateorgstatus) can be called with action as 2. This will require majority approval (API [approveOrgStatus](../Permissioning%20apis#quorumpermissionapproveorgstatus) with action 2)
```javascript
> quorumPermission.updateOrgStatus("ORG1", 2, {from: "0xed9d02e382b34818e88b88a309c7fe71e65f419d"})
{
msg: "Action completed successfully",
@ -483,8 +492,8 @@ Once the revoke is approved, all accounts in the organization and sub organizati
### Assigning admin privileges at organization and network level
There might be a scenario where in one of the accounts at the organization level needs to have network admin level permissions and be able to perform network admin activities. Similarly there can be a need to change the admin account at organization level. Both these activities can be performed by existing network admin accounts only and will require majority approval from the network admin accounts. The API usage details are as below.
> To assign network admin or org admin role to an account invoke [assignAdminRole](./Permissioning%20apis.md#quorumpermissionassignadminrole)
```$xslt
To assign network admin or org admin role to an account invoke [assignAdminRole](../Permissioning%20apis#quorumpermissionassignadminrole)
```javascript
> quorumPermission.assignAdminRole("ORG1", "0x0638e1574728b6d862dd5d3a3e0942c3be47d996", "ADMIN", {from: "0xed9d02e382b34818e88b88a309c7fe71e65f419d"})
{
msg: "Action completed successfully",
@ -499,8 +508,8 @@ There might be a scenario where in one of the accounts at the organization level
status: 1
}
```
> To approve the assignment of network admin role invoke [approveAdminRole](./Permissioning%20apis.md#quorumpermissionapproveadminrole) API
```$xslt
To approve the assignment of network admin role invoke [approveAdminRole](../Permissioning%20apis#quorumpermissionapproveadminrole) API
```javascript
> quorumPermission.approveAdminRole("ORG1", "0x0638e1574728b6d862dd5d3a3e0942c3be47d996", {from: eth.accounts[0]})
{
msg: "Action completed successfully",

32
docs/Permissioning/setup.md
View File

@ -1,25 +1,26 @@
# Set up
The steps to enable new permissions model are as described below:
* For a new network, bring up the initial set of nodes which will be part of the network
* Deploy the `PermissionsUpgradable.sol` in the network. The deployment of this contract will require a custodian account to be given as a part of deployment.
* Deploy the rest of the contracts. All the other contracts will require the address of `PermissionsUpgradable.sol` contract as a part of deployment.
* Once all the contracts are deployed create a file `permission-config.json` which will have the following construct:
```json
{
"upgradableAddress": "0x1932c48b2bf8102ba33b4a6b545c32236e342f34",
"interfaceAddress": "0x4d3bfd7821e237ffe84209d8e638f9f309865b87",
"implAddress": "0xfe0602d820f42800e3ef3f89e1c39cd15f78d283",
"nodeMgrAddress": "0x8a5e2a6343108babed07899510fb42297938d41f",
"accountMgrAddress": "0x9d13c6d3afe1721beef56b55d303b09e021e27ab",
"roleMgrAddress": "0x1349f3e1b8d71effb47b840594ff27da7e603d17",
"voterMgrAddress": "0xd9d64b7dc034fafdba5dc2902875a67b5d586420",
"orgMgrAddress" : "0x938781b9796aea6376e40ca158f67fa89d5d8a18",
"nwAdminOrg": "ADMINORG",
"nwAdminRole" : "ADMIN",
"orgAdminRole" : "ORGADMIN",
"accounts":["0xed9d02e382b34818e88b88a309c7fe71e65f419d", "0xca843569e3427144cead5e4d5999a3d0ccf92b8e"],
"subOrgBreadth" : "3",
"subOrgDepth" : "4"
"upgradableAddress": "0x1932c48b2bf8102ba33b4a6b545c32236e342f34",
"interfaceAddress": "0x4d3bfd7821e237ffe84209d8e638f9f309865b87",
"implAddress": "0xfe0602d820f42800e3ef3f89e1c39cd15f78d283",
"nodeMgrAddress": "0x8a5e2a6343108babed07899510fb42297938d41f",
"accountMgrAddress": "0x9d13c6d3afe1721beef56b55d303b09e021e27ab",
"roleMgrAddress": "0x1349f3e1b8d71effb47b840594ff27da7e603d17",
"voterMgrAddress": "0xd9d64b7dc034fafdba5dc2902875a67b5d586420",
"orgMgrAddress" : "0x938781b9796aea6376e40ca158f67fa89d5d8a18",
"nwAdminOrg": "ADMINORG",
"nwAdminRole" : "ADMIN",
"orgAdminRole" : "ORGADMIN",
"accounts":["0xed9d02e382b34818e88b88a309c7fe71e65f419d", "0xca843569e3427144cead5e4d5999a3d0ccf92b8e"],
"subOrgBreadth" : "3",
"subOrgDepth" : "4"
}
```
> * `upgrdableAddress` is the address of deployed contract `PermissionsUpgradable.sol`
@ -51,4 +52,5 @@ var intr = "0x4d3bfd7821e237ffe84209d8e638f9f309865b87" // address of the interf
* In case migrating from an earlier version to current version, upgrade `geth`
* Bring up all `geth` nodes in `--permissioned` mode for the new permissions model to take effect
It should be noted that the new permission model will be in force only when `permission-config.json` is present in data directory. If this file is not there and the node is brought up with `--permissioned` flag, node level permissions as per the earlier model will be effective.
!!! Note
It should be noted that the new permission model will be in force only when `permission-config.json` is present in data directory. If this file is not there and the node is brought up with `--permissioned` flag, node level permissions as per the earlier model will be effective.

2
mkdocs.yml
View File

@ -74,7 +74,7 @@ extra_css:
markdown_extensions:
- toc:
permalink: true
toc_depth: 3
toc_depth: 4
- codehilite
- admonition
- footnotes