Suporte à extensão Scaled UI Amount na Solana

Contexto

A extensão Scaled UI Amount permite que emissores de tokens especifiquem um multiplicador a ser usado ao calcular o valor de UI do saldo de tokens de um utilizador. Isso permite que emissores criem tokens de rebase e habilitem coisas como desdobramentos de ações. Esta extensão, assim como a extensão de token com juros, fornece um valor de UI puramente cosmético, o que significa que as equipas precisam fazer algum trabalho adicional para proporcionar uma boa experiência. Cálculos e transferências subjacentes ocorrem todos usando os valores brutos no programa.

Recursos:

• Documentação para programadores
• Código Rust da extensão
• Código Rust de Amount to UI Amount

Resumo

• Utilizadores finais devem interagir com o UIAmount (valor bruto * multiplicador) para o preço do token, saldo do token e valores de tokens sempre que possível
• dApps e fornecedores de serviços devem usar o valor bruto e preços não escalados para todos os cálculos e converter para os utilizadores na interface
• Feeds de preços históricos precisam ser fornecidos tanto para valores escalados quanto não escalados para facilitar a integração
• Valores históricos do multiplicador precisam estar acessíveis para dados históricos precisos

Definições de termos

• Multiplicador: multiplicador estático atualizável que é usado para cálculos de UI Amount
• UIAmount: multiplicador * valor bruto (também conhecido como: valor escalado)
• Valor bruto: valor (também conhecido como: valor não escalado)

Saldo atual

Valor atual para exibição

• Sempre que exibir valores para tokens que usam a extensão scaled UI amount para utilizadores finais, deve usar:
  • UIAmount/UIAmountString (preferencial)
  • Um cálculo manual de valor bruto * multiplicador
  • Recomendamos truncar este valor com base no número de casas decimais que o token possui.
    • Ex: se yUSD tem 6 casas decimais e um utilizador tem um UIAmount de 1.123456789, deve exibir "1.123456"

Onde obter estes dados:

• Para o saldo atual de um utilizador, pode obter informações atualizadas sobre os valores acima chamando getTokenAccountBalance ou getAccountInfo
• Se precisar de saber o UI Amount para um valor arbitrário, pode obter este cálculo chamando a função amountToUiAmountForMintWithoutSimulation (web3.js v1) ou simulando uma transação usando amountToUiAmount.
  • Nota: amountToUiAmount requer uma simulação de transação, o que significa que também precisa de um pagador de taxas válido com saldo. Por isso, esta não deve ser a forma padrão de obter um saldo.

Chamadas RPC

• getTokenAccountBalance
  • Retorna o saldo do token account e as informações do 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
  • Retorna as informações da conta e as informações do 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
}

Atualizar o valor atual

Como os emissores podem atualizar o multiplicador a qualquer momento, pode considerar fazer polling ocasionalmente para manter o saldo da conta atualizado. É improvável que os emissores atualizem este multiplicador mais de uma vez por dia. Se um multiplicador estiver definido para uma data futura, pode fazer polling automaticamente nesse momento de atualização

Valores de tokens em transações (transferências / swaps, etc.)

• Os utilizadores devem inserir valores a serem interpretados como o “UIAmount” escalado. A aplicação que tem de processar isto deve converter para o valor bruto do token para a transação.
  • Se houver problemas de arredondamento, arredonde para baixo e prefira deixar uma pequena quantidade residual em vez de arriscar a falha da transação
  • Para fazer esta conversão, pode usar a função uiAmountToAmountForMintWithoutSimulation (web3.js v1) ou simular uma transação 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 */

• As aplicações devem usar o valor bruto total quando um utilizador solicita realizar uma ação com “máximo” ou “tudo” do seu saldo. Isto garante que não sobra nenhum resíduo.
  • Opcional: Pode considerar fechar automaticamente uma conta quando “máximo” é usado para reembolsar o utilizador do seu depósito de armazenamento

Preço do token

• O preço do token deve ser sempre apresentado como o preço escalado sempre que possível.
• Se é um fornecedor de serviços de feed de preços, como um oráculo, deve expor tanto o preço escalado como o não escalado.
  • Sempre que possível, forneça um SDK/API que abstraia as complexidades da extensão de valor de interface escalado.

Multiplicador atual

• O multiplicador atual pode ser lido a partir do mint do token a qualquer momento chamando getAccountInfo. Adicionalmente, se um multiplicador futuro estiver definido, esta informação também está disponível no mint do token. Recomendamos não mostrar este multiplicador pois pode confundir a experiência do utilizador.

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

Dados históricos

Dados históricos para feed de preços

• Os serviços que fornecem dados históricos devem armazenar e apresentar tanto os preços escalados como os não escalados para a extensão de valor de interface escalado.
• Esperamos que os valores escalados sejam usados com mais frequência, pois isto alinha-se com a forma como o mundo das finanças tradicionais trata gráficos relacionados com tokens com divisões de ações.
• As atualizações do multiplicador podem incluir um carimbo temporal que está no passado. Recomendamos usar o carimbo temporal do bloco para dados históricos.
• Note que o multiplicador ativo pode ser o "multiplicador" ou o "novoMultiplicador" dependendo do carimbo temporal atual e de quando o novo multiplicador está definido para estar ativo.

Dados históricos para valores

• Se você deseja mostrar o saldo transferido no passado, precisa ter acesso ao multiplicador naquele slot específico. Você também pode salvar o UiAmount para transferências conforme processa as transações para evitar fazer esse cálculo no futuro.

Compatibilidade retroativa

• Por padrão, carteiras e aplicativos que não entendem a extensão de valor escalado na interface mostrarão o preço total correto de uma atividade multiplicando o preço não escalado * valor bruto.
• Eles, no entanto, exibiriam o preço não escalado, causando alguma confusão ao usuário.
• Esperamos que isso incentive as equipes a atualizar seus dapps para serem compatíveis com tokens que usam a extensão de valor escalado na interface e estamos felizes em fornecer suporte durante esse processo.

Prioridades de integração recomendadas por plataforma

Requisitos gerais

Carteiras

Exploradores

Agregadores de dados de mercado (ex: CoinGecko, Birdeye)

Provedores de feed de preços

DEXes

CEXes