Skip to content

Add TIP-173 and TIP-1167 (Last Call) #896

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Benson0224 merged 1 commit into from
Jun 26, 2026
+265 −0
Merged

Add TIP-173 and TIP-1167 (Last Call) #896

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,7 @@ For further discussion, please enter [Telegram](https://t.me/troncoredevscommuni
| TIP&nbsp;157 | [Freeze instructions in TVM](https://github.com/tronprotocol/tips/blob/master/tip-157.md) | <taihao.fu@gmail.com> | Standards&nbsp;Track | VM | true | Final |
| TIP&nbsp;165 | [TRC-165 Standard Interface Detection In Contract](https://github.com/tronprotocol/tips/blob/master/tip-165.md) | <timothychungkitwai@gmail.com> | Standards&nbsp;Track | TRC | true | Final |
| TIP&nbsp;171 | [STAKE instructions in TVM](https://github.com/tronprotocol/tips/blob/master/tip-171.md) | <taihao.fu@gmail.com> | Standards&nbsp;Track | VM | true | Withdrawn |
| TIP&nbsp;173 | [TRC-173: Contract Ownership Standard](https://github.com/tronprotocol/tips/blob/master/tip-173.md) | <yanghang8612@gmail.com> | Standards&nbsp;Track | TRC | false | Last Call |
| TIP&nbsp;174 | [CHAINID instructions in TVM](https://github.com/tronprotocol/tips/blob/master/tip-174.md) | <taihao.fu@gmail.com> | Standards&nbsp;Track | VM | true | Final |
| TIP&nbsp;175 | [SELFBALANCE instructions in TVM](https://github.com/tronprotocol/tips/blob/master/tip-175.md) | <taihao.fu@gmail.com> | Standards&nbsp;Track | VM | true | Final |
| TIP&nbsp;176 | [altbn128 operation energy reduction in TVM](https://github.com/tronprotocol/tips/blob/master/tip-176.md) | <taihao.fu@gmail.com> | Standards&nbsp;Track | VM | true | Final |
Expand Down Expand Up @@ -205,6 +206,7 @@ For further discussion, please enter [Telegram](https://t.me/troncoredevscommuni
| TIP&nbsp;871 | [TIP-871: Canonicalize MODEXP output length when modulus is zero](https://github.com/tronprotocol/tips/blob/master/tip-871.md) | <yanghang8612@163.com> | Standards&nbsp;Track | VM | true | Last Call |
| TIP&nbsp;1102 | [TIP-1102: Opt-in account exposure](https://github.com/tronprotocol/tips/blob/master/tip-1102.md) | <aaronluotron@gmail.com> | Standards&nbsp;Track | Interface | false | Final |
| TIP&nbsp;1155 | [Multi Token Standard](https://github.com/tronprotocol/tips/blob/master/tip-1155.md) | <yanghang8612@163.com> | Standards&nbsp;Track | TRC | false | Final |
| TIP&nbsp;1167 | [TRC-1167: Minimal Proxy Contract](https://github.com/tronprotocol/tips/blob/master/tip-1167.md) | <yanghang8612@gmail.com> | Standards&nbsp;Track | TRC | false | Last Call |
| TIP&nbsp;1193 | [TIP-1193: TRON Provider JavaScript API](https://github.com/tronprotocol/tips/blob/master/tip-1193.md) | <aaronluotron@gmail.com> | Standards&nbsp;Track | Interface | false | Final |
| TIP&nbsp;1271 | [Standard Signature Validation Method for Contracts](https://github.com/tronprotocol/tips/blob/master/tip-1271.md) | <yanghang8612@gmail.com> | Standards&nbsp;Track | TRC | false | Final |
| TIP&nbsp;1967 | [TRC-1967: Proxy Storage Slots](https://github.com/tronprotocol/tips/blob/master/tip-1967.md) | <yanghang8612@gmail.com> | Standards&nbsp;Track | TRC | false | Final |
Expand Down
150 changes: 150 additions & 0 deletions tip-1167.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,150 @@
```
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](https://www.ietf.org/rfc/rfc2119.txt).

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](https://github.com/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](https://github.com/tronprotocol/tips/blob/master/tip-6780.md) (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](https://github.com/tronprotocol/tips/blob/master/tip-1967.md) and the TRC-7201 namespaced-storage proposal (tracked in [#853](https://github.com/tronprotocol/tips/issues/853)) for the recommended patterns.

## Copyright

Copyright and related rights waived via [CC0](https://github.com/tronprotocol/tips/blob/master/LICENSE.md).
Loading