adequate_crypto_address 0.1.11 → 0.3.0

data/lib/adequate_crypto_address/bch.rb

@@ -5,6 +5,7 @@ require 'digest'
 
 module AdequateCryptoAddress
   class InvalidAddress < StandardError; end
+
   class Bch
     class InvalidLegacyAddress < ::AdequateCryptoAddress::InvalidAddress; end
     class InvalidCashAddress < ::AdequateCryptoAddress::InvalidAddress; end
@@ -25,6 +26,11 @@ module AdequateCryptoAddress
       ]
     }.freeze
     DEFAULT_PREFIX = :bitcoincash
+    CASH_PREFIXES = %w[bitcoincash bchtest bchreg].freeze
+    # CashAddr size bits (version byte bits 2..0) mapped to the hash length in bytes.
+    CASH_HASH_SIZES = { 0 => 20, 1 => 24, 2 => 28, 3 => 32, 4 => 40, 5 => 48, 6 => 56, 7 => 64 }.freeze
+    LEGACY_LENGTH = 25 # 1 version byte + 20 hash bytes + 4 checksum bytes
+    MAX_LENGTH = 120
 
     attr_reader :raw_address, :type, :payload, :prefix, :digest
 
@@ -41,23 +47,20 @@ module AdequateCryptoAddress
       end
     end
 
-    def address_type(address_code, address_type)
-      TYPE_MAP[address_code].each do |mapping|
-        return mapping if mapping.include?(address_type)
-      end
-
-      raise(AdequateCryptoAddress::InvalidAddress, 'Could not determine address type')
+    # Public contract: the detected legacy/cash type Symbol, or nil when invalid.
+    def address_type
+      type
     end
 
     def legacy_address
-      type_int = address_type(:legacy, type)[1]
+      type_int = type_mapping(:legacy, type)[1]
       input = code_list_to_string([type_int] + payload + Array(digest))
       input += Digest::SHA256.digest(Digest::SHA256.digest(input))[0..3] unless digest
       Base58.binary_to_base58(input, :bitcoin)
     end
 
     def cash_address
-      type_int = address_type(:cash, type)[1]
+      type_int = type_mapping(:cash, type)[1]
       p = [type_int] + payload
       p = convertbits(p, 8, 5)
       checksum = calculate_cash_checksum(p)
@@ -68,7 +71,18 @@ module AdequateCryptoAddress
 
     private
 
+    def type_mapping(address_code, address_type)
+      TYPE_MAP[address_code].each do |mapping|
+        return mapping if mapping.include?(address_type)
+      end
+
+      raise(AdequateCryptoAddress::InvalidAddress, 'Could not determine address type')
+    end
+
     def normalize
+      return unless raw_address.is_a?(String)
+      return if raw_address.length > MAX_LENGTH
+
       begin
         from_cash_string
       rescue InvalidCashAddress
@@ -79,43 +93,83 @@ module AdequateCryptoAddress
     end
 
     def from_cash_string
-      if (raw_address.upcase != raw_address) && (raw_address.downcase != raw_address)
-        raise(InvalidCashAddress, 'Cash address contains uppercase and lowercase characters')
-      end
+      validate_cash_address_case!
 
       @raw_address = raw_address.downcase
-      @raw_address = "#{DEFAULT_PREFIX}:#{raw_address}" if !raw_address.include?(':')
+      @raw_address = "#{DEFAULT_PREFIX}:#{raw_address}" unless raw_address.include?(':')
 
       @prefix, base32string = raw_address.split(':')
-      decoded = b32decode(base32string)
+      raise(InvalidCashAddress, 'Unsupported cash address prefix') unless CASH_PREFIXES.include?(prefix)
+
+      assign_cash_payload(decode_cash_payload(base32string))
+    end
 
-      raise(InvalidCashAddress, 'Bad cash address checksum') if !verify_cash_checksum(decoded)
+    def assign_cash_payload(payload_bytes)
+      version = payload_bytes.first
+      raise(InvalidCashAddress, 'Invalid cash address version byte') unless valid_cash_version?(version, payload_bytes)
+
+      @payload = payload_bytes[1..]
+      @type = cash_type(version)
+      @type = testnet_type(type) if prefix == 'bchtest'
+    end
 
-      converted = convertbits(decoded, 5, 8)
-      @type = address_type(:cash, converted[0].to_i)[0]
-      @payload = converted[1..-7]
+    # Version byte layout: bit 7 reserved (must be 0), bits 6..3 type, bits 2..0 size.
+    def valid_cash_version?(version, payload_bytes)
+      return false unless version&.nobits?(0x80)
+      return false unless cash_type(version)
 
