Поддержка расширения Scaled UI Amount в Solana

Введение

Расширение Scaled UI Amount позволяет эмитентам токенов указывать множитель, который используется при вычислении UI-количества баланса токена пользователя. Это даёт возможность создавать ребейзинговые токены и реализовывать такие функции, как дробление акций. Это расширение, как и расширение для токенов с начислением процентов, предоставляет исключительно косметическое UI-значение, поэтому командам необходимо выполнить дополнительную работу для обеспечения качественного пользовательского опыта. Все базовые вычисления и переводы происходят с использованием необработанных значений в программе.

Ресурсы:

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

Кратко

• Конечные пользователи должны взаимодействовать с UIAmount (необработанное значение * множитель) для цены токена, баланса токена и количества токенов, когда это возможно
• dApp и сервис-провайдеры должны использовать необработанные значения и нескейленные цены для всех вычислений и преобразовывать их для пользователей на уровне интерфейса
• Для облегчения интеграции необходимо предоставлять исторические ценовые данные как для скейленных, так и для нескейленных значений
• Для точных исторических данных должен быть доступ к историческим значениям множителя

Определения терминов

• Множитель: статический обновляемый множитель, используемый для вычисления UI Amount
• UIAmount: множитель * необработанное значение (также: скейленное значение)
• Необработанное значение: 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

$ 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-объема.
• Мы ожидаем, что масштабированные объемы будут использоваться чаще, так как это соответствует тому, как традиционные финансовые рынки отображают графики для токенов с дроблением акций.
• Обновления множителя могут включать временную метку, которая находится в прошлом. Рекомендуем использовать временную метку блока для исторических данных.
• Обратите внимание, что активный множитель может быть как "multiplier", так и "newMultiplier" в зависимости от текущей временной метки и времени, когда новый множитель должен стать активным.

Исторические данные по суммам

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

Обратная совместимость

• По умолчанию кошельки и приложения, которые не поддерживают расширение масштабируемого UIAmount, будут показывать правильную итоговую цену операции, умножая немасштабированную цену на необработанную сумму.
• Однако они будут отображать немасштабированную цену, что может вызвать путаницу у пользователей.
• Мы надеемся, что это побудит команды обновить свои dapp для совместимости с токенами, использующими расширение масштабируемого UIAmount, и готовы оказать поддержку в этом процессе.

Рекомендуемые приоритеты интеграции по платформам

Общие требования

Кошельки

Обозреватели

Агрегаторы рыночных данных (например, CoinGecko, Birdeye)

Поставщики ценовых данных

DEX

CEX