Account Permission Management

How TRON accounts support multi-party control through weighted permissions and signature thresholds.

A TRON account does not need to be controlled by a single private key. Through Account Permission Management (TIP-16), an account can be jointly operated by multiple parties — each holding their own keys, each with a configurable weight, and each transaction authorized only when the sum of signatures meets a threshold.

This page covers the three permission types, the threshold-and-weight model, the structure of the permission update contract, how operations specifies the transaction types allowed by an active permission, and the fees charged for permission updates and multi-signed transactions.

📘

Prerequisites


Permission types

Each TRON account has three permission slots:

PermissionDefault purposeNotes
OwnerFull control — can execute any contract type and modify the account's own permissionsCreated by default for new accounts with ID 0
WitnessUsed by SR accounts to sign blocks; cannot authorize ordinary transactions such as transfers or smart contract callsMust contain exactly 1 authorized address
ActiveCustom-scoped permissions for delegated operationOne is created by default with ID 2; up to 8 per account

The proto-level name witness_permission is the same as what TRON prose calls "Super Representative (SR) permission". This page uses Witness when referring to the permission type (matching the code), and SR when discussing the role. For the broader witness-vs-SR convention, see Consensus and DPoS.


Threshold and weight

A permission is authorized when the sum of signing weights meets or exceeds the threshold. Each permission is configured with:

  • A threshold — a positive integer
  • A list of authorized addresses (keys), each paired with a positive weight (int64)

When a transaction is signed, the network recovers the signing addresses, looks them up in the relevant permission's keys list, sums the weights of the recognized signers, and checks the sum against the threshold.

The configuration must satisfy these constraints (enforced at AccountPermissionUpdateContract validation):

RuleDetail
Max authorized addresses per permission5
Distinct addressesA keys list cannot contain the same address twice
Positive weightsEach address's weight > 0
Sum ≥ thresholdThe sum of all authorized address weights must be at least the threshold (otherwise threshold is unreachable)
permission_name lengthUp to 32 characters
parent_idMust be 0
Witness permissionRequired when Super Representative accounts or registered Super Representative candidate accounts update their permissions; must contain exactly 1 authorized address. Other accounts must not configure it.

Single-signer (default)

A new account starts with one owner permission and one active permission. Both have a threshold of 1 and a keys list containing only the account's own address with weight 1. The transaction types allowed by the default active permission are determined by the network's preset operations configuration. The initial owner permission is:

threshold: 1
keys:
  - address: <account's own address>, weight: 1

For either default permission, the account's private key contributes weight 1 and meets the threshold. A transaction using the active permission must also have its transaction type allowed by the permission's operations field.

Multi-party

A 2-of-3 owner permission across three parties:

threshold: 2
keys:
  - address: TKey1...AA, weight: 1
  - address: TKey2...BB, weight: 1
  - address: TKey3...CC, weight: 1

Any two of the three signers can authorize a transaction.

Weighted

Different parties can hold different authority levels:

threshold: 3
keys:
  - address: TFounder...A, weight: 2
  - address: TCofnd1...B, weight: 1
  - address: TCofnd2...C, weight: 1

A founder (weight 2) plus any one cofounder (weight 1) reaches threshold 3. Either cofounder alone (weight 1) does not. Both cofounders working without the founder (1 + 1 = 2) does not.


Active permissions and contract restrictions

An active permission uses operations to specify the transaction types it allows, such as TRX transfers, voting, or resource delegation.

The field is encoded as a 32-byte (256-bit) bitmap. Each bit corresponds to a system contract type ID from the ContractType enum in Tron.proto. Contract type ID n is bit (n & 7) of byte n / 8:

  • ID 0 → byte 0, bit 0 (least-significant bit of first byte)
  • ID 7 → byte 0, bit 7
  • ID 8 → byte 1, bit 0
  • ID 59 → byte 7, bit 3

A bit set to 1 means "this permission can execute this contract type". A bit set to 0 means "this contract type is forbidden under this permission".

Contract type IDs

Every TRON contract type has a numeric ID from the Transaction.Contract.ContractType proto enum. The table below lists popular transaction supported on mainnet:

