Підтримка розширення 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

$ curl http://localhost:8899 -s -X POST -H "Content-Type: application/json" -d '
{"jsonrpc": "2.0", "id": 1, "method": "getTokenAccountBalance", "params": ["2uuvxpnEKw52aTqNerHiQ3WeSqZriCMNVt8LhWfrkbPk"]}' | jq .

{
  "jsonrpc": "2.0",
  "result": {
    "context": {
      "apiVersion": "2.2.14",
      "slot": 381130751
    },
    "value": {
      "amount": "10000000",
      "decimals": 6,
      "uiAmount": 20.0,
      "uiAmountString": "20"
    }
  },
  "id": 1
}

• getAccountInfo
  • Повертає інформацію про акаунт та інформацію про mint

$ curl http://localhost:8899 -s -X POST -H "Content-Type: application/json" -d '
{"jsonrpc": "2.0", "id": 1, "method": "getAccountInfo", "params": ["2uuvxpnEKw52aTqNerHiQ3WeSqZriCMNVt8LhWfrkbPk", {"encoding": "jsonParsed"}]}' | jq .

{
  "jsonrpc": "2.0",
  "result": {
    "context": {
      "apiVersion": "2.2.14",
      "slot": 381131001
    },
    "value": {
      "data": {
        "parsed": {
          "info": {
            "extensions": [
              {
                "extension": "immutableOwner"
              },
              {
                "extension": "pausableAccount"
              }
            ],
            "isNative": false,
            "mint": "BZCd6HfTbb5ZYJ8hQsm8282tG4QzLyeqFR6tdgQA9EAG",
            "owner": "G7ARQSUCwNrfvTDUCZvM5xdiRdBJiN3qVw2PryD8Wnib",
            "state": "initialized",
            "tokenAmount": {
              "amount": "10000000",
              "decimals": 6,
              "uiAmount": 20.0,
              "uiAmountString": "20"
            }
          },
          "type": "account"
        },
        "program": "spl-token-2022",
        "space": 174
      },
      "executable": false,
      "lamports": 2101920,
      "owner": "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb",
      "rentEpoch": 18446744073709551615,
      "space": 174
    }
  },
  "id": 1
}

Оновлення поточної суми

Оскільки емітенти можуть оновлювати множник у будь-який час, ви можете розглянути можливість періодичного опитування для підтримки актуальності балансу рахунку. Емітенти навряд чи оновлюватимуть цей множник частіше, ніж раз на день. Якщо множник встановлено на майбутню дату, ви можете автоматично опитувати систему в цей час оновлення

Суми токенів у транзакціях (перекази / обміни тощо)

• Користувачі повинні вводити суми, які інтерпретуються як масштабований "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-и

CEX-и