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

package/src/types/path-set.ts

@@ -0,0 +1,294 @@
+import { AccountID } from './account-id'
+import { Currency } from './currency'
+import { BinaryParser } from '../serdes/binary-parser'
+import { SerializedType, JsonObject, SerializedTypeID } from './serialized-type'
+import { bytesToHex, concat } from '@transia/isomorphic/utils'
+
+/**
+ * Constants for separating Paths in a PathSet
+ */
+const PATHSET_END_BYTE = 0x00
+const PATH_SEPARATOR_BYTE = 0xff
+
+/**
+ * Constant for masking types of a Hop
+ */
+const TYPE_ACCOUNT = 0x01
+const TYPE_CURRENCY = 0x10
+const TYPE_ISSUER = 0x20
+
+/**
+ * The object representation of a Hop, an issuer AccountID, an account AccountID, and a Currency
+ */
+interface HopObject extends JsonObject {
+  issuer?: string
+  account?: string
+  currency?: string
+}
+
+/**
+ * TypeGuard for HopObject
+ */
+function isHopObject(arg): arg is HopObject {
+  return (
+    arg.issuer !== undefined ||
+    arg.account !== undefined ||
+    arg.currency !== undefined
+  )
+}
+
+/**
+ * TypeGuard for PathSet
+ */
+function isPathSet(arg): arg is Array<Array<HopObject>> {
+  return (
+    (Array.isArray(arg) && arg.length === 0) ||
+    (Array.isArray(arg) && Array.isArray(arg[0]) && arg[0].length === 0) ||
+    (Array.isArray(arg) && Array.isArray(arg[0]) && isHopObject(arg[0][0]))
+  )
+}
+
+/**
+ * Serialize and Deserialize a Hop
+ */
+class Hop extends SerializedType {
+  /**
+   * Create a Hop from a HopObject
+   *
+   * @param value Either a hop or HopObject to create a hop with
+   * @returns a Hop
+   */
+  static from(value: Hop | HopObject): Hop {
+    if (value instanceof Hop) {
+      return value
+    }
+
+    const bytes: Array<Uint8Array> = [Uint8Array.from([0])]
+
+    if (value.account) {
+      bytes.push(AccountID.from(value.account).toBytes())
+      bytes[0][0] |= TYPE_ACCOUNT
+    }
+
+    if (value.currency) {
+      bytes.push(Currency.from(value.currency).toBytes())
+      bytes[0][0] |= TYPE_CURRENCY
+    }
+
+    if (value.issuer) {
+      bytes.push(AccountID.from(value.issuer).toBytes())
+      bytes[0][0] |= TYPE_ISSUER
+    }
+
+    return new Hop(concat(bytes))
+  }
+
+  /**
+   * Construct a Hop from a BinaryParser
+   *
+   * @param parser BinaryParser to read the Hop from
+   * @returns a Hop
+   */
+  static fromParser(parser: BinaryParser): Hop {
+    const type = parser.readUInt8()
+    const bytes: Array<Uint8Array> = [Uint8Array.from([type])]
+
+    if (type & TYPE_ACCOUNT) {
+      bytes.push(parser.read(AccountID.width))
+    }
+
+    if (type & TYPE_CURRENCY) {
+      bytes.push(parser.read(Currency.width))
+    }
+
+    if (type & TYPE_ISSUER) {
+      bytes.push(parser.read(AccountID.width))
+    }
+
+    return new Hop(concat(bytes))
+  }
+
+  /**
+   * Get the JSON interpretation of this hop
+   *
+   * @returns a HopObject, an JS object with optional account, issuer, and currency
+   */
+  toJSON(): HopObject {
+    const hopParser = new BinaryParser(bytesToHex(this.bytes))
+    const type = hopParser.readUInt8()
+
+    let account, currency, issuer
+    if (type & TYPE_ACCOUNT) {
+      account = (AccountID.fromParser(hopParser) as AccountID).toJSON()
+    }
+
+    if (type & TYPE_CURRENCY) {
+      currency = (Currency.fromParser(hopParser) as Currency).toJSON()
+    }
+
+    if (type & TYPE_ISSUER) {
+      issuer = (AccountID.fromParser(hopParser) as AccountID).toJSON()
+    }
+
+    const result: HopObject = {}
+    if (account) {
+      result.account = account
+    }
+
+    if (issuer) {
+      result.issuer = issuer
+    }
+
+    if (currency) {
+      result.currency = currency
+    }
+
+    return result
+  }
+
+  /**
+   * get a number representing the type of this hop
+   *
+   * @returns a number to be bitwise and-ed with TYPE_ constants to describe the types in the hop
+   */
+  type(): number {
+    return this.bytes[0]
+  }
+}
+
+/**
+ * Class for serializing/deserializing Paths
+ */
+class Path extends SerializedType {
+  /**
+   * construct a Path from an array of Hops
+   *
+   * @param value Path or array of HopObjects to construct a Path
+   * @returns the Path
+   */
+  static from(value: Path | Array<HopObject>): Path {
+    if (value instanceof Path) {
+      return value
+    }
+
+    const bytes: Array<Uint8Array> = []
+    value.forEach((hop: HopObject) => {
+      bytes.push(Hop.from(hop).toBytes())
+    })
+
+    return new Path(concat(bytes))
+  }
+
+  /**
+   * Read a Path from a BinaryParser
+   *
+   * @param parser BinaryParser to read Path from
+   * @returns the Path represented by the bytes read from the BinaryParser
+   */
+  static fromParser(parser: BinaryParser): Path {
+    const bytes: Array<Uint8Array> = []
+    while (!parser.end()) {
+      bytes.push(Hop.fromParser(parser).toBytes())
+
+      if (
+        parser.peek() === PATHSET_END_BYTE ||
+        parser.peek() === PATH_SEPARATOR_BYTE
+      ) {
+        break
+      }
+    }
+    return new Path(concat(bytes))
+  }
+
+  /**
+   * Get the JSON representation of this Path
+   *
+   * @returns an Array of HopObject constructed from this.bytes
+   */
+  toJSON(): Array<HopObject> {
+    const json: Array<HopObject> = []
+    const pathParser = new BinaryParser(this.toString())
+
+    while (!pathParser.end()) {
+      json.push(Hop.fromParser(pathParser).toJSON())
+    }
+
+    return json
+  }
+}
+
+/**
+ * Deserialize and Serialize the PathSet type
+ */
+class PathSet extends SerializedType {
+  /**
+   * Construct a PathSet from an Array of Arrays representing paths
+   *
+   * @param value A PathSet or Array of Array of HopObjects
+   * @returns the PathSet constructed from value
+   */
+  static from<T extends PathSet | Array<Array<HopObject>>>(value: T): PathSet {
+    if (value instanceof PathSet) {
+      return value
+    }
+
+    if (isPathSet(value)) {
+      const bytes: Array<Uint8Array> = []
+
+      value.forEach((path: Array<HopObject>) => {
+        bytes.push(Path.from(path).toBytes())
+        bytes.push(Uint8Array.from([PATH_SEPARATOR_BYTE]))
+      })
+
+      bytes[bytes.length - 1] = Uint8Array.from([PATHSET_END_BYTE])
+
+      return new PathSet(concat(bytes))
+    }
+
+    throw new Error('Cannot construct PathSet from given value')
+  }
+
+  /**
+   * Construct a PathSet from a BinaryParser
+   *
+   * @param parser A BinaryParser to read PathSet from
+   * @returns the PathSet read from parser
+   */
+  static fromParser(parser: BinaryParser): PathSet {
+    const bytes: Array<Uint8Array> = []
+
+    while (!parser.end()) {
+      bytes.push(Path.fromParser(parser).toBytes())
+      bytes.push(parser.read(1))
+
+      if (bytes[bytes.length - 1][0] == PATHSET_END_BYTE) {
+        break
+      }
+    }
+
+    return new PathSet(concat(bytes))
+  }
+
+  /**
+   * Get the JSON representation of this PathSet
+   *
+   * @returns an Array of Array of HopObjects, representing this PathSet
+   */
+  toJSON(): Array<Array<HopObject>> {
+    const json: Array<Array<HopObject>> = []
+    const pathParser = new BinaryParser(this.toString())
+
+    while (!pathParser.end()) {
+      json.push(Path.fromParser(pathParser).toJSON())
+      pathParser.skip(1)
+    }
+
+    return json
+  }
+
+  getSType(): SerializedTypeID {
+    return SerializedTypeID.STI_PATHSET
+  }
+}
+
+export { PathSet }

