TRC-1167: Minimal Proxy Contract

[yanghang8612]

tip: 1167
title: Minimal Proxy Contract
author: yanghang8612@gmail.com
discussions-to: https://github.com/tronprotocol/tips/issues/879
status: Last Call
type: Standards Track
category: TRC
created: 2026-05-21

Simple Summary

To simply and cheaply clone contract functionality in an immutable way, this standard specifies a minimal bytecode implementation that delegates all calls to a known, fixed address.

Abstract

By standardizing on a known minimal bytecode redirect implementation, this standard allows users and third party tools (e.g. Tronscan) to (a) simply discover that a contract will always redirect in a known manner and (b) depend on the behavior of the code at the destination contract as the behavior of the redirecting contract. Specifically, tooling can interrogate the bytecode at a redirecting address to determine the location of the code that will run - and can depend on representations about that code (verified source, third-party audits, etc). This implementation forwards all calls and 100% of the gas to the implementation contract and then relays the return value back to the caller. In the case where the implementation reverts, the revert is passed back along with the payload data (for revert with message).

Motivation

This standard supports use-cases wherein it is desirable to clone exact contract functionality with a minimum of side effects (e.g. memory slot stomping) and with low gas cost deployment of duplicate proxies.

Specification

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

The exact bytecode of the standard clone contract is this: 363d3d373d3d3d363d73bebebebebebebebebebebebebebebebebebebebe5af43d82803e903d91602b57fd5bf3 wherein the bytes at indices 10 - 29 (inclusive) are replaced with the 20 byte address of the master functionality contract.

The 20 bytes embedded at indices 10–29 are the implementation address in the TVM execution-layer form. TRON addresses carry a leading 0x41 byte at the protocol/encoding layer (Base58Check / 21-byte hex), but at the TVM execution layer addresses are 20 bytes, identical to the EVM. The 0x41 prefix is not present at the execution layer; bytes 10–29 are exactly the 20-byte VM address (the value of address(impl) as seen inside Solidity), and that is what DELEGATECALL targets at run time.

Compliance presumes that DELEGATECALL, RETURNDATASIZE, and RETURNDATACOPY behave per the TVM specification — which is equivalent to the EVM semantics ERC-1167 was designed against. This specification normatively defines only the deployed runtime bytecode and the observable delegate-and-bubble-revert behavior; factory choices (CREATE vs CREATE2) and the per-instance initialization protocol are out of scope, and creation code is addressed separately under Implementation.

A reference implementation of this can be found at the optionality/clone-factory github repo.

Rationale

The goals of this effort have been the following:

• inexpensive deployment (low gas to deploy clones)
• support clone initialization in creation transaction (through factory contract model)
• simple clone bytecode to encourage directly bytecode interrogation (see CloneProbe.sol in the clone-factory project)
• dependable, locked-down behavior - this is not designed to handle upgradability, nor should it as the representation we are seeking is stronger.
• small operational overhead - adds a single call cost to each call
• handles error return bubbling for revert messages

Backwards Compatibility

There are no backwards compatibility issues. There may be some systems that are using earlier versions of the proxy contract bytecode. They will not be compliant with this standard.

Test Cases

Test cases include:

• invocation with no arguments
• invocation with arguments
• invocation with fixed length return values
• invocation with variable length return values
• invocation with revert (confirming reverted payload is transferred)

Tests for these cases are included in the reference implementation project.

Implementation

Deployment bytecode is not included in this specification. One approach is defined in the proxy-contract reference implementation.

Standard Proxy

The disassembly of the standard deployed proxy contract code (from r2 and edited to include stack visualization)

