Account Permission Management¶

The TRON network supports fine-grained control of account permissions. By configuring permissions (owner, witness, active), joint control of accounts, secure delegation, and functional permission separation can be achieved. The following document details the account permission model, contract structure, configuration methods, and common interface calls.

Function Overview¶

Account permission management allows:

Setting permission levels for an account.
Associating each permission with a group of addresses and weights.
Implementing permission control through a threshold mechanism.
Flexibly configuring which addresses can execute which contract types.

For detailed specifications, see TIP-16: Account Permission Management.

Permission Level Concepts¶

TRON supports three types of permission:

Permission Type	Description
owner	Highest account permission, controls ownership and permission structure
witness	Super Representative permission, used only for block production
active	Custom permission, can specify functional permission combinations

Permission Structure Definition¶

1. Account Structure: `Account`¶

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

Explanation:

owner_permission: owner permission (only one).
witness_permission: Super Representative permission (only one).
active_permission: active permission list, supports up to 8.

2. Permission Configuration: `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;
}

Explanation:

type: Permission type (owner/witness/active).
id: Permission ID, automatically assigned by the system.
- owner = 0, witness = 1, active starts from 2 and increments.
permission_name: Permission name, maximum 32 characters.
threshold: Permission threshold, the operation is authorized only when the cumulative weight of valid signatures meets or exceeds this value.
operations: Used only for Active permissions, specifies executable contract types.
keys: Addresses and weights with this permission (up to 5).

3. Permission Key Structure: `Key`¶

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

address: Address with permission.
weight: Weight of this address under this permission.

4. Permission Update Transaction: `AccountPermissionUpdateContract`¶

message AccountPermissionUpdateContract {
  bytes owner_address = 1;
  Permission owner = 2;
  Permission witness = 3;
  repeated Permission actives = 4;
}

This contract is used to update all account permission structures at once, which is an "all-or-nothing" update. Even if modifying a single permission, the full permission set must be resubmitted to prevent accidental loss of access.
Even if only one permission is modified, all other existing permissions must be fully specified in the contract.

5. Contract Type Enumeration: `ContractType`¶

Active permissions configure which ContractType can be executed through the operations field. The full list of ContractType enum values together with their Proto Message, Actuator, status, and business behaviors is maintained in System Contracts — ContractType Overview. For details on how to calculate the value of operations from these enum values, please see Operations Value Calculation Example.

Explanation of Each Permission Type¶

`owner` Permission (Account Master Control)¶

Holds full control over the account.
Can modify any permission structure (including itself).
Automatically set when creating an account, default threshold is 1, includes the account's own address.
By default, transactions without a specified Permission_id use the Owner permission.

`witness` Permission (Block Production Permission)¶

Available only for Super Representative, Super Representative Partner, and Super Representative Candidate accounts.
Controls block-producing nodes, does not have permissions for fund transfers or other operations.
Can delegate block production permission to other addresses to enhance account security.
Must contain exactly one key.

Super Representative Node Configuration Example:¶

# config.conf
//localWitnessAccountAddress = TMK5c1jd...m6FXFXEz  # TRON Address
localwitness = [
  xxx  # Private key of TMK5c1jd...m6FXFXEz
]

If the witness permission is modified, then:

localWitnessAccountAddress = TSMC4YzU...PBebBk2E
localwitness = [
  yyy  # Private key of TSMC4YzU...PBebBk2E
]

Note: Only one private key is allowed in localwitness.

Active Permission (Functional Permission Combination)¶

Can combine contract permissions, assigning sub-permissions to different roles.
Supports up to 8 active permission configurations.
Permission IDs start from 2 and increment.
When creating an account by default, one active permission is generated, with a default threshold of 1, containing only the account's own address.

Fees and Constraints¶

Operation	Fee Standard
Modify Account Permission	100 TRX
Transaction (2 or more signatures)	Additional 1 TRX

The above fees can be adjusted through proposals.

Interfaces and Operation Examples¶

1. Permission Modification Operation Process¶

Use getaccount to query the current account permission structure.
Construct the new permission configuration.
Call AccountPermissionUpdateContract.
Sign and broadcast the transaction.

Note: When a block contains transactions that modify account permissions, no further transactions from this account will be included in this block to ensure that such account permission modify transactions actually take effect starting from the next block.

Example Request:¶

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

{
  "owner_address": "41ffa946...",
  "owner": {
    "type": 0,
    "id": 0,
    "permission_name": "owner",
    "threshold": 2,
    "keys": [...]
  },
  "witness": {
    "type": 1,
    "id": 1,
    "permission_name": "witness",
    "threshold": 1,
    "keys": [...]
  },
  "actives": [
    {
      "type": 2,
      "id": 2,
      "permission_name": "active0",
      "threshold": 3,
      "operations": "7fff1fc0037e...",
      "keys": [...]
    }
  ]
}

2. Operations Value Calculation Example¶

operations field is a 32-byte hexadecimal string (little-endian) where each bit represents a specific ContractType , defining the functional scope of an Active permission. The following Java example generates permissions for contracts (ID=0-45):

Integer[] contractId = {0, 1, 2, ..., 45};
byte[] operations = new byte[32];
for (int id : contractId) {
  operations[id / 8] |= (1 << id % 8);
}
System.out.println(ByteArray.toHexString(operations));

Note: The contractId above only illustrates the bit-setting logic. ContractType IDs are not contiguous (7, 21-29, 34-40, etc. are gaps), and a bit can only be set for a contract type already present in the on-chain AVAILABLE_CONTRACT_TYPE bitmap; otherwise the transaction is rejected during validation. AVAILABLE_CONTRACT_TYPE roughly corresponds to the # column in the table above, except it does not include ShieldedTransferContract(51).

3. Transaction Execution Process¶

Create the transaction.
Set Permission_id (default is 0, i.e., owner permission).
User A signs and forwards to B.
User B signs and forwards to C.
(Under Asynchronous Multi-Sig Orchestration,transactions can be partially signed and passed between authorized parties until the threshold is met.)
The last user signs and broadcasts.
The node verifies if the total signature weight ≥ threshold; if yes, accepts the transaction.

Example code reference: wallet-cli Example

Auxiliary Interfaces¶

Query Signed Addresses¶

POST /wallet/getapprovedlist

rpc GetTransactionApprovedList(Transaction) returns (TransactionApprovedList) {}

Query Signature Weight¶

POST /wallet/getsignweight

rpc GetTransactionSignWeight(Transaction) returns (TransactionSignWeight) {}