Unterstützung der Scaled UI Amount-Erweiterung auf Solana

Hintergrund

Die Scaled UI Amount-Erweiterung ermöglicht es Token-Emittenten, einen Multiplikator anzugeben, der bei der Berechnung des UI-Betrags des Token-Guthabens eines Benutzers verwendet wird. Dies ermöglicht es Emittenten, Rebasing-Token zu erstellen und Dinge wie Aktiensplits zu ermöglichen. Diese Erweiterung bietet, wie die zinstragende Token-Erweiterung, einen rein kosmetischen UI-Betrag, was bedeutet, dass Teams zusätzliche Arbeit leisten müssen, um eine gute Benutzererfahrung zu bieten. Zugrunde liegende Berechnungen und Überweisungen erfolgen alle unter Verwendung der Rohbeträge im Programm.

Ressourcen:

• Entwicklerdokumentation
• Erweiterungs-Rust-Code
• Amount to UI Amount Rust-Code

Zusammenfassung

• Endbenutzer sollten wann immer möglich mit dem UIAmount (Rohbetrag * Multiplikator) für den Token-Preis, das Token-Guthaben und die Token-Beträge interagieren
• dApps und Dienstanbieter sollten den Rohbetrag und nicht skalierte Preise für alle Berechnungen verwenden und für Benutzer am Rand konvertieren
• Historische Preis-Feeds müssen sowohl für skalierte als auch für nicht skalierte Beträge bereitgestellt werden, um eine einfachere Integration zu ermöglichen
• Historische Multiplikatorwerte müssen für genaue historische Daten zugänglich sein

Begriffsdefinitionen

• Multiplikator: statischer aktualisierbarer Multiplikator, der für UIAmount-Berechnungen verwendet wird
• UIAmount: Multiplikator * Rohbetrag (auch: skalierter Betrag)
• Rohbetrag: Betrag (auch: nicht skalierter Betrag)

Aktuelles Guthaben

Aktueller Betrag zur Anzeige

• Jedes Mal, wenn Sie Beträge für Token, die die Scaled UI Amount-Erweiterung verwenden, für Endbenutzer anzeigen, sollten Sie entweder verwenden:
  • UIAmount/UIAmountString (bevorzugt)
  • Eine manuelle Berechnung von Rohbetrag * Multiplikator
  • Wir empfehlen, diesen Wert basierend auf der Anzahl der Dezimalstellen, die der Token hat, zu kürzen.
    • Beispiel: Wenn yUSD 6 Dezimalstellen hat und ein Benutzer einen UIAmount von 1,123456789 hat, sollten Sie „1,123456" anzeigen

Wo Sie diese Daten erhalten:

• Für den aktuellen Kontostand eines Benutzers können Sie aktualisierte Informationen zu den oben genannten Beträgen erhalten, indem Sie entweder getTokenAccountBalance oder getAccountInfo aufrufen
• Wenn Sie den UI-Betrag für einen beliebigen Betrag benötigen, können Sie diese Berechnung durch Aufrufen der Funktion amountToUiAmountForMintWithoutSimulation (web3.js v1) oder durch Simulieren einer Transaktion mit amountToUiAmount erhalten.
  • Hinweis: amountToUiAmount erfordert eine Transaktionssimulation, was bedeutet, dass auch ein gültiger Gebührenzahler mit Guthaben benötigt wird. Aus diesem Grund sollte dies nicht die Standardmethode zum Abrufen eines Kontostands sein.

RPC-Aufrufe

• getTokenAccountBalance
  • Gibt den Token-Kontostand und die Mint-Informationen zurück

$ 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
  • Gibt die Kontoinformationen und die Mint-Informationen zurück

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

Aktualisierung des aktuellen Betrags

Da Emittenten den Multiplikator jederzeit aktualisieren können, sollten Sie gelegentlich eine Abfrage durchführen, um den Kontostand aktuell zu halten. Es ist unwahrscheinlich, dass Emittenten diesen Multiplikator mehr als einmal pro Tag aktualisieren. Wenn ein Multiplikator für ein zukünftiges Datum festgelegt ist, können Sie zu diesem Aktualisierungszeitpunkt automatisch eine Abfrage durchführen

