Estructuras de datos JSON comunes para métodos RPC de Solana

Varios métodos RPC de Solana devolverán respuestas más complejas como objetos JSON estructurados, llenos de valores con claves específicas.

Las estructuras de datos JSON más comunes incluyen:

• transacciones
• instrucciones internas
• saldos de tokens

Transacciones

Las transacciones son bastante diferentes de las de otras blockchains. Asegúrate de revisar Anatomía de una transacción para aprender sobre las transacciones en Solana.

JSON

La estructura JSON de una transacción se define de la siguiente manera:

• message: <object> - Define el contenido de la transacción.
  • accountKeys: <array[string]> - Lista de claves públicas codificadas en base-58 utilizadas por la transacción, incluyendo las instrucciones y para firmas. Las primeras message.header.numRequiredSignatures claves públicas deben firmar la transacción.
  • header: <object> - Detalla los tipos de cuenta y las firmas requeridas por la transacción.
    • numRequiredSignatures: <number> - El número total de firmas requeridas para hacer válida la transacción. Las firmas deben coincidir con las primeras numRequiredSignatures de message.accountKeys.
    • numReadonlySignedAccounts: <number> - Las últimas numReadonlySignedAccounts de las claves firmadas son cuentas de solo lectura. Los programas pueden procesar múltiples transacciones que cargan cuentas de solo lectura dentro de una sola entrada PoH, pero no tienen permitido acreditar o debitar lamports o modificar datos de la cuenta. Las transacciones dirigidas a la misma cuenta de lectura-escritura se evalúan secuencialmente.
    • numReadonlyUnsignedAccounts: <number> - Las últimas numReadonlyUnsignedAccounts de las claves no firmadas son cuentas de solo lectura.
  • recentBlockhash: <string> - Un hash codificado en base-58 de un bloque reciente en el libro mayor utilizado para prevenir la duplicación de transacciones y para dar a las transacciones un tiempo de vida.
  • instructions: <array[object]> - Lista de instrucciones de programa que serán ejecutadas en secuencia y confirmadas en una transacción atómica si todas tienen éxito.
    • programIdIndex: <number> - Índice en el array message.accountKeys que indica la cuenta del programa que ejecuta esta instrucción.
    • accounts: <array[number]> - Lista de índices ordenados en el array message.accountKeys que indican qué cuentas pasar al programa.
    • data: <string> - Los datos de entrada del programa codificados en una cadena base-58.
  • addressTableLookups: <array[object]|undefined> - Lista de búsquedas en tablas de direcciones utilizadas por una transacción para cargar dinámicamente direcciones desde tablas de búsqueda de direcciones en la cadena. No definido si maxSupportedTransactionVersion no está establecido.
    • accountKey: <string> - clave pública codificada en base-58 para una cuenta de tabla de búsqueda de direcciones.
    • writableIndexes: <array[number]> - Lista de índices utilizados para cargar direcciones de cuentas escribibles desde una tabla de búsqueda.
    • readonlyIndexes: <array[number]> - Lista de índices utilizados para cargar direcciones de cuentas de solo lectura desde una tabla de búsqueda.
• signatures: <array[string]> - Una lista de firmas codificadas en base-58 aplicadas a la transacción. La lista siempre tiene una longitud de message.header.numRequiredSignatures y no está vacía. La firma en el índice i corresponde a la clave pública en el índice i en message.accountKeys. La primera se utiliza como el id de transacción.

JSON analizado

La estructura analizada JSON de una transacción sigue una estructura similar al formato JSON regular, con análisis adicional de la información de cuentas e instrucciones:

• message: <object> - Define el contenido de la transacción.
  • accountKeys: <array[object]> - Lista de información de cuentas utilizadas por la transacción.
    • pubkey: <string> - La clave pública codificada en base-58 de la cuenta.
    • signer: <boolean> - Indica si la cuenta es un firmante requerido para la transacción.
    • writable: <boolean> - Indica si la cuenta es escribible.
    • source: <string> - Origen de la cuenta (transacción o tabla de búsqueda).
  • recentBlockhash: <string> - Un hash codificado en base-58 de un bloque reciente en el libro mayor utilizado para prevenir la duplicación de transacciones y para dar vida útil a las transacciones.
  • instructions: <array[object]> - Lista de instrucciones de programa analizadas.
    • program: <string> - El nombre del programa que se está llamando.
    • programId: <string> - La clave pública codificada en base-58 del programa.
    • stackHeight: <number|null> - La altura de la pila de la instrucción.
    • parsed: <object> - Datos analizados específicos del programa.
      • type: <string> - El tipo de instrucción (por ejemplo, "transfer").
      • info: <object> - Información de instrucción analizada específica para el programa y tipo de instrucción.
• signatures: <array[string]> - Una lista de firmas codificadas en base-58 aplicadas a la transacción.

Metadatos de estado de transacción

