Supportare l'estensione Scaled UI Amount su Solana

Contesto

L'estensione Scaled UI Amount consente agli emittenti di token di specificare un moltiplicatore da utilizzare quando si calcola l'importo UI del saldo token di un utente. Questo permette agli emittenti di creare token con rebase e di abilitare operazioni come gli split azionari. Questa estensione, come l'estensione per i token fruttiferi di interessi, fornisce un importo UI puramente cosmetico, il che significa che i team devono fare un lavoro aggiuntivo per offrire una buona esperienza. I calcoli sottostanti e i trasferimenti avvengono tutti utilizzando gli importi raw nel programma.

Risorse:

• Documentazione per sviluppatori
• Codice Rust dell'estensione
• Codice Rust per la conversione da Amount a UI Amount

In breve

• Gli utenti finali dovrebbero interagire con l'UIAmount (importo raw * moltiplicatore) per il prezzo del token, il saldo del token e gli importi del token quando possibile
• Le dApp e i fornitori di servizi dovrebbero utilizzare l'importo raw e i prezzi non scalati per tutti i calcoli e convertirli per gli utenti solo nell'interfaccia
• I feed di prezzo storici devono essere forniti sia per gli importi scalati che per quelli non scalati per una più facile 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'importo UI
• UIAmount: moltiplicatore * importo raw (noto anche come: importo scalato)
• Raw Amount: importo (noto anche come: importo non scalato)

Saldo attuale

Importo attuale per la visualizzazione

• Ogni volta che mostri importi per token che utilizzano l'estensione scaled UI amount agli utenti finali dovresti utilizzare:
  • UIAmount/UIAmountString (preferito)
  • Un calcolo manuale di importo raw * moltiplicatore
  • Consigliamo di troncare questo valore in base al numero di decimali che il token possiede.
    • 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 in tempo reale di un utente puoi ottenere informazioni aggiornate sugli importi sopra indicati chiamando getTokenAccountBalance o getAccountInfo
• Se hai bisogno di conoscere l'importo UI 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 che significa che ha anche bisogno di un pagatore di commissioni valido con saldo. Per questo motivo, questo non dovrebbe essere il modo predefinito per ottenere un saldo.

Chiamate RPC

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

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
  • Restituisce le informazioni sull'account e le informazioni sul mint

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

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 automaticamente effettuare 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 convertirlo nell'importo raw del token per la transazione.
  • Se ci sono problemi di arrotondamento, arrotonda per difetto e preferisci lasciare una piccola quantità di dust piuttosto che rischiare che la transazione fallisca
  • Per effettuare questa conversione puoi utilizzare la funzione uiAmountToAmountForMintWithoutSimulation (web3.js v1) o simulare 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 raw totale quando un utente richiede di eseguire un'azione con "max" o "tutto" il proprio saldo. Questo garantisce che non rimanga dust.
  • Opzionale: Puoi considerare di chiudere automaticamente un account quando viene utilizzato "max" per rimborsare all'utente il suo deposito di storage

Prezzo del token

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

Moltiplicatore attuale

• Il moltiplicatore attuale 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é potrebbe confondere l'UX.

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 dei prezzi

• I servizi che forniscono dati storici dovrebbero memorizzare e mostrare sia i prezzi scalati che quelli non scalati per l'estensione degli importi UI scalati.
• Ci aspettiamo che gli importi scalati vengano utilizzati più frequentemente poiché questo si allinea con come il mondo della finanza tradizionale tratta i grafici relativi ai token con stock split.

Dati storici per gli importi

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

Compatibilità con le versioni precedenti

• Per impostazione predefinita, i wallet e le applicazioni che non comprendono l'estensione degli importi UI scalati mostreranno il prezzo totale corretto di un'attività moltiplicando il prezzo non scalato * importo raw.
• Tuttavia, mostrerebbero il prezzo non scalato causando una certa confusione all'utente.
• Speriamo che questo incoraggi i team ad aggiornare le loro dapp per essere compatibili con i token che utilizzano l'estensione degli importi UI scalati 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)

Fornitori di feed di prezzi

DEX