TRC-8056: Scaled UI Amount Extension for TRC-20 Tokens

オープン
#904 コメント 12 件 リアクション 0 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
35/100
issue の種類
機能追加
明瞭さ
おおむね明確
活発さ
活発
技術スタック
solidity
領域
blockchain

調査の方向性

Read the TRC-20 and TRC-165 references, then examine the ScaledUIToken reference implementation and the required versus optional interfaces in issue 904. Done means the multiplier semantics, interface identifiers, update behavior, and backwards-compatibility requirements are resolved and documented as an accepted TRC standard.

索引モデルが issue の本文から書いたものです。

説明

tip: 8056
title: Scaled UI Amount Extension for TRC-20 Tokens
description: Equity Token support for Stock Splits
author: [email protected]
discussions-to: https://github.com/tronprotocol/tips/issues/904
status: Draft
type: Standards Track
category: TRC
created: 2026-07-10
requires: 20, 165

Simple Summary

A standard extension that lets a token issuer publish an updatable multiplier, so that a stock split can be reflected in the balance shown to users without minting tokens or moving them.

Abstract

This proposal describes a standard extension to TRC-20 tokens that enables issuers to apply an updatable multiplier to the UI (user interface) amount of tokens. This allows for efficient representation of stock splits, without requiring actual token minting or transfers. The extension provides a cosmetic layer that modifies how token balances are displayed to users while maintaining the underlying token economics.

Motivation

Current TRC-20 implementations lack an efficient mechanism to handle real-world asset scenarios such as stock splits: When a company performs a 2-for-1 stock split, all shareholders should see their holdings double. Currently, this requires minting new tokens to all holders, which is energy-intensive and operationally complex. Moreover, the internal accounting in DeFi protocols would break from such a split.

The inability to efficiently handle this scenario limits the adoption of tokenized real-world assets (RWAs) on TRON. This proposal addresses these limitations by introducing a multiplier mechanism that adjusts the displayed balance without altering the actual token supply.

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.

Core Interface

Compliant contracts MUST implement the IScaledUIAmount interface:

interface IScaledUIAmount {
    // Emitted when the UI multiplier is updated
    event UIMultiplierUpdated(uint256 oldMultiplier, uint256 newMultiplier, uint256 effectiveAtTimestamp);

    // OPTIONAL: Emitted during a token transfer with the UI-adjusted amount
    event TransferWithUIAmount(address indexed from, address indexed to, uint256 amount, uint256 uiAmount);

    // Returns the current UI multiplier
    // Multiplier is represented with 18 decimals (1e18 = 1.0)
    function uiMultiplier() external view returns (uint256);
}

Note: How the multiplier is updated is an implementation detail left to the token issuer. The reference implementation below shows one approach using a setUIMultiplier function with delayed effectiveness.

Optional Extension: Conversion

Contracts MAY implement the IScaledUIAmountConversion extension for on-chain conversion helpers:

interface IScaledUIAmountConversion {
    // Converts a raw token amount to UI amount
    function toUIAmount(uint256 rawAmount) external view returns (uint256);

    // Converts a UI amount to raw token amount
    function fromUIAmount(uint256 uiAmount) external view returns (uint256);
}
Optional Extension: Balances

Contracts MAY implement the IScaledUIAmountBalances extension for on-chain UI balance queries:

interface IScaledUIAmountBalances {
    // Returns the UI-adjusted balance of an account
    function balanceOfUI(address account) external view returns (uint256);

    // Returns the UI-adjusted total supply
    function totalSupplyUI() external view returns (uint256);
}
Required Extension: Pending Multiplier

Compliant contracts MUST implement the IScaledUIAmountNewUIMultiplier extension to expose a pending UI multiplier that has been scheduled but has not yet taken effect:

interface IScaledUIAmountNewUIMultiplier {
    // Returns the pending UI multiplier scheduled to take effect at effectiveAt
    // Multiplier is represented with 18 decimals (1e18 = 1.0)
    function newUIMultiplier() external view returns (uint256);

    // Returns the timestamp at which the pending multiplier becomes effective
    function effectiveAt() external view returns (uint256);
}
Interface Detection

Compliant contracts MUST implement TRC-165 and return true when queried for the IScaledUIAmount interface ID.

