coin-op 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 15c0933fbbf6c12f7a0991e4a889f1ca232a006d
-  data.tar.gz: acf109f9766f69d87e14160cb8df32b06e475696
+  metadata.gz: 0549717040829929865680910e3d10be98a3a605
+  data.tar.gz: bab2d7e727c99896a8689b9819662c7f7a9c4b89
 SHA512:
-  metadata.gz: 3d79df943d4f273f8b067bc6e632cd4691090202a191738d87c844f7a8cc2dc71d3a918e1c96d84a5d36b3399a28789a997c8fe8d9e3f90478b261fc254539a2
-  data.tar.gz: e426b4496eb66d122b8fb82e6d08d71e6b35c16fdb649f57ee5ada6fe05d251cae64230693ebf666125c1337691d9f653452b3346cbc41b2c3e14a7f59ec2d26
+  metadata.gz: 20025659e8398d0ae10ed292335dcc21b835641339c9c9b864b768640a8b553b00945dd017058826078a2790a70ba5481d228532bc037abd829fac4d789705da
+  data.tar.gz: 33fbc0697dd2d619c9d9dfdfe259338de649fae5497563295afb7ed9ca2d15f2c19f1e9677a79b542cb02c2787fdb9ee0c0c91b3fab82f171b0abe1023d21e3b

data/README.md

@@ -5,13 +5,53 @@ Install:
     gem install coin-op
 
 
-Use:
+Basic usage:
 
 ```ruby
 require "coin-op"
 
 include CoinOp::Bit
 
+transaction = Transaction.from_data(
+  # Override the minimum suggested fee
+  :fee => 20_000,
+  :inputs => [
+    {
+      :output => {
+        :transaction_hash => "2f47a8d7537fd981670b6142f86e1961991577506a825cdfb4c6ab3666db4fc1",
+        :index => 0,
+        :value => 2_000_000
+      }
+    },
+    {
+      :output => {
+        :transaction_hash => "fe4d26f6536c17c451e7d9fd7bca3e981a1c9f4542ee49f3bdcb71050c8ef243",
+        :index => 0,
+        :value => 2_600_000
+      }
+    }
+  ],
+  :outputs => [
+    {
+      :value => 3_000_000,
+      :address => "2N9c7acEJNHkDaQvRShMxJcBu5Lw535AvwR"
+    }
+  ]
+)
+
+transaction.add_change(change_address)
+
+# Set the script_sigs manually
+transaction.inputs[0].script_sig = "foo"
+transaction.inputs[1].script_sig = "bar"
+
+# Or use an iterating helper method. First argument is an array of
+# items corresponding to the inputs.  The block yields to you each
+# input, along with the corresponding element from your array.
+transaction.set_script_sigs *keypairs do |input, keypair|
+  sig_for(keypair, input)
+end
+
 ```
 
 # Developers

data/lib/coin-op.rb

@@ -7,6 +7,5 @@ end
 require_relative "coin-op/encodings"
 require_relative "coin-op/crypto"
 require_relative "coin-op/bit"
-require_relative "coin-op/blockchain/mockchain"
 require_relative "coin-op/blockchain/blockr"
 

data/lib/coin-op/bit.rb

@@ -1,4 +1,14 @@
 require "bitcoin"
+
+# bitcoin-ruby is not multi-network friendly.  It's also a hassle
+# to tell what network you're using if you don't already know.
+# This makes it a bit easier.
+Bitcoin::NETWORKS.each do |name, definition|
+  definition[:name] = name
+end
+
+
+# BIP 32 Hierarchical Deterministic Wallets
 require "money-tree"
 
 # establish the namespace
@@ -15,6 +25,7 @@ require_relative "bit/output"
 require_relative "bit/input"
 require_relative "bit/transaction"
 require_relative "bit/spendable"
+require_relative "bit/fee"
 
 # Augmented functionality
 require_relative "bit/multi_wallet"

data/lib/coin-op/bit/fee.rb

