Solana'da Ölçeklendirilmiş UI Miktarı Uzantısını Destekleme

Arka Plan

Ölçeklendirilmiş UI Miktarı uzantısı, token ihraççılarının bir kullanıcının token bakiyesinin UI miktarını hesaplarken kullanılacak bir çarpan belirlemelerine olanak tanır. Bu, ihraççıların yeniden tabanlı tokenler oluşturmasını ve hisse bölünmeleri gibi işlemleri etkinleştirmesini sağlar. Bu uzantı, faiz getiren token uzantısı gibi, tamamen kozmetik bir UI miktarı sağlar, bu da ekiplerin iyi bir deneyim sunmak için bazı ek çalışmalar yapması gerektiği anlamına gelir. Altta yatan hesaplamalar ve transferlerin tümü, programdaki ham miktarlar kullanılarak gerçekleşir.

Kaynaklar:

• Geliştirici Belgeleri
• Uzantı Rust Kodu
• Miktar - UI Miktarı Rust Kodu

Özet

• Son kullanıcılar mümkün olduğunca token fiyatı, token bakiyesi ve token miktarları için UIAmount (ham miktar * çarpan) ile etkileşimde bulunmalıdır
• dApp'ler ve servis sağlayıcıları tüm hesaplamalar için ham miktarı ve ölçeklenmemiş fiyatları kullanmalı ve kullanıcılar için son aşamada dönüştürmelidir
• Daha kolay entegrasyon için hem ölçeklendirilmiş hem de ölçeklenmemiş miktarlar için geçmiş fiyat verileri sağlanmalıdır
• Doğru geçmiş veriler için geçmiş çarpan değerlerine erişilebilir olmalıdır

Terim Tanımları

• Çarpan: UI Miktarı hesaplamaları için kullanılan statik güncellenebilir çarpan
• UIAmount: çarpan * ham miktar (diğer adıyla: ölçeklendirilmiş miktar)
• Ham Miktar: miktar (diğer adıyla: ölçeklenmemiş miktar)

Mevcut Bakiye

Görüntüleme için Mevcut Miktar

• Ölçeklendirilmiş UI miktarı uzantısını kullanan tokenlerin miktarlarını son kullanıcılara gösterdiğiniz her zaman şunlardan birini kullanmalısınız:
  • UIAmount/UIAmountString (tercih edilen)
  • Ham miktar * çarpan şeklinde manuel bir hesaplama
  • Bu değeri tokenin sahip olduğu ondalık sayısına göre kırpmanızı öneririz.
    • Örnek: eğer yUSD 6 ondalık basamağa sahipse ve bir kullanıcının UIAmount değeri 1.123456789 ise "1.123456" şeklinde göstermelisiniz

Bu verileri nereden alabilirsiniz:

• Bir kullanıcının canlı bakiyesi için yukarıdaki miktarlar hakkında güncel bilgileri getTokenAccountBalance veya getAccountInfo çağrısı yaparak alabilirsiniz
• Herhangi bir miktar için UI Miktarını bilmeniz gerekiyorsa, bu hesaplamayı amountToUiAmountForMintWithoutSimulation (web3.js v1) fonksiyonunu çağırarak veya amountToUiAmount kullanarak bir işlem simülasyonu yaparak elde edebilirsiniz.
  • Not: amountToUiAmount bir işlem simülasyonu gerektirir, bu da geçerli ve bakiyesi olan bir ücret ödeyicisi gerektirir. Bu nedenle, bakiye almak için varsayılan yöntem olmamalıdır.

RPC Çağrıları

• getTokenAccountBalance
  • Token account bakiyesini ve mint bilgisini döndürür

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
  • Hesap bilgisini ve mint bilgisini döndürür

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

Mevcut Miktarı Güncelleme

İhraççılar çarpanı herhangi bir zamanda güncelleyebileceğinden, hesap bakiyesini güncel tutmak için ara sıra sorgulama yapmayı düşünebilirsiniz. İhraççıların bu çarpanı günde birden fazla güncellemesi pek olası değildir. Eğer bir çarpan gelecekteki bir tarih için ayarlanmışsa, bu güncelleme zamanında otomatik olarak sorgulama yapabilirsiniz

