Add missing field types to lending protocol related objects and support Int32 serialized type (#3198)

* WIP

* update history

* fix lint errors

* add Int32 type

* add encode decode test

* update history

* fix tests

* use typeName

* fix lint errors

Author: Patel-Raj11

packages/ripple-binary-codec/HISTORY.md

@@ -3,6 +3,7 @@
 ## Unreleased
 
 ### Fixed
+* Add `Int32` serialized type.
 * Fix STNumber serialization logic to work with large mantissa scale [10^18, 10^19-1].
 * Error if a decimal is passed into a `UInt`-typed field.
 

packages/ripple-binary-codec/src/types/index.ts

@@ -6,6 +6,7 @@ import { Hash128 } from './hash-128'
 import { Hash160 } from './hash-160'
 import { Hash192 } from './hash-192'
 import { Hash256 } from './hash-256'
+import { Int32 } from './int-32'
 import { Issue } from './issue'
 import { STNumber } from './st-number'
 import { PathSet } from './path-set'
@@ -29,6 +30,7 @@ const coreTypes: Record<string, typeof SerializedType> = {
   Hash160,
   Hash192,
   Hash256,
+  Int32,
   Issue,
   Number: STNumber,
   PathSet,
@@ -57,6 +59,7 @@ export {
   Hash160,
   Hash192,
   Hash256,
+  Int32,
   PathSet,
   STArray,
   STObject,

packages/ripple-binary-codec/src/types/int-32.ts

@@ -0,0 +1,72 @@
+import { Int } from './int'
+import { BinaryParser } from '../serdes/binary-parser'
+import { readInt32BE, writeInt32BE } from '../utils'
+
+/**
+ * Derived Int class for serializing/deserializing signed 32-bit integers.
+ */
+class Int32 extends Int {
+  protected static readonly width: number = 32 / 8 // 4 bytes
+  static readonly defaultInt32: Int32 = new Int32(new Uint8Array(Int32.width))
+
+  // Signed 32-bit integer range
+  static readonly MIN_VALUE: number = -2147483648 // -2^31
+  static readonly MAX_VALUE: number = 2147483647 // 2^31 - 1
+
+  constructor(bytes: Uint8Array) {
+    super(bytes ?? Int32.defaultInt32.bytes)
+  }
+
+  /**
+   * Construct an Int32 from a BinaryParser
+   *
+   * @param parser BinaryParser to read Int32 from
+   * @returns An Int32 object
+   */
+  static fromParser(parser: BinaryParser): Int {
+    return new Int32(parser.read(Int32.width))
+  }
+
+  /**
+   * Construct an Int32 object from a number or string
+   *
+   * @param val Int32 object, number, or string
+   * @returns An Int32 object
+   */
+  static from<T extends Int32 | number | string>(val: T): Int32 {
+    if (val instanceof Int32) {
+      return val
+    }
+
+    const buf = new Uint8Array(Int32.width)
+
+    if (typeof val === 'string') {
+      const num = Number(val)
+      if (!Number.isFinite(num) || !Number.isInteger(num)) {
+        throw new Error(`Cannot construct Int32 from string: ${val}`)
+      }
+      Int32.checkIntRange('Int32', num, Int32.MIN_VALUE, Int32.MAX_VALUE)
+      writeInt32BE(buf, num, 0)
+      return new Int32(buf)
+    }
+
+    if (typeof val === 'number' && Number.isInteger(val)) {
+      Int32.checkIntRange('Int32', val, Int32.MIN_VALUE, Int32.MAX_VALUE)
+      writeInt32BE(buf, val, 0)
+      return new Int32(buf)
+    }
+
+    throw new Error('Cannot construct Int32 from given value')
+  }
+
+  /**
+   * Get the value of the Int32 object
+   *
+   * @returns the signed 32-bit integer represented by this.bytes
+   */
+  valueOf(): number {
+    return readInt32BE(this.bytes, 0)
+  }
+}
+
+export { Int32 }

packages/ripple-binary-codec/src/types/int.ts

@@ -0,0 +1,75 @@
+import { Comparable } from './serialized-type'
+
+/**
+ * Compare numbers and bigInts n1 and n2
+ *
+ * @param n1 First object to compare
+ * @param n2 Second object to compare
+ * @returns -1, 0, or 1, depending on how the two objects compare
+ */
+function compare(n1: number | bigint, n2: number | bigint): number {
+  return n1 < n2 ? -1 : n1 == n2 ? 0 : 1
+}
+
+/**
+ * Base class for serializing and deserializing signed integers.
+ */
+abstract class Int extends Comparable<Int | number> {
+  protected static width: number
+
+  constructor(bytes: Uint8Array) {
+    super(bytes)
+  }
+
+  /**
+   * Overload of compareTo for Comparable
+   *
+   * @param other other Int to compare this to
+   * @returns -1, 0, or 1 depending on how the objects relate to each other
+   */
+  compareTo(other: Int | number): number {
+    return compare(this.valueOf(), other.valueOf())
+  }
+
+  /**
+   * Convert an Int object to JSON
+   *
+   * @returns number or string represented by this.bytes
+   */
+  toJSON(): number | string {
+    const val = this.valueOf()
+    return typeof val === 'number' ? val : val.toString()
+  }
+
+  /**
+   * Get the value of the Int represented by this.bytes
+   *
+   * @returns the value
+   */
+  abstract valueOf(): number | bigint
+
+  /**
+   * Validate that a number is within the specified signed integer range
+   *
+   * @param typeName The name of the type (for error messages)
+   * @param val The number to validate
+   * @param min The minimum allowed value
+   * @param max The maximum allowed value
+   * @throws Error if the value is out of range
+   */
+  // eslint-disable-next-line max-params -- for error clarity in browsers
+  static checkIntRange(
+    typeName: string,
+    val: number | bigint,
+    min: number | bigint,
+    max: number | bigint,
+  ): void {
+    if (val < min || val > max) {
+      throw new Error(
+        `Invalid ${typeName}: ${val} must be >= ${min} and <= ${max}`,
+      )
+    }
+  }
+}
+
+export { Int }

packages/ripple-binary-codec/test/int.test.ts

@@ -0,0 +1,203 @@
+import { Int32 } from '../src/types'
+import { encode, decode } from '../src'
+
+describe('Int32', () => {
+  describe('from()', () => {
+    it('should create Int32 from positive number', () => {
+      const int32 = Int32.from(12345)
+      expect(int32.valueOf()).toBe(12345)
+    })
+
+    it('should create Int32 from negative number', () => {
+      const int32 = Int32.from(-12345)
+      expect(int32.valueOf()).toBe(-12345)
+    })
+
+    it('should create Int32 from zero', () => {
+      const int32 = Int32.from(0)
+      expect(int32.valueOf()).toBe(0)
+    })
+
+    it('should create Int32 from positive string', () => {
+      const int32 = Int32.from('67890')
+      expect(int32.valueOf()).toBe(67890)
+    })
+
+    it('should create Int32 from negative string', () => {
+      const int32 = Int32.from('-67890')
+      expect(int32.valueOf()).toBe(-67890)
+    })
+
+    it('should create Int32 from another Int32', () => {
+      const original = Int32.from(999)
+      const copy = Int32.from(original)
+      expect(copy.valueOf()).toBe(999)
+    })
+
+    it('should handle MIN_VALUE', () => {
+      const int32 = Int32.from(-2147483648)
+      expect(int32.valueOf()).toBe(-2147483648)
+    })
+
+    it('should handle MAX_VALUE', () => {
+      const int32 = Int32.from(2147483647)
+      expect(int32.valueOf()).toBe(2147483647)
+    })
+  })
+
+  describe('range validation', () => {
+    it('should throw error when value exceeds MAX_VALUE', () => {
+      expect(() => Int32.from(2147483648)).toThrow(
+        new Error(
+          'Invalid Int32: 2147483648 must be >= -2147483648 and <= 2147483647',
+        ),
+      )
+    })
+
+    it('should throw error when value is below MIN_VALUE', () => {
+      expect(() => Int32.from(-2147483649)).toThrow(
+        new Error(
+          'Invalid Int32: -2147483649 must be >= -2147483648 and <= 2147483647',
+        ),
+      )
+    })
+
+    it('should throw error for string exceeding MAX_VALUE', () => {
+      expect(() => Int32.from('2147483648')).toThrow(
+        new Error(
+          'Invalid Int32: 2147483648 must be >= -2147483648 and <= 2147483647',
+        ),
+      )
+    })
+
+    it('should throw error for string below MIN_VALUE', () => {
+      expect(() => Int32.from('-2147483649')).toThrow(
+        new Error(
+          'Invalid Int32: -2147483649 must be >= -2147483648 and <= 2147483647',
+        ),
+      )
+    })
+  })
+
+  describe('decimal validation', () => {
+    it('should throw error when passed a decimal number', () => {
+      expect(() => Int32.from(100.5)).toThrow(
+        new Error('Cannot construct Int32 from given value'),
+      )
+    })
+
+    it('should throw error when passed a negative decimal', () => {
+      expect(() => Int32.from(-100.5)).toThrow(
+        new Error('Cannot construct Int32 from given value'),
+      )
+    })
+
+    it('should throw error when passed a small decimal', () => {
+      expect(() => Int32.from(0.001)).toThrow(
+        new Error('Cannot construct Int32 from given value'),
+      )
+    })
+
+    it('should throw error for decimal string', () => {
+      expect(() => Int32.from('1.23')).toThrow(
+        new Error('Cannot construct Int32 from string: 1.23'),
+      )
+    })
+
+    it('should throw error for non-numeric string', () => {
+      expect(() => Int32.from('abc')).toThrow(
+        new Error('Cannot construct Int32 from string: abc'),
+      )
+    })
+  })
+
+  describe('compareTo()', () => {
+    it('should return 0 for equal values', () => {
+      expect(Int32.from(100).compareTo(Int32.from(100))).toBe(0)
+    })
+
+    it('should return 1 when first value is greater', () => {
+      expect(Int32.from(100).compareTo(Int32.from(50))).toBe(1)
+    })
+
+    it('should return -1 when first value is smaller', () => {
+      expect(Int32.from(50).compareTo(Int32.from(100))).toBe(-1)
+    })
+
+    it('should compare with raw number', () => {
+      expect(Int32.from(100).compareTo(100)).toBe(0)
+      expect(Int32.from(100).compareTo(50)).toBe(1)
+      expect(Int32.from(50).compareTo(100)).toBe(-1)
+    })
+
+    it('should handle negative values', () => {
+      expect(Int32.from(-100).compareTo(Int32.from(-50))).toBe(-1)
+      expect(Int32.from(-50).compareTo(Int32.from(-100))).toBe(1)
+      expect(Int32.from(-100).compareTo(Int32.from(-100))).toBe(0)
+    })
+
+    it('should compare negative and positive values', () => {
+      expect(Int32.from(-100).compareTo(Int32.from(100))).toBe(-1)
+      expect(Int32.from(100).compareTo(Int32.from(-100))).toBe(1)
+    })
+  })
+
+  describe('toJSON()', () => {
+    it('should return number for positive value', () => {
+      expect(Int32.from(12345).toJSON()).toBe(12345)
+    })
+
+    it('should return number for negative value', () => {
+      expect(Int32.from(-12345).toJSON()).toBe(-12345)
+    })
+
+    it('should return 0 for zero', () => {
+      expect(Int32.from(0).toJSON()).toBe(0)
+    })
+  })
+
+  describe('valueOf()', () => {
+    it('should allow bitwise operations', () => {
+      const val = Int32.from(5)
+      expect(val.valueOf() | 0x2).toBe(7)
+    })
+
+    it('should handle negative values in bitwise operations', () => {
+      const val = Int32.from(-1)
+      expect(val.valueOf() & 0xff).toBe(255)
+    })
+  })
+
+  describe('encode/decode with Loan ledger entry', () => {
+    // Loan object from Devnet with LoanScale field
+    const loanWithScale = {
+      Borrower: 'rs5fUokF7Y5bxNkstM4p4JYHgqzYkFamCg',
+      GracePeriod: 60,
+      LoanBrokerID:
+        '18F91BD8009DAF09B5E4663BE7A395F5F193D0657B12F8D1E781EB3D449E8151',
+      LoanScale: -11,
+      LoanSequence: 1,
+      NextPaymentDueDate: 822779431,
+      PaymentInterval: 400,
+      PaymentRemaining: 1,
+      PeriodicPayment: '10000',
+      PrincipalOutstanding: '10000',
+      StartDate: 822779031,
+      TotalValueOutstanding: '10000',
+      LedgerEntryType: 'Loan',
+    }
+
+    it('can encode and decode Loan with negative LoanScale', () => {
+      const encoded = encode(loanWithScale)
+      const decoded = decode(encoded)
+      expect(decoded).toEqual(loanWithScale)
+    })
+
+    it('can encode and decode Loan with positive LoanScale', () => {
+      const loan = { ...loanWithScale, LoanScale: 5 }
+      const encoded = encode(loan)
+      const decoded = decode(encoded)
+      expect(decoded).toEqual(loan)
+    })
+  })
+})

packages/xrpl/HISTORY.md

@@ -7,6 +7,7 @@ Subscribe to [the **xrpl-announce** mailing list](https://groups.google.com/g/xr
 ### Added
 * Add `faucetProtocol` (http or https) option to `fundWallet` method. Makes `fundWallet` work with locally running faucet servers.
 * Add `signLoanSetByCounterparty` and `combineLoanSetCounterpartySigners` helper functions to sign and combine LoanSet transactions signed by the counterparty.
+* Add newly added fields to `Loan`, `LoanBroker` and `Vault` ledger objects and lending protocol related transaction types.
 
 ## 4.5.0 (2025-12-16)