@@ -0,0 +1,84 @@
+
+module CoinOp::Bit
+
+  module Fee
+
+    module_function
+
+    # Given an array of unspent Outputs and an array of Outputs for a
+    # Transaction, estimate the fee required for the transaction to be
+    # included in a block.  Optionally takes an Integer specifying the
+    # transaction size in bytes, which is necessary when using unspents
+    # that deviate from the customary single signature.
+    #
+    # Returns the estimated fee in satoshis.
+    def estimate(unspents, payees, tx_size=nil)
+      # https://en.bitcoin.it/wiki/Transaction_fees
+
+      # dupe because we'll need to add a change output
+      payees = payees.dup
+
+      unspent_total = unspents.inject(0) {|sum, output| sum += output.value}
+      payee_total = payees.inject(0) {|sum, payee| sum += payee.value}
+      nominal_change = unspent_total - payee_total
+      payees << Output.new(:value => nominal_change)
+
+      tx_size ||= estimate_tx_size(unspents.size, payees.size)
+      min = payees.min_by {|payee| payee.value }
+
+      small = tx_size < 1000
+      big_outputs = min.value > 1_000_000
+
+      p = priority :size => tx_size, :unspents => (unspents.map do |output|
+        {:value => output.value, :age => output.confirmations}
+      end)
+      high_priority = p > PRIORITY_THRESHOLD
+
+      if small && big_outputs && high_priority
+        0
+      else
+        fee_for_bytes(tx_size)
+      end
+
+    end
+
+    def fee_for_bytes(bytes)
+      # https://en.bitcoin.it/wiki/Transaction_fees
+      # > the reference implementation will round up the transaction size to the
+      # > next thousand bytes and add a fee of 0.1 mBTC (0.0001 BTC) per thousand bytes
+      size = (bytes / 1000) + 1
+      Bitcoin.network[:min_tx_fee] * size
+    end
+
+    # From http://bitcoinfees.com.  This estimation is only valid for
+    # transactions with all inputs using the common "public key hash" method
+    # for authorization.
+    def estimate_tx_size(num_inputs, num_outputs)
+      # From http://bitcoinfees.com.
+      (148 * num_inputs) + (34 * num_outputs) + 10
+    end
+
+
+    # https://en.bitcoin.it/wiki/Transaction_fees#Including_in_Blocks
+    #
+    # https://en.bitcoin.it/wiki/Transaction_fees#Technical_info
+    # > Transactions need to have a priority above 57,600,000 to avoid the
+    # > enforced limit.... This threshold is written in the code as
+    # > COIN * 144 / 250, suggesting that the threshold represents a one day
+    # > old, 1 btc coin (144 is the expected number of blocks per day) and a
+    # > transaction size of 250 bytes.
+    PRIORITY_THRESHOLD = 57_600_000
+
+    def priority(params)
+      tx_size, unspents = params.values_at :size, :unspents
+      sum = unspents.inject(0) do |sum, output|
+        age = output[:age] || 0
+        sum += (output[:value] * age)
+        sum
+      end
+      sum / tx_size
+    end
+
+
+  end
+end

data/lib/coin-op/bit/input.rb

@@ -1,55 +1,60 @@
 
 module CoinOp::Bit
 
-  class SparseInput
-    include CoinOp::Encodings
-
-    def initialize(binary_hash, index)
-      @output = {
-        # the binary hash is the result of 
-        # [tx.hash].pack("H*").reverse
-        :transaction_hash => hex(binary_hash.reverse),
-        :index => index,
-      }
-    end
-
-    def to_json(*a)
-      {
-        :output => @output,
-      }.to_json(*a)
-    end
-
-  end
-
-
   class Input
+
     include CoinOp::Encodings
 
     attr_reader :native, :output, :binary_sig_hash,
       :signatures, :sig_hash, :script_sig, :index
 
+    # Takes a Hash containing these fields:
+    #
+    # * :transaction - a Transaction instance
+    # * :index - the index of the input within the transaction
+    # * :output - a value representing this input's unspent output
+    #
+    # Optionally:
+    #
+    # * script_sig_asm - the string form of the scriptSig for this input
+    #
     def initialize(options={})
       @transaction, @index, @output =
         options.values_at :transaction, :index, :output
 
+      script_sig_asm = options[:script_sig_asm]
+
       unless @output.is_a? Output
         @output = Output.new(@output)
       end
 
       @native = Bitcoin::Protocol::TxIn.new
 
+      # TODO: the reverse is cargo-culted from a function in bitcoin-ruby
+      # that doesn't document the reason.  Find the explanation in the bitcoin
+      # wiki or in the reference client source and document here.
       @native.prev_out = decode_hex(@output.transaction_hash).reverse
       @native.prev_out_index = @output.index
 
+      if script_sig_asm
+        self.script_sig = Bitcoin::Script.binary_from_string(script_sig_asm)
+      end
       @signatures = []
     end
 
+    # Set the sig_hash (the digest used in signing) for this input using a
+    # string of bytes.
     def binary_sig_hash=(blob)
+      # This is only a setter because of the initial choice to do things
+      # eagerly.  Can become an attr_accessor when we move to lazy eval.
       @binary_sig_hash = blob
       @sig_hash = hex(blob)
     end
 
+    # Set the scriptSig for this input using a string of bytes.
     def script_sig=(blob)
