Thorchain-Specific Functionality

This module encompasses specialized components tailored for the Thorchain blockchain within the ShapeShift Unchained platform. It addresses Thorchain's unique blockchain event structures, transaction formats, and affiliate fee indexing, as well as its integration with the Cosmos SDK framework. The module extends generic Cosmos functionality by implementing Thorchain-specific parsing, transaction synthesis, and revenue tracking to provide accurate and enriched blockchain data to clients.

Core Concepts and Purpose

Thorchain-Specific Functionality exists to bridge the generic Cosmos-based API framework with the particularities of Thorchain's blockchain data and operations. Thorchain differs from typical Cosmos chains in transaction event structures, fee models, and message types, necessitating:

This module ensures that clients receive accurate transaction histories, fee estimations, and affiliate revenue data reflective of Thorchain's blockchain behavior.

Module Components and How They Work

1. API Server (go/coinstacks/thorchain/api/api.go)

The API server provides REST and WebSocket endpoints exposing Thorchain blockchain data. It builds upon a Cosmos SDK-based API framework (`cosmos.API`) but injects Thorchain-specific logic via a custom `Handler`. Key features include:

The API instantiates a `Handler` that combines Cosmos base handling with Thorchain-specific processing and an `AffiliateFeeIndexer` for revenue tracking.

handler := &Handler{
    Handler: &cosmos.Handler{...},
    indexer: indexer,
}

The server integrates middleware for logging, CORS, and Prometheus metrics, and hosts Swagger documentation.

2. Handler (go/coinstacks/thorchain/api/handler.go)

The `Handler` extends the generic Cosmos `Handler` to implement Thorchain-specific business logic:

Example of affiliate revenue retrieval:

func (h *Handler) GetAffiliateRevenue(start int, end int) (*AffiliateRevenue, error) {
    total := big.NewInt(0)
    for _, fee := range h.indexer.AffiliateFees {
        if fee.Timestamp >= int64(start) && fee.Timestamp <= int64(end) {
            amount := new(big.Int)
            amount.SetString(fee.Amount, 10)
            total.Add(total, amount)
        }
    }
    ...
    return a, nil
}

3. Transaction Parsing and Formatting (go/pkg/thorchain/tx.go)

This component is responsible for interpreting Thorchain blockchain events and synthesizing transaction data:

The parsing functions carefully combine raw blockchain event data with domain-specific knowledge of Thorchain's transaction semantics, ensuring that clients receive a coherent and enriched view of on-chain activity.

4. Thorchain Event Types (go/pkg/thorchain/events.go)

This package defines Thorchain-specific blockchain event models and parsing logic:

This event parsing layer abstracts the complexity of raw blockchain event formats and provides structured data for higher-level transaction processing.

5. Fee Parsing and Adjustment (go/pkg/thorchain/thorchain.go)

Thorchain deducts a native fee automatically from every transaction, which may not be explicitly represented in standard fee fields. This module:

func ParseFee(tx cosmos.SigningTx, txid string, denom string, nativeFee int) cosmos.Value {
    fee := cosmos.Fee(tx, txid, denom)
    i := new(big.Int)
    i.SetString(fee.Amount, 10)
    fee.Amount = i.Add(i, big.NewInt(int64(nativeFee))).String()
    return fee
}

Interaction with Other System Components

This module is tightly coupled with Thorchain blockchain data and the Cosmos SDK-based infrastructure, forming a specialized layer that enriches and adapts blockchain data for client APIs.

Design Patterns and Unique Approaches

Illustration of Key Workflow: Transaction Parsing and Affiliate Revenue Retrieval

sequenceDiagram
    participant API as Thorchain API Server
    participant Handler as Thorchain Handler
    participant HTTPClient as Cosmos HTTP Client
    participant BlockService as Block Service
    participant Indexer as AffiliateFeeIndexer

    Client->>API: Request Tx History for Pubkey
    API->>Handler: GetTxHistory(pubkey)
    Handler->>HTTPClient: Search Blocks with Pubkey Events
    HTTPClient->>Handler: Return Matching Blocks
    Handler->>HTTPClient: Fetch Block Results for Each Block
    HTTPClient->>Handler: Return Block Events
    Handler->>thorchain.tx: Parse Block Events and Synthesize Tx
    Handler->>Client: Return Formatted Tx History

    Client->>API: Request Affiliate Revenue (start, end)
    API->>Handler: GetAffiliateRevenue(start, end)
    Handler->>Indexer: Aggregate Affiliate Fees in Time Range
    Indexer->>Handler: Return Total Revenue and Addresses
    Handler->>Client: Return Affiliate Revenue Data

This documentation captures the specialized Thorchain functionality within the ShapeShift Unchained platform, highlighting how the module adapts generic Cosmos infrastructure to Thorchain's unique blockchain characteristics while providing enriched API services and affiliate revenue tracking.