bitcoinrb 1.14.0 → 1.16.0

data/lib/bitcoin/taproot/custom_depth_builder.rb

@@ -31,6 +31,18 @@ module Bitcoin
         raise NotImplementedError
       end
 
+      # Generating a control block from a nested tree is not supported yet.
+      # @raise [NotImplementedError]
+      def control_block(leaf)
+        raise NotImplementedError, 'CustomDepthBuilder does not support control_block yet.'
+      end
+
+      # Generating an inclusion proof from a nested tree is not supported yet.
+      # @raise [NotImplementedError]
+      def inclusion_proof(leaf)
+        raise NotImplementedError, 'CustomDepthBuilder does not support inclusion_proof yet.'
+      end
+
       private
 
       def merkle_root

data/lib/bitcoin/tx.rb

@@ -9,7 +9,15 @@ module Bitcoin
     include Bitcoin::HexConverter
     include SilentPayment
 
-    MAX_STANDARD_VERSION = 2
+    # Version 3 is TRUC (BIP-431).
+    MAX_STANDARD_VERSION = 3
+
+    # A tx smaller than this without the witness is not relayed, as it could be confused with a 64-byte merkle tree node.
+    MIN_STANDARD_TX_NONWITNESS_SIZE = 65
+
+    # The number of dust outputs a standard tx may have. Bitcoin Core relays a tx with one dust output only when
+    # the tx pays no fee and is spent by a child in the same package (ephemeral dust), which this class cannot see.
+    MAX_DUST_OUTPUTS_PER_TX = 1
 
     # The maximum weight for transactions we're willing to relay/mine
     MAX_STANDARD_TX_WEIGHT = 400000
@@ -50,18 +58,20 @@ module Bitcoin
     def self.parse_from_payload(payload, non_witness: false, strict: false)
       buf = payload.is_a?(String) ? StringIO.new(payload) : payload
       tx = new
-      tx.version = buf.read(4).unpack1('V')
+      tx.version = Bitcoin.read_exact(buf, 4).unpack1('V')
 
       in_count = Bitcoin.unpack_var_int_from_io(buf)
       has_witness = false
       if in_count.zero? && !non_witness
         tx.marker = 0
-        tx.flag = buf.read(1).unpack1('c')
+        tx.flag = Bitcoin.read_exact(buf, 1).unpack1('C')
         if tx.flag.zero?
           buf.pos -= 1
         else
           in_count = Bitcoin.unpack_var_int_from_io(buf)
-          has_witness = true
+          # Bit 0 of the flag announces the witnesses. Bitcoin Core rejects any other bit after reading
+          # the inputs and outputs, see below.
+          has_witness = tx.flag & 1 == 1
         end
       end
 
@@ -78,10 +88,14 @@ module Bitcoin
         in_count.times do |i|
           tx.inputs[i].script_witness = Bitcoin::ScriptWitness.parse_from_payload(buf)
         end
+        # A tx whose witnesses are all empty is serialized without them, so this encoding has no
+        # txid-preserving reading and Bitcoin Core rejects it.
+        raise ArgumentError, 'Superfluous witness record.' unless tx.witness?
       end
+      raise ArgumentError, 'Unknown transaction optional data.' if tx.flag && (tx.flag & ~1) != 0
 
       raise ArgumentError, 'Transaction has unexpected data.' if strict &&  (buf.pos + 4) != buf.length
-      tx.lock_time = buf.read(4).unpack1('V')
+      tx.lock_time = Bitcoin.read_exact(buf, 4).unpack1('V')
       tx
     end
 
@@ -111,9 +125,10 @@ module Bitcoin
 
     # get the witness commitment of coinbase tx.
     # if this tx does not coinbase or not have commitment, return nil.
+    # When more than one output looks like a commitment, the last one counts, as in Bitcoin Core.
     def witness_commitment
       return nil unless coinbase_tx?
-      outputs.each do |output|
+      outputs.reverse_each do |output|
         commitment = output.script_pubkey.witness_commitment
         return commitment if commitment
       end