Contracts implementing optional extensions MUST also return true for their respective interface IDs.

The interface identifiers are:

  • IScaledUIAmount: 0xa60bf13d
  • IScaledUIAmountNewUIMultiplier: 0x4bd27648
  • IScaledUIAmountConversion: 0x57854fc3
  • IScaledUIAmountBalances: 0xd890fd71
Implementation Requirements:
  1. TRC-165 Support: Compliant contracts MUST implement TRC-165 interface detection.

  2. Multiplier Precision: The UI multiplier MUST use 18 decimal places for precision (1e18 represents a multiplier of 1.0).

  3. Backwards Compatibility: The standard TRC-20 functions (balanceOf, transfer, transferFrom, etc.) MUST continue to work with raw amounts.

  4. Event Emission: The UIMultiplierUpdated event MUST be emitted whenever the multiplier is changed.

Reference Implementation

The following implementation includes the core interface and all optional extensions:

contract ScaledUIToken is
    ERC20,
    ERC165,
    IScaledUIAmount,
    IScaledUIAmountConversion,
    IScaledUIAmountBalances,
    IScaledUIAmountNewUIMultiplier,
    Ownable
{
    uint256 private constant MULTIPLIER_DECIMALS = 1e18;
    uint256 private _uiMultiplier = MULTIPLIER_DECIMALS; // Initially 1.0
    uint256 private _newUIMultiplier = MULTIPLIER_DECIMALS;
    uint256 private _effectiveAt = 0;

    constructor(string memory name, string memory symbol) ERC20(name, symbol) {}

    // TRC-165 interface detection
    function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool) {
        return
            interfaceId == type(IScaledUIAmount).interfaceId ||
            interfaceId == type(IScaledUIAmountConversion).interfaceId ||
            interfaceId == type(IScaledUIAmountBalances).interfaceId ||
            interfaceId == type(IScaledUIAmountNewUIMultiplier).interfaceId ||
            super.supportsInterface(interfaceId);
    }

    // ============ Core Interface ============

    function uiMultiplier() public view override returns (uint256) {
        uint256 currentTime = block.timestamp;
        if (currentTime >= _effectiveAt) {
            return _newUIMultiplier;
        } else {
            return _uiMultiplier;
        }
    }

    // ============ Pending Multiplier Interface ============

    function newUIMultiplier() public view override returns (uint256) {
        return _newUIMultiplier;
    }

    function effectiveAt() public view override returns (uint256) {
        return _effectiveAt;
    }

    // Implementation-specific: How the multiplier is updated
    function setUIMultiplier(uint256 newMultiplier, uint256 effectiveAtTimestamp) external onlyOwner {
        require(newMultiplier > 0, "Multiplier must be positive");

        uint256 currentTime = block.timestamp;
        require(effectiveAtTimestamp > currentTime, "Effective At must be in the future");

        if (currentTime > _effectiveAt) {
            uint256 oldMultiplier = _newUIMultiplier;
            _uiMultiplier = oldMultiplier;
            _newUIMultiplier = newMultiplier;
            _effectiveAt = effectiveAtTimestamp;
            emit UIMultiplierUpdated(oldMultiplier, newMultiplier, effectiveAtTimestamp);
        } else {
            uint256 oldMultiplier = _uiMultiplier;
            _newUIMultiplier = newMultiplier;
            _effectiveAt = effectiveAtTimestamp;
            emit UIMultiplierUpdated(oldMultiplier, newMultiplier, effectiveAtTimestamp);
        }
    }

    // ============ Optional: Conversion Extension ============

    function toUIAmount(uint256 rawAmount) public view override returns (uint256) {
        uint256 currentTime = block.timestamp;
        if (currentTime >= _effectiveAt) {
            return (rawAmount * _newUIMultiplier) / MULTIPLIER_DECIMALS;
        } else {
            return (rawAmount * _uiMultiplier) / MULTIPLIER_DECIMALS;
        }
    }

    function fromUIAmount(uint256 uiAmount) public view override returns (uint256) {
        uint256 currentTime = block.timestamp;
        if (currentTime >= _effectiveAt) {
            return (uiAmount * MULTIPLIER_DECIMALS) / _newUIMultiplier;
        } else {
            return (uiAmount * MULTIPLIER_DECIMALS) / _uiMultiplier;
        }
    }

    // ============ Optional: Balances Extension ============

    function balanceOfUI(address account) public view override returns (uint256) {
        return toUIAmount(balanceOf(account));
    }

    function totalSupplyUI() public view override returns (uint256) {
        return toUIAmount(totalSupply());
    }

    // ============ Optional: TransferWithUIAmount Event ============

    function _update(address from, address to, uint256 amount) internal virtual override {
        super._update(from, to, amount);
        uint256 uiAmount = toUIAmount(amount);
        emit TransferWithUIAmount(from, to, amount, uiAmount);
    }
}

