Skip to content

UTXO Store Reference Documentation

Overview

The UTXO (Unspent Transaction Output) Store provides an interface for managing and querying UTXO data in a blockchain system.

Core Types

Spend

Represents a UTXO being spent.

type Spend struct {
    // TxID is the transaction ID that created this UTXO
    TxID *chainhash.Hash `json:"txId"`

    // Vout is the output index in the creating transaction
    Vout uint32 `json:"vout"`

    // UTXOHash is the unique identifier of this UTXO
    UTXOHash *chainhash.Hash `json:"utxoHash"`

    // SpendingData contains information about the transaction that spends this UTXO
    // This will be nil if the UTXO is unspent
    SpendingData *spend.SpendingData `json:"spendingData,omitempty"`

    // ConflictingTxID is the transaction ID that conflicts with this UTXO
    ConflictingTxID *chainhash.Hash `json:"conflictingTxId,omitempty"`

    // BlockIDs is the list of blocks the transaction has been mined into
    BlockIDs []uint32 `json:"blockIDs,omitempty"`

    // error is the error that occurred during the spend operation
    Err error `json:"err,omitempty"`
}

The Spend struct also provides a Clone() method that creates a deep copy of the spend object.

SpendResponse

Represents the response from a GetSpend operation.

type SpendResponse struct {
    // Status indicates the current state of the UTXO
    Status int `json:"status"`

    // SpendingData contains information about the transaction that spent this UTXO, if any
    SpendingData *spend.SpendingData `json:"spendingData,omitempty"`

    // LockTime is the block height or timestamp until which this UTXO is locked
    LockTime uint32 `json:"lockTime,omitempty"`
}

SpendResponse provides serialization methods:

  • Bytes(): Serializes the response to a byte slice
  • FromBytes(b []byte): Deserializes from a byte slice

MinedBlockInfo

Contains information about a block where a transaction appears.

type MinedBlockInfo struct {
    // BlockID is the unique identifier of the block
    BlockID     uint32

    // BlockHeight is the height of the block in the blockchain
    BlockHeight uint32

    // SubtreeIdx is the index of the subtree where the transaction appears
    SubtreeIdx  int
}

UnresolvedMetaData

Holds metadata for unresolved transactions.

type UnresolvedMetaData struct {
    // Hash is the transaction hash
    Hash chainhash.Hash
    // Idx is the index in the original list of hashes passed to BatchDecorate
    Idx int
    // Data holds the fetched metadata, nil until fetched
    Data *meta.Data
    // Fields specifies which metadata fields should be fetched
    Fields []fields.FieldName
    // Err holds any error encountered while fetching the metadata
    Err error
}

IgnoreFlags

Options for ignoring certain flags during UTXO operations.

type IgnoreFlags struct {
    IgnoreConflicting bool
    IgnoreUnspendable bool
}

CreateOptions

Options for creating a new UTXO entry.

type CreateOptions struct {
    MinedBlockInfos []MinedBlockInfo
    TxID            *chainhash.Hash
    IsCoinbase      *bool
    Frozen          bool
    Conflicting     bool
    Unspendable     bool
}

Store Interface

The Store interface defines the contract for UTXO storage operations. Implementations must be thread-safe as they will be accessed concurrently.

