models.ts

Overview

The [models.ts](/projects/291/68901) file defines TypeScript interfaces that model the fundamental data structures and API response formats used throughout the application. These interfaces primarily represent error responses, account details, transaction information, pagination structure, and JSON-RPC request/response formats. The file serves as a centralized type definition module that ensures consistent data handling and validation across various components interacting with blockchain data, transactions, and API communications.

Key functionalities include:

• Typing of various HTTP error responses (400, 404, 422, 500).

• Modeling of account and transaction-related data entities.

• Defining structures for paginated API responses.

• Specifying JSON-RPC request and response formats for blockchain node communication.

This file acts as a foundational layer for data integrity and type safety in the system.

Interfaces and Their Details

1. BadRequestError

Represents a 400 Bad Request HTTP error response.

interface BadRequestError {
  error: string;
}

• Properties:

  • error (string): A descriptive error message explaining the bad request.

• Usage Example:

  const errorResponse: BadRequestError = {
    error: "Invalid transaction format"
  };
  

2. NotFoundError

Represents a 404 Not Found HTTP error response.

interface NotFoundError {
  message: string;
}

• Properties:

  • message (string): A message indicating the requested resource was not found.

• Usage Example:

  const errorResponse: NotFoundError = {
    message: "Account not found"
  };
  

3. ValidationError

Represents a 422 Validation Error response indicating failed input validation.

interface ValidationError {
  message: 'Validation failed';
  details: { [name: string]: unknown };
}

• Properties:

  • message (literal string): Always 'Validation failed' to indicate validation failure.

  • details (object): A dictionary object where keys are field names and values are details about the validation errors.

• Usage Example:

  const errorResponse: ValidationError = {
    message: 'Validation failed',
    details: {
      amount: "Amount must be positive",
      address: "Invalid address format"
    }
  };
  

4. InternalServerError

Represents a 500 Internal Server Error HTTP response.

interface InternalServerError {
  message: string;
}

• Properties:

  • message (string): A message describing the server error.

• Usage Example:

  const errorResponse: InternalServerError = {
    message: "Unexpected server error occurred"
  };
  

5. BaseAccount

Represents basic account details for a blockchain address or an extended public key (xpub).

interface BaseAccount {
  balance: string;
  unconfirmedBalance: string;
  pubkey: string;
}

• Properties:

  • balance (string): Confirmed balance of the account in the smallest currency unit.

  • unconfirmedBalance (string): Unconfirmed balance (e.g., pending transactions).

  • pubkey (string): The public key or address identifier.

• Usage Example:

  const account: BaseAccount = {
    balance: "1000000",
    unconfirmedBalance: "50000",
    pubkey: "xpub6CUGRUonZSQ4TWtTMmzXdrXDtypWKiKp6..."
  };
  

6. BaseInfo

Represents basic information about the running blockchain stack or network.

interface BaseInfo {
  network: string;
}

• Properties:

  • network (string): The blockchain network identifier (e.g., "mainnet", "testnet").

• Usage Example:

  const info: BaseInfo = {
    network: "mainnet"
  };
  

7. Pagination

Represents pagination data for API responses supporting paged results.

interface Pagination {
  cursor?: string;
}

• Properties:

  • cursor (optional string): A cursor string used to fetch the next page of results.

• Usage Example:

  const pagination: Pagination = {
    cursor: "eyJ2IjoiMSJ9"
  };
  

8. SendTxBody

Represents the body of a request to send a serialized raw transaction.

interface SendTxBody {
  hex: string;
}

• Properties:

  • hex (string): The raw transaction data encoded as a hexadecimal string.

• Usage Example:

  const txBody: SendTxBody = {
    hex: "0100000001abcdef..."
  };
  

9. EstimateGasBody

Represents the transaction data used to estimate gas cost for a transaction.

interface EstimateGasBody {
  data: string;
  from: string;
  to: string;
  value: string;
}

• Properties:

  • data (string): The transaction input data (e.g., encoded method call).

  • from (string): The sender's address.

  • to (string): The recipient's address.

  • value (string): The amount of cryptocurrency to send, typically in smallest unit.

• Usage Example:

  const estimateGas: EstimateGasBody = {
    data: "0xa9059cbb000000000000000000000000...",
    from: "0xabc123...",
    to: "0xdef456...",
    value: "0"
  };
  

10. BaseTx

Represents basic transaction details.

interface BaseTx {
  txid: string;
  blockHash?: string;
  blockHeight: number;
  timestamp: number;
}

• Properties:

  • txid (string): Unique transaction identifier (hash).

  • blockHash (optional string): Hash of the block containing the transaction.

  • blockHeight (number): Height/index of the block in the blockchain.

  • timestamp (number): Unix timestamp when the transaction was included.

• Usage Example:

  const tx: BaseTx = {
    txid: "0x123abc...",
    blockHash: "0xdeadbeef...",
    blockHeight: 123456,
    timestamp: 1640995200
  };
  

11. BaseTxHistory<T = BaseTx>

Represents paginated transaction history for a given public key.