+      # This is only a setter because of the initial choice to do things
+      # eagerly.  Can become an attr_accessor when we move to lazy eval.
       script = Script.new(:blob => blob)
       @script_sig = script.to_s
       @native.script_sig = blob
@@ -67,6 +72,30 @@ module CoinOp::Bit
 
   end
 
+  # Used in Transaction.from_native or other situations where we do
+  # not have full information about the unspent output being used
+  # for an input.
+  class SparseInput
+    include CoinOp::Encodings
+
+    def initialize(binary_hash, index)
+      @output = {
+        # the binary hash is the result of 
+        # [tx.hash].pack("H*").reverse
+        :transaction_hash => hex(binary_hash.reverse),
+        :index => index,
+      }
+    end
+
+    def to_json(*a)
+      {
+        :output => @output,
+      }.to_json(*a)
+    end
+
+  end
+
+
 
 end
 

data/lib/coin-op/bit/multi_wallet.rb

@@ -6,32 +6,42 @@ module CoinOp::Bit
   class MultiWallet
     include CoinOp::Encodings
 
-    def self.generate(names, network=:bitcoin_testnet)
+    NetworkMap = {
+      :testnet3 => :bitcoin_testnet,
+      :bitcoin_testnet => :bitcoin_testnet,
+      :bitcoin => :bitcoin
+    }
+
+    def self.generate(names, network_name=:testnet3)
+      unless network = NetworkMap[network_name]
+        raise ArgumentError, "Unknown network #{network_name}"
+      end
       masters = {}
       names.each do |name|
         name = name.to_sym
         masters[name] = MoneyTree::Master.new(:network => network)
       end
-      self.new(:private => masters)
+      self.new(:private => masters, :network => network)
     end
 
     attr_reader :trees
 
     def initialize(options)
-      # FIXME: must accept option for which network to use.
       @private_trees = {}
       @public_trees = {}
       @trees = {}
-      private_trees = options[:private]
+      @network = NetworkMap[options.include? :network ? options[:network] : :testnet3]
 
       # FIXME: we should allow this.
-      if !private_trees
-        raise "Must supply :private"
-      end
+      # if !private_trees
+      #   raise "Must supply :private"
+      # end
 
-      private_trees.each do |name, arg|
-        name = name.to_sym
-        @private_trees[name] = @trees[name] = self.get_node(arg)
+      if private_trees = options[:private]
+        private_trees.each do |name, arg|
+          name = name.to_sym
+          @private_trees[name] = @trees[name] = self.get_node(arg)
+        end
       end
 
       if public_trees = options[:public]
@@ -130,7 +140,8 @@ module CoinOp::Bit
       options = {
         :path => path,
         :private => {},
-        :public => {}
+        :public => {},
+        :network => @network
       }
       @private_trees.each do |name, node|
         options[:private][name] = node.node_for_path(path)
@@ -142,6 +153,10 @@ module CoinOp::Bit
       MultiNode.new(options)
     end
 
+    def address(path)
+      path(path).address
+    end
+
     def valid_output?(output)
       if path = output.metadata.wallet_path
         node = self.path(path)
@@ -219,6 +234,7 @@ module CoinOp::Bit
       @public_keys = {}
       @private = options[:private]
       @public = options[:public]
+      @network = options[:network]
 
       @private.each do |name, node|
         key = Bitcoin::Key.new(node.private_key.to_hex, node.public_key.to_hex)
@@ -231,9 +247,9 @@ module CoinOp::Bit
     end
 
     def script(m=2)
-      # m of n 
+      # m of n
       keys = @public_keys.sort_by {|name, key| name }.map {|name, key| key.pub }
-      Script.new(:public_keys => keys, :needed => m)
+      Script.new(:public_keys => keys, :needed => m, :network => @network)
     end
 
     def address
@@ -243,7 +259,7 @@ module CoinOp::Bit
     alias_method :p2sh_address, :address
 
     def p2sh_script
-      Script.new(:address => self.script.p2sh_address)
+      Script.new(:address => self.script.p2sh_address, :network => @network)
     end
 
     def sign(name, value)
@@ -269,4 +285,3 @@ module CoinOp::Bit
 
 
 end
-

data/lib/coin-op/bit/output.rb

@@ -5,20 +5,21 @@ module CoinOp::Bit
     include CoinOp::Encodings
 
     attr_accessor :metadata
-    attr_reader :native, :transaction, :index, :value, :script, :address
+    attr_reader :native, :transaction, :index, :value, :script
 
     # Takes a Hash with required keys:
     #