IDContractTypeDescription
0AccountCreateContractCreate an account
1TransferContractTransfer TRX
2TransferAssetContractTransfer a TRC-10 token
4VoteWitnessContractVote for a Super Representative
5WitnessCreateContractApply to become an SR candidate
11FreezeBalanceContractStake 1.0 — stake TRX
12UnfreezeBalanceContractStake 1.0 — unstake TRX
13WithdrawBalanceContractWithdraw voting rewards
16ProposalCreateContractCreate a governance proposal
17ProposalApproveContractApprove a proposal
30CreateSmartContractDeploy a smart contract
31TriggerSmartContractCall a smart contract
33UpdateSettingContractUpdate consume_user_resource_percent
45UpdateEnergyLimitContractAdjust the Energy limit a deployer subsidizes
46AccountPermissionUpdateContractUpdate account permissions
48ClearABIContractClear a contract's ABI
49UpdateBrokerageContractUpdate SR brokerage rate
54FreezeBalanceV2ContractStake 2.0 — stake TRX
55UnfreezeBalanceV2ContractStake 2.0 — unstake TRX
56WithdrawExpireUnfreezeContractWithdraw unstaked TRX after the cooldown
57DelegateResourceContractDelegate Bandwidth or Energy
58UnDelegateResourceContractCancel resource delegation
59CancelAllUnfreezeV2ContractCancel all pending unstake operations

Source: protocol/src/main/protos/core/Tron.proto enum ContractType. The list reflects the protocol as of java-tron v4.8+. For the source-of-truth enum, also see Details of supported transaction types.

Computing the operations bitmap

To allow a permission to execute, say, TRX transfers (ID 1), SR voting (ID 4), and Stake 2.0 staking (ID 54), compute the bitmap by setting bits 1, 4, and 54:

import org.bouncycastle.util.encoders.Hex;

int[] contractIds = { 1, 4, 54 };  // TransferContract, VoteWitnessContract, FreezeBalanceV2Contract
byte[] operations = new byte[32];
for (int id : contractIds) {
  operations[id / 8] |= (byte) (1 << (id % 8));
}
System.out.println(Hex.toHexString(operations));
// "1200000000004000000000000000000000000000000000000000000000000000"

Decode in the reverse direction:

public static List<Integer> decodeOperations(String operationsHex) {
  byte[] ops = Hex.decode(operationsHex);
  List<Integer> ids = new ArrayList<>();
  for (int i = 0; i < ops.length; i++) {
    for (int bit = 0; bit < 8; bit++) {
      if ((ops[i] >> bit & 0x1) == 1) {
        ids.add(i * 8 + bit);
      }
    }
  }
  return ids;
}

Worked encoding examples

Operations allowedBinary (big-endian by byte, low bit first within each byte)Hex (little-endian byte order)
TransferContract (ID 1) + VoteWitnessContract (ID 4)00010010 00000000 00000000 …12 00 00 …
TransferContract (ID 1) + UpdateAssetContract (ID 15)00000010 10000000 00000000 …02 80 00 …
All system contracts (per Mainnet defaults)01111111 11111111 00011111 …7F FF 1F …

Decoding a hex string by eye: read each byte as a binary nibble pair, with the least-significant bit being the lowest contract ID for that byte. Byte 0's bit 0 = contract type ID 0; byte 0's bit 7 = ID 7; byte 1's bit 0 = ID 8; and so on.

Use case: a hot key for transfers only

