Soporte de la extensión Scaled UI Amount en Solana

Contexto

La extensión Scaled UI Amount permite a los emisores de tokens especificar un multiplicador que se utilizará al calcular el monto UI del saldo de tokens de un usuario. Esto permite a los emisores crear tokens de rebase y habilitar cosas como divisiones de acciones. Esta extensión, al igual que la extensión de token con interés, proporciona un monto UI puramente cosmético, lo que significa que los equipos necesitan hacer trabajo adicional para proporcionar una buena experiencia. Los cálculos y transferencias subyacentes ocurren utilizando los montos sin procesar en el programa.

Recursos:

• Documentación para desarrolladores
• Código Rust de la extensión
• Código Rust de Amount to UI Amount

Resumen

• Los usuarios finales deben interactuar con el UIAmount (monto sin procesar * multiplicador) para el precio del token, saldo del token y montos de tokens siempre que sea posible
• Las dApps y proveedores de servicios deben usar el monto sin procesar y precios no escalados para todos los cálculos y convertir para los usuarios en el extremo
• Los feeds de precios históricos deben proporcionarse tanto para montos escalados como no escalados para una integración más fácil
• Los valores históricos del multiplicador deben ser accesibles para datos históricos precisos

Definiciones de términos

• Multiplicador: multiplicador estático actualizable que se utiliza para cálculos de UI Amount
• UIAmount: multiplicador * monto sin procesar (también conocido como: monto escalado)
• Raw Amount: monto (también conocido como: monto no escalado)

Saldo actual

Monto actual para visualización

• Cada vez que muestres montos para tokens que utilizan la extensión scaled UI amount a usuarios finales, debes usar:
  • UIAmount/UIAmountString (preferido)
  • Un cálculo manual de monto sin procesar * multiplicador
  • Recomendamos truncar este valor según el número de decimales que tenga el token.
    • Ej: si yUSD tiene 6 decimales y un usuario tiene un UIAmount de 1.123456789, debes mostrar “1.123456”

Dónde obtener estos datos:

• Para el saldo en vivo de un usuario puedes obtener información actualizada sobre las cantidades anteriores llamando a getTokenAccountBalance o getAccountInfo
• Si necesitas conocer el UI Amount para una cantidad arbitraria puedes obtener este cálculo llamando a la función amountToUiAmountForMintWithoutSimulation (web3.js v1) o simulando una transacción usando amountToUiAmount.
  • Nota: amountToUiAmount requiere una simulación de transacción, lo que significa que también necesita un pagador de comisiones válido con saldo. Por esto, esta no debería ser la forma predeterminada de obtener un saldo.

Llamadas RPC

• getTokenAccountBalance
  • Devuelve el saldo del token account y la información del 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
  • Devuelve la información de la cuenta y la información del 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
}

Actualizar la cantidad actual

Dado que los emisores pueden actualizar el multiplicador en cualquier momento, puedes considerar hacer polling ocasionalmente para mantener actualizado el saldo de la cuenta. Es poco probable que los emisores actualicen este multiplicador más de una vez al día. Si se establece un multiplicador para una fecha futura, puedes hacer polling automáticamente en ese momento de actualización

Cantidades de tokens en transacciones (transferencias / swaps, etc.)

• Los usuarios deben ingresar cantidades que se interpretarán como el “UIAmount” escalado. La aplicación que tenga que procesar esto debe convertir a la cantidad de token sin procesar para la transacción.
  • Si hay problemas de redondeo, redondea hacia abajo y prefiere dejar una pequeña cantidad de polvo en lugar de arriesgar que la transacción falle
  • Para hacer esta conversión puedes usar la función uiAmountToAmountForMintWithoutSimulation (web3.js v1) o simulando una transacción 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 */

• Las aplicaciones deben usar la cantidad bruta total cuando un usuario solicita realizar una acción con “máx” o “todo” su saldo. Esto garantiza que no quede ningún residuo.
  • Opcional: Puedes considerar cerrar automáticamente una cuenta cuando se usa “máx” para reembolsar al usuario su depósito de almacenamiento

Precio del token

• El precio del token siempre debe mostrarse como el precio escalado siempre que sea posible.
• Si eres un proveedor de servicios de fuentes de precios, como un oráculo, debes exponer tanto el precio escalado como el no escalado.
  • Siempre que sea posible, proporciona un SDK/API que abstraiga las complejidades de la extensión de cantidad de UI escalada.

Multiplicador actual

• El multiplicador actual se puede leer desde el mint del token en cualquier momento llamando a getAccountInfo. Además, si se establece un multiplicador futuro, esta información también está disponible desde el mint del token. Recomendamos no mostrar este multiplicador ya que puede confundir la experiencia de usuario.

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

Datos históricos

Datos históricos para fuentes de precios

• Los servicios que proporcionan datos históricos deben almacenar y mostrar tanto los precios escalados como los no escalados para la extensión de cantidad de UI escalada.
• Esperamos que las cantidades escaladas se usen con mayor frecuencia, ya que esto se alinea con la forma en que el mundo de las finanzas tradicionales trata los gráficos relacionados con tokens con divisiones de acciones.
• Las actualizaciones del multiplicador pueden incluir una marca de tiempo que está en el pasado. Recomendamos usar la marca de tiempo del bloque para datos históricos.
• Ten en cuenta que el multiplicador activo puede ser el "multiplicador" o el "nuevoMultiplicador" dependiendo de la marca de tiempo actual y de cuándo se establece que el nuevo multiplicador esté activo.

Datos históricos para cantidades

• Si deseas mostrar el saldo transferido en el pasado, necesitas acceso al multiplicador en ese slot determinado. También puedes guardar el UiAmount para las transferencias a medida que procesas las transacciones para evitar hacer este cálculo en el futuro.

Compatibilidad hacia atrás

• Por defecto, las wallets y aplicaciones que no comprenden la extensión de cantidad ui escalada mostrarán el precio total correcto de una actividad multiplicando el precio no escalado * cantidad bruta.
• Sin embargo, mostrarían el precio no escalado causando cierta confusión en el usuario.
• Esperamos que esto anime a los equipos a actualizar sus dapps para que sean compatibles con tokens que utilizan la extensión de cantidad ui escalada y estamos encantados de proporcionar soporte durante este proceso.

Prioridades de integración recomendadas por plataforma

Requisitos generales

Wallets

Exploradores

Agregadores de datos de mercado (ej: CoinGecko, Birdeye)

Proveedores de feeds de precios

DEXes

CEXes