GuidesAPI ReferenceCommunityDiscordBlogFAQBug BountyAnnouncements
Guides
Chinese(中文版)
  1. Smart Contracts
  2. Advanced

Upgrading smart contracts

Patterns for upgrading deployed TRON smart contracts: data migration, logic-data separation, the proxy pattern, the strategy pattern, and the diamond standard.

📘

Prerequisites

A deployed TRON smart contract is immutable — the bytecode at its address cannot be changed. That guarantees a clean trust model, but it also means a discovered bug or a missing feature cannot be fixed in place. The blockchain ecosystem has developed a handful of patterns that work around this constraint by separating what runs at an address from the data that address holds. This page is a reference for those patterns on TRON.

Upgradeability is not the same as mutability. The code at an address is still fixed once deployed; "upgrading" means routing user calls through one stable entry point while replacing the implementation behind it.

Why upgrade

The cases that consistently justify the extra complexity:

  • Bug fixes — even audited contracts ship with vulnerabilities. An upgrade path lets you patch quickly without asking users to migrate.
  • Feature additions — DApps evolve. Adding functionality without redeploying the entire system and migrating data keeps the user-facing address stable.
  • Performance optimization — Energy-cost improvements in newer VM versions or better algorithms can be picked up by deploying a new implementation contract.

If the contract is small, holds little value, or has no reasonable extension path, immutability is fine. Reach for an upgrade pattern only when the cost of not being able to upgrade clearly outweighs the cost of the upgrade machinery itself.

Strategy 1 — Redeploy and migrate data

The simplest approach. Deploy a new contract containing the updated logic, read the old contract's state, write it into the new one, then ask every dependent system (front ends, integrators, exchanges) to point at the new address.

Trade-offs. Conceptually easy and feasible for small contracts with simple state. Quickly becomes impractical for contracts with extensive user data — migration consumes significant Energy and Bandwidth, and coordinating address changes across all dependents is error-prone. The on-chain address changes, breaking deep links and indexers.

Use when the contract is small, recently deployed, or has few external integrators.

Strategy 2 — Separate logic and data

Split the contract into two:

  • Storage contract — holds all state. Designed to be simple and non-upgradeable so the data sits behind a fixed, audited surface.
  • Logic contract — contains business logic. When you upgrade, you deploy a new logic contract and update the storage contract's pointer to it.

Users interact with the logic contract. The logic contract reads and writes state through calls to the storage contract, which restricts writes to a whitelist of authorized logic-contract addresses.

Trade-offs. Avoids the data-migration cost of Strategy 1 — the data never moves. The user-facing address still changes (users interact with the logic contract), and the trust surface grows: a bug in the logic contract can still corrupt or drain the storage contract.

Use when the storage layout is mature but the business logic is expected to evolve.

Strategy 3 — Proxy pattern (recommended)

The dominant pattern in EVM-compatible ecosystems and what most production upgradeable contracts on TRON use.

  • Proxy contract — lightweight, non-upgradeable. Holds the user-facing address and the contract's state.
  • Implementation contract — holds the business logic. Replaceable.

The proxy stores a pointer to the current implementation contract. When a user calls a function on the proxy, the proxy's fallback function DELEGATECALLs the implementation. The delegate call is the key mechanism: although the code executing is in the implementation, all storage reads and writes (and msg.sender, msg.value, contract balance) happen against the proxy's context. The implementation operates on the proxy's storage as if it were its own.

Upgrading is a one-transaction operation: deploy a new implementation, then call the proxy's upgrade function to point at it. From the next block onward, users calling the same proxy address run the new code, and the data is preserved.

Trade-offs. The user-facing address is stable across upgrades — the most important property for ecosystem integration. Implementation requires careful attention to DELEGATECALL semantics; the most common pitfall is storage collision — the proxy and implementation must agree on the layout of storage slots, or upgrades silently corrupt state. OpenZeppelin's UUPS and Transparent Proxy implementations handle this; do not write a proxy from scratch unless you have time to audit the slot layout properly.

