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

package/src/types/uint-64.ts

@@ -0,0 +1,135 @@
+import { UInt } from './uint'
+import { BinaryParser } from '../serdes/binary-parser'
+import { bytesToHex, concat, hexToBytes } from '@transia/isomorphic/utils'
+import { readUInt32BE, writeUInt32BE } from '../utils'
+import { DEFAULT_DEFINITIONS, XrplDefinitionsBase } from '../enums'
+
+const HEX_REGEX = /^[a-fA-F0-9]{1,16}$/
+const BASE10_REGEX = /^[0-9]{1,20}$/
+const mask = BigInt(0x00000000ffffffff)
+
+const BASE10_AMOUNT_FIELDS = new Set([
+  'MaximumAmount',
+  'OutstandingAmount',
+  'MPTAmount',
+  'LockedAmount',
+])
+
+function isBase10(fieldName: string): boolean {
+  return BASE10_AMOUNT_FIELDS.has(fieldName)
+}
+
+/**
+ * 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(
+    new Uint8Array(UInt64.width),
+  )
+
+  constructor(bytes: Uint8Array) {
+    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 | number>(
+    val: T,
+    fieldName = '',
+  ): UInt64 {
+    if (val instanceof UInt64) {
+      return val
+    }
+
+    let buf = new Uint8Array(UInt64.width)
+
+    if (typeof val === 'number') {
+      if (val < 0) {
+        throw new Error('value must be an unsigned integer')
+      }
+
+      const number = BigInt(val)
+
+      const intBuf = [new Uint8Array(4), new Uint8Array(4)]
+      writeUInt32BE(intBuf[0], Number(number >> BigInt(32)), 0)
+      writeUInt32BE(intBuf[1], Number(number & BigInt(mask)), 0)
+
+      return new UInt64(concat(intBuf))
+    }
+
+    if (typeof val === 'string') {
+      if (isBase10(fieldName)) {
+        if (!BASE10_REGEX.test(val)) {
+          throw new Error(`${fieldName} ${val} is not a valid base 10 string`)
+        }
+        val = BigInt(val).toString(16) as T
+      }
+
+      if (typeof val === 'string' && !HEX_REGEX.test(val)) {
+        throw new Error(`${val} is not a valid hex-string`)
+      }
+
+      const strBuf = (val as string).padStart(16, '0')
+      buf = hexToBytes(strBuf)
+      return new UInt64(buf)
+    }
+
+    if (typeof val === 'bigint') {
+      const intBuf = [new Uint8Array(4), new Uint8Array(4)]
+      writeUInt32BE(intBuf[0], Number(Number(val >> BigInt(32))), 0)
+      writeUInt32BE(intBuf[1], Number(val & BigInt(mask)), 0)
+
+      return new UInt64(concat(intBuf))
+    }
+
+    throw new Error('Cannot construct UInt64 from given value')
+  }
+
+  /**
+   * The JSON representation of a UInt64 object
+   *
+   * @returns a hex-string
+   */
+  toJSON(
+    _definitions: XrplDefinitionsBase = DEFAULT_DEFINITIONS,
+    fieldName = '',
+  ): string {
+    const hexString = bytesToHex(this.bytes)
+    if (isBase10(fieldName)) {
+      return BigInt('0x' + hexString).toString(10)
+    }
+
+    return hexString
+  }
+
+  /**
+   * Get the value of the UInt64
+   *
+   * @returns the number represented buy this.bytes
+   */
+  valueOf(): bigint {
+    const msb = BigInt(readUInt32BE(this.bytes.slice(0, 4), 0))
+    const lsb = BigInt(readUInt32BE(this.bytes.slice(4), 0))
+    return (msb << BigInt(32)) | lsb
+  }
+
+  /**
+   * Get the bytes representation of the UInt64 object
+   *
+   * @returns 8 bytes representing the UInt64
+   */
+  toBytes(): Uint8Array {
+    return this.bytes
+  }
+}
+
+export { UInt64 }

package/src/types/uint-8.ts

