ripple-binary-codec 1.0.2 → 1.0.3-mpt-beta

package/src/types/path-set.ts

@@ -0,0 +1,290 @@
+import { AccountID } from './account-id'
+import { Currency } from './currency'
+import { BinaryParser } from '../serdes/binary-parser'
+import { SerializedType, JsonObject } from './serialized-type'
+import { bytesToHex, concat } from '@xrplf/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
+  }
+}
+
+export { PathSet }

package/src/types/serialized-type.ts

@@ -0,0 +1,122 @@
+import { BytesList } from '../serdes/binary-serializer'
+import { BinaryParser } from '../serdes/binary-parser'
+import { XrplDefinitionsBase } from '../enums'
+import { bytesToHex } from '@xrplf/isomorphic/utils'
+
+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): JSON {
+    return this.toHex()
+  }
+
+  /**
+   * @returns hexString representation of this.bytes
+   */
+  toString(): string {
+    return this.toHex()
+  }
+}
+
+/**
+ * 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,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 '@xrplf/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-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 { STArray } from './st-array'
+
+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 })
+    }, {})
+
+    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 }