Skip to main content

Common JSON Data Structures for Koii RPC Methods

Various Koii RPC methods will return more complex responses as structured JSON objects, filled with specific keyed values.

The most common of these JSON data structures include:

Transactions

Transactions are quite different from those on other blockchains.

The JSON structure of a transaction is defined as follows:

  • signatures: <array[string]> - A list of base-58 encoded signatures applied to the transaction. The list is always of length message.header.numRequiredSignatures and not empty. The signature at index i corresponds to the public key at index i in message.accountKeys. The first one is used as the transaction id
  • message: <object> - Defines the content of the transaction.
    • accountKeys: <array[string]> - List of base-58 encoded public keys used by the transaction, including by the instructions and for signatures. The first message.header.numRequiredSignatures public keys must sign the transaction.
    • header: <object> - Details the account types and signatures required by the transaction.
      • numRequiredSignatures: <number> - The total number of signatures required to make the transaction valid. The signatures must match the first numRequiredSignatures of message.accountKeys.
      • numReadonlySignedAccounts: <number> - The last numReadonlySignedAccounts of the signed keys are read-only accounts. Programs may process multiple transactions that load read-only accounts within a single PoH entry, but are not permitted to credit or debit lamports or modify account data. Transactions targeting the same read-write account are evaluated sequentially.
      • numReadonlyUnsignedAccounts: <number> - The last numReadonlyUnsignedAccounts of the unsigned keys are read-only accounts.
    • recentBlockhash: <string> - A base-58 encoded hash of a recent block in the ledger used to prevent transaction duplication and to give transactions lifetimes.
    • instructions: <array[object]> - List of program instructions that will be executed in sequence and committed in one atomic transaction if all succeed.
      • programIdIndex: <number> - Index into the message.accountKeys array indicating the program account that executes this instruction.
      • accounts: <array[number]> - List of ordered indices into the message.accountKeys array indicating which accounts to pass to the program.
      • data: <string> - The program input data encoded in a base-58 string.
    • addressTableLookups: <array[object]|undefined> - List of address table lookups used by a transaction to dynamically load addresses from on-chain address lookup tables. Undefined if maxSupportedTransactionVersion is not set.
      • accountKey: <string> - base-58 encoded public key for an address lookup table account.
      • writableIndexes: <array[number]> - List of indices used to load addresses of writable accounts from a lookup table.
      • readonlyIndexes: <array[number]> - List of indices used to load addresses of readonly accounts from a lookup table.

Inner Instructions

The Koii runtime records the cross-program instructions that are invoked during transaction processing and makes these available for greater transparency of what was executed on-chain per transaction instruction. Invoked instructions are grouped by the originating transaction instruction and are listed in order of processing.

The JSON structure of inner instructions is defined as a list of objects in the following structure:

  • index: number - Index of the transaction instruction from which the inner instruction(s) originated
  • instructions: <array[object]> - Ordered list of inner program instructions that were invoked during a single transaction instruction.
    • programIdIndex: <number> - Index into the message.accountKeys array indicating the program account that executes this instruction.
    • accounts: <array[number]> - List of ordered indices into the message.accountKeys array indicating which accounts to pass to the program.
    • data: <string> - The program input data encoded in a base-58 string.

Token Balances

The JSON structure of token balances is defined as a list of objects in the following structure:

  • accountIndex: <number> - Index of the account in which the token balance is provided for.
  • mint: <string> - Pubkey of the token's mint.
  • owner: <string|undefined> - Pubkey of token balance's owner.
  • programId: <string|undefined> - Pubkey of the Token program that owns the account.
  • uiTokenAmount: <object> -
    • amount: <string> - Raw amount of tokens as a string, ignoring decimals.
    • decimals: <number> - Number of decimals configured for token's mint.
    • uiAmount: <number|null> - Token amount as a float, accounting for decimals. DEPRECATED
    • uiAmountString: <string> - Token amount as a string, accounting for decimals.