|           0x00000000      36             calldatasize          cds
|           0x00000001      3d             returndatasize        0 cds
|           0x00000002      3d             returndatasize        0 0 cds
|           0x00000003      37             calldatacopy          
|           0x00000004      3d             returndatasize        0
|           0x00000005      3d             returndatasize        0 0 
|           0x00000006      3d             returndatasize        0 0 0
|           0x00000007      36             calldatasize          cds 0 0 0
|           0x00000008      3d             returndatasize        0 cds 0 0 0
|           0x00000009      73bebebebebe.  push20 0xbebebebe     0xbebe 0 cds 0 0 0
|           0x0000001e      5a             gas                   gas 0xbebe 0 cds 0 0 0
|           0x0000001f      f4             delegatecall          suc 0
|           0x00000020      3d             returndatasize        rds suc 0
|           0x00000021      82             dup3                  0 rds suc 0
|           0x00000022      80             dup1                  0 0 rds suc 0
|           0x00000023      3e             returndatacopy        suc 0
|           0x00000024      90             swap1                 0 suc
|           0x00000025      3d             returndatasize        rds 0 suc
|           0x00000026      91             swap2                 suc 0 rds
|           0x00000027      602b           push1 0x2b            0x2b suc 0 rds
|       ,=< 0x00000029      57             jumpi                 0 rds
|       |   0x0000002a      fd             revert
|       `-> 0x0000002b      5b             jumpdest              0 rds
\           0x0000002c      f3             return

NOTE: as an effort to reduce gas costs as much as possible, the above bytecode depends on the behavior that returndatasize returns zero prior to any calls within the call-frame. returndatasize uses 1 less gas than dup*.

Vanity Address Optimization

Proxy deployment can be further optimized by installing the master contract at a vanity contract deployment address with leading zero-bytes. By generating a master contract vanity address that includes Z leading 0 bytes in its address, you can shorten the proxy bytecode by replacing the push20 opcode with pushN (where N is 20 - Z) followed by the N non-zero address bytes. The revert jump address is decremented by Z in this case. Here is an example where Z = 4:

|           0x00000000      36             calldatasize          cds
|           0x00000001      3d             returndatasize        0 cds
|           0x00000002      3d             returndatasize        0 0 cds
|           0x00000003      37             calldatacopy          
|           0x00000004      3d             returndatasize        0
|           0x00000005      3d             returndatasize        0 0 
|           0x00000006      3d             returndatasize        0 0 0
|           0x00000007      36             calldatasize          cds 0 0 0
|           0x00000008      3d             returndatasize        0 cds 0 0 0
|           0x00000009      6fbebebebebe.  push16 0xbebebebe     0xbebe 0 cds 0 0 0
|           0x0000001a      5a             gas                   gas 0xbebe 0 cds 0 0 0
|           0x0000001b      f4             delegatecall          suc 0
|           0x0000001c      3d             returndatasize        rds suc 0
|           0x0000001d      82             dup3                  0 rds suc 0
|           0x0000001e      80             dup1                  0 0 rds suc 0
|           0x0000001f      3e             returndatacopy        suc 0
|           0x00000020      90             swap1                 0 suc
|           0x00000021      3d             returndatasize        rds 0 suc
|           0x00000022      91             swap2                 suc 0 rds
|           0x00000023      6027           push1 0x27            0x27 suc 0 rds
|       ,=< 0x00000025      57             jumpi                 0 rds
|       |   0x00000026      fd             revert
|       `-> 0x00000027      5b             jumpdest              0 rds
\           0x00000028      f3             return

This saves 4 bytes of proxy contract size (savings on each deployment) and has zero impact on runtime gas costs.

Detection Guidance

Tooling such as block explorers, wallets, and on-chain proxy-aware contracts SHOULD detect compliant proxies behaviorally rather than by exact 45-byte match. The 9-byte fixed prefix 363d3d373d3d3d363d (indices 0–8) is followed by a PUSH(20−Z) opcode (0x73 for the canonical runtime, 0x6f for the Z=4 vanity variant, etc.) and its (20−Z) operand bytes — where Z is the number of leading zero bytes in the implementation address — then the 9-byte fixed middle 5af43d82803e903d91, then a PUSH1 (0x60) with a one-byte operand equal to 0x2b − Z pointing at the revert jumpdest, then the 4-byte suffix 57fd5bf3. Both runtime variants are equally compliant; the 20-byte VM implementation address is recovered from the variable-length push. Extracted addresses SHOULD be rendered as Base58Check (T...) only at the UI layer; on-chain comparisons and storage SHOULD use the 20-byte VM form.

Clone Initialization

