ripple-binary-codec 1.7.1 → 1.9.0

package/src/types/serialized-type.ts

@@ -0,0 +1,120 @@
+import { BytesList } from '../serdes/binary-serializer'
+import { BinaryParser } from '../serdes/binary-parser'
+import bigInt = require('big-integer')
+import { Buffer } from 'buffer/'
+import { XrplDefinitionsBase } from '../enums'
+
+type JSON = string | number | boolean | null | undefined | JSON[] | JsonObject
+
+type JsonObject = { [key: string]: JSON }
+
+/**
+ * The base class for all binary-codec types
+ */
+class SerializedType {
+  protected readonly bytes: Buffer = Buffer.alloc(0)
+
+  constructor(bytes: Buffer) {
+    this.bytes = bytes ?? Buffer.alloc(0)
+  }
+
+  static fromParser(parser: BinaryParser, hint?: number): SerializedType {
+    throw new Error('fromParser not implemented')
+    return this.fromParser(parser, hint)
+  }
+
+  static from(
+    value: SerializedType | JSON | bigInt.BigInteger,
+  ): SerializedType {
+    throw new Error('from not implemented')
+    return this.from(value)
+  }
+
+  /**
+   * Write the bytes representation of a SerializedType to a BytesList
+   *
+   * @param list The BytesList to write SerializedType bytes to
+   */
+  toBytesSink(list: BytesList): void {
+    list.put(this.bytes)
+  }
+
+  /**
+   * Get the hex representation of a SerializedType's bytes
+   *
+   * @returns hex String of this.bytes
+   */
+  toHex(): string {
+    return this.toBytes().toString('hex').toUpperCase()
+  }
+
+  /**
+   * Get the bytes representation of a SerializedType
+   *
+   * @returns A buffer of the bytes
+   */
+  toBytes(): Buffer {
+    if (this.bytes) {
+      return this.bytes
+    }
+    const bytes = new BytesList()
+    this.toBytesSink(bytes)
+    return bytes.toBytes()
+  }
+
+  /**
+   * Return the JSON representation of a SerializedType
+   *
+   * @param _definitions rippled definitions used to parse the values of transaction types and such.
+   *                          Unused in default, but used in STObject, STArray
+   *                          Can be customized for sidechains and amendments.
+   * @returns any type, if not overloaded returns hexString representation of bytes
+   */
+  toJSON(_definitions?: XrplDefinitionsBase): JSON {
+    return this.toHex()
+  }
+
+  /**
+   * @returns hexString representation of this.bytes
+   */
+  toString(): string {
+    return this.toHex()
+  }
+}
+
+/**
+ * Base class for SerializedTypes that are comparable
+ */
+class Comparable extends SerializedType {
+  lt(other: Comparable): boolean {
+    return this.compareTo(other) < 0
+  }
+
+  eq(other: Comparable): boolean {
+    return this.compareTo(other) === 0
+  }
+
+  gt(other: Comparable): boolean {
+    return this.compareTo(other) > 0
+  }
+
+  gte(other: Comparable): boolean {
+    return this.compareTo(other) > -1
+  }
+
+  lte(other: Comparable): boolean {
+    return this.compareTo(other) < 1
+  }
+
+  /**
+   * Overload this method to define how two Comparable SerializedTypes are compared
+   *
+   * @param other The comparable object to compare this to
+   * @returns A number denoting the relationship of this and other
+   */
+  compareTo(other: Comparable): number {
+    throw new Error(`cannot compare ${this.toString()} and ${other.toString()}`)
+  }
+}
+
+export { SerializedType, Comparable, JSON, JsonObject }

package/src/types/st-array.ts

