models.ts

Overview

The [models.ts](/projects/291/68901) file defines TypeScript types and interfaces that model the core data structures related to blockchain transactions, accounts, tokens, and fees within the application. It serves as a foundational data schema layer that standardizes the shape and expected properties of entities involved in transaction processing and account management. This file also includes an interface to abstract API interactions related to fetching transaction details.

By combining base types from a common API and enriched transaction data from an external SDK (`helius-sdk`), the file ensures consistent and enriched data representation across the application. These models facilitate type safety, code clarity, and easier integration between the UI, business logic, and API communication layers.

Detailed Descriptions

Type Aliases

Tx

export type Tx = BaseTx & EnrichedTransaction

• Description:
  Represents a blockchain transaction by extending the base transaction (BaseTx) with enriched data from the helius-sdk (EnrichedTransaction). This composite type includes all standard transaction fields along with additional metadata or enrichment details.

• Usage Example:

async function printTx(txid: string, api: API) {
  const transaction: Tx = await api.getTransaction(txid);
  console.log(transaction.signature, transaction.slot, transaction.type);
}

TxHistory

export type TxHistory = BaseTxHistory<Tx>

• Description:
  Represents a paginated or aggregated history of transactions. It uses a generic base type BaseTxHistory parameterized with Tx to specify the transaction type it holds.

• Usage Example:

function processHistory(history: TxHistory) {
  history.txs.forEach(tx => console.log(tx.signature));
}

Interfaces

Address

export interface Address {
  balance: string
  pubkey: string
}

• Description:
  Models an address associated with an extended public key along with its balance.

• Properties:

  • balance - The balance of the address as a string (typically representing a numeric value in smallest denomination).

  • pubkey - The public key string of the address.

• Usage Example:

const addr: Address = {
  balance: "1000000",
  pubkey: "F7Yd..."
};

Token

export interface Token {
  id: string
  decimals: number
  name: string
  symbol: string
  type: string
}

• Description:
  Describes the basic properties of a blockchain token.

• Properties:

  • id - Unique identifier of the token (e.g., mint address).

  • decimals - Number of decimal places for the token.

  • name - Human-readable name.

  • symbol - Token symbol (e.g., "SOL").

  • type - Token type or classification.

• Usage Example:

const solToken: Token = {
  id: "So11111111111111111111111111111111111111112",
  decimals: 9,
  name: "Solana",
  symbol: "SOL",
  type: "native"
};

TokenBalance

export interface TokenBalance extends Token {
  balance: string
}

• Description:
  Extends the Token interface by adding a balance field to represent the amount of this token held by a particular address or account.

• Properties:

  • Inherits all properties from Token.

  • balance - The token balance as a string.

• Usage Example:

const userTokenBalance: TokenBalance = {
  id: "TokenMintAddress",
  decimals: 6,
  name: "USD Coin",
  symbol: "USDC",
  type: "spl-token",
  balance: "1500000"
};

Account

export interface Account extends BaseAccount {
  tokens: Array<TokenBalance>
}

• Description:
  Represents an account or extended public key holding multiple tokens. Extends from BaseAccount (imported from common API) to include the standard account fields plus a list of tokens with balances.

• Properties:

  • Inherits all properties from BaseAccount.

  • tokens - An array of TokenBalance objects representing all tokens held by this account.

• Usage Example:

const account: Account = {
  // BaseAccount fields like address, pubkey, etc.
  address: "SomeAddress",
  pubkey: "PubkeyString",
  tokens: [
    {
      id: "TokenMint1",
      decimals: 9,
      name: "Token1",
      symbol: "TK1",
      type: "spl-token",
      balance: "100000000"
    }
  ]
};

PriorityFees

export interface PriorityFees {
  baseFee: string
  slow: string
  average: string
  fast: string
}

• Description:
  Contains recommended priority fee estimations for a transaction to be included in a block at different confirmation speeds.

• Properties:

  • baseFee - Base fee per signature.

  • slow - Estimated fee for slow confirmation.

  • average - Estimated fee for average confirmation.

  • fast - Estimated fee for fast confirmation.

• Usage Example:

