Panduan Integrasi Jumlah UI Berskala

Mendukung Ekstensi Jumlah UI Berskala di Solana

Latar Belakang

Ekstensi Scaled UI Amount memungkinkan penerbit token untuk menentukan pengali yang akan digunakan saat menghitung jumlah UI dari saldo token pengguna. Ini memungkinkan penerbit untuk membuat token rebasing dan memungkinkan hal-hal seperti pemecahan saham. Ekstensi ini, seperti ekstensi token penghasil bunga, menyediakan jumlah UI yang murni kosmetik yang berarti tim perlu melakukan beberapa pekerjaan tambahan untuk memberikan pengalaman yang baik. Perhitungan dan transfer yang mendasarinya semua terjadi menggunakan jumlah mentah dalam program.

Sumber Daya:

TL;DR

  • Pengguna akhir harus berinteraksi dengan UIAmount (jumlah mentah * pengali) untuk harga token, saldo token, dan jumlah token kapanpun memungkinkan
  • dApps dan penyedia layanan harus menggunakan jumlah mentah dan harga non-scaled untuk semua perhitungan dan mengkonversi untuk pengguna di ujungnya
  • Feed harga historis perlu disediakan untuk jumlah scaled dan non-scaled untuk integrasi yang lebih mudah
  • Nilai pengali historis perlu dapat diakses untuk data historis yang akurat

Definisi Istilah

  • Pengali: pengali yang dapat diperbarui statis yang digunakan untuk perhitungan UI Amount
  • UIAmount: pengali * jumlah mentah (juga dikenal sebagai: jumlah scaled)
  • Raw Amount: jumlah (juga dikenal sebagai: jumlah non-scaled)

Saldo Saat Ini

Jumlah Saat Ini untuk Tampilan

  • Setiap kali Anda menampilkan jumlah untuk token yang menggunakan ekstensi scaled UI amount kepada pengguna akhir, Anda harus menggunakan salah satu:
    • UIAmount/UIAmountString (diutamakan)
    • Perhitungan manual dari jumlah mentah * pengali
    • Kami merekomendasikan untuk memotong nilai ini berdasarkan jumlah desimal yang dimiliki token.
      • Contoh: jika yUSD memiliki 6 desimal dan pengguna memiliki UIAmount 1.123456789, Anda harus menampilkan "1.123456"

Dimana mendapatkan data ini:

  • Untuk saldo pengguna yang aktif, Anda bisa mendapatkan informasi terbaru tentang jumlah di atas dengan memanggil getTokenAccountBalance atau getAccountInfo
  • Jika Anda perlu mengetahui UI Amount untuk jumlah tertentu, Anda bisa mendapatkan perhitungan ini dengan memanggil fungsi amountToUiAmountForMintWithoutSimulation (web3.js v1) atau mensimulasikan transaksi menggunakan amountToUiAmount.
    • Catatan: amountToUiAmount memerlukan simulasi transaksi yang berarti juga membutuhkan pembayar biaya yang valid dengan saldo. Karena ini, ini seharusnya tidak menjadi cara default untuk mendapatkan saldo.

Panggilan RPC

  • getTokenAccountBalance
    • Mengembalikan saldo token account dan info 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
    • Mengembalikan info akun dan info 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"
}
} */

Memperbarui Jumlah Saat Ini

Karena Penerbit dapat memperbarui pengali kapan saja, Anda dapat mempertimbangkan untuk melakukan polling secara berkala untuk menjaga saldo akun tetap diperbarui. Penerbit kemungkinan tidak akan memperbarui pengali ini lebih dari sekali per hari. Jika pengali diatur untuk tanggal di masa depan, Anda dapat secara otomatis melakukan polling pada waktu pembaruan ini

Jumlah Token dalam Transaksi (transfer / swap dll)

  • Pengguna harus memasukkan jumlah yang akan diinterpretasikan sebagai "UIAmount" yang diskalakan. Aplikasi yang harus memproses ini harus mengkonversi ke jumlah token mentah untuk transaksi.
    • Jika ada masalah pembulatan, bulatkan ke bawah dan lebih baik menyisakan sedikit dust daripada berisiko transaksi gagal
    • Untuk melakukan konversi ini Anda dapat menggunakan fungsi uiAmountToAmountForMintWithoutSimulation (web3.js v1) atau mensimulasikan transaksi menggunakan amountToUiAmount.
web3js-uiAmountToAmountForMintWithoutSimulation.ts
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 */
  • Aplikasi harus menggunakan jumlah mentah total ketika pengguna meminta untuk melakukan tindakan dengan "maksimum" atau "semua" saldo mereka. Ini memastikan tidak ada dust yang tersisa.
    • Opsional: Anda dapat mempertimbangkan untuk secara otomatis menutup akun ketika "maksimum" digunakan untuk mengembalikan deposit penyimpanan kepada pengguna

Harga Token

  • Harga token harus selalu ditampilkan sebagai harga yang diskalakan bila memungkinkan.
  • Jika Anda adalah penyedia layanan feed harga, seperti oracle, Anda harus menampilkan baik harga yang diskalakan maupun yang tidak diskalakan.
    • Bila memungkinkan, sediakan SDK/API yang mengabstraksikan kompleksitas ekstensi UI amount yang diskalakan.

Pengali Saat Ini

  • Pengali saat ini dapat dibaca dari token mint kapan saja dengan memanggil getAccountInfo. Selain itu, jika pengali masa depan telah ditetapkan, informasi ini juga tersedia dari token mint. Kami menyarankan untuk tidak menampilkan pengali ini karena dapat membingungkan UX.
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
*/

Data Historis

