On the second part of our Multisig and Permission series, we review how to update the authority structure of your account on an EOSIO blockchain, which is still somewhat of a mystery to many users. By using the correct tools and having a proper understanding of what the blockchain requires, it becomes rather simple and you’ll be able to harness the incredible power of this unique feature.
Exploring Permissions of an Account
There are two ways to explore the permission structure of an account if you want to review how other accounts have structured themselves.
The first is to use a block explorer such as eosq, which is where the screenshots in this article have come from. It shows a clean and easy-to-follow graphic of how all permissions of an account are nested and structured like the one below.
Another method is by using the eosc command line tool, using the command eosc get account ACCOUNT_NAME. If you prefer to look at the json format, you can add the flag --json to that command to change views.
Crafting a .yaml File
Once you have decided on a new structure, you must then create the yaml file to load to the chain. The structure of the file is very rigid and must be adhered to, or it will give errors when trying to update. One thing to note, as it has not been well documented, is that keys and accounts must be listed in alpha-numerical order. Otherwise it will return an "action validate exception" error.
The screenshot above is an example of a standard permission that contains a single key for both the active and owner permissions.
If you wanted to add a second key to the active permission, you could craft a yaml file like so:
---
threshold: 2
keys:
- key: EOS6qiF84rDueuGuRYjJe6HwHN9hGPAUetpGGSVgBZp25zr34xcQ9
weight: 1
permission: active
- key: EOS7WXh1FtKTnbg3GE9GWJX9KKqMxHzra7anCWaRFBJ46mj3oVtep
weight: 1
permission: active
---
Sample files are hosted in our GitHub repository. This example can be found here
Remember to ensure that you list the keys in alpha-numerical order to avoid an error. Also note that you can define different weights for each key, and a threshold as desired for the permission.
Once the file has been crafted, within eosc you would use the command: eosc system updateauth [ACCOUNT_NAME] [PERMISSION_NAME] [PARENT_PERMISSION] [FILENAME.yaml]
The new structure, as viewed on eosq will now become:
Assigning Authority to Other Accounts
If you wanted to assign signing authority of one account to another account (presumably that you either control, or share control of), you could use a yaml file crafted like the one below.
---
threshold: 2
accounts:
- permission:
actor: msigexample2
permission: active
weight: 1
- permission:
actor: msigexample3
permission: active
weight: 1
---Above sample found here
In this case, whatever is required to satisfy the active permission of the accounts msigexample2 and msigexample3 would both be required to satisfy this active permission. Again, take note to ensure that you have listed the actor account names in alpha-numerical order.
Using Time Delays
All EOSIO blockchains have a very unique feature: adding delay to a transaction can count towards the multi-signature threshold. Note that a transaction cannot be authorized solely with time delays, at least one cryptographic signature is required. For example:
---
threshold: 2
keys:
- key: EOS6qiF84rDueuGuRYjJe6HwHN9hGPAUetpGGSVgBZp25zr34xcQ9
weight: 1
permission: active
waits:
- wait_sec: 60
weight: 1
permission: active
---Above sample found here
To satisfy the active permission, include the --delay-sec flag equal to (or greater than) the delay that wait_sec defines within the permission. An example of this would be:
eosc transfer [SENDER] [RECIPIENT] 1.0000 --delay-sec 60
If you include multiple waits in your permission, then they act cumulatively. So if you had a permission structure like the one below, a --delay-sec of 60 seconds would satisfy the active permission.
Why Use a Time Delay?
You could have a high-value account on which you want to force time delays for any transaction. This way, if someone obains your keys you will have some time to review what happened and issue a cancellation of the transaction before it is applied. Then, using a higher-level permission (like owner) to alter your lower-level permissions’ keys, locking out the hacker. You could use a service like dfuse to track, in real-time, pending transactions to your account and send you a push notification.
To cancel a transaction using eosc, you would run the command: eosc tx cancel [ACCOUNT_NAME] [TX_ID]
Note that due to the time delay needed to satisfy the above active permission, you would need to utilize the owner permission to run this command. To do this, you would add the flag --permission [ACCOUNT_NAME]@owner.
Combining All Three
You can mix and match the three different types to use keys, accounts and waits in any configuration that you can imagine. Here’s an example where any 2 of the 3 would satisfy the threshold.
---
threshold: 2
keys:
- key: EOS6qiF84rDueuGuRYjJe6HwHN9hGPAUetpGGSVgBZp25zr34xcQ9
weight: 1
permission: active
waits:
- wait_sec: 60
weight: 1
permission: active
accounts:
- permission:
actor: msigexample2
permission: active
weight: 1
---Above sample found here
Be sure that when you finally make changes to your accounts permission that you double check any change that you commit to the owner permission. The only permission that can change owner is owner itself. It's worth noting that you should be sure not create a loop of accounts. For example, if you had account1's active permission satisfied by account2's active permission, while also having account2's active permission satisfied by account1's active permission, then that loop can never become authorized. All permissions must end up with a key at some point.
In the following article, we’ll explore how to use these permissions in conjunction with msig. Make sure that before you begin to change the permissions of your accounts that you practice on a test account on a testnet.