@@ -159,10 +174,12 @@ module Bitcoin
       inputs.map { |i| i.script_witness.to_payload }.join
     end
 
-    # check this tx is standard.
+    # Whether this tx is standard, as IsStandardTx in Bitcoin Core judges it, and at least
+    # MIN_STANDARD_TX_NONWITNESS_SIZE bytes without the witness, as the mempool of Bitcoin Core requires.
     def standard?
-      return false if version > MAX_STANDARD_VERSION
+      return false if version < 1 || version > MAX_STANDARD_VERSION
       return false if weight > MAX_STANDARD_TX_WEIGHT
+      return false if serialize_old_format.bytesize < MIN_STANDARD_TX_NONWITNESS_SIZE
       inputs.each do |i|
         # Biggest 'standard' txin is a 15-of-15 P2SH multisig with compressed keys (remember the 520 byte limit on redeemScript size).
         # That works out to a (15*(33+1))+3=513 byte redeemScript, 513+1+15*(73+1)+3=1627
@@ -171,15 +188,19 @@ module Bitcoin
         return false if i.script_sig.size > 1650
         return false unless i.script_sig.push_only?
       end
-      data_count = 0
+      # The OP_RETURN outputs share MAX_OP_RETURN_RELAY bytes, however many of them there are.
+      data_bytes_left = MAX_OP_RETURN_RELAY
+      dust_count = 0
       outputs.each do |o|
         return false unless o.script_pubkey.standard?
-        data_count += 1 if o.script_pubkey.op_return?
-        # TODO add non P2SH multisig relay(permitbaremultisig)
-        return false if o.dust?
+        if o.script_pubkey.op_return?
+          return false if o.script_pubkey.size > data_bytes_left
+          data_bytes_left -= o.script_pubkey.size
+        elsif o.dust?
+          dust_count += 1
+        end
       end
-      return false if data_count > 1
-      true
+      dust_count <= MAX_DUST_OUTPUTS_PER_TX
     end
 
     # The serialized transaction size

data/lib/bitcoin/tx_in.rb

@@ -39,9 +39,9 @@ module Bitcoin
       if sig_length == 0
         i.script_sig = Bitcoin::Script.new
       else
-        i.script_sig = Script.parse_from_payload(buf.read(sig_length))
+        i.script_sig = Script.parse_from_payload(Bitcoin.read_exact(buf, sig_length))
       end
-      i.sequence = buf.read(4).unpack1('V')
+      i.sequence = Bitcoin.read_exact(buf, 4).unpack1('V')
       i
     end
 

data/lib/bitcoin/tx_out.rb

@@ -16,9 +16,9 @@ module Bitcoin
 
     def self.parse_from_payload(payload)
       buf = payload.is_a?(String) ? StringIO.new(payload) : payload
-      value = buf.read(8).unpack1('Q<')
+      value = Bitcoin.read_exact(buf, 8).unpack1('Q<')
       script_size = Bitcoin.unpack_var_int_from_io(buf)
-      new(value: value, script_pubkey: Script.parse_from_payload(buf.read(script_size)))
+      new(value: value, script_pubkey: Script.parse_from_payload(Bitcoin.read_exact(buf, script_size)))
     end
 
     def to_payload

data/lib/bitcoin/util.rb

@@ -8,56 +8,75 @@ module Bitcoin
   #     Bitcoin.pack_var_int(5)
   module Util
 
+    # Serialize +payload+ as a CompactSize length followed by its bytes.
+    # @param [String] payload The bytes, whatever encoding the string carries.
     def pack_var_string(payload)
-      pack_var_int(payload.bytesize) + payload
+      pack_var_int(payload.bytesize) + payload.b
     end
 
     def unpack_var_string(payload)
       size, payload = unpack_var_int(payload)
-      size && size > 0 ? payload.unpack("a#{size}a*") : ['', payload.to_s]
+      raise ArgumentError, 'Variable length string is truncated.' if payload.bytesize < size
+      [payload.byteslice(0, size), payload.byteslice(size..-1)]
     end
 
