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

Передумови

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

Ресурси:

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

Коротко

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

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

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

Поточний множник

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

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

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

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

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

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

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

Гаманці

Провідники

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

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

DEX-и

CEX-и