Supporting Scaled UI Amount Extension on Solana

Background

The Scaled UI Amount extension allows token issuers to specify a multiplier to be used when calculating the UI amount of a user’s token balance. This enables issuers to create rebasing tokens and to enable things like stock splits. This extension, like the interest bearing token extension, provides a purely cosmetic UI amount which means teams need to do some additional work to provide a good experience. Underlying calculations and transfers all occur using the raw amounts in the program.

Resources:

• Developer Documentation
• Extension Rust Code
• Amount to UI Amount Rust Code

TL;DR

• End users should interact with the UIAmount (raw amount * multiplier) for the token price, token balance, and token amounts whenever possible
• dApps and service providers should use the raw amount and non-scaled prices for all calculations and convert for users at the edge
• Historical price feeds need to be provided for both scaled and non-scaled amounts for easier integration
• Historical multiplier values need to be accessible for accurate historical data

Terms Definitions

• Multiplier: static updatable multiplier that’s used for UI Amount calculations
• UIAmount: multiplier * raw amount (AKA: scaled amount)
• Raw Amount: amount (AKA: non-scaled amount)

Current Balance

Current Amount for Display

• Anytime you display amounts for tokens that use the scaled UI amount extension to end users you should use either:
  • UIAmount/UIAmountString (preferred)
  • A manual calculation of raw amount * multiplier
  • We recommend truncating this value based on the number of decimals the token has.
    • Ex: if yUSD has 6 decimals and a user has a UIAmount of 1.123456789 you should display “1.123456”

Where to get this data:

• For a user’s live balance you can get updated information on the above amounts by calling either getTokenAccountBalance or getAccountInfo
• If you need to know the UI Amount for an arbitrary amount you can get this calculation by calling the amountToUiAmountForMintWithoutSimulation (web3.js v1) function or simulating a transaction using amountToUiAmount.
  • Note: amountToUiAmount requires a transaction simulation which means it also needs a valid fee payer with balance. Because of this, this should not be the default way to get a balance.

Updating the Current Amount

Because Issuers can update the multiplier at any given time you can consider occasionally polling in order to keep the account balance updated. Issuers are unlikely to update this multiplier more than once per day. If a multiplier is set for a future date, you can automatically poll at this update time

Token Amounts in Transactions (transfers / swaps etc)

• Users should enter amounts to be interpreted as the scaled “UIAmount”. The app that has to process this should convert to the raw token amount for the transaction.
  • If there are rounding issues, round down and prefer leaving a tiny amount of dust rather than risk the transaction failing
  • To do this conversion you can use the uiAmountToAmountForMintWithoutSimulation (web3.js v1) function or simulating a transaction using amountToUiAmount.
• Apps should use the total raw amount when a user requests to do an action with “max” or “all” of their balance. This ensures that there is no dust left over.
  • Optional: You can consider automatically closing an account when “max” is used to refund the user of their storage deposit

Token Price

• Token price should always be displayed as the scaled price wherever possible.
• If you are a price feed service provider, such as an oracle, you should expose both the scaled and non-scaled price.
  • Wherever possible provide an SDK/API that abstracts the scaled UI amount extension complexities away.

Current Multiplier

• The current multiplier can be read from the token mint at any time by calling getAccountInfo. Additionally, if a future multiplier is set, this information is also available from the token mint. We recommend not showing this multiplier as it can confuse the UX.

Historical Data

Historical Data for Price Feed

• Services who provide historical data should store and surface both the scaled and non-scaled prices for the scaled UI amount extension.
• We expect scaled amounts to be used most frequently as this aligns with how the traditional finance world treats charts related to tokens with stock splits.

Historical Data for Amounts

• If you would like to show the balance transferred in the past you need access to the multiplier at that given slot. You can also save the UiAmount for transfers as you process transactions to avoid doing this calculation in the future.

Backwards Compatibility

• By default wallets and applications that do not understand the scaled UI amount extension will show the correct total price of an activity by multiplying the non-scaled price * raw amount.
• They would, however, display the non-scaled price causing some user confusion.
• We hope this encourages teams to update their dapps to be compatible with tokens that use the scaled UI amount extension and are happy to provide support during this process.

Recommended Integration Priorities Per Platform

General Requirements

---

Wallets

---

Explorers

---

Market Data Aggregators (Ex: CoinGecko)

---

Price Feed Providers

---

DEXes