@transia/ripple-binary-codec 1.4.6-alpha.9 → 2.5.1-quantum.0

package/src/types/st-array.ts

@@ -0,0 +1,113 @@
+import { DEFAULT_DEFINITIONS, XrplDefinitionsBase } from '../enums'
+import { SerializedType, JsonObject } from './serialized-type'
+import { STObject } from './st-object'
+import { BinaryParser } from '../serdes/binary-parser'
+import { concat } from '@transia/isomorphic/utils'
+
+const ARRAY_END_MARKER = Uint8Array.from([0xf1])
+const ARRAY_END_MARKER_NAME = 'ArrayEndMarker'
+
+const OBJECT_END_MARKER = Uint8Array.from([0xe1])
+
+/**
+ * TypeGuard for Array<JsonObject>
+ */
+function isObjects(args): args is Array<JsonObject> {
+  return (
+    Array.isArray(args) &&
+    args.every(
+      (arg) =>
+        typeof arg === 'object' &&
+        Object.keys(arg).length === 1 &&
+        typeof Object.values(arg)[0] === 'object',
+    )
+  )
+}
+
+/**
+ * Class for serializing and deserializing Arrays of Objects
+ */
+class STArray extends SerializedType {
+  /**
+   * Construct an STArray from a BinaryParser
+   *
+   * @param parser BinaryParser to parse an STArray from
+   * @returns An STArray Object
+   */
+  static fromParser(parser: BinaryParser): STArray {
+    const bytes: Array<Uint8Array> = []
+
+    while (!parser.end()) {
+      const field = parser.readField()
+      if (field.name === ARRAY_END_MARKER_NAME) {
+        break
+      }
+
+      bytes.push(
+        field.header,
+        parser.readFieldValue(field).toBytes(),
+        OBJECT_END_MARKER,
+      )
+    }
+
+    bytes.push(ARRAY_END_MARKER)
+    return new STArray(concat(bytes))
+  }
+
+  /**
+   * Construct an STArray from an Array of JSON Objects
+   *
+   * @param value STArray or Array of Objects to parse into an STArray
+   * @param definitions optional, types and values to use to encode/decode a transaction
+   * @returns An STArray object
+   */
+  static from<T extends STArray | Array<JsonObject>>(
+    value: T,
+    definitions: XrplDefinitionsBase = DEFAULT_DEFINITIONS,
+  ): STArray {
+    if (value instanceof STArray) {
+      return value
+    }
+
+    if (isObjects(value)) {
+      const bytes: Array<Uint8Array> = []
+      value.forEach((obj) => {
+        bytes.push(STObject.from(obj, undefined, definitions).toBytes())
+      })
+
+      bytes.push(ARRAY_END_MARKER)
+      return new STArray(concat(bytes))
+    }
+
+    throw new Error('Cannot construct STArray from value given')
+  }
+
+  /**
+   * Return the JSON representation of this.bytes
+   *
+   * @param definitions optional, types and values to use to encode/decode a transaction
+   * @returns An Array of JSON objects
+   */
+  toJSON(
+    definitions: XrplDefinitionsBase = DEFAULT_DEFINITIONS,
+  ): Array<JsonObject> {
+    const result: Array<JsonObject> = []
+
+    const arrayParser = new BinaryParser(this.toString(), definitions)
+
+    while (!arrayParser.end()) {
+      const field = arrayParser.readField()
+      if (field.name === ARRAY_END_MARKER_NAME) {
+        break
+      }
+
+      const outer = {}
+      outer[field.name] = STObject.fromParser(arrayParser).toJSON(definitions)
+      result.push(outer)
+    }
+
+    return result
+  }
+}
+
+export { STArray }

package/src/types/st-number.ts