@@ -0,0 +1,52 @@
+import { UInt } from './uint'
+import { BinaryParser } from '../serdes/binary-parser'
+import { bytesToHex } from '@transia/isomorphic/utils'
+import { writeUInt8 } from '../utils'
+
+/**
+ * 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(new Uint8Array(UInt8.width))
+
+  constructor(bytes: Uint8Array) {
+    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') {
+      UInt8.checkUintRange(val, 0, 0xff)
+
+      const buf = new Uint8Array(UInt8.width)
+      writeUInt8(buf, 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 parseInt(bytesToHex(this.bytes), 16)
+  }
+}
+
+export { UInt8 }

package/src/types/uint.ts

@@ -0,0 +1,60 @@
+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 unsigned integers.
+ */
+abstract class UInt extends Comparable<UInt | number> {
+  protected static width: number
+
+  constructor(bytes: Uint8Array) {
+    super(bytes)
+  }
+
+  /**
+   * Overload of compareTo for Comparable
+   *
+   * @param other other UInt to compare this to
+   * @returns -1, 0, or 1 depending on how the objects relate to each other
+   */
+  compareTo(other: UInt | number): number {
+    return compare(this.valueOf(), other.valueOf())
+  }
+
+  /**
+   * Convert a UInt 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 UInt represented by this.bytes
+   *
+   * @returns the value
+   */
+  abstract valueOf(): number | bigint
+
+  static checkUintRange(val: number, min: number, max: number): void {
+    if (val < min || val > max) {
+      throw new Error(
+        `Invalid ${this.constructor.name}: ${val} must be >= ${min} and <= ${max}`,
+      )
+    }
+  }
+}
+
+export { UInt }

package/src/types/vector-256.ts

@@ -0,0 +1,79 @@
+import { SerializedType } from './serialized-type'
+import { BinaryParser } from '../serdes/binary-parser'
+import { Hash256 } from './hash-256'
+import { BytesList } from '../serdes/binary-serializer'
+import { bytesToHex } from '@transia/isomorphic/utils'
+
+/**
+ * TypeGuard for Array<string>
+ */
+function isStrings(arg): arg is Array<string> {
+  return Array.isArray(arg) && (arg.length === 0 || typeof arg[0] === 'string')
+}
+
+/**
+ * Class for serializing and deserializing vectors of Hash256
+ */
+class Vector256 extends SerializedType {
+  constructor(bytes: Uint8Array) {
+    super(bytes)
+  }
+
+  /**
+   * Construct a Vector256 from a BinaryParser
+   *
+   * @param parser BinaryParser to
+   * @param hint length of the vector, in bytes, optional
+   * @returns a Vector256 object
+   */
+  static fromParser(parser: BinaryParser, hint?: number): Vector256 {
+    const bytesList = new BytesList()
+    const bytes = hint ?? parser.size()
+    const hashes = bytes / 32
+    for (let i = 0; i < hashes; i++) {
+      Hash256.fromParser(parser).toBytesSink(bytesList)
+    }
+    return new Vector256(bytesList.toBytes())
+  }
+
+  /**
+   * Construct a Vector256 object from an array of hashes
+   *
+   * @param value A Vector256 object or array of hex-strings representing Hash256's
+   * @returns a Vector256 object
+   */
+  static from<T extends Vector256 | Array<string>>(value: T): Vector256 {
+    if (value instanceof Vector256) {
+      return value
+    }
+
+    if (isStrings(value)) {
+      const bytesList = new BytesList()
+      value.forEach((hash) => {
+        Hash256.from(hash).toBytesSink(bytesList)
+      })
+      return new Vector256(bytesList.toBytes())
+    }
+
+    throw new Error('Cannot construct Vector256 from given value')
+  }
+
+  /**
+   * Return an Array of hex-strings represented by this.bytes
+   *
+   * @returns An Array of strings representing the Hash256 objects
+   */
+  toJSON(): Array<string> {
+    if (this.bytes.byteLength % 32 !== 0) {
+      throw new Error('Invalid bytes for Vector256')
+    }
+
+    const result: Array<string> = []
+    for (let i = 0; i < this.bytes.byteLength; i += 32) {
+      result.push(bytesToHex(this.bytes.slice(i, i + 32)))
+    }
+    return result
+  }
+}
+
+export { Vector256 }

