Підтримка розширення Scaled UI Amount на Solana

Передумови

Розширення Scaled UI Amount дозволяє емітентам токенів вказати множник, який використовуватиметься при обчисленні UI-суми балансу токенів користувача. Це дає змогу емітентам створювати токени з ребазингом та уможливлювати такі речі, як дроблення акцій. Це розширення, як і розширення токенів, що приносять відсотки, надає суто косметичну UI-суму, що означає необхідність додаткової роботи команд для забезпечення хорошого досвіду користувачів. Базові обчислення та перекази відбуваються з використанням необроблених сум у програмі.

Ресурси:

• Документація для розробників
• Код розширення на Rust
• Код перетворення суми в UI-суму на Rust

Коротко

• Кінцеві користувачі повинні взаємодіяти з UIAmount (необроблена сума * множник) для ціни токена, балансу токена та сум токенів, коли це можливо
• dApps та постачальники послуг повинні використовувати необроблену суму та немасштабовані ціни для всіх обчислень і конвертувати їх для користувачів на кінцевому етапі
• Історичні цінові фіди повинні надаватися як для масштабованих, так і для немасштабованих сум для полегшення інтеграції
• Історичні значення множника повинні бути доступними для точних історичних даних

Визначення термінів

• Множник: статичний оновлюваний множник, що використовується для обчислень UI-суми
• UIAmount: множник * необроблена сума (також відома як: масштабована сума)
• Raw Amount: сума (також відома як: немасштабована сума)

Поточний баланс

Поточна сума для відображення

• Щоразу, коли ви відображаєте суми для токенів, які використовують розширення масштабованої UI-суми для кінцевих користувачів, вам слід використовувати:
  • 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. Крім того, якщо встановлено майбутній множник, ця інформація також доступна з токен-мінту. Ми рекомендуємо не показувати цей множник, оскільки він може заплутати UX.

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
*/

Історичні дані

Історичні дані для цінового фіду

• Сервіси, які надають історичні дані, повинні зберігати та показувати як масштабовані, так і немасштабовані ціни для розширення масштабованої UI-суми.
• Ми очікуємо, що масштабовані суми будуть використовуватися найчастіше, оскільки це відповідає тому, як традиційний фінансовий світ обробляє графіки, пов'язані з токенами зі спліт-акціями.

Історичні дані для сум

• Якщо ви хочете показати баланс, переданий у минулому, вам потрібен доступ до множника на той конкретний slot. Ви також можете зберігати UiAmount для переказів під час обробки транзакцій, щоб уникнути цього розрахунку в майбутньому.

Зворотна сумісність

• За замовчуванням гаманці та програми, які не розуміють розширення масштабованої UI суми, показуватимуть правильну загальну ціну активності шляхом множення немасштабованої ціни * на необроблену кількість.
• Однак вони відображатимуть немасштабовану ціну, що може спричинити деяку плутанину для користувачів.
• Ми сподіваємося, що це заохотить команди оновити свої децентралізовані додатки для сумісності з токенами, які використовують розширення масштабованої UI суми, і ми раді надати підтримку під час цього процесу.

Рекомендовані пріоритети інтеграції за платформами

Загальні вимоги

Гаманці

Провідники

Агрегатори ринкових даних (наприклад, CoinGecko)

Постачальники потоків цін

DEX-и