Rationale

Design Decisions:

  1. Separate UI Functions: Rather than modifying the core TRC-20 functions, we provide separate UI-specific functions. This ensures backward compatibility and allows integrators to opt-in to the UI scaling feature.

  2. 18 Decimal Precision: Using 18 decimals for the multiplier provides sufficient precision for most use cases while aligning with the standard decimal representation.

  3. No Automatic Updates: The multiplier must be explicitly set by authorized parties, giving issuers full control over when and how adjustments are made.

  4. Raw Amount Preservation: All actual token operations continue to use raw amounts, ensuring that the multiplier is purely a display feature and doesn't affect the underlying token economics.

  5. Optional Extensions: Following the pattern established by TRC-721 and TRC-1155, helper functions like toUIAmount, fromUIAmount, balanceOfUI, and totalSupplyUI are defined in separate optional interfaces. The TransferWithUIAmount event is defined in the core interface as optional since events do not affect interface IDs. This keeps the core interface minimal while allowing contracts to opt-in to additional on-chain functionality. Integrators can detect support for these extensions using TRC-165 interface detection.

Alternative Approaches Considered:

  1. Rebasing Tokens: While rebasing tokens adjust supply automatically, they create complexity for integrators and can break composability with DeFi protocols.

  2. Wrapper Tokens: Creating wrapper tokens for each adjustment event adds unnecessary complexity and energy costs.

  3. Index/Exchange Rate Tokens confer similar advantages to the proposed Scaled UI approach, but is ultimately less intuitive and requires more calculations on the UI layers.

  4. Off-chain Solutions: Purely off-chain solutions lack standardization and require trust in centralized providers.

Token Value Representation Approaches

Token Architecture Layers

Backwards Compatibility

This proposal is fully backwards compatible with TRC-20. Existing TRC-20 functions continue to work as expected, and the UI scaling features are opt-in through additional functions.

Test Cases

Example test scenarios:

  1. Initial Multiplier Test:
    • Verify that initial multiplier is 1.0 (1e18)
    • Confirm balanceOf equals balanceOfUI initially
  2. Stock Split Test:
    • Set multiplier to 2.0 (2e18) for 2-for-1 split
    • Verify UI balance is double the raw balance
    • Confirm conversion functions work correctly

Security Considerations

  1. Multiplier Manipulation
    • Unauthorized changes to the UI multiplier could mislead users about their holdings
    • Implementations MUST use robust access control mechanisms
    • The setUIMultiplier function MUST be restricted to authorized addresses (e.g., contract owner or a designated role).
  2. Integer Overflow
    • Risk of overflow when applying the multiplier
    • Use SafeMath or Solidity 0.8.0+ automatic overflow protection
  3. User Confusion
    • Clear communication is essential when UI amounts differ from raw amounts
    • Integrators MUST clearly indicate when displaying UI-adjusted balances
  4. Oracle Dependency
    • For automated multiplier updates, the system may depend on oracles
    • Oracle failures or manipulations could affect displayed balances
  5. Overflow Protection: Implementations MUST handle potential overflow when applying the multiplier.
Implementation Guide for Integrators
Wallet Integration

Wallets supporting this standard should:

  1. Check if a token implements IScaledUIAmount interface using TRC-165

  2. Optionally check for IScaledUIAmountBalances extension for on-chain balance queries

  3. Display both raw and UI amounts, clearly labeled

  4. Compute UI balance off-chain using balanceOf() and uiMultiplier(), or use balanceOfUI() if the extension is supported

  5. Handle transfers using raw amounts (standard TRC-20 functions)

Example JavaScript integration:

const MULTIPLIER_DECIMALS = BigInt(1e18);

