xrpl-ruby 0.6.1 → 0.8.0

data/lib/binary-codec/enums/definitions.rb

@@ -8,6 +8,26 @@ module BinaryCodec
 
     @@instance = nil
 
+    # The permissions a DelegateSet can grant that are narrower than a whole
+    # transaction type. rippled numbers them from 65537 upwards, above the
+    # range the transaction types occupy. The table is not part of
+    # definitions.json - xrpl.js carries it in code as well
+    # (XrplDefinitionsBase#granularPermissions) - so it lives here.
+    GRANULAR_PERMISSIONS = {
+      'TrustlineAuthorize' => 65_537,
+      'TrustlineFreeze' => 65_538,
+      'TrustlineUnfreeze' => 65_539,
+      'AccountDomainSet' => 65_540,
+      'AccountEmailHashSet' => 65_541,
+      'AccountMessageKeySet' => 65_542,
+      'AccountTransferRateSet' => 65_543,
+      'AccountTickSizeSet' => 65_544,
+      'PaymentMint' => 65_545,
+      'PaymentBurn' => 65_546,
+      'MPTokenIssuanceLock' => 65_547,
+      'MPTokenIssuanceUnlock' => 65_548
+    }.freeze
+
      def initialize
       file_path = File.join(__dir__, 'definitions.json') #
       contents = File.read(file_path)
@@ -18,6 +38,15 @@ module BinaryCodec
       @transaction_results = @definitions['TRANSACTION_RESULTS']
       @transaction_types = @definitions['TRANSACTION_TYPES']
 
+      # PermissionValue names a delegatable permission. A whole transaction
+      # type is its type code plus one, so that Payment (type 0) is not
+      # confused with "no permission"; the granular permissions follow above.
+      @delegatable_permissions = @transaction_types
+                                 .reject { |_, code| code.negative? }
+                                 .transform_values { |code| code + 1 }
+                                 .merge(GRANULAR_PERMISSIONS)
+                                 .freeze
+
       @field_info_map = {}
       @field_id_name_map = {}
       @field_header_map = {}
@@ -47,6 +76,19 @@ module BinaryCodec
 
      end
 
+    # The parsed definitions.json, for the sections this class does not index
+    # itself - TRANSACTION_FORMATS and TRANSACTION_FLAGS, which the transaction
+    # models are built from.
+    #
+    # @return [Hash] the raw document
+    attr_reader :definitions
+    alias raw definitions
+
+    # Name -> code tables, for the types that render as names in JSON.
+    # @return [Hash{String => Integer}]
+    attr_reader :transaction_types, :ledger_entry_types, :transaction_results,
+                :delegatable_permissions
+
     # Returns the singleton instance of the Definitions class.
     # @return [Definitions] The singleton instance.
     def self.instance
@@ -69,9 +111,12 @@ module BinaryCodec
 
     # Returns a FieldInstance for a given field name.
     # @param field_name [String] The name of the field.
-    # @return [FieldInstance] The field instance.
+    # @return [FieldInstance, nil] The field instance, nil for a name the
+    #   definitions do not know
     def get_field_instance(field_name)
        field_info = @field_info_map[field_name]
