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 instance
- executor - Executor: Executor instance
- nameResolver - NameResolver: NameResolver instance
- web3 - Web3: Web3 instance
- log - Function (optional): function to use for logging: (message, level) => {...}
- logLevel - LogLevel (optional): messages with this level will be logged with log
- logLog - LogLogInterface (optional): container for collecting log messages
- logLogLevel - LogLevel (optional): messages with this level will be pushed to logLog

Returns¶

RightsAndRoles instance

Example¶

const rightsAndRoles = new RightsAndRoles({
  contractLoader,
  executor,
  nameResolver,
  web3,
});

addAccountToRole¶

rightsAndRoles.addAccountToRole(contract, accountId, targetAccountId, role);

Adds the target identity or account to a specific role.

The main principle is that an identity or account 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 identity or account belongs to a certain role. To add an identity or account to the role ‘member’.

Parameters¶

contract - string|any: contractId or contract instance
accountId - string: executing identity or account
targetAccountId - string: target identity or account
role - 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 identity or account from a specific role.

Parameters¶

contract - string|any: contractId or contract instance
accountId - string: executing identity or account
targetAccountId - string: target identity or account
role - 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 identity or 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 identity or account.

“Function permissions” are granted or denied 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 instance
accountId - string: executing identity or account
role - number: role id
functionSignature - string: 4 Bytes function signature
allow - 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 instance
accountId - string: executing identity or account
role - number: roleId
propertyName - string: target property name
propertyType - PropertyType: list or entry
modificationType - ModificationType: set or remove
allow - 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 identity or account has the specific role.

Parameters¶

contract - string|any: contractId or contract instance
accountId - string: executing accountId
targetAccountId - string: to be checked accountId
role - 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 instance
accountId - string: executing identity or account
targetAccountId - string: target identity or account

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
);