types.ts

Overview

This file defines TypeScript interfaces used across the project for modeling data structures related to blockchain transaction tracing, debugging, and explorer API responses. These interfaces provide a strongly typed contract for handling complex JSON data returned by blockchain explorers and tracing tools, enabling safer and clearer code when interacting with external APIs or internal data flows.

Key purposes include:

• Representing cursor pagination state for blockchain data queries.

• Defining detailed trace call structures for transaction execution tracing.

• Structuring debug call stacks for nested call analysis.

• Typing the responses from blockchain explorer APIs.

• Modeling internal transaction data retrieved by transaction hash or address.

Interfaces and Their Details

1. Cursor

Represents pagination information used to track the position in blockchain data queries, supporting both blockbook and explorer pagination styles.

**Usage example:**

const cursor: Cursor = {
  blockbookPage: 1,
  explorerPage: 1,
  blockHeight: 1234567,
};

2. TraceCall

Models a detailed trace of a single call within a transaction, used primarily for deep analysis of Ethereum-like transaction executions.

**Usage example:**

const trace: TraceCall = {
  action: {
    callType: "call",
    from: "0xabc...",
    gas: "21000",
    input: "0x",
    to: "0xdef...",
    value: "1000000000000000000",
  },
  blockHash: "0xblockhash...",
  blockNumber: 1234567,
  result: {
    gasUsed: "21000",
    output: "0x",
  },
  subtraces: 0,
  traceAddress: [],
  transactionHash: "0xtxhash...",
  transactionPosition: 1,
  type: "call",
};

3. DebugCallStack

Represents a hierarchical debug call stack used for debugging nested contract calls.

**Usage example:**

const debugStack: DebugCallStack = {
  type: "call",
  from: "0xabc...",
  to: "0xdef...",
  gas: "100000",
  gasUsed: "21000",
  input: "0xinputdata",
  output: "0xoutputdata",
  calls: [
    {
      type: "call",
      from: "0xdef...",
      to: "0xghi...",
      gas: "80000",
      gasUsed: "20000",
      input: "0xnestedinput",
      output: "0xnestedoutput",
    }
  ]
};

4. ExplorerApiResponse<T>

Generic interface representing the structure of API responses from blockchain explorers.

**Usage example:**

const response: ExplorerApiResponse<TraceCall[]> = {
  status: "1",
  message: "OK",
  result: [ /* array of TraceCall objects */ ],
};

5. ExplorerInternalTxByHash

Models internal transactions retrieved by transaction hash from a blockchain explorer.

6. ExplorerInternalTxByAddress

Represents internal transactions retrieved by blockchain address from an explorer API.

Implementation Details

• All interfaces are plain TypeScript interfaces without any implementation logic.

• The design favors strong typing for JSON data coming from external blockchain explorer APIs or internal tracing tools.

• Interfaces like DebugCallStack are recursive to represent nested call structures typical in smart contract execution.

• Use of generics in ExplorerApiResponse<T> allows reuse for different result types, improving code flexibility.

• The fields mostly use string for numeric values (e.g., gas, value) to avoid precision loss typical in JavaScript number type and to handle large integers safely.

Interaction with Other Parts of the System

• These interfaces are likely imported and used in:

  • API client modules that fetch and parse data from blockchain explorers.

  • Debugging or tracing tools that analyze contract calls and transactions.

  • Pagination and state management components that need to track cursor positions when querying blockchain data.

  • Business logic layers that perform validation, transformation, and analysis on transaction traces or explorer data.

• They form the foundational types enabling safe and predictable data handling, minimizing runtime errors due to unexpected or malformed data structures.

Visual Diagram: Interface Structure Overview

classDiagram
    class Cursor {
        +blockHeight?: number
        +blockbookPage: number
        +blockbookTxid?: string
        +explorerPage: number
        +explorerTxid?: string
    }

    class TraceCall {
        +action: object
        +blockHash: string
        +blockNumber: number
        +result: object
        +subtraces: number
        +traceAddress: number[]
        +transactionHash: string
        +transactionPosition: number
        +type: string
    }

    class DebugCallStack {
        +type: string
        +from: string
        +to: string
        +value?: string
        +gas: string
        +gasUsed: string
        +input: string
        +output: string
        +calls?: DebugCallStack[]
    }

    class ExplorerApiResponse~T~ {
        +status: string
        +message: string
        +result: T
    }

    class ExplorerInternalTxByHash {
        +index?: number
        +blockNumber: string
        +timeStamp: string
        +from: string
        +to: string
        +value: string
        +contractAddress: string
        +input: string
        +type: string
        +gas: string
        +gasUsed: string
        +isError: string
        +errCode: string
    }

    class ExplorerInternalTxByAddress {
        +blockNumber: string
        +timeStamp: string
        +hash: string
        +from: string
        +to: string
        +value: string
        +contractAddress: string
        +input: string
        +type: string
        +gas: string
        +gasUsed: string
        +traceId: string
        +isError: string
        +errCode: string
    }

    DebugCallStack "1" *-- "*" DebugCallStack : calls
    ExplorerApiResponse <|-- ExplorerInternalTxByHash
    ExplorerApiResponse <|-- ExplorerInternalTxByAddress

Summary

The [types.ts](/projects/291/69057) file acts as a centralized type definition hub for blockchain transaction tracing and explorer API data models. It ensures consistent data structures for pagination cursors, trace calls, debug stacks, and explorer internal transactions, facilitating robust integration with blockchain data sources and internal analysis modules. The recursive and generic typing patterns support complex nested data scenarios commonly encountered in smart contract execution tracing and blockchain data exploration.