TRON Multi-Signature mechanism

tronangel (8)in #blockchain • 5 years ago

Introduction
Standard transactions on cryptocurrency networks can be called single-signature transactions because they require only one digital signature for a transaction to be done. Multi-signature gives every signature one weight, the signatures’ total weight of the transactions must reach the customized weight threshold before they can be executed. By multi-signature, an account can be managed by several private keys, and the transactions created in one account can be signed by serval private keys. This document discuss multi-signature operation permission specification and how to implement user-defined operation permission for multi-signature.
Background
The scheme includes three kinds of permission, owner-permission, witness-permission, and active-permission, where owner-permission has the authority to execute all contracts, witness-permission is used for generating blocks, and active-permission is custom permission (a combination of contracts permission sets).
Scenario
Lets’ see several cases:
Alice is running a company, she creates an account as her company fund account. Alice adds Bob(Accountant), Carol(CFO) and Alice(CEO) into the owner-permission of her account. Bob’s signature weight is 2, Carol’s signature weight is 2, Alice’s signature weight is 5. Owner-permission’s signature weight threshold is 3. Alice’s signature weight is bigger than the threshold(5 > 3), so her only signature is sufficient to make transactions. Bob’s signature weight is smaller than the threshold(2 < 3), to make a transaction, Bob needs Carol’s or Alice’s signature if Carol approves, the total signature weight is 2+2 > 3, so the transaction can be executed.
Alice has many TRX assets. One day, misfortune has come, Alice is dead due to an accident. She is the only one who holds the private key of her account, so her assets will stay in that account forever, nobody can get it. (Current Scenario) Alice has many TRX assets. She creates an active-permission for her account, adds her husband and son’s addresses into the active-permission, and give the active-permission authority to operate her account. So after Alice no longer exists, her family members can still operate her account.
Alice is running a company, she creates an account as her business account. Alice creates an active-permission and adds Bob(Accountant), Carol(CFO) and Alice(CEO) into the active-permission of the account. Alice gives the active-permission authority to operate her business account. One day, Bob resigns. To keep Alice’s account safe, Alice can remove Bob’s account from the active-permission, then Bob can not operate her account anymore.
Alice has a witness account, if she wants to deploy a node but doesn’t know how to deploy, she needs to provide the account’s private key to the program administrator. (Current Scenario) Alice can assign witness-permission to the administrator. Since the administrator only has the producing-block permission, there is no TRX transfer permission, and even if the private key of the administrator on the server is compromised, TRX will not be lost.
Specification
Let’s see the protocol design of multi-signature first. Related structs in protocol include Account, Permission, Key, Transaction.

Account：

There are 3 different roles of permission: owner, witness and active. Owner permission has the right to execute all the contracts, witness permission is for SR, active permission contains a set of contracts selected execution permissions. Related attributes are added to the account: owner_permission、witness_permission and active_permission. active_permission is a list, the length must <= 8.

Permission：

Each bit of struct member operations, 1 means true, 0 means not, support up to 256 different type of contract; index refers to the definition of Transaction.ContractType (see below).
For instance, operations=0x0100…00(hex) or 100…0(binary), only the first bit is 1, the id of AccountCreateContract is 0, means this permission only owns the execution permission of AccountCreateContract. If the operations=0x7f ff 1f c0 03 3e 03 …(hex) or 11111110 11111111 11111000 00000011 11000000 01111100 11000000 …(binary), the 47th bit of operations is 0, it means it doesn’t support the execution of AccountPermissionUpdateContract, as the ContractType of AccountPermissionUpdateContract is 46 (start from 0) listed below.
All the hex byte sequences of operations are ordered in little-endian coding, but for each byte, it’s ordered in big-endian for binary bits. For the above example, the first byte is 7f, its corresponding binary coding is 11111110 ; the third byte is 1f, its corresponding binary coding is 11111000.

Key：

ContractType：

Owner Permission：
Owner permission is the top permission of an account. It is used to control account ownership, adjust permission structure. Owner Permission has the right to execute all the contracts.
Owner permission’s features:
The account that has owner permission can change the owner permission
When owner permission is null, the default owner of the account owns the owner permission
When you create a new account, the address will be insert into owner permission automatically, default weight is 1, keys field only contains this address and also weight is 1.
If a permissionId is not specified when a contract is executed, using owner permission by default.
Witness Permission:
Super representatives can use this permission to manage block producing. Only witness account has this permission.
Usage scenario example:
A super representative deploys a witness node on cloud server. In order to keep the account on the cloud server safe, you can only give the block producing permission to the account you put on cloud server. Because this account only owns block producing permission, no TRX transfer permission, so even if the account on the cloud server is leaked, the TRX will not be lost.
Witness node configuration:

if no witness permission is used, no need to configure
if witness permission is used, need to reconfigure:

