Skip to content

Fix system contracts doc: sync with java-tron proto#328

Open
abn2357 wants to merge 8 commits into
tronprotocol:masterfrom
abn2357:fix_system_contract
Open

Fix system contracts doc: sync with java-tron proto#328
abn2357 wants to merge 8 commits into
tronprotocol:masterfrom
abn2357:fix_system_contract

Conversation

@abn2357
Copy link
Copy Markdown
Contributor

@abn2357 abn2357 commented May 15, 2026

Summary

Follows the English-side PR tronprotocol/documentation-en#601 to bring the Chinese docs/mechanism-algorithm/system-contracts.md back 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)

  • Added a top-level ContractType overview table for easy cross-referencing; replaced the duplicated ContractType table in multi-signatures.md with an anchor link to this overview.
  • Removed the "(已废弃)" prefix from the FreezeBalanceContract heading since its disabled status is already reflected in the new ContractType overview table.
  • Reordered UpdateEnergyLimitContract, ClearABIContract, UpdateBrokerageContract, and added a new AccountPermissionUpdateContract section, all placed before ShieldedTransferContract.
  • Added MarketSellAssetContract and MarketCancelOrderContract after ShieldedTransferContract.
  • Added Stake 2.0's CancelAllUnfreezeV2Contract at the end.
  • Clarified AccountPermissionUpdateContract field semantics: witness is required only for SRs and must be empty for non-SRs; actives is capped at 8.

Additional fixes from source-code cross-check (commit 9b2d476)

  • UnfreezeBalanceContract.receiver_address: field number corrected from 13 to 15.
  • AssetIssueContract: added missing int32 precision = 7; and string id = 41; fields, with matching field descriptions.
  • AssetIssueContract.order: updated the stale inline comment from // the order of tokens of the same name to // useless (the field has no business effect in the current source).
  • DelegateResourceContract: added the missing int64 lock_period = 6; field with a description covering its semantics and the MAX_DELEGATE_LOCK_PERIOD proposal gating; corrected the lock field description (the original "lock for 3 days" is no longer accurate).

Terminology and field-description polish (commit f2becc9)

  • Per-contract owner_address descriptions. 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 the Arrays.equals(ownerAddress, deployedContractOwnerAddress) check in each actuator).
  • Witness terminology. Renamed headings and field descriptions that used "超级节点候选人" to "Witness" (e.g. "创建 Witness", "更新 Witness URL", "投票 Witness") to match the proto type name and the rest of the doc.
  • TRC-10 spelling. Standardized TRC10TRC-10 across the ContractType table and prose, and added missing spaces around TRC-10 in bullet descriptions.
  • Token vocabulary. Replaced legacy 通证 / 代币 with token and 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 heading. Changed "## 发布 TRC-10 …" to "## 发行 TRC-10 token AssetIssueContract" to align with the contract's actual semantics (AssetIssueContract = issue, not publish).

Test plan

  • mkdocs build --strict passes
  • The ./system-contracts.md#contracttype anchor resolves correctly from multi-signatures.md
  • All revised fields match the current java-tron master proto definitions
  • Each per-contract owner_address description was cross-checked against the corresponding *Actuator.validate() in java-tron

abn2357 added 2 commits May 15, 2026 14:47
- 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`:合约持有人地址。
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, we need to find a more accurate description — preferably a unified one.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

abn2357 added 6 commits May 21, 2026 09:09
…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).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants