Advanced WAX Permissions
One of the main differences between WAX and most other blockchains is the account system. This account system allows you to completely customize the structure of your account, allowing you to do many awesome things. In this article, we will talk about how permissions in a WAX account work and about all the possibilities you have when customizing the permissions structure of an account.
Permissions structure in a default WAX account
Before we start explaining advanced permissions structures, it is important to understand the permissions structure of a default WAX account first. We will explain this below.
Every user has one or more accounts on the WAX blockchain. WAX accounts are human-readable identifiers that are stored on the blockchain and they are required to push any (valid) transaction to the WAX blockchain.
Every WAX account has permissions. Permissions can be seen as requirements which need to be fulfilled in order for a transaction to go through. Each permission has certain actions associated with it. A default WAX account has 2 native permissions:
- Owner: shows ownership of the account and is needed to make any changes to the ownership the account. The private key for this permission is best kept (safely) offline, as it is not needed to do most things on the WAX network.
- Active: used for transferring funds, voting for producers and making other high-level account changes.
Besides these 2 native permissions you can create new, custom, permissions that fit your needs.
Each permission has one key associated with it. Each key associated with a permission has a certain weight, and each permission has a certain weight threshold which needs to be met before a transaction requiring that permission is accepted.
To help you understand all of this information we have included the above image, which visualizes the permissions structure of a default WAX account. As you can see, the owner permission has a default threshold of 1, and 1 key with a weight of 1 associated with it. The same goes for the active permission, which has a default threshold of 1, and 1 key with a weight of 1 associated with it. This means that only the (private) key associated with the owner or active permission is required to perform any transaction requiring the owner or active permission, respectively.
The (private) key associated with the owner permission is often referred to as the owner key, whereas the (private) key associated with the active permission is often referred to as the active key.
Each permission also has a parent permission. The parent permission is able to change the keys of its child permissions. In a default WAX account the owner permission is the parent permission of the active permission. This means that any key(s) associated with the owner permission can change the key(s) associated with the active permission, but not the other way around. The key(s) associated with the owner permission can also change the keys associated with the owner permission.
Customizing the permissions structure
Now you are familiar with the default permissions structure of a WAX account you are likely wondering how this structure can be altered. Let’s start with one of the most common changes to the permissions structure of a WAX account, multisignature permissions.
Multisignature permissions
To put it briefly, transactions requiring a multisignature permission are transaction that require multiple signatures before they are executed. A singlesignature permission can be turned into a multisignature permission by adding either a key, permission of a (different) account, or wait, with a certain weight, to the permission and changing the threshold of the permission.
In the image above you can see an example of a multisignature permission. The owner permission has a threshold of 2 and has 2 keys with a weight of 1 associated with it. This means that any transaction requiring the owner permission will have to get signed by both keys before it is executed.
You can read more about multisignature accounts and permissions in our article on this topic!
Wait timer
In addition to creating multisignature permissions it is also possible to set wait timers with a certain weight. A wait timer consists of 2 parts, the wait time (in seconds) and the weight.
- Wait time: This is the time needed before the delay requirement has been met. This time is specified in seconds.
- Weight: This is the amount that gets added to the threshold of the permission once the wait time has expired.
In the image above you can see a permissions structure with a wait timer. The owner permission has a threshold of 2 and has 1 key with a weight of 1 and 1 wait timer with a weight of 1 associated with it. This means that any transaction requiring the owner permission has to both get signed by the key and get delayed by 1 hour (3600 seconds), before it is executed.
Custom permissions
Lastly, we have custom permissions. Custom permission refers to any non-native permission on a WAX account. This can be any kind of permission, ranging from a simple permission with a single native EOSIO action to complicated multisignature permissions with various actions from a dApp contract.
In the image above you can see a permissions structure with a custom permission, the publish permission. In this example the permission named publish has the publish action from a theoretical blog dApp linked to it. The active permission is the parent permission of the publish permission. Now any transaction with the publish action can get signed by the lower permission, publish, instead of having to get signed by the active permission. This improves the security of the account.
Creating custom permissions
Custom permissions can be used for various reasons, but are most often used for security reasons, as exposing the keys associated with your owner and active permissions can be risky. We will be explaining how to create your own custom permission. For this example, we will create a permission that has the native voteproducer action (the action that votes for Guilds) and the native claimgenesis action (the action that claims the Genesis Block Member program rewards) .
Let’s start with getting a WAX account on which you will create this custom permission. If you do not have an account yet, you can follow the official guide on how to create one here. If you would like to create a new account using your primary account, you can follow our guide here.
Once you have an account, you can continue. Make sure the keys of the account are imported in Scatter (for this tutorial only the key for active permission is needed).
Once you have the keys of your account in Scatter, it is time to generate an additional key in Scatter which you will use for the permission. To generate an additional key click “Generate key” in Scatter, select EOSIO, and follow the instructions.
Creating a new, custom, permission consists of 2 steps. First you have to create the permission and then you have to link actions to the permission. To start go to Bloks and login with the active permission of your account using the button on the top right (make sure Scatter is open and unlocked).
For the first step, go to this page (Wallet -> Keys and Permissions -> Advanced), click “Add New Permission” and click on the permission. Now you are able to edit the information of the permission fill in the correct information, as can be seen in the image above. When you have filled in the correct information, click “Save Permission” and sign the transaction. You have now created the permission. You can choose any name for the permission, as long as the length of the name is 12 characters or less. In this example, the permission is named “voteandclaim”.
Note: Scatter might disallow you to execute this transaction. If this is the case, go to the settings, then firewall, and remove “updateauth” from the list of blacklisted actions. After this is done Scatter should allow you to execute the transaction.
The next step is linking the voteproducer and claimgenesis action to the voteandclaim permission (or whatever name you have given to the permission). Go to the Link Auth page of Bloks and fill in the correct information, as can be seen in the image above. We will first link the voteproducer action. The contract name is “eosio”, as voteproducer is a native EOSIO action. When this is done click “Link Auth” and sign the transaction.
Once that is done, we will link the claimgenesis action to the voteandclaim permission. Follow the instructions above but use claimgenesis instead of voteproducer in the ‘contract action’ section. Then click “Link Auth” and sign the transaction.
You have now linked the voteproducer and claimgenesis action to the newly created voteandclaim permission
To create a custom permission that has a certain dApp action, you can follow the same steps, but instead of “eosio” as the contract name pick the contract name of the dApp you are using, and use the action(s) you would like to link to the permission instead of voteproducer and claimgenesis during the second step.
Verifying everything has gone well
Of course you want to verify everything has gone well. Luckily this can be done very easily by going to Bloks, looking up your account and going to the keys section of your account.
If everything has gone well, your vote permission should look like this. If not, follow the instructions in Bloks on how to remove the permission and try again.
The permissions of your account are shown using the following format:
You can now use your new permission to sign any transaction with the action(s) of your permission!
About us
Founding block producer for the EOS mainnet. Block producer for the BOS mainnet. WAX Guild candidate. Partner in the Europechain sister chain. Investor in blockchain projects. Governance, intercultural cooperation and security specialist. You can find us here:
EOS Block Producer name: eosamsterdam
BOS Block Producer name: amsterdambos
WAX Guild name: amsterdamwax
Website
Twitter
Youtube
Telegram
Wechat
Written by Yannick Slenter for EOS Amsterdam