+    # Read exactly +size+ bytes from +buf+.
+    # @param [StringIO] buf
+    # @param [Integer] size
+    # @return [String] the bytes read.
+    # @raise [ArgumentError] If +buf+ ends before +size+ bytes.
+    def read_exact(buf, size)
+      data = size.zero? ? ''.b : buf.read(size)
+      raise ArgumentError, 'Payload is truncated.' if data.nil? || data.bytesize != size
+      data
+    end
+
+    # Encode +i+ as a CompactSize.
+    # @param [Integer] i
+    # @return [String] the CompactSize with binary format.
+    # @raise [ArgumentError] If +i+ is not an integer from 0 to 2**64 - 1, which have no CompactSize.
     def pack_var_int(i)
+      raise ArgumentError, 'CompactSize must be an integer from 0 to 2**64 - 1.' unless i.is_a?(Integer) && i.between?(0, 0xffffffffffffffff)
       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 "int(#{i}) too large!"
+        [0xff, i].pack('CQ<')
       end
     end
 
     # @return an integer for a valid payload, otherwise nil
+    # Decode a CompactSize at the head of +payload+.
+    # @return [Array(Integer, String)] the value and the rest of the payload.
+    # @raise [ArgumentError] If the encoding is truncated or not canonical.
     def unpack_var_int(payload)
-      case payload.unpack1('C')
-      when 0xfd
-        payload.unpack('xva*')
-      when 0xfe
-        payload.unpack('xVa*')
-      when 0xff
-        payload.unpack('xQ<a*')
-      else
-        payload.unpack('Ca*')
-      end
+      buf = StringIO.new(payload)
+      value = unpack_var_int_from_io(buf)
+      [value, buf.read.to_s]
     end
 
     # @return an integer for a valid payload, otherwise nil
+    # Decode a CompactSize from +buf+. As ReadCompactSize in Bitcoin Core, a value encoded with more
+    # bytes than it needs is rejected, so every value has exactly one encoding.
+    # @param [StringIO] buf
+    # @return [Integer]
+    # @raise [ArgumentError] If the encoding is truncated or not canonical.
     def unpack_var_int_from_io(buf)
-      uchar = buf.read(1)&.unpack1('C')
-      case uchar
-      when 0xfd
-        buf.read(2)&.unpack1('v')
-      when 0xfe
-        buf.read(4)&.unpack1('V')
-      when 0xff
-        buf.read(8)&.unpack1('Q<')
-      else
-        uchar
-      end
+      first = buf.read(1)
+      raise ArgumentError, 'CompactSize is truncated.' if first.nil?
+      uchar = first.unpack1('C')
+      size, format, minimum = case uchar
+                              when 0xfd then [2, 'v', 0xfd]
+                              when 0xfe then [4, 'V', 0x10000]
+                              when 0xff then [8, 'Q<', 0x100000000]
+                              else return uchar
+                              end
+      value = read_exact(buf, size).unpack1(format)
+      raise ArgumentError, 'CompactSize is not canonical.' if value < minimum
+      value
     end
 
     def pack_boolean(b)
@@ -66,6 +85,7 @@ module Bitcoin
 
     def unpack_boolean(payload)
       data, payload = payload.unpack('Ca*')
+      raise ArgumentError, 'Payload is truncated.' if data.nil?
       [(data.zero? ? false : true), payload]
     end
 
@@ -117,13 +137,14 @@ module Bitcoin
     # decode Base58 check encoding address.
     # @param [String] addr address.
     # @return [Array] hex and address version
+    # @raise [ArgumentError] If +addr+ is not a P2PKH or P2SH address of the current chain.
     def decode_base58_address(addr)
       hex = Base58.decode(addr)
       if hex.size == 50 && calc_checksum(hex[0...-8]) == hex[-8..-1]