A treasury account's owner permission is held by a multi-sig group. To pay routine vendor invoices without convening the multi-sig every time, the treasury creates an active permission with:

  • A single-signer threshold (e.g., threshold: 1, the delegate's address with weight: 1)
  • An operations value that allows only TRX transfers (TransferContract, ID 1) — hex 02 00 00 …
  • All other contract types disabled — the delegate cannot stake, vote, deploy contracts, or modify permissions

The delegate's hot key can sign vendor transfers, but cannot perform any other operation. The owner permission remains in cold storage.


Updating permissions

To modify any permission, the account submits an AccountPermissionUpdateContract transaction. The contract replaces the complete permission configuration: even if you only want to change one active permission, you must submit the new owner permission and the complete active-permission list. An SR account must also submit its new Witness permission; a non-SR account must not submit a Witness permission.

message AccountPermissionUpdateContract {
  bytes owner_address = 1;
  Permission owner = 2;
  Permission witness = 3;
  repeated Permission actives = 4;
}
FieldDescription
owner_addressThe account being modified
ownerThe new owner permission (required, not optional)
witnessThe new Witness permission (only meaningful for SR accounts; otherwise null)
activesThe new list of active permissions (1–8 required)

The transaction is normally authorized by the account's current owner permission. An active permission can also authorize it when the transaction selects that permission and its operations field allows permission updates (AccountPermissionUpdateContract, ID 46).

⚠️

A misconfigured update can make permissions unrecoverable

The node checks whether the permission configuration follows the rules, but passing validation does not mean the corresponding private keys are usable. Before updating permissions, confirm that the configured authorized addresses are correct and that their corresponding private keys can be used to sign.

If you cannot obtain signatures that meet the owner permission's threshold and no usable active permission allows permission updates, the account's permissions cannot be changed again. Other usable active permissions can still authorize the transactions they allow, and an SR can still sign blocks with a valid Witness permission.

Before updating account permissions, check the following:

  • Rehearse the same payload on Shasta or Nile, and verify that the intended signer combinations can meet the threshold and complete a transaction.
  • Check every Base58Check address character by character and confirm that its private key is currently usable.
  • For each planned key-loss scenario, confirm that the remaining usable weight can still meet the threshold.
  • For a staged migration, you may temporarily retain the address of the current owner key in the new keys list if that key remains trusted, then remove it after validating the other keys. Do not retain a key that may be compromised.
  • Create a threshold-1 active permission only when the application explicitly needs a single-key emergency path. It becomes a single-key authorization path for every transaction type allowed by its operations field, so restrict operations and leave ID 46 disabled unless that key is intentionally allowed to change account permissions.

See Reverting the owner permission to single-signature below.

Permission_id in transactions

Every transaction declares which permission level it is signed under via Permission_id in the contract body:

Permission_idPermission
0Owner permission (default if omitted)
1Witness permission — reserved for SR block production; cannot authorize normal contract transactions
2–9Active permissions, in the order they were added to the account

The id of an active permission is automatically assigned by the network in sequence starting at 2. For any Permission_id != 0, the permission's type must equal Active and the requested transaction type must be allowed by the permission's operations field; otherwise the transaction is rejected with Permission type is wrong! or Permission denied!.


Fees

Permission management on TRON charges two kinds of fees. Both are dynamic chain parameters and can be adjusted by governance proposal — query the live values via wallet/getchainparameters rather than hard-coding them.

FeeChain parameterCurrent Mainnet value (query-time snapshot)When charged
Update account permissions#22 getUpdateAccountPermissionFee100 TRX (100,000,000 sun)Every AccountPermissionUpdateContract transaction
Multi-signature surcharge#23 getMultiSignFee1 TRX (1,000,000 sun)Charged once when a transaction carries two or more signatures

Both fees are added on top of the normal Bandwidth or Energy cost of the transaction.


Worked example: 2-of-3 multi-sig setup

The payload below configures a 2-of-3 owner permission and creates one active permission. It assumes that all three owner keys have been verified as usable. owner_address identifies the account being modified; that address does not also have to appear in owner.keys.

{
  "owner_address": "TYourAccount...XX",
  "owner": {
    "type": 0,
    "id": 0,
    "permission_name": "owner",
    "threshold": 2,
    "keys": [
      { "address": "TKey1...AA", "weight": 1 },
      { "address": "TKey2...BB", "weight": 1 },
      { "address": "TKey3...CC", "weight": 1 }
    ]
  },
  "witness": null,
  "actives": [
    {
      "type": 2,
      "id": 2,
      "permission_name": "active0",
      "threshold": 1,
      "operations": "120000000000c00f000000000000000000000000000000000000000000000000",
      "keys": [
        { "address": "TKey2...BB", "weight": 1 }
      ]
    }
  ]
}

After this transaction confirms, transactions using the owner permission require signatures from any two of the three keys. With the active0 permission (id 2), TKey2 can sign alone, but only for TRX transfers, SR voting, and Stake 2.0 transactions (system contract type IDs 1, 4, 54–59), not permission updates (ID 46). The example's operations value is generated using the method under "Computing the operations bitmap" above. Configure this active permission only when these transactions genuinely require single-key authorization.

For the end-to-end transaction flow with multi-party signing, see Account Permission Management transaction example.


Reverting the owner permission to single-signature

The owner permission can be changed back to single-signature as long as a current permission can authorize AccountPermissionUpdateContract: normally an owner permission that meets its threshold, or a usable active permission whose operations field allows permission updates (ID 46). Submit another permission update with one authorized address of weight: 1 in owner.keys and threshold: 1, together with the complete list of 1–8 active permissions. An SR account must also submit its Witness permission; a non-SR account omits it or passes null. The update fee applies again (100 TRX on Mainnet at the time of writing).

This changes only the owner permission. Existing active permissions can still authorize the transaction types allowed by their respective operations fields. To place the entire account under the same single key, also set the keys and threshold of every active permission to that single-key configuration, while retaining only the required operations. Witness is a separate single-key permission used by an SR for block production and should be changed only when its signing address also needs to change.

If the owner permission cannot meet its threshold and no usable active permission enables ID 46, the permission update cannot be authorized and the owner permission cannot be changed back to single-signature.


Limits

LimitValue
Maximum authorized addresses per permission5
Active permissions per account1–8
permission_name lengthUp to 32 characters
Permission_id range0–9 (0 = owner, 1 = Witness, 2–9 = active)
Witness permission address countMust be exactly 1
Active permission parent_idMust be 0

APIs

APIDescription
wallet/accountpermissionupdateUpdate account permissions
wallet/getsignweightInspect collected signature weight on a partial transaction
wallet/getapprovedlistList addresses that have signed
wallet/broadcasttransactionSubmit a fully-signed transaction

Related resources