@@ -0,0 +1,233 @@
+import { BinaryParser } from '../serdes/binary-parser'
+import { SerializedType } from './serialized-type'
+import { writeInt32BE, writeInt64BE, readInt32BE, readInt64BE } from '../utils'
+
+/**
+ * Constants for mantissa and exponent normalization per XRPL Number spec.
+ * These define allowed magnitude for mantissa and exponent after normalization.
+ */
+const MIN_MANTISSA = BigInt('1000000000000000')
+const MAX_MANTISSA = BigInt('9999999999999999')
+const MIN_EXPONENT = -32768
+const MAX_EXPONENT = 32768
+const DEFAULT_VALUE_EXPONENT = -2147483648
+
+/**
+ * Extract mantissa, exponent, and sign from a number string.
+ *
+ * @param val - The string representing the number (may be integer, decimal, or scientific notation).
+ * @returns Object containing mantissa (BigInt), exponent (number), and isNegative (boolean).
+ * @throws Error if the string cannot be parsed as a valid number.
+ *
+ * Examples:
+ *   '123'        -> { mantissa: 123n, exponent: 0, isNegative: false }
+ *   '-00123.45'  -> { mantissa: -12345n, exponent: -2, isNegative: true }
+ *   '+7.1e2'     -> { mantissa: 71n, exponent: -1 + 2 = 1, isNegative: false }
+ */
+function extractNumberPartsFromString(val: string): {
+  mantissa: bigint
+  exponent: number
+  isNegative: boolean
+} {
+  /**
+   * Regex for parsing decimal/float/scientific number strings with optional sign, integer, decimal, and exponent parts.
+   *
+   * Pattern: /^([-+]?)([0-9]+)(?:\.([0-9]+))?(?:[eE]([+-]?[0-9]+))?$/
+   *
+   * Breakdown:
+   *   1. ([-+]?)         - Optional '+' or '-' sign at the start.
+   *   2. ([0-9]+)        - Integer part: one or more digits (leading zeros allowed).
+   *   3. (?:\.([0-9]+))? - Optional decimal point followed by one or more digits.
+   *   4. (?:[eE]([+-]?[0-9]+))? - Optional exponent, starting with 'e' or 'E', optional sign, and digits.
+   *
+   * Notes:
+   *   - Leading zeros are accepted and normalized by code after parsing.
+   *   - Empty decimal ('123.') and missing integer ('.456') are NOT matched—must be fully specified.
+   */
+  const regex = /^([-+]?)([0-9]+)(?:\.([0-9]+))?(?:[eE]([+-]?[0-9]+))?$/
+  const match = regex.exec(val)
+  if (!match) throw new Error(`Unable to parse number from string: ${val}`)
+
+  const [, sign, intPart, fracPart, expPart] = match
+  // Remove leading zeros (unless the entire intPart is zeros)
+  const cleanIntPart = intPart.replace(/^0+(?=\d)/, '') || '0'
+
+  let mantissaStr = cleanIntPart
+  let exponent = 0
+
+  if (fracPart) {
+    mantissaStr += fracPart
+    exponent -= fracPart.length
+  }
+  if (expPart) exponent += parseInt(expPart, 10)
+
+  let mantissa = BigInt(mantissaStr)
+  if (sign === '-') mantissa = -mantissa
+  const isNegative = mantissa < BigInt(0)
+
+  return { mantissa, exponent, isNegative }
+}
+
+/**
+ * Normalize the mantissa and exponent to XRPL constraints.
+ *
+ * Ensures that after normalization, the mantissa is between MIN_MANTISSA and MAX_MANTISSA (unless zero).
+ * Adjusts the exponent as needed by shifting the mantissa left/right (multiplying/dividing by 10).
+ *
+ * @param mantissa - The unnormalized mantissa (BigInt).
+ * @param exponent - The unnormalized exponent (number).
+ * @returns An object with normalized mantissa and exponent.
+ * @throws Error if the number cannot be normalized within allowed exponent range.
+ */
+function normalize(
+  mantissa: bigint,
+  exponent: number,
+): { mantissa: bigint; exponent: number } {
+  let m = mantissa < BigInt(0) ? -mantissa : mantissa
+  const isNegative = mantissa < BigInt(0)
+
+  while (m !== BigInt(0) && m < MIN_MANTISSA && exponent > MIN_EXPONENT) {
+    exponent -= 1
+    m *= BigInt(10)
+  }
+  while (m > MAX_MANTISSA) {
+    if (exponent >= MAX_EXPONENT)
+      throw new Error('Mantissa and exponent are too large')
+    exponent += 1
+    m /= BigInt(10)
+  }
+  if (isNegative) m = -m
+  return { mantissa: m, exponent }
+}
+
+/**
+ * STNumber: Encodes XRPL's "Number" type.
+ *
+ * - Always encoded as 12 bytes: 8-byte signed mantissa, 4-byte signed exponent, both big-endian.
+ * - Can only be constructed from a valid number string or another STNumber instance.
+ *
+ * Usage:
+ *   STNumber.from("1.2345e5")
+ *   STNumber.from("-123")
+ *   STNumber.fromParser(parser)
+ */
+export class STNumber extends SerializedType {
+  /** 12 zero bytes, represents canonical zero. */
+  static defaultBytes = new Uint8Array(12)
+
+  /**
+   * Construct a STNumber from 12 bytes (8 for mantissa, 4 for exponent).
+   * @param bytes - 12-byte Uint8Array
+   * @throws Error if input is not a Uint8Array of length 12.
+   */
+  constructor(bytes?: Uint8Array) {
+    const used = bytes ?? STNumber.defaultBytes
+    if (!(used instanceof Uint8Array) || used.length !== 12) {
+      throw new Error(
+        `STNumber must be constructed from a 12-byte Uint8Array, got ${used?.length}`,
+      )
+    }
+    super(used)
+  }
+
+  /**
+   * Construct from a number string (or another STNumber).
+   *
+   * @param value - A string, or STNumber instance.
+   * @returns STNumber instance.
+   * @throws Error if not a string or STNumber.
+   */
+  static from(value: unknown): STNumber {
+    if (value instanceof STNumber) {
+      return value
+    }
+    if (typeof value === 'string') {
+      return STNumber.fromValue(value)
+    }
+    throw new Error(
+      'STNumber.from: Only string or STNumber instance is supported',
+    )
+  }
+
+  /**
+   * Construct from a number string (integer, decimal, or scientific notation).
+   * Handles normalization to XRPL Number constraints.
+   *
+   * @param val - The number as a string (e.g. '1.23', '-123e5').
+   * @returns STNumber instance
+   * @throws Error if val is not a valid number string.
+   */
+  static fromValue(val: string): STNumber {
+    const { mantissa, exponent, isNegative } = extractNumberPartsFromString(val)
+    let normalizedMantissa: bigint
+    let normalizedExponent: number
+
+    if (mantissa === BigInt(0) && exponent === 0 && !isNegative) {
+      normalizedMantissa = BigInt(0)
+      normalizedExponent = DEFAULT_VALUE_EXPONENT
+    } else {
+      ;({ mantissa: normalizedMantissa, exponent: normalizedExponent } =
+        normalize(mantissa, exponent))
+    }
+
+    const bytes = new Uint8Array(12)
+    writeInt64BE(bytes, normalizedMantissa, 0)
+    writeInt32BE(bytes, normalizedExponent, 8)
+    return new STNumber(bytes)
+  }
+
+  /**
+   * Read a STNumber from a BinaryParser stream (12 bytes).
+   * @param parser - BinaryParser positioned at the start of a number
+   * @returns STNumber instance
+   */
+  static fromParser(parser: BinaryParser): STNumber {
+    return new STNumber(parser.read(12))
+  }
+
+  /**
+   * Convert this STNumber to a normalized string representation.
+   * The output is decimal or scientific notation, depending on exponent range.
+   * Follows XRPL convention: zero is "0", other values are normalized to a canonical string.
+   *
+   * @returns String representation of the value
+   */
+  // eslint-disable-next-line complexity -- required
+  toJSON(): string {
+    const b = this.bytes
+    if (!b || b.length !== 12)
+      throw new Error('STNumber internal bytes not set or wrong length')
+
+    // Signed 64-bit mantissa
+    const mantissa = readInt64BE(b, 0)
+    // Signed 32-bit exponent
+    const exponent = readInt32BE(b, 8)
+
+    // Special zero: XRPL encodes canonical zero as mantissa=0, exponent=DEFAULT_VALUE_EXPONENT.
+    if (mantissa === BigInt(0) && exponent === DEFAULT_VALUE_EXPONENT) {
+      return '0'
+    }
+    if (exponent === 0) return mantissa.toString()
+
+    // Use scientific notation for small/large exponents, decimal otherwise
+    if (exponent < -25 || exponent > -5) {
+      return `${mantissa}e${exponent}`
+    }
+
+    // Decimal rendering for -25 <= exp <= -5
+    const isNegative = mantissa < BigInt(0)
+    const mantissaAbs = mantissa < BigInt(0) ? -mantissa : mantissa
+
+    const padPrefix = 27
+    const padSuffix = 23
+    const mantissaStr = mantissaAbs.toString()
+    const rawValue = '0'.repeat(padPrefix) + mantissaStr + '0'.repeat(padSuffix)
+    const OFFSET = exponent + 43
+    const integerPart = rawValue.slice(0, OFFSET).replace(/^0+/, '') || '0'
+    const fractionPart = rawValue.slice(OFFSET).replace(/0+$/, '')
+
+    return `${isNegative ? '-' : ''}${integerPart}${
+      fractionPart ? '.' + fractionPart : ''
+    }`
+  }
+}

