API de contas históricas da Solana (Beta)

O que é o estado histórico de uma conta?

• Verificar os saldos de tokens de uma carteira em um determinado momento para auditorias, contabilidade ou declarações fiscais
• Depurar uma transação lendo as contas que ela acessou imediatamente antes e depois da execução
• Ler as contas de um protocolo, como pools, cofres ou oráculos, em um slot anterior sem precisar reproduzir o ledger por conta própria

Qual método devo usar?

Disponibilidade e preços

• Planos: planos Business e superiores.
• Custo: 0 créditos por chamada durante a fase beta (preços sujeitos a alterações).
• Limites de taxa: getHistoricalAccountInfo permite 100 solicitações por segundo, com um pico máximo de 100. getHistoricalTokenAccountsByOwner permite 10 solicitações por segundo, com um pico máximo de 10. Esses limites são separados do limite de taxa de RPC do seu plano, e as solicitações que os excederem retornarão HTTP 429. Consulte limites de taxa.
• Rede: somente Mainnet. Chame-os no endpoint padrão da mainnet, https://mainnet.helius-rpc.com, ou no endpoint do Gatekeeper, https://beta.helius-rpc.com. A devnet retorna o erro -32601.

Cobertura de dados

Escolha uma posição no histórico

Leia o estado antes e depois de uma transação

• Depois da transação: consulte os próprios slot e transactionIndex dela.
• Antes da transação: consulte o mesmo slot com transactionIndex menos 1. Se a transação for a primeira do slot (índice 0), consulte o slot anterior sem transactionIndex.

# State of the account right after the transaction at index 10 in slot 445000000
curl https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "getHistoricalAccountInfo",
    "params": [
      "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      { "slot": 445000000, "transactionIndex": 10 },
      { "encoding": "jsonParsed" }
    ]
  }'

Entenda lastUpdatedAt

"lastUpdatedAt": { "slot": 444999837, "transactionIndex": 700 }

• slot e transactionIndex apontam para a última gravação na posição consultada ou antes dela. No exemplo acima, uma consulta ao slot 445.000.000 retornou o estado gravado pela última vez pela transação no índice 700 do slot 444.999.837.
• transactionIndex: null significa que a gravação ocorreu fora de uma transação, como no caso de recompensas de época.
• slot: 444959999 com transactionIndex: null significa que a conta não mudou desde o início da cobertura do histórico. Isso não significa que a conta foi gravada nesse slot.

O que significa um valor null

• Uma resposta null não contém lastUpdatedAt, portanto ela não informa quando a conta foi criada ou encerrada. Para encontrar essas transações, use getTransactionsForAddress.
• Um endereço que nunca existiu também retorna null, não um erro.
• Um slot anterior à cobertura do histórico retorna o erro -32018 para todos os endereços, independentemente de a conta ter existido ou não.

Percorra o histórico da conta em ordem reversa

const url = `https://mainnet.helius-rpc.com/?api-key=${process.env.HELIUS_API_KEY}`;
const COVERAGE_START_SLOT = 444959999;

type Position = { slot?: number; transactionIndex?: number };

async function getAccountHistory(address: string, start: Position = {}, maxStates = 100) {
  const states = [];
  let position = start;

  while (states.length < maxStates) {
    const response = await fetch(url, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        jsonrpc: "2.0",
        id: "1",
        method: "getHistoricalAccountInfo",
        params: [address, position, { encoding: "base64" }],
      }),
    });
    const { result, error } = await response.json();
    if (error) throw new Error(`${error.code}: ${error.message}`);

    const account = result.value;
    if (!account) break; // The account didn't exist before this write

    states.push(account);
    const { slot, transactionIndex } = account.lastUpdatedAt;
    if (slot <= COVERAGE_START_SLOT) break; // Reached the start of history coverage

    // Step to the position just before this write
    position = transactionIndex ? { slot, transactionIndex: transactionIndex - 1 } : { slot: slot - 1 };
  }

  return states; // Newest first
}

• Contas que estão encerradas atualmente retornam null no slot mais recente. Passe uma posição start de quando a conta ainda existia.
• Gravações não relacionadas a transações avançam para o slot anterior. Se a mesma conta também tiver sido gravada por uma transação anterior nesse slot, o percurso ignorará esse estado.
• Para avançar no tempo, liste as transações da conta da mais antiga para a mais recente com getTransactionsForAddress e sortOrder: "asc". Depois, leia o estado nos valores slot e transactionIndex de cada transação.

Contexto da resposta

Paginação consistente

• Passe paginationKey novamente no objeto de configuração para buscar a próxima página.
• Pare somente quando paginationKey for null. Uma página pode ter poucos resultados ou estar vazia e ainda assim haver mais resultados depois dela.
• Fixe slot em todas as páginas. Se você omitir slot, cada página lerá o slot indexado mais recente, e suas páginas poderão vir de momentos diferentes.
• Defina limit entre 1 e 5.000. O padrão é 5.000.

Codificações e dados analisados

• As codificações compatíveis são base64 (o padrão), base64+zstd e jsonParsed. base58 e binary não são compatíveis.
• Contas de tokens jsonParsed usam as casas decimais do mint na posição consultada. Assim, os valores permanecem corretos mesmo que o mint tenha sido alterado desde então. Se o mint não puder ser lido nessa posição, a conta usará base64 como alternativa.
• dataSlice funciona da mesma forma que em getAccountInfo.

Commitment

Erros

Perguntas frequentes

Como obtenho o estado de uma conta da Solana em um slot específico?

Posso ler uma conta entre duas transações no mesmo slot?

Até onde posso retroceder em uma consulta?

Quais planos incluem os métodos de contas históricas?

Quais são os limites de taxa?

Como obtenho todos os estados anteriores de uma conta?

Preciso de um novo SDK?

Próximas etapas