package/src/types/xchain-bridge.ts

@@ -0,0 +1,128 @@
+import { BinaryParser } from '../serdes/binary-parser'
+
+import { AccountID } from './account-id'
+import { JsonObject, SerializedType } from './serialized-type'
+import { Issue, IssueObject } from './issue'
+import { concat } from '@transia/isomorphic/utils'
+
+/**
+ * Interface for JSON objects that represent cross-chain bridges
+ */
+interface XChainBridgeObject extends JsonObject {
+  LockingChainDoor: string
+  LockingChainIssue: IssueObject | string
+  IssuingChainDoor: string
+  IssuingChainIssue: IssueObject | string
+}
+
+/**
+ * Type guard for XChainBridgeObject
+ */
+function isXChainBridgeObject(arg): arg is XChainBridgeObject {
+  const keys = Object.keys(arg).sort()
+  return (
+    keys.length === 4 &&
+    keys[0] === 'IssuingChainDoor' &&
+    keys[1] === 'IssuingChainIssue' &&
+    keys[2] === 'LockingChainDoor' &&
+    keys[3] === 'LockingChainIssue'
+  )
+}
+
+/**
+ * Class for serializing/deserializing XChainBridges
+ */
+class XChainBridge extends SerializedType {
+  static readonly ZERO_XCHAIN_BRIDGE: XChainBridge = new XChainBridge(
+    concat([
+      Uint8Array.from([0x14]),
+      new Uint8Array(40),
+      Uint8Array.from([0x14]),
+      new Uint8Array(40),
+    ]),
+  )
+
+  static readonly TYPE_ORDER: { name: string; type: typeof SerializedType }[] =
+    [
+      { name: 'LockingChainDoor', type: AccountID },
+      { name: 'LockingChainIssue', type: Issue },
+      { name: 'IssuingChainDoor', type: AccountID },
+      { name: 'IssuingChainIssue', type: Issue },
+    ]
+
+  constructor(bytes: Uint8Array) {
+    super(bytes ?? XChainBridge.ZERO_XCHAIN_BRIDGE.bytes)
+  }
+
+  /**
+   * Construct a cross-chain bridge from a JSON
+   *
+   * @param value XChainBridge or JSON to parse into an XChainBridge
+   * @returns An XChainBridge object
+   */
+  static from<T extends XChainBridge | XChainBridgeObject>(
+    value: T,
+  ): XChainBridge {
+    if (value instanceof XChainBridge) {
+      return value
+    }
+
+    if (!isXChainBridgeObject(value)) {
+      throw new Error('Invalid type to construct an XChainBridge')
+    }
+
+    const bytes: Array<Uint8Array> = []
+    this.TYPE_ORDER.forEach((item) => {
+      const { name, type } = item
+      if (type === AccountID) {
+        bytes.push(Uint8Array.from([0x14]))
+      }
+      const object = type.from(value[name])
+      bytes.push(object.toBytes())
+    })
+    return new XChainBridge(concat(bytes))
+  }
+
+  /**
+   * Read an XChainBridge from a BinaryParser
+   *
+   * @param parser BinaryParser to read the XChainBridge from
+   * @returns An XChainBridge object
+   */
+  static fromParser(parser: BinaryParser): XChainBridge {
+    const bytes: Array<Uint8Array> = []
+
+    this.TYPE_ORDER.forEach((item) => {
+      const { type } = item
+      if (type === AccountID) {
+        parser.skip(1)
+        bytes.push(Uint8Array.from([0x14]))
+      }
+      const object = type.fromParser(parser)
+      bytes.push(object.toBytes())
+    })
+
+    return new XChainBridge(concat(bytes))
+  }
+
+  /**
+   * Get the JSON representation of this XChainBridge
+   *
+   * @returns the JSON interpretation of this.bytes
+   */
+  toJSON(): XChainBridgeObject {
+    const parser = new BinaryParser(this.toString())
+    const json = {}
+    XChainBridge.TYPE_ORDER.forEach((item) => {
+      const { name, type } = item
+      if (type === AccountID) {
+        parser.skip(1)
+      }
+      const object = type.fromParser(parser).toJSON()
+      json[name] = object
+    })
+    return json as XChainBridgeObject
+  }
+}
+
+export { XChainBridge, XChainBridgeObject }

