LogoLogo
PAO DocsCommunity DocsInfrastructure DocsPeerplays.com
  • Developer Documentation
  • API Reference
    • Peerplays Core API
      • Popular API Calls
      • Account History
      • Asset API
      • Block API
      • Crypto API
      • Database API
      • Network Broadcast API
      • Network Nodes API
      • Orders API
    • Wallet API
      • Account Calls
      • Asset Calls
      • Blockchain Inspection
      • General Calls
      • Governance
      • Privacy Mode
      • Trading Calls
      • Transaction Builder
      • Wallet Calls
    • Bookie API
      • General Calls
      • Listeners
      • Tournaments
  • Peerplays API Libraries
    • Python Peerplays
      • Installation
      • Creating an Account
      • Creating a Peerplays Wallet
      • NFT API
      • Marketplace API
      • Role Based Permissions API
  • Development Guides
    • Creating User Issued Assets
    • Introduction to Permissions
    • NFT Minting
    • Calculating Costs
  • The Cookbook
    • NFTs for Staking Creator Tokens
  • Tools and Integrations
    • PeerID
      • 1.0.0
        • Infrastructure
          • Deployment on a Linux Serve
          • Deployment to AWS ECS
            • Building the Docker Images
            • Storing Secrets in Amazon Parameter Store to use in ECS
            • Creating the Task Definition
            • Creating the Cluster
            • Creating the Service
        • Development
          • How does PeerID work without storing the keys ?
          • Authentication with PeerID
          • Brain Storming
          • Software Requirements
      • Authentication with PeerID
      • Requirements Specification
    • Random Number Generator
      • RNG Technical Summary
      • RNG API
  • Supporting & Reference Docs
    • Peerplays Development FAQs
    • Sidechain Operator Node (SON) Development
      • Generic Sidechain Docs
        • Quick joining GLADIATOR
        • Changes to Peerplaysjs-lib
        • Requirements Specification
        • Low Level Designs
          • bitcoin-deposit-handling-lld
          • bitcoin-operations-draft
          • bitcoin-sidechain-handler-lld
          • bitcoin-sidechain-multisig-bitcoin-wallet-and-bitcoin-addresses-pw
          • bitcoin-withdrawal-handling-lld
          • btc-address-scripting-mechanism
          • comparison-between-scenarios-for-handling-deposits-and-withdrawals
          • exchange-rate-list
          • generic-sidechain-deposit-hld
          • generic-sidechain-high-level-design
          • generic-sidechain-listener-hld
          • generic-sidechain-withdrawal-hld
          • refund-btc-mechanism
          • son-configuration
          • son-consensus-communication-and-transaction-signing-on-chain-lld
          • son-de-register-proposals-lld
          • son-objects-and-operators
          • son-rewards-lld
          • son-voting-lld
          • son-wallet-list_sons-lld
          • creation of a multi-sig bitcoin address lld
          • claiming initial son vesting lld
          • changeover and SON maintenance scenarios lld
          • user-sidechain-addresses-mapping
          • wallet-commands-for-son
        • Functional Specs
          • SON Configuration
          • SON rewards
          • SON Voting and Consensus
          • SONs switchover scenarios
          • SON Status Operations & Monitoring
          • Proposals
          • SON Smart Contracts
      • Bitcoin Sidechain Docs
        • Functional Specs
          • btc-refunds
          • voting-and-consensus
          • son-switchover
          • son-rewards
          • son-proposals
          • son-configuration
          • heartbeat-monitoring
          • BTC Transaction Processing & Signing
          • Bitcoin Withdrawal Handling
          • Bitcoin Deposit Handling
          • SON Multisig Bitcoin Wallet
      • Hive Sidechain Docs
        • Functional Specs
          • HIVE Deposit Handling
          • HIVE Withdrawal Handling
    • Peerplays DEX Development
      • Peerplays NEX
        • Functional Specifications
          • NEX-FS01 Dashboard Page
            • NEX-FS12 ETH-SONs Deposit/Withdraw Functionality
          • NEX-FS02 Login and Account Creation
          • NEX-FS03 Menus and Nav
          • NEX-FS04 Notifications
          • NEX-FS05a Market Page (alpha)
          • NEX-FS05 Market Page
          • NEX-FS06 Profile Page
          • NEX-FS07 Wallet Functions
          • NEX-FS08 App Settings
          • NEX-FS09 Blockchain Page
          • NEX-FS10 GPOS Page
          • NEX-FS11 WhaleVault Integration
      • Requirements Specification
      • Functional Specs
        • Asset Info Page and Asset Lists
        • Dashboard
        • Exchange Page
        • Login and Account Creation
        • User Account Page
        • Voting Page
    • SPK Network
      • Functional Specs
        • Claimdrop Snapshot Functional Specification
        • Initial Claimdrop Functional Specification
    • NFT Development
      • NFT Store
        • NFT Store User Stories
        • NFT Store UI HLD
        • NFT Store Requirements Specification
        • Functional Specifications
          • APP-FS01 App Header
          • APP-FS02 App Body
          • APP-FS03 App Footer
          • APP-FS04 App Navigation
          • APP-FS05 Wallet Functions
          • APP-FS06 App Home Page
          • APP-FS07 Account Page
          • APP-FS08 Browse View
        • App Page List
        • Requirement Traceability Matrix
    • Operation IDs List
    • Sidechain Flow Diagram (HIVE coin)
    • Sidechain Flow Diagram (Bitcoin)
    • Sidechain Flow Diagram (Ethereum coin)
    • TradeHands Explorer
      • User Personas
      • User stories
      • APP-FS01 Detailed View
      • Draft: APP-FS02 Front Page
      • APP-FS03 Collection Details Page
    • Grafana
      • Grafana Installation
      • Install Grafana Behind reverse proxy
      • Loki Installation
      • Promtail agent Installation
      • Grafana Explorer
    • NEX Deployment & Configuration
      • NEX Deployment
      • NEX - Blockchain API configuration
      • Deploying NEX in a HA scenario
    • API Node
      • MarketCap API
    • TOTO Application
      • FS-Subscription Plan
      • FS-Achievements
  • Development Workflow Docs
    • Development Workflow
  • Other Documentation
    • Peerplays Home
    • Community Docs
    • Infrastructure Docs
    • Site Reliability Engineering
