btcruby 0.0.0 → 1.0.0

data/documentation/wif.md

@@ -0,0 +1,72 @@
+[Index](index.md)
+
+BTC::WIF
+========
+
+A subclass of [BTC::Address](address.md) that represents a serialized private [key](key.md) in a Wallet Import Format (WIF), also known as "sipa format".
+
+Initializers
+------------
+
+#### new(string: *String*)
+
+Returns a new WIF by parsing a [Base58Check](base58.md)-encoded string (must be a valid WIF string).
+
+#### new(private\_key: *String*, network: *BTC::Network*, public\_key\_compressed: *false|true*)
+
+Returns a new WIF with the 32-byte binary string `private_key`.
+
+If `network` is not specified, [BTC::Network.default](network.md#default) is used.
+
+If `public_key_compressed` is not specified, `false` is used.
+
+#### new(key: *BTC::Key*, network: *BTC::Network*, public\_key\_compressed: *false|true*)
+
+Returns a new WIF with [key.private_key](key.md).
+
+Raises `ArgumentError` if `key` does not have a `private_key` component.
+
+If `network` is not specified, `key.network` is used (instance of [BTC::Network](network.md)).
+
+If `public_key_compressed` is not specified, `key.public_key_compressed` is used.
+
+
+Instance Methods
+----------------
+
+#### key
+
+Returns a [BTC::Key](key.md) instance represented by the WIF. The returned object inherits `network` and `public_key_compressed` attributes.
+
+#### private_key
+
+Returns raw binary 32-byte private key stored in WIF.
+
+#### to_s
+
+Returns string representation of the WIF in [Base58Check](base58.md) encoding.
+
+#### public_address
+
+Returns [BTC::PublicKeyAddress](p2pkh.md) instance corresponding to this key's public key.
+
+#### public\_key\_compressed
+
+Returns `true` or `false` depending on whether the corresponding [public key](key.md) should be compressed (33 bytes) or not (65 bytes).
+
+#### network
+
+Returns a [BTC::Network](network.md) instance based on the version prefix of the address (mainnet or testnet).
+
+#### version
+
+Returns an integer value of the one-byte prefix of the WIF encoding. 128 for mainnet, 239 for testnet.
+
+#### p2pkh?
+
+Returns `false`.
+
+#### p2sh?
+
+Returns `false`.
+

data/documentation/wire_format.md

@@ -0,0 +1,70 @@
+[Index](index.md)
+
+BTC::WireFormat
+===============
+
+WireFormat module implements routines dealing with parsing and writing protocol messages.
+All functions are also available as methods of `BTC::WireFormat` object.
+
+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 what Satoshi called [CompactSize](https://en.bitcoin.it/wiki/Protocol_specification#Variable_length_integer). 
+BitcoinQT has later added even more compact format called *CVarInt* to use in its local block storage. *CVarInt* is not implemented here.
+
+Value Encoded   | Storage Size (bytes)   | 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 Functions
+----------------
+
+#### read_varint(data: *String*, offset: *Integer*)
+#### read_varint(stream: *IO*, offset: *Integer*)
+
+Returns `[value, length]` by reading from binary string `data` or `stream`. 
+Value is a decoded integer value. Length is number of bytes read (including offset bytes).
+
+In case of failure, returns `[nil, length]` where `length` is a number of bytes read before the error was encountered.
+
+Default `offset` is 0.
+
+
+#### encode_varint(*integer*)
+
+Returns binary varint representation of `integer`.
+
+
+#### write_varint(integer, data: *String*)
+#### write_varint(integer, stream: *IO*)
+
+Encodes the `integer` and appends it to binary string `data` or writes to `stream`. 
+
+Returns binary varint representation of `integer`.
+
+
+#### read_string(data: *String*, offset: *Integer*)
+#### read_string(stream: *IO*, offset: *Integer*)
+
+Returns `[string, length]` where `length` is 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.
+
+Default `offset` is 0.
+
+
+#### encode_string(*string*)
+
+Returns binary representation of `string` (equals the string itself prepended with its byte length in varint format).
+
+
+#### write_string(string, data: *String*)
+#### write_string(string, stream: *IO*)
+
+Encodes the `string` and appends it to binary string `data` or writes to `stream`. 
+
+Returns binary representation of `string` (that is, with varint length prefix).

data/lib/btcruby/address.rb

@@ -0,0 +1,296 @@
+# Addresses are Base58-encoded pieces of data representing various objects:
+#
+# 1. Public key hash address. Example: 19FGfswVqxNubJbh1NW8A4t51T9x9RDVWQ.
+# 2. Private key for uncompressed public key (WIF).
+#    Example: 5KQntKuhYWSRXNqp2yhdXzjekYAR7US3MT1715Mbv5CyUKV6hVe.
+# 3. Private key for compressed public key (WIF).
+#    Example: L3p8oAcQTtuokSCRHQ7i4MhjWc9zornvpJLfmg62sYpLRJF9woSu.
+# 4. Script hash address (P2SH). Example: 3NukJ6fYZJ5Kk8bPjycAnruZkE5Q7UW7i8.
+#
+# To differentiate between testnet and mainnet, use `network` accessor or `mainnet?`/`testnet?` methods.
+#
+# To check if the instance of the class is available for
+# mainnet or testnet, use mainnet? and testnet? methods respectively.
+#
+# Usage:
+# 1. When receiving an address in Base58 format, convert it to a proper type by doing:
+#
+#      address = BTC::Address.parse("19FGfswVqxNubJbh1NW8A4t51T9x9RDVWQ")
+#
+# 2. To create an address, use appropriate type and call with_data(binary_data):
+#
+#      address = BTC::PublicKeyAddress.new(hash: hash)
+#
+# 3. To convert address to its Base68Check format call to_s:
+#
+#      string = address.to_s
+#
+module BTC
+  class Address
+
+    # Converts base58-encoded string to a BTC::Address instance.
+    # If BTC::Address is already provided, returns it.
+    def self.with_address(string_or_address)
+      raise ArgumentError, "Use Address.parse(...) instead"
+    end
+
+    def self.with_string(base58check_string)
+      raise ArgumentError, "Use #{self}.parse(...) instead"
+    end
+
+    # Decodes address from a Base58Check-encoded string
+    def self.parse(string_or_address)
+      raise ArgumentError, "Argument is missing" if !string_or_address
+      if string_or_address.is_a?(self)
+        return string_or_address
+      elsif string_or_address.is_a?(Address)
+        raise ArgumentError, "Argument must be an instance of #{self}, not #{string_or_address.class}."
+      end
+      string = string_or_address
+      raise ArgumentError, "String is expected" if !string.is_a?(String)
+      raw_data = Base58.data_from_base58check(string)
+      result = parse_raw_data(raw_data, string)
+      if !result.is_a?(self)
+        raise ArgumentError, "Argument must be an instance of #{self}, not #{result.class}."
+      end
+      result
+    end
+
+    # Internal method to parse address from raw binary data.
+    def self.parse_raw_data(raw_data, _string = nil)
+      raise ArgumentError, "Raw data is missing" if !raw_data
+      if raw_data.bytesize < 2 # should contain at least a version byte and some content
+        raise FormatError, "Failed to decode BTC::Address: raw data is too short"
+      end
+      version = raw_data.bytes.first
+      address_class = version_to_class_dictionary[version]
+      if !address_class
+        raise FormatError, "Failed to decode BTC::Address: unknown version #{version}"
+      end
+      return address_class.new(string: _string, _raw_data: raw_data)
+    end
+
+    def network
+      @network ||= if !@version
+        BTC::Network.default
+      elsif @version == self.class.mainnet_version
+        BTC::Network.mainnet
+      else
+        BTC::Network.testnet
+      end
+    end
+
+    def version
+      @version ||= if self.network.mainnet?
+        self.class.mainnet_version
+      else
+        self.class.testnet_version
+      end
+    end
+
+    # Returns binary contents of the address (without version byte and checksum).
+    def data
+      @data
+    end
+
+    # Returns a public version of the address. For public addresses (P2PKH and P2SH) returns self.
+    def public_address
+      self
+    end
+
+    # Two instances are equal when they have the same contents and versions.
+    def ==(other)
+      return false if !other
+      self.data == other.data && self.version == other.version
+    end
+    alias_method :eql?, :==
+
+    # Returns Base58Check representation of an address.
+    def to_s
+      @base58check_string ||= Base58.base58check_from_data(self.data_for_base58check_encoding)
+    end
+
+    # Whether this address is usable on mainnet.
+    def mainnet?
+      self.network.mainnet?
+    end
+
+    # Whether this address is usable on testnet.
+    def testnet?
+      self.network.testnet?
+    end
+
+    # Whether this address is pay-to-public-key-hash (classic address which is a hash of a single public key).
+    def p2pkh?
+      false
+    end
+
+    # Whether this address is pay-to-script-hash.
+    def p2sh?
+      false
+    end
+
+    def inspect
+      %{#<#{self.class}:#{to_s}>}
+    end
+
+    protected
+
+    # Overriden in subclasses to provide concrete version
+    def self.mainnet_version
+      raise Exception, "Override mainnet_version in your subclass"
+    end
+
+    def self.testnet_version
+      raise Exception, "Override testnet_version in your subclass"
+    end
+
+    # To override in subclasses
+    def data_for_base58check_encoding
+      raise Exception, "Override data_for_base58check_encoding in #{self.class} to return complete data to be base58-encoded."
+    end
+
+    private
+
+    def self.version_to_class_dictionary
+      @version_to_class_dictionary ||= [
+        PublicKeyAddress,
+        ScriptHashAddress,
+        WIF,
+        AssetID,
+        AssetAddress
+      ].inject({}) do |dict, cls|
+        dict[cls.mainnet_version] = cls
+        dict[cls.testnet_version] = cls
+        dict
+      end
+    end
+  end
+
+  class BitcoinPaymentAddress < Address
+  end
+
+  # Base class for P2SH and P2PKH addresses
+  class Hash160Address < BitcoinPaymentAddress
+
+    HASH160_LENGTH = 20
+
+    # Instantiates addess with the 20-byte hash
+    def self.with_data(hash, network: nil)
+      raise ArgumentError, "Use #{self}.new(hash: ...) instead"
+    end
+
+    def initialize(string: nil, hash: nil, network: nil, _raw_data: nil)
+      if string || _raw_data
+        _raw_data ||= Base58.data_from_base58check(string)
+        if _raw_data.bytesize != (1 + HASH160_LENGTH)
+          raise FormatError, "Raw data should have length #{1 + HASH160_LENGTH}, but it is #{_raw_data.bytesize} instead"
+        end
+        @base58check_string = string
+        @data = _raw_data[1, HASH160_LENGTH]
+        @version = _raw_data.bytes.first
+        @network = nil
+      elsif hash
+        if hash.bytesize != HASH160_LENGTH
+          raise FormatError, "Data should have length #{HASH160_LENGTH}, but it is #{hash.bytesize} instead"
+        end
+        @base58check_string = nil
+        @data = hash
+        @version = nil
+        @network = network
+      else
+        raise ArgumentError, "Either data or string must be provided"
+      end
+    end
+
+    def hash
+      @data
+    end
+
+    def data_for_base58check_encoding
+      BTC::Data.data_from_bytes([self.version]) + @data
+    end
+  end
+
+
+
+  # Standard pulic key (P2PKH) address (e.g. 19FGfswVqxNubJbh1NW8A4t51T9x9RDVWQ)
+  class PublicKeyAddress < Hash160Address
+
+    def self.mainnet_version
+      0
+    end
+
+    def self.testnet_version
+      111
+    end
+
+    def p2pkh?
+      true
+    end
+
+    # Instantiates address with a BTC::Key or a binary public key.
+    def initialize(string: nil, hash: nil, network: nil, _raw_data: nil, public_key: nil, key: nil)
+      if key
+        super(hash: BTC.hash160(key.public_key), network: key.network || network)
+      elsif public_key
+        super(hash: BTC.hash160(public_key), network: network)
+      else
+        super(string: string, hash: hash, network: network, _raw_data: _raw_data)
+      end
+    end
+
+    # Instantiates an address with a public key binary data
+    def self.with_public_key(public_key, network: nil)
+      raise ArgumentError, "Use #{self}.new(public_key: ...) instead"
+    end
+
+    # Returns BTC::Script with data 'OP_DUP OP_HASH160 <hash> OP_EQUALVERIFY OP_CHECKSIG'
+    def script
+      raise ArgumentError, "BTC::PublicKeyAddress: invalid data length (must be 20 bytes)" if self.data.bytesize != 20
+      BTC::Script.new << OP_DUP << OP_HASH160 << self.data << OP_EQUALVERIFY << OP_CHECKSIG
+    end
+  end
+
+
+  # P2SH address (e.g. 3NukJ6fYZJ5Kk8bPjycAnruZkE5Q7UW7i8)
+  class ScriptHashAddress < Hash160Address
+
+    def self.mainnet_version
+      5
+    end
+
+    def self.testnet_version
+      196
+    end
+
+    def p2sh?
+      true
+    end
+
+    # Instantiates address with a given redeem script.
+    def initialize(string: nil, hash: nil, network: nil, _raw_data: nil, redeem_script: nil)
+      if redeem_script
+        super(hash: BTC.hash160(redeem_script.data), network: network)
+      else
+        super(string: string, hash: hash, network: network, _raw_data: _raw_data)
+      end
+    end
+
+    # Instantiates address with a given redeem script.
+    def self.with_redeem_script(redeem_script, network: nil)
+      raise ArgumentError, "Use #{self}.new(redeem_script: ...) instead"
+    end
+
+    # Instantiates address with a given redeem script binary data.
+    def self.with_redeem_script_data(redeem_script_data, network: nil)
+      raise ArgumentError, "Use #{self}.new(hash: BTC.hash160(redeem_script.data)) instead"
+    end
+
+    # Returns BTC::Script with data 'OP_HASH160 <hash> OP_EQUAL'
+    def script
+      raise ArgumentError, "BTC::ScriptHashAddress: invalid data length (must be 20 bytes)" if self.data.bytesize != 20
+      BTC::Script.new << OP_HASH160 << self.data << OP_EQUAL
+    end
+  end
+end

data/lib/btcruby/base58.rb

@@ -0,0 +1,108 @@
+module BTC
+  # Base58 is used for compact human-friendly representation of Bitcoin addresses and private keys.
+  # Typically Base58-encoded text also contains a checksum (so-called "Base58Check").
+  # Addresses look like 19FGfswVqxNubJbh1NW8A4t51T9x9RDVWQ.
+  # Private keys look like 5KQntKuhYWSRXNqp2yhdXzjekYAR7US3MT1715Mbv5CyUKV6hVe.
+  #
+  # Here is what Satoshi said about Base58:
+  # Why base-58 instead of standard base-64 encoding?
+  # - Don't want 0OIl characters that look the same in some fonts and
+  #      could be used to create visually identical looking account numbers.
+  # - A string with non-alphanumeric characters is not as easily accepted as an account number.
+  # - E-mail usually won't line-break if there's no punctuation to break at.
+  # - Double-clicking selects the whole number as one word if it's all alphanumeric.
+  #
+  module Base58
+    extend self
+
+    ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz".freeze
+
+    # Converts binary string into its Base58 representation.
+    # If string is empty returns an empty string.
+    # If string is nil raises ArgumentError
+    def base58_from_data(data)
+      raise ArgumentError, "Data is missing" if !data
+      leading_zeroes = 0
+      int = 0
+      base = 1
+      data.bytes.reverse_each do |byte|
+        if byte == 0
+          leading_zeroes += 1
+        else
+          leading_zeroes = 0
+          int += base*byte
+        end
+        base *= 256
+      end
+      return ("1"*leading_zeroes) + base58_from_int(int)
+    end
+
+    # Converts binary string into its Base58 representation.
+    # If string is empty returns an empty string.
+    # If string is nil raises ArgumentError.
+    def data_from_base58(string)
+      raise ArgumentError, "String is missing" if !string
+      int = int_from_base58(string)
+      bytes = []
+      while int > 0
+        remainder = int % 256
+        int = int / 256
+        bytes.unshift(remainder)
+      end
+      data = BTC::Data.data_from_bytes(bytes)
+      byte_for_1 = "1".bytes.first
+      BTC::Data.ensure_ascii_compatible_encoding(string).bytes.each do |byte|
+        break if byte != byte_for_1
+        data = "\x00" + data
+      end
+      data
+    end
+
+    def base58check_from_data(data)
+      raise ArgumentError, "Data is missing" if !data
+      return base58_from_data(data + BTC.hash256(data)[0,4])
+    end
+
+    def data_from_base58check(string)
+      data = data_from_base58(string)
+      if data.bytesize < 4
+        raise FormatError, "Invalid Base58Check string: too short string #{string.inspect}"
+      end
+      payload_size = data.bytesize - 4
+      payload = data[0, payload_size]
+      checksum = data[payload_size, 4]
+      if checksum != BTC.hash256(payload)[0,4]
+        raise FormatError, "Invalid Base58Check string: checksum invalid in #{string.inspect}"
+      end
+      payload
+    end
+
+    private
+
+    def base58_from_int(int)
+      raise ArgumentError, "Integer is missing" if !int
+      string = ''
+      base = ALPHABET.size
+      while int > 0
+        int, remainder = int.divmod(base)
+        string = ALPHABET[remainder] + string
+      end
+      return string
+    end
+
+    def int_from_base58(string)
+      raise ArgumentError, "String is missing" if !string
+      int = 0
+      base = ALPHABET.size
+      string.reverse.each_char.with_index do |char,index|
+        char_index = ALPHABET.index(char)
+        if !char_index
+          raise FormatError, "Invalid Base58 character: #{char.inspect} at index #{index} (full string: #{string.inspect})"
+        end
+        int += char_index*(base**index)
+      end
+      int
+    end
+
+  end
+end

data/lib/btcruby/big_number.rb

@@ -0,0 +1,47 @@
+# OpenSSL-compatible BigNumber API.
+module BTC
+  class BigNumber
+
+    # Ruby Integer representation (Fixnum or Bignum)
+    attr_reader :integer
+
+    # Raw little-endian signed integer data
+    attr_reader :signed_little_endian
+
+    # OpenSSL-compatible big-endian signed integer data
+    attr_reader :unsigned_big_endian
+
+    # Initializes with one of the formats:
+    # 1) Raw little-endian data extracted from MPI,
+    # 2) Native OpenSSL BIGNUM big-endian unsigned big integer,
+    # 3) Ruby Integer (Fixnum or Bignum)
+    def initialize(signed_little_endian: nil, unsigned_big_endian: nil, integer: nil)
+      if signed_little_endian
+
+        raise "Not Implemented"
+
+      elsif unsigned_big_endian
+
+        raise "Not Implemented"
+
+      elsif integer
+        @integer = integer
+      else
+        raise ArgumentError, "One of the arguments must not be nil"
+      end
+    end
+
+    def integer
+      @integer
+    end
+
+    def signed_little_endian
+      raise "Not Implemented" # reversed mpi with stripped 4-byte length prefix
+    end
+
+    def unsigned_big_endian
+      raise "Not Implemented" # bin2bn
+    end
+
+  end # BigNumber
+end # BTC