-    # * either :transaction (an instance of Transaction)
-    #   or :transaction_hash (the hex-encoded hash of a Bitcoin transaction)
+    # * either  :transaction (instance of Transaction)
+    #   or      :transaction_hash (hex-encoded hash of a Bitcoin transaction)
     # * :index
-    # * :script
+    # * :value
     #
     # optional keys:
     #
-    # * :value
-    # * :metadata
-    # 
+    # * either  :script (a value usable in Script.new)
+    #   or      :address (a valid Bitcoin address)
+    # * :metadata (a Hash with arbitrary contents)
+    #
     def initialize(options)
       if options[:transaction]
         @transaction = options[:transaction]
@@ -28,26 +29,43 @@ module CoinOp::Bit
 
       # FIXME: be aware of string bitcoin values versus
       # integer satoshi values
-      @index, @value, @address = options.values_at :index, :value, :address
+      @index, @value, @address, confirmations =
+        options.values_at :index, :value, :address, :confirmations
+
       @metadata = options[:metadata] || {}
+      @metadata[:confirmations] ||= confirmations
 
       if options[:script]
         @script = Script.new(options[:script])
-      else
-        raise ArgumentError, "No script supplied"
+      elsif @address
+        @script = Script.new(:address => @address)
       end
 
+
       @native = Bitcoin::Protocol::TxOut.from_hash(
         "value" => @value.to_s,
         "scriptPubKey" => @script.to_s
       )
     end
 
+    # The bitcoin address generated from the associated Script.
+    def address
+      if @script
+        @script.address
+      end
+    end
+
+    def confirmations
+      @metadata[:confirmations]
+    end
+
+    # DEPRECATED
     def set_transaction(transaction, index)
       @transaction_hash = nil
       @transaction, @index = transaction, index
     end
 
+    # Returns the transaction hash for this output.
     def transaction_hash
       if @transaction
         @transaction.hex_hash

data/lib/coin-op/bit/script.rb

@@ -1,12 +1,37 @@
 
 module CoinOp::Bit
 
+  # A wrapper class to make it easier to read and write Bitcoin scripts.
+  # Provides a sane #to_json method.
   class Script
     include CoinOp::Encodings
 
+    # Accessor for the "native" ::Bitcoin::Script script instance
     attr_reader :native
 
+    # Takes either a String or a Hash as its argument.
+    #
+    # A String argument will be parsed as a human readable script.
+    #
+    # A Hash argument specifies a script using one of several possible
+    # keys:
+    #
+    # * :string
+    # * :blob
+    # * :hex
+    # * :address
+    # * :public_key
+    # * :public_keys, :needed
+    # * :signatures
+    #
+    # The name of the crypto-currency network may also be specified.  It
+    # defaults to :testnet3.  Names supplied in this manner must correspond
+    # to the names in the ::Bitcoin::NETWORKS Hash.
     def initialize(options)
+      # Doing the rescue in case the input argument is a String.
+      network_name = (options[:network] || :testnet3) rescue :testnet3
+      @network = Bitcoin::NETWORKS[network_name]
+
       # literals
       if options.is_a? String
         @blob = Bitcoin::Script.binary_from_string options
@@ -19,6 +44,9 @@ module CoinOp::Bit
       # arguments for constructing
       else
         if address = options[:address]
+          unless Bitcoin::valid_address?(address)
+            raise ArgumentError, "Invalid address: #{address}"
+          end
           @blob = Bitcoin::Script.to_address_script(address)
         elsif public_key = options[:public_key]
           @blob = Bitcoin::Script.to_pubkey_script(public_key)
@@ -36,6 +64,10 @@ module CoinOp::Bit
       @string = @native.to_string
     end
 
+    def address
+      @native.get_p2sh_address
+    end
+
     def to_s
       @string
     end
@@ -53,8 +85,11 @@ module CoinOp::Bit
     def type
       case self.native.type
       when :hash160
+        # Pay to address, because an "address" is really just the hash
+        # of a public key.
         :pubkey_hash
       when :p2sh
+        # Pay to Script Hash
         :script_hash
       else
         self.native.type
@@ -76,6 +111,10 @@ module CoinOp::Bit
       Bitcoin.hash160(@hex)
     end
 
+    # Generate the script that uses a P2SH address.
+    # Used for an Output's scriptPubKey value.  Not much used, and
+    # can probably be removed, as I think it is equivalent to
+    # Script.new :address => some_p2sh_address
     def p2sh_script
       self.class.new Bitcoin::Script.to_p2sh_script(self.hash160)
     end
@@ -84,6 +123,9 @@ module CoinOp::Bit
       Bitcoin.hash160_to_p2sh_address(self.hash160)
     end
 
