Estruturas de Dados JSON Comuns para Métodos RPC da Solana

Vários métodos RPC da Solana retornam respostas mais complexas como objetos JSON estruturados, preenchidos com valores específicos.

As estruturas de dados JSON mais comuns incluem:

• transações
• instruções internas
• saldos de tokens

Transações

As transações são bastante diferentes daquelas em outras blockchains. Certifique-se de rever Anatomia de uma Transação para aprender sobre transações na Solana.

JSON

A estrutura JSON de uma transação é definida da seguinte forma:

• message: <object> - Define o conteúdo da transação.
  • accountKeys: <array[string]> - Lista de chaves públicas codificadas em base-58 usadas pela transação, incluindo as instruções e assinaturas. As primeiras message.header.numRequiredSignatures chaves públicas devem assinar a transação.
  • header: <object> - Detalha os tipos de conta e assinaturas exigidas pela transação.
    • numRequiredSignatures: <number> - O número total de assinaturas necessárias para tornar a transação válida. As assinaturas devem corresponder às primeiras numRequiredSignatures de message.accountKeys.
    • numReadonlySignedAccounts: <number> - As últimas numReadonlySignedAccounts das chaves assinadas são contas somente leitura. Os programas podem processar várias transações que carregam contas somente leitura dentro de uma única entrada PoH, mas não têm permissão para creditar ou debitar lamports ou modificar dados da conta. Transações direcionadas à mesma conta de leitura e escrita são avaliadas sequencialmente.
    • numReadonlyUnsignedAccounts: <number> - As últimas numReadonlyUnsignedAccounts das chaves não assinadas são contas somente leitura.
  • recentBlockhash: <string> - Um hash codificado em base-58 de um bloco recente no ledger usado para evitar duplicação de transações e para dar às transações tempo de vida.
  • instructions: <array[object]> - Lista de instruções de programa que serão executadas em sequência e confirmadas em uma transação atômica se todas tiverem sucesso.
    • programIdIndex: <number> - Índice no array message.accountKeys indicando a conta do programa que executa esta instrução.
    • accounts: <array[number]> - Lista de índices ordenados no array message.accountKeys indicando quais contas passar para o programa.
    • data: <string> - Os dados de entrada do programa codificados em uma string base-58.
  • addressTableLookups: <array[object]|undefined> - Lista de consultas de tabela de endereços usadas por uma transação para carregar dinamicamente endereços de tabelas de consulta de endereços on-chain. Indefinido se maxSupportedTransactionVersion não estiver definido.
    • accountKey: <string> - chave pública codificada em base-58 para uma conta de tabela de consulta de endereços.
    • writableIndexes: <array[number]> - Lista de índices usados para carregar endereços de contas graváveis de uma tabela de consulta.
    • readonlyIndexes: <array[number]> - Lista de índices usados para carregar endereços de contas somente leitura de uma tabela de consulta.
• signatures: <array[string]> - Uma lista de assinaturas codificadas em base-58 aplicadas à transação. A lista sempre tem o comprimento message.header.numRequiredSignatures e não é vazia. A assinatura no índice i corresponde à chave pública no índice i em message.accountKeys. A primeira é usada como o id da transação.

JSON analisado

A estrutura analisada em JSON de uma transação segue uma estrutura similar ao formato JSON regular, com análise adicional de informações de conta e instruções:

• message: <object> - Define o conteúdo da transação.
  • accountKeys: <array[object]> - Lista de informações de contas usadas pela transação.
    • pubkey: <string> - A chave pública codificada em base-58 da conta.
    • signer: <boolean> - Indica se a conta é um signatário obrigatório da transação.
    • writable: <boolean> - Indica se a conta é gravável.
    • source: <string> - Fonte da conta (transação ou tabela de consulta).
  • recentBlockhash: <string> - Um hash codificado em base-58 de um bloco recente no ledger usado para prevenir duplicação de transações e para dar vida útil às transações.
  • instructions: <array[object]> - Lista de instruções de programa analisadas.
    • program: <string> - O nome do programa sendo chamado.
    • programId: <string> - A chave pública codificada em base-58 do programa.
    • stackHeight: <number|null> - A altura da pilha da instrução.
    • parsed: <object> - Dados analisados específicos do programa.
      • type: <string> - O tipo de instrução (ex: "transfer").
      • info: <object> - Informações de instrução analisadas específicas para o programa e tipo de instrução.
• signatures: <array[string]> - Uma lista de assinaturas codificadas em base-58 aplicadas à transação.

Metadados de status da transação

