Посібник з інтеграції масштабованої суми інтерфейсу
Підтримка розширення масштабованої суми інтерфейсу на Solana
Передумови
Розширення Scaled UI Amount дозволяє емітентам токенів вказати множник, який буде використовуватися при обчисленні UI-суми балансу токенів користувача. Це дає змогу емітентам створювати токени з ребазингом та уможливлювати такі речі, як дроблення акцій. Це розширення, як і розширення токенів з нарахуванням відсотків, надає суто косметичну UI-суму, що означає, що командам потрібно виконати додаткову роботу для забезпечення хорошого досвіду користувачів. Базові обчислення та перекази здійснюються з використанням необроблених сум у програмі.
Ресурси:
Коротко
- Кінцеві користувачі повинні взаємодіяти з UIAmount (необроблена сума * множник) для ціни токена, балансу токена та кількості токенів, коли це можливо
- Децентралізовані додатки та постачальники послуг повинні використовувати необроблену суму та немасштабовані ціни для всіх обчислень і конвертувати для користувачів на кінцевому етапі
- Історичні цінові фіди повинні надаватися як для масштабованих, так і для немасштабованих сум для простішої інтеграції
- Історичні значення множника повинні бути доступними для точних історичних даних
Визначення термінів
- Множник: статичний оновлюваний множник, який використовується для обчислень UI Amount
- UIAmount: множник * необроблена сума (також відома як: масштабована сума)
- Raw Amount: сума (також відома як: немасштабована сума)
Поточний баланс
Поточна сума для відображення
- Щоразу, коли ви відображаєте суми для токенів, які використовують розширення
scaled UI amount для кінцевих користувачів, вам слід використовувати:
- UIAmount/UIAmountString (рекомендовано)
- Ручне обчислення необробленої суми * множник
- Ми рекомендуємо обрізати це значення на основі кількості десяткових знаків,
які має токен.
- Наприклад: якщо yUSD має 6 десяткових знаків і користувач має UIAmount 1.123456789, вам слід відображати "1.123456"
Де отримати ці дані:
- Для перегляду актуального балансу користувача ви можете отримати оновлену інформацію про вищезазначені суми викликавши getTokenAccountBalance або getAccountInfo
- Якщо вам потрібно дізнатися UI Amount для довільної суми, ви можете отримати
цей розрахунок, викликавши функцію
amountToUiAmountForMintWithoutSimulation
(web3.js v1) або симулюючи транзакцію за допомогою amountToUiAmount.- Примітка: amountToUiAmount потребує симуляції транзакції, що означає, що також потрібен дійсний платник комісії з балансом. Через це, це не повинен бути стандартним способом отримання балансу.
RPC-виклики
getTokenAccountBalance
- Повертає баланс token account та інформацію про mint
import { address, createSolanaRpc } from "@solana/kit";const rpc_url = "https://api.devnet.solana.com";const rpc = createSolanaRpc(rpc_url);let tokenAddress = address("2uuvxpnEKw52aTqNerHiQ3WeSqZriCMNVt8LhWfrkbPk");let tokenBalance = await rpc.getTokenAccountBalance(tokenAddress).send();console.log("Token Balance:", tokenBalance);/* Token Balance: {context: { apiVersion: '2.2.14', slot: 381132711n },value: {amount: '10000000',decimals: 6,uiAmount: 20,uiAmountString: '20'}} */
getAccountInfo
- Повертає інформацію про акаунт та інформацію про mint
import { address, createSolanaRpc } from "@solana/kit";const rpc_url = "https://api.devnet.solana.com";const rpc = createSolanaRpc(rpc_url);const publicKey = address("2uuvxpnEKw52aTqNerHiQ3WeSqZriCMNVt8LhWfrkbPk");const accountInfo = await rpc.getAccountInfo(publicKey).send();console.log("Account Info:",JSON.stringify(accountInfo,(key, value) => (typeof value === "bigint" ? value.toString() : value),2));/* Account Info: {"context": {"apiVersion": "2.2.14","slot": "381133640"},"value": {"data": {"parsed": {"info": {"extensions": [{"extension": "immutableOwner"},{"extension": "pausableAccount"}],"isNative": false,"mint": "BZCd6HfTbb5ZYJ8hQsm8282tG4QzLyeqFR6tdgQA9EAG","owner": "G7ARQSUCwNrfvTDUCZvM5xdiRdBJiN3qVw2PryD8Wnib","state": "initialized","tokenAmount": {"amount": "10000000","decimals": 6,"uiAmount": 20,"uiAmountString": "20"}},"type": "account"},"program": "spl-token-2022","space": "174"},"executable": false,"lamports": "2101920","owner": "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb","rentEpoch": "18446744073709551615","space": "174"}} */
Оновлення поточної суми
Оскільки емітенти можуть оновлювати множник у будь-який час, ви можете розглянути можливість періодичного опитування для підтримки актуальності балансу рахунку. Емітенти навряд чи оновлюватимуть цей множник частіше, ніж раз на день. Якщо множник встановлено на майбутню дату, ви можете автоматично опитувати систему в цей час оновлення
Суми токенів у транзакціях (перекази / обміни тощо)
- Користувачі повинні вводити суми, які інтерпретуються як масштабована
"UIAmount". Додаток, який має обробляти це, повинен конвертувати в необроблену
суму токенів для транзакції.
- Якщо виникають проблеми з округленням, округліть у меншу сторону і краще залиште невелику кількість пилу, ніж ризикуйте невдачею транзакції
- Для цього перетворення ви можете використовувати функцію
uiAmountToAmountForMintWithoutSimulation
(web3.js v1) або симулювати транзакцію за допомогою amountToUiAmount.
import { uiAmountToAmountForMintWithoutSimulation } from "@solana/web3.js";import { Connection, PublicKey, clusterApiUrl } from "@solana/web3.js";const connection = new Connection(clusterApiUrl("devnet"), "confirmed");const mint = new PublicKey("BZCd6HfTbb5ZYJ8hQsm8282tG4QzLyeqFR6tdgQA9EAG");const uiAmount = "20.2";const rawAmount = await uiAmountToAmountForMintWithoutSimulation(connection as unknown as Connection,mint,uiAmount);console.log("Raw Amount:", rawAmount);/* Raw Amount: 20200000 */
- Додатки повинні використовувати загальну необроблену суму, коли користувач
запитує виконати дію з "максимальним" або "всім" своїм балансом. Це гарантує,
що не залишиться пилу.
- Опціонально: Ви можете розглянути можливість автоматичного закриття рахунку, коли використовується "максимум", щоб повернути користувачеві їхній депозит зберігання
Ціна токена
- Ціна токена завжди повинна відображатися як масштабована ціна, де це можливо.
- Якщо ви є постачальником цінових фідів, наприклад оракулом, ви повинні
надавати як масштабовану, так і немасштабовану ціну.
- Де можливо, надавайте SDK/API, який абстрагує складності розширення масштабованої UI-суми.
Поточний множник
- Поточний множник можна зчитати з мінту токена в будь-який час, викликавши
getAccountInfo
. Крім того, якщо встановлено майбутній множник, ця інформація також доступна з мінту токена. Ми рекомендуємо не показувати цей множник, оскільки це може заплутати користувацький інтерфейс.
import { address, createSolanaRpc } from "@solana/kit";const rpc_url = "https://api.devnet.solana.com";const rpc = createSolanaRpc(rpc_url);const publicKey = address("BZCd6HfTbb5ZYJ8hQsm8282tG4QzLyeqFR6tdgQA9EAG");const accountInfo = await rpc.getAccountInfo(publicKey, { encoding: "jsonParsed" }).send();const mintData = accountInfo.value?.data as Readonly<{parsed: {info?: {extensions: {extension: string;state: object;}[];};type: string;};program: string;space: bigint;}>;const scaledUiAmountConfig = mintData.parsed.info?.extensions?.find((extension) => extension.extension === "scaledUiAmountConfig") as Readonly<{state: {newMultiplierEffectiveTimestamp: number;newMultiplier: number;multiplier: number;};}>;const currentMultiplier =scaledUiAmountConfig?.state &&Date.now() / 1000 >=scaledUiAmountConfig.state.newMultiplierEffectiveTimestamp? scaledUiAmountConfig.state.newMultiplier: scaledUiAmountConfig.state.multiplier;console.log("Scaled UI Amount Config:", scaledUiAmountConfig);console.log("Current Multiplier:", currentMultiplier);/*Scaled UI Amount Config: {extension: 'scaledUiAmountConfig',state: {authority: 'G7ARQSUCwNrfvTDUCZvM5xdiRdBJiN3qVw2PryD8Wnib',multiplier: '2',newMultiplier: '2',newMultiplierEffectiveTimestamp: 1743000000n}}Current Multiplier: 2*/
Історичні дані
Історичні дані для цінового фіду
- Сервіси, які надають історичні дані, повинні зберігати та показувати як масштабовані, так і немасштабовані ціни для розширення масштабованої суми інтерфейсу.
- Ми очікуємо, що масштабовані суми будуть використовуватися найчастіше, оскільки це відповідає тому, як традиційний фінансовий світ обробляє графіки, пов'язані з токенами зі спліт-акціями.
Історичні дані для сум
- Якщо ви хочете показати баланс, переказаний у минулому, вам потрібен доступ до множника на той конкретний slot. Ви також можете зберігати UiAmount для переказів під час обробки транзакцій, щоб уникнути цього обчислення в майбутньому.
Зворотна сумісність
- За замовчуванням гаманці та програми, які не розуміють розширення масштабованої суми інтерфейсу, показуватимуть правильну загальну ціну активності, множачи немасштабовану ціну * сиру суму.
- Однак вони відображатимуть немасштабовану ціну, що може спричинити деяку плутанину для користувачів.
- Ми сподіваємося, що це заохотить команди оновити свої децентралізовані програми для сумісності з токенами, які використовують розширення масштабованої суми інтерфейсу, і ми раді надати підтримку під час цього процесу.
Рекомендовані пріоритети інтеграції за платформами
Загальні вимоги
Вимога | Опис | Пріоритет |
---|---|---|
Підтримка дій користувача з UiAmount | Усі дії користувача повинні вводитися в UiAmount, коли UiAmount увімкнено в усьому додатку. Якщо UiAmount не видно в додатку, вони повинні використовувати сирі суми, доки додаток не буде оновлено. | P0 |
Гаманці
Вимога | Опис | Пріоритет |
---|---|---|
Відображення масштабованого балансу | Показувати масштабовану суму (uiAmount) як основний баланс. | P0 |
Підтримка переказів токенів | Кінцеві користувачі повинні вводити суми переказів з їхніми масштабованими балансами (сира сума * баланс). | P0 |
Відображення спотової ціни | Відображати масштабовану спотову ціну для користувачів | P0 |
Метадані історії транзакцій | Показувати масштабовану суму (UIAmount) для кожного переказу, де це можливо. | P1 |
Показ оновлень множника в історії транзакцій | Коли відбуваються оновлення множника, показувати це як подію в історії транзакцій користувача, включаючи отриману суму | P2 |
Відображення графіка історії цін | Відображати масштабовані ціни на графіку цін | P1 |
Онбординг/Підказки | Пропонувати підказки або онбординг для інформування користувачів про токени, які використовують розширення масштабованої суми ui | P2 |
Провідники
Вимога | Опис | Пріоритет |
---|---|---|
Покращення сторінки деталей токена | Відображення метаданих, таких як загальна масштабована ринкова капіталізація та поточний множник | P0 |
Відображення масштабованого балансу для балансів | Відображення масштабованих балансів (UiAmount) для поточних балансів. | P0 |
Відображення масштабованого балансу для транзакцій | Відображення масштабованих балансів (UiAmount) для сум переказів для історичних транзакцій. | P0 |
Відображення масштабованої ціни для транзакцій | Відображення масштабованих цін для попередніх транзакцій | P1 |
Правильний аналіз і відображення транзакцій оновлення множника | Правильно показувати деталі про оновлення множника | P2 |
Агрегатори ринкових даних (наприклад: CoinGecko)
Вимога | Опис | Пріоритет |
---|---|---|
Оновлення API для масштабованих даних | Розширити функціональність API, щоб включити зміни множника з часом, а також масштабовану ціну. | P0 |
Загальна пропозиція з масштабованим коригуванням | При відображенні загальної пропозиції та загальної ринкової капіталізації враховувати масштабовані баланси | P0 |
Відстеження історичних цін | Надавати історичний графік цін, використовуючи масштабовану ціну з часом. | P1 |
Відстеження історичних множників | Надавати історичні маркери оновлень множника для токенів, що приносять відсотки. | P2 |
Освітній контент або пояснення | Включати короткі описи або підказки, що пояснюють, як працюють масштабовані токени. | P2 |
Постачальники цінових фідів
Вимога | Опис | Пріоритет |
---|---|---|
Масштабовані та немасштабовані цінові фіди | Надавати цінові фіди як для масштабованих, так і для немасштабованих цін. | P0 |
Дані про історичні множники | Пропонувати API з історичними змінами множника. | P0 |
Дані про історичні ціни | Пропонувати API з історичними цінами на основі як масштабованих, так і немасштабованих сум. | P0 |
DEX-и
Вимога | Опис | Пріоритет |
---|---|---|
Відображення ребазованих балансів токенів | Показувати масштабовані баланси для торгівлі або надання ліквідності в інтерфейсі (бекенд може використовувати необроблені суми) | P0 |
Підтримка дій з токенами | Кінцеві користувачі повинні вводити суми дій зі своїми балансами UiAmount (множник * необроблена сума). | P0 |
Адаптація цінового фіду | Будь-де, де використовується ціновий фід для відображення поточної ціни, надавати масштабовану ціну кінцевим користувачам. | P1 |
Відображення графіка історії цін | Відображати масштабовані ціни на графіку цін | P1 |
Is this page helpful?