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

Giới thiệu

Tiện ích mở rộng Scaled UI Amount cho phép người phát hành token chỉ định một bộ nhân để 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ỹ, điều này có nghĩa là các nhóm cần thực hiện một số công việc bổ sung để cung cấp 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ộ nhân) cho giá token, số dư token và số lượng token bất cứ khi nào có thể
• 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 tỷ lệ 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 tỷ lệ và chưa điều chỉnh tỷ lệ để tích hợp dễ dàng hơn
• Giá trị bộ nhân lịch sử cần phải có sẵn để lấy dữ liệu lịch sử chính xác

Định nghĩa thuật ngữ

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

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ộ nhân
  • 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 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ố tiền hiện tại

Vì người phát hành có thể cập nhật hệ số nhân bất kỳ lúc nào, bạn có thể cân nhắc việc thăm dò định kỳ để cập nhật số dư tài khoản. Người phát hành ít khi 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ố tiền được hiểu là "UIAmount" đã được điều chỉnh. Ứng dụng xử lý việc 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ỏ hơn là 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 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 lại số dư nhỏ.
  • Tùy chọn: Bạn có thể xem xét tự động đóng tài khoản khi "tối đa" được sử dụng để 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ệ khi 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ệ.
  • Khi 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 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á đã điều chỉnh tỷ lệ và chưa điều chỉnh tỷ lệ cho tiện ích 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 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ý các biểu đồ liên quan đến token với phân chia 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 đã 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 tính toán lại 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 đã được điều chỉnh 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á không được điều chỉnh * số lượng thô.
• Tuy nhiên, chúng sẽ hiển thị giá không được điều chỉnh 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 dapps của họ để tương thích với các token sử dụng phần mở rộng số lượng UI đã được điều chỉnh và chúng tôi sẵn sàng hỗ trợ trong quá trình này.

Ưu tiên tích hợp được khuyến nghị cho từng 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 cấp giá

DEXes