btcruby 0.0.0 → 1.0.0

data/lib/btcruby/wif.rb

@@ -0,0 +1,118 @@
+module BTC
+  # Private key in Wallet Import Format (WIF aka Sipa format).
+  # Examples: 5KQntKuhYWSRXNq... or L3p8oAcQTtuokSC...
+  class WIF < Address
+
+    KEY_LENGTH = 32
+
+    def self.mainnet_version
+      128
+    end
+
+    def self.testnet_version
+      239
+    end
+
+    attr_accessor :public_key_compressed
+    def public_key_compressed?
+      @public_key_compressed
+    end
+
+    def key
+      BTC::Key.new(private_key: self.private_key, public_key_compressed: @public_key_compressed, network: self.network)
+    end
+
+    def private_key
+      @data
+    end
+
+    def public_address
+      self.key.address(network: self.network)
+    end
+
+    def ==(other)
+      return false if !other
+                       self.data == other.data &&
+                    self.version == other.version &&
+      self.public_key_compressed == other.public_key_compressed
+    end
+    alias_method :eql?, :==
+
+    # private API
+    def self.with_string(base58check_string, raw_data = nil)
+      raise ArgumentError, "Use WIF.new(string: ...) instead"
+    end
+
+    # Creates an address with private key data and non-compressed pubkey flag.
+    def self.with_data(data, public_key_compressed: false, network: nil)
+      raise ArgumentError, "Use WIF.new(private_key: ...) or WIF.new(key: ...) instead"
+    end
+
+    # Usage:
+    # * WIF.new(string: ...)
+    # * WIF.new(private_key: ..., public_key_compressed: true|false, network: ...)
+    # * WIF.new(key: ...)
+    def initialize(string: nil,
+                   data: nil,
+                   network: nil,
+                   _raw_data: nil,
+                   private_key: nil,
+                   key: nil,
+                   public_key_compressed: nil)
+      if key
+        raise ArgumentError, "Key must contain private_key to be exported in WIF" if !key.private_key
+        private_key = key.private_key
+        if public_key_compressed == nil
+          public_key_compressed = key.public_key_compressed
+        end
+        network ||= key.network
+      end
+      if string
+        if data || private_key || key || (public_key_compressed != nil) || network
+          raise ArgumentError, "Cannot specify individual attributes when decoding WIF from string"
+        end
+        _raw_data ||= Base58.data_from_base58check(string)
+        if _raw_data.bytesize != (1 + KEY_LENGTH) && _raw_data.bytesize != (2 + KEY_LENGTH)
+          raise FormatError, "Raw WIF data should have size #{1 + KEY_LENGTH}(+1), but it is #{_raw_data.bytesize} instead"
+        end
+        # compressed flag is simply one more byte appended to the string
+        @base58check_string = string
+        @data = _raw_data[1, KEY_LENGTH]
+        @public_key_compressed = (_raw_data.bytesize == (2 + KEY_LENGTH))
+        @version = _raw_data.bytes.first
+        @network = nil
+      elsif data ||= private_key
+        if data.bytesize != KEY_LENGTH
+          raise FormatError, "Failed to create WIF: data should have size #{KEY_LENGTH}, but it is #{data.bytesize} instead"
+        end
+        @base58check_string = nil
+        @data = data
+        @public_key_compressed = public_key_compressed
+        if @public_key_compressed == nil
+          @public_key_compressed = false # legacy default is uncompressed pubkey
+        end
+        @version = nil
+        @network = network
+      else
+        raise ArgumentError, "Either data or string must be provided"
+      end
+    end
+
+    def data_for_base58check_encoding
+      data = BTC::Data.data_from_bytes([self.version]) + @data
+      if @public_key_compressed
+        data += BTC::Data.data_from_bytes([0x01])
+      end
+      return data
+    end
+
+    def inspect
+      %{#<#{self.class}:#{to_s} privkey:#{BTC::Data.hex_from_data(data)} (#{@public_key_compressed ? '' : 'un'}compressed pubkey)>}
+    end
+
+  end
+
+  # For compatibility
+  PrivateKeyAddress = WIF
+
+end

data/lib/btcruby/wire_format.rb

@@ -0,0 +1,362 @@
+# A collection of routines dealing with parsing and writing protocol messages.
+# Various structures have a variable-length data prepended by a length prefix which is itself of variable length.
+# This length prefix is a variable-length integer, varint (aka "CompactSize").
+#
+# NB. varint refers to https://en.bitcoin.it/wiki/Protocol_specification#Variable_length_integer and is what Satoshi called "CompactSize"
+# BitcoinQT has later added even more compact format called CVarInt to use in its local block storage. CVarInt is not implemented here.
+#
+#  Value           Storage length     Format
+#  < 0xfd          1                  uint8_t
+# <= 0xffff        3                  0xfd followed by the value as little endian uint16_t
+# <= 0xffffffff    5                  0xfe followed by the value as little endian uint32_t
+#  > 0xffffffff    9                  0xff followed by the value as little endian uint64_t
+#
+module BTC
+  module WireFormat
+    extend self
+
+    # Reads varint from data or stream.
+    # Either data or stream must be present (and only one of them).
+    # Optional offset is useful when reading from data.
+    # Returns [value, length] where value is a decoded integer value and length is number of bytes read (including offset bytes).
+    # Value may be nil when decoding failed (length might be zero or greater, depending on how much data was consumed before failing).
+    # Usage:
+    #   i, _ = read_varint(data: buffer, offset: 42)
+    #   i, _ = read_varint(stream: File.open('someblock','r'))
+    def read_varint(data: nil, stream: nil, offset: 0)
+      if data && !stream
+        return [nil, 0] if data.bytesize < 1 + offset
+
+        bytes = BTC::Data.bytes_from_data(data, offset: offset, limit: 9) # we don't need more than 9 bytes.
+
+        byte = bytes[0]
+
+        if byte < 0xfd
+          return [byte, offset + 1]
+        elsif byte == 0xfd
+          return [nil, 1] if data.bytesize < 3 + offset # 1 byte prefix, 2 bytes uint16
+          return [bytes[1] +
+                  bytes[2]*256, offset + 3]
+        elsif byte == 0xfe
+          return [nil, 1] if data.bytesize < 5 + offset # 1 byte prefix, 4 bytes uint32
+          return [bytes[1] +
+                  bytes[2]*256 +
+                  bytes[3]*256*256 +
+                  bytes[4]*256*256*256, offset + 5]
+        elsif byte == 0xff
+          return [nil, 1] if data.bytesize < 9 + offset # 1 byte prefix, 8 bytes uint64
+          return [bytes[1] +
+                  bytes[2]*256 +
+                  bytes[3]*256*256 +
+                  bytes[4]*256*256*256 +
+                  bytes[5]*256*256*256*256 +
+                  bytes[6]*256*256*256*256*256 +
+                  bytes[7]*256*256*256*256*256*256 +
+                  bytes[8]*256*256*256*256*256*256*256, offset + 9]
+        end
+
+      elsif stream && !data
+
+        if stream.eof?
+          raise ArgumentError, "Can't parse varint from stream because it is already closed."
+        end
+
+        if offset > 0
+          buf = stream.read(offset)
+          return [nil, 0] if !buf
+          return [nil, buf.bytesize] if buf.bytesize < offset
+        end
+
+        prefix = stream.read(1)
+
+        return [nil, offset] if !prefix || prefix.bytesize == 0
+
+        byte = prefix.bytes[0]
+
+        if byte < 0xfd
+          return [byte, offset + 1]
+        elsif byte == 0xfd
+          buf = stream.read(2)
+          return [nil, offset + 1] if !buf
+          return [nil, offset + 1 + buf.bytesize] if buf.bytesize < 2
+          return [buf.unpack("v").first, offset + 3]
+        elsif byte == 0xfe
+          buf = stream.read(4)
+          return [nil, offset + 1] if !buf
+          return [nil, offset + 1 + buf.bytesize] if buf.bytesize < 4
+          return [buf.unpack("V").first, offset + 5]
+        elsif byte == 0xff
+          buf = stream.read(8)
+          return [nil, offset + 1] if !buf
+          return [nil, offset + 1 + buf.bytesize] if buf.bytesize < 8
+          return [buf.unpack("Q<").first, offset + 9]
+        end
+
+      else
+        raise ArgumentError, "Either data or stream must be specified."
+      end
+    end # read_varint
+
+    # Encodes integer and returns its binary varint representation.
+    def encode_varint(i)
+      raise ArgumentError, "int must be present" if !i
+      raise ArgumentError, "int must be non-negative" if i < 0
+
+      buf = if i <  0xfd
+        [i].pack("C")
+      elsif i <= 0xffff
+        [0xfd, i].pack("Cv")
+      elsif i <= 0xffffffff
+        [0xfe, i].pack("CV")
+      elsif i <= 0xffffffffffffffff
+        [0xff, i].pack("CQ<")
+      else
+        raise ArgumentError, "Does not support integers larger 0xffffffffffffffff (i = 0x#{i.to_s(16)})"
+      end
+
+      buf
+    end
+
+    # Encodes integer and returns its binary varint representation.
+    # If data is given, appends to a data.
+    # If stream is given, writes to a stream.
+    def write_varint(i, data: nil, stream: nil)
+      buf = encode_varint(i)
+      data << buf if data
+      stream.write(buf) if stream
+      buf
+    end
+
+    # Reads variable-length string from data buffer or IO stream.
+    # Either data or stream must be present (and only one of them).
+    # Returns [string, length] where length is a number of bytes read (includes length prefix and offset bytes).
+    # In case of failure, returns [nil, length] where length is a number of bytes read before the error was encountered.
+    def read_string(data: nil, stream: nil, offset: 0)
+      if data && !stream
+
+        string_length, read_length = read_varint(data: data, offset: offset)
+
+        # If failed to read the length prefix, return nil.
+        return [nil, read_length] if !string_length
+
+        # Check if we have enough bytes to read the string itself
+        return [nil, read_length] if data.bytesize < read_length + string_length
+
+        string = BTC::Data.ensure_binary_encoding(data)[read_length, string_length]
+
+        return [string, read_length + string_length]
+
+      elsif stream && !data
+
+        string_length, read_length = read_varint(stream: stream, offset: offset)
+        return [nil, read_length] if !string_length
+
+        buf = stream.read(string_length)
+
+        return [nil, read_length] if !buf
+        return [nil, read_length + buf.bytesize] if buf.bytesize < string_length
+
+        return [buf, read_length + buf.bytesize]
+      else
+        raise ArgumentError, "Either data or stream must be specified."
+      end
+    end
+
+    # Returns the binary representation of the var-length string.
+    def encode_string(string)
+      raise ArgumentError, "String must be present" if !string
+      encode_varint(string.bytesize) + BTC::Data.ensure_binary_encoding(string)
+    end
+
+    # Writes variable-length string to a data buffer or IO stream.
+    # If data is given, appends to a data.
+    # If stream is given, writes to a stream.
+    # Returns the binary representation of the var-length string.
+    def write_string(string, data: nil, stream: nil)
+      raise ArgumentError, "String must be present" if !string
+
+      intbuf = write_varint(string.bytesize, data: data, stream: stream)
+
+      stringbuf = BTC::Data.ensure_binary_encoding(string)
+
+      data << stringbuf if data
+      stream.write(stringbuf) if stream
+
+      intbuf + stringbuf
+    end
+    
+    
+    # LEB128 encoding used in Open Assets protocol
+    
+    # Decodes an unsigned integer encoded in LEB128.
+    # Returns `[value, length]` where `value` is an integer decoded from LEB128 and `length` 
+    # is a number of bytes read (includes length prefix and offset bytes).
+    def read_uleb128(data: nil, stream: nil, offset: 0)
+      if (data && stream) || (!data && !stream)
+        raise ArgumentError, "Either data or stream must be specified."
+      end
+      if data
+        data = BTC::Data.ensure_binary_encoding(data)
+      end
+      if stream
+        if stream.eof?
+          raise ArgumentError, "Can't read LEB128 from stream because it is already closed."
+        end
+        if offset > 0
+          buf = stream.read(offset)
+          return [nil, 0] if !buf
+          return [nil, buf.bytesize] if buf.bytesize < offset
+        end
+      end
+      result = 0
+      shift = 0
+      while true
+        byte = if data
+          return [nil, offset] if data.bytesize < 1 + offset
+          BTC::Data.bytes_from_data(data, offset: offset, limit: 1)[0]
+        elsif stream
+          buf = stream.read(1)
+          return [nil, offset] if !buf || buf.bytesize == 0
+          buf.bytes[0]
+        end
+        result |= (byte & 0x7f) << shift
+        break if byte & 0x80 == 0
+        shift += 7
+        offset += 1
+      end
+      [result, offset + 1]
+    end
+
+    # Encodes an unsigned integer using LEB128.
+    def encode_uleb128(value)
+      raise ArgumentError, "Signed integers are not supported" if value < 0
+      return "\x00" if value == 0
+      bytes = []
+      while value != 0
+        byte = value & 0b01111111 # 0x7f
+        value >>= 7
+        if value != 0
+          byte |= 0b10000000 # 0x80
+        end
+        bytes << byte
+      end
+      return BTC::Data.data_from_bytes(bytes)
+    end
+
+    # Writes an unsigned integer encoded in LEB128 to a data buffer or a stream.
+    # Returns LEB128-encoded binary string.
+    def write_uleb128(value, data: nil, stream: nil)
+      raise ArgumentError, "Integer must be present" if !value
+      buf = encode_uleb128(value)
+      data << buf if data
+      stream.write(buf) if stream
+      buf
+    end
+    
+    
+
+    PACK_FORMAT_UINT8    = "C".freeze
+    PACK_FORMAT_INT8     = "c".freeze
+    PACK_FORMAT_UINT16LE = "S<".freeze
+    PACK_FORMAT_INT16LE  = "s<".freeze
+    PACK_FORMAT_UINT32LE = "L<".freeze
+    PACK_FORMAT_INT32LE  = "l<".freeze
+    PACK_FORMAT_UINT32BE = "L>".freeze # used in BIP32
+    PACK_FORMAT_UINT64LE = "Q<".freeze
+    PACK_FORMAT_INT64LE  = "q<".freeze
+
+    # These read fixed-length integer in appropriate format ("le" stands for "little-endian")
+    # Return [value, length] or [nil, length] just like #read_varint method (see above).
+    def read_uint8(data: nil, stream: nil, offset: 0)
+      _read_fixint(name: :uint8,    length: 1, pack_format: PACK_FORMAT_UINT8,    data: data, stream: stream, offset: offset)
+    end
+
+    def read_int8(data: nil, stream: nil, offset: 0)
+      _read_fixint(name: :int8,     length: 1, pack_format: PACK_FORMAT_INT8,     data: data, stream: stream, offset: offset)
+    end
+
+    def read_uint16le(data: nil, stream: nil, offset: 0)
+      _read_fixint(name: :uint16le, length: 2, pack_format: PACK_FORMAT_UINT16LE, data: data, stream: stream, offset: offset)
+    end
+
+    def read_int16le(data: nil, stream: nil, offset: 0)
+      _read_fixint(name: :int16le,  length: 2, pack_format: PACK_FORMAT_INT16LE,  data: data, stream: stream, offset: offset)
+    end
+
+    def read_uint32le(data: nil, stream: nil, offset: 0)
+      _read_fixint(name: :uint32le, length: 4, pack_format: PACK_FORMAT_UINT32LE, data: data, stream: stream, offset: offset)
+    end
+
+    def read_int32le(data: nil, stream: nil, offset: 0)
+      _read_fixint(name: :int32le,  length: 4, pack_format: PACK_FORMAT_INT32LE,  data: data, stream: stream, offset: offset)
+    end
+    
+    def read_uint32be(data: nil, stream: nil, offset: 0) # used in BIP32
+      _read_fixint(name: :uint32be, length: 4, pack_format: PACK_FORMAT_UINT32BE, data: data, stream: stream, offset: offset)
+    end
+
+    def read_uint64le(data: nil, stream: nil, offset: 0)
+      _read_fixint(name: :uint64le, length: 8, pack_format: PACK_FORMAT_UINT64LE, data: data, stream: stream, offset: offset)
+    end
+
+    def read_int64le(data: nil, stream: nil, offset: 0)
+      _read_fixint(name: :int64le,  length: 8, pack_format: PACK_FORMAT_INT64LE,  data: data, stream: stream, offset: offset)
+    end
+
+    # Encode int into one of the formats
+    def encode_uint8(int);    [int].pack(PACK_FORMAT_UINT8);    end
+    def encode_int8(int);     [int].pack(PACK_FORMAT_INT8);     end
+    def encode_uint16le(int); [int].pack(PACK_FORMAT_UINT16LE); end
+    def encode_int16le(int);  [int].pack(PACK_FORMAT_INT16LE);  end
+    def encode_uint32le(int); [int].pack(PACK_FORMAT_UINT32LE); end
+    def encode_int32le(int);  [int].pack(PACK_FORMAT_INT32LE);  end
+    def encode_uint32be(int); [int].pack(PACK_FORMAT_UINT32BE); end # used in BIP32
+    def encode_uint64le(int); [int].pack(PACK_FORMAT_UINT64LE); end
+    def encode_int64le(int);  [int].pack(PACK_FORMAT_INT64LE);  end
+
+
+    protected
+
+    def _read_fixint(name: nil, length: nil, pack_format: nil, data: nil, stream: nil, offset: 0)
+      if data && !stream
+
+        if data.bytesize < offset + length
+          Diagnostics.current.add_message("BTC::WireFormat#read_#{name}: Not enough bytes to read #{name} in binary string.")
+          return [nil, 0]
+        end
+
+        if offset > 0
+          pack_format = "@#{offset}" + pack_format
+        end
+
+        return [data.unpack(pack_format).first, offset + length]
+
+      elsif stream && !data
+
+        if offset > 0
+          buf = stream.read(offset)
+          return [nil, 0] if !buf
+          return [nil, buf.bytesize] if buf.bytesize < offset
+        end
+
+        buf = stream.read(length)
+
+        if !buf
+          Diagnostics.current.add_message("BTC::WireFormat#read_#{name}: Failed to read #{name} from stream.")
+          return [nil, offset]
+        end
+
+        if buf.bytesize < length
+          Diagnostics.current.add_message("BTC::WireFormat#read_#{name}: Not enough bytes to read #{name} from stream.")
+          return [nil, offset + buf.bytesize]
+        end
+
+        return [buf.unpack(pack_format).first, offset + length]
+
+      else
+        raise ArgumentError, "BTC::WireFormat#read_#{name}: Either data or stream must be specified."
+      end
+    end
+
+  end
+end

data/lib/btcruby.rb

@@ -1,2 +1,44 @@
-module BTC
-end
+
+require 'ffi' # gem install ffi
+
+# Tip: import 'btcruby/extensions' to enable extensions to standard classes (e.g. String#to_hex)
+# Extensions are not imported by default to avoid conflicts with other libraries.
+
+require_relative 'btcruby/version.rb'
+require_relative 'btcruby/errors.rb'
+require_relative 'btcruby/diagnostics.rb'
+require_relative 'btcruby/safety.rb'
+require_relative 'btcruby/hash_functions.rb'
+require_relative 'btcruby/data.rb'
+require_relative 'btcruby/openssl.rb'
+require_relative 'btcruby/big_number.rb'
+require_relative 'btcruby/base58.rb'
+
+require_relative 'btcruby/constants.rb'
+require_relative 'btcruby/currency_formatter.rb'
+require_relative 'btcruby/network.rb'
+require_relative 'btcruby/address.rb'
+require_relative 'btcruby/wif.rb'
+require_relative 'btcruby/key.rb'
+require_relative 'btcruby/keychain.rb'
+require_relative 'btcruby/wire_format.rb'
+require_relative 'btcruby/hash_id.rb'
+require_relative 'btcruby/transaction.rb'
+require_relative 'btcruby/transaction_input.rb'
+require_relative 'btcruby/transaction_output.rb'
+require_relative 'btcruby/transaction_outpoint.rb'
+require_relative 'btcruby/script.rb'
+require_relative 'btcruby/opcode.rb'
+require_relative 'btcruby/signature_hashtype.rb'
+require_relative 'btcruby/transaction_builder.rb'
+require_relative 'btcruby/proof_of_work.rb'
+require_relative 'btcruby/block_header.rb'
+require_relative 'btcruby/block.rb'
+require_relative 'btcruby/open_assets.rb'
+
+# TODO:
+# require_relative 'btcruby/curve_point.rb'
+# require_relative 'btcruby/script_machine.rb'
+# require_relative 'btcruby/merkle_block.rb'
+# require_relative 'btcruby/bloom_filter.rb'
+# require_relative 'btcruby/processor.rb'

data/sample_code/creating_a_p2sh_multisig_address.rb

@@ -0,0 +1,21 @@
+# Creating a P2SH multisig address
+# --------------------------------
+#
+# To create a P2SH multisig address you will need a set of public keys.
+# In the example below we generate three random keys and compose 2-of-3 multisig script
+# which is then transformed into a P2SH address. To redeem from this address you will need
+# not only two signatures, but also the original multisig script.
+
+require_relative "../lib/btcruby.rb"
+
+keys = [BTC::Key.random, BTC::Key.random, BTC::Key.random]
+pubkeys = keys.map(&:public_key)
+
+multisig_script = BTC::Script.multisig_script(public_keys: pubkeys, signatures_required: 2)
+puts multisig_script.to_s # => "OP_2 03e4e14a... 03b4b3f7... 030fa2ec... OP_3 OP_CHECKMULTISIG"
+
+p2sh_script = multisig_script.p2sh_script
+puts p2sh_script.to_s # => "OP_HASH160 26f5b7ad4e890c07b8c55fc551e39d6693c5e984 OP_EQUAL"
+
+address = p2sh_script.standard_address
+puts address.to_s # => 35F1xaoodzRZUBJHi6TgA85qPjXQcW8XsQ

data/sample_code/creating_a_transaction_manually.rb

@@ -0,0 +1,44 @@
+# Creating a transaction manually
+# -------------------------------
+#
+# To manually create a transaction, you will need to specify raw inputs,
+# compute the signature and compose a signature script for each input and
+# take care of calculating a change amount correctly.
+
+require_relative "../lib/btcruby.rb"
+
+include BTC
+
+tx = Transaction.new
+
+# 1. Add a raw input with previous transaction ID and output index.
+tx.add_input(TransactionInput.new(
+                previous_id: "aa94ab02c182214f090e99a0d57021caffd0f195a81c24602b1028b130b63e31",
+                previous_index: 0))
+
+# 2. Add a raw output with a script
+tx.add_output(TransactionOutput.new(
+                value: 100_000,
+                script: PublicKeyAddress.with_string("1CBtcGivXmHQ8ZqdPgeMfcpQNJrqTrSAcG").script))
+
+# 3. Get the private key from WIF
+key = Key.new(wif: "L1uyy5qTuGrVXrmrsvHWHgVzW9kKdrp27wBC7Vs6nZDTF2BRUVwy")
+
+# 4. Sign the input (assuming it links to an output with address 18oxCAnbuKHDjP7KzLBDj8mLjggDBjE1Q9)
+hashtype = BTC::SIGHASH_ALL
+sighash = tx.signature_hash(input_index: 0,
+                            output_script: PublicKeyAddress.with_string("18oxCAnbuKHDjP7KzLBDj8mLjggDBjE1Q9").script,
+                            hash_type: hashtype)
+tx.inputs[0].signature_script = Script.new << (key.ecdsa_signature(sighash) + WireFormat.encode_uint8(hashtype)) << key.public_key
+
+# Get transaction data and broadcast it
+puts "Binary transaction:"
+puts tx.data # => raw binary data
+puts "Hex transaction:"
+puts tx.to_hex # hex-encoded data
+# => 0100000001313eb630b128102b60241ca895f1d0ffca2170d5a0990e094f2182c102ab94aa
+#    000000006a473044022039148258144202301221a305adb38ce0a182ecb4055c6015cdd735
+#    8372d7ad6d022008aa259c87177f0e4e887dd0947c57fd140eb8f8a826f14ef8389dbc26ef
+#    a7b20121029f50f51d63b345039a290c94bffd3180c99ed659ff6ea6b1242bca47eb93b59f
+#    ffffffff01a0860100000000001976a9147ab89f9fae3f8043dcee5f7b5467a0f0a6e2f7e1
+#    88ac00000000

data/sample_code/generating_an_address.rb

@@ -0,0 +1,20 @@
+# Generating an address
+# ---------------------
+#
+# This example demonstrates how to generate a key and get its address.
+
+require_relative "../lib/btcruby.rb"
+
+key = BTC::Key.random
+
+puts key.to_wif # private key in WIF format
+# => L4RqZhbn2VsVgy2wCWW8kUPpA4xEkH7WbfPtj1MdFug5MayHzLeT
+
+puts key.address.to_s # public address
+# => 1MFqAcAxNsAKj5e6yksZCCyfNukSdDGsEY
+
+puts key.to_wif(network: BTC::Network.testnet)
+# => cUnq2cbdTZZkrQWCavKG7ntsnJFeQjDCfhYMqRp8m2L5cL1yHDmc
+
+puts key.address(network: BTC::Network.testnet).to_s
+# => n1mnTfFwBtbaWC7ihKqw28BzEuM9YqxRyw

data/sample_code/using_transaction_builder.rb

@@ -0,0 +1,49 @@
+# Using transaction builder
+# -------------------------
+# 
+# Transaction builder helps composing arbitrary transactions using just keys or unspent outputs.
+# It takes care of computing a proper change amount, adding fees and signing inputs.
+# It is also highly customizable, so you may use it for very complex transactions.
+
+require_relative "../lib/btcruby.rb"
+
+builder = BTC::TransactionBuilder.new
+
+# 1. Provide a list of address to get unspent outputs from.
+#    If address is a WIF instance, it will be used to sign corresponding input
+#    If address is a public address (or P2SH), its input will remain unsigned.
+builder.input_addresses = [ BTC::Key.new(wif: "L1uyy5qTuGrVXrmrsvHWHgVzW9kKdrp27wBC7Vs6nZDTF2BRUVwy").to_wif_object ]
+
+# 2. Use external API (e.g. Chain.com) to fetch unspent outputs for the input addresses.
+#    In this example we simply hard-code a single unspent output.
+#    Note: transaction ID and output index must be provided.
+builder.unspent_outputs_provider_block = lambda do |addresses, outputs_amount, outputs_size, fee|
+  txout = BTC::TransactionOutput.new(
+    value: 50_000,
+    script: BTC::PublicKeyAddress.with_string("17XBj6iFEsf8kzDMGQk5ghZipxX49VXuaV").script,
+    transaction_id: "115e8f72f39fad874cfab0deed11a80f24f967a84079fb56ddf53ea02e308986",
+    index: 0
+  )
+  [ txout ]
+end
+
+# 3. Specify payment address and amount
+builder.outputs = [ BTC::TransactionOutput.new(
+                        value: 10_000, 
+                        script: BTC::PublicKeyAddress.with_string("17XBj6iFEsf8kzDMGQk5ghZipxX49VXuaV").script) ]
+
+# 4. Specify the change address
+builder.change_address = BTC::PublicKeyAddress.with_string("1CBtcGivXmHQ8ZqdPgeMfcpQNJrqTrSAcG")
+
+# 5. Build the transaction and broadcast it.
+result = builder.build
+tx = result.transaction
+puts tx.to_hex 
+
+# => 01000000018689302ea03ef5dd56fb7940a867f9240fa811eddeb0fa4c87ad9ff3728f5e11
+#    000000006b483045022100e280f71106a84a4a1b1a2035eae70266eb53630beab2b59cc8cf
+#    f40b1a5bdbb902201dcbae9bb12730fe5563dc37e3a33e064f2efa78ba0af5c0179187aece
+#    180b6c0121029f50f51d63b345039a290c94bffd3180c99ed659ff6ea6b1242bca47eb93b5
+#    9fffffffff0210270000000000001976a91447862fe165e6121af80d5dde1ecb478ed17056
+#    5b88ac30750000000000001976a9147ab89f9fae3f8043dcee5f7b5467a0f0a6e2f7e188ac
+#    00000000