-      @type = :p2shtest if prefix == 'bchtest' && type == :p2sh
-      @type = :p2pkhtest if prefix == 'bchtest' && type == :p2pkh
+      expected = CASH_HASH_SIZES[version & 0x07]
+      (payload_bytes.length - 1) == expected
+    end
+
+    def cash_type(version)
+      { 0 => :p2pkh, 1 => :p2sh }[(version >> 3) & 0x0f]
     end
 
     def from_legacy_string
-      decoded = nil
-      begin
-        decoded = Base58.base58_to_binary(raw_address, :bitcoin).bytes
-      rescue StandardError
-        raise(InvalidLegacyAddress, 'Could not decode legacy address')
-      end
+      decoded = decode_legacy_address
+      raise(InvalidLegacyAddress, 'Invalid legacy address length') unless decoded.length == LEGACY_LENGTH
+      raise(InvalidLegacyAddress, 'Bad legacy address checksum') unless valid_legacy_checksum?(decoded)
 
-      @type = address_type(:legacy, decoded[0].to_i)[0]
+      @type = type_mapping(:legacy, decoded[0].to_i)[0]
       @payload = decoded[1..-5]
-      @digest = decoded[-4..-1]
+      @digest = decoded[-4..]
       @prefix = DEFAULT_PREFIX
-
-      @type = :p2shtest if prefix == 'bchtest' && type == :p2sh
-      @type = :p2pkhtest if prefix == 'bchtest' && type == :p2pkh
       @prefix = 'bchtest' if [:p2shtest, :p2pkhtest].include?(type)
     end
+
+    def valid_legacy_checksum?(decoded)
+      body = code_list_to_string(decoded[0...-4])
+      Digest::SHA256.digest(Digest::SHA256.digest(body))[0, 4] == code_list_to_string(decoded[-4..])
+    end
+
+    def validate_cash_address_case!
+      return if raw_address.upcase == raw_address || raw_address.downcase == raw_address
+
+      raise(InvalidCashAddress, 'Cash address contains uppercase and lowercase characters')
+    end
+
+    def decode_cash_payload(base32string)
+      decoded = b32decode(base32string)
+      raise(InvalidCashAddress, 'Invalid cash address encoding') if decoded.empty? || decoded.include?(nil)
+      raise(InvalidCashAddress, 'Bad cash address checksum') unless verify_cash_checksum(decoded)
+
+      # Drop the eight 5-bit checksum symbols, then map the payload back to bytes.
+      payload = convertbits(decoded[0...-8], 5, 8, pad: false)
+      raise(InvalidCashAddress, 'Invalid cash address payload') unless payload
+
+      payload
+    end
+
+    def decode_legacy_address
+      Base58.base58_to_binary(raw_address, :bitcoin).bytes
+    rescue StandardError
+      raise(InvalidLegacyAddress, 'Could not decode legacy address')
+    end
+
+    def testnet_type(address_type)
+      { p2sh: :p2shtest, p2pkh: :p2pkhtest }.fetch(address_type)
+    end
   end
 
   Bitcoincash = Bch

data/lib/adequate_crypto_address/btc.rb

@@ -2,97 +2,124 @@
 
 module AdequateCryptoAddress
   class Btc
-    attr_reader :address, :type
+    BASE58_TYPES = {
+      '00' => :hash160,
+      '05' => :p2sh,
+      '6f' => :hash160test,
+      'c4' => :p2shtest
+    }.freeze
+    BASE58_NETWORKS = { '00' => :mainnet, '05' => :mainnet, '6f' => :testnet, 'c4' => :testnet }.freeze
+    SEGWIT_NETWORKS = { 'bc' => :mainnet, 'tb' => :testnet }.freeze
+    MAX_LENGTH = 100
+
+    attr_reader :address, :type, :network
     alias raw_address address
 
     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
+
+    # Public contract: the detected type Symbol, or nil when invalid. The
+    # SegWit type is network-agnostic; use #network to enforce mainnet/testnet.
+    def address_type
+      type
     end
 
     private
 