+    # Generate a P2SH script_sig for the current script, using the
+    # supplied options, which will, in the case of a multisig input,
+    # be {:signatures => array_of_signatures}.
     def p2sh_sig(options)
       string = Script.new(options).to_s
       Bitcoin::Script.binary_from_string("#{string} #{self.to_hex}")

data/lib/coin-op/bit/spendable.rb

@@ -1,9 +1,21 @@
 module CoinOp::Bit
+
+  # A mixin to provide simple transaction preparation. Not currently
+  # used in any production code, so needs vetting.
+  #
+  # Requires the including class to define these methods:
+  #
+  # * network
+  # * balance
+  # * select_unspent
+  # * authorize
+  #
   module Spendable
 
     class InsufficientFunds < RuntimeError
     end
 
+    # Return the network name (must be one of the keys from Bitcoin.network)
     def network
       raise "implement #network in your class"
     end
@@ -12,42 +24,24 @@ module CoinOp::Bit
       raise "implement #balance in your class"
     end
 
-    def unspent
-      raise "implement #unspent in your class"
-    end
-
-    def select_unspent
+    # Takes a value in satoshis.
+    # Returns an array of spendable Outputs
+    def select_unspent(value)
       raise "implement #select_unspent in your class"
     end
 
-    def authorize
+    # Authorize the supplied transaction by setting its inputs' script_sigs
+    # to whatever values are appropriate.
+    def authorize(transaction)
       raise "implement #authorize in your class"
     end
 
-    def blockchain
-      # FIXME: use the return value of #network as the arg, once this ticket
-      # is resolved: # https://github.com/BitVault/bitvault/issues/251
-      @blockchain ||= BitVaultAPI::Blockchain::Blockr.new(:test)
-    end
-
-    def lock(outputs)
-      # no op
-      # Mixing classes may wish to lock down these selected outputs
-      # so that concurrent payments or transfers cannot use them.
-      #
-      # When do we release unspents (if a user abandons a transaction)?
-    end
-
-    def unlock(outputs)
-    end
-
-    def create_transaction(outputs, change_address)
+    def create_transaction(outputs, change_address, fee_amount=nil)
 
-      transaction = CoinOp::Bit::Transaction.build do |t|
-        outputs.each do |output|
-          t.add_output(output)
-        end
-      end
+      transaction = CoinOp::Bit::Transaction.from_data(
+        :fee => fee_amount,
+        :outputs => outputs
+      )
 
       if self.balance < transaction.output_value
         raise InsufficientFunds
@@ -56,29 +50,20 @@ module CoinOp::Bit
       unspent = self.select_unspent(transaction.output_value)
 
       unspent.each do |output|
-        transaction.add_input output
+        transaction.add_input :output => output
       end
 
       input_amount = unspent.inject(0) {|sum, output| sum += output.value }
-      fee = transaction.suggested_fee
 
       # FIXME: there's likely another unspent output we can add, but the present
       # implementation of all this can't easily help us.  Possibly stop
       # using select_unspent(value) and start using a while loop that shifts
       # outputs off the array.  Then we can start the process over.
-      if input_amount < (transaction.output_value + transaction.suggested_fee)
+      unless transaction.funded?
         raise InsufficientFunds
       end
 
-      change = input_amount - (transaction.output_value + fee)
-
-      transaction.add_output(
-        :value => change,
-        :script => {
-          :address => change_address
-        },
-        :address => change_address,
-      )
+      transaction.add_change change_address
 
       self.authorize(transaction)
       transaction
@@ -86,3 +71,4 @@ module CoinOp::Bit
 
   end
 end
+

data/lib/coin-op/bit/transaction.rb

@@ -1,15 +1,57 @@
-
 module CoinOp::Bit
 
   class Transaction
     include CoinOp::Encodings
 
+    # Deprecated.  Easier to use Transaction.from_data
     def self.build(&block)
       transaction = self.new
       yield transaction
       transaction
     end
 
