Introduction to Permissions

A brief explanation of role-based & resource permissions for Peerplays objects.

1. Types of Permissions in Peerplays

There are three functions available in the CLI Wallet to produce permission settings:

1. create_custom_permission

2. create_custom_account_authority

3. create_account_role

The first two functions deal with creating Hierarchical Role-based Permissions (HRP). The third is used to provide resource permissions with account roles.

HRP is a feature of the Peerplays blockchain which helps to increase the security of user accounts. Users don’t have to use their active and owner keys for everything they do on the chain. Instead, they can create role based custom permissions and map them to different keys other than active and owner keys. They can then use these custom keys to sign transactions.

As opposed to HRP mentioned above, resource permissions are controlled by the owner of a resource (such as NFT metadata). These are similar to IAM permissions in an AWS Cloud environment.

2. Hierarchical Role-based Permissions (HRP)

To create a custom HRP, the first step is to create the custom permission. Then the custom permission will be mapped to the actual operations present on the blockchain by creating a related custom account authority.

Some of the following functions need Operation IDs. You can find a list of Operation IDs here.

2.1. create_custom_permission

This function creates a new custom permission.

return type, namespace, & method

signed_transaction graphene::wallet::wallet_api::create_custom_permission(
    string owner, 
    string permission_name, 
    authority auth, 
    bool broadcast)

Function Call

The basic structure of the create_custom_permission function looks like this:

When using the cli_wallet...

create_custom_permission <owner> <permission_name> <auth> true

Parameters

name	data type	description	details
owner	string	The name or id of the account who is creating the permission.	n/a
permission_name	string	The name of the permission.	n/a
auth	authority	This is a JSON object which describes an account authority. See below for details.	a JSON object
broadcast	bool	true or false, whether or not you want to broadcast the transaction.	n/a

The auth parameter is a JSON object which looks like this:

{
  "weight_threshold": 1,
  "account_auths": [["1.2.52",1]],
  "key_auths": [["TEST71ADtL4fzjGKErk9nQJrABmCPUR8QCjkCUNfdmgY5yDzQGhwto",1]],
  "address_auths": []
}

This represents an authority structure, account_auths represents the amount of weight each account has on our account, in this example 1.2.52 has a weight of 1.

key_auths represents the amount of weight each public key has on this account, in this example TEST71ADtL4fzjGKErk9nQJrABmCPUR8QCjkCUNfdmgY5yDzQGhwto has a weight of 1.

weight_threshold represents the required weight for a transaction to be signed successfully.

In this example, either 1.2.52 can sign with their active key or TEST71ADtL4fzjGKErk9nQJrABmCPUR8QCjkCUNfdmgY5yDzQGhwto can be used to sign a transaction successfully because they each have a weight of 1, and only 1 is required by the threshold.

Example Call

create_custom_permission account01 perm1 { "weight_threshold": 1,  "account_auths": [["1.2.52",1]], "key_auths": [["TEST71ADtL4fzjGKErk9nQJrABmCPUR8QCjkCUNfdmgY5yDzQGhwto",1]], "address_auths": [] } true

2.2. get_custom_permissions

This function returns the custom permissions that have been created by the given account.

return type, namespace, & method

signed_transaction graphene::wallet::wallet_api::get_custom_permissions(
    string owner)

Function Call

The basic structure of the get_custom_permission function looks like this:

When using the cli_wallet...

get_custom_permissions <owner>

Parameters

name	data type	description	details
owner	string	The name or id of the account for which we'd like to see the list of created custom permissions.	n/a

Example Call

get_custom_permissions account01

2.3. update_custom_permission

This function updates an existing permission with the new authority object that you supply.

return type, namespace, & method

signed_transaction graphene::wallet::wallet_api::update_custom_permission(
    string owner,
    custom_permission_id_type permission_id,
    fc::optional<authority> new_auth,
    bool broadcast)

Function Call

The basic structure of the update_custom_permission function looks like this:

When using the cli_wallet...

update_custom_permissions <owner> <permission_id> <new_auth> true

Parameters

name	data type	description	details
owner	string	The name or id of the account who is updating the permission.	n/a
permission_id	custom_permission_id_type	The ID of the custom permission we're intending to edit.	n/a
new_auth	authority	Just like create_custom_permission, this is a JSON object which represents an account authority.	n/a
broadcast	bool	true or false, whether or not you want to broadcast the transaction.	n/a

Example Call

update_custom_permission account01 1.27.0 { "weight_threshold": 1,  "account_auths": [["1.2.53",1]], "key_auths": [], "address_auths": [] } true

Here we removed the key_auths and added 1.2.53 with weight 1, which is equal to weight_threshold , so 1.2.53 can alone sign the transaction successfully.

The new authority object will replace the old authority object using this function call. Make sure that the authority object that you supply here is set exactly as you'd like.

2.4. create_custom_account_authority

Creating a custom authority maps the created custom permissions with the actual operations present on the blockchain. It also has expiry time by when this custom permission is no longer valid on any given account and operation combination.

return type, namespace, & method