package/src/types/st-object.ts

@@ -0,0 +1,215 @@
+import {
+  DEFAULT_DEFINITIONS,
+  FieldInstance,
+  Bytes,
+  XrplDefinitionsBase,
+} from '../enums'
+import { SerializedType, JsonObject } from './serialized-type'
+import {
+  xAddressToClassicAddress,
+  isValidXAddress,
+} from '@transia/ripple-address-codec'
+import { BinaryParser } from '../serdes/binary-parser'
+import { BinarySerializer, BytesList } from '../serdes/binary-serializer'
+
+import { STArray } from './st-array'
+import { UInt64 } from './uint-64'
+
+const OBJECT_END_MARKER_BYTE = Uint8Array.from([0xe1])
+const OBJECT_END_MARKER = 'ObjectEndMarker'
+const ST_OBJECT = 'STObject'
+const DESTINATION = 'Destination'
+const ACCOUNT = 'Account'
+const SOURCE_TAG = 'SourceTag'
+const DEST_TAG = 'DestinationTag'
+
+/**
+ * Break down an X-Address into an account and a tag
+ *
+ * @param field Name of field
+ * @param xAddress X-Address corresponding to the field
+ */
+function handleXAddress(field: string, xAddress: string): JsonObject {
+  const decoded = xAddressToClassicAddress(xAddress)
+
+  let tagName
+  if (field === DESTINATION) tagName = DEST_TAG
+  else if (field === ACCOUNT) tagName = SOURCE_TAG
+  else if (decoded.tag !== false)
+    throw new Error(`${field} cannot have an associated tag`)
+
+  return decoded.tag !== false
+    ? { [field]: decoded.classicAddress, [tagName]: decoded.tag }
+    : { [field]: decoded.classicAddress }
+}
+
+/**
+ * Validate that two objects don't both have the same tag fields
+ *
+ * @param obj1 First object to check for tags
+ * @param obj2 Second object to check for tags
+ * @throws When both objects have SourceTag or DestinationTag
+ */
+function checkForDuplicateTags(obj1: JsonObject, obj2: JsonObject): void {
+  if (!(obj1[SOURCE_TAG] === undefined || obj2[SOURCE_TAG] === undefined))
+    throw new Error('Cannot have Account X-Address and SourceTag')
+  if (!(obj1[DEST_TAG] === undefined || obj2[DEST_TAG] === undefined))
+    throw new Error('Cannot have Destination X-Address and DestinationTag')
+}
+
+/**
+ * Class for Serializing/Deserializing objects
+ */
+class STObject extends SerializedType {
+  /**
+   * Construct a STObject from a BinaryParser
+   *
+   * @param parser BinaryParser to read STObject from
+   * @returns A STObject object
+   */
+  static fromParser(parser: BinaryParser): STObject {
+    const list: BytesList = new BytesList()
+    const bytes: BinarySerializer = new BinarySerializer(list)
+
+    while (!parser.end()) {
+      const field = parser.readField()
+      if (field.name === OBJECT_END_MARKER) {
+        break
+      }
+
+      const associatedValue = parser.readFieldValue(field)
+
+      bytes.writeFieldAndValue(field, associatedValue)
+      if (field.type.name === ST_OBJECT) {
+        bytes.put(OBJECT_END_MARKER_BYTE)
+      }
+    }
+
+    return new STObject(list.toBytes())
+  }
+
+  /**
+   * Construct a STObject from a JSON object
+   *
+   * @param value An object to include
+   * @param filter optional, denote which field to include in serialized object
+   * @param definitions optional, types and values to use to encode/decode a transaction
+   * @returns a STObject object
+   */
+  static from<T extends STObject | JsonObject>(
+    value: T,
+    filter?: (...any) => boolean,
+    definitions: XrplDefinitionsBase = DEFAULT_DEFINITIONS,
+  ): STObject {
+    if (value instanceof STObject) {
+      return value
+    }
+
+    const list: BytesList = new BytesList()
+    const bytes: BinarySerializer = new BinarySerializer(list)
+
+    let isUnlModify = false
+
+    const xAddressDecoded = Object.entries(value).reduce((acc, [key, val]) => {
+      let handled: JsonObject | undefined = undefined
+      if (val && isValidXAddress(val.toString())) {
+        handled = handleXAddress(key, val.toString())
+        checkForDuplicateTags(handled, value)
+      }
+      return Object.assign(acc, handled ?? { [key]: val })
+    }, {})
+
+    function isValidFieldInstance(
+      f: FieldInstance | undefined,
+    ): f is FieldInstance {
+      return (
+        f !== undefined &&
+        xAddressDecoded[f.name] !== undefined &&
+        f.isSerialized
+      )
+    }
+
+    let sorted = Object.keys(xAddressDecoded)
+      .map((f: string): FieldInstance | undefined => {
+        if (!(f in definitions.field)) {
+          if (f[0] === f[0].toLowerCase()) return undefined
+          throw new Error(`Field ${f} is not defined in the definitions`)
+        }
+        return definitions.field[f] as FieldInstance
+      })
+      .filter(isValidFieldInstance)
+      .sort((a, b) => {
+        return a.ordinal - b.ordinal
+      })
+
+    if (filter !== undefined) {
+      sorted = sorted.filter(filter)
+    }
+
+    sorted.forEach((field) => {
+      const associatedValue =
+        field.type.name === ST_OBJECT
+          ? this.from(xAddressDecoded[field.name], undefined, definitions)
+          : field.type.name === 'STArray'
+          ? STArray.from(xAddressDecoded[field.name], definitions)
+          : field.type.name === 'UInt64'
+          ? UInt64.from(xAddressDecoded[field.name], field.name)
+          : field.associatedType?.from
+          ? field.associatedType.from(xAddressDecoded[field.name])
+          : (() => {
+              throw new Error(
+                `Type ${field.type.name} for field ${field.name} is missing associatedType.from`,
+              )
+            })()
+
+      if (associatedValue == undefined) {
+        throw new TypeError(
+          `Unable to interpret "${field.name}: ${
+            xAddressDecoded[field.name]
+          }".`,
+        )
+      }
+
+      if ((associatedValue as unknown as Bytes).name === 'UNLModify') {
+        // triggered when the TransactionType field has a value of 'UNLModify'
+        isUnlModify = true
+      }
+      // true when in the UNLModify pseudotransaction (after the transaction type has been processed) and working with the
+      // Account field
+      // The Account field must not be a part of the UNLModify pseudotransaction encoding, due to a bug in rippled
+      const isUnlModifyWorkaround = field.name == 'Account' && isUnlModify
+      bytes.writeFieldAndValue(field, associatedValue, isUnlModifyWorkaround)
+      if (field.type.name === ST_OBJECT) {
+        bytes.put(OBJECT_END_MARKER_BYTE)
+      }
+    })
+
+    return new STObject(list.toBytes())
+  }
+
+  /**
+   * Get the JSON interpretation of this.bytes
+   * @param definitions rippled definitions used to parse the values of transaction types and such.
+   *                          Can be customized for sidechains and amendments.
+   * @returns a JSON object
+   */
+  toJSON(definitions?: XrplDefinitionsBase): JsonObject {
+    const objectParser = new BinaryParser(this.toString(), definitions)
+    const accumulator = {}
+
+    while (!objectParser.end()) {
+      const field = objectParser.readField()
+      if (field.name === OBJECT_END_MARKER) {
+        break
+      }
+
+      accumulator[field.name] = objectParser
+        .readFieldValue(field)
+        .toJSON(definitions, field.name)
+    }
+
+    return accumulator
+  }
+}
+
+export { STObject }

