Підтримка розширення масштабованої суми інтерфейсу на Solana

Передумови

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

Ресурси:

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

Коротко

• Кінцеві користувачі повинні взаємодіяти з 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 для переказів під час обробки транзакцій, щоб уникнути цього обчислення в майбутньому.

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

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

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

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

Гаманці

Провідники

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

Постачальники цінових фідів

DEX-и