AccountPermissionUpdate: Rewriting the Key-Set

Most TRON accounts never change their permissions. They are created with a default owner permissionThe highest permission on a TRON account: it can authorize any transaction type and — uniquely — rewrite the account's entire permission structure. By default it is held by the account's own address with a threshold of one, and whoever satisfies the owner permission ultimately controls the account. — one key, the account’s own, weight one, threshold one — and they keep it for life. Every transactionA signed instruction ("tx" for short) that changes on-chain state — transferring value, calling a contract, or updating an account's settings. Once it is included in a block and that block reaches finality the record is permanent: later transactions can supersede its effects, but the entry itself can never be edited or deleted. Before finality, a freshly included transaction can still be reversed if its block is reorganized out. they send is authorized by that single key, and the permission structure is a formality.

When an account does change its permissions, one contract type does the job, and its shape is worth understanding up front: the transaction replaces the account’s entire authorization structure at once. Both the forensic value and the danger come from that.

This article is about the mechanic — the contract itself, what a permission is made of, and how a valid update can still be a fatal one. How to read a permission structure as a control signal is a separate question; here the subject is the transaction that writes it.

The contract that rewrites control

AccountPermissionUpdateContract is contract type 46 in the protocol. Its job is to set an account’s permissions, and its fields are the permissions themselves:

Field	What it carries
owner_address	The account being modified.
owner	The new owner permission. The protocol marks it “Empty is invalidate” — you cannot submit without one.
witness	The new witness permission. “Can be empty” — only Super RepresentativeOne of the 27 elected block producers on the TRON network, chosen every six hours from a wider candidate pool by TRON Power voting (one vote per staked TRX); candidates ranked 28th–127th, called SR partners, earn voting rewards without producing blocks. SRs collect block and vote rewards and pass a share to their voters after deducting a self-set commission. TRON's protocol code also calls these producers "witnesses" — a term other DPoS chains such as Steem and Hive use for the same role. accounts use it.
actives	The new active permissionsA delegated permission on a TRON account that can authorize only the transaction types enabled in its operations field, a bitmask with one bit per contract type. An account may configure up to eight active permissions, so an owner can grant, for example, transfer rights to an operational key without surrendering the power to change permissions., as a list. Also “Empty is invalidate.”

The account’s stored state mirrors these fields exactly: an owner_permission, a witness_permission, and a list of active_permission. The update contract is a whole-state assignment — the permissions the account will have after it lands are the permissions inside the contract, and nothing else. The account model describes what those three permission slots mean; this contract is the only way to write them after creation.

What the contract writes

Each permission the contract carries is a compact structure. The full model — how keys, weights, and thresholds resolve, and what an operations bitmask allows — is the subject of the account-model article; the pieces the update writes are:

Element	Meaning
type / id	Owner (id 0), Witness (id 1), or Active (id 2 and up).
threshold	The signing weight an action under this permission requires.
keys	Up to five addresses, each with a weight.
operations	Active permissions only — a 32-byte bitmask, one bit per contract type.
permission_name	A human label, stored on-chain but not load-bearing.

One asymmetry is worth flagging now. An active permission’s operations mask can be scoped to a narrow set of contract types. The owner permission carries no such limit — it can authorize anything, including the next AccountPermissionUpdateContract. Keep that in mind for the lockout section below.

All-or-nothing: the whole set, every time

The property that surprises people is that the update overwrites. The developer documentation is explicit: “This interface will override the original account permissionsTRON records who may act for an account directly in on-chain account state: one owner permission and up to eight active permissions, each a list of weighted keys — each key recorded as a TRON address, not a raw public key — with a threshold. Reading this structure answers, from the ledger itself, who can authorize transactions for the account right now., so even if you only want to modify the owner permission, you still need to configure the witness (if it is a witness account) and active permissions.” The java-tron reference calls it “an ‘all-or-nothing’ update” and warns that “even if modifying a single permission, the full permission set must be resubmitted to prevent accidental loss of access.”

There is no partial update. To add one key to an active permission, you resubmit the owner permission, every active permission, and the witness permission if the account is a Super Representative. What you submit is the complete desired end-state, with the one change folded in. Whatever you leave out is gone.