package/src/types/uint-16.ts

@@ -0,0 +1,53 @@
+import { UInt } from './uint'
+import { BinaryParser } from '../serdes/binary-parser'
+import { readUInt16BE, writeUInt16BE } from '../utils'
+
+/**
+ * Derived UInt class for serializing/deserializing 16 bit UInt
+ */
+class UInt16 extends UInt {
+  protected static readonly width: number = 16 / 8 // 2
+  static readonly defaultUInt16: UInt16 = new UInt16(
+    new Uint8Array(UInt16.width),
+  )
+
+  constructor(bytes: Uint8Array) {
+    super(bytes ?? UInt16.defaultUInt16.bytes)
+  }
+
+  static fromParser(parser: BinaryParser): UInt {
+    return new UInt16(parser.read(UInt16.width))
+  }
+
+  /**
+   * Construct a UInt16 object from a number
+   *
+   * @param val UInt16 object or number
+   */
+  static from<T extends UInt16 | number>(val: T): UInt16 {
+    if (val instanceof UInt16) {
+      return val
+    }
+
+    if (typeof val === 'number') {
+      UInt16.checkUintRange(val, 0, 0xffff)
+
+      const buf = new Uint8Array(UInt16.width)
+      writeUInt16BE(buf, val, 0)
+      return new UInt16(buf)
+    }
+
+    throw new Error('Can not construct UInt16 with given value')
+  }
+
+  /**
+   * get the value of a UInt16 object
+   *
+   * @returns the number represented by this.bytes
+   */
+  valueOf(): number {
+    return parseInt(readUInt16BE(this.bytes, 0))
+  }
+}
+
+export { UInt16 }