-    def address_type
-      segwit_decoded = begin
-                         decode_segwit_address
-                       rescue StandardError
-                         nil
-                       end
-      if segwit_decoded
-        witness_version, witness_program_hex = segwit_decoded
-        witness_program = [witness_program_hex].pack('H*')
-
-        return :segwit_v0_keyhash if witness_version == 0 && witness_program.bytesize == 20
-
-        return :segwit_v0_scripthash if witness_version == 0 && witness_program.bytesize == 32
-
-        return :taproot if witness_version == 1 && witness_program.bytesize == 32
-      end
-
-      base58_decoded = begin
-              decode_base58(address)
-                       rescue StandardError
-                         nil
-            end
-      if base58_decoded && base58_decoded.bytesize == 50 && valid_base58_address_checksum?(base58_decoded)
-        case base58_decoded[0...2]
-        when '00'
-          return :hash160
-        when '05'
-          return :p2sh
-        when '6f'
-          return :hash160test
-        when 'c4'
-          return :p2shtest
-        end
-      end
+    def detect_type
+      return nil if address.to_s.length > MAX_LENGTH
 
-      nil
+      segwit_address_type || base58_address_type
+    end
+
+    def segwit_address_type
+      hrp, witness_version, witness_program_hex = safely_decode_segwit_address
+      return unless witness_version
+
+      witness_program_size = witness_program_hex.length / 2
+      type = segwit_type(witness_version, witness_program_size)
+      @network = SEGWIT_NETWORKS[hrp] if type
+      type
+    end
+
+    def segwit_type(witness_version, witness_program_size)
+      return { 20 => :segwit_v0_keyhash, 32 => :segwit_v0_scripthash }[witness_program_size] if witness_version.zero?
+
+      :taproot if witness_version == 1 && witness_program_size == 32
+    end
+
+    def base58_address_type
+      decoded = safely_decode_base58
+      return unless decoded&.bytesize == 50
+      return unless valid_base58_address_checksum?(decoded)
+
+      version = decoded[0...2]
+      @network = BASE58_NETWORKS[version]
+      BASE58_TYPES[version]
     end
 
     def decode_segwit_address
-      actual_hrp, data = Utils::Bech32.decode(address)
+      actual_hrp, data, encoding = Utils::Bech32.decode(address, include_encoding: true)
+      return nil unless %w[bc tb].include?(actual_hrp)
+      return nil if data.empty? || data.size > 65
+
+      witness_version = data.first
+      return nil unless valid_witness_encoding?(witness_version, encoding)
+
+      program = Utils::Bech32.convert_bits(data[1..], from_bits: 5, to_bits: 8, pad: false)
+      return nil unless valid_witness_program?(witness_version, program)
+
+      [actual_hrp, witness_version, program.pack('C*').unpack1('H*')]
+    end
 
-      return nil if actual_hrp.nil?
+    def valid_witness_encoding?(witness_version, encoding)
+      return false unless witness_version&.between?(0, 16)
 
-      length = data.size
-      return nil if length == 0 || length > 65
-      return nil if actual_hrp != 'bc'
-      return nil if data[0] > 16
+      encoding == (witness_version.zero? ? :bech32 : :bech32m)
+    end
+
+    def valid_witness_program?(witness_version, program)
+      return false unless program&.size&.between?(2, 40)
+      return [20, 32].include?(program.size) if witness_version.zero?
+      return program.size == 32 if witness_version == 1
 
-      program = Utils::Bech32.convert_bits(data[1..-1], from_bits: 5, to_bits: 8, pad: false)
-      return nil if program.nil?
+      true
+    end
 
-      length = program.size
-      return nil if length < 2 || length > 40
-      return nil if data[0] == 0 && length != 20 && length != 32
-      return nil if data[0] == 1 && length != 32
+    def safely_decode_segwit_address
+      decode_segwit_address
+    rescue StandardError
+      []
+    end
 
-      program_hex = program.pack('C*').unpack('H*').first
-      [data[0], program_hex]
+    def safely_decode_base58
+      decode_base58
+    rescue StandardError
+      nil
     end
 
-    def decode_base58(_base58_val)
+    def decode_base58
       Base58.base58_to_binary(address, :bitcoin).each_byte.map { |b| b.to_s(16).rjust(2, '0') }.join
     end
 
     def valid_base58_address_checksum?(base58_decoded)
       return false unless base58_decoded
 
-      checksum(base58_decoded[0...-8]) == base58_decoded[-8..-1]
+      checksum(base58_decoded[0...-8]) == base58_decoded[-8..]
     end
 
     def checksum(hex)
       Digest::SHA256.hexdigest(Digest::SHA256.digest([hex].pack('H*')))[0...8]
     end
   end
+
   Bitcoin = Btc
 end

data/lib/adequate_crypto_address/doge.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module AdequateCryptoAddress
+  class Doge < Altcoin
+    ADDRESS_TYPES = {
+      prod: %w[1e 16],
+      test: %w[71 c4]
+    }.freeze
+  end
+
+  Dogecoin = Doge
+end

