Solana'da Scaled UI Amount uzantısını destekleme

Arka plan

Scaled UI Amount uzantısı, token ihraççılarının kullanıcının token bakiyesinin UI miktarını hesaplarken kullanılacak bir çarpan belirlemesine olanak tanır. Bu, ihraççıların rebasing token'lar oluşturmasını ve hisse bölünmeleri gibi şeyleri 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. Temel hesaplamalar ve transferler, programdaki ham miktarlar kullanılarak gerçekleşir.

Kaynaklar:

• Geliştirici dokümantasyonu
• Uzantı Rust kodu
• Amount to UI Amount Rust kodu

Özet

• Son kullanıcılar, token fiyatı, token bakiyesi ve token miktarları için mümkün olduğunca UIAmount (ham miktar * çarpan) ile etkileşime girmelidir
• dApp'ler ve servis sağlayıcılar, tüm hesaplamalar için ham miktarı ve ölçeklendirilmemiş fiyatları kullanmalı ve kullanıcılar için kenarda dönüştürmelidir
• Daha kolay entegrasyon için hem ölçekli hem de ölçeksiz miktarlar için geçmiş fiyat akışlarının sağlanması gerekir
• Doğru geçmiş veriler için geçmiş çarpan değerlerine erişilebilir olması gerekir

Terim tanımları

• Multiplier: UI Amount hesaplamaları için kullanılan statik güncellenebilir çarpan
• UIAmount: çarpan * ham miktar (diğer adıyla: ölçekli miktar)
• Raw Amount: miktar (diğer adıyla: ölçeksiz miktar)

Mevcut bakiye

Görüntüleme için mevcut miktar

• Scaled UI amount uzantısını kullanan token'lar için son kullanıcılara miktarları görüntülediğinizde şunlardan birini kullanmalısınız:
  • UIAmount/UIAmountString (tercih edilen)
  • Ham miktar * çarpan'ın manuel hesaplaması
  • Bu değeri, token'ın sahip olduğu ondalık sayısına göre kısaltmanızı öneririz.
    • Örnek: yUSD 6 ondalığa sahipse ve bir kullanıcının UIAmount değeri 1.123456789 ise "1.123456" görüntülemelisiniz

Bu verileri nereden alabilirsiniz:

• Bir kullanıcının canlı bakiyesi için yukarıdaki miktarlarla ilgili güncel bilgileri getTokenAccountBalance veya getAccountInfo çağrısı yaparak alabilirsiniz
• Rastgele bir miktar için UI Amount değerini 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 bir bakiyeye sahip ücret ödeyiciye ihtiyaç duyduğu anlamına gelir. Bu nedenle, bakiye almanın varsayılan yolu bu olmamalıdır.

RPC çağrıları

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

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

$ 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
}

Mevcut miktarı güncelleme

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

İşlemlerdeki token miktarları (transferler / takaslar vb.)

• Kullanıcılar ölçeklendirilmiş “UIAmount” olarak yorumlanacak miktarları girmelidir. Bunu işlemesi gereken 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ı bakiyesinin “tamamı” veya “hepsi” ile bir işlem yapmak istediğinde toplam ham miktarı kullanmalıdır. Bu, geriye kalan toz miktarı kalmamasını sağlar.
  • İsteğe bağlı: “Tamamı” kullanıldığında kullanıcıya depolama depozitosunu iade etmek için hesabı otomatik olarak kapatmayı düşünebilirsiniz

Token fiyatı

• Token fiyatı, mümkün olan her yerde her zaman ölçeklendirilmiş fiyat olarak gösterilmelidir.
• Bir oracle gibi fiyat akışı hizmeti sağlayıcısıysanız, hem ölçeklendirilmiş hem de ölçeklendirilmemiş 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.

Mevcut çarpan

• Mevcut çarpan, getAccountInfo çağrılarak herhangi bir zamanda token mint'inden okunabilir. Ayrıca, gelecekteki bir çarpan ayarlanmışsa, bu bilgi de token mint'inden edinilebilir. Bu çarpanı göstermemenizi öneririz çünkü kullanıcı deneyimini karıştırabilir.

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 akışı 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çeklendirilmemiş fiyatları depolamalı 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ünmeleri olan tokenlerle ilgili grafikleri nasıl ele aldığıyla uyumludur.
• Çarpan güncellemeleri geçmişte olan bir zaman damgası içerebilir. Geçmiş veriler için blok zaman damgasını kullanmanızı öneririz.
• Aktif çarpanın, mevcut zaman damgasına ve yeni çarpanın ne zaman aktif olacağına bağlı olarak "multiplier" veya "newMultiplier" olabileceğini unutmayın.

Miktarlar için geçmiş veriler

• Geçmişte transfer edilen bakiyeyi göstermek istiyorsanız, o belirli slot'taki çarpana erişiminiz olması gerekir. Ayrıca, gelecekte bu hesaplamayı yapmaktan kaçınmak için işlemleri işlerken transferler için UiAmount'u kaydedebilirsiniz.

Geriye dönük uyumluluk

• Varsayılan olarak, ölçeklendirilmiş kullanıcı arayüzü miktarı uzantısını anlamayan cüzdanlar ve uygulamalar, ölçeklenmemiş fiyat * ham miktar çarpımı yaparak bir aktivitenin doğru toplam fiyatını gösterecektir.
• Ancak, ölçeklenmemiş fiyatı göstereceklerdir ve bu da bazı kullanıcı karışıklıklarına neden olacaktır.
• Ekiplerin dapp'lerini ölçeklendirilmiş kullanıcı arayüzü miktarı uzantısını kullanan tokenlerle uyumlu olacak şekilde güncellemelerini teşvik etmeyi umuyoruz ve bu süreçte destek sağlamaktan mutluluk 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

CEX'ler