package/src/utils.ts

@@ -0,0 +1,220 @@
+// Even though this comes from NodeJS it is valid in the browser
+import TypedArray = NodeJS.TypedArray
+
+/**
+ * Writes value to array at the specified offset. The value must be a valid unsigned 8-bit integer.
+ * @param array Uint8Array to be written to
+ * @param value Number to be written to array.
+ * @param offset plus the number of bytes written.
+ */
+export function writeUInt8(
+  array: Uint8Array,
+  value: number,
+  offset: number,
+): void {
+  value = Number(value)
+  array[offset] = value
+}
+
+/**
+ * Writes value to array at the specified offset as big-endian. The value must be a valid unsigned 16-bit integer.
+ * @param array Uint8Array to be written to
+ * @param value Number to be written to array.
+ * @param offset plus the number of bytes written.
+ */
+export function writeUInt16BE(
+  array: Uint8Array,
+  value: number,
+  offset: number,
+): void {
+  value = Number(value)
+
+  array[offset] = value >>> 8
+  array[offset + 1] = value
+}
+
+/**
+ * Writes value to array at the specified offset as big-endian. The value must be a valid unsigned 32-bit integer.
+ * @param array Uint8Array to be written to
+ * @param value Number to be written to array.
+ * @param offset plus the number of bytes written.
+ */
+export function writeUInt32BE(
+  array: Uint8Array,
+  value: number,
+  offset: number,
+): void {
+  array[offset] = (value >>> 24) & 0xff
+  array[offset + 1] = (value >>> 16) & 0xff
+  array[offset + 2] = (value >>> 8) & 0xff
+  array[offset + 3] = value & 0xff
+}
+
+/**
+ * Writes a signed 32-bit integer to a Uint8Array at the specified offset (big-endian).
+ *
+ * @param array - The Uint8Array to write to.
+ * @param value - The signed 32-bit integer to write.
+ * @param offset - The offset at which to write.
+ */
+export function writeInt32BE(
+  array: Uint8Array,
+  value: number,
+  offset: number,
+): void {
+  new DataView(array.buffer, array.byteOffset, array.byteLength).setInt32(
+    offset,
+    value,
+    false,
+  )
+}
+
+/**
+ * Writes a signed 64-bit integer (BigInt) to a Uint8Array at the specified offset (big-endian).
+ *
+ * @param array - The Uint8Array to write to.
+ * @param value - The signed 64-bit integer (BigInt) to write.
+ * @param offset - The offset at which to write.
+ */
+export function writeInt64BE(
+  array: Uint8Array,
+  value: bigint,
+  offset: number,
+): void {
+  new DataView(array.buffer, array.byteOffset, array.byteLength).setBigInt64(
+    offset,
+    value,
+    false,
+  )
+}
+
+/**
+ * Reads an unsigned, big-endian 16-bit integer from the array at the specified offset.
+ * @param array Uint8Array to read
+ * @param offset Number of bytes to skip before starting to read. Must satisfy 0 <= offset <= buf.length - 2
+ */
+export function readUInt16BE(array: Uint8Array, offset: number): string {
+  return new DataView(array.buffer).getUint16(offset, false).toString(10)
+}
+
+/**
+ * Reads an unsigned, big-endian 16-bit integer from the array at the specified offset.
+ * @param array Uint8Array to read
+ * @param offset Number of bytes to skip before starting to read. Must satisfy 0 <= offset <= buf.length - 4
+ */
+export function readUInt32BE(array: Uint8Array, offset: number): string {
+  return new DataView(array.buffer).getUint32(offset, false).toString(10)
+}
+
+/**
+ * Reads a signed 32-bit integer from a Uint8Array at the specified offset (big-endian).
+ *
+ * @param array - The Uint8Array to read from.
+ * @param offset - The offset at which to start reading.
+ * @returns The signed 32-bit integer.
+ */
+export function readInt32BE(array: Uint8Array, offset: number): number {
+  return new DataView(
+    array.buffer,
+    array.byteOffset,
+    array.byteLength,
+  ).getInt32(offset, false)
+}
+
+/**
+ * Reads a signed 64-bit integer (BigInt) from a Uint8Array at the specified offset (big-endian).
+ *
+ * @param array - The Uint8Array to read from.
+ * @param offset - The offset at which to start reading.
+ * @returns The signed 64-bit integer (BigInt).
+ */
+export function readInt64BE(array: Uint8Array, offset: number): bigint {
+  return new DataView(
+    array.buffer,
+    array.byteOffset,
+    array.byteLength,
+  ).getBigInt64(offset, false)
+}
+
+/**
+ * Compares two Uint8Array or ArrayBuffers
+ * @param a first array to compare
+ * @param b second array to compare
+ */
+export function equal(
+  a: Uint8Array | ArrayBuffer,
+  b: Uint8Array | ArrayBuffer,
+): boolean {
+  const aUInt = a instanceof ArrayBuffer ? new Uint8Array(a, 0) : a
+  const bUInt = b instanceof ArrayBuffer ? new Uint8Array(b, 0) : b
+  if (aUInt.byteLength != bUInt.byteLength) return false
+  if (aligned32(aUInt) && aligned32(bUInt)) return compare32(aUInt, bUInt) === 0
+  if (aligned16(aUInt) && aligned16(bUInt)) return compare16(aUInt, bUInt) === 0
+  return compare8(aUInt, bUInt) === 0
+}
+
+/**
+ * Compares two 8 bit aligned arrays
+ * @param a first array to compare
+ * @param b second array to compare
+ */
+function compare8(a, b) {
+  const ua = new Uint8Array(a.buffer, a.byteOffset, a.byteLength)
+  const ub = new Uint8Array(b.buffer, b.byteOffset, b.byteLength)
+  return compare(ua, ub)
+}
+
+/**
+ * Compares two 16 bit aligned arrays
+ * @param a first array to compare
+ * @param b second array to compare
+ */
+function compare16(a: Uint8Array, b: Uint8Array) {
+  const ua = new Uint16Array(a.buffer, a.byteOffset, a.byteLength / 2)
+  const ub = new Uint16Array(b.buffer, b.byteOffset, b.byteLength / 2)
+  return compare(ua, ub)
+}
+
+/**
+ * Compares two 32 bit aligned arrays
+ * @param a first array to compare
+ * @param b second array to compare
+ */
+function compare32(a: Uint8Array, b: Uint8Array) {
+  const ua = new Uint32Array(a.buffer, a.byteOffset, a.byteLength / 4)
+  const ub = new Uint32Array(b.buffer, b.byteOffset, b.byteLength / 4)
+  return compare(ua, ub)
+}
+
+/**
+ * Compare two TypedArrays
+ * @param a first array to compare
+ * @param b second array to compare
+ */
+export function compare(a: TypedArray, b: TypedArray): 1 | -1 | 0 {
+  if (a.byteLength !== b.byteLength) {
+    throw new Error('Cannot compare arrays of different length')
+  }
+
+  for (let i = 0; i < a.length - 1; i += 1) {
+    if (a[i] > b[i]) return 1
+    if (a[i] < b[i]) return -1
+  }
+  return 0
+}
+
+/**
+ * Determine if TypedArray is 16 bit aligned
+ * @param array The array to check
+ */
+function aligned16(array: TypedArray) {
+  return array.byteOffset % 2 === 0 && array.byteLength % 2 === 0
+}
+
+/**
+ * Determine if TypedArray is 32 bit aligned
+ * @param array The array to check
+ */
+function aligned32(array: TypedArray) {
+  return array.byteOffset % 4 === 0 && array.byteLength % 4 === 0
+}