@@ -0,0 +1,107 @@
+import { DEFAULT_DEFINITIONS, XrplDefinitionsBase } from '../enums'
+import { SerializedType, JsonObject } from './serialized-type'
+import { STObject } from './st-object'
+import { BinaryParser } from '../serdes/binary-parser'
+import { Buffer } from 'buffer/'
+
+const ARRAY_END_MARKER = Buffer.from([0xf1])
+const ARRAY_END_MARKER_NAME = 'ArrayEndMarker'
+
+const OBJECT_END_MARKER = Buffer.from([0xe1])
+
+/**
+ * TypeGuard for Array<JsonObject>
+ */
+function isObjects(args): args is Array<JsonObject> {
+  return (
+    Array.isArray(args) && (args.length === 0 || typeof args[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<Buffer> = []
+
+    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(Buffer.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<Buffer> = []
+      value.forEach((obj) => {
+        bytes.push(STObject.from(obj, undefined, definitions).toBytes())
+      })
+
+      bytes.push(ARRAY_END_MARKER)
+      return new STArray(Buffer.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-object.ts

@@ -0,0 +1,192 @@
+import {
+  DEFAULT_DEFINITIONS,
+  FieldInstance,
+  Bytes,
+  XrplDefinitionsBase,
+} from '../enums'
+import { SerializedType, JsonObject } from './serialized-type'
+import { xAddressToClassicAddress, isValidXAddress } from 'ripple-address-codec'
+import { BinaryParser } from '../serdes/binary-parser'
+import { BinarySerializer, BytesList } from '../serdes/binary-serializer'
+import { Buffer } from 'buffer/'
+import { STArray } from './st-array'
+
+const OBJECT_END_MARKER_BYTE = Buffer.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 })
+    }, {})
+
+    let sorted = Object.keys(xAddressDecoded)
+      .map((f: string): FieldInstance => definitions.field[f] as FieldInstance)
+      .filter(
+        (f: FieldInstance): boolean =>
+          f !== undefined &&
+          xAddressDecoded[f.name] !== undefined &&
+          f.isSerialized,
+      )
+      .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.associatedType.from(xAddressDecoded[field.name])
+
+      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)
+    }
+
+    return accumulator
+  }
+}
+
+export { STObject }

package/src/types/uint-16.ts