Data Historis untuk Price Feed

  • Layanan yang menyediakan data historis harus menyimpan dan menampilkan baik harga yang diskalakan maupun yang tidak diskalakan untuk ekstensi jumlah UI yang diskalakan.
  • Kami mengharapkan jumlah yang diskalakan akan digunakan paling sering karena ini selaras dengan bagaimana dunia keuangan tradisional memperlakukan grafik terkait token dengan stock splits.

Data Historis untuk Jumlah

  • Jika Anda ingin menampilkan saldo yang ditransfer di masa lalu, Anda memerlukan akses ke pengali pada slot tertentu tersebut. Anda juga dapat menyimpan UiAmount untuk transfer saat Anda memproses transaksi untuk menghindari melakukan perhitungan ini di masa depan.

Kompatibilitas Mundur

  • Secara default, dompet dan aplikasi yang tidak memahami ekstensi jumlah UI yang diskalakan akan menampilkan total harga yang benar dari suatu aktivitas dengan mengalikan harga yang tidak diskalakan * jumlah mentah.
  • Namun, mereka akan menampilkan harga yang tidak diskalakan yang menyebabkan kebingungan pengguna.
  • Kami berharap ini mendorong tim untuk memperbarui dapp mereka agar kompatibel dengan token yang menggunakan ekstensi jumlah UI yang diskalakan dan kami senang memberikan dukungan selama proses ini.

Prioritas Integrasi yang Direkomendasikan Per Platform

Persyaratan Umum

PersyaratanDeskripsiPrioritas
Mendukung Tindakan Pengguna Menggunakan UiAmountSemua tindakan pengguna harus dimasukkan dalam UiAmount ketika UiAmount diaktifkan di seluruh aplikasi. Jika UiAmount tidak terlihat di aplikasi, mereka harus menggunakan jumlah mentah sampai aplikasi diperbarui.P0

Dompet

PersyaratanDeskripsiPrioritas
Tampilkan Saldo TerskalaTampilkan jumlah terskala (uiAmount) sebagai saldo utama.P0
Dukungan untuk Transfer TokenPengguna akhir harus memasukkan jumlah transfer dengan saldo terskala mereka (jumlah mentah * saldo).P0
Tampilkan Harga SpotTampilkan harga spot terskala untuk penggunaP0
Metadata Riwayat TransaksiTampilkan jumlah terskala (UIAmount) untuk setiap transfer bila memungkinkan.P1
Tampilkan Pembaruan Pengali di Riwayat TransaksiKetika pembaruan pengali terjadi, tampilkan ini sebagai peristiwa dalam riwayat transaksi pengguna termasuk jumlah yang diperolehP2
Tampilkan Grafik Riwayat HargaMencerminkan harga terskala dalam grafik hargaP1
Pengenalan/TooltipTawarkan tooltip atau pengenalan untuk mengedukasi pengguna tentang token yang menggunakan ekstensi jumlah ui terskalaP2

Explorer

PersyaratanDeskripsiPrioritas
Peningkatan Halaman Detail TokenTampilkan metadata seperti kapitalisasi pasar terskala total dan pengali saat iniP0
Tampilkan Saldo Terskala untuk SaldoTampilkan saldo terskala (UiAmount) untuk saldo saat ini.P0
Tampilkan Saldo Terskala untuk TransaksiTampilkan saldo terskala (UiAmount) untuk jumlah transfer pada transaksi historis.P0
Tampilkan Harga Terskala untuk TransaksiTampilkan harga terskala untuk transaksi sebelumnyaP1
Parsing dan Tampilkan Transaksi Pembaruan Pengali dengan BenarTampilkan detail tentang pembaruan pengali dengan benarP2

Agregator Data Pasar (Contoh: CoinGecko)

PersyaratanDeskripsiPrioritas
Pembaruan API untuk Data TerskalaMemperluas fungsionalitas API untuk menyertakan perubahan pengali dari waktu ke waktu serta umpan harga terskala.P0
Total Suplai Dengan Penyesuaian TerskalaSaat menampilkan total suplai dan total kapitalisasi pasar, perhitungkan saldo terskalaP0
Pelacakan Harga HistorisMenyediakan grafik historis harga menggunakan harga terskala dari waktu ke waktu.P1
Pelacakan Pengali HistorisMenyediakan penanda historis pembaruan pengali untuk token yang menghasilkan bunga.P2
Konten Edukasi atau PenjelasanMenyertakan deskripsi singkat atau tooltip yang menjelaskan cara kerja token terskala.P2

Penyedia Umpan Harga

PersyaratanDeskripsiPrioritas
Umpan Harga Terskala & Non-terskalaMenyediakan umpan harga untuk harga terskala dan non-terskala.P0
Data Pengali HistorisMenawarkan API dengan perubahan pengali historis.P0
Data Harga HistorisMenawarkan API dengan harga historis berdasarkan jumlah terskala dan non-terskala.P0

DEX

PersyaratanDeskripsiPrioritas
Tampilkan Saldo Token RebaseMenampilkan saldo terskala untuk perdagangan atau penyediaan likuiditas di UI. (backend tetap dapat menggunakan jumlah mentah)P0
Dukungan untuk Tindakan TokenPengguna akhir harus memasukkan jumlah tindakan dengan saldo UiAmount mereka (pengali * jumlah mentah).P0
Adaptasi Umpan HargaDi mana pun umpan harga digunakan untuk menampilkan harga saat ini, berikan harga terskala kepada pengguna akhir.P1
Tampilkan Grafik Riwayat HargaMencerminkan harga terskala dalam grafik hargaP1

Is this page helpful?