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 d'interface utilisateur du solde de tokens d'un utilisateur. Cela permet aux émetteurs de créer des tokens à rebasage et d'activer des fonctionnalités telles que les fractionnements d'actions. Cette extension, comme l'extension de token portant intérêt, fournit un montant d'interface utilisateur 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 se produisent tous en utilisant les montants bruts dans le programme.

Ressources :

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

En résumé

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

Définitions des termes

• Multiplicateur : multiplicateur statique modifiable utilisé pour les calculs de UI Amount
• 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 tokens qui utilisent l'extension scaled UI amount aux utilisateurs finaux, vous devez utiliser soit :
  • UIAmount/UIAmountString (recommandé)
  • Un calcul manuel du montant brut * multiplicateur
  • Nous recommandons de tronquer cette valeur en fonction du nombre de décimales du token.
    • Ex : si yUSD a 6 décimales et qu'un utilisateur a un UIAmount de 1.123456789, vous devez afficher “1.123456”

Où obtenir ces données :

• Pour le solde en temps réel d'un utilisateur, vous pouvez obtenir des informations mises à jour sur les montants ci-dessus en appelant soit getTokenAccountBalance soit getAccountInfo
• Si vous devez 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 en 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 compte de jetons et les informations du 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
  • Renvoie les informations du compte et les informations du 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
}

Mise à jour du montant actuel

Étant donné que 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 jetons dans les transactions (transferts / échanges, etc.)

• Les utilisateurs doivent saisir des montants à interpréter comme le “UIAmount” mis à l'échelle. L'application qui doit traiter cela doit convertir en montant de jeton brut 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 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” son solde. Cela garantit qu'il ne reste aucune poussière.
  • Optionnel : vous pouvez envisager de fermer automatiquement un compte lorsque “max” est utilisé pour rembourser l'utilisateur de 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 services de flux de prix, tel qu'un oracle, vous devez 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 de montant d'interface utilisateur mis à l'échelle.

Multiplicateur actuel

• Le multiplicateur actuel peut être lu à partir du mint de jeton à tout moment en appelant getAccountInfo. De plus, si un multiplicateur futur est défini, cette information est également disponible à partir du mint de 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 de montant d'interface utilisateur mis à l'échelle.
• Nous nous attendons à ce que les montants mis à l'échelle soient utilisés le plus fréquemment car cela s'aligne sur la façon dont le monde de la finance traditionnelle traite les graphiques liés aux jetons avec des fractionnements d'actions.
• Les mises à jour du multiplicateur peuvent inclure un horodatage qui est dans le passé. Nous recommandons d'utiliser l'horodatage du bloc pour les données historiques.
• Notez que le multiplicateur actif peut être le "multiplicateur" ou le "nouveauMultiplicateur" selon l'horodatage actuel et le moment où le nouveau multiplicateur est défini pour être actif.

Données historiques pour les montants

• Si vous souhaitez afficher le solde transféré dans le passé, vous devez avoir accès au multiplicateur à ce slot donné. Vous pouvez également enregistrer le UiAmount pour les transferts au fur et à mesure que 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 * montant brut.
• Ils afficheraient cependant le prix non mis à l'échelle, ce qui pourrait causer une certaine confusion chez l'utilisateur.
• Nous espérons que cela encouragera les équipes à mettre à jour leurs dapps pour être 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, Birdeye)

Fournisseurs de flux de prix

DEX

CEX