Align contracts/contract.md with java-tron TVM source, solidity source and mainnet state#602
Open
abn2357 wants to merge 13 commits into
Open
Align contracts/contract.md with java-tron TVM source, solidity source and mainnet state#602abn2357 wants to merge 13 commits into
abn2357 wants to merge 13 commits into
Conversation
- Add missing `version` field to the SmartContract proto snippet and document `code_hash` / `trx_hash` / `version` in the field list. - Rewrite the CREATE section: correct the address formula to `sha3omit12(rootTransactionId || nonce)` (the nonce is concatenated, not pre-hashed) and clarify that `nonce` is a per-root-transaction internal-action counter, not a CREATE counter. - Refresh the built-in function section: drop the outdated "Odyssey-v3.1.1 not supported temporarily" annotations, fold in TVM_VOTE / TVM_TRANSFER_TRC10 / Stake 2.0 / Constantinople-Cancun upgrades (all active on mainnet), and note that ALLOW_TVM_COMPATIBLE_EVM is still inactive on mainnet (RIPEMD160 / BLAKE2F precompiles not yet enabled). Remove the SR proposal- management items, which are chain-level system contracts, not TVM built-ins. - Add `block.basefee` (London / proposal 63) to the Block Related list. - Rename `block.blockhash` to top-level `blockhash` and note the Solidity 0.4.22 / 0.5.0 changes; mark `now` as removed in Solidity 0.7.0.
- trx_hash: clarify that the field is populated only for CREATE2 deployments and stores the root transaction id; CREATE-opcode and gRPC `deployContract` deployments leave it empty. - version: rewrite to reflect that version 1 is a marker stamped on contracts deployed under ALLOW_TVM_COMPATIBLE_EVM (not a behavior switch), and note that the proposal is not active on mainnet, so every mainnet contract is currently version 0. - CREATE section: add that the final 21-byte address has a leading `0x41` TRON address prefix.
…ferences Replace chain-parameter IDs (which were ambiguously labeled "proposal N") with the actual on-chain committee proposal numbers and tronscan links. Also unwrap the built-in-function listing from a code fence so the markdown links render, and correct "read-only opcodes" to "read-only precompiles" for the vote/ reward query helpers (they are precompiles at fixed addresses, not opcodes).
The original note said a smart-contract transfer to a non-existent address cannot create the account. That is the pre-SOLIDITY_059 behavior; on current mainnet (ALLOW_TVM_SOLIDITY_059, committee proposal tronprotocol#29 activated 2020-02-21), Program.createAccountIfNotExist auto-creates the target account when the flag is on, matching the system-contract behavior.
- blockhash: clarify the 0.4.22 deprecation / 0.5.0 removal are upstream Solidity changes; TRON's Solidity fork inherits both from tv_0.4.24. - block.basefee: explain it returns the getEnergyFee chain parameter, not an EIP-1559 per-block base fee (the value only changes via a committee proposal). - now: identify it as an alias for block.timestamp, removed in upstream Solidity 0.7.0 (TRON's fork inherits from tv_0.7.0).
- Tighten ordered-list indentation under the built-in function section - Backtick code identifiers throughout: proto fields, opcodes, chain parameters, Solidity globals/keywords, function and class names - Wrap 'Energy' in backticks where introduced as the resource unit
…y_limit When a contract was deployed without origin_energy_limit, the proto3 default 0 is stored, but ContractCapsule.getOriginEnergyLimit() substitutes CREATOR_DEFAULT_ENERGY_LIMIT (10,000,000) at runtime. The zh-doc already mentioned this; the en-doc was missing it.
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.
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.
6 tasks
abn2357
changed the title
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 and on-chain state. Fixes both factual drift andformatting.
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 / removed in 0.5.0, inherited by TRON's
Solidity fork from
tv_0.4.24block.basefee: clarified it returnsgetEnergyFee(committee-set,not per-block EIP-1559), available since the London upgrade
now: noted removal in upstream Solidity 0.7.0, inherited by TRON'sSolidity fork from
tv_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)(pre-0.6.2 chained syntax) 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.7.0)callcodeis still anAddressTypemember andconstantis rejected byparseFunctionHeader()against thetronprotocol/solidity fork (
Types.cpp,Parser.cpp)backticks, code fences, tronscan links)