Guia de integração de valor de UI escalado

Suportando a extensão de valor de UI escalado no Solana

Contexto

A extensão de valor de UI escalado permite que os emissores de tokens especifiquem um multiplicador a ser usado ao calcular o valor de UI do saldo de token de um usuário. Isso permite que os emissores criem tokens de rebase e possibilitem coisas como desdobramentos de ações. Esta extensão, como a extensão de token com rendimento de juros, fornece um valor de UI puramente cosmético, o que significa que as equipes precisam fazer um trabalho adicional para fornecer uma boa experiência. Os cálculos e transferências subjacentes ocorrem usando os valores brutos no programa.

Recursos:

Resumo

  • Os usuários finais devem interagir com o UIAmount (valor bruto * multiplicador) para o preço do token, saldo do token e quantidades de token sempre que possível
  • dApps e provedores de serviços devem usar o valor bruto e preços não escalados para todos os cálculos e converter para os usuários na borda
  • 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 usado para cálculos de valor de UI
  • 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 você exibir valores para tokens que usam a extensão de valor de UI escalado para usuários finais, você deve usar:
    • UIAmount/UIAmountString (preferido)
    • Um cálculo manual de valor bruto * multiplicador
    • Recomendamos truncar este valor com base no número de decimais que o token possui.
      • Ex: se yUSD tem 6 decimais e um usuário tem um UIAmount de 1.123456789, você deve exibir "1.123456"

Onde obter estes dados:

  • Para o saldo em tempo real de um usuário, você pode obter informações atualizadas sobre os valores acima chamando getTokenAccountBalance ou getAccountInfo
  • Se você precisa saber o Valor UI para um valor arbitrário, você 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 taxa 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
}

Atualizando o valor atual

Como os emissores podem atualizar o multiplicador a qualquer momento, você 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 for definido para uma data futura, você pode automaticamente fazer polling neste momento de atualização

Valores de token em transações (transferências / trocas etc)

  • Os usuários devem inserir valores para serem interpretados como o "UIAmount" escalado. O aplicativo que precisa processar isso 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 de poeira em vez de arriscar a falha da transação
    • Para fazer esta conversão, você pode usar a função uiAmountToAmountForMintWithoutSimulation (web3.js v1) ou simular uma transação usando amountToUiAmount.
web3js-uiAmountToAmountForMintWithoutSimulation.ts
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 */
  • Os aplicativos devem usar o valor bruto total quando um usuário solicita fazer uma ação com "máximo" ou "todo" o seu saldo. Isso garante que não haja poeira restante.
    • Opcional: Você pode considerar fechar automaticamente uma conta quando "máximo" é usado para reembolsar o usuário de seu depósito de armazenamento

Preço do token

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

Multiplicador atual

  • O multiplicador atual pode ser lido da cunhagem do token a qualquer momento chamando getAccountInfo. Além disso, se um multiplicador futuro estiver definido, esta informação também está disponível na cunhagem do token. Recomendamos não mostrar este multiplicador, pois pode confundir a UX.
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

  • Serviços que fornecem dados históricos devem armazenar e apresentar tanto os preços escalados quanto os não escalados para a extensão de valor UI escalado.
  • Esperamos que os valores escalados sejam usados com mais frequência, pois isso se alinha com como o mundo financeiro tradicional trata gráficos relacionados a tokens com divisões de ações.

Dados históricos para valores

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

Compatibilidade retroativa

  • Por padrão, carteiras e aplicações que não compreendem a extensão de valor de UI escalada mostrarão o preço total correto de uma atividade multiplicando o preço não escalado * quantidade bruta.
  • No entanto, eles exibiriam o preço não escalado, causando alguma confusão para o usuário.
  • Esperamos que isso incentive as equipes a atualizarem seus dapps para serem compatíveis com tokens que usam a extensão de valor de UI escalada e estamos felizes em fornecer suporte durante este processo.

Prioridades de integração recomendadas por plataforma

Requisitos gerais

RequisitoDescriçãoPrioridade
Suporte a ações do usuário usando UiAmountTodas as ações do usuário devem ser inseridas em UiAmount quando o UiAmount estiver habilitado em todo o aplicativo. Se o UiAmount não estiver visível no aplicativo, eles devem usar quantidades brutas até que o aplicativo seja atualizado.P0

Carteiras

