docs: add Tron ecosystem baseline (tron-contracts) - #198
Merged
Merged
Conversation
✅ Deploy Preview for openzeppelin-docs-v2 ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Add a baseline docs section for OpenZeppelin Contracts for Tron, mirroring the structure of the Solidity contracts docs. Content is ported from the tron-contracts and tron-contracts-upgradeable repositories' AsciiDoc docs. - New content/tron-contracts/ section (16 pages): Overview, TVM Differences, Extending Contracts, Using with Upgrades, Backwards Compatibility, Access Control, Tokens (TRC-20 + Creating Supply, TRC-721, TRC-1155, TRC-4626, TRC-6909), Governance, Utilities, FAQ. - New "TVM Differences" page summarizing EVM<->TVM divergences (CREATE2 0x41 prefix, P256/RIP-7212, TRX 6 decimals, USDT-TRON transfer, TIP-712 address format, EIP-7702/4337, resource model, block cadence). - TRON branding: logomark icon, ecosystem tab, homepage card, nav wiring (navigation tree, ecosystem detection, path -> tree hook). - Diagrams copied under public/tron/. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sync the Tron pages with tron-contracts and tron-contracts-upgradeable at the 5.6.0-rc.1 release: - index: link the published npm packages, port the versioning policy, drop bug-bounty claims, point security reports at GitHub advisories, and replace the @dev install example with @next (npm publishes only latest and next). - utilities: P256 verifies in Solidity (TIP-7951 cited, verifyNative gone), TRC165/TRC1271/trc7201Slot renames, TIP-2935 blockhash note, correct TRC165 usage (no _registerInterface). - governance: TRON 3-second block arithmetic (28800/201600) plus the block-time callout, TRC-6372/TRC-5805 names, TRX instead of ETH, remove the nonexistent TRC20VotesComp variant. - tvm-differences: safeTransferChecked default (H-01), corrected P256, EIP-7702 and ERC-4337 rows, new TRC-10 row and section, new callout on 20-byte addresses inside bytes payloads. - trc4626: fee example uses safeTransferChecked. - access-control: TimelockController self-administration, AccessManager cancellation rights incl. role admins (#141). - upgradeable, backwards-compatibility: recommend the Tron Upgrades plugins; upgradeable versioning note. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
pepebndc
force-pushed
the
docs/tron-ecosystem-baseline
branch
from
August 24, 2026 09:47
b5276b1 to
9647c86
Compare
✅ Deploy Preview for openzeppelin-docs-v2 ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Tightens the Overview to explain what @openzeppelin/tron-contracts is, that it intentionally preserves upstream OpenZeppelin Contracts APIs where the TVM behaves like the EVM, and adapts them where TRON's standards or the TVM's execution model genuinely diverge (grounded in the tron-contracts README's own Overview section). Cleans up porting residue left over from the Ethereum-docs source: - "a token contract is simply an Ethereum smart contract" -> TRON - "tokens built on Ethereum is called TRC-20" -> TRON - TRC-1155's Golem/GNT example mislabeled a Ethereum-only ERC-20 token as a "TRC20-backed project" - TRC-6909 intro read as if TRC-6909 itself was published in 2018 (that date belongs to TRC-1155/EIP-1155, which it draws on) and mislabeled it a "draft EIP" - "Ethereum Signatures (secp256k1)" heading and prose, describing TRON's own native account signature scheme as if foreign to TRON - "the EVM supports ECDSA" -> the TVM, in a TVM-native docs page - "a single regular Ethereum account (EOA)" -> EOA is TRON's own account model too, not an Ethereum-only concept Adds targeted callouts where the docs assumed Ethereum-ecosystem tooling that doesn't exist on TRON, verified via web research rather than assumption: - access-control.mdx recommended Gnosis Safe and Aragon DAO as ownership options; neither is deployed on TRON. Adds a callout pointing to TRON's native account-level multisig (Owner/Active permissions, no contract required) as the actual TRON-native path, and clarifies when a custom governance contract is still the right tool. - governance.mdx presented Tally as the governance UI and used raw Ethers.js calls throughout; Tally does not support TRON (confirmed: requires an EVM RPC and an Etherscan-style explorer API, which the TVM doesn't provide), and the two "Tally" screenshots embedded in the page are byte-for-byte identical to the ones in the Ethereum docs (verified via checksum) -- they depict Ethereum's Tally UI, not TRON. Adds callouts disclosing this at the guide's intro, the Tally subsection, and next to both screenshots, and points at TronWeb-based tooling (already established elsewhere in this PR, e.g. upgradeable.mdx) as what actually reaches a TRON node. No navigation, structural, or generic (non-Ethereum-specific) content changes. Verified against tron-contracts and tron-contracts-upgradeable at v5.6.0-rc.1 and against the original openzeppelin-contracts docs source these pages were ported from. Self-checked against the docs-pr-review skill pipeline (architecture, ecosystem primer, DevX, style, self-check) after drafting; fixed the issues that pass surfaced in this session's own new prose, including nine em dashes introduced across the two rounds of edits (house style avoids them) and a "TRON USDT" naming inconsistency with the diff's established "USDT-TRON". Pre-existing findings from that review (untouched by this commit) are reported separately for human triage rather than fixed here, since they fall outside this commit's stated scope or are inherited site-wide patterns shared with every other ecosystem's docs, not specific to Tron. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
backwards-compatibility.mdx was a near-verbatim port from the Ethereum docs (content/contracts/5.x/backwards-compatibility.mdx), differing only in two already-fixed links/plugin names. Its "Draft or Pre-Final ERCs" section still framed the draft-*.sol convention as an Ethereum-only ERC concern, but the real tron-contracts repo's draft-*.sol files are a mix of TRON-native standards (draft-ITRC7802.sol, draft-ITRC1822.sol, draft-TRC7786.sol, draft-TRC20Bridgeable.sol) and inherited ERCs kept as-is (draft-IERC6093.sol), plus chain-agnostic ones (draft-InteroperableAddress.sol). Broadens the section to "Draft or Pre-Final Standards" covering both TRON's own TIPs/TRCs and inherited EIPs/ERCs. Verified TRON's TIP process has its own real "Final" status (Draft -> Last Call -> Final/Accepted, per github.com/tronprotocol/tips) before reusing that word here, so the claim isn't just carried over from the Ethereum-docs assumption. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…nly claims Audited every ERC-/EIP- reference in content/tron-contracts against what the tron-contracts repo actually names things, rather than against the Ethereum docs these pages were ported from. Renames the standards the repo already ported to TRC naming, which the prose still cited by their Ethereum names: - TRC-165 (utilities Introspection; repo has ITRC165/TRC165/TRC165Checker, and tvm-differences.mdx already claimed ERC165 -> TRC165) - TRC-1271, TRC-7913 (utilities Signature Verification; repo has ITRC1271, isValidTRC1271SignatureNow, ITRC7913, SignerTRC7913 — the page had an "ERC-7913" heading directly above a _verifyTRC7913Signature sample) - TRC-1967 (upgradeable; repo has proxy/TRC1967/TRC1967Proxy.sol) - TRC-777 (trc1155; repo has ITRC777.sol) - TRC-6372 (tvm-differences said EIP-6372 while governance.mdx and the repo both say TRC-6372) - TRC-7930, TRC-7913 (tvm-differences; matches draft-InteroperableAddress.sol and the ITRC7913 naming) Note the authority here is the repo's later `trc-remaining-names-port` changeset, which supersedes `trc-tip-terminology-residuals`: the earlier one said ERC-6372, ERC-777, ERC-2981 and ERC-3156 keep citing the real ERC, the later one ported all of them to TRC. Verified each rename resolves to a real file or the repo's own NatSpec prose; standards TRON never republished are deliberately left alone (TIP-712, EIP-2935, ERC-4337, EIP-6780, EIP-7702's SignerEIP7702, and ERC-7201, whose `erc7201:` annotation prefix Initializable.sol keeps on purpose). Adds the missing TRON-side spec citations, matching the dual-citation pattern trc4626.mdx already used: trc721 and trc1155 linked only to eips.ethereum.org for pages whose specs are TIP-721 and TIP-1155. Drops two Ethereum-only claims that don't hold on TRON: - faq.mdx cited Gnosis Safe as the smart-wallet example, the same product access-control.mdx was already corrected for; generalized to "smart contract wallets". - governance.mdx justified GovernorStorage's calldata/storage trade-off as "good for some L2 chains"; TRON is a standalone L1, so this is reframed around calldata (Bandwidth) cost. Also localizes three "gas" mentions that make direct cost claims, since TRON meters Energy (computation) and Bandwidth (transaction size) rather than gas (per developers.tron.network/docs/bandwidth-and-energy), and "the storage in the EVM" -> the TVM in the utilities Packing section. Casual gas-efficiency color elsewhere is left alone; index.mdx already routes readers to tvm-differences.mdx for the resource model. Clarifies in tokens.mdx that TIP-N and TRC-N name the same standard under two labels (TIP-20 is TRC-20, as EIP-20 is ERC-20), rather than reading as two unrelated standards processes. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
trc1155.mdx told developers to implement `onTRC1155Received` and `onTRC1155BatchReceived`. Neither function exists: `ITRC1155Receiver.sol` declares `onERC1155Received` and `onERC1155BatchReceived`, and grepping both packages for the TRC-named variants returns nothing. TIP-1155 republishes EIP-1155 verbatim including the receiver hook function names and selectors, so the port renames only the interface (`IERC1155Receiver` -> `ITRC1155Receiver`) and leaves the functions alone. TRC-721 is the opposite case: its hook genuinely is renamed to `onTRC721Received`, with a different selector. That asymmetry is what makes this easy to get wrong, so the fix adds a callout stating it explicitly rather than just correcting the names silently. This is an over-rename, the reverse of the under-renamed standards fixed in 73af2fb, and it had real consequences: a contract implementing the TRC-named hook would fail `TRC1155`'s receiver check and revert every incoming transfer with `TRC1155InvalidReceiver`. Verified with `cast sig`: onERC1155Received = 0xf23a6e61, onERC1155BatchReceived = 0xbc197c81, onTRC721Received = 0x5175f878 vs onERC721Received = 0x150b7a02 — all four match the selectors cited here and in the repo's own changeset. Found by sweeping every identifier containing TRC<n>/TIP<n> across the docs against the symbols actually declared in tron-contracts and tron-contracts-upgradeable. That sweep is now clean; the only other hits are example contracts the guides define themselves. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
stevep0z
approved these changes
Aug 27, 2026
stevep0z
left a comment
stevep0z
left a comment
Collaborator
There was a problem hiding this comment.
Thanks for this! LGTM, there are some small updates (wording updates etc.) I will make in a small PR following up, but I think we can progress forward with this.
A second pass over the ported guides, looking for statements that are true of Ethereum and false or misleading on TRON without containing any of the terms earlier passes grepped for (ERC/EIP, Ethereum/EVM, gas, tooling names). - trc20.mdx recommended a `decimals` value of 18 "just like Ether". The advice is right (TRC20.decimals() really does default to 18, and the library's own trc20.adoc carries this sentence verbatim), but the comparison invites the wrong inference on a chain whose native currency has 6 decimals, directly contradicting tvm-differences.mdx. Drops the Ether comparison and notes that 18 is a token convention rather than a chain-wide one, since TRX uses 6 and so do widely held TRC-20s like USDT-TRON. - governance.mdx motivated timestamp-based governance entirely by L2 networks with irregular block production. A TRON reader would reasonably conclude the section doesn't apply to them, which is backwards: tvm-differences.mdx actively recommends timestamp mode for time-bounded Governor windows. Adds why both concerns still apply on a regular ~3 second cadence, and links the recommendation. - trc20-supply.mdx explained `block.coinbase` via "in Proof of Stake networks ... not a miner". TRON never had mining; blocks come from the 27 elected Super Representatives under DPoS. Names that, and flags that the guide's `mintMinerReward`/`TRC20WithMinerReward` identifiers keep "Miner" only for continuity with the example's own API. - tokens.mdx used Ether as its example of a fungible good; now TRX. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The row read: "Addresses 0x03 / 0x09 / 0x0A are shadowed or repurposed (TIP-43, TIP-60); real RIPEMD-160 lives at 0x20003". Checked against java-tron's PrecompiledContracts.java, which is the authority here: 0x03 -> ripempd160 (TRON's own RIPEMD-160) 0x09 -> batchValidateSign (TIP-43) 0x0a -> validateMultiSign (TIP-60) 0x20003 -> ethRipemd160 (Ethereum-compatible RIPEMD-160) Two problems. Grouping 0x03 with 0x09/0x0A under "(TIP-43, TIP-60)" implied all three come from those TIPs; TIP-43 covers only 0x09 and TIP-60 only 0x0A, and neither mentions 0x03 or 0x20003. And 0x03 is not shadowed or repurposed at all: it is still RIPEMD-160, just TRON's implementation rather than Ethereum's, which is why a separate ethRipemd160 exists at 0x20003. Calling the one at 0x20003 the "real" RIPEMD-160 inverts that. Rewrites the row to attribute each TIP to its own address and to describe 0x03 and 0x20003 as TRON's variant and the Ethereum-compatible variant. The mitigation column is unchanged and was already correct. Verified in the same pass, all confirmed as written: TIP-26's CREATE2 preimage and its 0x41 prefix against Ethereum's 0xff; TIP-7951's P256 precompile at 0x100; TIP-6780 adopting EIP-6780 SELFDESTRUCT semantics (Final); the absence of any ERC-4337 account-abstraction contracts; EIP-7702 shipping only SignerEIP7702 with no delegation flow; the TRC-10 / address.transferToken claim, which Governor.sol and TimelockController.sol state independently in NatSpec; and USDT-TRON's transfer returning false on success, which TRC20USDTMock replicates and which SafeTRC20 documents as affecting transfer but not transferFrom. Not verified: whether TIP-7951's precompile is active on TRON mainnet. The spec is Final and shipped in java-tron, but activation needs a committee proposal I could not confirm either way. The page's guidance is unaffected, since P256.verify runs in Solidity regardless. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Reverts "more gas efficient operation" -> "more energy-efficient operation" and "as a measure to save gas" -> "as a measure to reduce Energy costs" back to their original wording. Unlike the standard-name and API-correctness fixes in this branch, this one was a judgment call, not a factual error: "gas efficient" isn't wrong, it's just not TRON's own noun for the resource. On reflection it doesn't hold up against the rest of the PR's own treatment of the same word (tokens.mdx, trc1155.mdx, trc6909.mdx, and utilities.mdx's Packing/Time sections all keep "gas" in identical casual-efficiency prose, deferring to the one dedicated explanation in tvm-differences.mdx's resource-model row), and "gas" is understood across blockchain dev audiences regardless of chain, including by TRON's own community (TRON DAO's blog uses "gas fees" colloquially). Separately, "energy-efficient" collides with its ordinary-English meaning (power/environmental efficiency), which is a worse ambiguity than the one it was meant to fix. The `governance.mdx` L2-chains fix from the same commit, and the newer "Motivation" paragraph explaining why timestamp-based governance matters on TRON, are unrelated to this and are kept — those are corrections to what TRON actually is (a standalone L1 with regular block cadence), not word-choice calls. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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 subscribe to this conversation on GitHub.
Already have an account?
Sign in.
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
Adds a baseline documentation section for OpenZeppelin Contracts for Tron, mirroring the structure of the existing Solidity contracts docs. Content is ported from the
tron-contractsandtron-contracts-upgradeablerepositories' AsciiDoc docs and converted to MDX, and is aligned with the released npm packages:@openzeppelin/tron-contractsand@openzeppelin/tron-contracts-upgradeable(currently5.6.0-rc.1on thelatesttag).The new section is available at
/tron-contracts, selectable via the Tron entry in the ecosystem switcher.What's included
16 pages under
content/tron-contracts/:TRON branding — official logomark icon, ecosystem tab, homepage ecosystem card + brand color (
#EF0027), and full navigation wiring.Release alignment (second commit)
The pages were re-verified against both source repos at the 5.6.0-rc.1 release, covering the full audit-fix wave that landed after the original port:
npm install @openzeppelin/tron-contracts(taglatest, audited) and@nextfor release candidates. The@devexample was dropped: npm publishes nodevtag (the release-tag policy table itself is kept as published in the repo docs).SafeTRC20.safeTransferCheckedas the USDT-safe default (H-01, Sui v1.0.0 #131) including the TRC-4626 fee example;trc7201Slot(L-04, chore: Updating favicon and OG image #115); TRC165/TRC1271 artifact renames (Update confidential contracts changelog #126); TRON block-time governance arithmetic and TRC-6372/TRC-5805 (fix: Fixing navigation #116); AccessManager cancellation rights including role admins (docs: fix EntryPoint address override and viem destructuring in WebAu… #141); TimelockController self-administration; Tron Upgrades plugins recommendations (Add your project to the Midnight ecosystem map #132).bytespayloads (Stellar: replace deprecated macro #117/Write Sui v1 learn sections w/ math & access #136).Notes / decisions
contracts/mocks/docs/sources.index.adocstill shows anpm install @openzeppelin/tron-contracts@devexample although nodevdist-tag is published.Validation
pnpm buildpasses (full static generation).main(Tron + Canton ecosystem entries merged).🤖 Generated with Claude Code