在 Solana 上支持缩放 UI 数量扩展

背景

Scaled UI Amount 扩展允许代币发行方指定一个乘数，用于计算用户代币余额的 UI 数量。这使得发行方能够创建可调整供应的代币，并实现类似股票拆分的功能。与利息代币扩展类似，此扩展提供的是纯粹的视觉效果 UI 数量，这意味着团队需要额外的工作来提供良好的用户体验。所有底层计算和转账都使用程序中的原始数量进行。

资源：

• 开发者文档
• 扩展 Rust 代码
• 数量到 UI 数量的 Rust 代码

简而言之

• 终端用户应尽可能使用 UIAmount（原始数量 * 乘数）来查看代币价格、代币余额和代币数量
• dApp 和服务提供商应使用原始数量和非缩放价格进行所有计算，并在边缘为用户转换
• 历史价格数据需要同时提供缩放和非缩放数量，以便于集成
• 历史乘数值需要可访问，以确保准确的历史数据

术语定义

• 乘数：用于 UI 数量计算的可更新静态乘数
• 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 从代币铸造中读取。此外，如果设置了未来的乘数，该信息也可以从代币铸造中获取。我们建议不要显示此乘数，因为它可能会混淆用户体验（UX）。

历史数据

价格数据的历史记录

• 提供历史数据的服务应存储并展示缩放价格和非缩放价格，以支持缩放 UI 金额扩展。
• 我们预计缩放金额会被更频繁地使用，因为这与传统金融世界中处理与股票分割相关的代币图表的方式一致。

金额的历史记录

• 如果您希望显示过去转账的余额，您需要访问在特定 slot 的乘数。您还可以在处理交易时保存转账的 UiAmount，以避免将来进行此计算。

向后兼容性

• 默认情况下，不支持缩放 UI 金额扩展的钱包和应用程序将通过将非缩放价格与原始金额相乘来显示活动的正确总价格。
• 然而，它们会显示非缩放价格，这可能会引起一些用户的困惑。
• 我们希望这能鼓励团队更新他们的 dapp，以兼容使用缩放 UI 金额扩展的代币，并乐于在此过程中提供支持。

各平台推荐的集成优先级

通用要求

---

钱包

---

浏览器

---

市场数据聚合器（例如：CoinGecko）

---

价格数据提供商

---

去中心化交易所（DEXes）