type Store interface {
    // Health checks the health status of the UTXO store.
    // If checkLiveness is true, it performs additional liveness checks.
    // Returns status code, status message and any error encountered.
    Health(ctx context.Context, checkLiveness bool) (int, string, error)

    // Create stores a new transaction's outputs as UTXOs and returns associated metadata.
    // The blockHeight parameter is used to determine coinbase maturity.
    // Additional options can be specified using CreateOption functions.
    Create(ctx context.Context, tx *bt.Tx, blockHeight uint32, opts ...CreateOption) (*meta.Data, error)

    // Get retrieves UTXO metadata for a given transaction hash.
    // The fields parameter can be used to specify which metadata fields to retrieve.
    // If fields is empty, all fields will be retrieved.
    Get(ctx context.Context, hash *chainhash.Hash, fields ...fields.FieldName) (*meta.Data, error)

    // Delete removes a UTXO and its associated metadata from the store.
    Delete(ctx context.Context, hash *chainhash.Hash) error

    // GetSpend retrieves information about a UTXO's spend status.
    GetSpend(ctx context.Context, spend *Spend) (*SpendResponse, error)

    // GetMeta retrieves transaction metadata.
    GetMeta(ctx context.Context, hash *chainhash.Hash) (*meta.Data, error)

    // Spend marks all the UTXOs of the transaction as spent.
    Spend(ctx context.Context, tx *bt.Tx, ignoreFlags ...IgnoreFlags) ([]*Spend, error)

    // Unspend reverses a previous spend operation, marking UTXOs as unspent.
    // This is used during blockchain reorganizations.
    Unspend(ctx context.Context, spends []*Spend, flagAsUnspendable ...bool) error

    // SetMinedMulti updates the block ID for multiple transactions that have been mined.
    SetMinedMulti(ctx context.Context, hashes []*chainhash.Hash, minedBlockInfo MinedBlockInfo) error

    // BatchDecorate efficiently fetches metadata for multiple transactions.
    // The fields parameter specifies which metadata fields to retrieve.
    BatchDecorate(ctx context.Context, unresolvedMetaDataSlice []*UnresolvedMetaData, fields ...fields.FieldName) error

    // PreviousOutputsDecorate fetches information about transaction inputs' previous outputs.
    PreviousOutputsDecorate(ctx context.Context, outpoints []*meta.PreviousOutput) error

    // FreezeUTXOs marks UTXOs as frozen, preventing them from being spent.
    // This is used by the alert system to prevent spending of UTXOs.
    FreezeUTXOs(ctx context.Context, spends []*Spend, tSettings *settings.Settings) error

    // UnFreezeUTXOs removes the frozen status from UTXOs, allowing them to be spent again.
    UnFreezeUTXOs(ctx context.Context, spends []*Spend, tSettings *settings.Settings) error

    // ReAssignUTXO reassigns a UTXO to a new transaction output.
    // The UTXO will become spendable after ReAssignedUtxoSpendableAfterBlocks blocks.
    ReAssignUTXO(ctx context.Context, utxo *Spend, newUtxo *Spend, tSettings *settings.Settings) error

    // GetCounterConflicting returns the counter conflicting transactions for a given transaction hash.
    GetCounterConflicting(ctx context.Context, txHash chainhash.Hash) ([]chainhash.Hash, error)

    // GetConflictingChildren returns the children of the given conflicting transaction.
    GetConflictingChildren(ctx context.Context, txHash chainhash.Hash) ([]chainhash.Hash, error)

    // SetConflicting marks transactions as conflicting or not conflicting and returns the affected spends.
    SetConflicting(ctx context.Context, txHashes []chainhash.Hash, value bool) ([]*Spend, []chainhash.Hash, error)

    // SetUnspendable marks transactions as unspendable or spendable.
    SetUnspendable(ctx context.Context, txHashes []chainhash.Hash, value bool) error

    // SetBlockHeight updates the current block height in the store.
    SetBlockHeight(height uint32) error

    // GetBlockHeight returns the current block height from the store.
    GetBlockHeight() uint32

    // SetMedianBlockTime updates the median block time in the store.
    SetMedianBlockTime(height uint32) error

    // GetMedianBlockTime returns the current median block time from the store.
    GetMedianBlockTime() uint32

    // Close closes the UTXO store and releases resources.
    Close(ctx context.Context) error
}

Key Functions

  • Health: Checks the health status of the UTXO store, optionally verifying liveness.
  • Create: Creates new UTXO entries from a transaction's outputs with configurable options.
  • Get: Retrieves UTXO metadata for specific fields with field-level filtering.
  • Delete: Removes a UTXO entry and its associated metadata.
  • GetSpend: Retrieves information about a UTXO's spend status, including spending transaction data.
  • Spend: Marks UTXOs as spent by a transaction, with optional flags for handling conflicts.
  • Unspend: Reverses spend operations during blockchain reorganization.
  • BatchDecorate: Efficiently fetches metadata for multiple transactions in a single operation.
  • FreezeUTXOs/UnFreezeUTXOs: Manages frozen status of UTXOs for the alert system.
  • SetConflicting/SetUnspendable: Controls transaction conflict and spendability status.
  • GetMeta: Retrieves transaction metadata for a single transaction.
  • SetMinedMulti: Updates block information for multiple mined transactions.
  • PreviousOutputsDecorate: Fetches information about transaction inputs' previous outputs.
  • ReAssignUTXO: Reassigns a UTXO to a new transaction output with safety measures.
  • GetCounterConflicting/GetConflictingChildren: Manages conflict relationships between transactions.
  • SetBlockHeight/GetBlockHeight/SetMedianBlockTime/GetMedianBlockTime: Manages blockchain state.
  • Close: Properly closes the UTXO store and releases associated resources.

Create Options

  • WithMinedBlockInfo: Sets the block information (ID, height, and subtree index) for a new UTXO entry. This replaces the deprecated WithBlockIDs option and provides more detailed tracking of where UTXOs appear in the blockchain.
  • WithTXID: Sets the transaction ID for a new UTXO entry.
  • WithSetCoinbase: Sets the coinbase flag for a new UTXO entry.
  • WithFrozen: Sets the frozen status for a new UTXO entry.
  • WithConflicting: Sets the conflicting status for a new UTXO entry.
  • WithUnspendable: Sets the transaction as unspendable on creation.

Constants

  • MetaFields: Default fields for metadata retrieval.
  • MetaFieldsWithTx: Metadata fields including the transaction.

Mock Implementation

The MockUtxostore struct provides a mock implementation of the Store interface for testing purposes.