BSV.TxBuilder (BSV v2.1.0) View Source

A flexible and powerful transaction building module and API.

The TxBuilder accepts inputs and outputs that are modules implementing the BSV.Contract behaviour. This abstraction makes for a succinct and elegant approach to building transactions. The BSV.Contract behaviour is flexible and can be used to define any kind of locking and unlocking script, not limited to a handful of standard transactions.

Examples

Because each input and output is prepared with all the information it needs, calling to_tx/1 is all that is needed to build and sign the transaction.

iex> utxo = UTXO.from_params!(%{
...>   "txid" => "5e3014372338f079f005eedc85359e4d96b8440e7dbeb8c35c4182e0c19a1a12",
...>   "vout" => 0,
...>   "satoshis" => 11000,
...>   "script" => "76a914538fd179c8be0f289c730e33b5f6a3541be9668f88ac"
...> })
iex>
iex> builder = %TxBuilder{
...>   inputs: [
...>     P2PKH.unlock(utxo, %{keypair: @keypair})
...>   ],
...>   outputs: [
...>     P2PKH.lock(10000, %{address: @address}),
...>     OpReturn.lock(0, %{data: ["hello", "world"]})
...>   ]
...> }
iex>
iex> tx = TxBuilder.to_tx(builder)
iex> Tx.to_binary(tx, encoding: :hex)
"0100000001121a9ac1e082415cc3b8be7d0e44b8964d9e3585dcee05f079f038233714305e000000006a47304402200f674ba40b14b8f85b751ad854244a4199008c5b491b076df2eb6c3efd0be4bf022004b48ef0e656ee1873d07cb3b06858970de702f63935df2fbe8816f1a5f15e1e412103f81f8c8b90f5ec06ee4245eab166e8af903fc73a6dd73636687ef027870abe39ffffffff0210270000000000001976a914538fd179c8be0f289c730e33b5f6a3541be9668f88ac00000000000000000e006a0568656c6c6f05776f726c6400000000"

Link to this section Summary

Types

Fee quote

t()

TxBuilder struct

Functions

Adds the given unlocking script contract to the builder.

Adds the given locking script contract to the builder.

Calculates the required fee for the builder's transaction, optionally using the given fee_quote/0.

Sets the change script on the builder as a P2PKH locking script to the given address.

Returns the sum of all inputs defined in the builder.

Returns the sum of all outputs defined in the builder.

Sorts the TxBuilder inputs and outputs according to BIP-69.

Builds and returns the signed transaction.

Link to this section Types

Specs

fee_quote() ::
  %{
    mine: %{data: number(), standard: number()},
    relay: %{data: number(), standard: number()}
  }
  | %{data: number(), standard: number()}
  | number()

Fee quote

A fee quote is a data structure representing miner fees. It can be either a single number representing satoshis per bytes, or a map with keys for both :data and :standard miner rates.

Specs

t() :: %BSV.TxBuilder{
  change_script: BSV.Script.t() | nil,
  inputs: [BSV.Contract.t()],
  lock_time: non_neg_integer(),
  options: map(),
  outputs: [BSV.Contract.t()]
}

TxBuilder struct

Link to this section Functions

Link to this function

add_input(builder, input)

View Source

Specs

add_input(t(), BSV.Contract.t()) :: t()

Adds the given unlocking script contract to the builder.

Link to this function

add_output(builder, output)

View Source

Specs

add_output(t(), BSV.Contract.t()) :: t()

Adds the given locking script contract to the builder.

Link to this function

calc_required_fee(builder, rates \\ %{mine: %{data: 0.5, standard: 0.5}, relay: %{data: 0.25, standard: 0.25}})

View Source

Specs

calc_required_fee(t(), fee_quote()) :: non_neg_integer()

Calculates the required fee for the builder's transaction, optionally using the given fee_quote/0.

When different :data and :standard rates are given, data outputs (identified by locking scripts beginning with OP_FALSE OP_RETURN) are calculated using the appropriate rate.

Link to this function

change_to(builder, address)

View Source

Specs

change_to(t(), BSV.Address.t() | BSV.Address.address_str()) :: t()

Sets the change script on the builder as a P2PKH locking script to the given address.

Specs

input_sum(t()) :: integer()

Returns the sum of all inputs defined in the builder.

Specs

output_sum(t()) :: integer()

Returns the sum of all outputs defined in the builder.

Specs

sort(t()) :: t()

Sorts the TxBuilder inputs and outputs according to BIP-69.

BIP-69 defines deterministic lexographical indexing of transaction inputs and outputs.

Specs

to_tx(t()) :: BSV.Tx.t()

Builds and returns the signed transaction.