Prise en charge de l'extension Scaled UI Amount sur Solana

Contexte

L'extension Scaled UI Amount permet aux émetteurs de tokens de spécifier un multiplicateur à utiliser lors du calcul du montant UI du solde de token d'un utilisateur. Cela permet aux émetteurs de créer des tokens à rebasage et d'activer des opérations comme les divisions d'actions. Cette extension, comme l'extension de token portant intérêt, fournit un montant UI purement cosmétique, ce qui signifie que les équipes doivent effectuer un travail supplémentaire pour offrir une bonne expérience. Les calculs sous-jacents et les transferts s'effectuent tous en utilisant les montants bruts dans le programme.

Ressources :

• Documentation développeur
• Code Rust de l'extension
• Code Rust de conversion Amount to UI Amount

En résumé

• Les utilisateurs finaux devraient interagir avec l'UIAmount (montant brut * multiplicateur) pour le prix du token, le solde du token et les montants du token dans la mesure du possible
• Les dApps et les fournisseurs de services devraient utiliser le montant brut et les prix non mis à l'échelle pour tous les calculs et effectuer la conversion pour les utilisateurs au niveau de l'interface
• Les flux de prix historiques doivent être fournis pour les montants mis à l'échelle et non mis à l'échelle pour faciliter l'intégration
• Les valeurs historiques des multiplicateurs doivent être accessibles pour des données historiques précises

Définitions des termes

• Multiplicateur : multiplicateur statique modifiable utilisé pour les calculs de montant UI
• UIAmount : multiplicateur * montant brut (aussi appelé : montant mis à l'échelle)
• Montant brut : montant (aussi appelé : montant non mis à l'échelle)

Solde actuel

Montant actuel pour l'affichage

• Chaque fois que vous affichez des montants pour les tokens qui utilisent l'extension scaled UI amount aux utilisateurs finaux, vous devriez utiliser soit :
  • UIAmount/UIAmountString (préféré)
  • Un calcul manuel du montant brut * multiplicateur
  • Nous recommandons de tronquer cette valeur en fonction du nombre de décimales que le token possède.
    • Ex : si yUSD a 6 décimales et qu'un utilisateur a un UIAmount de 1,123456789, vous devriez afficher « 1,123456 »

Où obtenir ces données :

• Pour le solde en direct d'un utilisateur, vous pouvez obtenir des informations mises à jour sur les montants ci-dessus en appelant soit getTokenAccountBalance soit getAccountInfo
• Si vous avez besoin de connaître le montant UI pour un montant arbitraire, vous pouvez obtenir ce calcul en appelant la fonction amountToUiAmountForMintWithoutSimulation (web3.js v1) ou en simulant une transaction utilisant amountToUiAmount.
  • Remarque : amountToUiAmount nécessite une simulation de transaction, ce qui signifie qu'il a également besoin d'un payeur de frais valide avec un solde. Pour cette raison, ce ne devrait pas être la méthode par défaut pour obtenir un solde.

Appels RPC

• getTokenAccountBalance
  • Renvoie le solde du token account et les informations du 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
  • Renvoie les informations du compte et les informations du 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"
  }
} */

Mise à jour du montant actuel

Étant donné que les émetteurs peuvent mettre à jour le multiplicateur à tout moment, vous pouvez envisager de faire un sondage occasionnel afin de maintenir le solde du compte à jour. Les émetteurs sont peu susceptibles de mettre à jour ce multiplicateur plus d'une fois par jour. Si un multiplicateur est défini pour une date future, vous pouvez automatiquement effectuer un sondage à ce moment de mise à jour

Montants de tokens dans les transactions (transferts / échanges, etc.)

• Les utilisateurs doivent saisir des montants à interpréter comme "UIAmount" mis à l'échelle. L'application qui doit traiter cela doit convertir en montant brut de token pour la transaction.
  • S'il y a des problèmes d'arrondi, arrondissez vers le bas et préférez laisser une infime quantité de poussière plutôt que de risquer l'échec de la transaction
  • Pour effectuer cette conversion, vous pouvez utiliser la fonction uiAmountToAmountForMintWithoutSimulation (web3.js v1) ou simuler une transaction utilisant 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 */

• Les applications doivent utiliser le montant brut total lorsqu'un utilisateur demande d'effectuer une action avec "max" ou "tout" de son solde. Cela garantit qu'il ne reste pas de poussière.
  • Optionnel : vous pouvez envisager de fermer automatiquement un compte lorsque "max" est utilisé pour rembourser à l'utilisateur son dépôt de stockage

Prix du jeton

• Le prix du jeton doit toujours être affiché comme le prix mis à l'échelle dans la mesure du possible.
• Si vous êtes un fournisseur de service de flux de prix, comme un oracle, vous devriez exposer à la fois le prix mis à l'échelle et non mis à l'échelle.
  • Dans la mesure du possible, fournissez un SDK/API qui abstrait les complexités d'extension du montant UI mis à l'échelle.

Multiplicateur actuel

• Le multiplicateur actuel peut être lu à partir du mint du jeton à tout moment en appelant getAccountInfo. De plus, si un multiplicateur futur est défini, cette information est également disponible à partir du mint du jeton. Nous recommandons de ne pas afficher ce multiplicateur car il peut rendre l'expérience utilisateur confuse.

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

Données historiques

Données historiques pour le flux de prix

• Les services qui fournissent des données historiques doivent stocker et présenter à la fois les prix mis à l'échelle et non mis à l'échelle pour l'extension du montant UI mis à l'échelle.
• Nous nous attendons à ce que les montants mis à l'échelle soient utilisés le plus fréquemment car cela correspond à la façon dont le monde de la finance traditionnelle traite les graphiques liés aux jetons avec des fractionnements d'actions.

Données historiques pour les montants

• Si vous souhaitez afficher le solde transféré dans le passé, vous avez besoin d'accéder au multiplicateur à ce slot donné. Vous pouvez également enregistrer le UiAmount pour les transferts lorsque vous traitez les transactions afin d'éviter de faire ce calcul à l'avenir.

Compatibilité ascendante

• Par défaut, les portefeuilles et applications qui ne comprennent pas l'extension de montant UI mis à l'échelle afficheront le prix total correct d'une activité en multipliant le prix non mis à l'échelle * le montant brut.
• Ils afficheraient cependant le prix non mis à l'échelle, ce qui pourrait créer une certaine confusion chez l'utilisateur.
• Nous espérons que cela encouragera les équipes à mettre à jour leurs dapps pour qu'elles soient compatibles avec les jetons qui utilisent l'extension de montant UI mis à l'échelle, et nous sommes heureux de fournir un support pendant ce processus.

Priorités d'intégration recommandées par plateforme

Exigences générales

Portefeuilles

Explorateurs

Agrégateurs de données de marché (Ex : CoinGecko)

Fournisseurs de flux de prix

DEX