Fix system contracts doc: sync with java-tron proto#328
Conversation
- Add ContractType overview table at the top of system-contracts.md as the single source of truth. - Replace the duplicated ContractType table in multi-signatures.md with a cross-link to the new overview section. - Fill in previously missing per-contract sections: AccountPermissionUpdateContract, MarketSellAssetContract, MarketCancelOrderContract, CancelAllUnfreezeV2Contract. - Reorder UpdateEnergyLimitContract, ClearABIContract and UpdateBrokerageContract to follow the proto enum order. - Drop the "(已废弃)" prefix from FreezeBalanceContract heading; status is already conveyed in the overview table. - Tighten AccountPermissionUpdateContract field constraints (witness required for SR / empty for non-witness; actives <= 8).
- UnfreezeBalanceContract.receiver_address: field number 13 -> 15 - AssetIssueContract: add precision (=7) and id (=41) fields - AssetIssueContract.order: update stale comment to // useless - DelegateResourceContract: add lock_period (=6); correct lock description
| } | ||
| ``` | ||
|
|
||
| * `owner_address`:合约持有人地址。 |
There was a problem hiding this comment.
Note: the owner_address description ("合约持有人地址") is a long-standing ambiguity in this doc. A more precise definition: owner_address is the address of the account whose pending V2 unfreeze operations are to be cancelled — i.e. the resource-owning account, not necessarily the transaction signer. In a multi-sig scenario, the actual signer could be a delegated account that holds the required permission on behalf of the owner. This applies consistently across all system contracts. No need to block this PR — suggest to address it in a follow-up cleanup PR.
There was a problem hiding this comment.
I really agree with your statement. This translation is both outdated and inaccurate. How about globally translating it as "Transaction initiator address", which applies to all transaction types?
There was a problem hiding this comment.
"Transaction initiator address" might not be accurate in a multi-sig scenario. I haven't found a single unified description that works cleanly across all system contracts yet. Looking forward to more good ideas. Now I'm leaning toward per-contract descriptions, e.g. FreezeBalanceV2Contract — "The address of the account that stakes TRX", CreateSmartContractContract — "The address of the account that deploys the contract", and so on.
There was a problem hiding this comment.
The owner address doesn't seem to have anything to do with multi-signature. It's like an SR—he can grant witness permissions to another account, but the block owner is still himself—only the signature changes.
There was a problem hiding this comment.
You're right that owner_address itself is independent of multi-sig — it always identifies the account the operation belongs to, regardless of who signs. The concern is specifically with the term "initiator": in a multi-sig scenario, the actual initiator (signer) is the delegated account, not the owner. So "Transaction initiator address" could be misread as referring to the signer rather than the owner. That's the ambiguity we're trying to avoid.
There was a problem hiding this comment.
Yes, we need to find a more accurate description — preferably a unified one.
There was a problem hiding this comment.
I have written a separate definition of owner_address for each contract type as you suggested. Also, I drop subjects from ContractType overview table to avoid permission ambiguity. Please review it again, Thx. Detailed information starts from this commit.
…ogy, TRC-10 and token style - Replace generic owner_address description with per-contract semantics (signer vs state-owning account, e.g. token issuer, contract deployer) - Use Witness instead of 超级节点候选人 in headings and field descriptions - Standardize TRC-10 spelling (TRC10 -> TRC-10, add missing spaces) - Use 发行 instead of 发布 for TRC-10 issuance to match AssetIssueContract - Replace 通证/代币 with token; lowercase token in prose, keep proto field names as-is
…cribe) - ContractType table: 认购 -> 参与...发行 - Section heading: 购买 -> 参与...发行 - owner_address: 参与认购的账户地址 -> 参与 TRC-10 token 发行的账户地址
- Make several thin owner_address descriptions more specific: - VoteWitness: 投票账户地址 -> 为 Witness 投票的账户地址 - WitnessUpdate: Witness 账户地址 -> 更新 URL 的 Witness 账户地址 - ExchangeInject/Withdraw: 注资/撤资 -> 注入/撤出流动性 - ExchangeTransaction: 交易账户地址 -> 通过交易对兑换资产的账户地址 - UpdateBrokerage: Witness 账户地址 -> 调整分成比例的 Witness 账户地址 - UnDelegateResource: 取消代理方 -> 回收已代理资源的账户地址 - Replace 分红 with 分成 in UpdateBrokerage section - Unify delegate terminology: 委托 -> 代理 in ContractType table - Rename UnDelegate section heading from 取消资源代理 to 回收先前代理的资源
- Unify SR to Witness in overview rows (VoteWitness, WitnessCreate, WitnessUpdate, ProposalCreate, ProposalApprove, UpdateBrokerage) - Unify 解冻 to 解质押 in V2 staking contexts; keep 冻结/解冻 in ICO context - UpdateBrokerage: 佣金 -> 分成 (align with bullet/heading) - ExchangeWithdraw: 赎回 -> 撤回 - ExchangeCreate bullet: 创建交易所 -> 创建交易对; add creator-only constraint to ExchangeWithdraw bullet - Exchange section headings: 交易所 -> 交易对; align verbs with bullets - UnDelegateResource: clarify resource/balance descriptions as 回收代理资源 - ZH multi-signatures-related text: 超级代表/见证人 -> Witness
The original subjects (Witness/Contract owner/Issuer/Proposal creator/ Exchange pair creator) imply only that specific role can perform the action. In TRON, the actual signer can be a different account via AccountPermissionUpdateContract (TIP-16), even though owner_address must still equal a specific protocol-level address. Drop the subjects so the table describes the action itself; per-contract owner_address bullets continue to spell out the address-level constraint. Also add the 'must be the pair's creator' constraint to the ExchangeInject owner_address bullet (mirrors ExchangeWithdraw).
Summary
Follows the English-side PR tronprotocol/documentation-en#601 to bring the Chinese
docs/mechanism-algorithm/system-contracts.mdback in sync, and additionally corrects proto-field discrepancies that were missed by the English PR after cross-checking against the java-tron source (protocol/src/main/protos/core/contract/*.proto).Changes aligned with the English PR (commit 3abcfd7)
ContractTypeoverview table for easy cross-referencing; replaced the duplicated ContractType table inmulti-signatures.mdwith an anchor link to this overview.FreezeBalanceContractheading since its disabled status is already reflected in the new ContractType overview table.UpdateEnergyLimitContract,ClearABIContract,UpdateBrokerageContract, and added a newAccountPermissionUpdateContractsection, all placed beforeShieldedTransferContract.MarketSellAssetContractandMarketCancelOrderContractafterShieldedTransferContract.CancelAllUnfreezeV2Contractat the end.AccountPermissionUpdateContractfield semantics:witnessis required only for SRs and must be empty for non-SRs;activesis capped at 8.Additional fixes from source-code cross-check (commit 9b2d476)
UnfreezeBalanceContract.receiver_address: field number corrected from13to15.AssetIssueContract: added missingint32 precision = 7;andstring id = 41;fields, with matching field descriptions.AssetIssueContract.order: updated the stale inline comment from// the order of tokens of the same nameto// useless(the field has no business effect in the current source).DelegateResourceContract: added the missingint64 lock_period = 6;field with a description covering its semantics and theMAX_DELEGATE_LOCK_PERIODproposal gating; corrected thelockfield description (the original "lock for 3 days" is no longer accurate).Terminology and field-description polish (commit f2becc9)
owner_addressdescriptions. Replaced the catch-all "合约持有人地址" with contract-specific semantics, cross-checked against the corresponding*Actuator.validate()in java-tron. For example:AssetIssueContract.owner_address→ "发行 TRC-10 token 的账户地址";UnfreezeAssetContract.owner_address→ "token 发行方账户地址";UpdateSettingContract/UpdateEnergyLimitContract/ClearABIContract→ "智能合约部署者账户地址" (validated by theArrays.equals(ownerAddress, deployedContractOwnerAddress)check in each actuator).TRC10→TRC-10across the ContractType table and prose, and added missing spaces aroundTRC-10in bullet descriptions.tokenand lowercased it in prose; proto field names and code blocks (token_id,call_token_value,first_token_id, ...) are intentionally left as-is to match the source.AssetIssueContract= issue, not publish).Test plan
mkdocs build --strictpasses./system-contracts.md#contracttypeanchor resolves correctly frommulti-signatures.mdjava-tronmaster proto definitionsowner_addressdescription was cross-checked against the corresponding*Actuator.validate()in java-tron