adequate_crypto_address 0.1.10 → 0.2.0

data/lib/adequate_crypto_address/utils/bech32.rb

@@ -15,154 +15,183 @@ module AdequateCryptoAddress
         -1, 29, -1, 24, 13, 25, 9, 8, 23, -1, 18, 22, 31, 27, 19, -1,
         1,  0,  3, 16, 11, 28, 12, 14, 6, 4, 2, -1, -1, -1, -1, -1
       ].freeze
+      GENERATORS = [0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3].freeze
 
       class << self
         def polymod_step(pre)
           b = pre >> 25
-          ((pre & 0x1FFFFFF) << 5) ^ \
-            (-((b >> 0) & 1) & 0x3b6a57b2) ^ \
-            (-((b >> 1) & 1) & 0x26508e6d) ^ \
-            (-((b >> 2) & 1) & 0x1ea119fa) ^ \
-            (-((b >> 3) & 1) & 0x3d4233dd) ^ \
-            (-((b >> 4) & 1) & 0x2a1462b3)
+          GENERATORS.each_with_index.reduce((pre & 0x1FFFFFF) << 5) do |checksum, (generator, index)|
+            checksum ^ (-((b >> index) & 1) & generator)
+          end
         end
 
-        # def encode(hrp, data)
-        #   buf = []
-        #   chk = 1
+        def decode(input, ignore_length: false, include_encoding: false)
+          hrp_string, data_string = split_input(input, ignore_length: ignore_length)
+          return nil unless hrp_string
 
-        #   hrp.unpack('C*').each do |ch|
-        #     return nil if ch < 33 || ch > 126
-        #     return nil if ch >= 'A'.ord && ch <= 'Z'.ord
+          hrp, checksum, casing = decode_hrp(hrp_string)
+          return nil unless hrp
 
-        #     chk = polymod_step(chk) ^ (ch >> 5)
-        #   end
+          data, checksum, casing = decode_data(data_string, checksum, casing)
+          return nil unless data
+          return nil if casing.values.all?
 
-        #   return nil if (hrp.bytesize + 7 + data.size) > 90
+          encoding = checksum_encoding(checksum)
+          return nil unless encoding
 
-        #   chk = polymod_step(chk)
-        #   hrp.unpack('C*').each do |ch|
-        #     chk = polymod_step(chk) ^ (ch & 0x1f)
-        #     buf << ch
-        #   end
+          decoded = [hrp.pack('C*'), data]
+          include_encoding ? decoded << encoding : decoded
+        end
 
-        #   buf << '1'.ord
+        # Utility for converting bytes of data between bases. These is used for
+        # BIP 173 address encoding/decoding to convert between sequences of bytes
+        # representing 8-bit values and groups of 5 bits. Conversions may be padded
+        # with trailing 0 bits to the nearest byte boundary. Returns nil if
+        # conversion requires padding and pad is false.
+        #
+        # For example:
+        #
+        #   convert_bits("\xFF\xFF", from_bits: 8, to_bits: 5, pad: true)
+        #     => "\x1F\x1F\x1F\10"
+        #
+        # See https://github.com/bitcoin/bitcoin/blob/595a7bab23bc21049526229054ea1fff1a29c0bf/src/utilstrencodings.h#L154
+        def convert_bits(chunks, from_bits:, to_bits:, pad:)
+          return nil unless valid_chunks?(chunks, from_bits)
+
+          conversion = {
+            from_bits: from_bits,
+            to_bits: to_bits,
+            output_mask: (1 << to_bits) - 1,
+            buffer_mask: (1 << (from_bits + to_bits - 1)) - 1
+          }
+          buffer = 0
+          bits = 0
+          output = []
 
-        #   data.each do |i|
-        #     return nil if (i >> 5) != 0
+          chunks.each do |chunk|
+            buffer, bits, converted = convert_chunk(chunk, buffer, bits, conversion)
+            output.concat(converted)
+          end
 
-        #     chk = polymod_step(chk) ^ i
-        #     buf << CHARSET[i]
-        #   end
+          remainder = conversion_remainder(buffer, bits, conversion, pad)
+          return nil if remainder == :invalid
 
-        #   6.times do
-        #     chk = polymod_step(chk)
-        #   end
+          output << remainder if remainder
 
-        #   chk ^= 1
+          output
+        end
 