• err: <object|null> - Error si la transacción falló, null si la transacción tuvo éxito. Definiciones de TransactionError
• fee: <u64> - tarifa que se cobró por esta transacción, como entero u64
• preBalances: <array> - matriz de saldos de cuenta u64 antes de que se procesara la transacción
• postBalances: <array> - matriz de saldos de cuenta u64 después de que se procesara la transacción
• innerInstructions: <array|null> - Lista de instrucciones internas o null si el registro de instrucciones internas no estaba habilitado durante esta transacción
• preTokenBalances: <array|undefined> - Lista de saldos de tokens antes de que se procesara la transacción u omitido si el registro de saldo de tokens aún no estaba habilitado durante esta transacción
• postTokenBalances: <array|undefined> - Lista de saldos de tokens después de que se procesara la transacción u omitido si el registro de saldo de tokens aún no estaba habilitado durante esta transacción
• logMessages: <array|null> - matriz de mensajes de registro de cadena o null si el registro de mensajes de registro no estaba habilitado durante esta transacción
• rewards: <array|null> - recompensas a nivel de transacción; una matriz de objetos JSON que contienen:
  • pubkey: <string> - La clave pública, como cadena codificada en base-58, de la cuenta que recibió la recompensa
  • lamports: <i64>- número de lamports de recompensa acreditados o debitados por la cuenta, como i64
  • postBalance: <u64> - saldo de la cuenta en lamports después de que se aplicara la recompensa
  • rewardType: <string|undefined> - tipo de recompensa: "fee", "rent", "voting", "staking"
  • commission: <u8|undefined> - comisión de cuenta de voto cuando se acreditó la recompensa, solo presente para recompensas de votación y staking
• OBSOLETO: status: <object> - Estado de la transacción
  • "Ok": <null> - La transacción fue exitosa
  • "Err": <ERR> - La transacción falló con TransactionError
• loadedAddresses: <object|undefined> - Direcciones de transacción cargadas desde tablas de búsqueda de direcciones. No definido si maxSupportedTransactionVersion no está establecido en los parámetros de solicitud, o si la codificación jsonParsed está establecida en los parámetros de solicitud.
  • writable: <array[string]> - Lista ordenada de direcciones codificadas en base-58 para cuentas cargadas escribibles
  • readonly: <array[string]> - Lista ordenada de direcciones codificadas en base-58 para cuentas cargadas de solo lectura
• returnData: <object|undefined> - los datos de retorno más recientes generados por una instrucción en la transacción, con los siguientes campos:
  • programId: <string> - el programa que generó los datos de retorno, como Pubkey codificada en base-58
  • data: <[string, encoding]> - los propios datos de retorno, como datos binarios codificados en base-64
• computeUnitsConsumed: <u64|undefined> - número de unidades de cómputo consumidas por la transacción
• version: <"legacy"|number|undefined> - Versión de la transacción. No definido si maxSupportedTransactionVersion no está establecido en los parámetros de solicitud.
• signatures: <array> - presente si se solicitan "signatures" para detalles de transacción; una matriz de cadenas de firmas, correspondientes al orden de transacción en el bloque

Instrucciones internas

El entorno de ejecución de Solana registra las instrucciones entre programas que se invocan durante el procesamiento de transacciones y las pone a disposición para una mayor transparencia de lo que se ejecutó en la cadena por instrucción de transacción. Las instrucciones invocadas se agrupan por la instrucción de transacción original y se enumeran en orden de procesamiento.

La estructura JSON de las instrucciones internas se define como una lista de objetos en la siguiente estructura:

• index: number - Índice de la instrucción de transacción de la cual se originaron las instrucciones internas
• instructions: <array[object]> - Lista ordenada de instrucciones internas del programa que fueron invocadas durante una única instrucción de transacción.
  • programIdIndex: <number> - Índice en el array message.accountKeys que indica la cuenta del programa que ejecuta esta instrucción.
  • accounts: <array[number]> - Lista de índices ordenados en el array message.accountKeys que indica qué cuentas pasar al programa.
  • data: <string> - Los datos de entrada del programa codificados en una cadena base-58.

Saldos de tokens

La estructura JSON de los saldos de tokens se define como una lista de objetos en la siguiente estructura:

• accountIndex: <number> - Índice de la cuenta para la cual se proporciona el saldo del token.
• mint: <string> - Pubkey del mint del token.
• owner: <string|undefined> - Pubkey del propietario del saldo del token.
• programId: <string|undefined> - Pubkey del Token Program que posee la cuenta.
• uiTokenAmount: <object> -
  • amount: <string> - Cantidad bruta de tokens como cadena, ignorando decimales.
  • decimals: <number> - Número de decimales configurados para el mint del token.
  • uiAmount: <number|null> - Cantidad de tokens como número flotante, teniendo en cuenta los decimales. OBSOLETO
  • uiAmountString: <string> - Cantidad de tokens como cadena, teniendo en cuenta los decimales.