Hỗ trợ tiện ích mở rộng Scaled UI Amount trên Solana

Bối cảnh

Tiện ích mở rộng Scaled UI Amount cho phép các nhà phát hành token chỉ định một hệ số nhân để sử dụng khi tính toán UI amount của số dư token người dùng. Điều này cho phép các nhà phát hành tạo ra các token rebasing và kích hoạt những thứ như chia tách cổ phiếu. Tiện ích mở rộng này, giống như tiện ích mở rộng token sinh lãi, cung cấp một UI amount hoàn toàn mang tính thẩm mỹ, có nghĩa là các nhóm cần thực hiện một số công việc bổ sung để mang lại trải nghiệm tốt. Các phép tính và chuyển khoản cơ bản đều xảy ra bằng cách sử dụng các raw amount trong chương trình.

Tài nguyên:

• Tài liệu dành cho nhà phát triển
• Mã Rust của tiện ích mở rộng
• Mã Rust chuyển đổi Amount sang UI Amount

Tóm tắt

• Người dùng cuối nên tương tác với UIAmount (raw amount * hệ số nhân) cho giá token, số dư token và số lượng token bất cứ khi nào có thể
• Các dApp và nhà cung cấp dịch vụ nên sử dụng raw amount và giá không được scale cho tất cả các phép tính và chuyển đổi cho người dùng ở tầng giao diện
• Nguồn cấp dữ liệu giá lịch sử cần được cung cấp cho cả số lượng scaled và non-scaled để tích hợp dễ dàng hơn
• Các giá trị hệ số nhân lịch sử cần có thể truy cập được để có dữ liệu lịch sử chính xác

Định nghĩa thuật ngữ

• Multiplier: hệ số nhân tĩnh có thể cập nhật được sử dụng cho các phép tính UI Amount
• UIAmount: multiplier * raw amount (còn gọi là: scaled amount)
• Raw Amount: amount (còn gọi là: non-scaled amount)

Số dư hiện tại

Số lượng hiện tại để hiển thị

• Bất cứ khi nào bạn hiển thị số lượng cho các token sử dụng tiện ích mở rộng scaled UI amount cho người dùng cuối, bạn nên sử dụng một trong hai:
  • UIAmount/UIAmountString (được khuyến nghị)
  • Tính toán thủ công raw amount * multiplier
  • Chúng tôi khuyến nghị cắt bớt giá trị này dựa trên số chữ số thập phân mà token có.
    • Ví dụ: nếu yUSD có 6 chữ số thập phân và người dùng có UIAmount là 1.123456789, bạn nên hiển thị "1.123456"

Nơi lấy dữ liệu này:

• Để biết số dư trực tiếp của người dùng, bạn có thể lấy thông tin cập nhật về các số tiền trên bằng cách gọi getTokenAccountBalance hoặc getAccountInfo
• Nếu bạn cần biết UI Amount cho một số tiền bất kỳ, bạn có thể thực hiện phép tính này bằng cách gọi hàm amountToUiAmountForMintWithoutSimulation (web3.js v1) hoặc mô phỏng giao dịch sử dụng amountToUiAmount.
  • Lưu ý: amountToUiAmount yêu cầu mô phỏng giao dịch, điều này có nghĩa là nó cũng cần một fee payer hợp lệ có số dư. Vì lý do này, đây không nên là cách mặc định để lấy số dư.

Lệnh gọi RPC

• getTokenAccountBalance
  • Trả về số dư token account và thông tin 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
  • Trả về thông tin account và thông tin 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
}

Cập nhật số tiền hiện tại

Vì các nhà phát hành có thể cập nhật hệ số nhân bất cứ lúc nào, bạn có thể cân nhắc thực hiện polling định kỳ để giữ số dư account được cập nhật. Các nhà phát hành không có khả năng cập nhật hệ số nhân này nhiều hơn một lần mỗi ngày. Nếu hệ số nhân được đặt cho một ngày trong tương lai, bạn có thể tự động polling vào thời điểm cập nhật này

Số lượng token trong giao dịch (chuyển khoản / hoán đổi, v.v.)

