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 con rebasing e di abilitare operazioni come gli split azionari. Questa estensione, come l'estensione per i token fruttiferi di interessi, fornisce un importo UI puramente estetico, il che significa che i team devono svolgere un lavoro aggiuntivo per offrire una buona esperienza. I calcoli sottostanti e i trasferimenti avvengono tutti utilizzando gli importi non elaborati 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 non elaborato * 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 non elaborato e i prezzi non scalati per tutti i calcoli e convertirli per gli utenti solo nell'interfaccia
• I feed di prezzi storici devono essere forniti sia per gli importi scalati che per quelli non scalati per facilitare l'integrazione
• I valori storici dei moltiplicatori devono essere accessibili per dati storici accurati

Definizione dei termini

• Moltiplicatore: moltiplicatore statico aggiornabile utilizzato per i calcoli dell'importo UI
• UIAmount: moltiplicatore * importo non elaborato (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 agli utenti finali gli importi per i token che utilizzano l'estensione Scaled UI Amount dovresti utilizzare:
  • UIAmount/UIAmountString (preferito)
  • Un calcolo manuale di importo non elaborato * 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 attivo 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 / scambi ecc.)

• Gli utenti dovrebbero inserire importi da interpretare come "UIAmount" scalato. L'app che deve elaborare questo dovrebbe convertire nell'importo grezzo del token per la transazione.
  • Se ci sono problemi di arrotondamento, arrotonda per difetto e preferisci lasciare una piccola quantità di polvere piuttosto che rischiare che la transazione fallisca
  • Per fare questa conversione puoi usare 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 totale lordo quando un utente richiede di eseguire un'azione con "max" o "tutto" del proprio saldo. Questo garantisce che non rimangano residui.
  • Opzionale: Puoi considerare la chiusura automatica di un account quando viene utilizzato "max" per rimborsare all'utente il suo deposito di archiviazione

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 prezzo, 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 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'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 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 come il mondo della finanza tradizionale tratta i grafici relativi ai token con split azionari.

Dati storici per 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 dell'importo UI scalato mostreranno il prezzo totale corretto di un'attività moltiplicando il prezzo non scalato * per l'importo raw.
• Tuttavia, visualizzerebbero il prezzo non scalato causando una certa confusione per l'utente.
• Ci auguriamo che questo incoraggi i team ad aggiornare le loro dapp per renderle compatibili con i token che utilizzano l'estensione dell'importo UI scalato 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 prezzo

DEX