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

背景

最近推出了一种名为“缩放 UI 数量”的新代币扩展，允许代币发行方指定一个乘数，用于计算用户代币余额的 UI 数量。这使得发行方可以创建重新定价代币，并实现类似股票拆分的功能。与利息收益代币扩展类似，此扩展提供的是纯粹的视觉 UI 数量。底层计算和转账均使用程序中的原始数量进行。

资源：

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

目标

• 为终端用户提供最佳的用户体验
• 为团队提供清晰且直接的指南，以在整个生态系统中创建统一的利息收益代币体验
• 确定并规划工作，以减少团队在集成缩放 UI 数量扩展时的工作量

简要说明

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

术语定义

• 倍数：用于 UI Amount 计算的静态可更新倍数
• UIAmount：倍数 * 原始金额（又称：缩放金额）
• 原始金额：金额（又称：未缩放金额）

当前余额

用于显示的当前金额

• 每当向终端用户显示使用缩放 UI Amount 扩展的代币金额时，您应使用以下任一方式：
  • UIAmount/UIAmountString（推荐）
  • 手动计算原始金额 * 倍数
  • 我们建议根据代币的小数位数截断此值。
    • 示例：如果 yUSD 有 6 位小数，且用户的 UIAmount 为 1.123456789，您应显示“1.123456”

从哪里获取这些数据：

• 对于用户的实时余额，您可以通过调用 getTokenAccountBalance 或 getAccountInfo 获取上述金额的更新信息
• 如果您需要知道任意金额的 UI Amount，可以通过调用 amountToUiAmountForMintWithoutSimulation （web3.js v1）函数或使用 amountToUiAmount 模拟交易来获取此计算。
  • 注意：amountToUiAmount 需要进行交易模拟，这意味着它还需要一个有余额的有效费用支付者。因此，这不应作为获取余额的默认方式。

更新当前金额

由于发行方可以随时更新倍数，您可以考虑偶尔轮询以保持账户余额的更新。发行方不太可能每天更新此倍数超过一次。如果为未来日期设置了倍数，您可以在此更新时间自动轮询。

交易中的代币金额（转账/兑换等）

• 用户应输入被解释为缩放后的“UIAmount”的金额。需要处理这些金额的应用程序应将其转换为交易所需的原始代币金额。
  • 如果存在舍入问题，应向下舍入，宁可留下少量的尘埃（dust），也不要冒交易失败的风险。
  • 要进行此转换，可以使用 uiAmountToAmountForMintWithoutSimulation （web3.js v1）函数，或者通过使用 amountToUiAmount 模拟交易。
• 当用户请求使用“最大”或“全部”余额进行操作时，应用程序应使用总的原始金额。这可以确保不会留下任何尘埃。
  • 可选：您可以考虑在使用“最大”时自动关闭账户，以退还用户的存储押金。

代币价格

• 代币价格应尽可能以缩放后的价格显示。
• 如果您是价格数据提供服务商，例如预言机，您应同时提供缩放后的价格和未缩放的价格。
  • 在可能的情况下，提供一个 SDK/API，以抽象掉缩放后的 UI 金额扩展的复杂性。

当前乘数

• 当前乘数可以随时通过调用 getAccountInfo 从代币铸造中读取。此外，如果设置了未来的乘数，该信息也可以从代币铸造中获取。我们建议不要显示此乘数，因为这可能会混淆用户体验（UX）。

历史数据

价格数据的历史记录

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

金额的历史数据

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

向后兼容性

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

添加到 SPL-Token 库的实用函数：

• [已完成] Amount 转换为 UIAmount：提供一个函数，根据当前时间、铸币和原始金额获取 UIAmount
• [已完成] UIAmount 转换为 Amount：提供一个函数，根据当前时间、铸币和 UIAmount 获取原始金额
• [已完成] Amount 转换为特定的 UIAmount：提供一个函数，根据给定的乘数、小数位和原始金额获取 UIAmount
• [已完成] UIAmount 转换为 Amount：提供一个函数，根据给定的乘数、小数位和 UIAmount 获取原始金额
• [待办] 为 @solana/kit 提供上述所有辅助功能

各平台的验收标准

通用要求

---

钱包

---

浏览器

---

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

---

价格数据提供商

---

去中心化交易所（DEXes）