-        raise 'Invalid version bytes.' unless [Bitcoin.chain_params.address_version, Bitcoin.chain_params.p2sh_version].include?(hex[0..1])
+        raise ArgumentError, 'Invalid version bytes.' unless [Bitcoin.chain_params.address_version, Bitcoin.chain_params.p2sh_version].include?(hex[0..1])
         [hex[2...-8], hex[0..1]]
       else
-        raise 'Invalid address.'
+        raise ArgumentError, 'Invalid address.'
       end
     end
 

data/lib/bitcoin/validation.rb

@@ -38,8 +38,11 @@ module Bitcoin
           return state.DoS(100, reject_code: Message::Reject::CODE_INVALID, reject_reason: 'bad-cb-length')
         end
       else
+        # Only the null prevout (zero hash and index 0xffffffff) is rejected, as COutPoint::IsNull in
+        # Bitcoin Core. An index of -1 is the default of OutPoint and serializes as 0xffffffff.
+        null_payload = OutPoint.create_coinbase_outpoint.to_payload
         tx.inputs.each do |i|
-          if i.out_point.nil? || !i.out_point.valid?
+          if i.out_point.nil? || i.out_point.to_payload == null_payload
             return state.DoS(10, reject_code: Message::Reject::CODE_INVALID, reject_reason: 'bad-txns-prevout-null')
           end
         end
@@ -47,33 +50,82 @@ module Bitcoin
       true
     end
 
-    # check proof of work
+    # Check the proof of work of a block header, as CheckBlockHeader in Bitcoin Core.
+    # @param [Bitcoin::BlockHeader] header
+    # @param [Bitcoin::ValidationState] state
+    # @return [Boolean]
     def check_block_header(header, state)
-      header.block_hash
-      header.bits
-
+      unless header.valid_pow?
+        return state.DoS(50, reject_code: Message::Reject::CODE_INVALID, reject_reason: 'high-hash', debug_message: 'proof of work failed')
+      end
+      true
     end
 
+    # Check a block without any context, as CheckBlock in Bitcoin Core: the header, the merkle root,
+    # the size limits, the coinbase, every tx and the legacy sigop count.
+    # @param [Bitcoin::Block] block
+    # @param [Bitcoin::ValidationState] state
+    # @return [Boolean]
     def check_block(block, state)
-      # check block header
       return false unless check_block_header(block.header, state)
 
-      # check merkle root
+      txs = block.transactions
+      # A block without any tx has no merkle root to check, and fails the size limits below.
+      unless txs.empty?
+        if block.calculate_merkle_root != block.header.merkle_root
+          return state.DoS(100, reject_code: Message::Reject::CODE_INVALID, reject_reason: 'bad-txnmrklroot', corruption_in: true, debug_message: 'hashMerkleRoot mismatch')
+        end
+        # CVE-2012-2459
+        if block.merkle_root_mutated?
+          return state.DoS(100, reject_code: Message::Reject::CODE_INVALID, reject_reason: 'bad-txns-duplicate', corruption_in: true, debug_message: 'duplicate transaction')
+        end
+      end
+
+      # Size limits, without the witness, which has not been checked for malleability.
+      if txs.empty? || txs.size * WITNESS_SCALE_FACTOR > MAX_BLOCK_WEIGHT || block.stripped_size * WITNESS_SCALE_FACTOR > MAX_BLOCK_WEIGHT
+        return state.DoS(100, reject_code: Message::Reject::CODE_INVALID, reject_reason: 'bad-blk-length', debug_message: 'size limits failed')
+      end
+
+      unless txs.first.coinbase_tx?
+        return state.DoS(100, reject_code: Message::Reject::CODE_INVALID, reject_reason: 'bad-cb-missing', debug_message: 'first tx is not coinbase')
+      end
+      if txs[1..].any?(&:coinbase_tx?)
+        return state.DoS(100, reject_code: Message::Reject::CODE_INVALID, reject_reason: 'bad-cb-multiple', debug_message: 'more than one coinbase')
+      end
 
-      # size limits
+      txs.each { |tx| return false unless check_tx(tx, state) }
 