-        #   6.times do |i|
-        #     buf << CHARSET[(chk >> ((5 - i) * 5)) & 0x1f]
-        #   end
+        private
 
-        #   buf.pack('C*')
-        # end
+        def split_input(input, ignore_length:)
+          input_length = input.bytesize
+          return if input_length < 8
+          return if input_length > 90 && !ignore_length
 
-        # rubocop:disable CyclomaticComplexity,PerceivedComplexity
-        def decode(input)
-          chk = 1
-          input_len = input.bytesize
-          have_lower = false
-          have_upper = false
+          separator = input.rindex('1')
+          return unless separator&.positive?
+          return if (input_length - separator - 1) < 6
 
-          return nil if input_len < 8 || input_len > 90
+          [input[0...separator], input[(separator + 1)..]]
+        end
 
-          data_len = 0
-          data_len += 1 while data_len < input_len && input[(input_len - 1) - data_len] != '1'
+        def decode_hrp(hrp_string)
+          hrp, casing = normalize_hrp(hrp_string)
+          return unless hrp
 
-          hrp_len = input_len - (1 + data_len)
-          return nil if hrp_len < 1 || data_len < 6
+          [hrp, hrp_checksum(hrp), casing]
+        end
 
+        def normalize_hrp(hrp_string)
           hrp = []
-          hrp_len.times do |i|
-            ch = input[i].ord
-            return nil if ch < 33 || ch > 126
-
-            if ch >= 'a'.ord && ch <= 'z'.ord
-              have_lower = true
-            elsif ch >= 'A'.ord && ch <= 'Z'.ord
-              have_upper = true
-              ch = (ch - 'A'.ord) + 'a'.ord
-            end
-
-            hrp << ch
-            chk = polymod_step(chk) ^ (ch >> 5)
+          casing = { lower: false, upper: false }
+
+          index = 0
+          while index < hrp_string.bytesize
+            character = hrp_string.getbyte(index)
+            character, character_case = normalize_hrp_character(character)
+            return unless character
+
+            casing[character_case] = true if character_case
+            hrp << character
+            index += 1
           end
 
-          chk = polymod_step(chk)
+          [hrp, casing]
+        end
 
-          hrp_len.times do |i|
-            chk = polymod_step(chk) ^ (input[i].ord & 0x1f)
+        def hrp_checksum(hrp)
+          checksum = hrp.reduce(1) do |value, character|
+            polymod_step(value) ^ (character >> 5)
           end
+          checksum = polymod_step(checksum)
+          hrp.each { |character| checksum = polymod_step(checksum) ^ (character & 0x1f) }
+          checksum
+        end
 
+        def decode_data(data_string, checksum, casing)
           data = []
-          i = hrp_len + 1
-          while i < input_len
-            ch = input[i].ord
-            v = (ch & 0x80) != 0 ? -1 : CHARSET_REV[ch]
-
-            have_lower = true if ch >= 'a'.ord && ch <= 'z'.ord
-            have_upper = true if ch >= 'A'.ord && ch <= 'Z'.ord
-            return nil if v == -1
-
-            chk = polymod_step(chk) ^ v
-            data << v if (i + 6) < input_len
-            i += 1
+          payload_length = data_string.bytesize - 6
+
+          index = 0
+          while index < data_string.bytesize
+            character = data_string.getbyte(index)
+            value = character.nobits?(0x80) ? CHARSET_REV[character] : -1
+            return if value == -1
+
+            character_case = letter_case(character)
+            casing[character_case] = true if character_case
+            checksum = polymod_step(checksum) ^ value
+            data << value if index < payload_length
+            index += 1
           end
 
-          return nil if have_lower && have_upper
-          
-          # Accept both Bech32 (chk == 1) and Bech32m (chk == 0x2bc830a3)
-          return nil unless chk == 1 || chk == 0x2bc830a3
+          [data, checksum, casing]
+        end
+
+        def normalize_hrp_character(character)
+          return unless character.between?(33, 126)
+          return [character, :lower] if character.between?('a'.ord, 'z'.ord)
+          return [(character - 'A'.ord) + 'a'.ord, :upper] if character.between?('A'.ord, 'Z'.ord)
 
-          [hrp.pack('C*'), data]
+          [character, nil]
         end
-        # rubocop:enable CyclomaticComplexity,PerceivedComplexity
 
