Advanced EOS Permissions
One of the main differences between EOS 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 an EOS account work and about all the possibilities you have when customizing the permissions structure of an account.
Permissions structure in a default EOS account
Before we start explaining advanced permissions structures it is important to understand the permissions structure of a default EOS accounts first. If you would like to fully understand EOS accounts, read our comprehensive guide here. If you would only like to learn about the default structure of an EOS account, read the explanation below.
Every user has one or more accounts on the EOS blockchain. EOS accounts are human-readable identifiers that are stored on the blockchain and they are required to push any (valid) transaction to the EOS blockchain.
Every EOS 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 EOS 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 EOS 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 EOS 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 EOS account the owner permission is the parent permission of the active permission. This means that any key associated with the owner permission can change the key(s) associated with the active permission, but not the other way around.
Customizing the permissions structure
Now you are familiar with the default permissions structure of an EOS 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 an EOS 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 an EOS account. This can be any kind of permission, ranging from a simple permission with a single native EOS 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 Block Producers).
Let’s start with getting an EOS account on which you will create this custom permission. If you do not have an account yet, you can follow our guide on how to create one 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 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 EOSToolkit and attach the active permission of your account using the button on the top left.
For the first step go to this page and fill in the correct information, as can be seen in the image above. When you have filled in the correct information click “Update” 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 “vote”.
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 action to the vote permission (or whatever name you have given to the permission). Go to the Link Auth page of the toolkit and fill in the correct information, as can be seen in the image above. The contract name is “eosio”, as voteproducer is a native EOS(IO) action. When this is done click “Link Auth” and sign the transaction. You have now linked the voteproducer action to your newly created 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” during the second step. For example, if you wanted a permission that only has the ability to transfer your Everipedia tokens, you would use “everipediaiq” as the contract name and “transfer” as the contract action.
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 a block explorer like 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 the toolkit on how to remove the permission and try again.
The permissions of your account are shown using the following format (if you are using Bloks):
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
📝 Read this story later in Journal.
👩💻 Wake up every Sunday morning to the week’s most noteworthy stories in Tech waiting in your inbox. Read the Noteworthy in Tech newsletter.