• err: <object|null> - Erro se a transação falhou, null se a transação foi bem-sucedida. Definições de TransactionError
• fee: <u64> - taxa cobrada por esta transação, como inteiro u64
• preBalances: <array> - array de saldos de conta u64 antes da transação ser processada
• postBalances: <array> - array de saldos de conta u64 depois que a transação foi processada
• innerInstructions: <array|null> - Lista de instruções internas ou null se o registro de instruções internas não estava habilitado durante esta transação
• preTokenBalances: <array|undefined> - Lista de saldos de token antes da transação ser processada ou omitida se o registro de saldo de token ainda não estava habilitado durante esta transação
• postTokenBalances: <array|undefined> - Lista de saldos de token depois que a transação foi processada ou omitida se o registro de saldo de token ainda não estava habilitado durante esta transação
• logMessages: <array|null> - array de mensagens de log em string ou null se o registro de mensagens de log não estava habilitado durante esta transação
• rewards: <array|null> - recompensas em nível de transação; um array de objetos JSON contendo:
  • pubkey: <string> - A chave pública, como string codificada em base-58, da conta que recebeu a recompensa
  • lamports: <i64>- número de lamports de recompensa creditados ou debitados pela conta, como um i64
  • postBalance: <u64> - saldo da conta em lamports após a recompensa ter sido aplicada
  • rewardType: <string|undefined> - tipo de recompensa: "fee", "rent", "voting", "staking"
  • commission: <u8|undefined> - comissão da conta de voto quando a recompensa foi creditada, presente apenas para recompensas de votação e staking
• DEPRECATED: status: <object> - Status da transação
  • "Ok": <null> - A transação foi bem-sucedida
  • "Err": <ERR> - A transação falhou com TransactionError
• loadedAddresses: <object|undefined> - Endereços de transação carregados de tabelas de consulta de endereços. Indefinido se maxSupportedTransactionVersion não estiver definido nos parâmetros da solicitação, ou se a codificação jsonParsed estiver definida nos parâmetros da solicitação.
  • writable: <array[string]> - Lista ordenada de endereços codificados em base-58 para contas carregadas graváveis
  • readonly: <array[string]> - Lista ordenada de endereços codificados em base-58 para contas carregadas somente leitura
• returnData: <object|undefined> - os dados de retorno mais recentes gerados por uma instrução na transação, com os seguintes campos:
  • programId: <string> - o programa que gerou os dados de retorno, como Pubkey codificada em base-58
  • data: <[string, encoding]> - os próprios dados de retorno, como dados binários codificados em base-64
• computeUnitsConsumed: <u64|undefined> - número de unidades de computação consumidas pela transação
• version: <"legacy"|number|undefined> - Versão da transação. Indefinido se maxSupportedTransactionVersion não estiver definido nos parâmetros da solicitação.
• signatures: <array> - presente se "signatures" forem solicitadas para detalhes da transação; um array de strings de assinaturas, correspondendo à ordem da transação no bloco

Instruções Internas

O runtime da Solana registra as instruções entre programas que são invocadas durante o processamento de transações e as disponibiliza para maior transparência sobre o que foi executado na blockchain por instrução de transação. As instruções invocadas são agrupadas pela instrução de transação de origem e são listadas em ordem de processamento.

A estrutura JSON das instruções internas é definida como uma lista de objetos na seguinte estrutura:

• index: number - Índice da instrução de transação da qual as instruções internas se originaram
• instructions: <array[object]> - Lista ordenada de instruções internas do programa que foram invocadas durante uma única instrução de transação.
  • programIdIndex: <number> - Índice no array message.accountKeys indicando a conta do programa que executa esta instrução.
  • accounts: <array[number]> - Lista de índices ordenados no array message.accountKeys indicando quais contas passar para o programa.
  • data: <string> - Os dados de entrada do programa codificados em uma string base-58.

Saldos de Token

A estrutura JSON dos saldos de token é definida como uma lista de objetos na seguinte estrutura:

• accountIndex: <number> - Índice da conta para a qual o saldo do token é fornecido.
• mint: <string> - Pubkey da mint do token.
• owner: <string|undefined> - Pubkey do proprietário do saldo do token.
• programId: <string|undefined> - Pubkey do Token Program que possui a conta.
• uiTokenAmount: <object> -
  • amount: <string> - Quantidade bruta de tokens como string, ignorando decimais.
  • decimals: <number> - Número de decimais configurados para a mint do token.
  • uiAmount: <number|null> - Quantidade de token como float, considerando decimais. OBSOLETO
  • uiAmountString: <string> - Quantidade de token como string, considerando decimais.