ripple-binary-codec 1.7.1 → 1.9.0

package/src/types/hash-128.ts

@@ -0,0 +1,33 @@
+import { Hash } from './hash'
+import { Buffer } from 'buffer/'
+
+/**
+ * Hash with a width of 128 bits
+ */
+class Hash128 extends Hash {
+  static readonly width = 16
+  static readonly ZERO_128: Hash128 = new Hash128(Buffer.alloc(Hash128.width))
+
+  constructor(bytes: Buffer) {
+    if (bytes && bytes.byteLength === 0) {
+      bytes = Hash128.ZERO_128.bytes
+    }
+
+    super(bytes ?? Hash128.ZERO_128.bytes)
+  }
+
+  /**
+   * Get the hex representation of a hash-128 bytes, allowing unset
+   *
+   * @returns hex String of this.bytes
+   */
+  toHex(): string {
+    const hex = this.toBytes().toString('hex').toUpperCase()
+    if (/^0+$/.exec(hex)) {
+      return ''
+    }
+    return hex
+  }
+}
+
+export { Hash128 }

package/src/types/hash-160.ts

@@ -0,0 +1,20 @@
+import { Hash } from './hash'
+import { Buffer } from 'buffer/'
+
+/**
+ * Hash with a width of 160 bits
+ */
+class Hash160 extends Hash {
+  static readonly width = 20
+  static readonly ZERO_160: Hash160 = new Hash160(Buffer.alloc(Hash160.width))
+
+  constructor(bytes?: Buffer) {
+    if (bytes && bytes.byteLength === 0) {
+      bytes = Hash160.ZERO_160.bytes
+    }
+
+    super(bytes ?? Hash160.ZERO_160.bytes)
+  }
+}
+
+export { Hash160 }

package/src/types/hash-256.ts

@@ -0,0 +1,16 @@
+import { Hash } from './hash'
+import { Buffer } from 'buffer/'
+
+/**
+ * Hash with a width of 256 bits
+ */
+class Hash256 extends Hash {
+  static readonly width = 32
+  static readonly ZERO_256 = new Hash256(Buffer.alloc(Hash256.width))
+
+  constructor(bytes: Buffer) {
+    super(bytes ?? Hash256.ZERO_256.bytes)
+  }
+}
+
+export { Hash256 }

package/src/types/hash.ts

@@ -0,0 +1,81 @@
+import { Comparable } from './serialized-type'
+import { BinaryParser } from '../serdes/binary-parser'
+import { Buffer } from 'buffer/'
+
+/**
+ * Base class defining how to encode and decode hashes
+ */
+class Hash extends Comparable {
+  static readonly width: number
+
+  constructor(bytes: Buffer) {
+    super(bytes)
+    if (this.bytes.byteLength !== (this.constructor as typeof Hash).width) {
+      throw new Error(`Invalid Hash length ${this.bytes.byteLength}`)
+    }
+  }
+
+  /**
+   * Construct a Hash object from an existing Hash object or a hex-string
+   *
+   * @param value A hash object or hex-string of a hash
+   */
+  static from<T extends Hash | string>(value: T): Hash {
+    if (value instanceof this) {
+      return value
+    }
+
+    if (typeof value === 'string') {
+      return new this(Buffer.from(value, 'hex'))
+    }
+
+    throw new Error('Cannot construct Hash from given value')
+  }
+
+  /**
+   * Read a Hash object from a BinaryParser
+   *
+   * @param parser BinaryParser to read the hash from
+   * @param hint length of the bytes to read, optional
+   */
+  static fromParser(parser: BinaryParser, hint?: number): Hash {
+    return new this(parser.read(hint ?? this.width))
+  }
+
+  /**
+   * Overloaded operator for comparing two hash objects
+   *
+   * @param other The Hash to compare this to
+   */
+  compareTo(other: Hash): number {
+    return this.bytes.compare(
+      (this.constructor as typeof Hash).from(other).bytes,
+    )
+  }
+
+  /**
+   * @returns the hex-string representation of this Hash
+   */
+  toString(): string {
+    return this.toHex()
+  }
+
+  /**
+   * Returns four bits at the specified depth within a hash
+   *
+   * @param depth The depth of the four bits
+   * @returns The number represented by the four bits
+   */
+  nibblet(depth: number): number {
+    const byteIx = depth > 0 ? (depth / 2) | 0 : 0
+    let b = this.bytes[byteIx]
+    if (depth % 2 === 0) {
+      b = (b & 0xf0) >>> 4
+    } else {
+      b = b & 0x0f
+    }
+    return b
+  }
+}
+
+export { Hash }

package/src/types/index.ts

