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

Общая информация

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

Ресурсы:

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

Кратко

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

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

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

Текущий баланс

Текущее значение для отображения

• Каждый раз, когда вы отображаете значения для токенов, использующих расширение Scaled UI Amount, конечным пользователям, вы должны использовать либо:
  • UIAmount/UIAmountString (предпочтительно)
  • Ручной расчет необработанного значения * множитель
  • Мы рекомендуем усекать это значение в зависимости от количества десятичных знаков, которые имеет токен.
    • Например: если yUSD имеет 6 десятичных знаков, а пользователь имеет UIAmount 1.123456789, вы должны отображать "1.123456"

Где получить эти данные:

• Для получения актуального баланса пользователя вы можете обновить информацию о вышеуказанных суммах, вызвав либо getTokenAccountBalance, либо getAccountInfo.
• Если вам нужно узнать UI Amount для произвольной суммы, вы можете выполнить этот расчет, вызвав функцию amountToUiAmountForMintWithoutSimulation (web3.js v1) или смоделировав транзакцию с использованием amountToUiAmount.
  • Примечание: amountToUiAmount требует симуляции транзакции, что означает, что также необходим действительный плательщик комиссии с балансом. По этой причине это не должно быть основным способом получения баланса.

Обновление текущей суммы

Поскольку эмитенты могут обновлять множитель в любое время, вы можете рассмотреть возможность периодического опроса, чтобы поддерживать актуальность баланса аккаунта. Эмитенты вряд ли будут обновлять этот множитель чаще одного раза в день. Если множитель установлен на будущую дату, вы можете автоматически опрашивать в это время обновления.

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

• Пользователи должны вводить суммы, которые интерпретируются как масштабированный «UIAmount». Приложение, которое должно обработать это, должно преобразовать в необработанную сумму токена для транзакции.
  • Если возникают проблемы с округлением, округляйте в меньшую сторону и оставляйте небольшое количество «пыли», чтобы избежать сбоя транзакции.
  • Для выполнения этого преобразования вы можете использовать функцию uiAmountToAmountForMintWithoutSimulation (web3.js v1) или смоделировать транзакцию с использованием amountToUiAmount.
• Приложения должны использовать общую необработанную сумму, когда пользователь запрашивает выполнение действия с «максимумом» или «всем» своим балансом. Это гарантирует, что не останется «пыли».
  • Дополнительно: вы можете рассмотреть возможность автоматического закрытия аккаунта при использовании «максимума», чтобы вернуть пользователю его депозит за хранение.

Цена токена

• Цена токена всегда должна отображаться как масштабированная цена, где это возможно.
• Если вы являетесь поставщиком данных о ценах, таким как оракул, вы должны предоставлять как масштабированную, так и немасштабированную цену.
  • По возможности предоставляйте SDK/API, которые абстрагируют сложности расширения масштабированного UI-значения.

Текущий множитель

• Текущий множитель можно получить из токенового минта в любое время, вызвав getAccountInfo. Кроме того, если установлен будущий множитель, эта информация также доступна из токенового минта. Мы рекомендуем не отображать этот множитель, так как это может запутать пользовательский интерфейс.

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

Исторические данные для источника цен

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

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

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

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

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

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

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

---

Кошельки

---

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

---

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

---

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

---

DEXы