-        # Utility for converting bytes of data between bases. These is used for
-        # BIP 173 address encoding/decoding to convert between sequences of bytes
-        # representing 8-bit values and groups of 5 bits. Conversions may be padded
-        # with trailing 0 bits to the nearest byte boundary. Returns nil if
-        # conversion requires padding and pad is false.
-        #
-        # For example:
-        #
-        #   convert_bits("\xFF\xFF", from_bits: 8, to_bits: 5, pad: true)
-        #     => "\x1F\x1F\x1F\10"
-        #
-        # See https://github.com/bitcoin/bitcoin/blob/595a7bab23bc21049526229054ea1fff1a29c0bf/src/utilstrencodings.h#L154
-        def convert_bits(chunks, from_bits:, to_bits:, pad:)
-          output_mask = (1 << to_bits) - 1
-          buffer_mask = (1 << (from_bits + to_bits - 1)) - 1
+        def letter_case(character)
+          return :lower if character.between?('a'.ord, 'z'.ord)
 
-          buffer = 0
-          bits = 0
+          :upper if character.between?('A'.ord, 'Z'.ord)
+        end
+
+        def checksum_encoding(checksum)
+          return :bech32 if checksum == 1
+
+          :bech32m if checksum == 0x2bc830a3
+        end
 
+        def valid_chunks?(chunks, from_bits)
+          chunks.all? { |chunk| chunk.between?(0, (1 << from_bits) - 1) }
+        end
+
+        def convert_chunk(chunk, buffer, bits, conversion)
+          buffer = ((buffer << conversion[:from_bits]) | chunk) & conversion[:buffer_mask]
+          bits += conversion[:from_bits]
           output = []
-          chunks.each do |chunk|
-            buffer = ((buffer << from_bits) | chunk) & buffer_mask
-            bits += from_bits
-            while bits >= to_bits
-              bits -= to_bits
-              output << ((buffer >> bits) & output_mask)
-            end
+
+          while bits >= conversion[:to_bits]
+            bits -= conversion[:to_bits]
+            output << ((buffer >> bits) & conversion[:output_mask])
           end
 
-          output << ((buffer << (to_bits - bits)) & output_mask) if pad && bits > 0
+          [buffer, bits, output]
+        end
 
-          return nil if !pad && (bits >= from_bits || ((buffer << (to_bits - bits)) & output_mask) != 0)
+        def conversion_remainder(buffer, bits, conversion, pad)
+          return (buffer << (conversion[:to_bits] - bits)) & conversion[:output_mask] if pad && bits.positive?
+          return if pad
+          return :invalid if bits >= conversion[:from_bits]
 
-          output
+          :invalid if (buffer << (conversion[:to_bits] - bits)).anybits?(conversion[:output_mask])
         end
       end
     end

data/lib/adequate_crypto_address/utils/monero_base58.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module AdequateCryptoAddress
+  module Utils
+    # Monero's Base58 encodes fixed 8-byte blocks into 11 characters (shorter
+    # trailing blocks use fewer characters). Reference:
+    # https://github.com/monero-project/monero/blob/master/src/common/base58.cpp
+    module MoneroBase58
+      ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'
+      FULL_BLOCK_SIZE = 8
+      FULL_ENCODED_BLOCK_SIZE = 11
+      # Decoded byte count produced by an encoded block of each valid length.
+      ENCODED_BLOCK_SIZES = [0, 2, 3, 5, 6, 7, 9, 10, 11].freeze
+
+      module_function
+
+      def decode(string)
+        return nil if string.nil? || string.empty?
+
+        full_blocks = string.length / FULL_ENCODED_BLOCK_SIZE
+        last_size = string.length % FULL_ENCODED_BLOCK_SIZE
+        return nil unless ENCODED_BLOCK_SIZES.include?(last_size)
+
+        out = []
+        full_blocks.times do |i|
+          block = decode_block(string[i * FULL_ENCODED_BLOCK_SIZE, FULL_ENCODED_BLOCK_SIZE], FULL_BLOCK_SIZE)
+          return nil unless block
+
+          out.concat(block)
+        end
+        decode_tail(string, full_blocks, last_size, out)
+      end
+
+      def decode_tail(string, full_blocks, last_size, out)
+        return out if last_size.zero?
+
+        tail = string[full_blocks * FULL_ENCODED_BLOCK_SIZE, last_size]
+        block = decode_block(tail, ENCODED_BLOCK_SIZES.index(last_size))
+        return nil unless block
+
+        out.concat(block)
+      end
+
+      # Decodes one Base58 block into exactly `size` big-endian bytes, rejecting
+      # unknown characters and values that overflow the target byte width.
+      def decode_block(chars, size)
+        num = 0
+        chars.each_char do |char|
+          index = ALPHABET.index(char)
+          return nil unless index
+
+          num = (num * 58) + index
+        end
+        return nil if num >= (1 << (size * 8))
+
+        Array.new(size) { |i| (num >> (8 * (size - 1 - i))) & 0xff }
+      end
+    end
+  end
+end

