Align contracts/contract.md with java-tron TVM source, solidity source and mainnet state#329
Open
abn2357 wants to merge 12 commits into
Open
Align contracts/contract.md with java-tron TVM source, solidity source and mainnet state#329abn2357 wants to merge 12 commits into
abn2357 wants to merge 12 commits into
Conversation
- Rewrite the built-in function section: move it out of the shell code fence and list each feature by its ALLOW_TVM_* chain parameter and the committee proposal that activated it on mainnet (tronprotocol#15, tronprotocol#18, tronprotocol#29, tronprotocol#44, tronprotocol#72, tronprotocol#84, tronprotocol#89, tronprotocol#103) - Fix the transfer-to-non-existent-address note: after the SOLIDITY_059 upgrade (proposal tronprotocol#29), the TVM auto-creates the target account on transfer, matching system-contract behavior - Add block.basefee bullet: returns getEnergyFee, available since the London upgrade (proposal tronprotocol#72) - Add the missing Energy subsection
…-version notes - Add missing 'version = 11' field to the SmartContract proto definition - Add descriptions for code_hash, trx_hash (CREATE2-only) and version - Rewrite the CREATE-address paragraph: spell out the sha3omit12(rootTransactionId || nonce) layout, the 8-byte nonce, the 0x41 prefix, and the per-root-transaction nonce semantics (it increments on every internal action, not only CREATE); point to TransactionUtil.generateContractAddress(byte[], long) - block.blockhash: note that 'block.blockhash(uint)' was deprecated in upstream Solidity 0.4.22 and removed in 0.5.0, inherited by TRON's Solidity fork from tv_0.4.24 - now: note removal in upstream Solidity 0.7.0, inherited by TRON's Solidity fork from tv_0.7.0
- Promote bullet-style subsection headers to '####' so they render as
proper sub-headings instead of list items (constant function,
message calls, delegatecall, CREATE, built-in function, address
conversion/check/assignment)
- Wrap the SmartContract proto definition in a fenced code block
('solidity') instead of a 4-space indented block, matching the
style used by the rest of the doc
- Backtick code identifiers consistently throughout: proto fields,
Solidity globals/keywords ('view', 'pure', 'constant',
'delegatecall', 'msg.sender', 'msg.value', etc), opcodes,
exception names, currency-unit suffixes ('trx', 'sun', 'ether',
'finney'), and the bullet labels under the Block Related list
… guidance The original 'see II-4-7,II-4-8' pointer referred to a chapter numbering scheme that no longer exists in the doc. Replace it with the same concrete instruction used in the en-doc: convert the base58 address to its 20-byte hex form via wallet-cli or a TRON SDK before assigning to a Solidity 'address'.
- Capitalize the product name 'Solidity' wherever it appeared as
lowercase 'solidity' in prose (heading, address-section paragraphs)
- Add half-width spaces between CJK and Latin/digit characters per
Chinese tech-writing convention ('20 字节', '21 字节', '返回 1')
- Fix '20 位地址' → '20 字节地址' (it's bytes, not bits)
- Backtick the Solidity 'address' type identifier in prose
- Rewrite the awkward L146 sentence about address-type conversion
- Reindent the three Solidity snippets in the address section to
standard 4-space body indentation (the originals had column-0 function
declarations with 8-space body indent that looked copy-pasted from
a deeper context)
- Drop the extra blank line between the Block Related list and the
Energy heading
The original hex string was 31 bytes (62 hex chars) — one zero-byte short of the 32-byte ABI slot. Pad to a full 32-byte ABI-encoded value and rewrite the surrounding sentence to describe its structure (11 leading zero bytes + 21-byte TRON address) instead of the inaccurate '21-byte address' claim.
The TRON Solidity fork's liblangutil/Token.h only registers the currency-unit keywords 'wei', 'gwei', 'ether', 'sun' and 'trx' — the 'finney' and 'szabo' keywords were removed in upstream Solidity 0.7.0 and the TRON fork inherited the removal. Mentioning 'finney' is now a compile error, so drop that sentence.
call.value(x) sets msg.value (TRX amount transferred), not the
energy/gas limit. Setting an energy limit on an inner call uses
call.gas(x) in the pre-0.6.2 chained syntax or {gas: x} in the 0.6.2+
options syntax — Solidity removed call.gas/call.value chaining in
0.7.0. Also normalize 'gas' to 'energy' for the TRON resource model
since the wording is talking about TVM consumption, not the API name.
The TRON Solidity fork's parser (Parser.cpp) only accepts Token::Constant
inside parseVariableDeclaration() for state-variable declarations
(alongside Immutable); parseFunctionHeader() does not recognize it.
Writing 'function foo() constant { ... }' is a parser error in the
current fork. Drop 'constant' from the listed function modifiers.
Add a note that legacy contracts may still carry the deprecated
'constant' modifier in their source / ABI — since view/pure/constant
are compile-time annotations only and never enter bytecode, already-
deployed contracts keep working; only recompiling such sources with
the current compiler fails.
The previous wording said TRON's Solidity fork inherits 'both' the 0.4.22 deprecation and the 0.5.0 removal of block.blockhash starting from tv_0.4.24. That tag (Solidity 0.4.24) is post-deprecation but pre-removal — it cannot have inherited the removal. Split the inheritance: deprecation from tv_0.4.24, removal from tv_0.5.4 (the earliest tv_0.5.x tag in the fork).
Where the Solidity upstream version and the TRON fork tv-tag have the same numeric form (e.g., upstream 0.7.0 / tv_0.7.0), drop the parenthetical 'TRON fork tv_X.Y.Z' restatement and write the version once. Keep the dual notation only where the two diverge (blockhash: upstream 0.4.22 vs fork tv_0.4.24, upstream 0.5.0 vs fork tv_0.5.4). Also tighten the chained/options syntax labels to cite the precise upstream version boundaries (removed in 0.7.0; introduced 0.6.2) instead of the imprecise 'pre-0.6.2' shorthand.
Normalize the inline-note prefix to **Note**: / **注意**: across the document. Also unify the lone 注: (shorthand) introduced in an earlier commit to 注意: for label consistency.
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
1 participant
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
Iteratively audited
docs/contracts/contract.mdagainst the currentjava-tronTVM source, thetronprotocol/solidityfork, and on-chainstate. Fixes both factual drift and formatting. Content-aligned with
the English counterpart
tronprotocol/documentation-en#602.
Notable corrections:
SmartContractproto fields: tightenedorigin_energy_limit,code_hash,trx_hash(CREATE2-only), andversionsemanticsorigin_energy_limitlegacy default: noted that for old contractsdeployed without this parameter, the stored value is 0 but the
runtime substitutes a 10,000,000 energy default
(
CREATOR_DEFAULT_ENERGY_LIMIT) viaContractCapsule.getOriginEnergyLimit()sha3omit12(rootTransactionId || nonce)layout, the 8-byte big-endian nonce, the per-root-transaction (not
per-account) nonce semantics, and pointed to
TransactionUtil.generateContractAddress(byte[], long)supported temporarily" note with concrete per-feature status, gated
by their actual
ALLOW_TVM_*chain parameters and referencing thecommittee proposals that activated them on mainnet:
#29,
#15,
#18,
#44,
#72,
#84,
#89,
#103
behavior change (auto-account-creation after committee
proposal #29)
blockhash: noted thatblock.blockhash(uint)was deprecated inupstream Solidity 0.4.22 and removed in 0.5.0; in TRON's Solidity
fork the deprecation is inherited from
tv_0.4.24and the removalfrom
tv_0.5.4onwardsblock.basefee: clarified it returnsgetEnergyFee(committee-set,not per-block EIP-1559), available since the London upgrade
now: noted removal in Solidity 0.7.0zero-byte short of the 32-byte ABI slot; padded to a proper 32-byte
ABI-encoded value and rewrote the surrounding sentence to describe
its structure (11 leading zero bytes + 21-byte TRON address) instead
of the inaccurate "21-byte address" claim
call.value(x)sets msg.value (TRXamount), not the energy/gas limit. Corrected the message-call section
to use
call.gas(x)(chained syntax, removed in Solidity 0.7.0) or{gas: x, value: ...}(0.6.2+ options syntax), and normalized "gas"to "energy" where the text refers to TVM resource consumption rather
than the Solidity API name
constantfunction modifier: dropped from the listed functionmodifiers because the TRON Solidity fork's
Parser.cpponly acceptsToken::Constantfor state-variable declarations, not for functionheaders —
function foo() constant { ... }is a parser error in thecurrent compiler. Added a note that legacy contracts may still carry
the deprecated modifier in their source/ABI; since view/pure/constant
are compile-time annotations and never enter bytecode, already-deployed
contracts keep working — only recompiling such sources fails
Formatting:
chain parameters, Solidity globals/keywords, function and class
names); left product/concept names (TRON, Ethereum, Solidity, TVM,
TRX/sun, Stake 2.0, etc.) as plain text
section so nested bullets render reliably across renderers
Test plan
java-tronTVM source(PrecompiledContracts.java, Op.java, OperationRegistry.java,
Program.java, TransactionUtil.java, ProposalUtil.java,
ContractCapsule.java, Constant.java)
wallet/getchainparametersactivated which
ALLOW_TVM_*key) viawallet/getproposalbyidclaims against the tronprotocol/solidity fork tags (
tv_0.4.24,tv_0.5.4,tv_0.7.0)callcodeis still anAddressTypemember andconstantis rejected byparseFunctionHeader()against thetronprotocol/solidity fork (
Types.cpp,Parser.cpp)backticks, code fences, tronscan links)