From ad2abca93abbf280cf8e12988ac8d05de7c94a33 Mon Sep 17 00:00:00 2001 From: vsmk98 Date: Fri, 10 May 2019 15:17:01 +0800 Subject: [PATCH] permissions: code comments update --- cmd/geth/main.go | 4 +- core/types/permissions_cache.go | 9 +-- internal/web3ext/web3ext.go | 71 ------------------- permission/contract/AccountManager.sol | 52 ++++++-------- permission/contract/NodeManager.sol | 19 +++-- permission/contract/OrgManager.sol | 34 ++++++--- .../contract/PermissionsImplementation.sol | 31 +++++++- permission/contract/PermissionsUpgradable.sol | 3 + permission/contract/RoleManager.sol | 9 ++- permission/contract/VoterManager.sol | 3 +- permission/permission.go | 23 +++--- 11 files changed, 119 insertions(+), 139 deletions(-) diff --git a/cmd/geth/main.go b/cmd/geth/main.go index aed12b594..9d02c1470 100644 --- a/cmd/geth/main.go +++ b/cmd/geth/main.go @@ -377,8 +377,8 @@ func startNode(ctx *cli.Context, stack *node.Node) { } -// Starts all permissioning services permissioning services will come up only when -// geth is brought up in --permissioned mode +// Starts the permissioning services. services will come up only when +// geth is brought up in --permissioned mode and permission-config.json is present func startQuorumPermissionService(ctx *cli.Context, stack *node.Node) { var quorumApis []string diff --git a/core/types/permissions_cache.go b/core/types/permissions_cache.go index 5beac9b47..2409d2688 100644 --- a/core/types/permissions_cache.go +++ b/core/types/permissions_cache.go @@ -188,7 +188,6 @@ func (pc *PermissionConfig) IsEmpty() bool { return pc.InterfAddress == common.HexToAddress("0x0") || pc.NodeAddress == common.HexToAddress("0x0") || pc.AccountAddress == common.HexToAddress("0x0") } -// sets default access to ReadOnly func SetSyncStatus() { syncStarted = true } @@ -197,12 +196,10 @@ func GetSyncStatus() bool { return syncStarted } -// sets default access to ReadOnly -func SetDefaultAccess() { +// sets default access to readonly and initializes the values for +// network admin role and org admin role +func SetDefaults(nwRoleId, oaRoleId string) { DefaultAccess = ReadOnly -} - -func SetAdminRole(nwRoleId, oaRoleId string) { networkAdminRole = nwRoleId orgAdminRole = oaRoleId } diff --git a/internal/web3ext/web3ext.go b/internal/web3ext/web3ext.go index 603b58f46..7b20abcff 100755 --- a/internal/web3ext/web3ext.go +++ b/internal/web3ext/web3ext.go @@ -34,7 +34,6 @@ var Modules = map[string]string{ "raft": Raft_JS, "istanbul": Istanbul_JS, "quorumPermission": QUORUM_NODE_JS, - "quorumOrgMgmt": QUORUM_ORG_JS, } const Chequebook_JS = ` @@ -853,76 +852,6 @@ web3._extend({ }) ` -const QUORUM_ORG_JS = ` -web3._extend({ - property: 'quorumOrgMgmt', - methods: - [ - new web3._extend.Method({ - name: 'addMasterOrg', - call: 'quorumOrgMgmt_addMasterOrg', - params: 2, - inputFormatter: [null,web3._extend.formatters.inputTransactionFormatter] - }), - new web3._extend.Method({ - name: 'addSubOrg', - call: 'quorumOrgMgmt_addSubOrg', - params: 3, - inputFormatter: [null,null,web3._extend.formatters.inputTransactionFormatter] - }), - new web3._extend.Method({ - name: 'addVoter', - call: 'quorumOrgMgmt_addOrgVoter', - params: 3, - inputFormatter: [null,null,web3._extend.formatters.inputTransactionFormatter] - }), - new web3._extend.Method({ - name: 'removeVoter', - call: 'quorumOrgMgmt_removeOrgVoter', - params: 3, - inputFormatter: [null,null,web3._extend.formatters.inputTransactionFormatter] - }), - new web3._extend.Method({ - name: 'addOrgKey', - call: 'quorumOrgMgmt_addOrgKey', - params: 3, - inputFormatter: [null,null,web3._extend.formatters.inputTransactionFormatter] - }), - new web3._extend.Method({ - name: 'removeOrgKey', - call: 'quorumOrgMgmt_removeOrgKey', - params: 3, - inputFormatter: [null,null,web3._extend.formatters.inputTransactionFormatter] - }), - new web3._extend.Method({ - name: 'approvePendingOp', - call: 'quorumOrgMgmt_approvePendingOp', - params: 2, - inputFormatter: [null,web3._extend.formatters.inputTransactionFormatter] - }), - new web3._extend.Method({ - name: 'getPendingOpDetails', - call: 'quorumOrgMgmt_getPendingOpDetails', - params: 1, - inputFormatter: [null] - }), - new web3._extend.Method({ - name: 'getOrgVoterList', - call: 'quorumOrgMgmt_getOrgVoterList', - params: 1, - inputFormatter: [null] - }), - ], - properties: - [ - new web3._extend.Property({ - name: 'orgKeyInfo', - getter: 'quorumOrgMgmt_orgKeyInfo' - }), - ] -}) -` - const Istanbul_JS = ` web3._extend({ property: 'istanbul', diff --git a/permission/contract/AccountManager.sol b/permission/contract/AccountManager.sol index 2fdaa97d0..efda6f8c8 100644 --- a/permission/contract/AccountManager.sol +++ b/permission/contract/AccountManager.sol @@ -27,12 +27,14 @@ contract AccountManager { event AccountAccessRevoked(address _address, string _orgId, string _roleId, bool _orgAdmin); event AccountStatusChanged(address _address, string _orgId, uint _status); + // checks if the caller is implementation contracts modifier onlyImpl { require(msg.sender == permUpgradable.getPermImpl()); _; } + // checks if the account is existing and part of the org modifier accountExists(string memory _orgId, address _account) { require((accountIndex[_account]) != 0, "account does not exists"); @@ -41,12 +43,12 @@ contract AccountManager { _; } + // constructor. sets the upgradable address constructor (address _permUpgradable) public { permUpgradable = PermissionsUpgradable(_permUpgradable); } - // Get account details given index - + // checks if the org is already having an org admin account function orgAdminExists(string memory _orgId) public view returns (bool) { if (orgAdminIndex[keccak256(abi.encodePacked(_orgId))] != address(0)) { @@ -57,6 +59,8 @@ contract AccountManager { } + // returns the status of input account. Returns 0 if the account is not + // existing function getAccountStatus(address _acct) internal view returns (uint) { if (accountIndex[_acct] == 0) { @@ -66,6 +70,7 @@ contract AccountManager { return (acctAccessList[aIndex].status); } + // Gets account details for a given account function getAccountDetails(address _acct) external view returns (address, string memory, string memory, uint, bool) { if (accountIndex[_acct] == 0) { @@ -75,6 +80,7 @@ contract AccountManager { return (acctAccessList[aIndex].acctId, acctAccessList[aIndex].orgId, acctAccessList[aIndex].role, acctAccessList[aIndex].status, acctAccessList[aIndex].orgAdmin); } + // Gets account details given index function getAccountDetailsFromIndex(uint aIndex) external view returns (address, string memory, string memory, uint, bool) { return (acctAccessList[aIndex].acctId, acctAccessList[aIndex].orgId, acctAccessList[aIndex].role, acctAccessList[aIndex].status, acctAccessList[aIndex].orgAdmin); @@ -86,6 +92,7 @@ contract AccountManager { return acctAccessList.length; } + // sets the default values for network admin and org admin roles function setDefaults(string calldata _nwAdminRole, string calldata _oAdminRole) external onlyImpl { @@ -93,6 +100,7 @@ contract AccountManager { orgAdminRole = _oAdminRole; } + // associates an account with a role and organization function setAccountRole(address _address, string memory _orgId, string memory _roleId, uint _status, bool _oAdmin) internal onlyImpl { @@ -108,26 +116,11 @@ contract AccountManager { accountIndex[_address] = numberOfAccts; acctAccessList.push(AccountAccessDetails(_address, _orgId, _roleId, _status, _oAdmin)); } - // if (_oAdmin) { - // orgAdminIndex[keccak256(abi.encodePacked(_orgId))] = _address; - // } emit AccountAccessModified(_address, _orgId, _roleId, _oAdmin, _status); } - // function changeOrgAdmin(address _address, string calldata _orgId, string calldata _roleId) external - // onlyImpl - // { - // // this function can ony be called from network admin to assign the org admin role to a new account - // setAccountRole(_address, _orgId, _roleId, 1, false); - // } - // - // // TODO: can we merge and remove this - // function addNWAdminAccount(address _address, string calldata _orgId) external - // onlyImpl - // { - // setAccountRole(_address, _orgId, adminRole, 2, true); - // } - + // this function can be only called for assigning org admin to network amdin roles and can be invoked by + // network admins only function assignAdminRole(address _address, string calldata _orgId, string calldata _roleId, uint _status) external onlyImpl { @@ -138,6 +131,8 @@ contract AccountManager { } + // this function can be only called for assigning any roles to accounts can be called by + // org admins only function assignAccountRole(address _address, string calldata _orgId, string calldata _roleId, bool _adminRole) external onlyImpl { @@ -145,6 +140,7 @@ contract AccountManager { setAccountRole(_address, _orgId, _roleId, 2, _adminRole); } + // this function removes an existing org admin from the admin role function removeExistingAdmin(string calldata _orgId) external onlyImpl returns (bool voterUpdate, address acct) @@ -160,7 +156,7 @@ contract AccountManager { return (false, address(0)); } - + // this function associates a new account with org or network admin role function addNewAdmin(string calldata _orgId, address _address) external onlyImpl returns (bool voterUpdate) @@ -180,17 +176,8 @@ contract AccountManager { return (keccak256(abi.encodePacked(acctAccessList[id].role)) == keccak256(abi.encodePacked(adminRole))); } - function revokeAccountRole(address _address) external - onlyImpl - { - // Check if account already exists - uint aIndex = getAcctIndex(_address); - if (accountIndex[_address] != 0) { - acctAccessList[aIndex].status = 3; - emit AccountAccessRevoked(_address, acctAccessList[aIndex].orgId, acctAccessList[aIndex].role, acctAccessList[aIndex].orgAdmin); - } - } - + // this function can be called for updating the account status suspending or blaclisting an account + // and for revoking suspension of an account function updateAccountStatus(string calldata _orgId, address _account, uint _status) external onlyImpl accountExists(_orgId, _account) @@ -219,6 +206,7 @@ contract AccountManager { emit AccountStatusChanged(_account, _orgId, newStat); } + // returns the account role function getAccountRole(address _acct) public view returns (string memory) { if (accountIndex[_acct] == 0) { @@ -233,6 +221,8 @@ contract AccountManager { } } + // checks if the account is a org admin for the passed organization or for the ultimate + // parent organization function checkOrgAdmin(address _acct, string memory _orgId, string memory _ultParent) public view returns (bool) { // check if the account role is network admin. If yes return success diff --git a/permission/contract/NodeManager.sol b/permission/contract/NodeManager.sol index 201aec33c..54d494b3b 100644 --- a/permission/contract/NodeManager.sol +++ b/permission/contract/NodeManager.sol @@ -2,7 +2,6 @@ pragma solidity ^0.5.3; import "./PermissionsUpgradable.sol"; - contract NodeManager { PermissionsUpgradable private permUpgradable; // enum and struct declaration @@ -36,6 +35,7 @@ contract NodeManager { // node permission events for node blacklist event NodeBlacklisted(string _enodeId, string _orgId); + // checks if the caller is implementation contracts modifier onlyImpl { require(msg.sender == permUpgradable.getPermImpl()); @@ -56,6 +56,7 @@ contract NodeManager { _; } + // constructor. sets the upgradable address constructor (address _permUpgradable) public { permUpgradable = PermissionsUpgradable(_permUpgradable); } @@ -66,11 +67,13 @@ contract NodeManager { uint nodeIndex = getNodeIndex(enodeId); return (nodeList[nodeIndex].orgId, nodeList[nodeIndex].enodeId, nodeList[nodeIndex].status); } + // Get node details given index function getNodeDetailsFromIndex(uint nodeIndex) public view returns (string memory _orgId, string memory _enodeId, uint _nodeStatus) { return (nodeList[nodeIndex].orgId, nodeList[nodeIndex].enodeId, nodeList[nodeIndex].status); } + // Get number of nodes function getNumberOfNodes() public view returns (uint) { @@ -85,7 +88,8 @@ contract NodeManager { } return nodeList[getNodeIndex(_enodeId)].status; } - //TODO - can the duplicacy in next 3 functions removed? + + // called at the time of initialization for adding admin nodes function addAdminNode(string calldata _enodeId, string calldata _orgId) external onlyImpl enodeNotInList(_enodeId) @@ -94,7 +98,9 @@ contract NodeManager { nodeIdToIndex[keccak256(abi.encodePacked(_enodeId))] = numberOfNodes; nodeList.push(NodeDetails(_enodeId, _orgId, 2)); } - // TODO: addNode should be external + + // called at the time of new org creation. will need approval for the node to be + // part of the network function addNode(string memory _enodeId, string memory _orgId) public onlyImpl enodeNotInList(_enodeId) @@ -105,6 +111,7 @@ contract NodeManager { emit NodeProposed(_enodeId, _orgId); } + // can be called by org admins to add new nodes to the org or sub orgs function addOrgNode(string calldata _enodeId, string calldata _orgId) external onlyImpl enodeNotInList(_enodeId) @@ -115,7 +122,7 @@ contract NodeManager { emit NodeApproved(_enodeId, _orgId); } - // Adds a node to the nodeList mapping and emits node added event if successfully and node exists event of node is already present + // updates the node status to approved and emits the event function approveNode(string memory _enodeId, string memory _orgId) public onlyImpl enodeInList(_enodeId) @@ -129,6 +136,8 @@ contract NodeManager { emit NodeApproved(nodeList[nodeIndex].enodeId, nodeList[nodeIndex].orgId); } + // updates the node status. Used for deactivating or blacklisting a node and reactivating + // a deactivated node function updateNodeStatus(string calldata _enodeId, string calldata _orgId, uint _status) external onlyImpl enodeInList(_enodeId) @@ -156,12 +165,14 @@ contract NodeManager { } /* private functions */ + // returs the node index for given node id function getNodeIndex(string memory _enodeId) internal view returns (uint) { return nodeIdToIndex[keccak256(abi.encodePacked(_enodeId))] - 1; } + // checks if the node is linked to the passed org function checkOrg(string memory _enodeId, string memory _orgId) internal view returns (bool) { diff --git a/permission/contract/OrgManager.sol b/permission/contract/OrgManager.sol index 4ee5ecb2b..87d06a082 100644 --- a/permission/contract/OrgManager.sol +++ b/permission/contract/OrgManager.sol @@ -7,6 +7,8 @@ contract OrgManager { PermissionsUpgradable private permUpgradable; // checks if first time network boot up has happened or not bool private networkBoot = false; + + // variables which control the breadth and depth of the sub org tree uint private DEPTH_LIMIT = 4; uint private BREADTH_LIMIT = 4; // enum OrgStatus {0- NotInList, 1- Proposed, 2- Approved, 3- PendingSuspension, 4- Suspended, 5- RevokeSuspension} @@ -31,6 +33,7 @@ contract OrgManager { event OrgSuspended(string _orgId, string _porgId, string _ultParent, uint _level); event OrgSuspensionRevoked(string _orgId, string _porgId, string _ultParent, uint _level); + // checks if the caller is implementation contracts modifier onlyImpl { require(msg.sender == permUpgradable.getPermImpl()); @@ -47,14 +50,18 @@ contract OrgManager { _; } + // constructor. sets the upgradable address constructor (address _permUpgradable) public { permUpgradable = PermissionsUpgradable(_permUpgradable); } + // returns the implementation contract address function getImpl() public view returns (address) { return permUpgradable.getPermImpl(); } + // called at the time of network init to set the depth breadth and create the + // default network admin org as per config file function setUpOrg(string calldata _orgId, uint _breadth, uint _depth) external onlyImpl { @@ -63,6 +70,7 @@ contract OrgManager { BREADTH_LIMIT = _breadth; } + // function to add a new organization function addNewOrg(string memory _pOrg, string memory _orgId, uint _level, uint _status) internal { bytes32 pid = ""; @@ -107,6 +115,7 @@ contract OrgManager { } } + // returns the number of orgs function getNumberOfOrgs() public view returns (uint) { return orgList.length; @@ -132,7 +141,7 @@ contract OrgManager { addNewOrg("", _orgId, 1, 1); } - // function for adding a new master org + // function for adding a sub org under a master org function addSubOrg(string calldata _pOrg, string calldata _orgId) external onlyImpl orgNotExists(string(abi.encodePacked(_pOrg, ".", _orgId))) @@ -140,6 +149,8 @@ contract OrgManager { addNewOrg(_pOrg, _orgId, 2, 2); } + // updates the status of an org for master orgs. The new status + // is valid once majority approval is achieved function updateOrg(string calldata _orgId, uint _status) external onlyImpl orgExists(_orgId) @@ -169,6 +180,7 @@ contract OrgManager { return pendingOp; } + // function to approve org status change function approveOrgStatusUpdate(string calldata _orgId, uint _status) external onlyImpl orgExists(_orgId) @@ -182,7 +194,7 @@ contract OrgManager { } - // function for adding a new master org + // updates the status of org as suspended function suspendOrg(string memory _orgId) internal { require(checkOrgStatus(_orgId, 2) == true, "Org not in approved state"); @@ -191,6 +203,7 @@ contract OrgManager { emit OrgPendingApproval(orgList[id].orgId, orgList[id].parentId, orgList[id].ultParent, orgList[id].level, 3); } + // revokes the suspension of an org function revokeOrgSuspension(string memory _orgId) internal { @@ -200,6 +213,7 @@ contract OrgManager { emit OrgPendingApproval(orgList[id].orgId, orgList[id].parentId, orgList[id].ultParent, orgList[id].level, 5); } + // approval for new org add function approveOrg(string calldata _orgId) external onlyImpl { @@ -209,6 +223,7 @@ contract OrgManager { emit OrgApproved(orgList[id].orgId, orgList[id].parentId, orgList[id].ultParent, orgList[id].level, 2); } + // approval for org suspension function approveOrgSuspension(string memory _orgId) internal { require(checkOrgStatus(_orgId, 3) == true, "Nothing to approve"); @@ -217,6 +232,7 @@ contract OrgManager { emit OrgSuspended(orgList[id].orgId, orgList[id].parentId, orgList[id].ultParent, orgList[id].level); } + // approval for org suspension revoke function approveOrgRevokeSuspension(string memory _orgId) internal { require(checkOrgStatus(_orgId, 5) == true, "Nothing to approve"); @@ -225,34 +241,31 @@ contract OrgManager { emit OrgSuspensionRevoked(orgList[id].orgId, orgList[id].parentId, orgList[id].ultParent, orgList[id].level); } + // confirms that org status is same as passed status function checkOrgStatus(string memory _orgId, uint _orgStatus) public view returns (bool){ uint id = getOrgIndex(_orgId); return ((OrgIndex[keccak256(abi.encodePacked(_orgId))] != 0) && orgList[id].status == _orgStatus); } - // function to check if morg exists + // function to check if org exists function checkOrgExists(string memory _orgId) public view returns (bool) { return (!(OrgIndex[keccak256(abi.encodePacked(_orgId))] == 0)); } - // function to check if morg exists - function checkNodeExists(string memory _pOrg, string memory _orgId) public view returns (bool) - { - return (!(OrgIndex[keccak256(abi.encodePacked(_pOrg, _orgId))] == 0)); - } - - // returns org and master org details based on org index + // returns org details based on org index function getOrgInfo(uint _orgIndex) external view returns (string memory, string memory, string memory, uint, uint) { return (orgList[_orgIndex].orgId, orgList[_orgIndex].parentId, orgList[_orgIndex].ultParent, orgList[_orgIndex].level, orgList[_orgIndex].status); } + // returns the sub org info based on index function getSubOrgInfo(uint _orgIndex) external view returns (uint[] memory) { return orgList[_orgIndex].subOrgIndexList; } + // returns total numbers of sub orgs under a org or sub org function getSubOrgIndexLength(uint _orgIndex) external view returns (uint) { return orgList[_orgIndex].subOrgIndexList.length; @@ -263,6 +276,7 @@ contract OrgManager { return orgList[_orgIndex].subOrgIndexList[_subOrgIndex]; } + // returns the master org id for the given org function getUltimateParent(string calldata _orgId) external view returns (string memory) { return orgList[getOrgIndex(_orgId)].ultParent; diff --git a/permission/contract/PermissionsImplementation.sol b/permission/contract/PermissionsImplementation.sol index 2fd2ab626..bbf7d1310 100644 --- a/permission/contract/PermissionsImplementation.sol +++ b/permission/contract/PermissionsImplementation.sol @@ -37,32 +37,38 @@ contract PermissionsImplementation { require(networkBoot == _status, "Incorrect network boot status"); _; } + + // checks if the account is a network admin modifier networkAdmin(address _account) { require(isNetworkAdmin(_account) == true, "Not an network admin"); _; } + // checks if the account is a org admin modifier orgAdmin(address _account, string memory _orgId) { require(isOrgAdmin(_account, _orgId) == true, "Not an org admin"); _; } + // checks if the org does not exists modifier orgNotExists(string memory _orgId) { require(checkOrgExists(_orgId) != true, "Org already exists"); _; } - + // checks if the org does exists modifier orgExists(string memory _orgId) { require(checkOrgExists(_orgId) == true, "Org does not exists"); _; } + // checks if the org is approved modifier orgApproved(string memory _orgId) { require(checkOrgApproved(_orgId) == true, "Org not approved"); _; } + // constructor. sets the upgradable address constructor (address _permUpgradable) public { permUpgradable = PermissionsUpgradable(_permUpgradable); } @@ -78,6 +84,7 @@ contract PermissionsImplementation { orgAdminRole = _oAdminRole; } + // called at the time network initialization to link all the contracts and set defaults function init(address _orgManager, address _rolesManager, address _acctManager, address _voterManager, address _nodeManager, uint _breadth, uint _depth) external onlyProxy networkBootStatus(false) @@ -93,6 +100,7 @@ contract PermissionsImplementation { accounts.setDefaults(adminRole, orgAdminRole); } + // function to add admin node as a part of network boot up function addAdminNodes(string calldata _enodeId) external onlyProxy networkBootStatus(false) @@ -100,6 +108,7 @@ contract PermissionsImplementation { nodes.addAdminNode(_enodeId, adminOrg); } + // function to add admin accounts as a part of network boot up function addAdminAccounts(address _acct) external onlyProxy networkBootStatus(false) @@ -118,6 +127,7 @@ contract PermissionsImplementation { return networkBoot; } + // functions to add a new org to the network function addOrg(string calldata _orgId, string calldata _enodeId, address _account, address _caller) external onlyProxy networkBootStatus(true) @@ -130,6 +140,7 @@ contract PermissionsImplementation { accounts.assignAdminRole(_account, _orgId, orgAdminRole, 1); } + // functions to approve a new org into the network function approveOrg(string calldata _orgId, string calldata _enodeId, address _account, address _caller) external onlyProxy networkAdmin(_caller) @@ -143,7 +154,7 @@ contract PermissionsImplementation { } } - // function for adding a new master org + // function for adding a new sub org under a master org or another sub org function addSubOrg(string calldata _pOrg, string calldata _orgId, string calldata _enodeId, address _account, address _caller) external orgExists(_pOrg) orgAdmin(_caller, _pOrg) @@ -159,6 +170,7 @@ contract PermissionsImplementation { } } + // function to update the org status function updateOrgStatus(string calldata _orgId, uint _status, address _caller) external onlyProxy networkAdmin(_caller) @@ -168,6 +180,7 @@ contract PermissionsImplementation { voter.addVotingItem(adminOrg, _orgId, "", address(0), pendingOp); } + // function to approve the org status update function approveOrgStatus(string calldata _orgId, uint _status, address _caller) external onlyProxy networkAdmin(_caller) @@ -187,6 +200,8 @@ contract PermissionsImplementation { } // Role related functions + + // function to add a new role ot a org function addNewRole(string calldata _roleId, string calldata _orgId, uint _access, bool _voter, bool _admin, address _caller) external onlyProxy orgApproved(_orgId) @@ -196,6 +211,7 @@ contract PermissionsImplementation { roles.addRole(_roleId, _orgId, _access, _voter, _admin); } + // function to remove a role from an org function removeRole(string calldata _roleId, string calldata _orgId, address _caller) external onlyProxy orgApproved(_orgId) @@ -207,6 +223,7 @@ contract PermissionsImplementation { } // Account related functions + // function to assign network admin role. can be called by network admin only function assignAdminRole(string calldata _orgId, address _account, string calldata _roleId, address _caller) external onlyProxy orgExists(_orgId) @@ -217,6 +234,7 @@ contract PermissionsImplementation { voter.addVotingItem(adminOrg, _orgId, "", _account, 4); } + // function to approve admin role assignment to an account function approveAdminRole(string calldata _orgId, address _account, address _caller) external onlyProxy networkAdmin(_caller) @@ -233,6 +251,7 @@ contract PermissionsImplementation { } } + // function to assign role and org to an account function assignAccountRole(address _acct, string memory _orgId, string memory _roleId, address _caller) public onlyProxy orgAdmin(_caller, _orgId) @@ -244,6 +263,7 @@ contract PermissionsImplementation { accounts.assignAccountRole(_acct, _orgId, _roleId, admin); } + // function to update the account status function updateAccountStatus(string calldata _orgId, address _account, uint _status, address _caller) external onlyProxy orgAdmin(_caller, _orgId) @@ -252,6 +272,8 @@ contract PermissionsImplementation { } // Node related functions + + // function to add node function addNode(string calldata _orgId, string calldata _enodeId, address _caller) external onlyProxy orgApproved(_orgId) @@ -261,6 +283,7 @@ contract PermissionsImplementation { nodes.addOrgNode(_enodeId, _orgId); } + // function to udpate node status function updateNodeStatus(string calldata _orgId, string calldata _enodeId, uint _status, address _caller) external onlyProxy orgAdmin(_caller, _orgId) @@ -276,6 +299,7 @@ contract PermissionsImplementation { } // Voter related functions + // function to add new network admin account to network level voter list function updateVoterList(string memory _orgId, address _account, bool _add) internal { if (_add) { @@ -286,12 +310,15 @@ contract PermissionsImplementation { } } + // function to process vote function processVote(string memory _orgId, address _caller, uint _pendingOp) internal returns (bool) { return voter.processVote(_orgId, _caller, _pendingOp); } + // returns pending approval operation at network admin org level. at any time + // only one pending op is allowed function getPendingOp(string calldata _orgId) external view returns (string memory, string memory, address, uint) { diff --git a/permission/contract/PermissionsUpgradable.sol b/permission/contract/PermissionsUpgradable.sol index faa3d1177..49e71f8a4 100644 --- a/permission/contract/PermissionsUpgradable.sol +++ b/permission/contract/PermissionsUpgradable.sol @@ -8,6 +8,8 @@ contract PermissionsUpgradable { address private permImpl; address private permInterface; + // sets the custodian account as part of constructor + // only this account will be able to change the implementation contract address constructor (address _custodian) public { custodian = _custodian; @@ -18,6 +20,7 @@ contract PermissionsUpgradable { _; } + // executed by custodian, links interface and implementation contract addresses function init(address _permInterface, address _permImpl) external onlyCustodian { diff --git a/permission/contract/RoleManager.sol b/permission/contract/RoleManager.sol index 4cc87b552..7cb1f80c9 100644 --- a/permission/contract/RoleManager.sol +++ b/permission/contract/RoleManager.sol @@ -32,6 +32,7 @@ contract RoleManager { permUpgradable = PermissionsUpgradable(_permUpgradable); } + // checks if the role is active or not function roleExists(string memory _roleId, string memory _orgId, string memory _ultParent) public view returns (bool) { uint id; @@ -46,6 +47,7 @@ contract RoleManager { return false; } + // returns the roles details for a given role id and org id function getRoleDetails(string calldata _roleId, string calldata _orgId) external view returns (string memory roleId, string memory orgId, uint accessType, bool voter, bool active) { if (!(roleExists(_roleId, _orgId, ""))) { @@ -55,6 +57,7 @@ contract RoleManager { return (roleList[rIndex].roleId, roleList[rIndex].orgId, roleList[rIndex].baseAccess, roleList[rIndex].isVoter, roleList[rIndex].active); } + // returns the role details for a given index function getRoleDetailsFromIndex(uint rIndex) external view returns (string memory roleId, string memory orgId, uint accessType, bool voter, bool admin, bool active) { return (roleList[rIndex].roleId, roleList[rIndex].orgId, roleList[rIndex].baseAccess, roleList[rIndex].isVoter, roleList[rIndex].isAdmin, roleList[rIndex].active); @@ -66,6 +69,7 @@ contract RoleManager { return roleList.length; } + // function to add a new role function addRole(string memory _roleId, string memory _orgId, uint _baseAccess, bool _voter, bool _admin) public { // Check if account already exists @@ -77,6 +81,7 @@ contract RoleManager { } } + // function to remove a role function removeRole(string calldata _roleId, string calldata _orgId) external { if (roleIndex[keccak256(abi.encodePacked(_roleId, _orgId))] != 0) { uint rIndex = getRoleIndex(_roleId, _orgId); @@ -90,7 +95,7 @@ contract RoleManager { return roleIndex[keccak256(abi.encodePacked(_roleId, _orgId))] - 1; } - + // checks if the role has full access function isFullAccessRole(string calldata _roleId, string calldata _orgId, string calldata _ultParent) external view returns (bool){ if (!(roleExists(_roleId, _orgId, _ultParent))) { return false; @@ -105,6 +110,7 @@ contract RoleManager { return (roleList[rIndex].active && roleList[rIndex].baseAccess == 3); } + // checks if the role is a voter role function isVoterRole(string calldata _roleId, string calldata _orgId, string calldata _ultParent) external view returns (bool){ if (!(roleExists(_roleId, _orgId, _ultParent))) { return false; @@ -119,6 +125,7 @@ contract RoleManager { return (roleList[rIndex].active && roleList[rIndex].isVoter); } + // checks if the role is admin role function isAdminRole(string calldata _roleId, string calldata _orgId, string calldata _ultParent) external view returns (bool){ if (!(roleExists(_roleId, _orgId, _ultParent))) { return false; diff --git a/permission/contract/VoterManager.sol b/permission/contract/VoterManager.sol index 5ddb43963..dbf74983a 100644 --- a/permission/contract/VoterManager.sol +++ b/permission/contract/VoterManager.sol @@ -51,6 +51,7 @@ contract VoterManager { _; } + // constructor. sets the upgradable address constructor (address _permUpgradable) public { permUpgradable = PermissionsUpgradable(_permUpgradable); } @@ -62,7 +63,7 @@ contract VoterManager { return orgVoterList[orgIndex].voterIndex[_vAccount] - 1; } - // returns the master org index for the org from voter list + // returns the org index for the org from voter list function getVoterOrgIndex(string memory _orgId) internal view returns (uint) { return VoterOrgIndex[keccak256(abi.encodePacked(_orgId))] - 1; diff --git a/permission/permission.go b/permission/permission.go index 742c7717f..903237b42 100644 --- a/permission/permission.go +++ b/permission/permission.go @@ -72,8 +72,7 @@ func (p *PermissionCtrl) Interface() *pbind.PermInterface { return p.permInterf } -// This function takes the local config data where all the information is in string -// converts that to address and populates the global permissions config +// converts local permissions data to global permissions config func populateConfig(config PermissionLocalConfig) types.PermissionConfig { var permConfig types.PermissionConfig permConfig.UpgrdAddress = common.HexToAddress(config.UpgrdAddress) @@ -99,7 +98,7 @@ func populateConfig(config PermissionLocalConfig) types.PermissionConfig { return permConfig } -// this function reads the permissions config file passed and populates the +// function reads the permissions config file passed and populates the // config structure accrodingly func ParsePermissionConifg(dir string) (types.PermissionConfig, error) { fileName := "permission-config.json" @@ -134,6 +133,9 @@ func ParsePermissionConifg(dir string) (types.PermissionConfig, error) { return permConfig, nil } +// for cases where the node is joining an existing network, permissioning +// service can be brought up only after block syncing is complete. This function +// waits for block syncing before the starting permissions func waitForSync(e *eth.Ethereum) { for !types.GetSyncStatus() { time.Sleep(10 * time.Millisecond) @@ -210,8 +212,7 @@ func NewQuorumPermissionCtrl(stack *node.Node, permissionedMode, isRaft bool, pc }, nil } -// Starts the node permissioning and event monitoring for permissions -// smart contracts +// Starts monitoring service for permissions events at contract level func (p *PermissionCtrl) Start() error { // Permissions initialization if err := p.init(); err != nil { @@ -242,14 +243,13 @@ func (p *PermissionCtrl) init() error { } // set the default access to ReadOnly - types.SetDefaultAccess() - types.SetAdminRole(p.permConfig.NwAdminRole, p.permConfig.OrgAdminRole) + types.SetDefaults(p.permConfig.NwAdminRole, p.permConfig.OrgAdminRole) return nil } -// monitors org management related events happening via -// smart contracts +// monitors org management related events happening via smart contracts +// and updates cache accordingly func (p *PermissionCtrl) manageOrgPermissions() { chPendingApproval := make(chan *pbind.OrgManagerOrgPendingApproval, 1) @@ -361,7 +361,8 @@ func (p *PermissionCtrl) manageNodePermissions() { } } -// Populates the new node information into the permissioned-nodes.json file +// updates node information in the permissioned-nodes.json file based on node +// management activities in smart contract func (p *PermissionCtrl) updatePermissionedNodes(enodeId string, operation NodeOperation) { log.Debug("updatePermissionedNodes", "DataDir", p.dataDir, "file", params.PERMISSIONED_CONFIG) @@ -524,7 +525,7 @@ func (p *PermissionCtrl) disconnectNode(enodeId string) { } } -// Thus function checks if the its the initial network boot up status and if no +// Thus function checks if the initial network boot up status and if no // populates permissioning model with details from permission-config.json func (p *PermissionCtrl) populateInitPermissions() error { auth := bind.NewKeyedTransactor(p.key)