signed_transaction graphene::wallet::wallet_api::create_custom_account_authority(
    string owner,
    custom_permission_id_type permission_id,
    int operation_type,
    fc::time_point_sec valid_from,
    fc::time_point_sec valid_to,
    bool broadcast)

Function Call

The basic structure of the create_custom_account_authority function looks like this:

When using the cli_wallet...

create_custom_account_authority <owner> <permission_id> <operation_type> <valid_from> <valid_to> true

Parameters

name	data type	description	details
owner	string	The name or id of the account who is creating the account authority.	n/a
permission_id	custom_permission_id_type	The ID of the custom permission we're intending to edit.	n/a
operation_type	int	This is the ID of any particular operation. IDs are available here.	n/a
valid_from	time_point_sec	The timestamp when the permission begins to be valid. See below for what a valid timestamp looks like.	n/a
valid_to	time_point_sec	The timestamp when the permission stops being valid. See below for what a valid timestamp looks like.	n/a
broadcast	bool	true or false, whether or not you want to broadcast the transaction.	n/a

A valid timestamp looks like this: "2019-11-22T18:30:00"

Example Call

create_custom_account_authority account01 1.27.0 0 "2019-11-22T18:30:00" "2020-12-03T17:53:25" true

Basically this represents a full HRP where the transfer operation on account01 can be done by authorities present in 1.27.0 instead of account owner account01.

2.5. update_custom_account_authority

This function can be used to update existing valid_from and valid_to times.

return type, namespace, & method

signed_transaction graphene::wallet::wallet_api::update_custom_account_authority(
    string owner,
    custom_account_authority_id_type auth_id,
    fc::optional<fc::time_point_sec> new_valid_from,
    fc::optional<fc::time_point_sec> new_valid_to,
    bool broadcast)

Function Call

The basic structure of the update_custom_account_authority function looks like this:

When using the cli_wallet...

update_custom_account_authority <owner> <auth_id> <new_valid_from> <new_valid_to> true

Parameters

name	data type	description	details
owner	string	The name or id of the account who is updating the account authority.	n/a
auth_id	custom_account_authority_id_type	The ID of the custom account authority we're intending to edit.	n/a
new_valid_from	time_point_sec	The timestamp when the permission begins to be valid. See below for what a valid timestamp looks like.	n/a
new_valid_to	time_point_sec	The timestamp when the permission stops being valid. See below for what a valid timestamp looks like.	n/a
broadcast	bool	true or false, whether or not you want to broadcast the transaction.	n/a

A valid timestamp looks like this: "2019-11-22T18:30:00"

Example Call

update_custom_account_authority account01 1.28.0 "2020-06-02T17:52:25" "2020-06-03T17:52:25" true

2.6. delete_custom_permission

This function is used to delete an existing custom permission.

This will delete all the custom account authorities linked to this permission as well.

A cascading delete!

return type, namespace, & method

signed_transaction graphene::wallet::wallet_api::delete_custom_permission(
    string owner,
    custom_permission_id_type permission_id,
    bool broadcast)

Function Call

The basic structure of the delete_custom_permission function looks like this:

When using the cli_wallet...

delete_custom_permission <owner> <permission_id> true

Parameters

name	data type	description	details
owner	string	The name or id of the account who is deleting the permission.	n/a
permission_id	custom_permission_id_type	The ID of the custom permission we're intending to delete.	n/a
broadcast	bool	true or false, whether or not you want to broadcast the transaction.	n/a

Example Call

delete_custom_permission account01 1.27.0 true

2.7. delete_custom_account_authority

This function is used to delete an account authority attached to a permission.

return type, namespace, & method

signed_transaction graphene::wallet::wallet_api::delete_custom_account_authority(
    string owner,
    custom_account_authority_id_type auth_id,
    bool broadcast)

Function Call

The basic structure of the delete_custom_account_authority function looks like this:

When using the cli_wallet...

delete_custom_account_authority <owner> <auth_id> true

Parameters

name	data type	description	details
owner	string	The name or id of the account who is deleting the account authority.	n/a
auth_id	custom_account_authority_id_type	The ID of the custom account authority we're intending to delete.	n/a
broadcast	bool	true or false, whether or not you want to broadcast the transaction.	n/a

Example Call

delete_custom_account_authority account01 1.28.0 true

3. Resource Permissions with Account Roles

Resource permissions can be granted by applying account roles to those resources. The allowed permissions are attached to the role. Then accounts can be added to the role to grant them the permissions the role provides.

Some of the following functions need Operation IDs. You can find a list of Operation IDs here.

3.1. create_account_role

This function creates an account role.

return type, namespace, & method

signed_transaction graphene::wallet::wallet_api::create_account_role(
    string owner_account_id_or_name,
    string name,
    string metadata,
    flat_set<int> allowed_operations,
    flat_set<account_id_type> whitelisted_accounts,
    time_point_sec valid_to,
    bool broadcast)

Function Call

The basic structure of the create_account_role function looks like this:

When using the cli_wallet...

create_account_role <owner_account_id_or_name> <name> <metadata> <allowed_operations> <whitelisted_accounts> <valid_to> true

Parameters