+       return nil if field_info.nil?
+
        field_header = get_field_header_from_name(field_name)
 
        FieldInstance.new(

data/lib/binary-codec/types/amount.rb

@@ -166,8 +166,11 @@ module BinaryCodec
         
         # value = mantissa * 10^exponent
         value = BigDecimal(mantissa_int) * (BigDecimal(10)**exponent)
-        value = -value unless is_positive
-        
+
+        # A zero IOU has its own encoding in which the sign bit is not set, so
+        # negating it would produce "-0" where rippled writes "0".
+        value = -value unless is_positive || mantissa_int.zero?
+
         # Format the value string to match xrpl.js (stripping trailing .0)
         formatted_value = value.to_s('F').sub(/\.0$/, '')
 

data/lib/binary-codec/types/currency.rb

@@ -51,8 +51,15 @@ module BinaryCodec
     end
 
     # Returns the JSON representation of the currency.
+    #
+    # The two ignored parameters are the SerializedType contract. Every type
+    # is called as to_json(definitions, field_name) from STObject, so a
+    # zero-arity to_json raises ArgumentError for every Currency field nested
+    # in an object - which is what silently dropped BaseAsset and QuoteAsset
+    # from PriceDataSeries.
+    #
     # @return [String] The ISO code or hex string.
-    def to_json
+    def to_json(_definitions = nil, _field_name = nil)
       iso = self.iso
       return iso unless iso.nil?
 

data/lib/binary-codec/types/issue.rb

@@ -1,47 +1,92 @@
 # frozen_string_literal: true
 
 module BinaryCodec
+  # An asset without an amount: XRP, an issued token, or an MPT.
+  #
+  # The width is not fixed, and it cannot be supplied from outside. XRP is the
+  # 20 byte currency code on its own, an issued token adds the 20 byte issuer,
+  # and an MPT carries the issuer, a reserved placeholder and the four byte
+  # issuance sequence. Only the currency code says which of the three it is, so
+  # the parser has to read that before it knows how much to consume.
+  #
+  # This class used to take a size hint and read a flat 40 bytes, which for an
+  # XRP issue swallowed the field that follows - that is why every AMM and
+  # XChain fixture decoded with a nil Asset or the wrong door account.
   class Issue < SerializedType
+    CURRENCY_LENGTH = 20
+    ISSUER_LENGTH = 20
+    SEQUENCE_LENGTH = 4
+    MPT_LENGTH = CURRENCY_LENGTH + ISSUER_LENGTH + SEQUENCE_LENGTH
+
+    # The reserved "no account" value. Sitting in the issuer slot, it marks the
+    # issue as an MPT rather than as a token issued by that account.
+    NO_ACCOUNT = '0000000000000000000000000000000000000001'
+
     def initialize(bytes = nil)
       super(bytes || [])
     end
 
     def self.from(value)
       return value if value.is_a?(Issue)
+      return Issue.new(hex_to_bytes(value)) if value.is_a?(String)
 
-      if value.is_a?(String)
-        return Issue.new(hex_to_bytes(value))
+      unless value.is_a?(::Hash)
+        raise StandardError, "Cannot construct Issue from #{value.class}"
       end
 
-      if value.is_a?(Hash) || value.is_a?(::Hash)
-        bytes = []
-        bytes.concat(Currency.from(value['currency']).to_bytes)
-        bytes.concat(AccountId.from(value['issuer']).to_bytes) if value['issuer']
-        return Issue.new(bytes)
-      end
+      return Issue.new(mpt_bytes(value['mpt_issuance_id'])) if value['mpt_issuance_id']
 
-      raise StandardError, "Cannot construct Issue from #{value.class}"
+      bytes = Currency.from(value['currency']).to_bytes
+      bytes += AccountId.from(value['issuer']).to_bytes if value['issuer']
+      Issue.new(bytes)
     end
 
-    def self.from_parser(parser, size_hint = nil)
-      bytes = []
-      return Issue.new(bytes) if parser.end?
-      bytes.concat(parser.read(20)) # Currency
-      unless parser.end? || (size_hint && size_hint <= 20)
-        bytes.concat(parser.read(20))
-      end
+    # An MPT issuance id is the issuance sequence followed by the issuer. The
+    # sequence is big endian there but little endian on the wire.
+    def self.mpt_bytes(issuance_id)
+      id = hex_to_bytes(issuance_id)
+      sequence = id[0, SEQUENCE_LENGTH]
+      issuer = id[SEQUENCE_LENGTH..]
+
+      issuer + hex_to_bytes(NO_ACCOUNT) + sequence.reverse
+    end
+    private_class_method :mpt_bytes
+
+    # The size hint is accepted and ignored: callers cannot know the width, and
+    # passing one in is how the fixed 40 byte read came about.
+    def self.from_parser(parser, _size_hint = nil)
+      return Issue.new([]) if parser.end?
+
+      currency = parser.read(CURRENCY_LENGTH)
+      return Issue.new(currency) if Currency.new(currency).to_json == 'XRP'
+
+      issuer = parser.read(ISSUER_LENGTH)
+      bytes = currency + issuer
+      bytes += parser.read(SEQUENCE_LENGTH) if bytes_to_hex(issuer).upcase == NO_ACCOUNT
+
       Issue.new(bytes)
     end
 
     def to_json(_definitions = nil, _field_name = nil)
+      return { 'mpt_issuance_id' => mpt_issuance_id } if to_bytes.length == MPT_LENGTH
+
       parser = BinaryParser.new(to_hex)
-      result = {}
-      result['currency'] = Currency.from_parser(parser).to_json
-      result['issuer'] = AccountId.from_parser(parser).to_json unless parser.end?
-      result
-    rescue
-      # Fallback for partial/invalid binary
-      { 'currency' => Currency.new(to_bytes[0, 20]).to_json }
+      currency = Currency.from_parser(parser).to_json
+
+      # An XRP issue has no issuer. Reporting one means 20 bytes of the next
+      # field were read as an account.
+      return { 'currency' => currency } if currency == 'XRP'
+
+      { 'currency' => currency, 'issuer' => AccountId.from_parser(parser).to_json }
+    end
+
+    private
+
+    def mpt_issuance_id
+      issuer = to_bytes[0, ISSUER_LENGTH]
+      sequence = to_bytes[CURRENCY_LENGTH + ISSUER_LENGTH, SEQUENCE_LENGTH].reverse
+
+      bytes_to_hex(sequence + issuer).upcase
     end
   end
 end

data/lib/binary-codec/types/number.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module BinaryCodec
+  # STNumber, the XRPL "Number" type.
+  #
+  # Always 12 bytes: a signed 64 bit mantissa followed by a signed 32 bit
+  # exponent, both big endian. Used by the Vault and Lending Protocol fields
+  # (AssetsAvailable, DebtTotal, PeriodicPayment and 14 others), which could
+  # not be serialised at all before this class existed.
+  #
+  # Reference: xrpl.js packages/ripple-binary-codec/src/types/st-number.ts
+  class Number < SerializedType
+    BYTE_LENGTH = 12
+
+    MIN_MANTISSA = 10**18
+    MAX_MANTISSA = 10**19 - 1
+    MAX_INT64 = 2**63 - 1
+
+    MIN_EXPONENT = -32_768
+    MAX_EXPONENT = 32_768
+
+    # The exponent rippled uses to encode a canonical zero.
+    DEFAULT_VALUE_EXPONENT = -2_147_483_648
+
+    # Significant decimal digits rippled renders with.
+    RANGE_LOG = 18
+
+    NUMBER_PATTERN = /\A([-+]?)([0-9]+)(?:\.([0-9]+))?(?:[eE]([+-]?[0-9]+))?\z/
+
+    def initialize(bytes = nil)
+      bytes ||= Array.new(BYTE_LENGTH, 0)
+
+      unless bytes.length == BYTE_LENGTH
+        raise StandardError, "Invalid Number length #{bytes.length}"
+      end
+
+      super(bytes)
+    end
+
+    def self.from(value)
+      return value if value.is_a?(Number)
+      mantissa, exponent = extract_parts(value.to_s)
+      mantissa, exponent = normalize(mantissa, exponent)
+
+      Number.new(pack_signed(mantissa, 8) + pack_signed(exponent, 4))
+    end
+
+    def self.from_parser(parser, _size_hint = nil)
+      Number.new(parser.read(BYTE_LENGTH))
+    end
+
+    def to_json(_definitions = nil, _field_name = nil)
+      mantissa = self.class.unpack_signed(to_bytes[0, 8])
+      exponent = self.class.unpack_signed(to_bytes[8, 4])
+
+      return '0' if mantissa.zero? && exponent == DEFAULT_VALUE_EXPONENT
+
+      negative = mantissa.negative?
+      mantissa = mantissa.abs
+
+      # A mantissa above 2^63-1 is shrunk by one digit before serialisation.
+      # Restore it so the rendering matches rippled's internal value.
+      if !mantissa.zero? && mantissa < MIN_MANTISSA
+        mantissa *= 10
+        exponent -= 1
+      end
+
+      sign = negative ? '-' : ''
+
+      if exponent != 0 && (exponent < -(RANGE_LOG + 10) || exponent > -(RANGE_LOG - 10))
+        return sign + scientific(mantissa, exponent)
+      end
+
+      sign + positional(mantissa, exponent)
+    end
+
+    # Scientific notation, with trailing zeros moved into the exponent.
+    def self.scientific(mantissa, exponent)
+      while !mantissa.zero? && (mantissa % 10).zero? && exponent < MAX_EXPONENT
+        mantissa /= 10
+        exponent += 1
+      end
+
+      "#{mantissa}e#{exponent}"
+    end
+
+    def scientific(mantissa, exponent)
+      self.class.scientific(mantissa, exponent)
+    end
+
+    # Plain decimal notation, built by padding the digits out far enough that
+    # the decimal point always lands inside the string.
+    def positional(mantissa, exponent)
+      pad_prefix = RANGE_LOG + 12
+      pad_suffix = RANGE_LOG + 8
+
+      raw = ('0' * pad_prefix) + mantissa.to_s + ('0' * pad_suffix)
+      offset = exponent + pad_prefix + RANGE_LOG + 1
+
+      integer = raw[0, offset].sub(/\A0+/, '')
+      integer = '0' if integer.empty?
+      fraction = raw[offset..].sub(/0+\z/, '')
+
+      fraction.empty? ? integer : "#{integer}.#{fraction}"
+    end
+
+    # Split a number string into an unnormalised mantissa and exponent.
+    def self.extract_parts(value)
+      match = NUMBER_PATTERN.match(value)
+      raise StandardError, "Unable to parse number from string: #{value}" unless match
+
+      sign, int_part, frac_part, exp_part = match.captures
+
+      digits = int_part.sub(/\A0+(?=.)/, '')
+      exponent = 0
+
+      unless frac_part.nil? || frac_part.empty?
+        digits += frac_part
+        exponent -= frac_part.length
+      end
+      exponent += exp_part.to_i unless exp_part.nil? || exp_part.empty?
+
+      while digits.length > 1 && digits.end_with?('0')
+        digits = digits[0..-2]
+        exponent += 1
+      end
+
+      mantissa = digits.to_i
+      mantissa = -mantissa if sign == '-'
+
+      [mantissa, exponent]
+    end
+
+    # Bring mantissa and exponent into the range rippled expects.
+    def self.normalize(mantissa, exponent)
+      return [0, DEFAULT_VALUE_EXPONENT] if mantissa.zero?
+
+      negative = mantissa.negative?
+      m = mantissa.abs
+
+      while m < MIN_MANTISSA && exponent > MIN_EXPONENT
+        exponent -= 1
+        m *= 10
+      end
+
+      last_digit = nil
+      while m > MAX_MANTISSA
+        raise StandardError, 'Mantissa and exponent are too large' if exponent >= MAX_EXPONENT
+
+        exponent += 1
+        last_digit = m % 10
+        m /= 10
+      end
+
+      raise StandardError, 'Underflow: value too small to represent' if exponent < MIN_EXPONENT || m < MIN_MANTISSA
+      raise StandardError, 'Exponent overflow: value too large to represent' if exponent > MAX_EXPONENT
+
+      if m > MAX_INT64
+        raise StandardError, 'Exponent overflow: value too large to represent' if exponent >= MAX_EXPONENT
+
+        exponent += 1
+        last_digit = m % 10
+        m /= 10
+      end
+
+      if last_digit && last_digit >= 5
+        m += 1
+
+        if m > MAX_INT64
+          raise StandardError, 'Exponent overflow: value too large to represent' if exponent >= MAX_EXPONENT
+
+          last_digit = m % 10
+          exponent += 1
+          m /= 10
+          m += 1 if last_digit >= 5
+        end
+      end
+
+      [negative ? -m : m, exponent]
+    end
+
+    # Big endian two's complement.
+    def self.pack_signed(value, byte_length)
+      value += 2**(byte_length * 8) if value.negative?
+
+      Array.new(byte_length) { |i| (value >> (8 * (byte_length - 1 - i))) & 0xFF }
+    end
+
+    def self.unpack_signed(bytes)
+      value = bytes.reduce(0) { |acc, b| (acc << 8) + b }
+      boundary = 2**(bytes.length * 8 - 1)
+
+      value >= boundary ? value - 2**(bytes.length * 8) : value
+    end
+  end
+end

data/lib/binary-codec/types/serialized_type.rb

@@ -99,8 +99,11 @@ module BinaryCodec
       when "UInt160" then Uint160
       when "UInt192" then Uint192
       when "UInt256" then Uint256
-      when "UInt384" then Uint384
-      when "UInt512" then Uint512
+      # The reference definitions call these Hash384/Hash512. The old UInt
+      # names are kept so a caller passing them still resolves.
+      when "Hash384", "UInt384" then Uint384
+      when "Hash512", "UInt512" then Uint512
+      when "Number" then Number
       when "Int32" then Int32
       when "Int64" then Int64
       when "PathSet" then PathSet

data/lib/binary-codec/types/st_array.rb

@@ -2,6 +2,8 @@
 
 module BinaryCodec
   class STArray < SerializedType
+    ARRAY_END_MARKER = 0xF1
+
     def initialize(byte_buf = nil)
       super(byte_buf || [])
     end
@@ -38,7 +40,7 @@ module BinaryCodec
             raise StandardError, "STArray item must be a Hash, got #{item.class}"
           end
         end
-        bytes.concat([0xF1]) # ArrayEndMarker
+        bytes.concat([ARRAY_END_MARKER])
         return STArray.new(bytes)
       end
 
@@ -53,7 +55,7 @@ module BinaryCodec
       bytes = []
       until parser.end?
         # Check if we reached the ArrayEndMarker (0xF1)
-        if parser.peek == 0xF1
+        if parser.peek == ARRAY_END_MARKER
           parser.read(1) # Consume 0xF1
           break
         end
@@ -70,6 +72,11 @@ module BinaryCodec
         bytes.concat(obj.to_bytes)
         bytes.concat([0xE1]) unless bytes.last == 0xE1
       end
+
+      # The ArrayEndMarker has to go back in. Without it the reconstructed
+      # bytes have no terminator, so re-parsing them - which is what to_json
+      # does - runs the array on into whatever field follows it.
+      bytes.concat([ARRAY_END_MARKER])
       STArray.new(bytes)
     end
 
@@ -82,23 +89,14 @@ module BinaryCodec
       parser = BinaryParser.new(to_hex)
       result = []
       until parser.end?
-        begin
-          # Check if we reached the ArrayEndMarker (0xF1) or if peek fails
-          break if parser.peek == 0xF1
-          
-          # Read field header of the array item (e.g., "Signer")
-          field_header = parser.read_field_header
-          field_name = definitions.get_field_name_from_header(field_header)
-          
-          # Read the STObject item
-          obj = STObject.from_parser(parser)
-          
-          # Array item in JSON is { "FieldName": { ... } }
-          item_json = obj.to_json(definitions)
-          result << { field_name => item_json.is_a?(String) ? JSON.parse(item_json) : item_json }
-        rescue => e
-          break
-        end
+        break if parser.peek == ARRAY_END_MARKER
+
+        # Each item is an STObject behind its own field header, e.g. "Signer".
+        field_header = parser.read_field_header
+        field_name = definitions.get_field_name_from_header(field_header)
+        obj = STObject.from_parser(parser)
+
+        result << { field_name => obj.to_json(definitions) }
       end
       result
     end

data/lib/binary-codec/types/st_object.rb

@@ -119,9 +119,14 @@ module BinaryCodec
       STObject.new(list.to_bytes)
     end
 
-    # Method to get the JSON interpretation of self.bytes
+    # The JSON interpretation of self.bytes.
     #
-    # @return [String] A stringified JSON object
+    # Returns a Hash, not a JSON string. It used to return a string, which
+    # forced every nested value to be serialised and parsed again on the way
+    # out - and that round trip is what turned native XRP amounts into
+    # integers, because JSON.parse("370000000") is a number.
+    #
+    # @return [Hash] The decoded object
     def to_json(_definitions = nil, _field_name = nil)
       definitions = _definitions || Definitions.instance
       parser = BinaryParser.new(to_hex)
@@ -129,7 +134,7 @@ module BinaryCodec
 
       until parser.end?
         begin
-          # Check if we are at the end marker (0xE1) or if peek fails
+          # Check if we are at the end marker (0xE1)
           break if parser.peek == 0xE1
           
           field = parser.read_field
@@ -142,21 +147,18 @@ module BinaryCodec
           else
             value_obj = parser.read_field_value(field)
             value = value_obj.to_json(definitions, field.name)
-            
-            # Re-parse if it's a nested structure to keep it as a Hash/Array in the accumulator
-            if field.type == 'STObject' || field.type == 'Amount' || field.type == 'STArray'
-              value = JSON.parse(value) if value.is_a?(String)
-            end
+
+            # Some types still hand back a serialised structure. Parse only
+            # what actually is one: an Amount for XRP is the string
+            # "370000000", and parsing that yields a number where rippled has
+            # a string.
+            value = JSON.parse(value) if value.is_a?(String) && value.start_with?('{', '[')
           end
           accumulator[field.name] = value
-        rescue => e
-          break
         end
       end
 
-      # Existing tests expect a JSON string for STObject#to_json
-      # To satisfy spec/binary-codec/types/st_object_spec.rb:10
-      JSON.generate(accumulator)
+      accumulator
     end
 
     private