Because the constructor of the implementation contract does not run during clone creation, common practice is to expose an initialize(...) function on the implementation, guarded by a one-shot flag (OpenZeppelin's Initializable pattern is the canonical reference), and have the factory call it once per clone immediately after deployment. This pattern is non-normative: clone initialization is a property of the implementation, not of the proxy, and the proxy specification deliberately makes no requirements about it. Implementations SHOULD document whether their initialization is constructor-like, one-shot, or externally callable, so integrators can avoid the common uninitialized-clone footgun.

Security Considerations

Constructor-set immutables do not propagate to clones. Solidity stores immutable variables in the deployed bytecode at construction time. Because the constructor never runs for a clone, immutables defined on the implementation contract are not populated for instances accessed through a TRC-1167 proxy. Implementation contracts MUST NOT rely on constructor-set immutables in any code path that will be invoked via a clone; use storage-backed state and an explicit initializer (see Clone Initialization above) instead.

Implementation destruction (SELFDESTRUCT). On legacy EVM behavior, an implementation contract destroyed via SELFDESTRUCT would silently break every clone pointing at it: a clone's DELEGATECALL to a now-codeless account returns success with empty returndata, leaving every call to the clone to succeed-and-do-nothing while value sent to it is lost (the Parity Multisig "killed" incident in 2017 was an instance of exactly this). On current TRON mainnet this risk is neutralized at the protocol level by TIP-6780 (shipped in GreatVoyage-v4.8.1 "Democritus", gated by network parameter #94, enabled on mainnet via Proposal #106): SELFDESTRUCT only removes a contract's code/storage when executed in the same transaction the contract was created in. A TRC-1167 implementation, by construction, is deployed in one transaction and used as a delegate target only in later ones, so a deployed, in-use implementation cannot be destroyed after the fact; the related metamorphic-CREATE2-resurrection attack is closed by the same change. Implementations MAY therefore use SELFDESTRUCT for legitimate purposes (for example, balance recovery) without endangering clone safety.

Storage-layout discipline. Clone contracts inherit the storage layout of the implementation. Storage-layout collisions across upgrades, library reuse, and extension contracts are a recurring source of bugs in DELEGATECALL-based patterns and are outside the scope of this minimal-proxy spec. Implementers SHOULD follow established storage-layout discipline; see TIP-1967 and the TRC-7201 namespaced-storage proposal (tracked in #853) for the recommended patterns.

Copyright

Copyright and related rights waived via CC0.

[halibobo1205]

I have a few questions to clarify the TRON-specific scope:

1. For the PUSH20 implementation address, should the standard explicitly use the 20-byte Solidity address, i.e. the TRON hex address without the 41 prefix?

2. Is the intention to keep the deployed runtime bytecode fully aligned with ERC-1167, relying on TVM semantics for RETURNDATASIZE, RETURNDATACOPY, and DELEGATECALL?

3. Should TRC-1167 define only the deployed runtime bytecode and observable behavior, while leaving factory/deployment bytecode out of scope?

4. For tooling such as Tronscan, should vanity-address optimized runtimes also be considered compliant, or only the canonical 45-byte runtime?

[yanghang8612]

@halibobo1205 Good questions — all four are about pinning the TRON-specific scope precisely.

1. PUSH20 address form — yes, the 20-byte address. TRON addresses carry a leading 0x41 byte at the protocol/encoding layer (Base58Check / 21-byte hex), but at the TVM execution layer addresses are 20 bytes, identical to the EVM. The PUSH20 operand and the DELEGATECALL target are the 20-byte form with the 0x41 prefix stripped, so bytes 10–29 of the runtime are exactly that 20-byte implementation address. I'll state this explicitly, as it's the most common porting mistake.

2. Yes — byte-for-byte alignment with ERC-1167, relying on TVM opcode semantics. TVM implements DELEGATECALL (preserves caller / callvalue / storage context), RETURNDATASIZE (returns 0 before any call in the frame — which the energy-saving trick depends on), and RETURNDATACOPY with EVM-equivalent semantics, so the canonical runtime is reused verbatim. Keeping it identical is the entire point — same detection logic, same audited behavior carry over. I'll add a normative note that compliance presumes these three opcodes behave per the TVM spec (which matches EVM); for the runtime bytecode and delegated-execution semantics this spec covers, the only relevant model difference from EVM is energy-vs-gas accounting, which affects neither the bytecode nor the forwarded-execution behavior.

3. Yes — runtime + observable behavior only; factory/deployment out of scope. Mirroring ERC-1167, the spec normatively defines just the deployed runtime bytecode and the observable delegate-and-bubble-revert behavior. Creation code and whether a factory uses CREATE or CREATE2 are left to the implementer (the "Deployment bytecode is not included in this specification" line already reflects that).

4. Both canonical and vanity-optimized runtimes are compliant — tooling MUST match the family. The vanity variant is functionally identical and explicitly part of this spec: for an implementation address with Z leading zero-bytes, push20 becomes push(20−Z) pushing the non-zero suffix, with the revert jumpdest decremented by Z. So Tronscan-class tooling should not match a fixed 45-byte string; it should match the fixed prefix/suffix template and extract the implementation address from the variable-length push (push(20−Z)). Compliance is behavioral — "delegates all calls to a fixed implementation with ERC-1167 semantics" — and both forms satisfy it. I'll add explicit detection guidance so explorers and wallets classify clones consistently.

[TonyStank911]

Storage layout collisions are a real-world footgun with minimal proxies — an implementation contract using slot 0 for one purpose, then a downstream extension reusing the same slot accidentally. Should TRC-1167 say anything about storage-layout discipline, or is that purely an implementation concern?

[yanghang8612]

@TonyStank911 Purely implementation concern in the source ERC, and that's the right call to preserve:

• ERC-1167 deliberately defines only the runtime forwarding behavior — what bytes 0–44 do at execution time. The storage layout of the implementation contract (and therefore the storage that clones share via DELEGATECALL) is entirely the implementation contract's responsibility, the same as for any other DELEGATECALL-based pattern.
• Putting storage-layout guidance into TRC-1167 would expand the standard beyond its scope and duplicate ground that TIP-1967 (TRC-1967: Proxy Storage Slots #845) already covers more broadly. The right answer is a one-line cross-reference:
  "Clone contracts inherit the storage layout of the implementation. Implementers SHOULD follow established storage-layout discipline — see TIP-1967 (TRC-1967: Proxy Storage Slots #845) and TRC-7201 (TRC-7201: Namespaced Storage Layout #853, namespaced storage) — to avoid collisions across upgrades or extension contracts."
• Anything more normative in TRC-1167 itself would force implementers to design around TVM-specific storage rules and break the byte-for-byte alignment with ERC-1167 that lets the canonical 45-byte runtime carry over verbatim.

[ouy95917]

Constructor logic doesn't run in clones — only the deployed 45-byte runtime executes. What's the recommended pattern for clone initialization, and should TRC-1167 say anything normative about it, or leave it entirely to the implementation contract?

[yanghang8612]

@ouy95917 Leave it to the implementation contract, but add a non-normative pattern recommendation plus one explicit warning:

• Why not normative: ERC-1167 governs the proxy runtime, not the implementation. Initialization is implementation-defined and properly belongs to the implementation contract's interface, not the proxy spec. Locking an initialize(...) ABI into TRC-1167 would over-constrain implementers who legitimately want zero-init clones, single-shot factories, or per-call configuration.
• Recommended pattern (non-normative, in an "Implementation Notes" section): an initialize(...) function on the implementation, guarded by a one-shot flag (OpenZeppelin's Initializable pattern is the canonical reference), called once per clone immediately after deployment by the factory. This is the universal pattern in the wild.
• Critical gotcha (explicit warning in Security Considerations): because the constructor doesn't run, the implementation contract MUST NOT rely on constructor-set immutables. Solidity stores immutables in code at deploy time, not in storage — clones don't get them, full stop. This is the single most common pitfall when porting from non-proxy contracts to clones, and deserves a dedicated callout next to the existing "no upgradability" note.

[lily309]

The classic minimal-proxy footgun is the implementation contract being destroyed via SELFDESTRUCT, which would turn every clone into a dead address. Is that a live risk on TRON that TRC-1167 needs to warn about, or has the protocol already handled it?

[yanghang8612]

@lily309 It was the canonical risk on pre-Cancun Ethereum, but on current TRON mainnet it's already neutralized at the protocol level by TIP-6780, so TRC-1167 does not need a "don't use SELFDESTRUCT" warning — at most a historical/clarifying note.

• The original danger: a clone is just a 45-byte forwarder, so if its implementation were destroyed, DELEGATECALL to a now-codeless account returns success=true with empty returndata — calls to the clone silently succeed while doing nothing, and value sent to it is lost. The Parity Multisig "killed" incident (Nov 2017, ~$280M frozen) was exactly this: a self-destructible shared library hundreds of clones depended on.
• TIP-6780 (#765) closes this on TRON. It mirrors EIP-6780: SELFDESTRUCT only deletes code/storage/account when executed in the same transaction the contract was created in; in any later transaction it merely transfers the contract's balance and halts, leaving code intact. It shipped in GreatVoyage-v4.8.1 (Democritus), is gated by network parameter Add Copyright and Acknowledgements in Template.md #94, and was enabled on mainnet via Proposal TRC106：Vector Commitment In TICP #106 (executed, and per the parameter's rules cannot be turned off again).
• Consequence for minimal proxies: a TRC-1167 implementation is, by construction, deployed in one transaction and used as a delegate target in later ones. After TIP-6780, a later SELFDESTRUCT can no longer remove it — so a deployed, in-use implementation cannot be killed, and the Parity-style clone-bricking scenario is no longer reachable. (An implementation that self-destructs within its own creation transaction never becomes a usable target in the first place, so there's nothing for clones to point at.)
• The related metamorphic / CREATE2-redeploy attack is closed by the same change: resurrecting an address with different bytecode requires first SELFDESTRUCT-ing it, which post-6780 is only possible same-tx-as-creation — so an implementation can't be swapped out from under existing clones.
• Spec direction (much lighter than a normative ban): a non-normative note that on TIP-6780-enabled TRON the implementation-destruction risk that applies to legacy EVM minimal proxies does not apply, so implementers don't need to avoid SELFDESTRUCT in the implementation for clone-safety reasons. The only residual is the balance-transfer behavior (irrelevant to typical zero-balance logic contracts and harmless to clones, since code survives).

[Redchar1992]

The latest clarification on SELFDESTRUCT makes sense: with TIP-6780, the classic implementation-destroyed risk is no longer the same live risk on current TRON.

For the TRC-1167 text, I would still add two non-normative implementation notes for tooling:

• explorer/wallet detection should match the exact 45-byte runtime and extract the 20-byte VM implementation address, then render it as Base58Check only at the UI layer; and
• clone initialization is intentionally outside the proxy standard, but implementations should document whether initialization is constructor-like, one-shot, or externally callable to avoid the usual uninitialized-clone footgun.

That should keep the spec narrow while giving integrators enough guidance.

[yanghang8612]

Agreed, @Redchar1992 — both go in as non-normative implementation notes. (1) Explorer/wallet detection should match the exact 45-byte runtime, extract the 20-byte VM implementation address, and render Base58Check only at the UI layer. (2) Since clone initialization is intentionally outside the proxy standard, implementations should document whether their init is constructor-like, one-shot, or externally callable, to avoid the uninitialized-clone footgun. Both keep the spec narrow while giving integrators enough to avoid the common mistakes — and thanks for confirming the TIP-6780 point.

[yanghang8612]

Status update: advancing to Last Call

Following the discussion at TRON Core Devs Meeting #64, TRC-1167 is moving from Draft to Last Call. The issue body above has been updated with the revised spec, incorporating the substantive feedback from this thread:

• @halibobo1205: Specification now explicitly pins (1) the 20-byte VM address form for PUSH20 (with 0x41 stripped), (2) byte-for-byte alignment with ERC-1167 relying on TVM DELEGATECALL / RETURNDATASIZE / RETURNDATACOPY semantics, (3) runtime + observable behavior as the only normative surface (creation code out of scope), and (4) behavioral compliance for both canonical and vanity-optimized runtimes.
• @halibobo1205 + @Redchar1992: new Detection Guidance subsection telling explorers/wallets to template-match the fixed prefix/suffix and reconstruct the address from the variable-length push, rather than exact 45-byte match. Base58Check rendering only at the UI layer.
• @ouy95917 + @Redchar1992: new Clone Initialization subsection documenting the initialize(...) / Initializable one-shot pattern as the recommended (non-normative) practice, with the requirement that implementations document their init shape.
• @ouy95917: new Security Considerations — constructor-set immutables MUST NOT be relied upon in any code path invoked via a clone.
• @lily309: new Security Considerations — the classic SELFDESTRUCT-implementation-bricking risk (Parity Multisig–style) is neutralized on current TRON by TIP-6780 (shipped in GreatVoyage-v4.8.1 "Democritus", gated by network parameter Add Copyright and Acknowledgements in Template.md #94, enabled via Proposal TRC106：Vector Commitment In TICP #106), with a full historical/technical explanation in the spec.
• @TonyStank911: new Security Considerations — storage-layout discipline cross-referenced to TIP-1967 and the TRC-7201 namespaced-storage proposal (#853).

Last Call review window: two weeks, closing 2026-06-29. Please raise any remaining concerns by then. Thanks to everyone who weighed in.