Integratie handleiding voor geschaalde UI-bedragen

Ondersteuning van de Scaled UI Amount Extension 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 stelt uitgevers in staat 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 vermenigvuldigerwaarden moeten toegankelijk zijn voor nauwkeurige historische gegevens

Definitie van termen

  • Vermenigvuldiger: statische bijwerkbare vermenigvuldiger die wordt gebruikt voor UI Amount-berekeningen
  • UIAmount: vermenigvuldiger * ruw bedrag (ook wel: geschaald bedrag)
  • Ruw bedrag: bedrag (ook wel: niet-geschaald bedrag)

Huidig saldo

Huidig bedrag voor weergave

  • Wanneer je bedragen weergeeft voor tokens die de scaled UI amount extension 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, dan moet je "1.123456" weergeven

Waar deze gegevens te verkrijgen:

  • Voor een actueel saldo van een gebruiker kun je bijgewerkte informatie over de bovenstaande bedragen krijgen door getTokenAccountBalance of getAccountInfo aan te roepen
  • Als je het UI-bedrag 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
$ 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
    • Geeft de accountinformatie en de mint-informatie terug
$ 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
}

Het huidige bedrag bijwerken

Omdat uitgevers de vermenigvuldiger op elk gewenst moment kunnen bijwerken, kun je overwegen om regelmatig te pollen om het accountsaldo bijgewerkt te houden. Uitgevers zullen deze vermenigvuldiger waarschijnlijk niet 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.
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 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 restbedrag 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 prijsfeed-serviceprovider bent, zoals een oracle, moet je zowel de geschaalde als 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 niet-geschaalde prijzen voor de geschaalde UI-bedrag extensie opslaan en beschikbaar stellen.
  • We verwachten dat geschaalde bedragen het vaakst zullen worden gebruikt, aangezien dit overeenkomt met hoe de traditionele financiële wereld grafieken behandelt die gerelateerd zijn 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 te vermenigvuldigen met het ruwe bedrag.
  • Ze zouden echter de niet-geschaalde prijs weergeven, wat tot enige verwarring bij gebruikers kan leiden.
  • We hopen dat dit teams aanmoedigt om hun dapps bij te werken zodat ze compatibel zijn met tokens die de geschaalde UI-bedrag extensie gebruiken, en we bieden graag ondersteuning tijdens dit proces.

Aanbevolen integratie prioriteiten per platform

Algemene vereisten

VereisteBeschrijvingPrioriteit
Ondersteuning gebruikersacties met UiAmountAlle 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

VereisteBeschrijvingPrioriteit
Geschaald saldo weergevenToon het geschaalde bedrag (uiAmount) als het primaire saldo.P0
Ondersteuning voor token-overdrachtenEindgebruikers moeten overdrachtsbedragen invoeren met hun geschaalde saldi (ruw bedrag * saldo).P0
Spotprijs weergevenToon de geschaalde spotprijs voor gebruikersP0
Transactiegeschiedenis metadataToon waar mogelijk het geschaalde bedrag (UIAmount) voor elke overdracht.P1
Toon vermenigvuldiger-updates in transactiegeschiedenisWanneer vermenigvuldiger-updates plaatsvinden, toon dit als een gebeurtenis in de transactiegeschiedenis van de gebruiker, inclusief het verkregen bedragP2
Prijsgeschiedenis grafiek weergevenWeerspiegel de geschaalde prijzen in de prijsgrafiekP1
Onboarding/tooltipsBied tooltips of onboarding aan om gebruikers te informeren over tokens die de geschaalde ui-bedrag extensie gebruikenP2

Explorers

