Mendukung ekstensi scaled UI amount di Solana

Latar belakang

Ekstensi scaled UI amount memungkinkan penerbit token untuk menentukan pengali yang akan digunakan saat menghitung UI amount dari saldo token pengguna. Ini memungkinkan penerbit untuk membuat token rebasing dan mengaktifkan hal-hal seperti pemecahan saham. Ekstensi ini, seperti ekstensi token interest bearing, menyediakan UI amount yang murni kosmetik yang berarti tim perlu melakukan beberapa pekerjaan tambahan untuk memberikan pengalaman yang baik. Kalkulasi dan transfer yang mendasari semuanya terjadi menggunakan jumlah mentah dalam program.

Sumber daya:

• Dokumentasi developer
• Kode Rust ekstensi
• Kode Rust amount to UI amount

Ringkasan

• Pengguna akhir harus berinteraksi dengan UIAmount (jumlah mentah * pengali) untuk harga token, saldo token, dan jumlah token sedapat mungkin
• dApp dan penyedia layanan harus menggunakan jumlah mentah dan harga non-scaled untuk semua kalkulasi dan mengonversi untuk pengguna di edge
• 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

• Multiplier: pengali statis yang dapat diperbarui yang digunakan untuk kalkulasi UI amount
• UIAmount: pengali * jumlah mentah (alias: scaled amount)
• Raw amount: jumlah (alias: non-scaled amount)

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 (direkomendasikan)
  • Kalkulasi manual dari jumlah mentah * pengali
  • Kami merekomendasikan 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”

Di mana mendapatkan data ini:

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

Panggilan RPC

• getTokenAccountBalance
  • Mengembalikan saldo token account dan informasi 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
  • Mengembalikan informasi akun dan informasi 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
}

Memperbarui jumlah saat ini

Karena penerbit dapat memperbarui multiplier kapan saja, Anda dapat mempertimbangkan untuk melakukan polling secara berkala guna menjaga saldo akun tetap terbaru. Penerbit tidak mungkin memperbarui multiplier ini lebih dari sekali per hari. Jika multiplier ditetapkan untuk tanggal mendatang, 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 mengonversi 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.

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 "max" atau "all" dari saldo mereka. Ini memastikan bahwa tidak ada sisa kecil yang tertinggal.
  • Opsional: Anda dapat mempertimbangkan untuk secara otomatis menutup akun ketika "max" digunakan untuk mengembalikan deposit penyimpanan pengguna

Harga token

• Harga token harus selalu ditampilkan sebagai harga berskala sedapat mungkin.
• Jika Anda adalah penyedia layanan umpan harga, seperti oracle, Anda harus menyediakan harga berskala dan non-berskala.
  • Sedapat mungkin sediakan SDK/API yang mengabstraksi kompleksitas ekstensi jumlah UI berskala.

Pengali saat ini

• Pengali saat ini dapat dibaca dari token mint kapan saja dengan memanggil getAccountInfo. Selain itu, jika pengali masa depan ditetapkan, informasi ini juga tersedia dari token mint. Kami merekomendasikan 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 umpan harga

• Layanan yang menyediakan data historis harus menyimpan dan menampilkan harga berskala dan non-berskala untuk ekstensi jumlah UI berskala.
• Kami mengharapkan jumlah berskala akan digunakan paling sering karena ini sejalan dengan cara dunia keuangan tradisional memperlakukan grafik yang terkait dengan token dengan pemecahan saham.
• Pembaruan pengali mungkin mencakup stempel waktu yang ada di masa lalu. Kami merekomendasikan menggunakan stempel waktu blok untuk data historis.
• Perhatikan bahwa pengali aktif mungkin adalah "multiplier" atau "newMultiplier" tergantung pada stempel waktu saat ini dan kapan pengali baru ditetapkan untuk aktif.

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 mendatang.

Kompatibilitas mundur

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

Prioritas integrasi yang direkomendasikan per platform

Persyaratan umum

Dompet

Explorer

Agregator Data Pasar (Contoh: CoinGecko, Birdeye)

Penyedia umpan harga

DEX

CEX