models.ts

Overview

The [models.ts](/projects/291/68901) file defines TypeScript interfaces and types that represent core blockchain data structures and related entities used throughout the application. These models encapsulate transaction details, unspent outputs, account and address information, network fees, and specify an API interface to interact with blockchain data sources.

Key functionalities include:

• Defining the shape of transaction inputs (Vin), outputs (Vout), and full transactions (Tx).

• Representing raw transactions as returned by blockchain nodes (RawTx).

• Modeling unspent transaction outputs (Utxo), account addresses, and overall account data.

• Providing structures for network fee recommendations.

• Specifying an API interface for fetching blockchain data asynchronously.

This file acts as a central schema definition for blockchain-related data and API contracts, promoting consistency and type safety across the system.

Detailed Documentation

Interfaces and Types

Vin

**Purpose:** Represents a transaction input, providing details about the source of funds in a transaction.

**Properties:**

**Usage Example:**

const input: Vin = {
  txid: "abc123",
  vout: "0",
  sequence: 4294967295,
  scriptSig: { hex: "483045022100..." },
  addresses: ["1A1zP1..."],
  value: "0.001"
};

Vout

**Purpose:** Describes a single transaction output, including its value and destination.

**Properties:**

**Usage Example:**

const output: Vout = {
  value: "0.002",
  n: 1,
  scriptPubKey: { hex: "76a91488ac..." },
  addresses: ["1BvBMSE..."]
};

Tx

**Inheritance:** Extends `BaseTx` (imported from an external module).

**Purpose:** Encapsulates a full transaction's details, including inputs, outputs, fees, and confirmations.

**Properties:**

**Usage Example:**

const transaction: Tx = {
  vin: [input1, input2],
  vout: [output1, output2],
  confirmations: 10,
  value: "0.003",
  fee: "0.0001",
  hex: "0200000001..."
};

TxHistory

**Type Alias:** `BaseTxHistory`

**Purpose:** Represents a collection or history of transactions of type `Tx`. This type derives from a generic base transaction history model.

RawTx

**Purpose:** Represents the raw transaction data as returned directly by a blockchain node's API.

**Properties:** Includes complete low-level transaction details such as version, size, inputs, outputs, and block information. The structure closely matches the data returned by blockchain nodes like Bitcoin Core.

Key fields include:

• txid, hash, version, size, vsize, weight, locktime

• vin: array of inputs with txid, vout, sequence, coinbase, scriptSig (with asm and hex), and txinwitness.

• vout: array of outputs with value, n, and scriptPubKey details including asm, hex, reqSigs, type, and addresses.

• hex: raw serialized transaction.

• blockhash, confirmations, time, blocktime.

**Usage Example:**

const rawTx: RawTx = {
  txid: "abc123",
  hash: "def456",
  version: 2,
  size: 225,
  vsize: 144,
  weight: 576,
  locktime: 0,
  vin: [{ txid: "prevtxid", vout: 0, scriptSig: { asm: "...", hex: "..." } }],
  vout: [{ value: 0.001, n: 0, scriptPubKey: { asm: "...", hex: "...", reqSigs: 1, type: "pubkeyhash", addresses: ["1A1zP1..."] } }],
  hex: "0200000001...",
  blockhash: "000000000000...",
  confirmations: 100,
  time: 1609459200,
  blocktime: 1609459200
};

Utxo

**Purpose:** Represents an Unspent Transaction Output (UTXO) that can be spent in new transactions.

**Properties:**

**Usage Example:**

const utxo: Utxo = {
  txid: "abc123",
  vout: 0,
  value: "0.001",
  confirmations: 15,
  address: "1A1zP1...",
  coinbase: false
};

Address

**Purpose:** Represents an individual address associated with an extended public key, with its balance and public key.

**Properties:**

Account

**Inheritance:** Extends `BaseAccount` (imported externally)

**Purpose:** Represents an account or extended public key with associated addresses and address indices for receiving and change addresses.

**Properties:**

NetworkFee

**Purpose:** Represents fee information to get a transaction confirmed within a certain number of blocks.

**Properties:**

NetworkFees

**Purpose:** Holds recommended network fees categorized by speed preference.

**Properties:**

Interface API

**Purpose:** Defines an asynchronous interface for coin-specific blockchain operations such as fetching UTXOs, transaction details, and network fee recommendations.

Methods

getUtxos(pubkey: string): Promise<Array<Utxo>>

Fetches all unspent transaction outputs for a given account address or extended public key.

• Parameters:

  • pubkey (string): The address or extended public key to query.

• Returns:

  • Promise<Array<Utxo>>: A promise that resolves to an array of UTXOs associated with the account.

• Example:

api.getUtxos("xpub6CUGRU...").then(utxos => {
  console.log(utxos);
});