name	data type	description	details
owner_account_id_or_name	string	The name or id of the account who is creating the account role.	n/a
name	string	The name of the account role. For example, "Movie Interstellar Permissions"	n/a
metadata	string	Metadata for additional info. For example, this could be a JSON object or and external URL with info.	n/a
allowed_operations	flat_set<int>	An array of numbers which represent all the operations that this role allows. IDs are available here.	n/a
whitelisted_accounts	flat_set<account_id_type>	An array of account IDs for the accounts that belong to this role and are therefore granted the allowed_operations for the resource.	n/a
valid_to	time_point_sec	The time at which the role no longer provides the allowed_operations to its whitelisted_accounts. Note: valid_from is automatically set to the time the account role was created.	n/a
broadcast	bool	true or false, whether or not you want to broadcast the transaction.	n/a

A valid timestamp looks like this: "2020-09-04T13:43:39"

Example Call

create_account_role account01 ar1 ar1 [89,95] [1.2.40, 1.2.41, 1.2.43] "2020-09-04T13:43:39" true

This command effectively limits any NFT to be sold or transferred between only three accounts, 1.2.40, 1.2.41, and 1.2.43.

3.2. get_account_roles_by_owner

You can use this to find all the account roles by their owner.

return type, namespace, & method

signed_transaction graphene::wallet::wallet_api::get_account_roles_by_owner(
    string owner_account_id_or_name)

Function Call

The basic structure of the get_account_roles_by_owner function looks like this:

When using the cli_wallet...

get_account_roles_by_owner <owner_account_id_or_name>

Parameters

name	data type	description	details
owner_account_id_or_name	string	The name or id of the account for which we'd like to see the list of created account roles.	n/a

Example Call

get_account_roles_by_owner account01

3.3. update_account_role

As a resource owner, you can update the operations and whitelisted accounts present in an account role. This helps in blacklisting any users from selling or transferring NFTs or any resources.

return type, namespace, & method

signed_transaction graphene::wallet::wallet_api::update_account_role(
    string owner_account_id_or_name,
    account_role_id_type role_id,
    optional<string> name,
    optional<string> metadata,
    flat_set<int> operations_to_add,
    flat_set<int> operations_to_remove,
    flat_set<account_id_type> accounts_to_add,
    flat_set<account_id_type> accounts_to_remove,
    optional<time_point_sec> valid_to,
    bool broadcast)

Function Call

The basic structure of the update_account_role function looks like this:

When using the cli_wallet...

update_account_role <owner_account_id_or_name> <role_id> <name> <metadata> <operations_to_add> <operations_to_remove> <accounts_to_add> <accounts_to_remove> <valid_to> true

Parameters

name	data type	description	details
owner_account_id_or_name	string	The name or id of the account who is updating the account role.	n/a
role_id	account_role_id_type	The ID of the account role we're intending to update.	n/a
name	string	The name of the account role. For example, "Movie Interstellar Permissions"	n/a
metadata	string	Metadata for additional info. For example, this could be a JSON object or and external URL with info.	n/a
operations_to_add	flat_set<int>	An array of numbers which represent all the operations that should be added to the role. IDs are available here.	n/a
operations_to_remove	flat_set<int>	An array of numbers which represent all the operations that should be removed from the role. IDs are available here.	n/a
accounts_to_add	flat_set<account_id_type>	An array of account IDs for the accounts that should be added to the role.	n/a
accounts_to_remove	flat_set<account_id_type>	An array of account IDs for the accounts that should be removed from the role.	n/a
valid_to	time_point_sec	The time at which the role no longer provides the allowed_operations to its whitelisted_accounts. Note: valid_from is automatically set to the time the account role was created.	n/a
broadcast	bool	true or false, whether or not you want to broadcast the transaction.	n/a

A valid timestamp looks like this: "2020-09-04T13:43:39"

Example Call

update_account_role account01 1.32.0 null null [88] [95] [1.2.42] [1.2.40] "2020-09-04T13:52:38" true

88 offer_operation is added.

95 nft_safe_transfer_from_operation is removed.

1.2.42 account is added to the whitelist.

1.2.40 account is removed from the whitelist.

3.4. delete_account_role

This function deletes an account role.

Once an account role is deleted, restrictions on resource access no longer work!

return type, namespace, & method

signed_transaction graphene::wallet::wallet_api::delete_account_role(
    string owner_account_id_or_name,
    account_role_id_type role_id,
    bool broadcast)

Function Call

The basic structure of the delete_account_role function looks like this:

When using the cli_wallet...

delete_account_role <owner_account_id_or_name> <role_id> true

Parameters

name	data type	description	details
owner_account_id_or_name	string	The name or id of the account who is deleting the account role.	n/a
role_id	account_role_id_type	The ID of the account role we're intending to delete.	n/a
broadcast	bool	true or false, whether or not you want to broadcast the transaction.	n/a

Example Call

delete_account_role account01 1.32.0 true

4. Related Documents

The functions listed in this guide will cost transaction fees. To calculate how much PPY you'll need to make these transactions and meet your development goals, please see the Calculating Costs guide.