-      # first tx is coinbase?
+      sigops = txs.sum { |tx| legacy_sigop_count(tx) }
+      if sigops * WITNESS_SCALE_FACTOR > MAX_BLOCK_SIGOPS_COST
+        return state.DoS(100, reject_code: Message::Reject::CODE_INVALID, reject_reason: 'bad-blk-sigops', debug_message: 'out-of-bounds SigOpCount')
+      end
+      true
+    end
 
-      # check tx count
+    private
 
-      # check sigop count
+    # Count the sigops of the scriptSigs and scriptPubkeys of +tx+, as GetLegacySigOpCount in Bitcoin Core:
+    # a CHECKMULTISIG counts as 20 whatever its key count.
+    def legacy_sigop_count(tx)
+      tx.inputs.sum { |i| script_sigop_count(i.script_sig) } + tx.outputs.sum { |o| script_sigop_count(o.script_pubkey) }
+    end
+
+    def script_sigop_count(script)
+      script.chunks.sum do |chunk|
+        next 0 if chunk.empty?
+        case chunk.opcode
+        when Opcodes::OP_CHECKSIG, Opcodes::OP_CHECKSIGVERIFY then 1
+        when Opcodes::OP_CHECKMULTISIG, Opcodes::OP_CHECKMULTISIGVERIFY then MAX_PUBKEYS_PER_MULTISIG
+        else 0
+        end
+      end
     end
 
   end
 
   class ValidationState
 
-    MODE = {valid: 0, invlid: 1, error: 2}
+    MODE = {valid: 0, invalid: 1, error: 2}
 
     attr_accessor :mode
     attr_accessor :n_dos

data/lib/bitcoin/version.rb

@@ -1,3 +1,3 @@
 module Bitcoin
-  VERSION = "1.14.0"
+  VERSION = "1.16.0"
 end

data/lib/bitcoin/wallet/account.rb

@@ -20,21 +20,30 @@ module Bitcoin
         validate_params!(account_key, purpose, index)
         @purpose = purpose
         @index = index
-        @name = name
+        @name = normalize_name(name)
         @receive_depth = 0
         @change_depth = 0
         @lookahead = 10
         @account_key = account_key
       end
 
+      # Parse an account from the payload made by #to_payload.
+      # @param [String] payload
+      # @return [Bitcoin::Wallet::Account]
+      # @raise [ArgumentError] If the payload is truncated, has data after the account, or holds invalid values.
       def self.parse_from_payload(payload)
+        raise ArgumentError, 'payload must be a String.' unless payload.is_a?(String)
         buf = StringIO.new(payload)
-        account_key = Bitcoin::ExtPubkey.parse_from_payload(buf.read(78))
-        payload = buf.read
-        name, payload = Bitcoin.unpack_var_string(payload)
-        name = name.force_encoding('utf-8')
-        purpose, index, receive_depth, change_depth, lookahead = payload.unpack('V*')
-        a = Account.new(account_key, purpose, index, name)
+        account_key = Bitcoin::ExtPubkey.parse_from_payload(Bitcoin.read_exact(buf, 78))
+        name_size = Bitcoin.unpack_var_int_from_io(buf)
+        raise ArgumentError, 'Payload is truncated.' if name_size.nil?
+        name = Bitcoin.read_exact(buf, name_size).force_encoding('utf-8')
+        purpose, index, receive_depth, change_depth, lookahead = Bitcoin.read_exact(buf, 20).unpack('V5')
+        raise ArgumentError, 'Account payload has data after the account.' unless buf.eof?
+        a = Account.new(account_key, purpose, index)
+        # A wallet made by an older version may hold a name which is not valid UTF-8. It is kept as stored,
+        # so that the wallet stays usable and #to_payload writes the same bytes back.
+        a.instance_variable_set(:@name, name)
         a.receive_depth = receive_depth
         a.change_depth = change_depth
         a.lookahead = lookahead
@@ -43,7 +52,7 @@ module Bitcoin
 
       def to_payload
         payload = account_key.to_payload
