mirror of https://github.com/poanetwork/quorum.git
Just corrections to the documentation.
This commit is contained in:
SatpalSandhu61
vsmk98
parent
894f26a23d
commit
f3b222af08
|
|
@ -2,12 +2,12 @@
|
|||
The permissions model is completely built on smart contracts. The smart contract design is as below:
|
||||
|
||||
|
||||
The permissions smart contract design follows the Proxy-Implementation-Storage pattern which allows the implementation logic to change without changing the storage or interface layer. Brief description of the smart contracts is as below:
|
||||
* `PermissionsUpgradable.sol`: This contract stores the address of current implementation contract and is owned by a custodian(an Ethereum account). Only custodian is allowed to change the implementation contract address.
|
||||
* `PermissionsInterface.sol`: This is the interface contract and holds the interfaces for permissions related actions. This does not have any business logic and it forwards requests to current implementation contract
|
||||
* `PermissionsImplementation.sol`: This contract has the business logic for the permissions actions. This contract can receive requests only from a valid interface as defined in `PermissionsUpgradable.sol` and interact with all the storage contracts for respective actions.
|
||||
* `OrgManager.sol`: This contract stores data for organizations and sub organizations. This contract can receive request from valid implementation contract as defined in `PermissionsUpgrdable.sol`
|
||||
* `AccountManager.sol`: This contract receives requests from valid implementation contract as defined in `PermissionsUpgrdable.sol`. This contracts stores the data of all accounts, their linkage to organization and various roles. This contracts also stores the status of an account. The account can be in any of the following states - `PendingApproval`, `Active`, `Suspended`, `Blacklisted`, `Revoked`
|
||||
* `NodeManager.sol`: This contract receives requests from valid implementation contract as defined in `PermissionsUpgrdable.sol`. This contracts stores the data of a node, its linkage to a organization or sub organization and status of the node. The node status can be any one of the following states - `PendingApproval`, `Active`, `Deactivated`, `Blacklisted`
|
||||
* `RoleManager.sol`: This contract receives requests from valid implementation contract as defined in `PermissionsUpgrdable.sol`. This contract stores data for various roles and the organization to which it is linked. At access at role level can be any one of the following: `Readonly` which allows only read operations, `Transact` which allows value transfer but no contract deployment access, `ContractDeploy` which allows both value transfer and contract deployment access and `FullAccess` which allows additional network level accesses in addition to value transfer and contract deployment. If a role is revoked all accounts which are linked to the role lose all access rights.
|
||||
* `VoterManager.sol`: This contract receives requests from valid implementation contract as defined in `PermissionsUpgrdable.sol`. This contract stores the data of valid voters at network level which can approve identified activities e.g. adding a new organization to the network. Any account which is linked to a predefined network admin role will be marked as a voter. Whenever a network level activity which requires voting is performed, a voting item is added to this contract and each voter account can vote for the activity. The activity is marked as `Approved` upon majority voting.
|
||||
The permissions smart contract design follows the Proxy-Implementation-Storage pattern which allows the implementation logic to change without changing the storage or interface layer. A brief description of the smart contracts is below:
|
||||
* `PermissionsUpgradable.sol`: This contract stores the address of current implementation contract and is owned by a custodian (an Ethereum account). Only the custodian is allowed to change the implementation contract address.
|
||||
* `PermissionsInterface.sol`: This is the interface contract and holds the interfaces for permissions related actions. It has no business logic and forwards requests to the current implementation contract
|
||||
* `PermissionsImplementation.sol`: This contract has the business logic for the permissions actions. It can receive requests only from a valid interface as defined in `PermissionsUpgradable.sol` and interacts with all the storage contracts for respective actions.
|
||||
* `OrgManager.sol`: This contract stores data for organizations and sub organizations. It can receive requests from a valid implementation contract as defined in `PermissionsUpgrdable.sol`
|
||||
* `AccountManager.sol`: This contract receives requests from a valid implementation contract as defined in `PermissionsUpgrdable.sol`. It stores the data of all accounts, their linkage to organization and various roles. The contract also stores the status of an account. The account can be in any of the following states - `PendingApproval`, `Active`, `Suspended`, `Blacklisted`, `Revoked`
|
||||
* `NodeManager.sol`: This contract receives requests from a valid implementation contract as defined in `PermissionsUpgrdable.sol`. It stores the data of a node, its linkage to an organization or sub organization, and status of the node. The node can be in any one of the following states - `PendingApproval`, `Active`, `Deactivated`, `Blacklisted`
|
||||
* `RoleManager.sol`: This contract receives requests from a valid implementation contract as defined in `PermissionsUpgrdable.sol`. It stores data for various roles and the organization to which it is linked. The access at role level can be any one of the following: `Readonly` which allows only read operations, `Transact` which allows value transfer but no contract deployment access, `ContractDeploy` which allows both value transfer and contract deployment access, and `FullAccess` which allows additional network level accesses in addition to value transfer and contract deployment. If a role is revoked all accounts which are linked to the role lose all access rights.
|
||||
* `VoterManager.sol`: This contract receives requests from a valid implementation contract as defined in `PermissionsUpgrdable.sol`. It stores the data of valid voters at network level which can approve identified activities e.g. adding a new organization to the network. Any account which is linked to a predefined network admin role will be marked as a voter. Whenever a network level activity which requires voting is performed, a voting item is added to this contract and each voter account can vote for the activity. The activity is marked as `Approved` upon majority voting.
|
||||
|
|
|
|||
|
|
@ -1,16 +1,16 @@
|
|||
# Introduction
|
||||
The [current permission model](../Old%20Permissioning.md) with in Quorum is limited to node level permissions only and allows a set of nodes which are part of `permissioned-nodes.json` to join the network. The model has been enhanced to cater for enterprise level needs to have **smart contract based permissions model** which allows flexibility to manage nodes, accounts and account level access controls. The overview of the model is as depicted below:
|
||||
The [current permission model](../Old%20Permissioning.md) within Quorum is limited to node level permissions only and allows a set of nodes which are part of `permissioned-nodes.json` to join the network. The model has been enhanced to cater for enterprise level needs to have a **smart contract based permissions model**; this has the flexibility to manage nodes, accounts, and account level access controls. The overview of the model is as depicted below:
|
||||
|
||||
### Key Definitions
|
||||
* Network - A set of interconnected nodes representing an enterprise blockchain which contains organizations
|
||||
* Organization - A set of Ethereum accounts, nodes having varied permissions to interact with the network
|
||||
* Sub Organization - Further sub grouping with in the Organization as per business need
|
||||
* Organization - A set of Ethereum accounts and nodes having a variety of permissions to interact with the network
|
||||
* Sub Organization - Further sub-grouping within the Organization as per business needs
|
||||
* Account - An Ethereum account which is an EOA (Externally Owned Account)
|
||||
* Voter - An account capable of voting for a certain action
|
||||
* Role - A named job function in organization
|
||||
* Role - A named job function in an organization
|
||||
* Node - A `geth` node which is part of the network and belongs to an organization or sub organization
|
||||
|
||||
As depicted above, in the enhanced permissions model, the network comprises of group of organization. The network admin accounts defined at network level can propose and approve new organizations to join the network and assign an account as the organization administration account. The organization admin account can in turn creates roles, sub organizations, assign roles to its accounts and add any other node which is part of the organization. The sub organizations in turn can have its own set of roles accounts and sub organizations. The organization administration account manages and controls all activities at the organization level. The organization administrator can create an admin role and assign the same to a different account to manage the administration of a sub organization. The access rights of an account are derived based on the role assigned to it. The account will be able to transact via any node linked to the sub org or at overall organizations level.
|
||||
As depicted above, in the enhanced permissions model, the network comprises a group of organizations. The network admin accounts defined at network level can propose and approve new organizations to join the network, and can assign an account as the organization administration account. The organization admin account can create roles, create sub organizations, assign roles to its accounts, and add any other node which is part of the organization. A sub organization can have its own set of roles, accounts and sub organizations. The organization administration account manages and controls all activities at the organization level. The organization administrator can create an admin role and assign the same to a different account to manage the administration of a sub organization. The access rights of an account are derived based on the role assigned to it. The account will be able to transact via any node linked to the sub org or at overall organizations level.
|
||||
|
||||
A sample network view is as depicted below:
|
||||
|
||||
|
|
|
|||
|
|
@ -75,9 +75,9 @@
|
|||
}]
|
||||
```
|
||||
#### quorumPermission.getOrgDetails
|
||||
This returns the list of accounts, nodes, roles, sub organizations linked to an organization
|
||||
* Input: idrganization or sub organization id
|
||||
* Output: list of all accounts, roles, nodes and sub orgs
|
||||
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:
|
||||
```
|
||||
> quorumPermission.getOrgDetails("INITORG")
|
||||
|
|
@ -135,7 +135,7 @@ This api can be executed by a network admin account only for proposing a new org
|
|||
status: true
|
||||
}
|
||||
```
|
||||
If there 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.
|
||||
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.
|
||||
```
|
||||
> quorumPermission.addOrg("ABC", "enode://3d9ca5956b38557aba991e31cf510d4df641dce9cc26bfeb7de082f0c07abb6ede3a58410c8f249dabeecee4ad3979929ac4c7c496ad20b8cfdd061b7401b4f5@127.0.0.1:21003?discport=0&raftport=50404", "0x0638e1574728b6d862dd5d3a3e0942c3be47d996", {from: eth.accounts[0]})
|
||||
{
|
||||
|
|
@ -156,7 +156,7 @@ If there any pending items for approval, proposal of any new organization will f
|
|||
```
|
||||
|
||||
#### quorumPermission.approveOrg
|
||||
This api can be executed by a network admin account only for approving a proposed organization into the network
|
||||
This api can be executed by a network admin account only for approving a proposed organization into the network.
|
||||
* Input: Unique organization id, enode id, account id
|
||||
* Output: Status of the operation
|
||||
* Example:
|
||||
|
|
@ -168,7 +168,7 @@ quorumPermission.approveOrg("ABC", "enode://3d9ca5956b38557aba991e31cf510d4df641
|
|||
}
|
||||
```
|
||||
#### quorumPermission.updateOrgStatus
|
||||
This api can be executed by a network admin account only for temporarily suspending an organization and re-enabling a suspended organization. This activity can be performed for master organization only and requires majority approval from network admins.
|
||||
This api can only be executed by a network admin account and is used for temporarily suspending an organization or re-enabling a suspended organization. This activity can be performed for master organization only and requires majority approval from network admins.
|
||||
* Input: organization id, action (3 for suspending the organization and 5 for re-enabling the suspended organization)
|
||||
* Output: Status of the operation
|
||||
* Example:
|
||||
|
|
@ -180,7 +180,7 @@ This api can be executed by a network admin account only for temporarily suspend
|
|||
}
|
||||
```
|
||||
#### quorumPermission.approveOrgStatus
|
||||
This api can be executed by a network admin account only for approving the org status change proposal. Once majority approval is received from network admins, the org status is updated.
|
||||
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 (3 for suspending the organization and 5 for re-enabling the suspended organization)
|
||||
* Output: Status of the operation
|
||||
* Example:
|
||||
|
|
@ -191,11 +191,11 @@ This api can be executed by a network admin account only for approving the org s
|
|||
status: true
|
||||
}
|
||||
```
|
||||
When a org is in suspended status, no transactions or contract deploy activities are allowed from any nodes linked to the org and sub organizations under it. Similarly no transactions will be allowed from any accounts linked to the organization
|
||||
When an organization is in suspended status, no transactions or contract deploy activities are allowed from any nodes linked to the org and sub organizations under it. Similarly no transactions will be allowed from any accounts linked to the organization
|
||||
|
||||
#### quorumPermission.addSubOrg
|
||||
This api can be executed by a organization admin account to create a sub organization under under the master org.
|
||||
* Input: parent org id, Sub organization id, enode id ( not mandatory and can be null), account id (not mandatory and can be 0x0)
|
||||
This api can be executed by a organization admin account to create a sub organization under the master org.
|
||||
* Input: parent org id, 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:
|
||||
```
|
||||
|
|
@ -206,7 +206,7 @@ This api can be executed by a organization admin account to create a sub organiz
|
|||
status: true
|
||||
}
|
||||
```
|
||||
For adding a sub organization at next level the parent org id should have the entire org hierarchy upto the immediate parent. e.g.
|
||||
For adding a sub organization at the next level, the parent org id should have the entire org hierarchy up to the immediate parent e.g.
|
||||
```
|
||||
> quorumPermission.addSubOrg("ABC.SUB1", "SUB2","", "0x0000000000000000000000000000000000000000", {from: eth.accounts[0]})
|
||||
{
|
||||
|
|
@ -220,8 +220,8 @@ For adding a sub organization at next level the parent org id should have the en
|
|||
}
|
||||
```
|
||||
#### quorumPermission.addNewRole
|
||||
This api can be executed by organization admin account to create a new role for the organization
|
||||
* Input: org or sub org id, role id, account access(can be 0 - ReadOnly, 1 - Transact, 2 - ContractDeploy, 3 - FullAccess), isVoter, isAdminRole
|
||||
This api can be executed by an organization admin account to create a new role for the organization.
|
||||
* Input: organiztion id or sub organization id, role id, account access (can be 0 - ReadOnly, 1 - Transact, 2 - ContractDeploy, 3 - FullAccess), isVoter, isAdminRole
|
||||
* Output: Status of the operation
|
||||
* Example:
|
||||
```
|
||||
|
|
@ -237,8 +237,8 @@ This api can be executed by organization admin account to create a new role for
|
|||
}
|
||||
```
|
||||
#### quorumPermission.removeRole
|
||||
This api can be executed by organization admin account to create a new role for the organization
|
||||
* Input: org or sub org id, role id
|
||||
This api can be executed by an organization admin account to create a new role for the organization.
|
||||
* Input: organization id or sub organization id, role id
|
||||
* Output: Status of the operation
|
||||
* Example:
|
||||
```
|
||||
|
|
@ -249,8 +249,8 @@ This api can be executed by organization admin account to create a new role for
|
|||
}
|
||||
```
|
||||
#### quorumPermission.assignAccountRole
|
||||
This api can be executed by organization admin account to assign a role to an account
|
||||
* Input: Account id, org or sub org id, role to be assigned
|
||||
This api can be executed by an organization admin account to assign a role to an account.
|
||||
* Input: Account id, organization id or sub organization id, role to be assigned
|
||||
* Output: Status of the operation
|
||||
* Example:
|
||||
```
|
||||
|
|
@ -269,8 +269,8 @@ The account can be linked to a organization or sub organization only and cannot
|
|||
}
|
||||
```
|
||||
#### quorumPermission.updateAccountStatus
|
||||
This api can be executed by organization admin account to update the account status
|
||||
* Input: org or sub org id, Account id, action (1 for suspending the account, 2 for activating a suspended account, 3 for blacklisting the account)
|
||||
This api can be executed by an organization admin account to update the account status.
|
||||
* 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:
|
||||
```
|
||||
|
|
@ -280,11 +280,11 @@ This api can be executed by organization admin account to update the account sta
|
|||
status: true
|
||||
}
|
||||
```
|
||||
Once a account is blacklisted no further action is allowed on it
|
||||
Once a account is blacklisted no further action is allowed on it.
|
||||
|
||||
#### quorumPermission.assignAdminRole
|
||||
This api can be executed by network admin to add a new account as network admin or change the org admin account for a organization
|
||||
* Input: org id to which the account belongs, account id, role id (it can be either org admin role or network admin role)
|
||||
This api can be executed by the network admin to add a new account as network admin or change the org admin account for an organization.
|
||||
* 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:
|
||||
```
|
||||
|
|
@ -296,8 +296,8 @@ This api can be executed by network admin to add a new account as network admin
|
|||
```
|
||||
|
||||
#### quorumPermission.approveAdminRole
|
||||
This api can be executed by network admin to add approve the org admin or network admin role assignment to an account. The role is approved once majority approvals is received
|
||||
* Input: org id to which the account belongs, account id
|
||||
This api can be executed by the network admin to approve the organization admin or network admin role assignment to an account. The role is approved once majority approval is received.
|
||||
* Input: organization id to which the account belongs, account id
|
||||
* Output: Status of the operation
|
||||
* Example:
|
||||
```
|
||||
|
|
@ -310,8 +310,8 @@ This api can be executed by network admin to add approve the org admin or networ
|
|||
```
|
||||
|
||||
#### quorumPermission.addNode
|
||||
This api can be executed by organization admin account to add a node to the org or sub org
|
||||
* Input: org or sub org id, enode id
|
||||
This api can be executed by the organization admin account to add a node to the organization or sub organization.
|
||||
* Input: organization id or sub organization id, enode id
|
||||
* Output: Status of the operation
|
||||
* Example:
|
||||
```
|
||||
|
|
@ -324,8 +324,8 @@ This api can be executed by organization admin account to add a node to the org
|
|||
A node cannot be part of multiple organizations.
|
||||
|
||||
#### quorumPermission.updateNodeStatus
|
||||
This api can be executed by organization admin account to update the status of a node
|
||||
* Input: org or sub org id, enode id, action (3 for deactivating the node, 4 for activating a deactivated node and 5 for blacklisting a node)
|
||||
This api can be executed by the organization admin account to update the status of a node.
|
||||
* Input: organization id or sub organization id, enode id, action (3 for deactivating the node, 4 for activating a deactivated node and 5 for blacklisting a node)
|
||||
* Output: Status of the operation
|
||||
* Example:
|
||||
```
|
||||
|
|
@ -347,9 +347,9 @@ The table below indicates the numeric value for each account access type.
|
|||
| Contract deploy | 2 |
|
||||
| Full access | 3 |
|
||||
|
||||
While setting the account access, system checks if the account which is setting the access has sufficient privileges to perform the activity.
|
||||
When setting the account access, the system checks if the account setting the access has sufficient privileges to perform the activity.
|
||||
* Accounts with `FullAccess` can grant any access type ( FullAccess, Transact, ContractDeploy or ReadOnly) to any other account
|
||||
* Accounts with `ContractDeploy` can grant only `Transact`, `ContractDeploy` or `ReadOnly` access to other accounts
|
||||
* Accounts with `Transact` access grant only `Transact` or `ReadOnly` access to other accounts
|
||||
* Accounts with `Transact` access can grant only `Transact` or `ReadOnly` access to other accounts
|
||||
* Accounts with `ReadOnly` access cannot grant any access
|
||||
|
||||
|
|
|
|||
|
|
@ -36,5 +36,5 @@ The steps to enable new permissions model are as described below:
|
|||
> * `subOrgBreadth` indicates the number of sub organizations that any org can have
|
||||
> * `subOrgDepth` indicates the maximum depth sub org hierarchy allowed in the network
|
||||
|
||||
* Bring down the all `geth` nodes in network and copy `permission-config.json` into the data directory of each of the node
|
||||
* Bring up all `geth` nodes in `--permissioned` mode for new permissions model to take effect
|
||||
* Bring down the all `geth` nodes in the network and copy `permission-config.json` into the data directory of each node
|
||||
* Bring up all `geth` nodes in `--permissioned` mode for the new permissions model to take effect
|
||||
|
|
|
|||
Loading…
Reference in New Issue