Transaction Parsing

Purpose

Transaction Parsing addresses the challenge of interpreting raw blockchain messages and events specific to Thorchain and Cosmos SDK. This subtopic focuses on transforming low-level, protocol-specific data—such as blockchain events, transaction messages, and attributes—into rich, structured, and meaningful transaction representations. These enriched transactions enable higher-level functionalities like detailed transaction history, analytics, and affiliate fee indexing within the Thorchain ecosystem.

Unlike the broader Thorchain components that deal with affiliate fee indexing or API serving, Transaction Parsing uniquely solves how to decode and correlate complex blockchain events and messages, including synthetic or inferred transactions, ensuring accurate and comprehensive transaction data.

Functionality

The core functions of Transaction Parsing include:

• Parsing Block Events:
  It extracts and categorizes blockchain events by their types (e.g., fee events, outbound transfers) from raw ABCI events emitted by the Thorchain blockchain. This categorization produces typed event objects used downstream.

• Decoding Messages:
  It interprets various Cosmos SDK and Thorchain message types (e.g., MsgSend, MsgDeposit, MsgObservedTxQuorum) to extract transaction details like sender, recipient, amounts, and event-related metadata.

• Correlating Events and Messages:
  Some blockchain behaviors produce synthetic or inferred transactions (e.g., outbound events following deposits). This parsing logic detects such patterns and creates synthetic messages or transactions to represent them accurately.

• Constructing Enriched Transactions:
  Using the parsed events and decoded messages, it builds comprehensive transaction objects (ResultTx) with linked events, messages, fees, memos, and blockchain metadata (block hash, height, timestamp).

• Filtering by Address:
  When retrieving transaction history for a specific public key, the parsing selectively includes only those transactions related to that address, improving relevancy and performance.

Key Workflows

1. GetTxHistory:
   Queries blocks and their results to find transactions involving a given public key, parses block events, and extracts transactions linked to that key.

2. ParseBlockEvents:
   Converts raw blockchain ABCI events into typed event structures for easier handling.

3. ParseMessages:
   Processes arrays of Cosmos SDK messages with their associated events, returning a list of enriched messages with detailed fields like From, To, Value, and Type.

4. GetTxFromBlockEvents:
   Builds a synthetic transaction from block-level outbound events, matching fees and setting transaction metadata.

Snippet: Parsing a MsgDeposit and generating synthetic outbound messages

case *thorchaintypes.MsgDeposit:
    to := ""
    coin := v.Coins[0]

    events[strconv.Itoa(i)]["message"]["memo"] = v.Memo

    withdraw := events[strconv.Itoa(i)]["withdraw"]
    if withdraw != nil {
        to = withdraw["to"]
    }

    // ... create deposit message ...

    outbound := events[strconv.Itoa(i)]["outbound"]
    if outbound != nil {
        coin, err := common.ParseCoin(outbound["coin"])
        // ... handle error ...
        message := cosmos.Message{
            Addresses: []string{outbound["from"], outbound["to"]},
            Type:      "outbound",
            // ... other fields ...
        }
        messages = append(messages, message)
    }

This snippet illustrates how deposit messages trigger detection of related outbound events, resulting in synthetic messages representing fund movements that are not explicit in the original transaction messages.

Integration

Transaction Parsing is a foundational subcomponent within the Thorchain-specific functionality, serving as the data interpretation layer between raw blockchain data and higher-level modules:

• With Affiliate Fee Indexer:
  Parses enriched transactions to identify and extract affiliate fee-related outbound transactions.

• With API Server:
  Provides the parsed and formatted transaction data served by REST and WebSocket endpoints, enabling clients to receive detailed and user-friendly transaction histories.

• With Blockchain Data Indexing:
  Works closely with indexed block events from Blockbook or other indexers, parsing those events into structured transactions.

This parsing logic enhances the parent topic by enabling a richer understanding of blockchain activity beyond raw data, supporting analytics, fee tracking, and user-facing transaction details.

Diagram

flowchart TD
    A[Query Blocks with Pubkey] --> B[Fetch Block Results]
    B --> C[ParseBlockEvents (raw ABCI events)]
    C --> D[ParseMessages (Cosmos & Thorchain messages)]
    D --> E[Detect Synthetic Events (e.g., outbound, refunds)]
    E --> F[Construct Enriched Transactions]
    F --> G[Filter Transactions by Pubkey]
    G --> H[Return TxHistory to Caller]

This flowchart visualizes the main process of parsing Thorchain transactions, from querying blocks to returning enriched transaction histories filtered by address.

Transaction Parsing encapsulates the domain-specific knowledge needed to translate complex, multi-layered blockchain events and messages into actionable, well-structured transaction data. It bridges low-level blockchain protocol details and higher-level application logic within the Thorchain coinstack.