Ondersteuning voor 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 stelt uitgevers in staat om rebasing-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 verrichten om een goede ervaring te bieden. Onderliggende berekeningen en overdrachten vinden allemaal plaats met de ruwe bedragen in het programma.

Bronnen:

• Ontwikkelaarsdocumentatie
• Extensie Rust-code
• Amount to UI Amount Rust-code

Samenvatting

• Eindgebruikers moeten waar mogelijk interactie hebben met het UIAmount (ruw bedrag * vermenigvuldiger) voor de tokenprijs, het tokensaldo en tokenbedragen
• dApps en serviceproviders moeten het ruwe bedrag en niet-geschaalde prijzen gebruiken voor alle berekeningen en deze aan de rand voor gebruikers converteren
• Historische prijsfeeds moeten worden verstrekt voor zowel geschaalde als niet-geschaalde bedragen voor eenvoudigere integratie
• Historische vermenigvuldigingswaarden moeten toegankelijk zijn voor nauwkeurige historische gegevens

Definities van termen

• Vermenigvuldiger: statische bij te werken 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

• Telkens wanneer je bedragen weergeeft voor tokens die de scaled UI amount-extensie gebruiken aan eindgebruikers, moet je een van de volgende gebruiken:
  • 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.
    • Voorbeeld: als yUSD 6 decimalen heeft en een gebruiker een UIAmount van 1,123456789 heeft, moet je “1,123456” weergeven

Waar deze gegevens te vinden:

• Voor het actuele saldo van een gebruiker kun je bijgewerkte informatie over bovenstaande bedragen verkrijgen door getTokenAccountBalance of getAccountInfo aan te roepen
• Als je het UI-bedrag voor een willekeurig bedrag moet weten, kun je deze berekening verkrijgen door de amountToUiAmountForMintWithoutSimulation (web3.js v1) functie aan te roepen of door een transactie te simuleren met amountToUiAmount.
  • Let op: amountToUiAmount vereist een transactiesimulatie, wat betekent dat er ook een geldige fee payer met saldo nodig is. Daarom zou dit niet de standaardmanier moeten zijn om een saldo op te halen.

RPC-aanroepen

• getTokenAccountBalance
  • Retourneert het token account-saldo en de mint-informatie

$ 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
  • Retourneert de account-informatie en de mint-informatie

$ 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 moment kunnen bijwerken, kun je overwegen om periodiek te pollen om het accountsaldo actueel te houden. Uitgevers zullen deze vermenigvuldiger waarschijnlijk niet vaker dan eens per dag bijwerken. Als een vermenigvuldiger is ingesteld voor een toekomstige datum, kun je automatisch pollen op dit bijwerktijdstip

Tokenbedragen in transacties (transfers / swaps etc)

• Gebruikers moeten bedragen invoeren die geïnterpreteerd moeten worden 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 stof achter dan het risico te lopen dat de transactie mislukt
  • Om deze conversie uit te voeren 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 onbewerkte bedrag gebruiken wanneer een gebruiker een actie wil uitvoeren met 'max' of 'alles' van hun saldo. Dit zorgt ervoor dat er geen restant 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-bedragextensie wegneemt.

Huidige vermenigvuldiger

• De huidige vermenigvuldiger kan op elk moment worden uitgelezen van de token mint door getAccountInfo aan te roepen. Bovendien is deze informatie ook beschikbaar vanuit de token mint als er een toekomstige vermenigvuldiger is ingesteld. We raden aan om deze vermenigvuldiger niet te tonen omdat dit de UX 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

• Services die historische gegevens leveren moeten zowel de geschaalde als niet-geschaalde prijzen voor de geschaalde UI-bedragextensie opslaan en beschikbaar stellen.
• We verwachten dat geschaalde bedragen het vaakst worden gebruikt omdat dit aansluit bij hoe de traditionele financiële wereld grafieken behandelt die gerelateerd zijn aan tokens met aandelensplitsingen.
• Vermenigvuldiger-updates kunnen een tijdstempel bevatten die in het verleden ligt. We raden aan om de bloktijdstempel te gebruiken voor historische gegevens.
• Merk op dat de actieve vermenigvuldiger de 'multiplier' of de 'newMultiplier' kan zijn, afhankelijk van de huidige tijdstempel en wanneer de nieuwe vermenigvuldiger actief wordt.

Historische gegevens voor bedragen

• Als je het in het verleden overgedragen saldo wilt weergeven, heb je toegang nodig tot de vermenigvuldiger op dat 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 tonen wallets en applicaties die de geschaalde UI-bedragextensie niet begrijpen de juiste totaalprijs van een activiteit door de niet-geschaalde prijs * ruwe bedrag te vermenigvuldigen.
• Ze zouden echter de niet-geschaalde prijs weergeven, wat enige verwarring bij gebruikers veroorzaakt.
• We hopen dat dit teams aanmoedigt om hun dapps bij te werken zodat ze compatibel zijn met tokens die de geschaalde UI-bedragextensie gebruiken en we bieden graag ondersteuning tijdens dit proces.

Aanbevolen integratieprioriteiten per platform

Algemene vereisten

Wallets

Explorers

Marktdata-aggregators (bijv. CoinGecko)

Prijsfeedproviders

DEXes

CEXes