Integrationsanleitung für skalierte UI-Beträge

Unterstützung der Scaled UI Amount-Erweiterung auf Solana

Hintergrund

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

Ressourcen:

Zusammenfassung

  • Endbenutzer sollten wann immer möglich mit dem UIAmount (Rohbetrag * Multiplikator) für den Token-Preis, Token-Guthaben und Token-Beträge interagieren
  • dApps und Dienstanbieter sollten für alle Berechnungen den Rohbetrag und nicht-skalierte Preise verwenden und diese nur an der Schnittstelle zum Benutzer umrechnen
  • Historische Preisfeeds müssen sowohl für skalierte als auch für nicht-skalierte Beträge bereitgestellt werden, um die Integration zu erleichtern
  • Historische Multiplikatorwerte müssen zugänglich sein, um genaue historische Daten zu gewährleisten

Begriffsdefinitionen

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

Aktuelles Guthaben

Aktueller Betrag zur Anzeige

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

Woher diese Daten beziehen:

  • Für das aktuelle Guthaben eines Nutzers können Sie aktualisierte Informationen zu den oben genannten Beträgen durch Aufruf von entweder getTokenAccountBalance oder getAccountInfo erhalten
  • Wenn Sie den UI-Betrag für einen beliebigen Betrag benötigen, können Sie diese Berechnung durch Aufruf der amountToUiAmountForMintWithoutSimulation (web3.js v1) Funktion oder durch Simulation einer Transaktion mit amountToUiAmount erhalten.
    • Hinweis: amountToUiAmount erfordert eine Transaktionssimulation, was bedeutet, dass es auch einen gültigen Gebührenzahler mit Guthaben benötigt. Aus diesem Grund sollte dies nicht der Standardweg sein, um ein Guthaben abzurufen.

RPC-Aufrufe

  • getTokenAccountBalance
    • Gibt den Token-Kontostand und die Mint-Informationen zurück
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
    • Gibt die Kontoinformationen und die Mint-Informationen zurück
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"
}
} */

Aktualisierung des aktuellen Betrags

Da Emittenten den Multiplikator jederzeit aktualisieren können, solltest du regelmäßiges Polling in Betracht ziehen, 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, kannst du zu diesem Aktualisierungszeitpunkt automatisch pollen

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

  • Benutzer sollten Beträge eingeben, die als skalierte "UIAmount" interpretiert werden. Die App, die dies verarbeiten muss, sollte für die Transaktion in den rohen Token-Betrag umrechnen.
    • Bei Rundungsproblemen sollte abgerundet werden und es ist besser, einen winzigen Restbetrag zu hinterlassen, als zu riskieren, dass die Transaktion fehlschlägt
    • Für diese Umrechnung kannst du die Funktion uiAmountToAmountForMintWithoutSimulation (web3.js v1) verwenden oder eine Transaktion mit amountToUiAmount simulieren.
web3js-uiAmountToAmountForMintWithoutSimulation.ts
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 anfordert. Dies stellt sicher, dass kein Restbetrag übrig bleibt.
    • Optional: Du kannst in Betracht ziehen, ein Konto automatisch zu schließen, wenn "max" verwendet wird, um dem Benutzer seine Speichereinlage zurückzuerstatten

Token-Preis

  • Der Token-Preis sollte, wo immer möglich, als skalierter Preis angezeigt werden.
  • Wenn du ein Preisfeed-Dienstanbieter bist, wie z.B. ein Oracle, solltest du sowohl den skalierten als auch den nicht-skalierten Preis bereitstellen.
    • Stelle nach Möglichkeit ein SDK/API bereit, das die Komplexität der skalierten UI-Betrags-Erweiterung abstrahiert.

Aktueller Multiplikator

  • Der aktuelle Multiplikator kann jederzeit aus dem Token-Mint ausgelesen werden, indem getAccountInfo aufgerufen wird. Wenn ein zukünftiger Multiplikator festgelegt ist, ist diese Information ebenfalls aus dem Token-Mint verfügbar. Wir empfehlen, diesen Multiplikator nicht anzuzeigen, da er die Benutzeroberfläche 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 Price Feed

  • Dienste, die historische Daten bereitstellen, sollten sowohl die skalierten als auch die nicht-skalierten Preise für die skalierte UI-Betrags-Erweiterung speichern und anzeigen.
  • Wir erwarten, dass skalierte Beträge am häufigsten verwendet werden, da dies der Art entspricht, wie die traditionelle Finanzwelt mit Diagrammen zu Tokens mit Aktiensplits umgeht.