VereisteBeschrijvingPrioriteit
Verbeteringen tokenpaginaToon metadata zoals totale geschaalde marktkapitalisatie en huidige vermenigvuldigerP0
Toon geschaald saldo voor balansenToon geschaalde saldi (UiAmount) voor huidige balansen.P0
Toon geschaald saldo voor transactiesToon geschaalde saldi (UiAmount) voor overboekingsbedragen bij historische transacties.P0
Toon geschaalde prijs voor transactiesToon geschaalde prijzen voor eerdere transactiesP1
Correct verwerken en weergeven van vermenigvuldigerupdatesToon correcte details over de vermenigvuldigerupdateP2

Marktdata-aggregators (bijv. CoinGecko)

VereisteBeschrijvingPrioriteit
API-updates voor geschaalde dataBreid API-functionaliteit uit met vermenigvuldigerwijzigingen in de tijd en de geschaalde prijsfeed.P0
Totale voorraad met geschaalde aanpassingBij weergave van totale voorraad en totale marktkapitalisatie, houd rekening met geschaalde saldiP0
Historische prijstrackingBied een historische grafiek van prijzen met de geschaalde prijs in de tijd.P1
Historische vermenigvuldigertrackingBied historische markeringen van vermenigvuldigerupdates voor rentegevende tokens.P2
Educatieve inhoud of uitlegVoeg korte beschrijvingen of tooltips toe die uitleggen hoe geschaalde tokens werken.P2

Prijsfeedproviders

VereisteBeschrijvingPrioriteit
Geschaalde & niet-geschaalde prijsfeedsBied prijsfeeds voor zowel geschaalde als niet-geschaalde prijzen.P0
Historische vermenigvuldigerdataBied API's met historische vermenigvuldigerwijzigingen.P0
Historische prijsdataBied API's met historische prijzen gebaseerd op zowel geschaalde als niet-geschaalde bedragen.P0

DEXes

VereisteBeschrijvingPrioriteit
Toon herberekende tokenbalansenToon geschaalde balansen voor handel of liquiditeitsverschaffing in de UI. (backend kan nog steeds ruwe bedragen gebruiken)P0
Ondersteuning voor tokenactiesEindgebruikers moeten actieaantallen invoeren met hun UiAmount-balansen (vermenigvuldiger * ruw bedrag).P0
Aanpassing van prijsfeedOveral waar een prijsfeed wordt gebruikt om de huidige prijs weer te geven, moet de geschaalde prijs aan eindgebruikers worden getoond.P1
Toon prijshistoriekgrafiekWeerspiegel de geschaalde prijzen in de prijsgrafiekP1

CEXes

VereisteBeschrijvingPrioriteit
Bijhouden van vermenigvuldigerupdatesHoud vermenigvuldigerupdates bij voor tokens die de geschaalde ui-bedragextensie gebruiken.P0
Toon herberekende tokenbalansenToon geschaalde balansen voor handel of liquiditeitsverschaffing in de UI. (backend kan nog steeds ruwe bedragen gebruiken)P0
Ondersteuning voor tokenactiesEindgebruikers moeten actieaantallen invoeren met hun UiAmount-balansen (vermenigvuldiger * ruw bedrag).P0
Historische acties moeten niet opnieuw worden geschaaldHistorische acties zoals transacties moeten worden weergegeven met het nauwkeurige geschaalde bedrag en de prijs op het moment van de actie.P1
Intern bijhouden van ruwe balansenHoud ruwe balansen bij voor onchain-transacties in plaats van geschaalde balansen. Dit is nauwkeuriger en op lange termijn gemakkelijker te beheren.P1
Aanpassing van prijsfeedOveral waar een prijsfeed wordt gebruikt om de huidige prijs weer te geven, moet de geschaalde prijs aan eindgebruikers worden getoond.P1
Toon prijshistoriekgrafiekWeerspiegel de geschaalde prijzen in de prijsgrafiek. Dit omvat het herschalen van historische prijzen naar de huidige vermenigvuldiger.P1
Schaal kostenbasisKosten per aandeel moeten worden geschaald naar de huidige vermenigvuldiger.P1

Is this page helpful?