package/src/types/serialized-type.ts

@@ -0,0 +1,271 @@
+import { BytesList } from '../serdes/binary-serializer'
+import { BinaryParser } from '../serdes/binary-parser'
+import { XrplDefinitionsBase } from '../enums'
+import { bytesToHex } from '@transia/isomorphic/utils'
+
+/**
+ * Enum for SerializedTypeID values used in XRPL
+ * These match the C++ implementation's STI_ constants
+ */
+export enum SerializedTypeID {
+  STI_NOTPRESENT = 0,
+  STI_UINT16 = 1,
+  STI_UINT32 = 2,
+  STI_UINT64 = 3,
+  STI_UINT128 = 4,
+  STI_UINT256 = 5,
+  STI_AMOUNT = 6,
+  STI_VL = 7,
+  STI_ACCOUNT = 8,
+  STI_NUMBER = 9,
+  STI_INT32 = 10,
+  STI_INT64 = 11,
+
+  STI_OBJECT = 14,
+  STI_ARRAY = 15,
+
+  STI_UINT8 = 16,
+  STI_UINT160 = 17,
+  STI_PATHSET = 18,
+  STI_VECTOR256 = 19,
+  STI_UINT96 = 20,
+  STI_UINT192 = 21,
+  STI_UINT384 = 22,
+  STI_UINT512 = 23,
+  STI_ISSUE = 24,
+  STI_XCHAIN_BRIDGE = 25,
+  STI_CURRENCY = 26,
+  STI_DATA = 27,
+  STI_DATATYPE = 28,
+  STI_JSON = 29,
+}
+
+/**
+ * Map of type strings to SerializedTypeID values
+ */
+export const TYPE_STRING_TO_ID: Record<string, SerializedTypeID> = {
+  NOTPRESENT: SerializedTypeID.STI_NOTPRESENT,
+  UINT16: SerializedTypeID.STI_UINT16,
+  UINT32: SerializedTypeID.STI_UINT32,
+  UINT64: SerializedTypeID.STI_UINT64,
+  UINT128: SerializedTypeID.STI_UINT128,
+  UINT256: SerializedTypeID.STI_UINT256,
+  AMOUNT: SerializedTypeID.STI_AMOUNT,
+  VL: SerializedTypeID.STI_VL,
+  ACCOUNT: SerializedTypeID.STI_ACCOUNT,
+  NUMBER: SerializedTypeID.STI_NUMBER,
+  INT32: SerializedTypeID.STI_INT32,
+  INT64: SerializedTypeID.STI_INT64,
+
+  OBJECT: SerializedTypeID.STI_OBJECT,
+  ARRAY: SerializedTypeID.STI_ARRAY,
+
+  UINT8: SerializedTypeID.STI_UINT8,
+  UINT160: SerializedTypeID.STI_UINT160,
+  PATHSET: SerializedTypeID.STI_PATHSET,
+  VECTOR256: SerializedTypeID.STI_VECTOR256,
+  UINT96: SerializedTypeID.STI_UINT96,
+  UINT192: SerializedTypeID.STI_UINT192,
+  UINT384: SerializedTypeID.STI_UINT384,
+  UINT512: SerializedTypeID.STI_UINT512,
+  ISSUE: SerializedTypeID.STI_ISSUE,
+  XCHAIN_BRIDGE: SerializedTypeID.STI_XCHAIN_BRIDGE,
+  CURRENCY: SerializedTypeID.STI_CURRENCY,
+  DATA: SerializedTypeID.STI_DATA,
+  DATATYPE: SerializedTypeID.STI_DATATYPE,
+  JSON: SerializedTypeID.STI_JSON,
+}
+
+/**
+ * Map of type strings to SerializedTypeID values
+ */
+export const TYPE_NUMBER_TO_ID: Record<number, SerializedTypeID> = {
+  0: SerializedTypeID.STI_NOTPRESENT,
+  1: SerializedTypeID.STI_UINT16,
+  2: SerializedTypeID.STI_UINT32,
+  3: SerializedTypeID.STI_UINT64,
+  4: SerializedTypeID.STI_UINT128,
+  5: SerializedTypeID.STI_UINT256,
+  6: SerializedTypeID.STI_AMOUNT,
+  7: SerializedTypeID.STI_VL,
+  8: SerializedTypeID.STI_ACCOUNT,
+  9: SerializedTypeID.STI_NUMBER,
+  10: SerializedTypeID.STI_INT32,
+  11: SerializedTypeID.STI_INT64,
+
+  14: SerializedTypeID.STI_OBJECT,
+  15: SerializedTypeID.STI_ARRAY,
+
+  16: SerializedTypeID.STI_UINT8,
+  17: SerializedTypeID.STI_UINT160,
+  18: SerializedTypeID.STI_PATHSET,
+  19: SerializedTypeID.STI_VECTOR256,
+  20: SerializedTypeID.STI_UINT96,
+  21: SerializedTypeID.STI_UINT192,
+  22: SerializedTypeID.STI_UINT384,
+  23: SerializedTypeID.STI_UINT512,
+  24: SerializedTypeID.STI_ISSUE,
+  25: SerializedTypeID.STI_XCHAIN_BRIDGE,
+  26: SerializedTypeID.STI_CURRENCY,
+  27: SerializedTypeID.STI_DATA,
+  28: SerializedTypeID.STI_DATATYPE,
+  29: SerializedTypeID.STI_JSON,
+}
+
+/**
+ * Map of SerializedTypeID values to type strings
+ */
+export const TYPE_ID_TO_STRING: Record<SerializedTypeID, string> = {
+  [SerializedTypeID.STI_NOTPRESENT]: '',
+  [SerializedTypeID.STI_UINT16]: 'UINT16',
+  [SerializedTypeID.STI_UINT32]: 'UINT32',
+  [SerializedTypeID.STI_UINT64]: 'UINT64',
+  [SerializedTypeID.STI_UINT128]: 'UINT128',
+  [SerializedTypeID.STI_UINT256]: 'UINT256',
+  [SerializedTypeID.STI_AMOUNT]: 'AMOUNT',
+  [SerializedTypeID.STI_VL]: 'VL',
+  [SerializedTypeID.STI_ACCOUNT]: 'ACCOUNT',
+  [SerializedTypeID.STI_NUMBER]: 'NUMBER',
+  [SerializedTypeID.STI_INT32]: 'INT32',
+  [SerializedTypeID.STI_INT64]: 'INT64',
+
+  [SerializedTypeID.STI_OBJECT]: 'OBJECT',
+  [SerializedTypeID.STI_ARRAY]: 'ARRAY',
+
+  [SerializedTypeID.STI_UINT8]: 'UINT8',
+  [SerializedTypeID.STI_UINT160]: 'UINT160',
+  [SerializedTypeID.STI_PATHSET]: 'PATHSET',
+  [SerializedTypeID.STI_VECTOR256]: 'VECTOR256',
+  [SerializedTypeID.STI_UINT96]: 'UINT96',
+  [SerializedTypeID.STI_UINT192]: 'UINT192',
+  [SerializedTypeID.STI_UINT384]: 'UINT384',
+  [SerializedTypeID.STI_UINT512]: 'UINT512',
+  [SerializedTypeID.STI_ISSUE]: 'ISSUE',
+  [SerializedTypeID.STI_XCHAIN_BRIDGE]: 'XCHAIN_BRIDGE',
+  [SerializedTypeID.STI_CURRENCY]: 'CURRENCY',
+  [SerializedTypeID.STI_DATA]: 'DATA',
+  [SerializedTypeID.STI_DATATYPE]: 'DATATYPE',
+  [SerializedTypeID.STI_JSON]: 'JSON',
+}
+
+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: Uint8Array = new Uint8Array(0)
+
+  constructor(bytes?: Uint8Array) {
+    this.bytes = bytes ?? new Uint8Array(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): 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 bytesToHex(this.toBytes())
+  }
+
+  /**
+   * Get the bytes representation of a SerializedType
+   *
+   * @returns A Uint8Array of the bytes
+   */
+  toBytes(): Uint8Array {
+    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, _fieldName?: string): JSON {
+    return this.toHex()
+  }
+
+  /**
+   * @returns hexString representation of this.bytes
+   */
+  toString(): string {
+    return this.toHex()
+  }
+
+  getSType(): SerializedTypeID {
+    return this.getSType()
+  }
+}
+
+/**
+ * Base class for SerializedTypes that are comparable.
+ *
+ * @template T - What types you want to allow comparisons between. You must specify all types. Primarily used to allow
+ * comparisons between built-in types (like `string`) and SerializedType subclasses (like `Hash`).
+ *
+ * Ex. `class Hash extends Comparable<Hash | string>`
+ */
+class Comparable<T extends Object> extends SerializedType {
+  lt(other: T): boolean {
+    return this.compareTo(other) < 0
+  }
+
+  eq(other: T): boolean {
+    return this.compareTo(other) === 0
+  }
+
+  gt(other: T): boolean {
+    return this.compareTo(other) > 0
+  }
+
+  gte(other: T): boolean {
+    return this.compareTo(other) > -1
+  }
+
+  lte(other: T): 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: T): 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,117 @@
+import { DEFAULT_DEFINITIONS, XrplDefinitionsBase } from '../enums'
+import { SerializedType, JsonObject, SerializedTypeID } 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
+  }
+
+  getSType(): SerializedTypeID {
+    return SerializedTypeID.STI_ARRAY
+  }
+}
+
+export { STArray }