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.
Development Guides - Previous
Creating User Issued Assets
Next - Development Guides
NFT Minting
Last modified 2yr ago
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