A library of secure, community-vetted smart contracts for the Tron network (TVM) — the upgradeable variant.

This package is the upgradeable build of @openzeppelin/tron-contracts: the same OpenZeppelin component library, ported to Tron's TVM and the TRC token standards, with every stateful contract rewritten to be safe to deploy behind a proxy.

• Implementations of Tron token standards — TRC-20, TRC-721, TRC-1155, TRC-4626 — and TRC-6909.
• Flexible role-based access control and on-chain governance.
• Reusable utilities: safe math, cryptography/signature verification, data structures, and more.

$ npm install @openzeppelin/tron-contracts-upgradeable @openzeppelin/tron-contracts

@openzeppelin/tron-contracts is a peer dependency — install it alongside the upgradeable package so the imported interfaces and libraries resolve.

The upgradeable package mirrors the structure of @openzeppelin/tron-contracts, but every stateful file and contract carries the Upgradeable suffix. Constructors are replaced by internal __{ContractName}_init initializers; you write your own public initialize that runs behind a proxy.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import {TRC721Upgradeable} from "@openzeppelin/tron-contracts-upgradeable/token/TRC721/TRC721Upgradeable.sol";

contract MyCollectible is TRC721Upgradeable {
    function initialize() public initializer {
        __TRC721_init("MyCollectible", "MCO");
    }
}

Compared to the non-upgradeable version:

-import {TRC721} from "@openzeppelin/tron-contracts/token/TRC721/TRC721.sol";
+import {TRC721Upgradeable} from "@openzeppelin/tron-contracts-upgradeable/token/TRC721/TRC721Upgradeable.sol";

-contract MyCollectible is TRC721 {
-    constructor() TRC721("MyCollectible", "MCO") {}
+contract MyCollectible is TRC721Upgradeable {
+    function initialize() public initializer {
+        __TRC721_init("MyCollectible", "MCO");
+    }
 }

You then deploy the implementation behind a proxy (e.g. an ERC-1967 / UUPS / transparent proxy) using your Tron toolchain — TronBox or @openzeppelin/hardhat-tron — and call initialize exactly once. See Using with Upgrades for proxy patterns and the initializer rules.

To keep your system secure, always use the installed code as-is; do not copy-paste from online sources or modify it yourself.

A contract deployed behind a proxy never runs its constructor in the proxy's context, so initialization happens in an initializer guarded by the initializer / onlyInitializing modifiers (from Initializable). Each contract exposes __{ContractName}_init (which chains its parent initializers) and __{ContractName}_init_unchained (which does not). See Using with Upgrades → Multiple Inheritance for the chaining rules.

Every stateful contract keeps its state in a struct annotated with @custom:storage-location erc7201:..., following ERC-7201: Namespaced Storage Layout. This isolates each contract's storage so new state variables can be added — and inheritance reordered — without shifting the layout of existing deployments.

This repository is produced by transpiling @openzeppelin/tron-contracts. The process — applying the upgradeable patches, compiling, and running the transpiler with the Tron-specific flags (peer-import mode, namespaced storage, excluded proxy contracts) — is documented in scripts/upgradeable/README.md. The exact non-upgradeable source each build was generated from is pinned as the lib/tron-contracts submodule.

The guides under docs/ cover the concepts and contracts in depth:

• Using with Upgrades — initializers, multiple inheritance, namespaced storage, proxy deployment.
• Access Control — decide who can perform each action.
• Tokens — TRC-20, TRC-721, TRC-1155, TRC-4626, TRC-6909.
• Governance and Utilities.
• Backwards Compatibility and the FAQ.

Because this is the upgradeable variant of OpenZeppelin Contracts, the upstream OpenZeppelin Contracts documentation and Using with Upgrades guides apply to the contract APIs as well — substitute the TRC token names and the @openzeppelin/tron-contracts* package names for their Ethereum equivalents.

This project is maintained by OpenZeppelin. The underlying components are derived from the audited OpenZeppelin Contracts library; however, this Tron port has not been independently audited and is not yet covered by a bug bounty. Using it is not a substitute for a security review of your own system.

The engineering guidelines we follow are in GUIDELINES.md, and community standards in CODE_OF_CONDUCT.md. Smart contracts are a nascent technology and carry a high level of technical risk and uncertainty.

Released under the MIT License.