The transaction also carries a fee. Modifying account permissions costs 100 TRXThe native coin of the TRON network. TRX settles value directly (no contract call needed), is staked to obtain Energy, Bandwidth, and voting power, and is burned to pay fees when staked resources fall short. Its smallest unit is the sun: 1 TRX = 1,000,000 sun. as of 2026 — not a resource cost paid in BandwidthA TRON network resource that covers the byte-size cost of putting a transaction on chain — one byte consumes one Bandwidth point. Every account receives a small free daily allowance (also called free bandwidth); heavier usage requires staking TRX, receiving a delegation, or burning TRX to cover the bytes. or EnergyA TRON network resource that meters the computational cost of smart-contract execution, consumed whenever a transaction calls contract code — including TRC-20 token transfers such as USDT. An account obtains Energy by staking TRX or receiving a delegation from another account; if it holds too little, the shortfall is paid by burning TRX from its balance. but a flat TRX fee, and one set by governance chain parameter, which means a Super Representative proposal can change it. The fee is small relative to what the transaction changes.

How an update locks an account out

The all-or-nothing design has a failure mode the static permission picture does not show. A permission whose threshold exceeds the combined weight of its keys is unsignable — an unreachable-threshold configuration the account-model article covers as a deliberate freeze. The danger unique to the update is how easily a routine change writes that state by accident.

Because every update resubmits the entire set, a permission is preserved only if you re-include it correctly. Omit your own key from the owner permission in a full resubmission, set a threshold one point too high, or list an addressA public identifier, derived from a key pair, at which an account receives funds and is looked up on-chain. Anyone can view an address's history, but only the matching private key can spend from it. TRON addresses are 34-character Base58Check strings beginning with "T". whose private keyA mathematically linked pair — a private key that signs transactions, and a public key (with the address derived from it) that lets anyone verify those signatures. Whoever holds the private key controls the address: on a blockchain, ownership is key control, whatever any off-chain record says. "Keypair", "private key", and "public key" all refer to parts of this same structure. you do not hold — and the transaction is accepted, because its shape is valid, and the account is now unsignable under that permission.

Do this to an active permission and you disable one path. Do it to the owner permission — the only permission that can rewrite permissions — and there is no recovery: re-permissioning the account requires clearing the owner threshold that can no longer be met. The documentation’s warning about “accidental loss of access” is precisely this: one careless full resubmission, and the lockout is permanent.

What a permission change tells a reader

Permission changes are rare, fee-bearing, and irreversible. When an AccountPermissionUpdateContract appears in an account’s history, the control arrangement changed on purpose at that block — a key added, a threshold raised, authority handed to a new address.

The transaction is also a complete record of the handover. Because the contract carries the full new key-set, it shows the after-state on its face: which addresses can now sign, with what weights, against what threshold. Compare that to the before-state and you have exactly what changed — a single-key account becoming a multi-sig, say, or one owner key swapped for another.

Two smaller reads come along with it. The operations mask on each active permission records precisely which contract types a delegated key may run; a key granted broad operations is a different arrangement from one scoped to a single contract, and the mask spells out which. And a self-locked account is visible: one whose owner permission can never meet its threshold is inert, able to receive value but never to send or re-permission it. That terminal state was written by one transaction, and it is on the record.

The permission structure answers “who can sign for this account.” This contract marks the moment that answer was last written, and because it always carries the full set, the whole new answer is right there in the transaction.

Sources

• account_contract.proto — tronprotocol/protocol — the AccountPermissionUpdateContract message: owner_address, owner (“Empty is invalidate”), witness (“Can be empty”), and actives (“Empty is invalidate”).
• Tron.proto — tronprotocol/protocol — the Permission message (type, id, threshold, parent_id, operations “1 bit 1 contract”, keys), the Key message (address, weight), and the Owner/Witness/Active permission-type enum.
• Account Permission Management — TRON Developer Hub — the override behavior, permission IDs, up to 8 active permissions, and the threshold rule. The live page still gives the override warning, as “This contract overwrites all three permission slots at once”, but no longer in the words quoted in the body, so the archived revision below is cited for the wording.
• Account Permission Management — TRON Developer Hub, archived 2025-10-12 — the revision carrying the override wording quoted in the body: “This interface will override the original account permissions, so even if you only want to modify the owner permission, you still need to configure the witness (if it is a witness account) and active permissions.” TRON has since rewritten the live page in place, so the last archived revision carrying this wording is cited alongside it.
• Account Permission Management — java-tron documentation — the “all-or-nothing” characterization, up to five keys per permission, the 32-byte little-endian operations bitmask, and the 100 TRX fee to modify account permissions.