Prise en charge de l'extension Montant UI mis à l'échelle sur Solana

Contexte

L'extension Scaled UI Amount permet aux émetteurs de jetons de spécifier un multiplicateur à utiliser lors du calcul du montant UI du solde de jetons d'un utilisateur. Cela permet aux émetteurs de créer des jetons à rebasage et d'activer des opérations comme les divisions d'actions. Cette extension, comme l'extension de jeton 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 et transferts sous-jacents s'effectuent tous en utilisant les montants bruts dans le programme.

Ressources :

• Documentation développeur
• Code Rust de l'extension
• Code Rust de conversion du montant en montant UI

En bref

• Les utilisateurs finaux devraient interagir avec le UIAmount (montant brut × multiplicateur) pour le prix du jeton, le solde du jeton et les montants du jeton chaque fois que 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 convertir pour les utilisateurs à la périphérie
• Les flux de prix historiques doivent être fournis pour les montants mis à l'échelle et non mis à l'échelle pour une intégration plus facile
• 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 des jetons 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 du jeton.
    • 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, cela 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 sur le 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 sur le 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

Comme les émetteurs peuvent mettre à jour le multiplicateur à tout moment, vous pouvez envisager de faire des sondages occasionnels 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 qui seront interprétés comme "UIAmount" mis à l'échelle. L'application qui doit traiter cela doit convertir en montant brut de token pour la transaction.
  • En cas de 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 en 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 token

• Le prix du token 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 de l'extension scaled UI amount.

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 cela 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 devraient stocker et présenter à la fois les prix mis à l'échelle et non mis à l'échelle pour l'extension de montant UI mis à l'échelle.
• Nous nous attendons à ce que les montants mis à l'échelle soient utilisés 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.

Rétrocompatibilité

• 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 soutien 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