-        payload << Bitcoin.pack_var_string(name.unpack1('H*').htb)
+        payload << Bitcoin.pack_var_string(name.b)
         payload << [purpose, index, receive_depth, change_depth, lookahead].pack('V*')
         payload
       end
@@ -139,11 +148,26 @@ module Bitcoin
         account_key.derive(branch).derive(address_index)
       end
 
+      # The name is stored as its UTF-8 bytes and read back as UTF-8, so that it has to be valid UTF-8.
+      # @raise [ArgumentError] If +name+ is not a String which converts to valid UTF-8.
+      def normalize_name(name)
+        raise ArgumentError, 'name must be a String.' unless name.is_a?(String)
+        utf8 = name.encode(Encoding::UTF_8)
+        raise ArgumentError, 'name must be valid UTF-8.' unless utf8.valid_encoding?
+        utf8
+      rescue EncodingError
+        raise ArgumentError, 'name must be valid UTF-8.'
+      end
+
+      # @raise [ArgumentError] If a parameter is invalid or they do not match each other.
       def validate_params!(account_key, purpose, index)
-        raise 'account_key must be an instance of Bitcoin::ExtPubkey.' unless account_key.is_a?(Bitcoin::ExtPubkey)
-        raise 'Account key and index does not match.' unless account_key.number == (index + Bitcoin::HARDENED_THRESHOLD)
+        raise ArgumentError, 'account_key must be an instance of Bitcoin::ExtPubkey.' unless account_key.is_a?(Bitcoin::ExtPubkey)
+        # Any BIP-44 style purpose is accepted, as an older version did. Its account key has to match it below.
+        raise ArgumentError, 'purpose must be an integer from 0 to 2**31 - 1.' unless purpose.is_a?(Integer) && purpose.between?(0, Bitcoin::HARDENED_THRESHOLD - 1)
+        raise ArgumentError, 'index must be an integer from 0 to 2**31 - 1.' unless index.is_a?(Integer) && index.between?(0, Bitcoin::HARDENED_THRESHOLD - 1)
+        raise ArgumentError, 'Account key and index does not match.' unless account_key.number == (index + Bitcoin::HARDENED_THRESHOLD)
         version_bytes = Bitcoin::ExtPubkey.version_from_purpose(purpose + Bitcoin::HARDENED_THRESHOLD)
-        raise 'The purpose and the account key do not match.' unless account_key.version == version_bytes
+        raise ArgumentError, 'The purpose and the account key do not match.' unless account_key.version == version_bytes
       end
 
     end

data/lib/bitcoin/wallet/base.rb

@@ -10,6 +10,10 @@ module Bitcoin
 
       VERSION = 1
 
+      # A wallet id names the directory +wallet<id>+ under the path prefix, so that it may hold only
+      # letters, digits, '_' and '-'. A '/' or '..' would put the wallet outside the prefix.
+      WALLET_ID_PATTERN = /\A[A-Za-z0-9_-]+\z/
+
       # get wallet dir path
       def self.default_path_prefix
         "#{Bitcoin.base_dir}/db/wallet/"
@@ -17,9 +21,10 @@ module Bitcoin
 
       # Create new wallet. If wallet already exist, throw error.
       # The wallet generates a seed using SecureRandom and store to db at initialization.
-      # @param [String] wallet_id new wallet id.
+      # @param [Integer, String] wallet_id new wallet id, which consists of letters, digits, '_' and '-'.
       # @param [String] path_prefix wallet file path prefix.
       # @return [Bitcoin::Wallet::Base] the wallet
+      # @raise [ArgumentError] If +wallet_id+ is invalid or the wallet already exists.
       def self.create(wallet_id = 1, path_prefix = default_path_prefix, purpose = Account::PURPOSE_TYPE[:native_segwit])
         raise ArgumentError, "wallet_id : #{wallet_id} already exist." if self.exist?(wallet_id, path_prefix)
         w = self.new(wallet_id, path_prefix)
@@ -33,6 +38,7 @@ module Bitcoin
 
       # load wallet with specified +wallet_id+
       # @return [Bitcoin::Wallet::Base] the wallet