interface BaseTxHistory<T = BaseTx> extends Pagination {
  pubkey: string;
  txs: Array<T>;
}

• Generic Type Parameter:

  • T (default BaseTx): The type of transaction entries in the list.

• Properties:

  • Inherits cursor from Pagination.

  • pubkey (string): The public key or address whose transaction history is returned.

  • txs (Array): An array of transactions of type T.

• Usage Example:

  const txHistory: BaseTxHistory = {
    pubkey: "xpub6CUGRUonZSQ4T...",
    txs: [
      { txid: "0x1", blockHeight: 1000, timestamp: 1620000000 },
      { txid: "0x2", blockHeight: 1001, timestamp: 1620003600 }
    ],
    cursor: "eyJ2IjoiMSJ9"
  };
  

12. RPCRequest

Represents a JSON-RPC 2.0 request structure for blockchain node communication.

interface RPCRequest {
  jsonrpc: '2.0';
  id: string | number;
  method: string;
  params?: Array<unknown>;
}

• Properties:

  • jsonrpc (literal string): Protocol version, always '2.0'.

  • id (string | number): Identifier for matching request and response.

  • method (string): The method name to invoke.

  • params (optional array): Parameters for the method invocation.

• Usage Example:

  const request: RPCRequest = {
    jsonrpc: '2.0',
    id: 1,
    method: 'eth_getBalance',
    params: ['0xabc123...', 'latest']
  };
  

13. RPCResponse

Represents a JSON-RPC 2.0 response structure.

interface RPCResponse {
  jsonrpc: '2.0';
  id: string | number;
  result?: unknown;
  error?: {
    code: number;
    message: string;
    data?: unknown;
  };
}

• Properties:

  • jsonrpc (literal string): Protocol version, always '2.0'.

  • id (string | number): Matches the request ID.

  • result (optional): The result returned by the RPC method if successful.

  • error (optional object): Contains error details if the RPC method failed.

    • code (number): Error code.

    • message (string): Error message.

    • data (optional): Additional error data.

• Usage Example:

  const response: RPCResponse = {
    jsonrpc: '2.0',
    id: 1,
    result: "0x0234c8a3397aab58"
  };
  

Important Implementation Details

• The file strictly uses TypeScript interfaces to define data shapes without any runtime logic or classes.

• It uses literal types for constant fields like message: 'Validation failed' and jsonrpc: '2.0' to enforce exact values.

• The BaseTxHistory interface is generic, allowing flexibility to substitute different transaction types.

• Error interfaces are separated by HTTP status codes, enabling precise error handling and response typing.

• The JSON-RPC interfaces conform to the official JSON-RPC 2.0 specification, ensuring compatibility with blockchain nodes and other JSON-RPC servers.

Interaction with Other Parts of the System

• These interfaces are imported and used by service modules that handle API interactions, such as fetching account data, sending transactions, or querying transaction histories.

• Error interfaces are used for typing API error responses, enabling clear error handling in UI or backend components.

• RPCRequest and RPCResponse are used in modules implementing JSON-RPC communication with blockchain nodes or proxies.

• Pagination interfaces assist in managing paged API results, facilitating efficient data loading and navigation in UI components.

• Transaction and account models are fundamental to wallet functionality, blockchain explorers, or transaction processors within the system.

Visual Diagram: Class Diagram Representing Interfaces and Their Relationships

classDiagram
    class BadRequestError {
        +error: string
    }
    class NotFoundError {
        +message: string
    }
    class ValidationError {
        +message: 'Validation failed'
        +details: { [name: string]: unknown }
    }
    class InternalServerError {
        +message: string
    }
    class BaseAccount {
        +balance: string
        +unconfirmedBalance: string
        +pubkey: string
    }
    class BaseInfo {
        +network: string
    }
    class Pagination {
        +cursor?: string
    }
    class SendTxBody {
        +hex: string
    }
    class EstimateGasBody {
        +data: string
        +from: string
        +to: string
        +value: string
    }
    class BaseTx {
        +txid: string
        +blockHash?: string
        +blockHeight: number
        +timestamp: number
    }
    class BaseTxHistory {
        +pubkey: string
        +txs: Array~BaseTx~
        +cursor?: string
    }
    class RPCRequest {
        +jsonrpc: '2.0'
        +id: string | number
        +method: string
        +params?: Array~unknown~
    }
    class RPCResponse {
        +jsonrpc: '2.0'
        +id: string | number
        +result?: unknown
        +error?: ErrorObject
    }
    class ErrorObject {
        +code: number
        +message: string
        +data?: unknown
    }

    BaseTxHistory --|> Pagination
    RPCResponse "1" o-- "1" ErrorObject : error

Summary

The [models.ts](/projects/291/68901) file provides a well-organized set of TypeScript interfaces modeling error responses, blockchain accounts, transactions, pagination, and JSON-RPC communication. It ensures type safety and consistent data structures across the application, supporting blockchain-related workflows such as transaction handling, account management, and node communication. This foundational module integrates closely with API layers, blockchain service components, and UI modules that display or manipulate blockchain data.