types.go

Overview

The `types.go` file defines core data structures and interfaces related to blockchain blocks and transactions within the Thorchain module. It primarily provides abstractions over block data and transaction results as used in the context of CometBFT (formerly Tendermint) blockchain consensus engine events and Cosmos SDK transaction handling.

This file encapsulates:

A generic Block interface for accessing block metadata (hash, height, timestamp).
Concrete implementations of the Block interface wrapping CometBFT block types (ResultBlock, NewBlock).
A ResultTx structure representing a blockchain transaction as derived from block results, including metadata, events, Cosmos SDK message details, and formatting logic.

Overall, this file acts as a bridge between raw blockchain event data and the higher-level Cosmos transaction processing components.

Detailed Descriptions

Interface: `Block`

type Block interface {
	Hash() string
	Height() int64
	Timestamp() int64
}

Purpose

Defines a minimal interface for blockchain block metadata access.

Methods

Method	Returns	Description
`Hash()`	`string`	Returns the block hash as a string.
`Height()`	`int64`	Returns the block height (block number).
`Timestamp()`	`int64`	Returns the block timestamp in milliseconds since Unix epoch.

Usage Example

func PrintBlockInfo(b Block) {
    fmt.Printf("Block %d at %d ms with hash %s\n", b.Height(), b.Timestamp(), b.Hash())
}

Struct: `ResultBlock`

type ResultBlock struct {
	*cometbfttypes.Block
}

Purpose

Wraps the `cometbfttypes.Block` type to implement the `Block` interface.

Methods

Method	Returns	Description
`Hash()`	`string`	Returns the block hash using CometBFT's `Block.Hash()` method.
`Height()`	`int64`	Returns the block height stored in the embedded block.
`Timestamp()`	`int64`	Returns the block time as Unix milliseconds.

Implementation Details

Delegates to the embedded cometbfttypes.Block for all property retrieval.
Converts block time (time.Time) to Unix milliseconds.

Usage Example

var cb *cometbfttypes.Block = getCometBlock()
rb := ResultBlock{Block: cb}
fmt.Println(rb.Hash())

Struct: `NewBlock`

type NewBlock struct {
	types.EventDataNewBlock
}

Purpose

Wraps `types.EventDataNewBlock` (an event emitted on new blocks by CometBFT) to implement the `Block` interface.

Methods

Method	Returns	Description
`Hash()`	`string`	Returns the block hash from the embedded `EventDataNewBlock`.
`Height()`	`int64`	Returns the block height from the embedded block.
`Timestamp()`	`int64`	Returns the block timestamp as Unix milliseconds.

Implementation Details

Similar to ResultBlock but wraps event data from block event streams.
Provides a consistent Block interface across different CometBFT block representations.

Struct: `ResultTx`

type ResultTx struct {
	BlockHash    string
	BlockHeight  int64
	Timestamp    int
	Index        int
	TxID         string
	Memo         string
	Fee          cosmos.Value
	Events       cosmos.EventsByMsgIndex
	Messages     []cosmos.Message
	TypedEvent   TypedEvent
	latestHeight int
	formatTx     func(tx *ResultTx) (*cosmos.Tx, error)
}

Purpose

Represents a blockchain transaction derived from block result events, enriched with Cosmos SDK-specific transaction data and events.

Fields