package/src/types/uint-32.ts

@@ -0,0 +1,59 @@
+import { UInt } from './uint'
+import { BinaryParser } from '../serdes/binary-parser'
+import { readUInt32BE, writeUInt32BE } from '../utils'
+
+/**
+ * Derived UInt class for serializing/deserializing 32 bit UInt
+ */
+class UInt32 extends UInt {
+  protected static readonly width: number = 32 / 8 // 4
+  static readonly defaultUInt32: UInt32 = new UInt32(
+    new Uint8Array(UInt32.width),
+  )
+
+  constructor(bytes: Uint8Array) {
+    super(bytes ?? UInt32.defaultUInt32.bytes)
+  }
+
+  static fromParser(parser: BinaryParser): UInt {
+    return new UInt32(parser.read(UInt32.width))
+  }
+
+  /**
+   * Construct a UInt32 object from a number
+   *
+   * @param val UInt32 object or number
+   */
+  static from<T extends UInt32 | number | string>(val: T): UInt32 {
+    if (val instanceof UInt32) {
+      return val
+    }
+
+    const buf = new Uint8Array(UInt32.width)
+
+    if (typeof val === 'string') {
+      const num = Number.parseInt(val)
+      writeUInt32BE(buf, num, 0)
+      return new UInt32(buf)
+    }
+
+    if (typeof val === 'number') {
+      UInt32.checkUintRange(val, 0, 0xffffffff)
+      writeUInt32BE(buf, val, 0)
+      return new UInt32(buf)
+    }
+
+    throw new Error('Cannot construct UInt32 from given value')
+  }
+
+  /**
+   * get the value of a UInt32 object
+   *
+   * @returns the number represented by this.bytes
+   */
+  valueOf(): number {
+    return parseInt(readUInt32BE(this.bytes, 0), 10)
+  }
+}
+
+export { UInt32 }