const fees: PriorityFees = {
  baseFee: "5000",
  slow: "10000",
  average: "20000",
  fast: "40000"
};

Type Alias: EstimateFeesBody

export type EstimateFeesBody =
  | { serializedTx?: string }
  | { message?: string }

• Description:
  Represents the payload body for estimating transaction fees. It supports either:

  • A base64 encoded serialized transaction (serializedTx), or

  • A message string (message).

• Usage Example:

const feeBody1: EstimateFeesBody = { serializedTx: "base64string" };
const feeBody2: EstimateFeesBody = { message: "some transaction message" };

Interface: API

export interface API {
  getTransaction(txid: string): Promise<Tx>
}

• Description:
  Defines the contract for coin-specific API operations. Currently, it specifies a method to fetch transaction details by transaction ID.

• Method:

• Usage Example:

async function fetchAndLogTx(api: API, txid: string) {
  const tx = await api.getTransaction(txid);
  console.log(tx);
}

• Note:
  The commented decorator @Get('tx/{txid}') suggests this method corresponds to an HTTP GET endpoint in a REST API.

Important Implementation Details

• Type Composition: Types like Tx and TxHistory are constructed by combining base types imported from a shared API module (BaseTx, BaseTxHistory) with enriched data from an external SDK (helius-sdk). This approach promotes reuse and consistency.

• String Usage for Numeric Values: Balances and fees are represented as strings to avoid precision loss that can occur with JavaScript number type, especially for large integers or decimal-sensitive blockchain amounts.

• Optional Properties in EstimateFeesBody: The use of a union with optional properties facilitates flexible input formats when estimating fees, allowing either a serialized transaction or a human-readable message.

• API Abstraction: The API interface abstracts external API calls, enabling different implementations (e.g., mocked data, different blockchain providers) while maintaining strong typing.

Integration with Other System Components

• Common API Module: Imports base models (BaseAccount, BaseTx, BaseTxHistory) from a shared API source to maintain type consistency across modules.

• helius-sdk: Enriches transaction data with detailed blockchain-specific information.

• API Layer: The API interface is intended to be implemented by service classes that interact with blockchain or backend services, providing transaction data to higher layers such as business logic or UI components.

• Usage in Business Logic and UI: These models underpin the shape of data passed through the application layers, enabling components like transaction history views, account dashboards, token lists, and fee estimators to function with well-defined data contracts.

Visual Diagram

classDiagram
    %% Tx is intersection of BaseTx and EnrichedTransaction (external)
    class Tx {
      <<type alias>>
    }

    %% TxHistory is BaseTxHistory generic on Tx
    class TxHistory {
      <<type alias>>
    }

    class Address {
      +balance: string
      +pubkey: string
    }

    class Token {
      +id: string
      +decimals: number
      +name: string
      +symbol: string
      +type: string
    }

    class TokenBalance {
      +balance: string
      +id: string
      +decimals: number
      +name: string
      +symbol: string
      +type: string
    }

    class Account {
      +tokens: Array~TokenBalance~
    }

    class PriorityFees {
      +baseFee: string
      +slow: string
      +average: string
      +fast: string
    }

    class EstimateFeesBody {
      <<union type>>
      +serializedTx?: string
      +message?: string
    }

    class API {
      +getTransaction(txid: string): Promise~Tx~
    }

    %% Inheritance
    TokenBalance --|> Token
    Account --|> BaseAccount

    %% Notes on external types
    note for Tx "Tx = BaseTx & EnrichedTransaction (external)"
    note for TxHistory "TxHistory = BaseTxHistory<Tx> (generic base)"
    note for Account "Account extends BaseAccount imported from common API"

Summary

The [models.ts](/projects/291/68901) file provides a structured and extensible set of type definitions and interfaces essential for representing blockchain transactions, accounts, tokens, and fee estimations within the system. It bridges external SDK data and internal base models, enabling consistency and clarity across the codebase. The API interface defines key blockchain data retrieval methods, facilitating modular and testable integration with backend services.

This file is foundational for any module working with blockchain data, ensuring reliable type contracts and supporting scalable system architecture.