Historische Daten für Beträge

  • Wenn Sie den in der Vergangenheit übertragenen Saldo anzeigen möchten, benötigen Sie Zugriff auf den Multiplikator zu diesem bestimmten slot. Sie können auch den UiAmount für Überweisungen speichern, während Sie Transaktionen verarbeiten, um diese Berechnung in der 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 könnte.
  • 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 bieten gerne Unterstützung während dieses Prozesses an.

Empfohlene Integrationsprioritäten nach Plattform

Allgemeine Anforderungen

AnforderungBeschreibungPriorität
Unterstützung von Benutzeraktionen mit UiAmountAlle Benutzeraktionen sollten in UiAmount eingegeben werden, wenn UiAmount in der gesamten App aktiviert ist. Wenn UiAmount in der App nicht sichtbar ist, sollten sie Rohbeträge verwenden, bis die App aktualisiert wird.P0

Wallets

AnforderungBeschreibungPriorität
Skaliertes Guthaben anzeigenZeige den skalierten Betrag (uiAmount) als primäres Guthaben an.P0
Unterstützung für Token-TransfersEndnutzer sollten Überweisungsbeträge mit ihren skalierten Guthaben eingeben (Rohbetrag * Guthaben).P0
Spot-Preis anzeigenZeige den skalierten Spot-Preis für Benutzer anP0
Transaktionsverlauf-MetadatenZeige den skalierten Betrag (UIAmount) für jede Überweisung an, wo immer möglich.P1
Multiplikator-Updates im TransaktionsverlaufWenn Multiplikator-Updates erfolgen, zeige dies als Ereignis im Transaktionsverlauf des Benutzers mit dem erhaltenen BetragP2
Preisverlaufsgrafik anzeigenSpiegele die skalierten Preise in der Preisgrafik widerP1
Onboarding/TooltipsBiete Tooltips oder Onboarding an, um Benutzer über Tokens zu informieren, die die skalierte UI-Betragserweiterung nutzenP2

Explorers

AnforderungBeschreibungPriorität
Verbesserungen der Token-DetailseiteZeige Metadaten wie die skalierte Marktkapitalisierung und den aktuellen Multiplikator anP0
Skaliertes Guthaben für Kontostände anzeigenZeige skalierte Guthaben (UiAmount) für aktuelle Kontostände an.P0
Skaliertes Guthaben für Transaktionen anzeigenZeige skalierte Guthaben (UiAmount) für Überweisungsbeträge bei historischen Transaktionen.P0
Skalierten Preis für Transaktionen anzeigenZeige skalierte Preise für frühere Transaktionen anP1
Korrekte Analyse und Anzeige von Multiplikator-UpdatesZeige Details zu Multiplikator-Updates korrekt anP2

Marktdaten-Aggregatoren (z.B.: CoinGecko)

AnforderungBeschreibungPriorität
API-Updates für skalierte DatenErweiterung der API-Funktionalität, um Multiplikatoränderungen im Zeitverlauf sowie den skalierten Preisfeed einzubeziehen.P0
Gesamtangebot mit skalierter AnpassungBei der Anzeige des Gesamtangebots und der Gesamtmarktkapitalisierung die skalierten Salden berücksichtigenP0
Historische PreisverfolgungBereitstellung eines historischen Diagramms der Preise unter Verwendung des skalierten Preises im Zeitverlauf.P1
Historische MultiplikatorverfolgungBereitstellung historischer Marker für Multiplikator-Updates für zinstragende Token.P2
Bildungsinhalte oder ErklärungenKurze Beschreibungen oder Tooltips einfügen, die erklären, wie skalierte Token funktionieren.P2

Preisfeed-Anbieter

AnforderungBeschreibungPriorität
Skalierte & nicht-skalierte PreisfeedsBereitstellung von Preisfeeds für sowohl skalierte als auch nicht-skalierte Preise.P0
Historische MultiplikatordatenAngebot von APIs mit historischen Multiplikatoränderungen.P0
Historische PreisdatenAngebot von APIs mit historischen Preisen basierend auf skalierten und nicht-skalierten Beträgen.P0

DEXes

AnforderungBeschreibungPriorität
Anzeige von rebasierten Token-SaldenAnzeige skalierter Salden für Handel oder Liquiditätsbereitstellung in der Benutzeroberfläche. (Backend kann weiterhin Rohbeträge verwenden)P0
Unterstützung für Token-AktionenEndbenutzer sollten Aktionsbeträge mit ihren UiAmount-Salden eingeben (Multiplikator × Rohbetrag).P0
Preisfeed-AnpassungÜberall, wo ein Preisfeed zur Anzeige des aktuellen Preises verwendet wird, den skalierten Preis für Endbenutzer bereitstellen.P1
Anzeige des PreisverlaufsdiagrammsDie skalierten Preise im Preisdiagramm widerspiegelnP1

Is this page helpful?