Hỗ trợ tiện ích mở rộng Số lượng UI được chia tỷ lệ trên Solana

Bối cảnh

Tiện ích mở rộng Scaled UI Amount cho phép người phát hành token chỉ định một bội số để sử dụng khi tính toán số lượng UI của số dư token của người dùng. Điều này cho phép người phát hành tạo ra các token tái cơ sở 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 số lượng UI thuần túy 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 để tạo trải nghiệm tốt. Các tính toán và chuyển khoản cơ bản đều diễn ra bằng cách sử dụng số lượng thô 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 số lượng sang số lượng UI

Tóm tắt

• Người dùng cuối nên tương tác với UIAmount (số lượng thô * bội số) cho giá token, số dư token và số lượng token bất cứ khi nào có thể
• Các ứng dụng phi tập trung (dApps) và nhà cung cấp dịch vụ nên sử dụng số lượng thô và giá không được điều chỉnh cho tất cả các tính toán và chuyển đổi cho người dùng ở giai đoạn cuối
• Nguồn cấp dữ liệu giá lịch sử cần được cung cấp cho cả số lượng đã điều chỉnh và chưa điều chỉnh để tích hợp dễ dàng hơn
• Các giá trị bội số lịch sử cần phải có thể truy cập được để có dữ liệu lịch sử chính xác

Định nghĩa thuật ngữ

• Bội số: bội số có thể cập nhật tĩnh được sử dụng cho các tính toán UI Amount
• UIAmount: bội số * số lượng thô (còn gọi là: số lượng đã điều chỉnh)
• Số lượng thô: số lượng (còn gọi là: số lượng chưa điều chỉnh)

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 các cách sau:
  • UIAmount/UIAmountString (ưu tiên)
  • Tính toán thủ công số lượng thô * bội số
  • Chúng tôi khuyên bạn nên cắt bớt giá trị này dựa trên 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 người trả phí 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ư.

Các lệnh gọi RPC

• getTokenAccountBalance
  • Trả về số dư token account và thông tin mint

import { address, createSolanaRpc } from "@solana/kit";
const rpc_url = "https://api.devnet.solana.com";
const rpc = createSolanaRpc(rpc_url);

let tokenAddress = address("2uuvxpnEKw52aTqNerHiQ3WeSqZriCMNVt8LhWfrkbPk");

let tokenBalance = await rpc.getTokenAccountBalance(tokenAddress).send();

console.log("Token Balance:", tokenBalance);
/* Token Balance: {
  context: { apiVersion: '2.2.14', slot: 381132711n },
  value: {
    amount: '10000000',
    decimals: 6,
    uiAmount: 20,
    uiAmountString: '20'
  }
} */

• getAccountInfo
  • Trả về thông tin tài khoản và thông tin mint

import { address, createSolanaRpc } from "@solana/kit";

const rpc_url = "https://api.devnet.solana.com";
const rpc = createSolanaRpc(rpc_url);

const publicKey = address("2uuvxpnEKw52aTqNerHiQ3WeSqZriCMNVt8LhWfrkbPk");
const accountInfo = await rpc.getAccountInfo(publicKey).send();

console.log(
  "Account Info:",
  JSON.stringify(
    accountInfo,
    (key, value) => (typeof value === "bigint" ? value.toString() : value),
    2
  )
);
/* Account Info: {
  "context": {
    "apiVersion": "2.2.14",
    "slot": "381133640"
  },
  "value": {
    "data": {
      "parsed": {
        "info": {
          "extensions": [
            {
              "extension": "immutableOwner"
            },
            {
              "extension": "pausableAccount"
            }
          ],
          "isNative": false,
          "mint": "BZCd6HfTbb5ZYJ8hQsm8282tG4QzLyeqFR6tdgQA9EAG",
          "owner": "G7ARQSUCwNrfvTDUCZvM5xdiRdBJiN3qVw2PryD8Wnib",
          "state": "initialized",
          "tokenAmount": {
            "amount": "10000000",
            "decimals": 6,
            "uiAmount": 20,
            "uiAmountString": "20"
          }
        },
        "type": "account"
      },
      "program": "spl-token-2022",
      "space": "174"
    },
    "executable": false,
    "lamports": "2101920",
    "owner": "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb",
    "rentEpoch": "18446744073709551615",
    "space": "174"
  }
} */

Cập nhật số lượng hiện tại

Vì Nhà phát hành có thể cập nhật hệ số nhân bất kỳ lúc nào, bạn nên cân nhắc việc thăm dò định kỳ để cập nhật số dư tài khoản. 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 thăm dò 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ố lượng được hiểu là "UIAmount" đã được điều chỉnh tỷ lệ. Ứng dụng xử lý điều này cần chuyển đổi thành 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ỏ dust 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 bằ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 một hành động với "tối đa" hoặc "tất cả" số dư của họ. Điều này đảm bảo không còn dust nào còn lại.
  • Tùy chọn: Bạn có thể cân nhắc tự động đóng tài khoản khi sử dụng "tối đa" để hoàn trả cho người dùng khoản tiền gửi lưu trữ của họ

Giá token

• Giá token luôn nên được hiển thị dưới dạng giá đã điều chỉnh tỷ lệ ở bất cứ nơi nào có thể.
• Nếu bạn là nhà cung cấp dịch vụ cung cấp giá, chẳng hạn như oracle, bạn nên hiển thị cả giá đã điều chỉnh tỷ lệ và chưa điều chỉnh tỷ lệ.
  • 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 UIAmount đã điều chỉnh tỷ lệ.

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 một hệ số nhân trong 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 không nên 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á đã được điều chỉnh tỷ lệ và giá chưa điều chỉnh tỷ lệ cho phần mở rộng số lượng UI đã điều chỉnh tỷ lệ.
• Chúng tôi kỳ vọng số lượng đã điều chỉnh tỷ lệ sẽ được sử dụng phổ biế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ý các biểu đồ liên quan đến token với việc chia tách cổ phiếu.

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 đó. Bạn cũng có thể lưu UiAmount cho các giao dịch chuyển khoản khi xử lý giao dịch để tránh phải thực hiện tính toán 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 phần 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 phần mở rộng số lượng UI đã điều chỉnh tỷ lệ và chúng tôi sẵn sàng cung cấp hỗ trợ trong quá trình này.

Ưu tiên tích hợp được khuyến nghị theo nền tảng

Yêu cầu chung

Ví

Trình khám phá

Nền tảng tổng hợp dữ liệu thị trường (Ví dụ: CoinGecko)

Nhà cung cấp nguồn giá

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