data/lib/adequate_crypto_address/eth.rb

@@ -23,7 +23,10 @@ module AdequateCryptoAddress
       end
     end
 
-    def address_type; end
+    # :eth when the address is a valid (optionally checksummed) address, else nil.
+    def address_type
+      valid? ? :eth : nil
+    end
 
     private
 
@@ -37,8 +40,6 @@ module AdequateCryptoAddress
       normalize(cased.join)
     end
 
-    private
-
     def checksum_matches?
       address == checksummed
     end
@@ -67,17 +68,26 @@ module AdequateCryptoAddress
       remove_hex_prefix address
     end
 
-    def remove_hex_prefix(s)
-      s[0, 2] == '0x' ? s[2..-1] : s
+    def remove_hex_prefix(string)
+      string[0, 2] == '0x' ? string[2..] : string
     end
 
     def bin_to_hex(string)
       string.unpack1('H*')
     end
 
-    def keccak256(x)
-      Digest::Keccak.new(256).digest(x)
+    def keccak256(input)
+      Digest::Keccak.new(256).digest(input)
     end
   end
   Ethereum = Eth
+
+  # BNB Smart Chain uses the same address format and EIP-55 checksum as Ethereum.
+  class Bsc < Eth
+    def address_type
+      valid? ? :bsc : nil
+    end
+  end
+
+  Binancesmartchain = Bsc
 end

data/lib/adequate_crypto_address/ltc.rb

@@ -6,51 +6,59 @@ module AdequateCryptoAddress
 
     private
 
-    def address_type
-      segwit_decoded = begin
-                         decode_segwit_address
-                       rescue StandardError
-                         nil
-                       end
-
-      if segwit_decoded
-        witness_version, witness_program_hex, hrp = segwit_decoded
-        witness_program = [witness_program_hex].pack('H*')
-
-        if witness_version == 0
-          return :prod if hrp == 'ltc' && [20, 32].include?(witness_program.bytesize)
-          return :test if hrp == 'tltc' && [20, 32].include?(witness_program.bytesize)
-        end
-
-        if witness_version == 1 && witness_program.bytesize == 32
-          return :prod if hrp == 'ltc'
-          return :test if hrp == 'tltc'
-        end
-      end
-
-      super
+    def detect_type
+      return nil if too_long?
+
+      segwit_address_type || super
     end
 
-    def decode_segwit_address
-      actual_hrp, data = Utils::Bech32.decode(address)
+    def segwit_address_type
+      witness_version, witness_program_hex, hrp = safely_decode_segwit_address
+      return unless witness_version
 
-      return nil if actual_hrp.nil?
+      witness_program_size = witness_program_hex.length / 2
+      return unless valid_known_witness_program?(witness_version, witness_program_size)
+
+      { 'ltc' => :prod, 'tltc' => :test }[hrp]
+    end
 
-      length = data.size
-      return nil if length == 0 || length > 65
+    def decode_segwit_address
+      actual_hrp, data, encoding = Utils::Bech32.decode(address, include_encoding: true)
       return nil unless %w[ltc tltc].include?(actual_hrp)
-      return nil if data[0] > 16
+      return nil if data.empty? || data.size > 65
+
+      witness_version = data.first
+      return nil unless valid_witness_encoding?(witness_version, encoding)
 
-      program = Utils::Bech32.convert_bits(data[1..-1], from_bits: 5, to_bits: 8, pad: false)
-      return nil if program.nil?
+      program = Utils::Bech32.convert_bits(data[1..], from_bits: 5, to_bits: 8, pad: false)
+      return nil unless valid_witness_program?(witness_version, program)
+
+      program_hex = program.pack('C*').unpack1('H*')
+      [witness_version, program_hex, actual_hrp]
+    end
 
-      length = program.size
-      return nil if length < 2 || length > 40
-      return nil if data[0] == 0 && length != 20 && length != 32
-      return nil if data[0] == 1 && length != 32
+    def valid_witness_encoding?(witness_version, encoding)
+      return false unless witness_version&.between?(0, 16)
+
+      encoding == (witness_version.zero? ? :bech32 : :bech32m)
+    end
+
+    def valid_witness_program?(witness_version, program)
+      return false unless program&.size&.between?(2, 40)
+      return [20, 32].include?(program.size) if witness_version.zero?
+      return program.size == 32 if witness_version == 1
+
+      true
+    end
+
+    def valid_known_witness_program?(witness_version, program_size)
+      (witness_version.zero? && [20, 32].include?(program_size)) || (witness_version == 1 && program_size == 32)
+    end
 