• Người dùng nên nhập số tiền được hiểu là "UIAmount" đã được điều chỉnh. Ứng dụng phải xử lý điều này nên chuyển đổi sang số lượng token thô cho giao dịch.
  • Nếu có vấn đề làm tròn, hãy làm tròn xuống và ưu tiên để lại một lượng nhỏ thay vì rủi ro giao dịch thất bại
  • Để thực hiện chuyển đổi này, bạn có thể sử dụng hàm uiAmountToAmountForMintWithoutSimulation (web3.js v1) hoặc mô phỏng giao dịch sử dụng 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 */

• Các ứng dụng nên sử dụng tổng số lượng thô khi người dùng yêu cầu thực hiện hành động với “max” hoặc “all” số dư của họ. Điều này đảm bảo không còn lại số dư nhỏ.
  • Tùy chọn: Bạn có thể cân nhắc tự động đóng tài khoản khi sử dụng “max” để hoàn lại cho người dùng khoản tiền gửi lưu trữ của họ

Giá token

• Giá token nên luôn được hiển thị dưới dạng giá đã điều chỉnh bất cứ khi nào có thể.
• Nếu bạn là nhà cung cấp dịch vụ nguồn cấp giá, chẳng hạn như oracle, bạn nên cung cấp cả giá đã điều chỉnh và chưa điều chỉnh.
  • Bất cứ khi nào có thể, hãy cung cấp SDK/API trừu tượng hóa các phức tạp của tiện ích mở rộng số lượng UI đã điều chỉnh.

Hệ số nhân hiện tại

• Hệ số nhân hiện tại có thể được đọc từ token mint bất cứ lúc nào bằng cách gọi getAccountInfo. Ngoài ra, nếu hệ số nhân tương lai được thiết lập, thông tin này cũng có sẵn từ token mint. Chúng tôi khuyến nghị không hiển thị hệ số nhân này vì nó có thể gây nhầm lẫn cho trải nghiệm người dùng.

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
*/

Dữ liệu lịch sử

Dữ liệu lịch sử cho nguồn cấp giá

• Các dịch vụ cung cấp dữ liệu lịch sử nên lưu trữ và hiển thị cả giá đã điều chỉnh và chưa điều chỉnh cho tiện ích mở rộng số lượng UI đã điều chỉnh.
• Chúng tôi kỳ vọng số lượng đã điều chỉnh sẽ được sử dụng thường xuyên nhất vì điều này phù hợp với cách thế giới tài chính truyền thống xử lý biểu đồ liên quan đến token có chia tách cổ phiếu.
• Cập nhật hệ số nhân có thể bao gồm dấu thời gian trong quá khứ. Chúng tôi khuyến nghị sử dụng dấu thời gian khối cho dữ liệu lịch sử.
• Lưu ý rằng hệ số nhân đang hoạt động có thể là "multiplier" hoặc "newMultiplier" tùy thuộc vào dấu thời gian hiện tại và khi nào hệ số nhân mới được thiết lập để hoạt động.

Dữ liệu lịch sử cho số lượng

• Nếu bạn muốn hiển thị số dư đã chuyển trong quá khứ, bạn cần truy cập vào hệ số nhân tại slot đã cho đó. Bạn cũng có thể lưu UiAmount cho các giao dịch chuyển khi xử lý giao dịch để tránh phải thực hiện phép tính này trong tương lai.

Khả năng tương thích ngược

• Theo mặc định, các ví và ứng dụng không hiểu tiện ích mở rộng số lượng UI đã điều chỉnh tỷ lệ sẽ hiển thị tổng giá chính xác của một hoạt động bằng cách nhân giá chưa điều chỉnh tỷ lệ * số lượng thô.
• Tuy nhiên, chúng sẽ hiển thị giá chưa điều chỉnh tỷ lệ gây ra một số nhầm lẫn cho người dùng.
• Chúng tôi hy vọng điều này khuyến khích các nhóm cập nhật dapp của họ để tương thích với các token sử dụng tiện ích mở rộng số lượng UI đã điều chỉnh tỷ lệ và sẵn sàng cung cấp hỗ trợ trong quá trình này.

Ưu tiên tích hợp được đề xuất theo từng nền tảng

Yêu cầu chung

Ví

Trình khám phá

Tổng hợp dữ liệu thị trường (Ví dụ: CoinGecko, Birdeye)

Nhà cung cấp nguồn cấp giá

Sàn giao dịch phi tập trung (DEX)

Sàn giao dịch tập trung (CEX)