+      # @raise [ArgumentError] If +wallet_id+ is invalid or the wallet does not exist.
       def self.load(wallet_id, path_prefix = default_path_prefix)
         raise ArgumentError, "wallet_id : #{wallet_id} dose not exist." unless self.exist?(wallet_id, path_prefix)
         self.new(wallet_id, path_prefix)
@@ -45,12 +51,14 @@ module Bitcoin
       end
 
       # get current wallet
+      # @return [Bitcoin::Wallet::Base] the wallet of the first wallet dir, or nil if there is none.
+      # Its wallet_id is an Integer if it consists of digits only, otherwise a String.
       def self.current_wallet(path_prefix = default_path_prefix)
-        path = wallet_paths(path_prefix).first # TODO default wallet selection
-        return nil unless path
-        path.slice!(path_prefix + 'wallet')
-        path.slice!('/')
-        self.load(path.to_i, path_prefix)
+        # TODO default wallet selection
+        ids = wallet_paths(path_prefix).map { |path| File.basename(path).delete_prefix('wallet') }
+        id = ids.find { |i| i.match?(WALLET_ID_PATTERN) } # A dir such as "wallet/" has no wallet id.
+        return nil unless id
+        self.load(id.match?(/\A[0-9]+\z/) ? id.to_i : id, path_prefix)
       end
 
       # get account list based on BIP-44
@@ -67,10 +75,12 @@ module Bitcoin
 
       # create new account
       # @param [Integer] purpose BIP44's purpose.
-      # @param [String] name a account name.
+      # @param [String] name a account name, which has to be unique in the wallet whatever the purpose.
       # @return [Bitcoin::Wallet::Account]
+      # @raise [ArgumentError] If an account with +name+ already exists.
       def create_account(purpose = Account::PURPOSE_TYPE[:native_segwit], name)
-        raise ArgumentError.new('Account already exists.') if find_account(name, purpose)
+        # An account is looked up by its name alone, e.g. in #generate_new_address.
+        raise ArgumentError.new('Account already exists.') if find_account(name)
         index = accounts.size
         path = "m/#{purpose}'/#{Bitcoin.chain_params.bip44_coin_type}'/#{index}'"
         account_key = master_key.derive(path).ext_pubkey
@@ -82,18 +92,23 @@ module Bitcoin
 
       # get wallet balance.
       # @param [Bitcoin::Wallet::Account] account a account in the wallet.
+      # @return [Integer] the balance in satoshis.
       def get_balance(account)
         # TODO get from utxo db.
-        0.00000000
+        0
       end
 
       # create new bitcoin address for receiving payments.
       # @param [String] account_name an account name.
+      # @param [Integer] purpose BIP44's purpose of the account, which is required only when a wallet
+      # created by an older version has accounts of the same name with different purposes.
       # @return [String] generated address.
-      def generate_new_address(account_name)
-        account = find_account(account_name)
-        raise ArgumentError.new('Account does not exist.') unless account
-        account.create_receive.addr
+      # @raise [ArgumentError] If no account, or more than one account, matches.
+      def generate_new_address(account_name, purpose = nil)
+        candidates = accounts(purpose).select{|a| a.name == account_name}
+        raise ArgumentError.new('Account does not exist.') if candidates.empty?
+        raise ArgumentError.new('More than one account has the name, specify the purpose.') if candidates.size > 1
+        candidates.first.create_receive.addr
       end
 
       # get wallet version.
@@ -119,10 +134,12 @@ module Bitcoin
         db.register_master_key(master_key)
       end
 
-      # decrypt wallet
+      # decrypt wallet, and store its seed unencrypted.
       # @param [String] passphrase the wallet passphrase
+      # @raise [ArgumentError] If +passphrase+ is wrong.
       def decrypt(passphrase)
-
+        master_key.decrypt(passphrase)
+        db.register_master_key(master_key)
       end
 
       # wallet information