RequisitoDescriçãoPrioridade
Exibir saldo escaladoMostrar a quantidade escalada (uiAmount) como o saldo principal.P0
Suporte para transferências de tokensOs usuários finais devem inserir valores de transferência com seus saldos escalados (quantidade bruta * saldo).P0
Exibir preço à vistaExibir o preço à vista escalado para os usuáriosP0
Metadados do histórico de transaçõesMostrar a quantidade escalada (UIAmount) para cada transferência sempre que possível.P1
Mostrar atualizações de multiplicador no histórico de transaçõesQuando ocorrerem atualizações de multiplicador, mostrar isso como um evento no histórico de transações do usuário, incluindo o valor ganhoP2
Exibir gráfico de histórico de preçosRefletir os preços escalados no gráfico de preçosP1
Integração/DicasOferecer dicas ou integração para educar os usuários sobre tokens que usam a extensão de valor de ui escaladaP2

Exploradores

RequisitoDescriçãoPrioridade
Melhorias na página de detalhes do tokenExibir metadados como capitalização de mercado escalonada total e multiplicador atualP0
Exibir saldo escalonado para saldosExibir saldos escalonados (UiAmount) para saldos atuais.P0
Exibir saldo escalonado para transaçõesExibir saldos escalonados (UiAmount) para valores de transferência em transações históricas.P0
Exibir preço escalonado para transaçõesExibir preços escalonados para transações anterioresP1
Analisar e exibir corretamente transações de atualização de multiplicadorMostrar corretamente detalhes sobre a atualização do multiplicadorP2

Agregadores de dados de mercado (Ex: CoinGecko)

RequisitoDescriçãoPrioridade
Atualizações de API para dados escalonadosEstender a funcionalidade da API para incluir mudanças de multiplicador ao longo do tempo, bem como o feed de preços escalonados.P0
Fornecimento total com ajuste escalonadoAo exibir o fornecimento total e a capitalização total de mercado, levar em conta os saldos escalonadosP0
Rastreamento histórico de preçosFornecer um gráfico histórico de preços usando o preço escalonado ao longo do tempo.P1
Rastreamento histórico de multiplicadorFornecer marcadores históricos de atualizações de multiplicador para tokens com rendimento de juros.P2
Conteúdo educacional ou explicaçõesIncluir breves descrições ou dicas explicando como funcionam os tokens escalonados.P2

Provedores de feed de preços

RequisitoDescriçãoPrioridade
Feeds de preços escalonados e não escalonadosFornecer feeds de preços tanto para preços escalonados quanto não escalonados.P0
Dados históricos de multiplicadorOferecer APIs com mudanças históricas de multiplicador.P0
Dados históricos de preçosOferecer APIs com preços históricos baseados em valores escalonados e não escalonados.P0

DEXes

RequisitoDescriçãoPrioridade
Exibir saldos de tokens rebaseadosMostrar saldos escalados para negociação ou provisão de liquidez na interface. (o backend ainda pode usar valores brutos)P0
Suporte para ações de tokensOs usuários finais devem inserir valores de ação com seus saldos UiAmount (multiplicador * valor bruto).P0
Adaptação do feed de preçosEm qualquer lugar onde um feed de preços é usado para exibir o preço atual, fornecer o preço escalado aos usuários finais.P1
Exibir gráfico de histórico de preçosRefletir os preços escalados no gráfico de preçosP1

CEXes

RequisitoDescriçãoPrioridade
Rastrear atualizações de multiplicadorRastrear atualizações de multiplicador para tokens que usam a extensão de valor escalado na interface.P0
Exibir saldos de tokens rebaseadosMostrar saldos escalados para negociação ou provisão de liquidez na interface. (o backend ainda pode usar valores brutos)P0
Suporte para ações de tokensOs usuários finais devem inserir valores de ação com seus saldos UiAmount (multiplicador * valor bruto).P0
Ações históricas não devem ser reescaladasAções históricas como negociações devem ser exibidas usando o valor escalado preciso e o preço no momento da ação.P1
Rastrear internamente saldos brutosRastrear saldos brutos para transações na blockchain em vez de saldos escalados. Isso será mais preciso e mais fácil de gerenciar a longo prazo.P1
Adaptação do feed de preçosEm qualquer lugar onde um feed de preços é usado para exibir o preço atual, fornecer o preço escalado aos usuários finais.P1
Exibir gráfico de histórico de preçosRefletir os preços escalados no gráfico de preços. Isso inclui reescalar preços históricos para o multiplicador atual.P1
Escalar base de custoO custo por ação deve ser escalado para o multiplicador atual.P1

Is this page helpful?