Permissions

How to Apply Permissions to other accounts for Holding or Managing your Security Tokens

GitHub - PolymathNetwork/permissions: A demo app of permission management on Polymath networkGitHub

👀 Overview

This tutorial application allows token owners (as well as privileged delegates) to manage different permissions on their security token. Permissions are structured per-feature. This means that, for example, you can assign a delegate for the Tokenholders feature, and said delegate will be able to perform actions related to that feature (permissions themselves are a feature, so you can assign a delegate to be able to assign other delegates). We will cover how to load and manage the status of available features per delegate.

🗄️ Loading roles & permissions

Loading data asynchronously via the SDK can be accomplished via an async action.

import { Feature } from '@polymathnetwork/sdk'
const PERMISSIONS_FEATURE = Feature.Permissions

...

function App() {

  ...

  // Load features status / available roles
  useEffect(() => {
    async function getFeaturesStatus() {
      const featuresStatus = await token.features.getStatus()
      let availableRoles = []
      const pmEnabled = featuresStatus[PERMISSIONS_FEATURE]
      delete featuresStatus[PERMISSIONS_FEATURE]
      // If permissions feature is enabled, load available roles.
      if (pmEnabled) {
        availableRoles = await token.permissions.getAvailableRoles()
      }
      return {
        availableRoles, features: featuresStatus, pmEnabled
      }
    }
    // Do NOT attempt to load features UNLESS a token is selected AND we haven't loaded features, previously.
    if (token && !features) {
      asyncAction(dispatch, () => getFeaturesStatus(), 'Loading features status')
    }
  }, [dispatch, features, token])
  ...
}

Below is the core component loading the status of token features.

const featuresStatus = await token.features.getStatus()

If the permissions feature is enabled, all available roles from currently enabled features will load.

In this tutorial, we need "Permissions" feature enabled, so let's enable it in case it is disabled

if (!featuresStatus[PERMISSIONS_FEATURE]) {
    await (await token.features.enable({feature: PERMISSIONS_FEATURE})).run()
}

🙋‍♂️ Managing delegates

You can assign various roles to delegates of your choice:

token.permissions.assignRole({ 
    '0xALICEADDRESS',
    SecurityTokenRole.TokenholdersAdministrator,
    'Adding Alice as a tokenholder admin by Bob'
})

The assignRole function expects the following:

delegateAddress: the Ethereum address of an existing or a new delegate. Note that you don't need to manage delegates and roles separately. If you happen to assign a role to a new delegateAddress , it's added behind the scenes.

role: role represents a feature-specific set of permissions. For instance, an administrator of tokenholders requires a TokenholdersAdministrator role. See available security token roles here.

description: this is an optional note you can keep to describe a delegate when assigning a role to them (for example, their name or role in your company).

You can revoke a role by specifying a delegate and the role you need revoked:

token.permissions.revokeRole({ 
    '0xALICEADDRESS',
    SecurityTokenRole.TokenholdersAdministrator,
})