data/lib/adequate_crypto_address/utils/xlm.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module AdequateCryptoAddress
+  module Utils
+    module Xlm
+      CHARSET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567'
+
+      module_function
+
+      def decode(input)
+        values = input.chars.map { |c| CHARSET.index(c) }
+        return nil if values.include?(nil)
+
+        bytes = convertbits(values, 5, 8, pad: false)
+        return nil unless bytes
+
+        bytes.pack('C*')
+      end
+
+      def convertbits(data, frombits, tobits, pad: true)
+        Bech32.convert_bits(data, from_bits: frombits, to_bits: tobits, pad: pad)
+      end
+    end
+  end
+end

data/lib/adequate_crypto_address/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AdequateCryptoAddress
-  VERSION = '0.1.10'
+  VERSION = '0.2.0'
 end

data/lib/adequate_crypto_address/xlm.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module AdequateCryptoAddress
+  class Xlm
+    attr_reader :address
+
+    ACCOUNT_VERSION_BYTE = 0x30
+    MUXED_VERSION_BYTE = 0x60
+
+    ACCOUNT_SIZE = 35
+    MUXED_SIZE = 43
+    MAX_LENGTH = 90 # G-addresses are 56 chars, M-addresses 69
+
+    def initialize(address)
+      @address = address
+    end
+
+    def valid?(_type = nil)
+      !address_type.nil?
+    end
+
+    # :account (G...) or :muxed (M...) when valid, otherwise nil.
+    def address_type
+      decoded = decode_strkey
+      return nil unless decoded
+
+      case decoded.getbyte(0)
+      when ACCOUNT_VERSION_BYTE
+        :account if valid_strkey?(decoded, ACCOUNT_SIZE)
+      when MUXED_VERSION_BYTE
+        :muxed if valid_strkey?(decoded, MUXED_SIZE)
+      end
+    rescue StandardError
+      nil
+    end
+
+    private
+
+    def valid_strkey?(decoded, expected_size)
+      return false unless decoded.bytesize == expected_size
+
+      payload = decoded[0...-2]
+      checksum = decoded[-2..]
+
+      crc16(payload) == checksum
+    end
+
+    def decode_strkey
+      return nil if address.to_s.length > MAX_LENGTH
+
+      Utils::Xlm.decode(address)
+    end
+
+    def crc16(data)
+      crc = 0
+
+      data.each_byte do |byte|
+        crc ^= byte << 8
+
+        8.times do
+          crc =
+            if crc.anybits?(0x8000)
+              (crc << 1) ^ 0x1021
+            else
+              crc << 1
+            end
+        end
+      end
+
+      [crc & 0xffff].pack('v')
+    end
+  end
+
+  Stellar = Xlm
+end

data/lib/adequate_crypto_address/xmr.rb

@@ -1,35 +1,83 @@
 # frozen_string_literal: true
 
+require 'digest'
+
 module AdequateCryptoAddress
+  # Validates Monero addresses by decoding the Monero Base58 payload and
+  # verifying the network byte, structural length, and Keccak-256 checksum.
+  # References: https://docs.getmonero.org/public-address/standard-address/
+  # and https://docs.getmonero.org/public-address/integrated-address/
   class Xmr
-    attr_reader :address, :type
+    STANDARD_LENGTH = 69   # prefix(1) + spend key(32) + view key(32) + checksum(4)
+    INTEGRATED_LENGTH = 77 # standard + payment id(8)
+    CHECKSUM_LENGTH = 4
+    ENCODED_LENGTHS = [95, 106].freeze
+
+    NETWORK_PREFIXES = {
+      standard: { 18 => :mainnet, 53 => :testnet, 24 => :stagenet },
+      integrated: { 19 => :mainnet, 54 => :testnet, 25 => :stagenet },
+      subaddress: { 42 => :mainnet, 63 => :testnet, 36 => :stagenet }
+    }.freeze
+
+    attr_reader :address, :type, :network
 
     def initialize(address)
       @address = address
