Obsługa rozszerzenia Scaled UI Amount na platformie Solana

Tło

Rozszerzenie Scaled UI Amount pozwala emitentom tokenów określić mnożnik, który jest używany przy obliczaniu ilości tokenów użytkownika wyświetlanej w interfejsie użytkownika. Umożliwia to emitentom tworzenie tokenów z mechanizmem rebasingu oraz realizację takich funkcji jak podziały akcji. To rozszerzenie, podobnie jak rozszerzenie tokenów oprocentowanych, zapewnia wyłącznie kosmetyczną ilość w interfejsie użytkownika, co oznacza, że zespoły muszą wykonać dodatkową pracę, aby zapewnić dobrą jakość doświadczenia użytkownika. Wszystkie obliczenia i transfery odbywają się przy użyciu surowych wartości w programie.

Zasoby:

• Dokumentacja dla deweloperów
• Kod rozszerzenia w języku Rust
• Kod Amount to UI Amount w języku Rust

TL;DR

• Użytkownicy końcowi powinni korzystać z UIAmount (surowa ilość * mnożnik) dla ceny tokena, salda tokena i ilości tokenów, gdy tylko jest to możliwe
• dAppy i dostawcy usług powinni używać surowej ilości i nieskalowanych cen do wszystkich obliczeń i konwertować je dla użytkowników na końcu
• Historyczne dane cenowe muszą być dostępne zarówno dla skalowanych, jak i nieskalowanych ilości, aby ułatwić integrację
• Historyczne wartości mnożnika muszą być dostępne dla dokładnych danych historycznych

Definicje terminów

• Mnożnik: statyczny, aktualizowalny mnożnik używany do obliczeń UI Amount
• UIAmount: mnożnik * surowa ilość (znane również jako: skalowana ilość)
• Surowa ilość: ilość (znane również jako: nieskalowana ilość)

Aktualne saldo

Aktualna ilość do wyświetlenia

• Za każdym razem, gdy wyświetlasz ilości tokenów korzystających z rozszerzenia scaled UI amount użytkownikom końcowym, powinieneś używać jednej z poniższych metod:
  • UIAmount/UIAmountString (zalecane)
  • Ręczne obliczenie surowej ilości * mnożnik
  • Zalecamy obcinanie tej wartości w oparciu o liczbę miejsc dziesiętnych, które posiada token.
    • Przykład: jeśli yUSD ma 6 miejsc dziesiętnych, a użytkownik ma UIAmount równy 1.123456789, powinieneś wyświetlić „1.123456”

Skąd wziąć te dane:

• Aby uzyskać aktualne saldo użytkownika, możesz pobrać zaktualizowane informacje o powyższych kwotach, wywołując funkcje getTokenAccountBalance lub getAccountInfo.
• Jeśli potrzebujesz znać kwotę UI dla dowolnej kwoty, możesz uzyskać to obliczenie, wywołując funkcję amountToUiAmountForMintWithoutSimulation (web3.js v1) lub symulując transakcję za pomocą amountToUiAmount.
  • Uwaga: amountToUiAmount wymaga symulacji transakcji, co oznacza, że potrzebuje również ważnego płatnika opłat z saldem. Z tego powodu nie powinno to być domyślnym sposobem uzyskiwania salda.

Wywołania RPC

• getTokenAccountBalance
  • Zwraca saldo konta tokena oraz informacje o monecie (mint info)

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
  • Zwraca informacje o koncie oraz informacje o monecie (mint info)

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

Aktualizacja bieżącej kwoty

Ponieważ emitenci mogą aktualizować mnożnik w dowolnym momencie, warto rozważyć okresowe odpytywanie w celu utrzymania aktualnego salda konta. Emitenci prawdopodobnie nie będą aktualizować tego mnożnika częściej niż raz dziennie. Jeśli mnożnik jest ustawiony na przyszłą datę, możesz automatycznie odpytywać w czasie tej aktualizacji.

Kwoty tokenów w transakcjach (przelewy / wymiany itp.)

• Użytkownicy powinni wprowadzać kwoty interpretowane jako skalowane „UIAmount”. Aplikacja, która musi to przetworzyć, powinna przekonwertować na surową kwotę tokena dla transakcji.
  • W przypadku problemów z zaokrąglaniem, zaokrąglaj w dół i preferuj pozostawienie niewielkiej ilości „kurzu” zamiast ryzykować niepowodzenie transakcji.
  • Aby dokonać tej konwersji, możesz użyć funkcji uiAmountToAmountForMintWithoutSimulation (web3.js v1) lub symulować transakcję za pomocą 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 */

• Aplikacje powinny używać całkowitej surowej kwoty, gdy użytkownik wybiera opcję „max” lub „all” swojego salda. Zapewnia to, że nie pozostaną żadne resztki.
  • Opcjonalnie: Możesz rozważyć automatyczne zamknięcie konta, gdy używana jest opcja „max”, aby zwrócić użytkownikowi depozyt za przechowywanie.

Cena tokena

• Cena tokena powinna być zawsze wyświetlana jako przeskalowana cena, gdzie to możliwe.
• Jeśli jesteś dostawcą usług feedu cenowego, takim jak oracle, powinieneś udostępniać zarówno przeskalowaną, jak i nieprzeskalowaną cenę.
  • Gdzie to możliwe, zapewnij SDK/API, które abstrahuje złożoności związane z rozszerzeniem przeskalowanej kwoty w interfejsie użytkownika.

Aktualny mnożnik

• Aktualny mnożnik można odczytać z token mint w dowolnym momencie, wywołując getAccountInfo. Dodatkowo, jeśli ustawiony jest przyszły mnożnik, ta informacja jest również dostępna z token mint. Zalecamy nie wyświetlać tego mnożnika, ponieważ może to wprowadzać zamieszanie w 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
*/

Dane historyczne

Dane historyczne dla feedu cenowego

• Usługi dostarczające dane historyczne powinny przechowywać i udostępniać zarówno przeskalowane, jak i nieprzeskalowane ceny dla rozszerzenia przeskalowanej kwoty w interfejsie użytkownika.
• Oczekujemy, że przeskalowane kwoty będą używane najczęściej, ponieważ jest to zgodne z tym, jak tradycyjny świat finansów traktuje wykresy związane z tokenami z podziałami akcji.

Dane historyczne dla kwot

• Jeśli chcesz pokazać saldo przeniesione w przeszłości, musisz mieć dostęp do mnożnika w danym slocie. Możesz również zapisać UiAmount dla transferów podczas przetwarzania transakcji, aby uniknąć wykonywania tego obliczenia w przyszłości.

Wsteczna kompatybilność

• Domyślnie portfele i aplikacje, które nie obsługują rozszerzenia skalowanej kwoty interfejsu użytkownika (UI), pokażą poprawną całkowitą cenę aktywności, mnożąc nieskalowaną cenę * surową kwotę.
• Jednakże wyświetlą nieskalowaną cenę, co może powodować pewne zamieszanie wśród użytkowników.
• Mamy nadzieję, że to zachęci zespoły do aktualizacji swoich dApps, aby były kompatybilne z tokenami korzystającymi z rozszerzenia skalowanej kwoty UI, i chętnie zapewnimy wsparcie w tym procesie.

Zalecane priorytety integracji według platformy

Ogólne wymagania

Portfele

Eksploratory

Agregatory danych rynkowych (np. CoinGecko)

Dostawcy kanałów cenowych

DEXy