+    # Construct a Transaction from a data structure of nested Hashes
+    # and Arrays.
+    def self.data(data)
+      version, lock_time, fee, inputs, outputs, confirmations =
+        data.values_at :version, :lock_time, :fee, :inputs, :outputs, :confirmations
+
+      transaction = self.new(
+        :fee => fee,
+        :version => version, :lock_time => lock_time,
+        :confirmations => confirmations
+      )
+
+      outputs.each do |data|
+        transaction.add_output Output.new(data)
+      end
+
+      #FIXME: we're not handling sig_scripts for already signed inputs.
+
+      if inputs
+        # TODO: use #each instead of #each_with_index
+        inputs.each_with_index do |data, index|
+          transaction.add_input(data)
+
+          ## FIXME: verify that the supplied and computed sig_hashes match
+          #puts :sig_hashes_match => (data[:sig_hash] == input.sig_hash)
+        end
+      end
+
+      transaction
+    end
+
+    # Construct a Transaction from raw bytes.
+    def self.raw(raw_tx)
+      self.native ::Bitcoin::Protocol::Tx.new(raw_tx)
+    end
+
+    # Construct a Transaction from a hex representation of the raw bytes.
+    def self.hex(hex)
+      self.from_bytes CoinOp::Encodings.decode_hex(hex)
+    end
+
+    # Construct a transaction from an instance of ::Bitcoin::Protocol::Tx
     def self.native(tx)
       transaction = self.new()
       # TODO: reconsider use of instance_eval
@@ -33,49 +75,39 @@ module CoinOp::Bit
 
       report = transaction.validate_syntax
       unless report[:valid] == true
-        raise "Invalid syntax:  #{report[:errors].to_json}"
+        raise "Invalid syntax:  #{report[:error].to_json}"
       end
       transaction
     end
 
-    def self.raw(raw_tx)
-      self.native ::Bitcoin::Protocol::Tx.new(raw_tx)
-    end
-
-    def self.hex(hex)
-      self.raw CoinOp::Encodings.decode_hex(hex)
+    # Preparation for interface change, where the from_foo methods become
+    # preferred, and the terser method names are deprecated.
+    #
+    # This nasty little construct allows us to work on the class's metaclass.
+    class << self
+      alias_method :from_data, :data
+      alias_method :from_hex, :hex
+      alias_method :from_bytes, :raw
+      alias_method :from_native, :native
     end
 
-    def self.data(hash)
-      version, lock_time, tx_hash, inputs, outputs = 
-        hash.values_at :version, :lock_time, :tx_hash, :inputs, :outputs
-
-      transaction = self.new
-
-      outputs.each do |data|
-        transaction.add_output Output.new(data)
-      end
-
-      #FIXME: we're not handling sig_scripts for already signed inputs.
-
-      inputs.each_with_index do |data, index|
-        transaction.add_input data[:output]
-
-        ## FIXME: verify that the supplied and computed sig_hashes match
-        #puts :sig_hashes_match => (data[:sig_hash] == input.sig_hash)
-      end
-
-      transaction
-    end
 
-    attr_reader :native, :inputs, :outputs
+    attr_reader :native, :inputs, :outputs, :confirmations
 
-    def initialize
-      @native = native || Bitcoin::Protocol::Tx.new
+    # A new Transaction contains no inputs or outputs; these can be added with
+    # #add_input and #add_output.
+    # FIXME:  version and locktime options are ignored here.
+    def initialize(options={})
+      @native = Bitcoin::Protocol::Tx.new
       @inputs = []
       @outputs = []
+      @fee_override = options[:fee]
+      @confirmations = options[:confirmations]
     end
 
+    # Update the "native" bitcoin-ruby instances for the transaction and
+    # all its inputs.  Will be removed when we rework the wrapper classes
+    # to be lazy, rather than eager.
     def update_native
       yield @native if block_given?
       @native = Bitcoin::Protocol::Tx.new(@native.to_payload)
@@ -91,6 +123,11 @@ module CoinOp::Bit
       end
     end
 
+    # Monkeypatch to remove a test that fails because bitcoin-ruby thinks a
+    # transaction doesn't have valid syntax when it contains a coinbase input.
+    Bitcoin::Validation::Tx::RULES[:syntax].delete(:inputs)
+
+    # Validate that the transaction is plausibly signable.
     def validate_syntax
       update_native
       validator = Bitcoin::Validation::Tx.new(@native, nil)
@@ -98,6 +135,7 @@ module CoinOp::Bit
       {:valid => valid, :error => validator.error}
     end
 
+    # Verify that the script_sigs for all inputs are valid.
     def validate_script_sigs
       bad_inputs = []
       valid = true
@@ -119,16 +157,14 @@ module CoinOp::Bit
     # * an instance of Output
     # * a Hash describing an Output
     #
-    def add_input(arg)
+    def add_input(input)
       # TODO: allow specifying prev_tx and index with a Hash.
       # Possibly stop using SparseInput.
