Integrationsanleitung für skalierte UI-Beträge
Unterstützung der Scaled UI Amount Extension auf Solana
Hintergrund
Die Scaled UI Amount Extension 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 zinstragende 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 den Rohbetrag und nicht-skalierte Preise für alle Berechnungen verwenden und für Benutzer am Ende konvertieren
- 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 erhalten
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 für die Anzeige
- Wann immer Sie Beträge für Token anzeigen, die die Scaled UI Amount Extension
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 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 durchführen.- 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 das Token-Kontoguthaben 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 in Betracht ziehen, gelegentlich abzufragen, um den Kontostand aktuell zu halten. Emittenten werden diesen Multiplikator wahrscheinlich nicht öfter als einmal pro Tag aktualisieren. Wenn ein Multiplikator für ein zukünftiges Datum festgelegt ist, können Sie zu diesem Aktualisierungszeitpunkt automatisch abfragen
Token-Beträge in Transaktionen (Überweisungen / Swaps usw.)
- Benutzer sollten Beträge eingeben, die als skalierter "UIAmount" interpretiert
werden. Die App, die dies verarbeiten muss, sollte in den Roh-Token-Betrag für
die Transaktion umrechnen.
- Bei Rundungsproblemen sollte abgerundet werden und es ist besser, einen winzigen Betrag als Rest zu belassen, als zu riskieren, dass die Transaktion fehlschlägt
- Für diese Umrechnung können Sie die
uiAmountToAmountForMintWithoutSimulation
(web3.js v1) Funktion 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 anfordert. Dies stellt sicher, dass kein
Restbetrag übrig bleibt.
- Optional: Sie können erwägen, 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 Sie ein Preisfeed-Dienstanbieter sind, wie z.B. ein Oracle, sollten Sie
sowohl den skalierten als auch den nicht-skalierten Preis bereitstellen.
- Bieten Sie nach Möglichkeit ein SDK/API an, das die Komplexität der skalierten UI-Betrags- erweiterung abstrahiert.
Aktueller Multiplikator
- Der aktuelle Multiplikator kann jederzeit aus dem Token-Mint abgerufen 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 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-Betragsanzeige speichern und anzeigen.
- Wir erwarten, dass skalierte Beträge am häufigsten verwendet werden, da dies der Darstellung von Charts für Tokens mit Aktiensplits in der traditionellen Finanzwelt entspricht.
- Multiplikator-Updates können einen Zeitstempel enthalten, der in der Vergangenheit liegt. Wir empfehlen die Verwendung des Block-Zeitstempels für historische Daten.
- Beachten Sie, dass der aktive Multiplikator entweder der "multiplier" oder der "newMultiplier" sein kann, abhängig vom aktuellen Zeitstempel und dem Zeitpunkt, zu dem der neue Multiplikator aktiv werden soll.
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.
Rückwärtskompatibilität
- Standardmäßig werden Wallets und Anwendungen, die die skalierte UI-Betrags-Erweiterung nicht verstehen, den korrekten Gesamtpreis einer Aktivität anzeigen, indem sie den nicht-skalierten Preis mit dem Rohbetrag multiplizieren.
- Sie würden jedoch den nicht-skalierten Preis anzeigen, was zu Verwirrung bei Nutzern 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
Anforderung | Beschreibung | Priorität |
---|---|---|
Unterstützung von Benutzeraktionen mit UiAmount | Alle Benutzeraktionen sollten in UiAmount eingegeben werden, wenn UiAmount in der gesamten App aktiviert ist. Wenn UiAmount in der App nicht sichtbar ist, sollten Rohbeträge verwendet werden, bis die App aktualisiert wird. | P0 |
Wallets
Anforderung | Beschreibung | Priorität |
---|---|---|
Skaliertes Guthaben anzeigen | Den skalierten Betrag (uiAmount) als primäres Guthaben anzeigen. | P0 |
Unterstützung für Token-Transfers | Endnutzer sollten Transferbeträge mit ihren skalierten Guthaben eingeben (Rohbetrag * Guthaben). | P0 |
Spot-Preis anzeigen | Den skalierten Spot-Preis für Benutzer anzeigen | P0 |
Transaktionsverlauf-Metadaten | Den skalierten Betrag (UIAmount) für jeden Transfer anzeigen, wo immer möglich. | P1 |
Multiplikator-Updates im Transaktionsverlauf anzeigen | Wenn Multiplikator-Updates auftreten, dies als Ereignis im Transaktionsverlauf des Benutzers anzeigen, einschließlich des gewonnenen Betrags | P2 |
Preisverlaufsgrafik anzeigen | Die skalierten Preise in der Preisgrafik widerspiegeln | P1 |
Onboarding/Tooltips | Tooltips oder Onboarding anbieten, um Benutzer über Tokens zu informieren, die die skalierte UI-Betrags-Erweiterung verwenden | P2 |
Explorer
Anforderung | Beschreibung | Priorität |
---|---|---|
Verbesserungen der Token-Detailseite | Anzeige von Metadaten wie skalierte Marktkapitalisierung und aktueller Multiplikator | P0 |
Anzeige des skalierten Guthabens für Kontostände | Anzeige skalierter Guthaben (UiAmount) für aktuelle Kontostände. | P0 |
Anzeige des skalierten Guthabens für Transaktionen | Anzeige skalierter Guthaben (UiAmount) für Überweisungsbeträge bei historischen Transaktionen. | P0 |
Anzeige des skalierten Preises für Transaktionen | Anzeige skalierter Preise für vorherige Transaktionen | P1 |
Korrektes Parsen und Anzeigen von Multiplikator-Updates | Korrekte Anzeige von Details zu Multiplikator-Updates | P2 |
Marktdaten-Aggregatoren (z.B. CoinGecko, Birdeye)
Anforderung | Beschreibung | Priorität |
---|---|---|
API-Updates für skalierte Daten | Erweiterung der API-Funktionalität, um Multiplikatoränderungen im Zeitverlauf sowie den skalierten Preisfeed einzubeziehen. | P0 |
Gesamtangebot mit skalierter Anpassung | Bei der Anzeige des Gesamtangebots und der Gesamtmarktkapitalisierung die skalierten Salden berücksichtigen | P0 |
Historische Preisverfolgung | Bereitstellung eines historischen Preisverlaufs unter Verwendung des skalierten Preises im Zeitverlauf. | P1 |
Historische Multiplikatorverfolgung | Bereitstellung historischer Markierungen von Multiplikator-Updates für zinstragende Tokens. Beachten Sie, dass Multiplikator-Updates einen Zeitstempel enthalten können, der in der Vergangenheit liegt. Wir empfehlen, für historische Daten den Block-Zeitstempel anstelle des im Multiplikator-Update angegebenen Zeitstempels zu verwenden. | P2 |
Bildungsinhalte oder Erklärungen | Kurze Beschreibungen oder Tooltips einfügen, die erklären, wie skalierte Tokens funktionieren. | P2 |
Preisfeed-Anbieter
Anforderung | Beschreibung | Priorität |
---|---|---|
Skalierte & nicht-skalierte Preisfeeds | Bereitstellung von Preisfeeds für sowohl skalierte als auch nicht-skalierte Preise. | P0 |
Historische Multiplikator-Daten | Angebot von APIs mit historischen Multiplikator-Änderungen. Beachten Sie, dass Multiplikator-Updates einen Zeitstempel enthalten können, der in der Vergangenheit liegt. Wir empfehlen, den Block-Zeitstempel anstelle des im Multiplikator-Update angegebenen Zeitstempels für historische Daten zu verwenden. | P0 |
Historische Preisdaten | Angebot von APIs mit historischen Preisen basierend auf skalierten und nicht-skalierten Beträgen. | P0 |
DEXes
Anforderung | Beschreibung | Priorität |
---|---|---|
Anzeige von rebasierten Token-Guthaben | Skalierte Guthaben für Handel oder Liquiditätsbereitstellung in der Benutzeroberfläche anzeigen. (Backend kann weiterhin Rohbeträge verwenden) | P0 |
Unterstützung für Token-Aktionen | Endbenutzer sollten Aktionsbeträge mit ihren UiAmount-Guthaben eingeben (Multiplikator * Rohbetrag). | P0 |
Anpassung des Preisfeeds | Überall, wo ein Preisfeed zur Anzeige des aktuellen Preises verwendet wird, sollte der skalierte Preis für Endbenutzer angezeigt werden. | P1 |
Anzeige des Preisverlaufsdiagramms | Die skalierten Preise im Preisdiagramm widerspiegeln | P1 |
CEXes
Anforderung | Beschreibung | Priorität |
---|---|---|
Multiplikator-Updates verfolgen | Multiplikator-Updates für Tokens verfolgen, die die skalierte UI-Betrags-Erweiterung verwenden. | P0 |
Anzeige von rebasierten Token-Guthaben | Skalierte Guthaben für Handel oder Liquiditätsbereitstellung in der Benutzeroberfläche anzeigen. (Backend kann weiterhin Rohbeträge verwenden) | P0 |
Unterstützung für Token-Aktionen | Endbenutzer sollten Aktionsbeträge mit ihren UiAmount-Guthaben eingeben (Multiplikator * Rohbetrag). | P0 |
Historische Aktionen sollten nicht neu skaliert werden | Historische Aktionen wie Trades sollten mit dem genauen skalierten Betrag und Preis zum Zeitpunkt der Aktion angezeigt werden. | P1 |
Intern Rohguthaben verfolgen | Rohguthaben für Onchain-Transaktionen anstelle von skalierten Guthaben verfolgen. Dies wird langfristig genauer und einfacher zu verwalten sein. | P1 |
Anpassung des Preisfeeds | Überall, wo ein Preisfeed zur Anzeige des aktuellen Preises verwendet wird, sollte der skalierte Preis für Endbenutzer angezeigt werden. | P1 |
Anzeige des Preisverlaufsdiagramms | Die skalierten Preise im Preisdiagramm widerspiegeln. Dies beinhaltet die Neuskalierung historischer Preise auf den aktuellen Multiplikator. | P1 |
Kostenbasis skalieren | Kosten pro Anteil sollten auf den aktuellen Multiplikator skaliert werden. | P1 |
Is this page helpful?