@@ -0,0 +1,61 @@
+import { AccountID } from './account-id'
+import { Amount } from './amount'
+import { Blob } from './blob'
+import { Currency } from './currency'
+import { Hash128 } from './hash-128'
+import { Hash160 } from './hash-160'
+import { Hash256 } from './hash-256'
+import { Issue } from './issue'
+import { PathSet } from './path-set'
+import { STArray } from './st-array'
+import { STObject } from './st-object'
+import { UInt16 } from './uint-16'
+import { UInt32 } from './uint-32'
+import { UInt64 } from './uint-64'
+import { UInt8 } from './uint-8'
+import { Vector256 } from './vector-256'
+import { type SerializedType } from './serialized-type'
+import { DEFAULT_DEFINITIONS } from '../enums'
+
+const coreTypes: Record<string, typeof SerializedType> = {
+  AccountID,
+  Amount,
+  Blob,
+  Currency,
+  Hash128,
+  Hash160,
+  Hash256,
+  Issue,
+  PathSet,
+  STArray,
+  STObject,
+  UInt8,
+  UInt16,
+  UInt32,
+  UInt64,
+  Vector256,
+}
+
+// Ensures that the DEFAULT_DEFINITIONS object connects these types to fields for serializing/deserializing
+// This is done here instead of in enums/index.ts to avoid a circular dependency
+// because some of the above types depend on BinarySerializer which depends on enums/index.ts.
+DEFAULT_DEFINITIONS.associateTypes(coreTypes)
+
+export {
+  coreTypes,
+  AccountID,
+  Amount,
+  Blob,
+  Currency,
+  Hash128,
+  Hash160,
+  Hash256,
+  PathSet,
+  STArray,
+  STObject,
+  UInt8,
+  UInt16,
+  UInt32,
+  UInt64,
+  Vector256,
+}

package/src/types/issue.ts

@@ -0,0 +1,96 @@
+import { BinaryParser } from '../serdes/binary-parser'
+
+import { AccountID } from './account-id'
+import { Currency } from './currency'
+import { JsonObject, SerializedType } from './serialized-type'
+import { Buffer } from 'buffer/'
+
+/**
+ * Interface for JSON objects that represent amounts
+ */
+interface IssueObject extends JsonObject {
+  currency: string
+  issuer?: string
+}
+
+/**
+ * Type guard for AmountObject
+ */
+function isIssueObject(arg): arg is IssueObject {
+  const keys = Object.keys(arg).sort()
+  if (keys.length === 1) {
+    return keys[0] === 'currency'
+  }
+  return keys.length === 2 && keys[0] === 'currency' && keys[1] === 'issuer'
+}
+
+/**
+ * Class for serializing/Deserializing Amounts
+ */
+class Issue extends SerializedType {
+  static readonly ZERO_ISSUED_CURRENCY: Issue = new Issue(Buffer.alloc(20))
+
+  constructor(bytes: Buffer) {
+    super(bytes ?? Issue.ZERO_ISSUED_CURRENCY.bytes)
+  }
+
+  /**
+   * Construct an amount from an IOU or string amount
+   *
+   * @param value An Amount, object representing an IOU, or a string
+   *     representing an integer amount
+   * @returns An Amount object
+   */
+  static from<T extends Issue | IssueObject>(value: T): Issue {
+    if (value instanceof Issue) {
+      return value
+    }
+
+    if (isIssueObject(value)) {
+      const currency = Currency.from(value.currency).toBytes()
+      if (value.issuer == null) {
+        return new Issue(currency)
+      }
+      const issuer = AccountID.from(value.issuer).toBytes()
+      return new Issue(Buffer.concat([currency, issuer]))
+    }
+
+    throw new Error('Invalid type to construct an Amount')
+  }
+
+  /**
+   * Read an amount from a BinaryParser
+   *
+   * @param parser BinaryParser to read the Amount from
+   * @returns An Amount object
+   */
+  static fromParser(parser: BinaryParser): Issue {
+    const currency = parser.read(20)
+    if (new Currency(currency).toJSON() === 'XRP') {
+      return new Issue(currency)
+    }
+    const currencyAndIssuer = [currency, parser.read(20)]
+    return new Issue(Buffer.concat(currencyAndIssuer))
+  }
+
+  /**
+   * Get the JSON representation of this Amount
+   *
+   * @returns the JSON interpretation of this.bytes
+   */
+  toJSON(): IssueObject {
+    const parser = new BinaryParser(this.toString())
+    const currency = Currency.fromParser(parser) as Currency
+    if (currency.toJSON() === 'XRP') {
+      return { currency: currency.toJSON() }
+    }
+    const issuer = AccountID.fromParser(parser) as AccountID
+
+    return {
+      currency: currency.toJSON(),
+      issuer: issuer.toJSON(),
+    }
+  }
+}
+
+export { Issue, IssueObject }

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 { Buffer } from 'buffer/'
+
+/**
+ * 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<Buffer> = [Buffer.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(Buffer.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<Buffer> = [Buffer.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(Buffer.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(this.bytes.toString('hex'))
+    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<Buffer> = []
+    value.forEach((hop: HopObject) => {
+      bytes.push(Hop.from(hop).toBytes())
+    })
+
+    return new Path(Buffer.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<Buffer> = []
+    while (!parser.end()) {
+      bytes.push(Hop.fromParser(parser).toBytes())
+
+      if (
+        parser.peek() === PATHSET_END_BYTE ||
+        parser.peek() === PATH_SEPARATOR_BYTE
+      ) {
+        break
+      }
+    }
+    return new Path(Buffer.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<Buffer> = []
+
+      value.forEach((path: Array<HopObject>) => {
+        bytes.push(Path.from(path).toBytes())
+        bytes.push(Buffer.from([PATH_SEPARATOR_BYTE]))
+      })
+
+      bytes[bytes.length - 1] = Buffer.from([PATHSET_END_BYTE])
+
+      return new PathSet(Buffer.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<Buffer> = []
+
+    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(Buffer.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 }