Powered by GitBook
On this page
  • 1. Types of Permissions in Peerplays
  • 2. Hierarchical Role-based Permissions (HRP)
  • 2.1. create_custom_permission
  • 2.2. get_custom_permissions
  • 2.3. update_custom_permission
  • 2.4. create_custom_account_authority
  • 2.5. update_custom_account_authority
  • 2.6. delete_custom_permission
  • 2.7. delete_custom_account_authority
  • 3. Resource Permissions with Account Roles
  • 3.1. create_account_role
  • 3.2. get_account_roles_by_owner
  • 3.3. update_account_role
  • 3.4. delete_account_role
  • 4. Related Documents

Was this helpful?

Export as PDF
  1. Development Guides

Introduction to Permissions

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

PreviousCreating User Issued AssetsNextNFT Minting

Last updated 3 years ago

Was this helpful?

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 .

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)

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)

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)

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

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

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)

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

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)

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)

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)

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.

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)

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>

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)

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)

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>

n/a

operations_to_remove

flat_set<int>

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)

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

Just like , this is a JSON object which represents an account authority.

Creating a custom authority maps the created 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.

This is the ID of any particular operation. IDs are .

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

An array of numbers which represent all the operations that this role allows. IDs are .

An array of numbers which represent all the operations that should be added to the role. IDs are .

An array of numbers which represent all the operations that should be removed from the role. IDs are .

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 guide.

Operation IDs here
Operation IDs here
Calculating Costs
custom permissions
available here
available here
available here
available here
create_custom_permission