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 rebalansujących 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ą obsługę. Wszystkie obliczenia i transfery odbywają się przy użyciu surowych wartości w programie.

Zasoby:

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

TL;DR

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

Definicje terminów

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

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 wartoś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 informacje o saldzie użytkownika, możesz pobrać zaktualizowane dane o powyższych kwotach, wywołując funkcje getTokenAccountBalance lub getAccountInfo.
• Jeśli potrzebujesz znać kwotę UI Amount 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)

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

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

Aktualizacja bieżącej kwoty

Ponieważ emitenci mogą aktualizować mnożnik w dowolnym momencie, warto rozważyć okresowe odpytywanie w celu utrzymania aktualności 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ągleniami, zaokrąglaj w dół i preferuj pozostawienie niewielkiej ilości „kurzu” zamiast ryzykować niepowodzenie transakcji.
  • Do 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” dla 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, jeśli to możliwe.
• Jeśli jesteś dostawcą usług feedu cenowego, takim jak wyrocznia, powinieneś udostępniać zarówno przeskalowaną, jak i nieprzeskalowaną cenę.
  • W miarę możliwości 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 w trakcie 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 zachęci to 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

CEXy