Multisignature Accounts On WAX: How Do They Work?
Accounts that require two or more keys to sign a transaction (requiring a certain permission), commonly referred to as multisignature accounts, are generally used to store funds securely and are without a doubt a very exciting EOSIO feature. But how do multisignature accounts work, how do you sign transactions with different keys and how can you set up a multisignature account yourself? We will explain all aspects of multisignature accounts on WAX in this article.
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.
How multisignature WAX accounts work
Now you are familiar with (the permissions structure of) default WAX accounts, it’s time to learn about multisignature WAX accounts. Multisignature WAX accounts function similar to default WAX accounts, the main difference between the two is the permissions structure. In a default WAX account all permissions have a threshold of 1 and only have 1 key with a weight of 1 associated with it, whereas the permissions in a multisignature WAX account have a threshold of 2 or higher and have multiple keys or account permissions with (possibly) varying weights associated with them. This also means that multiple keys or account permissions will have to sign any transaction from the multisignature WAX account.
An example of a possible permissions structure in a multisignature WAX account can be seen in the image above. Just like the default account described earlier, this account has both the owner and active permission.
However, the owner permission in this multisignature account has a threshold of 3 and has 3 keys associated with it: The active key from John’s account, which has a weight of 2, the active key from Bob’s account, which has a weight of 1 and the active key from Stacy’s account, which also has a weight of 1. This means that to execute any transaction requiring the owner permission, both John’s active key and either Bob’s or Stacy’s active key would have to sign the transaction before it can be executed.
The active permission in this multisignature account has a threshold of 2 and has 3 keys associated with it. The active key from John’s account, which has a weight of 1, the active key from Bob’s account, which has a weight of 1 and the active key from Stacy’s account, which also has a weight of 1. This means that to execute any transaction requiring the active permission (any combination) of 2 of the active keys would have to sign the transaction before can be executed.
Creating a multisignature WAX account
Now you are familiar with how multisignature accounts, it’s time to learn how to create a multisignature account yourself. Before you are able to create a multisignature account, you need to have/create a default WAX account first, which you will then turn into a multisignature account. 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 by importing your account into Scatter. If you don’t have the keys of your account in Scatter yet, you can follow the official instructions here.
Keep in mind that changing the permissions structure of your account might render your account inaccessible and unrecoverable, proceed with caution.
In this example we will create an account which can be shared with a friend. It will have the following permissions structure:
In this example the owner permission has a threshold of 2 and has 2 account permissions with a weight of 1 associated with it. The key associated with the owner permission of your own account and the key associated with the owner permission of your friend’s account. This means that in order to perform any transaction requiring the owner permission both you and your friend would have to sign the transaction with their owner key before it can be executed.
The active permission also has a threshold of 2 and has 2 keys with a weight of 1 associated with it. The key associated with the active permission of your own account and the key associated with the active permission of your friend’s account. This means that in order to perform any transaction requiring the active permission both you and your friend would have to sign the transaction with their active key before it can be executed.
Let’s start updating the permissions structure to turn this account into a multisignature account. We will be using Bloks for this tutorial.
Go to the top right of the page and click login (make sure Scatter is open and unlocked), then select ‘Scatter’. After doing so, Scatter will open a menu where you are able to choose which permission on which account you would like to connect. Choose the owner permission of the account and click ‘Allow’, as can be seen in the image on the left.
After you have connected the right permission of your account, navigate to ‘Wallet’, then ‘Keys and Permissions’, then click ‘Advanced’.
We will first update the active permission. Start by clicking on the active permission, remove the key currently associated with the permission and then click ‘Add Account’ twice. Fill in the blanks using the correct information, update the threshold of the permission to 2, and click ‘Save Permission’ after. Then sign the transaction using Scatter.
After you are done updating the active permission it is time to update the owner permission. Just like you did with the active permission, remove the key currently associated with the permission, click ‘Add Account’ twice, and fill in the correct account permissions/keys. Update the threshold of the permission to 2 and click ‘Save Permission’.
When you are done, the permissions structure of you account should look like the image above, but with the correct account permissions instead of the ones in the above image.
Creating, signing and executing multisignature transactions
You already know that multiple keys have to sign a multisignature transaction before it can be executed, but how can this be done both convenient and secure?
The process consists of 3 steps. First of all, someone has to create the multisignature transaction, after which those authorized to do so have to sign the transaction. Once the transaction has enough signatures to satisfy the threshold of the permission it requires, it can be executed. We will explain all 3 steps using the example account above.
Creating a multisignature transaction
As said above, the first step is creating a multisignature transaction. Let’s say you want to transfer 1 WAX from the shared multisignature account, which you have just created, to another WAX account. This action requires the active permission of the multisignature account (which has a threshold of 2 and has 2 keys with weights of 1, YourAccount@active and FriendAccount@active, associated with it).
First of all, login to Bloks using the active permission of your own account. Then click on ‘Multisig mode’ in the menu to turn it on. Once that is done, go to the ‘Transfer Tokens’ page of the Wallet section on Bloks.
Then click on the ‘Transfer 0 WAX’ button without filling any of the fields, which will open a tool to create your multisignature transaction.
Fill in the blanks with the correct information. The proposer is already filled in for you, this is the account which proposes the transaction (YourAccount in this case, this does not have to be the multisignature account). The proposal name can be any name. The requested approvals refer to the keys (belonging to a permission on an account) that have to sign the multisignature transaction. The contract and action have been filled in already as well. The authorization is the permission that is required to perform the transaction on the account from which the transaction will take place (in this case this is the active permission of the multisignature account). Lastly, make sure to change the from part of the data to the account name of the multisignature account, as you want to send the transaction from that account. Also make sure to fill in the account name of the recipient and the amount of WAX you’d like to send.
After having completed all of these steps, verify all information is correct and click ‘Propose’ at the bottom of the page, then accept the transaction using Scatter. Make sure to go to your proposal by clicking on the name of your proposal in the green window that will pop up after accepting the transaction (or visit the proposal from the page of your account).
Signing a multisignature transaction
Now you have created your multisignature transaction, it’s time to sign the transaction using the required keys. Since you just proposed the multisignature transaction using (the active permission) your own account, and the active permission of your own account is one of the accounts which needs to sign the transaction, you can immediately approve it.
Make sure to unselect ‘multisignature mode’ before continuing as you no longer need it.
You can approve the transaction by clicking the ‘Approve transaction’ button and accepting the transaction using Scatter. Bloks will then automatically update the approval status and 1 out of 2 accounts have now accepted the transaction.
Your friend would then have to sign the transaction as well, by logging into Bloks with the active permission of his account, going to the proposal and lastly, accepting the proposal.
Executing a multisignature transaction
The final step that remains after all parties have signed the transaction, is executing the transaction.
Executing the transaction can be done by going to the multisignature transaction on Bloks and then clicking ‘Execute transaction’ and accepting the transaction using Scatter. This can be done using both your own account or your friend’s account. If successful, the transaction will now be executed on the multisignature account.
You can verify this by navigating to the account page of the multisignature account and checking if the transaction is visible.
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
