A behaviour module for implementing Bitcoin transaction contracts.

A Bitcoin transaction contains two sides: inputs and outputs.

Transaction outputs are script puzzles, called "locking scripts" (sometimes also known as a "ScriptPubKey") which lock a number of satoshis. Transaction inputs are contain an "unlocking script" (or the "ScriptSig") and unlock the satoshis contained in the previous transaction's outputs.

Therefore, each locking script is unlocked by a corresponding unlocking script.

The BSV.Contract module provides a way to define a locking script and unlocking script in a plain Elixir function. Because it is just Elixir, it is trivial to add helper functions and macros to reduce boilerplate and create more complex contract types and scripts.

Defining a contract

The following module implements a Pay to Public Key Hash contract. Implementing a contract is just a case of defining locking_script/2 and unlocking_script/2.

defmodule P2PKH do
  @moduledoc "Pay to Public Key Hash contract."
  use BSV.Contract

  @impl true
  def locking_script(ctx, %{address: address}) do
    ctx
    |> op_dup
    |> op_hash160
    |> push(address.pubkey_hash)
    |> op_equalverify
    |> op_checksig
  end

  @impl true
  def unlocking_script(ctx, %{keypair: keypair}) do
    ctx
    |> signature(keypair.privkey)
    |> push(BSV.PubKey.to_binary(keypair.pubkey))
  end
end

Locking a contract

A contract locking script is initiated by calling lock/2 on the contract module, passing the number of satoshis and a map of parameters expected by locking_script/2 defined in the contract.

# Initiate the contract locking script
contract = P2PKH.lock(10_000, %{address: Address.from_pubkey(bob_pubkey)})

script = Contract.to_script(contract) # returns the locking script
txout = Contract.to_txout(contract)   # returns the full txout

Unlocking a contract

To unlock and spend the contract, a BSV.UTXO.t/0 is passed to unlock/2 with the parameters expected by unlocking_script/2 defined in the contract.

# Initiate the contract unlocking script
contract = P2PKH.unlock(utxo, %{keypair: keypair})

Optionally the current transaction context can be given to the contract. This allows the correct sighash to be calculated for any signatures.

# Pass the current transaction ctx
contract = Contract.put_ctx(contract, {tx, vin})

# returns the signed txin
txin = Contract.to_txin(contract)

Building transactions

The BSV.Contract behaviour is taken advantage of in the BSV.TxBuilder module, resulting in transaction building semantics that are easy to grasp and pleasing to work with.

builder = %TxBuilder{
  inputs: [
    P2PKH.unlock(utxo, %{keypair: keypair})
  ],
  outputs: [
    P2PKH.lock(10_000, %{address: address})
  ]
}

# Returns a fully signed transaction
TxBuilder.to_tx(builder)

For more information, refer to BSV.TxBuilder.