getTransaction(txid: string): Promise<Tx>

Retrieves detailed transaction information for a given transaction ID.

• Parameters:

  • txid (string): The transaction hash.

• Returns:

  • Promise<Tx>: A promise resolving to the transaction details.

• Example:

api.getTransaction("abc123").then(tx => {
  console.log(tx.vin, tx.vout);
});

getRawTransaction(txid: string): Promise<RawTx>

Fetches raw transaction data directly from the blockchain node.

• Parameters:

  • txid (string): The transaction hash.

• Returns:

  • Promise<RawTx>: A promise resolving to raw blockchain transaction data.

• Example:

api.getRawTransaction("abc123").then(rawTx => {
  console.log(rawTx.hex);
});

getNetworkFees(): Promise<NetworkFees>

Retrieves the current recommended network fees for different confirmation speeds.

• Returns:

  • Promise<NetworkFees>: A promise resolving to network fee recommendations.

• Example:

api.getNetworkFees().then(fees => {
  console.log(fees.fast?.satsPerKiloByte);
});

Important Implementation Details

• The file imports base types (BaseAccount, BaseTx, BaseTxHistory) from a parent ../models module but notes an import limitation with tsoa (TypeScript OpenAPI generator). This suggests the file is part of a broader type hierarchy and the base models extend or complement these interfaces.

• The interfaces use optional properties liberally (denoted by ?) reflecting the variability of blockchain data (e.g., coinbase inputs, optional addresses).

• The API interface methods are commented with REST-like annotations (e.g., @Get('tx/{txid}')), indicating these interfaces may be implemented by classes that interact with REST endpoints or blockchain nodes.

• The use of string types for monetary values (value, fee, balance) is likely to avoid floating-point precision issues common in blockchain financial computations.

Interaction with Other System Components

• This file provides foundational data models used throughout the application’s blockchain transaction handling layers.

• Other modules likely implement the API interface to provide coin-specific network communication and data retrieval (e.g., Bitcoin, Litecoin APIs).

• The models here are used in business logic layers for transaction history management, wallet/account management, fee estimation, and blockchain data parsing.

• The raw transaction interface (RawTx) enables low-level blockchain node integration, facilitating advanced features like transaction decoding or validation.

• The account and address models integrate with wallet management components that track balances and address usage.

• Network fee models inform transaction construction modules to set appropriate fees dynamically.

Mermaid Diagram: Class/Interface Structure

classDiagram
    class Vin {
        +txid?: string
        +vout?: string
        +sequence?: number
        +coinbase?: string
        +scriptSig?: { hex?: string }
        +addresses?: string[]
        +value?: string
    }

    class Vout {
        +value: string
        +n: number
        +opReturn?: string
        +scriptPubKey: { hex?: string }
        +addresses?: string[]
    }

    class Tx {
        +vin: Vin[]
        +vout: Vout[]
        +confirmations: number
        +value: string
        +fee: string
        +hex: string
    }

    class RawTx {
        +txid: string
        +hash: string
        +version: number
        +size: number
        +vsize: number
        +weight: number
        +locktime: number
        +vin: array
        +vout: array
        +hex: string
        +blockhash: string
        +confirmations: number
        +time: number
        +blocktime: number
    }

    class Utxo {
        +txid: string
        +vout: number
        +value: string
        +height?: number
        +confirmations: number
        +address?: string
        +path?: string
        +locktime?: number
        +coinbase?: boolean
    }

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

    class Account {
        +addresses?: Address[]
        +nextReceiveAddressIndex?: number
        +nextChangeAddressIndex?: number
    }

    class NetworkFee {
        +blocksUntilConfirmation: number
        +satsPerKiloByte: number
    }

    class NetworkFees {
        +fast?: NetworkFee
        +average?: NetworkFee
        +slow?: NetworkFee
    }

    class API {
        +getUtxos(pubkey: string): Promise<Array<Utxo>>
        +getTransaction(txid: string): Promise<Tx>
        +getRawTransaction(txid: string): Promise<RawTx>
        +getNetworkFees(): Promise<NetworkFees>
    }

    Tx ..|> BaseTx
    Account ..|> BaseAccount
    TxHistory --> Tx

Summary

[models.ts](/projects/291/68901) is a core schema definition file for blockchain transaction data and related entities within the system. It defines precise TypeScript interfaces for transaction inputs and outputs, full transactions, raw blockchain data, UTXOs, addresses, accounts, and network fees. The API interface defines asynchronous methods to retrieve blockchain data, enabling modular integration with different blockchain backends.

This file promotes type safety and consistent data handling across blockchain-related components, forming a foundational layer that interacts with wallet management, transaction processing, and network communication modules.