@@ -0,0 +1,49 @@
+import { UInt } from './uint'
+import { BinaryParser } from '../serdes/binary-parser'
+import { Buffer } from 'buffer/'
+
+/**
+ * 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(Buffer.alloc(UInt16.width))
+
+  constructor(bytes: Buffer) {
+    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') {
+      const buf = Buffer.alloc(UInt16.width)
+      buf.writeUInt16BE(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 this.bytes.readUInt16BE(0)
+  }
+}
+
+export { UInt16 }

package/src/types/uint-32.ts

@@ -0,0 +1,56 @@
+import { UInt } from './uint'
+import { BinaryParser } from '../serdes/binary-parser'
+import { Buffer } from 'buffer/'
+
+/**
+ * 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(Buffer.alloc(UInt32.width))
+
+  constructor(bytes: Buffer) {
+    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 = Buffer.alloc(UInt32.width)
+
+    if (typeof val === 'string') {
+      const num = Number.parseInt(val)
+      buf.writeUInt32BE(num, 0)
+      return new UInt32(buf)
+    }
+
+    if (typeof val === 'number') {
+      buf.writeUInt32BE(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 this.bytes.readUInt32BE(0)
+  }
+}
+
+export { UInt32 }

package/src/types/uint-64.ts

@@ -0,0 +1,105 @@
+import { UInt } from './uint'
+import { BinaryParser } from '../serdes/binary-parser'
+import bigInt = require('big-integer')
+import { isInstance } from 'big-integer'
+import { Buffer } from 'buffer/'
+
+const HEX_REGEX = /^[a-fA-F0-9]{1,16}$/
+const mask = bigInt(0x00000000ffffffff)
+
+/**
+ * Derived UInt class for serializing/deserializing 64 bit UInt
+ */
+class UInt64 extends UInt {
+  protected static readonly width: number = 64 / 8 // 8
+  static readonly defaultUInt64: UInt64 = new UInt64(Buffer.alloc(UInt64.width))
+
+  constructor(bytes: Buffer) {
+    super(bytes ?? UInt64.defaultUInt64.bytes)
+  }
+
+  static fromParser(parser: BinaryParser): UInt {
+    return new UInt64(parser.read(UInt64.width))
+  }
+
+  /**
+   * Construct a UInt64 object
+   *
+   * @param val A UInt64, hex-string, bigInt, or number
+   * @returns A UInt64 object
+   */
+  static from<T extends UInt64 | string | bigInt.BigInteger | number>(
+    val: T,
+  ): UInt64 {
+    if (val instanceof UInt64) {
+      return val
+    }
+
+    let buf = Buffer.alloc(UInt64.width)
+
+    if (typeof val === 'number') {
+      if (val < 0) {
+        throw new Error('value must be an unsigned integer')
+      }
+
+      const number = bigInt(val)
+
+      const intBuf = [Buffer.alloc(4), Buffer.alloc(4)]
+      intBuf[0].writeUInt32BE(Number(number.shiftRight(32)), 0)
+      intBuf[1].writeUInt32BE(Number(number.and(mask)), 0)
+
+      return new UInt64(Buffer.concat(intBuf))
+    }
+
+    if (typeof val === 'string') {
+      if (!HEX_REGEX.test(val)) {
+        throw new Error(`${val} is not a valid hex-string`)
+      }
+
+      const strBuf = val.padStart(16, '0')
+      buf = Buffer.from(strBuf, 'hex')
+      return new UInt64(buf)
+    }
+
+    if (isInstance(val)) {
+      const intBuf = [Buffer.alloc(4), Buffer.alloc(4)]
+      intBuf[0].writeUInt32BE(Number(val.shiftRight(bigInt(32))), 0)
+      intBuf[1].writeUInt32BE(Number(val.and(mask)), 0)
+
+      return new UInt64(Buffer.concat(intBuf))
+    }
+
+    throw new Error('Cannot construct UInt64 from given value')
+  }
+
+  /**
+   * The JSON representation of a UInt64 object
+   *
+   * @returns a hex-string
+   */
+  toJSON(): string {
+    return this.bytes.toString('hex').toUpperCase()
+  }
+
+  /**
+   * Get the value of the UInt64
+   *
+   * @returns the number represented buy this.bytes
+   */
+  valueOf(): bigInt.BigInteger {
+    const msb = bigInt(this.bytes.slice(0, 4).readUInt32BE(0))
+    const lsb = bigInt(this.bytes.slice(4).readUInt32BE(0))
+    return msb.shiftLeft(bigInt(32)).or(lsb)
+  }
+
+  /**
+   * Get the bytes representation of the UInt64 object
+   *
+   * @returns 8 bytes representing the UInt64
+   */
+  toBytes(): Buffer {
+    return this.bytes
+  }
+}
+
+export { UInt64 }

package/src/types/uint-8.ts

@@ -0,0 +1,49 @@
+import { UInt } from './uint'
+import { BinaryParser } from '../serdes/binary-parser'
+import { Buffer } from 'buffer/'
+
+/**
+ * Derived UInt class for serializing/deserializing 8 bit UInt
+ */
+class UInt8 extends UInt {
+  protected static readonly width: number = 8 / 8 // 1
+  static readonly defaultUInt8: UInt8 = new UInt8(Buffer.alloc(UInt8.width))
+
+  constructor(bytes: Buffer) {
+    super(bytes ?? UInt8.defaultUInt8.bytes)
+  }
+
+  static fromParser(parser: BinaryParser): UInt {
+    return new UInt8(parser.read(UInt8.width))
+  }
+
+  /**
+   * Construct a UInt8 object from a number
+   *
+   * @param val UInt8 object or number
+   */
+  static from<T extends UInt8 | number>(val: T): UInt8 {
+    if (val instanceof UInt8) {
+      return val
+    }
+
+    if (typeof val === 'number') {
+      const buf = Buffer.alloc(UInt8.width)
+      buf.writeUInt8(val, 0)
+      return new UInt8(buf)
+    }
+
+    throw new Error('Cannot construct UInt8 from given value')
+  }
+
+  /**
+   * get the value of a UInt8 object
+   *
+   * @returns the number represented by this.bytes
+   */
+  valueOf(): number {
+    return this.bytes.readUInt8(0)
+  }
+}
+
+export { UInt8 }