@@ -140,16 +157,24 @@ module Bitcoin
       private
 
       def initialize(wallet_id, path_prefix)
+        self.class.validate_wallet_id!(wallet_id)
         @path = "#{path_prefix}wallet#{wallet_id}/"
         @db = Bitcoin::Wallet::DB.new(@path)
         @wallet_id = wallet_id
       end
 
       def self.exist?(wallet_id, path_prefix)
+        validate_wallet_id!(wallet_id)
         path = "#{path_prefix}wallet#{wallet_id}"
         Dir.exist?(path)
       end
 
+      def self.validate_wallet_id!(wallet_id)
+        valid = (wallet_id.is_a?(Integer) && wallet_id >= 0) ||
+          (wallet_id.is_a?(String) && wallet_id.match?(WALLET_ID_PATTERN))
+        raise ArgumentError, "wallet_id must be a non-negative integer or a string of letters, digits, '_' and '-'." unless valid
+      end
+
       # find account using +account_name+
       def find_account(account_name, purpose = nil)
         accounts(purpose).find{|a| a.name == account_name}

data/lib/bitcoin/wallet/utxo.rb

@@ -7,7 +7,23 @@ module Bitcoin
       attr_reader :value
       attr_reader :script_pubkey
 
+      # @param [String] tx_hash The transaction hash with hex format.
+      # @param [Integer] index The index of the output, 0 to 2**32 - 1.
+      # @param [Integer] value The value in satoshi, 0 to 2**64 - 1.
+      # @param [Bitcoin::Script] script_pubkey The scriptPubKey of the output.
+      # @param [Integer, nil] block_height The height of the block which holds the tx, 1 to 2**32 - 1, or nil
+      # while the tx is unconfirmed.
+      # @raise [ArgumentError] If a value is out of range, since the serialization would silently change it.
       def initialize(tx_hash, index, value, script_pubkey, block_height = nil)
+        unless tx_hash.is_a?(String) && tx_hash.valid_hex? && tx_hash.length == 64
+          raise ArgumentError, 'tx_hash must be a 32 byte hash with hex format.'
+        end
+        raise ArgumentError, 'index must be an integer from 0 to 2**32 - 1.' unless index.is_a?(Integer) && index.between?(0, 0xffffffff)
+        raise ArgumentError, 'value must be an integer from 0 to 2**64 - 1.' unless value.is_a?(Integer) && value.between?(0, 0xffffffffffffffff)
+        raise ArgumentError, 'script_pubkey must be a Bitcoin::Script.' unless script_pubkey.is_a?(Bitcoin::Script)
+        unless block_height.nil? || (block_height.is_a?(Integer) && block_height.between?(1, 0xffffffff))
+          raise ArgumentError, 'block_height must be nil or an integer from 1 to 2**32 - 1.'
+        end
         @tx_hash = tx_hash
         @index = index
         @block_height = block_height
@@ -15,14 +31,16 @@ module Bitcoin
         @script_pubkey = script_pubkey
       end
 
+      # @param [String] payload The serialization made by #to_payload.
+      # @return [Bitcoin::Wallet::Utxo, nil] nil if +payload+ is nil.
+      # @raise [ArgumentError] If +payload+ is truncated or has bytes after the script.
       def self.parse_from_payload(payload)
         return nil if payload.nil?
-
-        tx_hash, index, block_height, value, payload = payload.unpack('H64VVQ<a*')
-
         buf = StringIO.new(payload)
+        tx_hash, index, block_height, value = Bitcoin.read_exact(buf, 48).unpack('H64VVQ<')
         script_size = Bitcoin.unpack_var_int_from_io(buf)
-        script_pubkey = Bitcoin::Script.parse_from_payload(buf.read(script_size));
+        script_pubkey = Bitcoin::Script.parse_from_payload(Bitcoin.read_exact(buf, script_size))
+        raise ArgumentError, 'Utxo payload has data after the script.' unless buf.eof?
         new(tx_hash, index, value, script_pubkey, block_height == 0 ? nil : block_height )
       end