TRC105: Multi-signature Permission Operation

[Federico2014]

tip: 105 
title: Multi-signature Permission Operation
author: federico<federico.zhen@tron.network>
discussions-to: https://github.com/tronprotocol/tips/issues/105
status: draft
type: Standards Track
category: TRC
created: 2019-10-31

Simple Summary

This TIP provides operation permission specification for Multi-signature.

Abstract

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 TIP is a supplement of TIP16 for Multi-signature operation permission specification.

Motivation

This TIP is used to make clear that how to implement user-defined operation permission for Multi-signature.

Specification

There are three types 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.

Protocols

Account

message Account { 
  ... 
  Permission owner_permission = 31;
  Permission witness_permission = 32;
  repeated Permission active_permission = 33;
}

Three attributes are added to the account: owner_permission、witness_permission and active_permission. active_permission is a list, the length can not be bigger than 8.

Permission

message Permission {
  enum PermissionType {
    Owner = 0;
    Witness = 1;
    Active = 2;
  }
  PermissionType type = 1; 
  int32 id = 2;     
  string permission_name = 3;
  int64 threshold = 4;
  int32 parent_id = 5; 
  bytes operations = 6;  
  repeated Key keys = 7;
}

PermissionType: Pemission type
id: Generated by system. Owner id=0, Witness id=1, Active id increases from 2. Specifying using which permission to execute a contract by setting id. For instance, using owner permission, set id=0
permission_name: Permission name, 32 bytes length limit
threshold: The threshold of the signature weight
parent_id: Current 0
operations: 32 bytes (256 b), each of which represents the authority of a contract, when 1 means the right to own the contract
keys: The accounts and weights that all own the permission, 5 keys at most.

Key

message Key {
  bytes address = 1;
  int64 weight = 2;
}

address: The account address
weight: The signature weight

Contract Type

message Transaction {
  message Contract {
    enum ContractType {
      AccountCreateContract = 0;
      TransferContract = 1;
      TransferAssetContract = 2;
      VoteAssetContract = 3;
      VoteWitnessContract = 4;
      WitnessCreateContract = 5;
      AssetIssueContract = 6;
      WitnessUpdateContract = 8;
      ParticipateAssetIssueContract = 9;
      AccountUpdateContract = 10;
      FreezeBalanceContract = 11;
      UnfreezeBalanceContract = 12;
      WithdrawBalanceContract = 13;
      UnfreezeAssetContract = 14;
      UpdateAssetContract = 15;
      ProposalCreateContract = 16;
      ProposalApproveContract = 17;
      ProposalDeleteContract = 18;
      SetAccountIdContract = 19;
      CustomContract = 20;
      CreateSmartContract = 30;
      TriggerSmartContract = 31;
      GetContract = 32;
      UpdateSettingContract = 33;
      ExchangeCreateContract = 41;
      ExchangeInjectContract = 42;
      ExchangeWithdrawContract = 43;
      ExchangeTransactionContract = 44;
      UpdateEnergyLimitContract = 45;
      AccountPermissionUpdateContract = 46;
      ClearABIContract = 48;
      UpdateBrokerageContract = 49;
    }
  }  
}

Each bit of operations in Permission represent the execution permission of one contract, 1 means it owns the execution permission of the contract. For instance, operations=0x0100...00(hex) or 100...0(binary), refer to the definition of Transaction.ContractType, the id of AccountCreateContract is 0, means this permission only owns the execution permission of AccountCreateContract. If the operations is set 0x7fff1fc0033e0300000000000000000000000000000000000000000000000000(hex) or 11111110 11111111 11111000 00000011 11000000 01111100 11000000 ......(binary), it means it support the execution of all contracts except AccountPermissionUpdateContract.

Note: 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.

Change Permission

If the account hasAccountPermissionUpdateContract permission, it can change the permissioins by the following steps:

1、call getaccount to query the account, get the original permission
2、change permission
3、build transaction and sign
4、send transaction

http-demo

http://{host}:{port}/wallet/accountpermissionupdate

{
  "owner_address": "41ffa9466d5bf6bb6b7e4ab6ef2b1cb9f1f41f9700",
  "owner": {
    "type": 0,
    "id": 0,
    "permission_name": "owner",
    "threshold": 2,
    "keys": [{
        "address": "41F08012B4881C320EB40B80F1228731898824E09D",
        "weight": 1
      },
      {
        "address": "41DF309FEF25B311E7895562BD9E11AAB2A58816D2",
        "weight": 1
      },
      {
        "address": "41BB7322198D273E39B940A5A4C955CB7199A0CDEE",
        "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": "41F08012B4881C320EB40B80F1228731898824E09D",
        "weight": 1
      },
      {
        "address": "41DF309FEF25B311E7895562BD9E11AAB2A58816D2",
        "weight": 1
      },
      {
        "address": "41BB7322198D273E39B940A5A4C955CB7199A0CDEE",
        "weight": 1
      }
    ]
  }]
}

Rationale

By providing the Multi-signature operation permission, it can empower the account permission control more flexibility and satisfy the different demands of account management.

Implementation

• https://github.com/tronprotocol/wallet-cli/blob/develop/src/main/java/org/tron/demo/MultiSignDemo.java

[muwhh]

How to remove or bypass sweeper bot