Security guides

What is a custom permission?

Lesson 1 Chapter 1

Let's start by explaining the eosio account and key structure.

WAX is using eosio as the blockchain solution to build upon, and it comes with a very powerful and neat permission system, which is different from other blockchain solutions. 

on WAX you own an account, which you verify ownership by signing messages with your private key. This is done through so called 'wallets', which in reality is an interface for your keys to use and sign messages on the blockchain. Your wallet doesn't hold anything, which is a misconception that many holds. You can see a wallet as your keychain, where you have keys for your home, car, bike etc. 

The neat thing with WAX is that you can add a key that is only allowed to unlock the car, but not start it. Or add a key that is only allowed to use to open the gas tank, but can not open the doors nor start the car. 

To move ahead with understanding the neatness of custom permissions, let's start by explaining the basic permissions.

The 2 different standard permissions, Owner and Active

On Bitcoin, you have 1 key, which can access your funds, if that key is lost, your funds are lost. On WAX, instead of having 1 key, you have 1 account. If you lose access to your account, you lose access to your funds. However, the benefit on WAX, is that your account can have multiple keys, so if 1 key is gone, you can still access it with the 2nd key. And the 2nd key can remove the first key and add a new. 

This allow you to save your funds in case one of your devices is compromised, and also, if you do this correctly, even if your device is compromised, and they get your key, they are limited in what they can do and your funds are still safe. Neat, right?

There are however a difference in the 2 standard permissions, the Owner key is a key that should NEVER be entered in any device unless you need its power. 

There is only 1 difference between active and owner key, they can both add custom permissions, they can both move tokens, stake, claim, vote and so forth. But only the Owner key can change the owner key. 

This means, if you have control of this key, you can take ownership of the account. And without it, you can not. 

Understanding the benefits of custom permissions

Using custom permissions, you can add a key, that as the analogy above described, can only be used for very specific purposes. Below is an example of how you can make this happen. 

In this case, the "owner" key and the "active" key are two different keys. Which is how it should be. But you can also see "desktop" and "msg".

These two keys have very specific purposes. Where the 'msg' key can only communicate with the smart contract located on 'waxwebmaster' account. And it can only sign 2 types of actions to that smart contract, the 'dispatch' and 'message'. This means it can not stake tokens, transfer tokens, change permissions or anything else but the authentication it has been linked to.  

The 'desktop' key can sign more actions, but nothing but the 6 actions that it has linked. it is allowed to vote for guilds, claim vote rewards and gbm rewards. It is also allowed to create, transfer and claim NFT tokens with the simpleasset contract. 

This means that I can add the desktop key to a device that doesn't have to be as secure as the device where I add the active key. I don't have to store that key as securely (Unless I have valuable NFT tokens). 


Adding custom permission keys is a very neat way to increase security of your account and reduce risk of issues with your account. Don't be lazy, just get it done for at least the daily stuff like voting and claiming.