Use this pattern for any contract that may need to evolve and where address stability matters. The complexity is worth it; the alternatives are either painful (Strategy 1) or weaker (Strategy 2).

Strategy 4 — Strategy pattern

A "main" contract holds core logic and delegates specific functions to "satellite" contracts whose addresses it stores. To upgrade a specific function, deploy a new satellite and update the main contract's pointer. Crucially, the main contract calls satellites via regular external calls, not DELEGATECALL — state is isolated per contract.

Trade-offs. Modular: you can upgrade one feature without affecting the rest. Because state is isolated, satellites cannot directly read or write the main contract's storage; data passes through function arguments. The main contract itself remains immutable — a bug in the main contract cannot be patched with this pattern alone.

Use when you have well-defined, swappable subsystems (price oracles, fee calculators, allowlist filters) but the core glue is small and unlikely to need changes.

Strategy 5 — Diamond pattern

The diamond pattern (EIP-2535) is an advanced variation of the proxy pattern. Instead of one implementation, the diamond proxy holds a mapping of function selectors to facet addresses. Each facet contains the logic for some subset of the contract's functions.

When a user calls a function, the proxy looks up the selector in its mapping, finds the facet that implements it, and DELEGATECALLs the facet.

Trade-offs. The pattern allows modular upgrades — replace one facet without touching others — and bypasses single-contract size limits by distributing logic across multiple facets. Fine-grained access control becomes possible: different governance bodies can be authorized to add, remove, or replace different facets. The cost is significant complexity in the selector-to-facet mapping; misconfigured upgrades can lose functions or introduce selector collisions.

Use when contract size limits are a real constraint or when the upgrade governance model genuinely needs per-feature control. For most projects, a plain proxy is simpler and adequate.

Trade-offs of introducing upgradeability

Upgradeability buys flexibility at the cost of the trust and complexity benefits of immutable contracts:

  • Trust. A contract that can change behavior under the deployer's control is harder for users to reason about. They have to trust both the current logic and the upgrade-control mechanism.
  • Centralization risk. If a single key controls upgrades, that key is a single point of compromise. Multi-sig, time-locks, and on-chain governance can mitigate this — but only if implemented well.
  • Complexity. The upgrade machinery is itself code that can have bugs. Storage collisions, uninitialized variables in new implementations, and selector clashes have all caused real production incidents.
  • Cost. Deploying new implementations and broadcasting upgrade transactions consume Energy and Bandwidth.

Considerations for upgrading on TRON

The mechanics described above are EVM-derived and apply to TRON without modification. Some TRON-specific points:

  • Access control. Restrict the upgrade function to a robust governance mechanism. TRON's Account Permission Management makes it straightforward to require a multi-sig threshold; a single owner key is a phishing and key-loss risk.
  • Storage compatibility. The proxy and every implementation contract must agree on the order and types of storage variables. Adding new state to a new implementation is fine, but reordering or changing the type of existing slots will corrupt data. Use OpenZeppelin's storage-gap pattern or upgradeable-libraries to keep layouts compatible.
  • Test on Shasta or Nile first. Every upgrade should be exercised end-to-end on a testnet — including the rollback path if the new implementation turns out to be wrong.
  • Audit upgrades, not just initial deployments. A clean initial deploy says nothing about whether the next upgrade is safe. Each implementation contract needs its own audit.
  • Time-lock the upgrade itself. Even with a trusted multi-sig, introduce a delay between announcing an upgrade and applying it. The delay gives users a window to react and verify, at the cost of slower emergency response.
  • Energy cost. A proxy upgrade is a small SSTORE on the proxy; a new implementation deployment is the larger cost. Estimate ahead of time — see FeeLimit & Energy cost.

When not to upgrade

Upgradeability is not free. For these cases, keeping the contract immutable is the better default:

  • Small, single-purpose contracts where the cost of redeploying-and-migrating is low.
  • Contracts whose value proposition is censorship resistance or audit-friendly immutability — a contract that "can be changed" defeats the property you are advertising.
  • Cases where the deployer is a single key without a trustworthy governance mechanism around it — upgradeability without governance is just custody.

Related resources

Updated 8 days ago