-      @type = address_type
+      @type = detect_type
     end
 
-    def valid?(type = nil)
-      if type
-        address_type == type.to_sym
-      else
-        !address_type.nil?
-      end
+    def valid?(validated_type = nil)
+      return !type.nil? unless validated_type
+
+      type == validated_type.to_sym
+    end
+
+    # :standard, :integrated, or :subaddress when valid, otherwise nil.
+    def address_type
+      type
     end
 
     private
 
-    def address_type
-      return nil unless [95, 106].include?(address.size)
+    def detect_type
+      bytes = decode
+      return nil unless bytes
 
-      return :monero if pattern_valid?
+      category, @network = classify(bytes.first)
+      return nil unless category
+      return nil unless bytes.length == expected_length(category)
+      return nil unless valid_checksum?(bytes)
+
+      category
     end
 
-    def pattern_valid?
-      address.size == 95 ?
-        address.match(/^4|8[0-9AB][1-9A-HJ-NP-Za-km-z]{93}$/) :
-        address.match(/^4|8[1-9A-HJ-NP-Za-km-z]{105}(?:[1-9A-HJ-NP-Za-km-z]{30})?$/)
+    def decode
+      return nil unless ENCODED_LENGTHS.include?(address.to_s.length)
+
+      Utils::MoneroBase58.decode(address)
+    end
+
+    def classify(prefix)
+      NETWORK_PREFIXES.each do |category, prefixes|
+        network = prefixes[prefix]
+        return [category, network] if network
+      end
+      [nil, nil]
+    end
+
+    def expected_length(category)
+      category == :integrated ? INTEGRATED_LENGTH : STANDARD_LENGTH
+    end
+
+    def valid_checksum?(bytes)
+      body = bytes[0...-CHECKSUM_LENGTH]
+      keccak256(body.pack('C*')).bytes[0, CHECKSUM_LENGTH] == bytes[-CHECKSUM_LENGTH..]
+    end
+
+    def keccak256(data)
+      Digest::Keccak.new(256).digest(data)
     end
   end
+
   Monero = Xmr
 end

data/lib/adequate_crypto_address.rb

@@ -2,6 +2,8 @@
 
 require 'adequate_crypto_address/utils/bech32'
 require 'adequate_crypto_address/utils/bch'
+require 'adequate_crypto_address/utils/xlm'
+require 'adequate_crypto_address/utils/monero_base58'
 
 require 'adequate_crypto_address/altcoin'
 require 'adequate_crypto_address/bch'
@@ -13,6 +15,10 @@ require 'adequate_crypto_address/zec'
 require 'adequate_crypto_address/ltc'
 require 'adequate_crypto_address/ton'
 require 'adequate_crypto_address/xmr'
+require 'adequate_crypto_address/doge'
+require 'adequate_crypto_address/sol'
+require 'adequate_crypto_address/xlm'
+require 'adequate_crypto_address/ada'
 
 module AdequateCryptoAddress
   class UnknownCurrency < StandardError; end
@@ -23,12 +29,29 @@ module AdequateCryptoAddress
   end
 
   def address(address, currency)
-    AdequateCryptoAddress.const_get(currency.capitalize).new(address)
-  rescue NameError
-    raise UnknownCurrency, "Wrong currency #{currency}"
+    klass = currency_class(currency)
+    raise UnknownCurrency, "Wrong currency #{currency}" unless klass
+
+    klass.new(address)
   end
 
+  # Public contract: returns the detected address type as a Symbol when the
+  # address is valid for the currency, or nil when it is not.
   def address_type(address, currency)
-    AdequateCryptoAddress.const_get(currency.capitalize).new(address).address_type
+    address(address, currency).address_type
+  end
+
+  # Resolve a currency name (string or symbol, any case) to its validator class.
+  # Only classes defined directly on this module that implement the validator
+  # interface are eligible, so malformed input can never be mistaken for a
+  # currency and NoMethodError is never swallowed as UnknownCurrency.
+  def currency_class(currency)
+    const_name = currency.to_s.capitalize
+    return nil unless const_defined?(const_name, false)
+
+    klass = const_get(const_name)
+    return nil unless klass.is_a?(Class) && klass.method_defined?(:valid?)
+
+    klass
   end
 end