BSV.Tokens.Lineage (bsv_sdk v1.1.0)

Copy Markdown View Source

Off-chain lineage validator for STAS tokens.

Walks the ancestor chain of a token UTXO back to the genesis (contract) transaction, verifying that every hop is a legitimate STAS token transfer or issuance.

Usage

validator = BSV.Tokens.Lineage.new(contract_txid, redemption_pkh)
{:ok, validator} = BSV.Tokens.Lineage.validate(validator, utxo_txid, vout, tx_fetcher_fn)

The tx_fetcher_fn is a function (txid_binary -> {:ok, raw_tx} | {:error, reason}).

Security Notice — Trust Model

This validator verifies the chain of txids and script types back to genesis, and confirms that sha256d(raw_tx) == expected_txid for each hop. However, it does not verify transaction signatures. It trusts the tx_fetcher to return authentic transaction data.

If the tx_fetcher is backed by an untrusted source, an attacker could supply fabricated transactions with valid txid hashes but forged scripts/outputs. For maximum security, combine lineage validation with SPV proof verification (Merkle path against a trusted block header) to confirm each transaction was actually mined.

Summary

Types

t()

Functions

is_validated?(lineage, txid)

Check whether a specific txid has already been validated.

new(arg1, arg2)

Create a new lineage validator.

validate(validator, utxo_txid, vout, tx_fetcher)

Validate a token UTXO's lineage back to the genesis transaction.

validated_count(lineage)

Return the number of txids that have been validated so far.

Types

t()

@type t() :: %BSV.Tokens.Lineage{
  contract_txid: <<_::256>>,
  redemption_pkh: <<_::160>>,
  validated: MapSet.t(binary())
}

Functions

is_validated?(lineage, txid)

@spec is_validated?(t(), binary()) :: boolean()

Check whether a specific txid has already been validated.

new(arg1, arg2)

@spec new(<<_::256>>, <<_::160>>) :: t()

Create a new lineage validator.

The contract TX is pre-validated (it is the trust anchor).

validate(validator, utxo_txid, vout, tx_fetcher)

@spec validate(t(), <<_::256>>, non_neg_integer(), (binary() ->
                                                {:ok, binary()}
                                                | {:error, term()})) ::
  {:ok, t()} | {:error, term()}

Validate a token UTXO's lineage back to the genesis transaction.

Note: Only the first input of each transaction is followed during ancestor traversal. Multi-input token merges are not fully validated — only the lineage through input 0 is checked.

The tx_fetcher is a function (txid :: binary -> {:ok, raw_tx} | {:error, reason}).

Returns {:ok, updated_validator} on success.

validated_count(lineage)

@spec validated_count(t()) :: non_neg_integer()

Return the number of txids that have been validated so far.