Sync system-contracts doc with java-tron proto#601
Open
abn2357 wants to merge 7 commits into
Open
Conversation
…ctType overview - Add missing contracts: MarketSellAssetContract, MarketCancelOrderContract, CancelAllUnfreezeV2Contract - Expand the Account Permission Management link into a full AccountPermissionUpdateContract message section - Fix ParticipateAssetIssueContract field name: account_name -> asset_name - Reorder all sections to match the ContractType enum order - Move the ContractType overview table from multi-signatures.md to system-contracts.md as the canonical index, leaving a link reference behind
- ClearABIContract: rename account_address to contract_address to match proto - AccountPermissionUpdateContract: clarify that witness permission is required for SR accounts and must be empty otherwise; note 8-entry cap on actives - Drop (Deprecated) prefix from FreezeBalanceContract heading for consistency with other disabled contracts (status is already in the overview table)
4 tasks
- AssetIssueContract: add missing precision=7 and id=41 fields; fix the
order=11 comment ("useless"); document the id field.
- UnfreezeBalanceContract: correct receiver_address field number from 13
to 15.
- DelegateResourceContract: add missing lock_period=6 field and document
its interaction with the MAX_DELEGATE_LOCK_PERIOD proposal.
…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 in headings and field descriptions; rename participant role from subscriber to participating in the asset issue; table Subscribe -> Participate - Standardize TRC-10 spelling (TRC10 -> TRC-10, fix stray spacing) - Lowercase token in prose; keep proto field names as-is
- VoteWitness: voter account -> account casting votes for Witnesses - WitnessUpdate: The Witness account address -> address of the Witness updating its URL - ExchangeTransaction: trading account -> account exchanging assets via the pair - UpdateBrokerage: The Witness account address -> address of the Witness adjusting its brokerage ratio - UnDelegateResource: canceling the delegation -> reclaiming previously delegated resources
- Unify SR to Witness in overview rows (VoteWitness, WitnessCreate, WitnessUpdate, ProposalCreate, ProposalApprove, UpdateBrokerage) - ExchangeWithdraw: redeems -> withdraws - ExchangeCreate bullet: creating the exchange -> creating the exchange pair; add creator-only constraint to ExchangeWithdraw bullet - VoteWitness vote_address: SR or candidate -> Witness - AccountPermissionUpdate witness field: SR (witness) accounts -> Witness - UpdateBrokerage bullet: Commission rate -> Brokerage ratio (typo fix)
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).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Brings
docs/mechanism-algorithm/system-contracts.mdback in sync with the currentjava-tronsource after cross-checkingprotocol/src/main/protos/core/Tron.proto, the per-contract*.protofiles, and each*Actuator.java.ContractType overview and missing sections (commit b5784bd)
system-contracts.mdlisting everyContractTypeenum value with its Proto Message, Actuator class, current status, and triggered business; per-contract message definitions stay in the sections below.UpdateEnergyLimitContract,AccountPermissionUpdateContract,MarketSellAssetContract,MarketCancelOrderContract,CancelAllUnfreezeV2Contract.(Deprecated)prefix from theFreezeBalanceContractheading so it lines up with the other disabled contracts (status is already conveyed in the overview table).ContractTypetable inmulti-signatures.mdwith a link to the new overview section to keep a single source of truth.Field-name and constraint fixes (commit 08f0d49)
ParticipateAssetIssueContract:account_name→asset_nameClearABIContract:account_address→contract_addressAccountPermissionUpdateContractfield constraints to matchAccountPermissionUpdateActuator.validate():witnessis required for SR accounts and must be empty for non-witness accountsactivesis capped at 8 entriesProto definition sync (commit 63177d2)
UnfreezeBalanceContract.receiver_address: field number corrected from13to15.AssetIssueContract: add missingint32 precision = 7;andstring id = 41;fields with matching descriptions; update the staleorderinline comment to// useless(no business effect in current source).DelegateResourceContract: add the missingint64 lock_period = 6;field with a description covering its semantics and theMAX_DELEGATE_LOCK_PERIODproposal gating; correct thelockfield description (the original "lock for 3 days" is no longer accurate).Terminology and field-description polish (commit 89e65f0)
owner_addressdescriptions. Replace the generic placeholder with contract-specific semantics, cross-checked against the corresponding*Actuator.validate()in java-tron. For example:AssetIssueContract.owner_address→ "The address of the account issuing the TRC-10 token.";UnfreezeAssetContract.owner_address→ "The address of the token issuer." (validated byaccountCapsule.getAssetIssuedName()/getAssetIssuedID()non-empty checks);UpdateSettingContract/UpdateEnergyLimitContract/ClearABIContract→ "The address of the contract deployer." (validated by theArrays.equals(ownerAddress, deployedContractOwnerAddress)check in each actuator). Distinguishes the state-owning account from the signer, which matters under multi-sig.ParticipateAssetIssueContract.owner_addressfrom "the subscriber account" to "the account participating in the asset issue" to match the proto name. Update the ContractType table entry fromSubscribetoParticipate.TRC10→TRC-10across the ContractType table and prose; fix stray spacing.Token→tokenin prose (e.g. table cell "TRC-10 token transfer"); proto field names and code blocks remain unchanged.Test plan
mkdocs serve/mkdocs build --strictrenders the overview table and new sections without warningsmulti-signatures.md(./system-contracts.md#contracttype-overview) resolvesTron.protoand the corresponding*Actuator.javaconstructor in java-tronowner_addressdescription was cross-checked against the corresponding*Actuator.validate()in java-tron