// Interface IDs for TRC-165 detection
const ISCALED_UI_AMOUNT_ID = "0xa60bf13d";
const ISCALED_UI_BALANCES_ID = "0xd890fd71";

// Off-chain conversion functions
function toUIAmount(rawAmount, multiplier) {
    return (BigInt(rawAmount) * BigInt(multiplier)) / MULTIPLIER_DECIMALS;
}

function fromUIAmount(uiAmount, multiplier) {
    return (BigInt(uiAmount) * MULTIPLIER_DECIMALS) / BigInt(multiplier);
}

async function displayBalance(tokenAddress, userAddress) {
    const token = await tronWeb.contract(ScaledUIAmountABI, tokenAddress);

    // Check if core scaled UI is supported
    const supportsScaledUI = await token.supportsInterface(ISCALED_UI_AMOUNT_ID).call();

    if (!supportsScaledUI) {
        // Fall back to standard TRC-20
        const balance = await token.balanceOf(userAddress).call();
        return {
            display: formatUnits(balance, decimals),
            raw: formatUnits(balance, decimals),
            multiplier: "1.0"
        };
    }

    // Check if optional balances extension is supported
    const supportsBalancesExt = await token.supportsInterface(ISCALED_UI_BALANCES_ID).call();

    const rawBalance = await token.balanceOf(userAddress).call();
    const multiplier = await token.uiMultiplier().call();

    // Use on-chain balanceOfUI if available, otherwise compute off-chain
    const uiBalance = supportsBalancesExt
        ? await token.balanceOfUI(userAddress).call()
        : toUIAmount(rawBalance, multiplier);

    return {
        display: formatUnits(uiBalance, decimals),
        raw: formatUnits(rawBalance, decimals),
        multiplier: formatUnits(multiplier, 18)
    };
}
Exchange Integration

Exchanges should:

  1. Store and track the multiplier for each supported token

  2. Display UI amounts in user interfaces

  3. Use raw amounts for all internal accounting

  4. Provide clear documentation about the scaling mechanism

Example implementation:

const MULTIPLIER_DECIMALS = BigInt(1e18);

class ScaledTokenHandler {
    // Off-chain conversion functions
    toUIAmount(rawAmount, multiplier) {
        return (BigInt(rawAmount) * BigInt(multiplier)) / MULTIPLIER_DECIMALS;
    }

    fromUIAmount(uiAmount, multiplier) {
        return (BigInt(uiAmount) * MULTIPLIER_DECIMALS) / BigInt(multiplier);
    }

    async processDeposit(tokenAddress, amount, isUIAmount) {
        const token = await tronWeb.contract(ScaledUIAmountABI, tokenAddress);

        let rawAmount;
        if (isUIAmount && await this.supportsScaledUI(tokenAddress)) {
            const multiplier = await token.uiMultiplier().call();
            rawAmount = this.fromUIAmount(amount, multiplier);
        } else {
            rawAmount = amount;
        }

        // Process deposit with raw amount
        return this.recordDeposit(tokenAddress, rawAmount);
    }

    async getDisplayBalance(tokenAddress, userAddress) {
        const token = await tronWeb.contract(ScaledUIAmountABI, tokenAddress);
        const rawBalance = await this.getInternalBalance(userAddress, tokenAddress);

        if (await this.supportsScaledUI(tokenAddress)) {
            const multiplier = await token.uiMultiplier().call();
            return this.toUIAmount(rawBalance, multiplier);
        }
        return rawBalance;
    }
}
DeFi Protocol Integration

DeFi protocols should:

  1. Continue using raw amounts for all protocol operations

  2. Provide UI helpers for displaying adjusted amounts

  3. Emit events with both raw and UI amounts where relevant

  4. Document clearly which amounts are used in calculations

Copyright

Copyright and related rights waived via CC0.

主要言語
言語のデータがありません
スター
341
フォーク
347
PR マージ指標
30日以内にマージされた PR はありません

環境構築

このプロジェクトには開発コンテナ、Dockerfile、コントリビューションガイドがありません。まず README を読み、一般的な手順ははじめてのコントリビューションガイドを参照してください。

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

tronprotocol/tips のほかの issue

tronprotocol/tips の issue をすべて見る

似ている issue

Blockchain の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。