-      program_hex = program.pack('C*').unpack('H*').first
-      [data[0], program_hex, actual_hrp]
+    def safely_decode_segwit_address
+      decode_segwit_address
+    rescue StandardError
+      []
     end
   end
   Litecoin = Ltc

data/lib/adequate_crypto_address/sol.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module AdequateCryptoAddress
+  class Sol
+    ALPHABET_TYPE = :bitcoin
+    MAX_LENGTH = 64 # a 32-byte key encodes to at most 44 Base58 characters
+
+    attr_reader :address
+
+    def initialize(address_string)
+      @address = address_string
+    end
+
+    def valid?(_type = nil)
+      valid_format?
+    end
+
+    # :solana when the address decodes to a 32-byte key, otherwise nil.
+    def address_type
+      valid_format? ? :solana : nil
+    end
+
+    private
+
+    def valid_format?
+      return false if address.to_s.length > MAX_LENGTH
+
+      decoded = Base58.base58_to_binary(address, ALPHABET_TYPE)
+      decoded.bytesize == 32
+    rescue StandardError
+      false
+    end
+  end
+
+  Solana = Sol
+end

data/lib/adequate_crypto_address/ton.rb

@@ -1,7 +1,16 @@
 # frozen_string_literal: true
 
 module AdequateCryptoAddress
+  # Validates TON user-friendly addresses (TEP-2). The 48-character Base64URL
+  # form decodes to 36 bytes: tag(1) + workchain(1) + account_id(32) + crc16(2).
   class Ton
+    ADDRESS_LENGTH = 48
+    DECODED_LENGTH = 36
+    BOUNCEABLE_TAG = 0x11
+    NON_BOUNCEABLE_TAG = 0x51
+    TEST_FLAG = 0x80
+    VALID_WORKCHAINS = [0x00, 0xff].freeze
+
     attr_reader :address, :type
 
     def initialize(address)
@@ -17,14 +26,55 @@ module AdequateCryptoAddress
       end
     end
 
+    # :ton_mainnet or :ton_testnet when valid, otherwise nil.
+    def address_type
+      bytes = decode
+      return nil unless bytes
+
+      tag = bytes[0]
+      return nil unless valid_tag?(tag)
+      return nil unless VALID_WORKCHAINS.include?(bytes[1])
+      return nil unless checksum_valid?(bytes)
+
+      tag.anybits?(TEST_FLAG) ? :ton_testnet : :ton_mainnet
+    end
+
     private
 
-    def address_type
-      return :TON if address.size == 48 && pattern_valid?
+    def decode
+      return nil unless valid_encoding?
+
+      # Base64URL decode via core unpack (the base64 gem is only a wrapper).
+      bytes = address.tr('-_', '+/').unpack1('m0')&.bytes
+      bytes if bytes && bytes.length == DECODED_LENGTH
+    rescue ArgumentError
+      nil
     end
 
-    def pattern_valid?
-      address.match(/([0-9a-zA-Z]|-|_){48}/)
+    def valid_encoding?
+      address.is_a?(String) &&
+        address.length == ADDRESS_LENGTH &&
+        address.match?(/\A[A-Za-z0-9_-]{#{ADDRESS_LENGTH}}\z/)
+    end
+
+    def valid_tag?(tag)
+      [BOUNCEABLE_TAG, NON_BOUNCEABLE_TAG].include?(tag & ~TEST_FLAG)
+    end
+
+    def checksum_valid?(bytes)
+      crc = crc16(bytes[0...34])
+      [(crc >> 8) & 0xff, crc & 0xff] == bytes[34..35]
+    end
+
+    # CRC16-CCITT (XMODEM): polynomial 0x1021, initial value 0x0000.
+    def crc16(bytes)
+      bytes.reduce(0) do |crc, byte|
+        crc ^= byte << 8
+        8.times { crc = crc.anybits?(0x8000) ? ((crc << 1) ^ 0x1021) & 0xffff : (crc << 1) & 0xffff }
+        crc
+      end
     end
   end
+
+  Toncoin = Ton
 end

data/lib/adequate_crypto_address/trx.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module AdequateCryptoAddress
+  # TRON mainnet addresses are Base58Check with the 0x41 version byte and a
+  # four-byte double-SHA256 checksum (25 bytes total, rendered as a 34-character
+  # string starting with "T"). https://developers.tron.network/docs/account
+  class Trx < Altcoin
+    ADDRESS_TYPES = { prod: %w[41] }.freeze
+  end
+
+  Tron = Trx
+end