İşlemlerdeki Token Miktarları (transferler / takaslar vb.)

• Kullanıcılar, ölçeklendirilmiş "UIAmount" olarak yorumlanacak miktarları girmelidir. Bu işlemi gerçekleştirecek uygulama, işlem için ham token miktarına dönüştürmelidir.
  • Yuvarlama sorunları varsa, aşağı yuvarlayın ve işlemin başarısız olma riskini almak yerine küçük bir miktar toz bırakmayı tercih edin
  • Bu dönüşümü yapmak için uiAmountToAmountForMintWithoutSimulation (web3.js v1) fonksiyonunu kullanabilir veya amountToUiAmount kullanarak bir işlem simülasyonu yapabilirsiniz.

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

• Uygulamalar, bir kullanıcı "maksimum" veya "tümü" bakiyesiyle bir işlem yapmak istediğinde toplam ham miktarı kullanmalıdır. Bu, hiç toz bakiye kalmamasını sağlar.
  • İsteğe bağlı: "Maksimum" kullanıldığında, kullanıcının depolama depozitosunu iade etmek için hesabı otomatik olarak kapatmayı düşünebilirsiniz

Token fiyatı

• Token fiyatı mümkün olan her yerde ölçeklendirilmiş fiyat olarak gösterilmelidir.
• Eğer oracle gibi bir fiyat besleme hizmeti sağlayıcısıysanız, hem ölçeklendirilmiş hem de ölçeklenmemiş fiyatı sunmalısınız.
  • Mümkün olan her yerde, ölçeklendirilmiş UI miktarı uzantısı karmaşıklıklarını soyutlayan bir SDK/API sağlayın.

Güncel çarpan

• Güncel çarpan, herhangi bir zamanda getAccountInfo çağrısı yapılarak token mint'inden okunabilir. Ayrıca, gelecekteki bir çarpan ayarlanmışsa, bu bilgi de token mint'inden erişilebilir. Kullanıcı deneyimini karıştırabileceği için bu çarpanı göstermemenizi öneririz.

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

Geçmiş veriler

Fiyat beslemesi için geçmiş veriler

• Geçmiş veri sağlayan hizmetler, ölçeklendirilmiş UI miktarı uzantısı için hem ölçeklendirilmiş hem de ölçeklenmemiş fiyatları saklamalı ve sunmalıdır.
• Ölçeklendirilmiş miktarların en sık kullanılmasını bekliyoruz çünkü bu, geleneksel finans dünyasının hisse bölünmesi olan tokenlerle ilgili grafikleri ele alış biçimiyle uyumludur.

Miktarlar için geçmiş veriler

• Geçmişte aktarılan bakiyeyi göstermek istiyorsanız, belirli bir slot'taki çarpana erişmeniz gerekir. Gelecekte bu hesaplamayı yapmaktan kaçınmak için işlemleri işlerken transferler için UiAmount'u da kaydedebilirsiniz.

Geriye Dönük Uyumluluk

• Varsayılan olarak, ölçeklendirilmiş UI miktar uzantısını anlamayan cüzdanlar ve uygulamalar, ölçeklendirilmemiş fiyat * ham miktar çarpımıyla bir aktivitenin doğru toplam fiyatını gösterecektir.
• Ancak, ölçeklendirilmemiş fiyatı gösterecekleri için bu durum kullanıcılarda kafa karışıklığına neden olabilir.
• Ekiplerin, ölçeklendirilmiş UI miktar uzantısını kullanan tokenlerle uyumlu olacak şekilde dapp'lerini güncellemelerini umuyoruz ve bu süreçte destek sağlamaktan memnuniyet duyarız.

Platform Başına Önerilen Entegrasyon Öncelikleri

Genel Gereksinimler

Cüzdanlar

Gezginler

Piyasa Veri Toplayıcıları (Örn: CoinGecko)

Fiyat Akışı Sağlayıcıları

DEX'ler