thorchainV1.go

Overview

The [thorchainV1.go](/projects/291/69226) file provides Go client functionality to interact with the Thorchain blockchain's RPC endpoints, specifically to retrieve block results at a given block height. It wraps and extends Tendermint's RPC client response types to provide easy access to blockchain events emitted during block processing.

This file primarily defines:

• A specialized HTTP client (HTTPClient) that embeds a generic Cosmos SDK HTTP client.

• A wrapped result type (ResultBlockResults) to handle block results in a Thorchain-specific context.

• Methods to fetch block results from the Thorchain node and extract block events for further processing.

This layer abstracts the complexity of Tendermint RPC calls and JSON unmarshaling, providing a clean interface for higher-level application components to consume blockchain event data.

Detailed Documentation

Package: thorchainV1

This package contains client-side types and methods to interact with Thorchain blockchain nodes, focusing on fetching block results.

Types

HTTPClient

type HTTPClient struct {
	*cosmos.HTTPClient
}

• Description:
  HTTPClient is a wrapper around the generic Cosmos SDK HTTP client, embedding it to extend or specialize HTTP RPC calls for Thorchain V1 endpoints.

• Usage:
  Use this client to perform Thorchain-specific RPC queries, such as fetching block results.

ResultBlockResults

type ResultBlockResults struct {
	*coretypes.ResultBlockResults
}

• Description:
  Wraps Tendermint's ResultBlockResults to provide additional convenience methods tailored for Thorchain.

• Methods:

  • GetBlockEvents() []cosmos.ABCIEvent

    Extracts and returns block events emitted during the EndBlock phase of block processing.

    • Returns:
      Slice of cosmos.ABCIEvent representing all events emitted at the end of the block.

    • Details:
      The method iterates over the underlying Tendermint EndBlockEvents, converts their attributes from byte arrays to strings, and returns them in the Cosmos SDK event format.

    • Example:

      var blockResults *ResultBlockResults = ...
      events := blockResults.GetBlockEvents()
      for _, event := range events {
          fmt.Println("Event type:", event.Type)
          for _, attr := range event.Attributes {
              fmt.Printf("  %s = %s\n", attr.Key, attr.Value)
          }
      }
      

Functions

NewHTTPClient

func NewHTTPClient(httpClient *cosmos.HTTPClient) *HTTPClient

• Description:
  Constructs a new Thorchain V1 HTTP client by embedding an existing Cosmos SDK HTTP client.

• Parameters:

  • httpClient (*cosmos.HTTPClient): The underlying Cosmos SDK HTTP client to wrap.

• Returns:
  Pointer to a new HTTPClient instance.

• Usage Example:

  baseClient := cosmos.NewHTTPClient("https://thorchain-node.example.com")
  thorchainClient := thorchainV1.NewHTTPClient(baseClient)
  

(*HTTPClient) BlockResults

func (c *HTTPClient) BlockResults(height int) (cosmos.BlockResults, error)

• Description:
  Fetches the block results for the block at the given height from the Thorchain node.

• Parameters:

  • height (int): The height of the block for which to fetch results.

• Returns:

  • cosmos.BlockResults: Interface representing the block results, wrapped in ResultBlockResults.

  • error: Non-nil if the request or unmarshaling fails.

• Implementation Details:

  • The method sends an HTTP GET request to the /block_results endpoint with a query parameter height.

  • The raw RPC response is unmarshaled into Tendermint's ResultBlockResults struct.

  • Errors are wrapped with context using the github.com/pkg/errors package.

• Usage Example:

  client := thorchainV1.NewHTTPClient(existingCosmosClient)
  blockHeight := 12345
  blockResults, err := client.BlockResults(blockHeight)
  if err != nil {
      log.Fatalf("Failed to fetch block results: %v", err)
  }
  events := blockResults.(*thorchainV1.ResultBlockResults).GetBlockEvents()
  for _, event := range events {
      fmt.Println(event.Type, event.Attributes)
  }
  

Important Implementation Details

• The HTTPClient relies on the embedded cosmos.HTTPClient which presumably handles low-level HTTP communication and request building.

• The response from /block_results is parsed into Tendermint's ResultBlockResults type, but the wrapper ResultBlockResults converts events into the project's cosmos.ABCIEvent format for compatibility.

• The code carefully converts byte slice attributes (from Tendermint) into strings in the event attributes, ensuring usability.

• Errors from HTTP requests and unmarshaling are wrapped using errors.Wrapf to provide detailed context.

Interaction with Other System Components

• cosmos.HTTPClient:
  This file extends the generic Cosmos SDK HTTP client to add Thorchain-specific RPC call support. The cosmos package likely provides common blockchain client utilities.

• Tendermint RPC Types (coretypes.ResultBlockResults):
  Uses Tendermint's standard RPC response structures to interpret raw node responses.

• cosmos.ABCIEvent and cosmos.ABCIEventAttribute:
  These types are used to represent blockchain events in a standardized manner consistent across the overall system.

• Higher-level Components:
  Other parts of the Thorchain client or application layers likely call BlockResults to obtain event data for business logic, analytics, or UI display.

Visual Diagram

classDiagram
    class HTTPClient {
        +BlockResults(height int) (cosmos.BlockResults, error)
    }
    HTTPClient o-- cosmos.HTTPClient : embeds

    class ResultBlockResults {
        +GetBlockEvents() []cosmos.ABCIEvent
    }
    ResultBlockResults o-- coretypes.ResultBlockResults : wraps

    HTTPClient --> ResultBlockResults : returns

• HTTPClient wraps cosmos.HTTPClient and provides the BlockResults method.

• BlockResults returns a ResultBlockResults instance.

• ResultBlockResults wraps Tendermint's ResultBlockResults and provides event extraction through GetBlockEvents().

Summary

The [thorchainV1.go](/projects/291/69226) file is a specialized client module designed for fetching and processing block results from Thorchain nodes using Tendermint RPC. It provides a clean abstraction to obtain block events, handling the nuances of RPC communication, JSON unmarshaling, and event attribute conversion. This file plays a key role in enabling higher-level Thorchain applications to consume blockchain event data reliably and efficiently.