Active Permission：
Active permission is composed of a set of contract execution permission, like creating an account, transfer function, etc. Active permission’s features:
the account owns owner permission can change active permission
the account owns the execution permission of AccountPermissionUpdateContract can also change active permission
8 permissions at most
permissionId increases from 2 automatically
when a new account is created, an active permission will be created automatically, and the address will be inserted into it, default weight is 1, keys field only contains this address and weight is 1
Fee:

Using AccountPermissionUpdateContract costs 100TRX
If a transaction contains 2 or more signatures, it charges an extra 1 TRX besides the transaction fee
The fee can be modified by proposing

Change Permission:
If the account has AccountPermissionUpdateContract permission, it can change the permissions by the following steps:
call getaccount to query the account, get the original permission
change permission with AccountPermissionUpdateContract

Example:

//http://{host}:{port}/wallet/accountpermissionupdate
{
"owner_address": "41ffa9466d5bf6bb6b7e4ab6ef2b1cb9f1f41f9700",
"owner": {
"type": 0,
"id": 0,
"permission_name": "owner",
"threshold": 2,
"keys": [
{
"address": "41ffa9466d5bf6bb6b7e4ab6ef2b1cb9f1f41f9700",
"weight": 1
},
{
"address": "{account_1}",
"weight": 1
},
{
"address": "{account_2}",
"weight": 1
}
]
},
"witness": {
"type": 1,
"id": 1,
"permission_name": "witness",
"threshold": 1,
"keys": [
{
"address": "41F08012B4881C320EB40B80F1228731898824E09D",
"weight": 1
}
]
},
"actives": [
{
"type": 2,
"id": 2,
"permission_name": "active0",
"threshold": 3,
"operations": "7fff1fc0037e0000000000000000000000000000000000000000000000000000",
"keys": [
{
"address": "{account_3}",
"weight": 1
},
{
"address": "{account_4}",
"weight": 1
},
{
"address": "{account_5}",
"weight": 1
}
]
},
{
"type": 2,
"id": 3,
"permission_name": "active1",
"threshold": 3,
"operations": "7fff1fc0037e0000000000000000000000000000000000000000000000000000",
"keys": [
{
"address": "{account_6}",
"weight": 1
},
{
"address": "{account_7}",
"weight": 1
},
{
"address": "{account_8}",
"weight": 1
}
]}]}

The account 41ffa9466d5bf6bb6b7e4ab6ef2b1cb9f1f41f9700 gives the owner access to itself and account_1, account_2 with id 0;
give witness access to 41F08012B4881C320EB40B80F1228731898824E09D with id 1;
gives active access to account_3 , account_4, account_5 with id 2;
give active access to account_6, account_7, account_8 with id 3.
Active access will need signatures from both accounts in order to take effect. If the account is not a witness, it’s not necessary to set witness_permission, otherwise an error will occur.

build and sign the transaction
send transaction to node

How to make Multi-signature with http API:
Assuming there are 5 accounts: owner, active1, active2, active3, receiver.
We suppose account ‘owner’ has 5000 TRX and plans to send 1000 TRX to ’receiver, this transaction will be successful only if obtaining at least 2 signatures from the other 3 account owners.

‘owner’ creates a transaction to update account permission type. 47.252.84.158:8090 is the ip and http service port of a test node.

curl -X POST http://47.252.84.158:8090/wallet/accountpermissionupdate

{
"owner_address" : "41AF498B43EE098B26926798CFEAE1AB1154EF4430",
"owner": {
"type": 0,
"id": 0,
"permission_name": "owner",
"threshold": 1,
"keys": [
{
"address": "41AF498B43EE098B26926798CFEAE1AB1154EF4430",
"weight": 1
}
]
},
"actives": [
{
"type": 2,
"id": 2,
"permission_name": "active1",
"threshold": 2,
"operations": "7fff1fc0033e0000000000000000000000000000000000000000000000000000",
"keys": [
{
"address": "41A6D58DCB0E0FC0C3FE23CC405D5BD7979E9016FB",
"weight": 1
},
{
"address": "41F04DC975557388CD5D5FBCAAA706D76AAD415E59",
"weight": 1
},
{
"address": "41CC187927EB7D648D779FE363F7915DDCFBF2212B",
"weight": 1
}
]}]}

gets response in json type, named ${result_2}

‘owner’ signs the transaction with his private key.

gets response in json type, named ${result_3},
Note: Using this api may have your private key leaked.

‘owner’ broadcasts this transaction

anyone creates a transfer transaction from ‘owner’ to ‘receiver’ and assign 2 to permission_id.

gets response in json type, named ${result_5} and sends ${result_5} to ‘active1’ in String type.

user ‘active1’ signs the receiving transaction with his private key.

gets response in json type, named ${result_6} and sends ${result_6} to ‘active2’ in String type.
Note: Using this api may have your private key leaked.