Token-Beträge in Transaktionen (Überweisungen / Swaps etc.)

• Benutzer sollten Beträge eingeben, die als skalierter „UIAmount" interpretiert werden sollen. Die App, die dies verarbeiten muss, sollte für die Transaktion in den rohen Token-Betrag umrechnen.
  • Bei Rundungsproblemen sollten Sie abrunden und lieber eine winzige Menge Staub übrig lassen, anstatt zu riskieren, dass die Transaktion fehlschlägt
  • Um diese Umrechnung durchzuführen, können Sie die Funktion uiAmountToAmountForMintWithoutSimulation (web3.js v1) verwenden oder eine Transaktion mit amountToUiAmount simulieren.

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

• Apps sollten den gesamten Rohbetrag verwenden, wenn ein Benutzer eine Aktion mit "max" oder "all" seines Guthabens durchführen möchte. Dies stellt sicher, dass kein Restbetrag übrig bleibt.
  • Optional: Sie können in Erwägung ziehen, ein Konto automatisch zu schließen, wenn "max" verwendet wird, um dem Benutzer seine Speichereinlage zurückzuerstatten

Token-Preis

• Der Token-Preis sollte nach Möglichkeit immer als skalierter Preis angezeigt werden.
• Wenn Sie ein Anbieter von Preisfeed-Diensten sind, wie z. B. ein Orakel, sollten Sie sowohl den skalierten als auch den nicht skalierten Preis bereitstellen.
  • Stellen Sie nach Möglichkeit ein SDK/API bereit, das die Komplexität der skalierten UI-Betragserweiterung abstrahiert.

Aktueller Multiplikator

• Der aktuelle Multiplikator kann jederzeit aus dem Token-Mint ausgelesen werden, indem getAccountInfo aufgerufen wird. Wenn zusätzlich ein zukünftiger Multiplikator festgelegt ist, sind diese Informationen ebenfalls aus dem Token-Mint verfügbar. Wir empfehlen, diesen Multiplikator nicht anzuzeigen, da er die UX verwirren kann.

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

Historische Daten

Historische Daten für Preisfeed

• Dienste, die historische Daten bereitstellen, sollten sowohl die skalierten als auch die nicht skalierten Preise für die skalierte UI-Betragserweiterung speichern und bereitstellen.
• Wir erwarten, dass skalierte Beträge am häufigsten verwendet werden, da dies mit der Art und Weise übereinstimmt, wie die traditionelle Finanzwelt Diagramme im Zusammenhang mit Token mit Aktiensplits behandelt.
• Multiplikator-Updates können einen Zeitstempel enthalten, der in der Vergangenheit liegt. Wir empfehlen, den Block-Zeitstempel für historische Daten zu verwenden.
• Beachten Sie, dass der aktive Multiplikator je nach aktuellem Zeitstempel und dem Zeitpunkt, zu dem der neue Multiplikator aktiv werden soll, entweder der "Multiplikator" oder der "newMultiplier" sein kann.

Historische Daten für Beträge

• Wenn Sie das in der Vergangenheit übertragene Guthaben anzeigen möchten, benötigen Sie Zugriff auf den Multiplikator zum jeweiligen Slot. Sie können auch den UiAmount für Überweisungen speichern, während Sie Transaktionen verarbeiten, um diese Berechnung in Zukunft zu vermeiden.

Abwärtskompatibilität

• Standardmäßig zeigen Wallets und Anwendungen, die die skalierte UI-Betrags-Erweiterung nicht verstehen, den korrekten Gesamtpreis einer Aktivität an, indem sie den nicht skalierten Preis * Rohbetrag multiplizieren.
• Sie würden jedoch den nicht skalierten Preis anzeigen, was zu Verwirrung bei den Benutzern führen kann.
• Wir hoffen, dass dies Teams dazu ermutigt, ihre dApps zu aktualisieren, um mit Tokens kompatibel zu sein, die die skalierte UI-Betrags-Erweiterung verwenden, und wir unterstützen gerne während dieses Prozesses.

Empfohlene Integrationsprioritäten pro Plattform

Allgemeine Anforderungen

Wallets

Explorer

Marktdaten-Aggregatoren (z. B. CoinGecko, Birdeye)

Preisfeed-Anbieter

DEXes

CEXes