-      if arg.is_a? Input
-        input = arg
-      else
-        input = Input.new(
+
+      unless input.is_a?(Input)
+        input = Input.new input.merge(
           :transaction => self,
           :index => @inputs.size,
-          :output => arg
         )
       end
 
@@ -139,12 +175,15 @@ module CoinOp::Bit
       input
     end
 
+    # Takes either an Output or a Hash describing an output.
     def add_output(output)
       unless output.is_a? Output
         output = Output.new(output)
       end
 
       index = @outputs.size
+      # TODO: stop using set_transaction and just pass self to Output.new
+      # Then remove output.set_transaction
       output.set_transaction self, index
       @outputs << output
       self.update_native do |native|
@@ -152,11 +191,13 @@ module CoinOp::Bit
       end
     end
 
+    # Returns the transaction hash as a string of bytes.
     def binary_hash
       update_native
       @native.binary_hash
     end
 
+    # Returns the transaction hash encoded as hex
     def hex_hash
       update_native
       @native.hash
@@ -170,27 +211,36 @@ module CoinOp::Bit
       @native.lock_time
     end
 
+    # Returns the transaction payload encoded as hex.  This value can
+    # be used by other bitcoin tools for publishing to the network.
     def to_hex
       payload = self.native.to_payload
       CoinOp::Encodings.hex(payload)
     end
 
-    def to_json(*a)
-      self.to_hash.to_json(*a)
-    end
-
+    # Returns a custom data structure representing the full transaction.
+    # Typically used only by #to_json.
     def to_hash
       {
         :version => self.version,
         :lock_time => self.lock_time,
         :hash => self.hex_hash,
+        :fee => self.fee,
         :inputs => self.inputs,
         :outputs => self.outputs,
       }
     end
 
+    def to_json(*a)
+      self.to_hash.to_json(*a)
+    end
+
+    # Compute the digest for a given input.  In most cases, you need to provide
+    # the script.  Which script to supply can be confusing, especially in the
+    # case of P2SH outputs.
+    # TODO: explain the above more clearly.
     def sig_hash(input, script=nil)
-      # NOTE: we only allow SIGHASH_ALL at this time
+      # We only allow SIGHASH_ALL at this time
       # https://en.bitcoin.it/wiki/OP_CHECKSIG#Hashtype_SIGHASH_ALL_.28default.29
 
       prev_out = input.output
@@ -199,6 +249,28 @@ module CoinOp::Bit
       @native.signature_hash_for_input(input.index, nil, script.to_blob)
     end
 
+    # A convenience method for authorizing inputs in a generic manner.
+    # Rather than iterating over the inputs manually, the user can
+    # provide this method with an array of values and a block that
+    # knows what to do with the values.
+    #
+    # For example, if you happen to have the script sigs precomputed
+    # for some strange reason, you could do this:
+    #
+    #   tx.set_script_sigs sig_array do |input, sig|
+    #     sig
+    #   end
+    #
+    # More realistically, if you have an array of the keypairs corresponding
+    # to the inputs:
+    #
+    #   tx.set_script_sigs keys do |input, key|
+    #     sig_hash = tx.sig_hash(input)
+    #     key.sign(sig_hash)
+    #   end
+    #
+    # Each element of the array may be an array, which allows for easy handling
+    # of multisig situations.
     def set_script_sigs(*input_args, &block)
       # No sense trying to authorize when the transaction isn't usable.
       report = validate_syntax
@@ -207,19 +279,32 @@ module CoinOp::Bit
       end
 
       # Array#zip here allows us to iterate over the inputs in lockstep with any
-      # number of sets of signatures.
+      # number of sets of values.
       self.inputs.zip(*input_args) do |input, *input_arg|
         input.script_sig = yield input, *input_arg
       end
     end
 
+    def fee_override
+      @fee_override || self.estimate_fee
+    end
 
-    def suggested_fee
-      @native.minimum_block_fee
+    # Estimate the fee in satoshis for this transaction.  Takes an optional
+    # tx_size argument because it is impossible to determine programmatically
+    # the size of the scripts used to create P2SH outputs.
+    # Rough testing of the size of a 2of3 multisig p2sh input: 297
+    def estimate_fee(tx_size=nil)
+      unspents = inputs.map(&:output)
+      Fee.estimate(unspents, outputs, tx_size)
     end
 
+    # Returns the transaction fee computed from the actual input and output
+    # values, as opposed to the requested override fee or the estimated fee.
+    def fee
+      input_value - output_value rescue nil
+    end
 
-    # Total value being spent
+    # Total value of all outputs.
     def output_value
       total = 0
       @outputs.each do |output|
@@ -229,6 +314,51 @@ module CoinOp::Bit
       total
     end
 
+    # Are the currently selected inputs sufficient to cover the current
+    # outputs and the desired fee?
+    def funded?
+      input_value >= (output_value + fee_override)
+    end
+
+    # Total value of all inputs.
+    def input_value
+      inputs.inject(0) { |sum, input| sum += input.output.value }
+    end
+
+    # Takes a set of Bitcoin addresses and returns the net change in value
+    # expressed in this transaction.
+    def value_for(addresses)
+      output_value_for(addresses) - input_value_for(addresses)
+    end
+
+    # Takes a set of Bitcoin addresses and returns the value expressed in
+    # the inputs for this transaction.
+    def input_value_for(addresses)
+      own = inputs.select { |input| addresses.include?(input.output.address) }
+      own.inject(0) { |sum, input| input.output.value }
+    end
+
+    # Takes a set of Bitcoin addresses and returns the value expressed in
+    # the outputs for this transaction.
+    def output_value_for(addresses)
+      own = outputs.select { |output| addresses.include?(output.address) }
+      own.inject(0) { |sum, output| output.value }
+    end
+
+    # Returns the value that should be assigned to a change output.
+    def change_value
+      input_value - (output_value + fee_override)
+    end
+
+    # Add an output to receive change for this transaction.
+    # Takes a bitcoin address and optional metadata Hash.
+    def add_change(address, metadata={})
+      add_output(
+        :value => change_value,
+        :address => address,
+        :metadata => {:memo => "change"}.merge(metadata)
+      )
+    end
 
   end
 

data/lib/coin-op/blockchain/mockchain.rb

@@ -1,3 +1,5 @@
+# DEPRECATED
+#
 require "bitcoin"
 
 Bitcoin::NETWORKS[:mockchain] = {

data/lib/coin-op/crypto.rb

@@ -1,19 +1,39 @@
+# Ruby bindings for libsodium, a port of DJB's NaCl crypto library
 require "rbnacl"
 require "openssl"
 
 module CoinOp
   module Crypto
 
+    # A wrapper for NaCl's Secret Box, taking a user-supplied passphrase
+    # and deriving a secret key, rather than using a (far more secure)
+    # randomly generated secret key.
+    #
+    # NaCl Secret Box provides a high level interface for authenticated
+    # symmetric encryption.  When creating the box, you must supply a key.
+    # When using the box to encrypt, you must supply a random nonce.  Nonces
+    # must never be re-used.
+    #
+    # Secret Box decryption requires the ciphertext and the nonce used to
+    # create it.
+    #
+    # The PassphraseBox class takes a passphrase, rather than a randomly
+    # generated key. It uses PBKDF2 to generate a key that, while not random,
+    # is somewhat resistant to brute force attacks.  Great care should still
+    # be taken to avoid passphrases that are subject to dictionary attacks.
     class PassphraseBox
-      include CoinOp::Encodings
+
+      # Both class and instance methods need encoding help, so we supply
+      # them to both scopes using extend and include, respectively.
       extend CoinOp::Encodings
+      include CoinOp::Encodings
 
       # PBKDF2 work factor
       ITERATIONS = 100_000
 
       # Given passphrase and plaintext as strings, returns a Hash
       # containing the ciphertext and other values needed for later
-      # decryption.
+      # decryption.  Binary values are encoded as hexadecimal strings.
       def self.encrypt(passphrase, plaintext)
         box = self.new(passphrase)
         box.encrypt(plaintext)
@@ -53,8 +73,8 @@ module CoinOp
         nonce = RbNaCl::Random.random_bytes(RbNaCl::SecretBox.nonce_bytes)
         ciphertext = @box.encrypt(nonce, plaintext)
         {
-          :salt => hex(@salt),
           :iterations => @iterations,
+          :salt => hex(@salt),
           :nonce => hex(nonce),
           :ciphertext => hex(ciphertext)
         }

data/lib/coin-op/encodings.rb

@@ -2,6 +2,8 @@
 module CoinOp
 
   module Encodings
+    # Extending a module with itself allows it to be used as both a mixin
+    # and a bag of functions, e.g. CoinOp::Encodings.hex(string)
     extend self
 
     def hex(blob)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: coin-op
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Matthew King
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-10 00:00:00.000000000 Z
+date: 2015-01-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bitcoin-ruby
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.5
+        version: 0.0.6
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.5
+        version: 0.0.6
 - !ruby/object:Gem::Dependency
   name: money-tree
   requirement: !ruby/object:Gem::Requirement
@@ -107,6 +107,7 @@ files:
 - README.md
 - lib/coin-op.rb
 - lib/coin-op/bit.rb
+- lib/coin-op/bit/fee.rb
 - lib/coin-op/bit/input.rb
 - lib/coin-op/bit/multi_wallet.rb
 - lib/coin-op/bit/output.rb
@@ -137,7 +138,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.0
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: Crypto currency classes in Ruby