diff --git a/README.md b/README.md index 032e180..44168d0 100644 --- a/README.md +++ b/README.md @@ -127,6 +127,7 @@ For further discussion, please enter [Telegram](https://t.me/troncoredevscommuni | TIP 157 | [Freeze instructions in TVM](https://github.com/tronprotocol/tips/blob/master/tip-157.md) | | Standards Track | VM | true | Final | | TIP 165 | [TRC-165 Standard Interface Detection In Contract](https://github.com/tronprotocol/tips/blob/master/tip-165.md) | | Standards Track | TRC | true | Final | | TIP 171 | [STAKE instructions in TVM](https://github.com/tronprotocol/tips/blob/master/tip-171.md) | | Standards Track | VM | true | Withdrawn | +| TIP 173 | [TRC-173: Contract Ownership Standard](https://github.com/tronprotocol/tips/blob/master/tip-173.md) | | Standards Track | TRC | false | Last Call | | TIP 174 | [CHAINID instructions in TVM](https://github.com/tronprotocol/tips/blob/master/tip-174.md) | | Standards Track | VM | true | Final | | TIP 175 | [SELFBALANCE instructions in TVM](https://github.com/tronprotocol/tips/blob/master/tip-175.md) | | Standards Track | VM | true | Final | | TIP 176 | [altbn128 operation energy reduction in TVM](https://github.com/tronprotocol/tips/blob/master/tip-176.md) | | Standards Track | VM | true | Final | @@ -205,6 +206,7 @@ For further discussion, please enter [Telegram](https://t.me/troncoredevscommuni | TIP 871 | [TIP-871: Canonicalize MODEXP output length when modulus is zero](https://github.com/tronprotocol/tips/blob/master/tip-871.md) | | Standards Track | VM | true | Last Call | | TIP 1102 | [TIP-1102: Opt-in account exposure](https://github.com/tronprotocol/tips/blob/master/tip-1102.md) | | Standards Track | Interface | false | Final | | TIP 1155 | [Multi Token Standard](https://github.com/tronprotocol/tips/blob/master/tip-1155.md) | | Standards Track | TRC | false | Final | +| TIP 1167 | [TRC-1167: Minimal Proxy Contract](https://github.com/tronprotocol/tips/blob/master/tip-1167.md) | | Standards Track | TRC | false | Last Call | | TIP 1193 | [TIP-1193: TRON Provider JavaScript API](https://github.com/tronprotocol/tips/blob/master/tip-1193.md) | | Standards Track | Interface | false | Final | | TIP 1271 | [Standard Signature Validation Method for Contracts](https://github.com/tronprotocol/tips/blob/master/tip-1271.md) | | Standards Track | TRC | false | Final | | TIP 1967 | [TRC-1967: Proxy Storage Slots](https://github.com/tronprotocol/tips/blob/master/tip-1967.md) | | Standards Track | TRC | false | Final | diff --git a/tip-1167.md b/tip-1167.md new file mode 100644 index 0000000..8623f57 --- /dev/null +++ b/tip-1167.md @@ -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). diff --git a/tip-173.md b/tip-173.md new file mode 100644 index 0000000..1dd3a0a --- /dev/null +++ b/tip-173.md @@ -0,0 +1,113 @@ +``` +tip: 173 +title: Contract Ownership Standard +description: A standard interface for ownership of contracts +author: yanghang8612@gmail.com +discussions-to: https://github.com/tronprotocol/tips/issues/878 +status: Last Call +type: Standards Track +category: TRC +created: 2026-05-21 +``` + +## Abstract + +This specification defines standard functions for owning or controlling a contract. + +An implementation allows reading the current owner (`owner() returns (address)`) and transferring ownership (`transferOwnership(address newOwner)`) along with a standardized event for when ownership is changed (`OwnershipTransferred(address indexed previousOwner, address indexed newOwner)`). + +## Motivation + +Many smart contracts require that they be owned or controlled in some way. For example to withdraw funds or perform administrative actions. It is so common that the contract interface used to handle contract ownership should be standardized to allow compatibility with user interfaces and contracts that manage contracts. + +Here are some examples of kinds of contracts and applications that can benefit from this standard: +1. Exchanges that buy/sell/auction TRON contracts. This is only widely possible if there is a standard for getting the owner of a contract and transferring ownership. +2. Contract wallets that hold the ownership of contracts and that can transfer the ownership of contracts. +3. Contract registries. It makes sense for some registries to only allow the owners of contracts to add/remove their contracts. A standard must exist for these contract registries to verify that a contract is being submitted by the owner of it before accepting it. +4. User interfaces that show and transfer ownership of contracts. + +## 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). + +Every TRC-173 compliant contract must implement the `TRC173` interface. Contracts should also implement `TRC165` for the TRC-173 interface. + +```solidity + +/// @title TRC-173 Contract Ownership Standard +/// Note: the TRC-165 identifier for this interface is 0x7f5828d0 +interface TRC173 /* is TRC165 */ { + /// @dev This emits when ownership of a contract changes. + event OwnershipTransferred(address indexed previousOwner, address indexed newOwner); + + /// @notice Get the address of the owner + /// @return The address of the owner. + function owner() view external returns(address); + + /// @notice Set the address of the new owner of the contract + /// @dev Set _newOwner to address(0) to renounce any ownership. + /// @param _newOwner The address of the new owner of the contract + function transferOwnership(address _newOwner) external; +} + +interface TRC165 { + /// @notice Query if a contract implements an interface + /// @param interfaceID The interface identifier, as specified in TRC-165 + /// @dev Interface identification is specified in TRC-165. + /// @return `true` if the contract implements `interfaceID` and + /// `interfaceID` is not 0xffffffff, `false` otherwise + function supportsInterface(bytes4 interfaceID) external view returns (bool); +} +``` + +The `owner()` function may be implemented as `pure` or `view`. + +A `view` implementation is RECOMMENDED for any contract that implements transferable ownership — i.e., any contract that may emit a non-construction `OwnershipTransferred`. The `pure` form is permitted to accommodate constant-owner implementations where the owner address is hardcoded into the bytecode (for example, factory-deployed contracts with a baked-in deployer, or contracts where ownership is intentionally non-transferable). A `pure` owner-getter combined with a functional `transferOwnership` is a contradiction and SHOULD NOT be implemented. Indexers and explorers SHOULD treat both forms as compliant and SHOULD flag `pure` implementations as having immutable ownership for user clarity. + +The `transferOwnership(address _newOwner)` function may be implemented as `public` or `external`. + +To renounce any ownership of a contract set `_newOwner` to the zero address: `transferOwnership(address(0))`. If this is done then a contract is no longer owned by anybody. + +Compliant contracts MUST emit `OwnershipTransferred(address(0), initialOwner)` exactly once during construction — or, for clones and proxy patterns such as [TRC-1167](https://github.com/tronprotocol/tips/blob/master/tip-1167.md) where no constructor runs, during the equivalent initialization step — before any state-changing function becomes callable. Subsequent ownership changes (including renouncement via `transferOwnership(address(0))`) are covered by the standard transfer-event rule above. + +## Optional Extensions + +The following patterns are commonly layered on top of the minimal core defined above. They are non-normative and do not affect TRC-173 compliance; they are listed here so implementers and tools converge on the same names where possible. + +**Two-step ownership transfer.** An optional companion interface that replaces the immediate semantics of `transferOwnership` with a propose-then-accept flow: `transferOwnership(newOwner)` records a pending owner (readable via `pendingOwner()`), and the transfer takes effect only once that address calls `acceptOwnership()` — analogous to OpenZeppelin's `Ownable2Step`. This is the RECOMMENDED safe-transfer pattern when the risk of transferring ownership to a wrong or uncontrolled address is a concern. Because it changes the meaning of `transferOwnership` and adds new functions, it is exposed as a separately-identified TRC-165 interface rather than being folded into TRC-173. + +**Explicit `renounceOwnership()`.** A separate, no-argument function reserved exclusively for renouncing ownership, as an alternative (or complement) to passing `address(0)` to `transferOwnership`. An explicit function makes the irreversible intent unmistakable on the call site. This is an optional implementation choice and is not part of TRC-173 compliance. + +## Rationale + +Key factors influencing the standard: +- Keeping the number of functions in the interface to a minimum to prevent contract bloat. +- Backwards compatibility with existing contracts. +- Simplicity +- Gas efficient + +Several ownership schemes were considered. The scheme chosen in this standard was chosen because of its simplicity, low gas cost and backwards compatibility with existing contracts. + +Here are other schemes that were considered: +1. **Associating an Ethereum Name Service (ENS) domain name with a contract.** A contract's `owner()` function could look up the owner address of a particular ENS name and use that as the owning address of the contract. Using this scheme a contract could be transferred by transferring the ownership of the ENS domain name to a different address. Short comings to this approach are that it is not backwards compatible with existing contracts and requires gas to make external calls to ENS related contracts to get the owner address. +2. **Associating a [TRC-721](https://github.com/tronprotocol/tips/blob/master/tip-721.md)-based non-fungible token (NFT) with a contract.** Ownership of a contract could be tied to the ownership of an NFT. The benefit of this approach is that the existing TRC-721-based infrastructure could be used to sell/buy/auction contracts. Short comings to this approach are additional complexity and infrastructure required. A contract could be associated with a particular NFT but the NFT would not track that it had ownership of a contract unless it was programmed to track contracts. In addition handling ownership of contracts this way is not backwards compatible. + +This standard does not exclude the above ownership schemes or other schemes from also being implemented in the same contract. For example a contract could implement this standard and also implement the other schemes so that ownership could be managed and transferred in multiple ways. This standard does provide a simple ownership scheme that is backwards compatible, is light-weight and simple to implement, and can be widely adopted and depended on. + +This standard can be (and has been) extended by other standards to add additional ownership functionality. + +## Security Considerations + +If the address returned by `owner()` is an externally owned account then its private key must not be lost or compromised. + +Calling `transferOwnership(address(0))` permanently renounces ownership and is irreversible. Implementations MAY add safeguards such as a separate `renounceOwnership()` function (see Optional Extensions), a two-step confirmation, or rejecting `address(0)` in `transferOwnership` to reduce the risk of accidental loss of contract control. + +Ownership of a TRC-173 contract by a multi-signature account — whether via TRON's native multi-signature account system ([TIP-16](https://github.com/tronprotocol/tips/blob/master/tip-16.md), [TIP-105](https://github.com/tronprotocol/tips/blob/master/tip-105.md)) or via a multi-sig smart-contract wallet — is supported as an implementation choice and requires no specification change. TRC-173 standardizes only the contract-facing `msg.sender == owner()` check; how the owning account is itself authorized is outside the scope of this interface. Wallets and explorers MAY surface the underlying TRON account-permission structure for UX, but doing so is not a normative requirement. + +## Backwards Compatibility + +Many existing contracts already implement this standard. + +## Copyright + +Copyright and related rights waived via [CC0](https://github.com/tronprotocol/tips/blob/master/LICENSE.md).