What is Multisig
Multisig is a term frequently used in the cryptographic and blockchain space. Essentially it enables multiple parties to sign or approve an action that takes place - typically a requirement for certain wallets, accounts, and smart contracts to prevent a rogue or hacked individual from performing detrimental actions.
In the EOS blockchain there are a number of elements that form the overall structure of Authorities and Permissions. An outline is available on the EOS wiki directly at: https://github.com/EOSIO/eos/wiki/Accounts%20%26%20Permissions
At the most basic level you have an EOS public/private key pair, which is stored in a “wallet” so it can be used to sign transactions. The EOSIO code provides a bundled command line based wallet called keosd. In the future GUI based wallets will be developed and available.
The next level is the EOS account - a simple, human readable “name” that can be owned by an individual or a group, and is required to approve and push transactions to the network. Accounts have authorities or permissions attached, and the most simple account has a single public key tied to the “owner” authority and “active” authority. If an individual’s wallet has the corresponding private key, they can act with the respective authority of the paired public key.
Accounts can hold funds (such as EOS, or other tokens released by other parties) and publish smart contracts. The account can therefore control the movement of those funds, or revise the smart contract - this makes the authority scheme used for an account very important.
Why is it important
If a DAC, a group of friends, or a small business decide to manage funds or operate a smart contract it may be preferable that a single person or employee would be unable to approve large sum transfers single handedly.
This is where multisig and authorities come in. A common multisig configuration is to have three individuals own an account, and require at least two of three signatories to execute an action. This is common for escrow accounts, where the sender and receiver each own one of the public keys, and an escrow arbitrator has the third in the case of a dispute. If everyone is happy, the sender and receiver sign the transaction. If there is a dispute, the escrow arbitrator can provide the private key to the winner of the dispute.
Configuration options
EOS accounts provide an exceptional level of flexibility when it comes to configuring the authority framework. Every account has two native authorities: owner and active. The owner can do “anything” and change authorities that are beneath it, such as active and custom permissions. The active authority can do anything (transfer funds, publish smart contracts, vote for block producers, etc) except change the owner.
Custom authorities can be configured that would be used by smart contracts. For example a blog smart contract might utilize a “publish” authority. Various writers could be added to the publish authority without compromising control of the smart contract and account itself.
Authorities are structured in a parent/child relationship, where the parent is capable of modifying the authorities beneath it. The “active” authority is a child of “owner”, and custom authorities may be created as children of “active” or other custom authorities.
Each authority defines a threshold and a number of public keys or other accounts and their individual weights. A standard account has a threshold of 1 and a single public key with a weight of 1 - this means that anyone with the private key can complete an action individually.
Setting a threshold of 2 and defining three accounts or public keys with a weight of 1 will result in the traditional 2 of 3 signatory multisig configuration. One could dictate “super users” that have a higher weight so they don’t require additional signatures when they act, while other users would still require additional signatures.
Because authorities can reference both public keys and accounts, the account listed in the authority structure may itself be a multisig account. It becomes clear that the account authority configuration is infinitely flexible to a group or developers specific requirements, making the EOS platform a safe and secure environment for transactions and Dapps.
Running commands
This section assumes the reader already has a basic understanding on how to use the cleos command line. A tutorial to get started using the command line is available at the official EOSIO wiki at https://github.com/EOSIO/eos/wiki/Tutorial-Comprehensive-Accounts-and-Wallets
Lets assume we have four accounts created on the network:
- mymultisig11 - a multisig account we will configure
- partner11111 - Bob’s personal account
- partner22222 - Joe’s personal account
- partner33333 - Dave’s personal account
When mymultisig11 was initially created it was configured with a single public key as both owner and active key by Bob, who is configuring the mymultisig11 prior to launching a smart contract. The team wants to configure a standard 2 of 3 multisig on both the owner and active authorities. To prevent Bob from needing everyone to participate he will change the active authority first, and the owner authority last.
mymultisig11 has a single public key for owner and active permission. mymultisig11 has a 1000 EOS balance, partner11111 has a 100 EOS balance
Bob runs the following command - he sets the threshold to 2, and gives each of the team’s accounts a weight of 1. He specifies the active permission for each individual account so that their respective owner keys aren’t required. Bob could have chosen to specify keys instead of accounts which would have used the JSON:
{"key":”<PUBLIC_KEY>”,"weight":1}However by using accounts the account owners are given the flexibility the update their keys and authority structure without having to update the mymultisig11 authorities.
cleos set account permission mymultisig11 active '{"threshold":2,"keys":[],"accounts":[{"permission":{"actor":"partner11111","permission":"active"},"weight":1},{"permission":{"actor":"partner22222","permission":"active"},"weight":1},{"permission":{"actor":"partner33333","permission":"active"},"weight":1}],"waits":[]}' owner -p mymultisig11@owner
active permission now shows the three accounts and a threshold of 2
Now the the active permissions have been set, Bob goes ahead and changes the ownership permission. Once the ownership authority has changed to a multisig format Bob will require his team to participate whenever they need to change any additional authorities in the future.
Notice that the “owner” parent is dropped from the end of this command (just before the -p). Thats because that parameter specifies the parent of the authority being configured - owner has no parent, and so it is left blank.
cleos set account permission mymultisig11 owner '{"threshold":2,"keys":[],"accounts":[{"permission":{"actor":"partner11111","permission":"owner"},"weight":1},{"permission":{"actor":"partner22222","permission":"owner"},"weight":1},{"permission":{"actor":"partner33333","permission":"owner"},"weight":1}],"waits":[]}' -p mymultisig11@owner
owner permission has been similarly updated
Now that the mymultisig11 account has been successfully configured Bob would like to test the multisig functionality by paying himself for his efforts. To do this Bob uses the eosio.msig system contract to propose a transaction. The other team members may review and approve or unapprove the transaction.
Bob runs this command to propose the payment. The first array is the permissions the proposal requires, while the second array dictates which permission is used to actually execute the transaction. To “unlock” the mymultisig11@active permission he requires the approval of two of three of the accounts specified.
Because Bob doesn’t want to sign his own transaction, he requests Joe and Dave to sign it. Bob could have listed himself, and approved one of the signatures himself, but he felt that would be rude.
cleos multisig propose payme '[{"actor": "partner22222", "permission": "active"},{"actor": "partner33333", "permission": "active"}]' '[{"actor": "mymultisig11", "permission": "active"}]' eosio.token transfer '{"from":"mymultisig11", "to":"partner11111", "quantity":"25.0000 SYS", "memo":"Pay partner11111 some money"}' -p partner11111@activeNow the proposal has been listed Joe and Dave can review it by running the following command. This command returns JSON that shows the transaction that will be executed if they approve it.
cleos multisig review partner11111 payme -p partner22222@active
Reviewing the JSON of the proposal shows the transaction and authority being requested. Pay careful attention to only approve acceptable transactions!
Satisfied with the hard work Bob has done today Joe and Dave both approve the transaction from their own terminals using their own unlocked wallets.
cleos multisig approve partner11111 payme '{"actor": "partner22222", "permission": "active"}' -p partner22222@activecleos multisig approve partner11111 payme '{"actor": "partner33333", "permission": "active"}' -p partner33333@activeNow that the multisig transaction is approved Bob can execute it.
cleos multisig exec partner11111 payme -p partner11111@active
In the real world Joe and Dave would approve on their “own computers”. Now that the transaction has been executed we see that 25 EOS has moved from mymultisig11 to partner11111 successfully.
Conclusion
Multisig accounts will be a critical safety feature for all users of the EOS ecosystem. While future development will lead to GUI wallets that simplify and streamline the process it is important for Dapp developers and enthusiasts to experiment and fully understand the multisig process as early as possible.
Decentralised applications and charitable, transparent endeavours such as those GenerEOS is developing will rely heavily upon multisig security, and we hope this article helps ensure the EOS implementation of multisig is as safe and successful as possible.
Check out Nathan's overview video on this topic: Youtube: https://youtu.be/Bi3Oals39l8
About Us
GenerEOS is a social enterprise block producing candidate with a mission of promoting and supporting scalable and highly reliable block production whilst giving back block rewards to charities.
Based out of Sydney, Australia, GenerEOS is founded by a team of like minded blockchain enthusiasts with diverse backgrounds and a passion to make a difference in the world and fostering the spirit of generosity by giving back.
Public Presence
Website: https://www.genereos-sydney.io
Steem: https://steemit.com/@genereos
Telegram: https://t.me/joinchat/FfqLYBDQkv5vSkiLsh34IA
Reddit: https://www.reddit.com/user/GenerEOS
Github: https://github.com/generEOS
Medium: https://medium.com/@generEOS
Facebook: https://www.facebook.com/generEOS
great easy to read article!
Thanks Tai :)
great stuff guys, thanks!
There are lots of people waiting for the GUI!
Great Article!! Has anything changed for the syntax with v1.0.1 release
Command - cleos set account permission mymultisig11 owner '{"threshold":2,"keys":[],"accounts":[{"permission":{"actor":"partner11111","permission":"owner"},"weight":1},{"permission":{"actor":"partner22222","permission":"owner"},"weight":1},{"permission":{"actor":"partner33333","permission":"owner"},"weight":1}],"waits":[]}' -p mymultisig11@owner
So many thank you !