Rights and Roles¶
Class Name | RightsAndRoles |
---|---|
Extends | Logger |
Source | rights-and-roles.ts |
Examples | rights-and-roles.spec.ts |
The RightsAndRoles module follows the approach described in the evan.network wik at:
It allows to manage permissions for contracts, that use the authority DSRolesPerContract.sol for as its permission approach.
Contracts, that use DSRolesPerContract and therefore allow to configure its permissions with the RightsAndRoles
module are:
Also have a look at the Smart Contract Permissioning section in the evan.network wiki.
constructor¶
new RightsAndRole(options);
Creates new RightsAndRole instance.
Parameters¶
options
-RightsAndRolesOptions
: options for RightsAndRole constructor.contractLoader
-ContractLoader
:ContractLoader
instanceexecutor
-Executor
:Executor
instancenameResolver
-NameResolver
:NameResolver
instanceweb3
-Web3
:Web3
instancelog
-Function
(optional): function to use for logging:(message, level) => {...}
logLevel
-LogLevel
(optional): messages with this level will be logged withlog
logLog
-LogLogInterface
(optional): container for collecting log messageslogLogLevel
-LogLevel
(optional): messages with this level will be pushed tologLog
Returns¶
RightsAndRoles
instance
Example¶
const rightsAndRoles = new RightsAndRoles({
contractLoader,
executor,
nameResolver,
web3,
});
addAccountToRole¶
rightsAndRoles.addAccountToRole(contract, accountId, targetAccountId, role);
Adds the traget account to a specific role.
The main principle is that accounts can be assigned to roles and those roles can be granted capabilities. Function Permissions are basically the capability to call specific functions if the calling account belongs to a certain role. To add an account to the role ‘member’.
Parameters¶
contract
-string|any
: contractId or contract instanceaccountId
-string
: executing accountIdtargetAccountId
-string
: target accountIdrole
-number
: roleId
Returns¶
Promise
returns void
: resolved when done
Example¶
const contractOwner = '0x0000000000000000000000000000000000000001';
const newMember = '0x0000000000000000000000000000000000000002';
const memberRole = 1;
await rightsAndRoles.addAccountToRole(
contract, // contract to be updated
contractOwner, // account, that can change permissions
newMember, // add this account to role
memberRole, // role id, uint8 value
);
removeAccountFromRole¶
rightsAndRoles.removeAccountFromRole(contract, accountId, targetAccountId, role);
Removes target account from a specific role.
Parameters¶
contract
-string|any
: contractId or contract instanceaccountId
-string
: executing accountIdtargetAccountId
-string
: target accountIdrole
-number
: roleId
Returns¶
Promise
returns void
: resolved when done
Example¶
const contractOwner = '0x0000000000000000000000000000000000000001';
const newMember = '0x0000000000000000000000000000000000000002';
const memberRole = 1;
await rightsAndRoles.removeAccountFromRole(
contract, // contract to be updated
contractOwner, // account, that can change permissions
newMember, // remove this account from role
memberRole, // role id, uint8 value
);
getMembers¶
rightsAndRoles.getMembers(contract);
Returns all roles with all members.
The DSRolesPerContract authority tracks used roles and their members and allows to retrieve an overview with all roles and their members. To get this information, you can use the getMembes
function.
Parameters¶
contract
-string|any
: contractId or contract instance
Returns¶
Promise
returns any
: Object with mapping roleId -> [accountId, accountId,…]
Example¶
const members = await rightsAndRoles.getMembers(contract);
console.log(members);
// Output:
// {
// "0": [
// "0x0000000000000000000000000000000000000001"
// ],
// "1": [
// "0x0000000000000000000000000000000000000001",
// "0x0000000000000000000000000000000000000002"
// ]
// }
The contract from this example has an owner (0x0000000000000000000000000000000000000001
) and a member (0x0000000000000000000000000000000000000002
). As the owner account has the member role as well, it is listed among the members.
setFunctionPermission¶
rightsAndRoles.setFunctionPermission(contract, accountId, role, functionSignature, allow);
Allows or denies contract function for the accountId.
“Function permissions” are granted or denying by allowing a certain role to execute a specific function. The function is specified as the unhashed function selector and must follow its guidelines (no spaces, property typenames, etc.) for the function to be able to generate valid hashes for later validations. E.g. to grant the role “member” the permission to use the function addListEntries, that has two arguments (a bytes32
array and a bytes32
value), the function permission for addListEntries(bytes32[],bytes32[])
has to be granted.
Parameters¶
contract
-string|any
: contractId or contract instanceaccountId
-string
: executing accountIdrole
-number
: roleidfunctionSignature
-string
: 4 Bytes function signatureallow
-boolean
: allow or deny function
Returns¶
Promise
returns void
: resolved when done
Example¶
const contractOwner = '0x0000000000000000000000000000000000000001';
const memberRole = 1;
await rightsAndRoles.setFunctionPermission(
contract, // contract to be updated
contractOwner, // account, that can change permissions
memberRole, // role id, uint8 value
'addListEntries(bytes32[],bytes32[])', // (unhashed) function selector
true, // grant this capability
);
setOperationPermission¶
rightsAndRoles.setOperationPermission(contract, accountId, role, propertyName, propertyType, modificationType, allow);
Allows or denies setting properties on a contract.
“Operation Permissions” are capabilities granted per contract logic. They have a bytes32
key, that represents the capability, e.g. in a DataContract a capability to add values to a certain list can be granted.
The way, those capability hashes are build, depends on the contract logic and differs from contract to contract. For example a capability check for validation if a member is allowed to add an item to the list “example” in a DataContract has four arguments, in this case:
- which role is allowed to do? (e.g. a member)
- what type of element is modified? (–> a list)
- which element is modified? (name of the list –> “example”)
- type of the modification (–> “set an item” (== “add an item”))
These four values are combined into one bytes32
value, that is used when granting or checking permissions, the setOperationPermission
function takes care of that.
Parameters¶
contract
-string|any
: contractId or contract instanceaccountId
-string
: executing accountIdrole
-number
: roleIdpropertyName
-string
: target property namepropertyType
-PropertyType
: list or entrymodificationType
-ModificationType
: set or removeallow
-boolean
: allow or deny
Returns¶
Promise
returns void
: resolved when done
Example¶
// make sure, you have required the enums from rights-and-roles.ts
import { ModificationType, PropertyType } from '@evan.network/api-blockchain-core';
const contractOwner = '0x0000000000000000000000000000000000000001';
const memberRole = 1;
await rightsAndRoles.setOperationPermission(
contract, // contract to be updated
contractOwner, // account, that can change permissions
memberRole, // role id, uint8 value
'example', // name of the object
PropertyType.ListEntry, // what type of element is modified
ModificationType.Set, // type of the modification
true, // grant this capability
);
hasUserRole¶
rightsAndRoles.hasUserRole(contract, accountId, targetAccountId, role);
Returns true or false, depending on if the account has the specific role.
Parameters¶
contract
-string|any
: contractId or contract instanceaccountId
-string
: executing accountIdtargetAccountId
-string
: to be checked accountIdrole
-number
: roleId
Returns¶
Promise
returns void
: resolved when done
Example¶
const accountToCheck = '0x0000000000000000000000000000000000000002';
const memberRole = 1;
const hasRole = await rightsAndRoles.hashUserRole(contract, null, accountToCheck, memberRole);
console.log(hasRole);
// Output:
// true
transferOwnership¶
rightsAndRoles.transferOwnership();
Function description
Parameters¶
contract
-string|any
: contractId or contract instanceaccountId
-string
: executing accountIdtargetAccountId
-string
: target accountId
Returns¶
Promise
returns void
: resolved when done
Example¶
const contractOwner = '0x0000000000000000000000000000000000000001';
const newOwner = '0x0000000000000000000000000000000000000002';
await rightsAndRoles.transferOwnership(
contract, // contract to be updated
contractOwner, // current owner
newOwner, // this account becomes new owner
);