Integratie handleiding voor geschaalde UI-bedragen
Ondersteuning van de Scaled UI Amount-extensie op Solana
Achtergrond
De Scaled UI Amount-extensie stelt token-uitgevers in staat om een vermenigvuldiger te specificeren die gebruikt wordt bij het berekenen van het UI-bedrag van het tokensaldo van een gebruiker. Dit maakt het voor uitgevers mogelijk om rebaserende tokens te creëren en dingen zoals aandelensplitsingen mogelijk te maken. Deze extensie biedt, net als de interest bearing token-extensie, een puur cosmetisch UI-bedrag, wat betekent dat teams extra werk moeten doen om een goede gebruikerservaring te bieden. Onderliggende berekeningen en overdrachten gebeuren allemaal met de ruwe bedragen in het programma.
Bronnen:
Samenvatting
- Eindgebruikers moeten waar mogelijk werken met het UIAmount (ruw bedrag × vermenigvuldiger) voor de tokenprijs, tokensaldo en tokenbedragen
- dApps en serviceproviders moeten het ruwe bedrag en niet-geschaalde prijzen gebruiken voor alle berekeningen en deze voor gebruikers aan de rand converteren
- Historische prijsfeeds moeten worden aangeboden voor zowel geschaalde als niet-geschaalde bedragen voor eenvoudigere integratie
- Historische vermenigvuldigerswaarden moeten toegankelijk zijn voor nauwkeurige historische gegevens
Begripsdefinities
- Vermenigvuldiger: statische bijwerkbare vermenigvuldiger die wordt gebruikt voor UI Amount-berekeningen
- UIAmount: vermenigvuldiger × ruw bedrag (ook bekend als: geschaald bedrag)
- Ruw bedrag: bedrag (ook bekend als: niet-geschaald bedrag)
Huidig saldo
Huidig bedrag voor weergave
- Wanneer je bedragen weergeeft voor tokens die de scaled UI amount-extensie
gebruiken aan eindgebruikers, moet je gebruikmaken van:
- UIAmount/UIAmountString (aanbevolen)
- Een handmatige berekening van ruw bedrag × vermenigvuldiger
- We raden aan deze waarde af te kappen op basis van het aantal decimalen dat
de token heeft.
- Bijv.: als yUSD 6 decimalen heeft en een gebruiker heeft een UIAmount van 1.123456789, moet je "1.123456" weergeven
Waar deze gegevens te verkrijgen:
- Voor het actuele saldo van een gebruiker kun je bijgewerkte informatie over de bovenstaande bedragen krijgen door getTokenAccountBalance of getAccountInfo aan te roepen
- Als je de UI-hoeveelheid voor een willekeurig bedrag moet weten, kun je deze
berekening krijgen door de
amountToUiAmountForMintWithoutSimulation
(web3.js v1) functie aan te roepen of door een transactie te simuleren met amountToUiAmount.- Opmerking: amountToUiAmount vereist een transactiesimulatie, wat betekent dat het ook een geldige fee payer met saldo nodig heeft. Daarom zou dit niet de standaardmethode moeten zijn om een saldo op te halen.
RPC-aanroepen
getTokenAccountBalance
- Geeft het token account saldo en de mint-informatie terug
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
- Geeft de account-informatie en de mint-informatie terug
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"}} */
Het huidige bedrag bijwerken
Omdat uitgevers de vermenigvuldiger op elk moment kunnen bijwerken, kun je overwegen om regelmatig te pollen om het accountsaldo bijgewerkt te houden. Het is onwaarschijnlijk dat uitgevers deze vermenigvuldiger vaker dan eenmaal per dag bijwerken. Als een vermenigvuldiger is ingesteld voor een toekomstige datum, kun je automatisch pollen op dit bijwerkmoment
Tokenbedragen in transacties (overdrachten / swaps etc)
- Gebruikers moeten bedragen invoeren die worden geïnterpreteerd als het
geschaalde "UIAmount". De app die dit moet verwerken, moet dit omzetten naar
het ruwe tokenbedrag voor de transactie.
- Als er afrondingsproblemen zijn, rond dan naar beneden af en laat liever een klein beetje dust over dan het risico te lopen dat de transactie mislukt
- Voor deze conversie kun je de
uiAmountToAmountForMintWithoutSimulation
(web3.js v1) functie gebruiken of een transactie simuleren met 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 */
- Apps moeten het totale ruwe bedrag gebruiken wanneer een gebruiker vraagt om
een actie uit te voeren met "max" of "alles" van hun saldo. Dit zorgt ervoor
dat er geen dust overblijft.
- Optioneel: Je kunt overwegen om automatisch een account te sluiten wanneer "max" wordt gebruikt om de gebruiker hun opslagdeposito terug te betalen
Tokenprijs
- Tokenprijs moet waar mogelijk altijd worden weergegeven als de geschaalde prijs.
- Als je een prijsfeedserviceprovider bent, zoals een oracle, moet je zowel de
geschaalde als de niet-geschaalde prijs beschikbaar stellen.
- Bied waar mogelijk een SDK/API aan die de complexiteit van de geschaalde UI-bedrag extensie abstraheert.
Huidige vermenigvuldiger
- De huidige vermenigvuldiger kan op elk moment worden uitgelezen van de token
mint door
getAccountInfo
aan te roepen. Als er een toekomstige vermenigvuldiger is ingesteld, is deze informatie ook beschikbaar vanuit de token mint. We raden aan om deze vermenigvuldiger niet te tonen omdat dit de gebruikerservaring kan verwarren.
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 gegevens
Historische gegevens voor prijsfeed
- Diensten die historische gegevens leveren, moeten zowel de geschaalde als de niet-geschaalde prijzen voor de geschaalde UI-bedrag-extensie opslaan en tonen.
- We verwachten dat geschaalde bedragen het meest gebruikt zullen worden, aangezien dit overeenkomt met hoe de traditionele financiële wereld omgaat met grafieken gerelateerd aan tokens met aandelensplitsingen.
Historische gegevens voor bedragen
- Als je het in het verleden overgedragen saldo wilt tonen, heb je toegang nodig tot de vermenigvuldiger op die specifieke slot. Je kunt ook het UiAmount voor overdrachten opslaan terwijl je transacties verwerkt om deze berekening in de toekomst te vermijden.
Achterwaartse compatibiliteit
- Standaard zullen wallets en applicaties die de geschaalde UI-bedrag-extensie niet begrijpen, de juiste totaalprijs van een activiteit tonen door de niet-geschaalde prijs * ruwe hoeveelheid te vermenigvuldigen.
- Ze zouden echter de niet-geschaalde prijs tonen, wat tot enige verwarring bij gebruikers kan leiden.
- We hopen dat dit teams aanmoedigt om hun dapps compatibel te maken met tokens die de geschaalde UI-bedrag-extensie gebruiken en we bieden graag ondersteuning tijdens dit proces.
Aanbevolen integratieprioriteiten per platform
Algemene vereisten
Vereiste | Beschrijving | Prioriteit |
---|---|---|
Ondersteun gebruikersacties met UiAmount | Alle gebruikersacties moeten worden ingevoerd in UiAmount wanneer UiAmount is ingeschakeld in de hele app. Als UiAmount niet zichtbaar is in de app, moeten ze ruwe bedragen gebruiken totdat de app is bijgewerkt. | P0 |
Wallets
Vereiste | Beschrijving | Prioriteit |
---|---|---|
Geschaald saldo weergeven | Toon het geschaalde bedrag (uiAmount) als het primaire saldo. | P0 |
Ondersteuning voor tokenoverdrachten | Eindgebruikers moeten overdrachtsbedragen invoeren met hun geschaalde saldi (raw amount * balance). | P0 |
Spotprijs weergeven | Toon de geschaalde spotprijs voor gebruikers | P0 |
Transactiegeschiedenis metadata | Toon het geschaalde bedrag (UIAmount) voor elke overdracht waar mogelijk. | P1 |
Toon vermenigvuldigerupdates in transactiegeschiedenis | Wanneer vermenigvuldigerupdates plaatsvinden, toon dit als een gebeurtenis in de transactiegeschiedenis van de gebruiker, inclusief het verkregen bedrag | P2 |
Prijshistoriekgrafiek weergeven | Weerspiegel de geschaalde prijzen in de prijsgrafiek | P1 |
Onboarding/tooltips | Bied tooltips of onboarding aan om gebruikers te informeren over tokens die de geschaalde ui-bedragextensie gebruiken | P2 |
Explorers
Vereiste | Beschrijving | Prioriteit |
---|---|---|
Verbeteringen tokenpagina | Toon metadata zoals totale geschaalde marktkapitalisatie en huidige vermenigvuldiger | P0 |
Geschaald saldo weergeven voor saldi | Toon geschaalde saldi (UiAmount) voor huidige saldi. | P0 |
Geschaald saldo weergeven voor transacties | Toon geschaalde saldi (UiAmount) voor overdrachtsbedragen bij historische transacties. | P0 |
Geschaalde prijs weergeven voor transacties | Toon geschaalde prijzen voor eerdere transacties | P1 |
Correct verwerken en weergeven van vermenigvuldigerupdatetransacties | Toon correct de details over de vermenigvuldigerupdate | P2 |
Marktgegevensaggregators (bijv. CoinGecko)
Vereiste | Beschrijving | Prioriteit |
---|---|---|
API-updates voor geschaalde data | API-functionaliteit uitbreiden om vermenigvuldigingswijzigingen over tijd en geschaalde prijsfeed op te nemen. | P0 |
Totale voorraad met geschaalde aanpassing | Bij het weergeven van totale voorraad en totale marktkapitalisatie, rekening houden met geschaalde saldi | P0 |
Historische prijstracking | Een historische grafiek van prijzen bieden met de geschaalde prijs over tijd. | P1 |
Historische vermenigvuldigertracking | Historische markeringen bieden van vermenigvuldigerupdates voor rentegevende tokens. | P2 |
Educatieve inhoud of uitleg | Korte beschrijvingen of tooltips opnemen die uitleggen hoe geschaalde tokens werken. | P2 |
Prijsfeedproviders
Vereiste | Beschrijving | Prioriteit |
---|---|---|
Geschaalde & niet-geschaalde prijsfeeds | Prijsfeeds bieden voor zowel geschaalde als niet-geschaalde prijzen. | P0 |
Historische vermenigvuldigerdata | API's aanbieden met historische vermenigvuldigingswijzigingen. | P0 |
Historische prijsdata | API's aanbieden met historische prijzen gebaseerd op zowel geschaalde als niet-geschaalde bedragen. | P0 |
DEXes
Vereiste | Beschrijving | Prioriteit |
---|---|---|
Toon geherbaseerde tokensaldi | Toon geschaalde saldi voor handel of liquiditeitsverschaffing in de UI. (backend kan nog steeds ruwe bedragen gebruiken) | P0 |
Ondersteuning voor tokenacties | Eindgebruikers moeten actiebedragen invoeren met hun UiAmount-saldi (vermenigvuldiger * ruw bedrag). | P0 |
Prijsfeedaanpassing | Overal waar een prijsfeed wordt gebruikt om de huidige prijs weer te geven, bied de geschaalde prijs aan eindgebruikers. | P1 |
Toon prijshistoriekgrafiek | Weerspiegelen van de geschaalde prijzen in de prijsgrafiek | P1 |
Is this page helpful?