Supporto dell'estensione Scaled UI Amount su Solana

Contesto

L'estensione Scaled UI Amount consente agli emittenti di token di specificare un moltiplicatore da utilizzare nel calcolo dell'importo UI del saldo token di un utente. Questo permette agli emittenti di creare token rebasing e di abilitare funzionalità come i frazionamenti azionari. Questa estensione, come l'estensione interest bearing token, fornisce un importo UI puramente cosmetico, il che significa che i team devono svolgere del lavoro aggiuntivo per offrire una buona esperienza. I calcoli e i trasferimenti sottostanti avvengono tutti utilizzando gli importi grezzi nel programma.

Risorse:

• Documentazione per sviluppatori
• Codice Rust dell'estensione
• Codice Rust Amount to UI Amount

In breve

• Gli utenti finali dovrebbero interagire con l'UIAmount (importo grezzo * moltiplicatore) per il prezzo del token, il saldo del token e gli importi dei token quando possibile
• Le dApp e i fornitori di servizi dovrebbero utilizzare l'importo grezzo e i prezzi non scalati per tutti i calcoli e convertire per gli utenti al momento della visualizzazione
• I feed di prezzo storici devono essere forniti sia per gli importi scalati che non scalati per facilitare l'integrazione
• I valori storici del moltiplicatore devono essere accessibili per dati storici accurati

Definizioni dei termini

• Moltiplicatore: moltiplicatore statico aggiornabile utilizzato per i calcoli dell'UI Amount
• UIAmount: moltiplicatore * importo grezzo (noto anche come: importo scalato)
• Importo grezzo: importo (noto anche come: importo non scalato)

Saldo attuale

Importo attuale per la visualizzazione

• Ogni volta che visualizzi importi per token che utilizzano l'estensione scaled UI amount agli utenti finali dovresti usare:
  • UIAmount/UIAmountString (preferito)
  • Un calcolo manuale di importo grezzo * moltiplicatore
  • Consigliamo di troncare questo valore in base al numero di decimali del token.
    • Es: se yUSD ha 6 decimali e un utente ha un UIAmount di 1.123456789 dovresti visualizzare "1.123456"

Dove ottenere questi dati:

• Per il saldo live di un utente puoi ottenere informazioni aggiornate sugli importi sopra indicati chiamando getTokenAccountBalance o getAccountInfo
• Se hai bisogno di conoscere l'UI Amount per un importo arbitrario puoi ottenere questo calcolo chiamando la funzione amountToUiAmountForMintWithoutSimulation (web3.js v1) o simulando una transazione usando amountToUiAmount.
  • Nota: amountToUiAmount richiede una simulazione di transazione, il che significa che necessita anche di un fee payer valido con saldo. Per questo motivo, non dovrebbe essere il modo predefinito per ottenere un saldo.

Chiamate RPC

• getTokenAccountBalance
  • Restituisce il saldo del token account e le informazioni del mint

$ 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
  • Restituisce le informazioni dell'account e le informazioni del mint

$ 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
}

Aggiornamento dell'importo corrente

Poiché gli emittenti possono aggiornare il moltiplicatore in qualsiasi momento, puoi considerare di effettuare polling occasionalmente per mantenere aggiornato il saldo dell'account. È improbabile che gli emittenti aggiornino questo moltiplicatore più di una volta al giorno. Se un moltiplicatore è impostato per una data futura, puoi effettuare automaticamente il polling a questo orario di aggiornamento

Importi dei token nelle transazioni (trasferimenti / swap ecc.)

• Gli utenti dovrebbero inserire importi da interpretare come “UIAmount” scalato. L'app che deve elaborare questo dovrebbe convertire nell'importo token grezzo per la transazione.
  • Se ci sono problemi di arrotondamento, arrotonda per difetto e preferisci lasciare una piccola quantità residua piuttosto che rischiare il fallimento della transazione
  • Per effettuare questa conversione puoi usare la funzione uiAmountToAmountForMintWithoutSimulation (web3.js v1) o simulando una transazione usando 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 */

• Le app dovrebbero utilizzare l'importo totale grezzo quando un utente richiede di eseguire un'azione con "max" o "tutto" il proprio saldo. Questo garantisce che non rimanga alcun residuo.
  • Opzionale: puoi considerare di chiudere automaticamente un account quando viene utilizzato "max" per rimborsare l'utente del deposito di archiviazione

Prezzo del token

• Il prezzo del token dovrebbe essere sempre visualizzato come prezzo scalato ovunque possibile.
• Se sei un fornitore di servizi di feed di prezzo, come un oracolo, dovresti esporre sia il prezzo scalato che quello non scalato.
  • Ovunque possibile, fornisci un SDK/API che astragga le complessità dell'estensione dell'importo UI scalato.

Moltiplicatore corrente

• Il moltiplicatore corrente può essere letto dal mint del token in qualsiasi momento chiamando getAccountInfo. Inoltre, se è impostato un moltiplicatore futuro, questa informazione è disponibile anche dal mint del token. Consigliamo di non mostrare questo moltiplicatore poiché può confondere l'esperienza utente.

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
*/

Dati storici

Dati storici per il feed di prezzo

• I servizi che forniscono dati storici dovrebbero memorizzare e mostrare sia i prezzi scalati che quelli non scalati per l'estensione dell'importo UI scalato.
• Ci aspettiamo che gli importi scalati vengano utilizzati più frequentemente poiché questo si allinea con il modo in cui il mondo della finanza tradizionale tratta i grafici relativi ai token con frazionamenti azionari.
• Gli aggiornamenti del moltiplicatore possono includere un timestamp che è nel passato. Consigliamo di utilizzare il timestamp del blocco per i dati storici.
• Nota che il moltiplicatore attivo può essere il "moltiplicatore" o il "nuovoMoltiplicatore" a seconda del timestamp corrente e di quando il nuovo moltiplicatore è impostato per essere attivo.

Dati storici per gli importi

• Se desideri mostrare il saldo trasferito in passato, hai bisogno di accedere al moltiplicatore in quel dato slot. Puoi anche salvare l'UiAmount per i trasferimenti mentre elabori le transazioni per evitare di fare questo calcolo in futuro.

Retrocompatibilità

• Per impostazione predefinita, i wallet e le applicazioni che non comprendono l'estensione scaled UI amount mostreranno il prezzo totale corretto di un'attività moltiplicando il prezzo non scalato * importo grezzo.
• Tuttavia, visualizzerebbero il prezzo non scalato causando una certa confusione nell'utente.
• Speriamo che questo incoraggi i team ad aggiornare le loro dapp per essere compatibili con i token che utilizzano l'estensione scaled UI amount e siamo felici di fornire supporto durante questo processo.

Priorità di integrazione consigliate per piattaforma

Requisiti generali

Wallet

Explorer

Aggregatori di dati di mercato (es: CoinGecko, Birdeye)

Fornitori di feed dei prezzi

DEX

CEX