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

package/src/types/hash.ts

@@ -0,0 +1,86 @@
+import { Comparable } from './serialized-type'
+import { BinaryParser } from '../serdes/binary-parser'
+import { HEX_REGEX, hexToBytes } from '@transia/isomorphic/utils'
+import { compare } from '../utils'
+
+/**
+ * Base class defining how to encode and decode hashes
+ */
+class Hash extends Comparable<Hash | string> {
+  static readonly width: number
+
+  constructor(bytes: Uint8Array) {
+    super(bytes)
+    if (this.bytes.length !== (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') {
+      if (!HEX_REGEX.test(value)) {
+        throw new Error(`Invalid hash string ${value}`)
+      }
+      return new this(hexToBytes(value))
+    }
+
+    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 compare(
+      this.bytes,
+      (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,68 @@
+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 { Hash192 } from './hash-192'
+import { Hash256 } from './hash-256'
+import { Issue } from './issue'
+import { STNumber } from './st-number'
+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 { XChainBridge } from './xchain-bridge'
+import { type SerializedType } from './serialized-type'
+import { DEFAULT_DEFINITIONS } from '../enums'
+
+const coreTypes: Record<string, typeof SerializedType> = {
+  AccountID,
+  Amount,
+  Blob,
+  Currency,
+  Hash128,
+  Hash160,
+  Hash192,
+  Hash256,
+  Issue,
+  Number: STNumber,
+  PathSet,
+  STArray,
+  STObject,
+  UInt8,
+  UInt16,
+  UInt32,
+  UInt64,
+  Vector256,
+  XChainBridge,
+}
+
+// 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,
+  Hash192,
+  Hash256,
+  PathSet,
+  STArray,
+  STObject,
+  UInt8,
+  UInt16,
+  UInt32,
+  UInt64,
+  Vector256,
+}

package/src/types/issue.ts

@@ -0,0 +1,136 @@
+import { concat } from '@transia/isomorphic/utils'
+import { BinaryParser } from '../serdes/binary-parser'
+
+import { AccountID } from './account-id'
+import { Currency } from './currency'
+import { JsonObject, SerializedType } from './serialized-type'
+import { Hash192 } from './hash-192'
+
+interface XRPIssue extends JsonObject {
+  currency: string
+}
+
+interface IOUIssue extends JsonObject {
+  currency: string
+  issuer: string
+}
+interface MPTIssue extends JsonObject {
+  mpt_issuance_id: string
+}
+/**
+ * Interface for JSON objects that represent issues
+ */
+type IssueObject = XRPIssue | IOUIssue | MPTIssue
+
+/**
+ * Type guard for Issue Object
+ */
+function isIssueObject(arg): arg is IssueObject {
+  const keys = Object.keys(arg).sort()
+  const isXRP = keys.length === 1 && keys[0] === 'currency'
+  const isIOU =
+    keys.length === 2 && keys[0] === 'currency' && keys[1] === 'issuer'
+  const isMPT = keys.length === 1 && keys[0] === 'mpt_issuance_id'
+
+  return isXRP || isIOU || isMPT
+}
+
+/**
+ * Class for serializing/Deserializing Amounts
+ */
+class Issue extends SerializedType {
+  static readonly ZERO_ISSUED_CURRENCY: Issue = new Issue(new Uint8Array(20))
+
+  constructor(bytes: Uint8Array) {
+    super(bytes ?? Issue.ZERO_ISSUED_CURRENCY.bytes)
+  }
+
+  /**
+   * Construct an amount from an IOU or string amount
+   *
+   * @param value An Amount, object representing an IOU, MPTAmount, or a string
+   *     representing an integer amount
+   * @returns An Issue object
+   */
+  static from<T extends Issue | IssueObject>(value: T): Issue {
+    if (value instanceof Issue) {
+      return value
+    }
+
+    if (isIssueObject(value)) {
+      if (value.currency) {
+        const currency = Currency.from(value.currency.toString()).toBytes()
+
+        //IOU case
+        if (value.issuer) {
+          const issuer = AccountID.from(value.issuer.toString()).toBytes()
+          return new Issue(concat([currency, issuer]))
+        }
+
+        //XRP case
+        return new Issue(currency)
+      }
+
+      // MPT case
+      if (value.mpt_issuance_id) {
+        const mptIssuanceIdBytes = Hash192.from(
+          value.mpt_issuance_id.toString(),
+        ).toBytes()
+        return new Issue(mptIssuanceIdBytes)
+      }
+    }
+
+    throw new Error('Invalid type to construct an Amount')
+  }
+
+  /**
+   * Read an amount from a BinaryParser
+   *
+   * @param parser BinaryParser to read the Amount from
+   * @param hint The number of bytes to consume from the parser.
+   * For an MPT amount, pass 24 (the fixed length for Hash192).
+   *
+   * @returns An Issue object
+   */
+  static fromParser(parser: BinaryParser, hint?: number): Issue {
+    if (hint === Hash192.width) {
+      const mptBytes = parser.read(Hash192.width)
+      return new Issue(mptBytes)
+    }
+    const currency = parser.read(20)
+    if (new Currency(currency).toJSON() === 'XRP') {
+      return new Issue(currency)
+    }
+    const currencyAndIssuer = [currency, parser.read(20)]
+    return new Issue(concat(currencyAndIssuer))
+  }
+
+  /**
+   * Get the JSON representation of this Amount
+   *
+   * @returns the JSON interpretation of this.bytes
+   */
+  toJSON(): IssueObject {
+    // If the buffer is exactly 24 bytes, treat it as an MPT amount.
+    if (this.toBytes().length === Hash192.width) {
+      return {
+        mpt_issuance_id: this.toHex().toUpperCase(),
+      }
+    }
+
+    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 { 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
+  }
+}
+
+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 '@transia/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, _fieldName?: string): 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 }