Field	Type	Description
`BlockHash`	`string`	Hash of the block containing this transaction.
`BlockHeight`	`int64`	Height of the block containing this transaction.
`Timestamp`	`int`	Timestamp of the block in Unix seconds (note: differs from block's ms).
`Index`	`int`	Index of the transaction within the block.
`TxID`	`string`	Unique identifier (hash) of the transaction.
`Memo`	`string`	Memo string attached to the transaction.
`Fee`	`cosmos.Value`	Fee paid for this transaction.
`Events`	`cosmos.EventsByMsgIndex`	Events grouped by message index within the transaction.
`Messages`	`[]cosmos.Message`	Slice of Cosmos SDK messages included in the transaction.
`TypedEvent`	`TypedEvent`	Typed event representation associated with the transaction.
`latestHeight`	`int`	Internal field tracking latest block height for caching or validation.
`formatTx`	`func(ResultTx) (cosmos.Tx, error)`	Function pointer to a formatter that converts `ResultTx` to a Cosmos `Tx`.

Methods

Method	Returns	Description
`GetHeight()`	`int64`	Returns the block height of the transaction.
`GetIndex()`	`int`	Returns the transaction index in the block.
`GetTxID()`	`string`	Returns the transaction ID (hash).
`FormatTx()`	`(*cosmos.Tx, error)`	Applies the formatter function to produce a Cosmos SDK `Tx` object.

Usage Example

tx := ResultTx{
    BlockHash: "ABC123",
    BlockHeight: 100,
    TxID: "TX456",
    formatTx: func(r *ResultTx) (*cosmos.Tx, error) {
       // custom formatting logic here
       return cosmosTx, nil
    },
}

fmt.Println(tx.GetTxID())  // Output: TX456

cosmosTx, err := tx.FormatTx()
if err != nil {
    log.Fatal(err)
}

Implementation Details

ResultTx acts as a container for transaction data parsed from block results.
The formatTx function allows pluggable conversion logic to transform raw transaction data into a structured Cosmos SDK transaction.
Uses typed events and grouped message events for detailed event parsing and processing.

Implementation Notes and Algorithms

The file uses Go embedding to extend CometBFT types (cometbfttypes.Block and types.EventDataNewBlock) while implementing a common Block interface.
Time is consistently converted to Unix milliseconds (except ResultTx.Timestamp which is in seconds, likely reflecting original event data).
The ResultTx structure supports extensibility via the formatTx function pointer, enabling flexible transaction formatting depending on context or version.
This design isolates blockchain event data reading from Cosmos transaction business logic, supporting modularity and easier testing.

Interaction with Other Components

CometBFT: The ResultBlock and NewBlock wrap types from CometBFT, interfacing with the Tendermint consensus layer to obtain block data.
Cosmos SDK: ResultTx contains Cosmos-specific types such as cosmos.Value, cosmos.Message, and cosmos.Tx, linking blockchain event data to Cosmos transaction processing.
Typed Events: TypedEvent (not defined here) presumably standardizes event handling and typing across transactions.
Event Handling Layer: The file supports parsing and formatting of events and messages from raw block and transaction data, contributing to higher-level event-driven modules.
Unchained Package: The import of github.com/shapeshift/unchained/pkg/cosmos indicates integration with the Unchained project, which provides blockchain data indexing and processing.

Mermaid Diagram: Structure of types.go

classDiagram
    class Block {
        <<interface>>
        +Hash() string
        +Height() int64
        +Timestamp() int64
    }

    class ResultBlock {
        -Block *cometbfttypes.Block
        +Hash() string
        +Height() int64
        +Timestamp() int64
    }

    class NewBlock {
        -EventDataNewBlock types.EventDataNewBlock
        +Hash() string
        +Height() int64
        +Timestamp() int64
    }

    class ResultTx {
        +BlockHash string
        +BlockHeight int64
        +Timestamp int
        +Index int
        +TxID string
        +Memo string
        +Fee cosmos.Value
        +Events cosmos.EventsByMsgIndex
        +Messages []cosmos.Message
        +TypedEvent TypedEvent
        -latestHeight int
        -formatTx func(*ResultTx) (*cosmos.Tx, error)
        +GetHeight() int64
        +GetIndex() int
        +GetTxID() string
        +FormatTx() (*cosmos.Tx, error)
    }

    ResultBlock ..|> Block
    NewBlock ..|> Block

Summary

The `types.go` file in the Thorchain module defines key abstractions for blockchain blocks and transactions, bridging CometBFT raw data and Cosmos SDK transaction structures. It standardizes access to block metadata across different block representations and encapsulates complex transaction data along with flexible formatting capabilities. This modular design facilitates event-driven processing of blockchain data within the broader Thorchain and Cosmos ecosystem.

types.go

Overview

Detailed Descriptions

Interface: Block

Purpose

Methods

Usage Example

Struct: ResultBlock

Purpose

Methods

Implementation Details

Usage Example

Struct: NewBlock

Purpose

Methods

Implementation Details

Struct: ResultTx

Purpose

Fields

Methods

Usage Example

Implementation Details

Implementation Notes and Algorithms

Interaction with Other Components

Mermaid Diagram: Structure of types.go

Summary

Interface: `Block`

Struct: `ResultBlock`

Struct: `NewBlock`

Struct: `ResultTx`