ripple-binary-codec 0.2.7 → 1.0.0-mpt-beta

package/src/types/currency.ts

@@ -0,0 +1,140 @@
+import { Hash160 } from './hash-160'
+import { bytesToHex, hexToBytes, hexToString } from '@xrplf/isomorphic/utils'
+
+const XRP_HEX_REGEX = /^0{40}$/
+const ISO_REGEX = /^[A-Z0-9a-z?!@#$%^&*(){}[\]|]{3}$/
+const HEX_REGEX = /^[A-F0-9]{40}$/
+// eslint-disable-next-line no-control-regex
+const STANDARD_FORMAT_HEX_REGEX = /^0{24}[\x00-\x7F]{6}0{10}$/
+
+/**
+ * Convert an ISO code to a currency bytes representation
+ */
+function isoToBytes(iso: string): Uint8Array {
+  const bytes = new Uint8Array(20)
+  if (iso !== 'XRP') {
+    const isoBytes = iso.split('').map((c) => c.charCodeAt(0))
+    bytes.set(isoBytes, 12)
+  }
+  return bytes
+}
+
+/**
+ * Tests if ISO is a valid iso code
+ */
+function isIsoCode(iso: string): boolean {
+  return ISO_REGEX.test(iso)
+}
+
+function isoCodeFromHex(code: Uint8Array): string | null {
+  const iso = hexToString(bytesToHex(code))
+  if (iso === 'XRP') {
+    return null
+  }
+  if (isIsoCode(iso)) {
+    return iso
+  }
+  return null
+}
+
+/**
+ * Tests if hex is a valid hex-string
+ */
+function isHex(hex: string): boolean {
+  return HEX_REGEX.test(hex)
+}
+
+/**
+ * Tests if a string is a valid representation of a currency
+ */
+function isStringRepresentation(input: string): boolean {
+  return input.length === 3 || isHex(input)
+}
+
+/**
+ * Tests if a Uint8Array is a valid representation of a currency
+ */
+function isBytesArray(bytes: Uint8Array): boolean {
+  return bytes.byteLength === 20
+}
+
+/**
+ * Ensures that a value is a valid representation of a currency
+ */
+function isValidRepresentation(input: Uint8Array | string): boolean {
+  return input instanceof Uint8Array
+    ? isBytesArray(input)
+    : isStringRepresentation(input)
+}
+
+/**
+ * Generate bytes from a string or UInt8Array representation of a currency
+ */
+function bytesFromRepresentation(input: string): Uint8Array {
+  if (!isValidRepresentation(input)) {
+    throw new Error(`Unsupported Currency representation: ${input}`)
+  }
+  return input.length === 3 ? isoToBytes(input) : hexToBytes(input)
+}
+
+/**
+ * Class defining how to encode and decode Currencies
+ */
+class Currency extends Hash160 {
+  static readonly XRP = new Currency(new Uint8Array(20))
+  private readonly _iso: string | null
+
+  constructor(byteBuf: Uint8Array) {
+    super(byteBuf ?? Currency.XRP.bytes)
+    const hex = bytesToHex(this.bytes)
+
+    if (XRP_HEX_REGEX.test(hex)) {
+      this._iso = 'XRP'
+    } else if (STANDARD_FORMAT_HEX_REGEX.test(hex)) {
+      this._iso = isoCodeFromHex(this.bytes.slice(12, 15))
+    } else {
+      this._iso = null
+    }
+  }
+
+  /**
+   * Return the ISO code of this currency
+   *
+   * @returns ISO code if it exists, else null
+   */
+  iso(): string | null {
+    return this._iso
+  }
+
+  /**
+   * Constructs a Currency object
+   *
+   * @param val Currency object or a string representation of a currency
+   */
+  static from<T extends Hash160 | string>(value: T): Currency {
+    if (value instanceof Currency) {
+      return value
+    }
+
+    if (typeof value === 'string') {
+      return new Currency(bytesFromRepresentation(value))
+    }
+
+    throw new Error('Cannot construct Currency from value given')
+  }
+
+  /**
+   * Gets the JSON representation of a currency
+   *
+   * @returns JSON representation
+   */
+  toJSON(): string {
+    const iso = this.iso()
+    if (iso !== null) {
+      return iso
+    }
+    return bytesToHex(this.bytes)
+  }
+}
+
+export { Currency }

package/src/types/hash-128.ts

@@ -0,0 +1,33 @@
+import { Hash } from './hash'
+import { bytesToHex } from '@xrplf/isomorphic/utils'
+
+/**
+ * Hash with a width of 128 bits
+ */
+class Hash128 extends Hash {
+  static readonly width = 16
+  static readonly ZERO_128: Hash128 = new Hash128(new Uint8Array(Hash128.width))
+
+  constructor(bytes: Uint8Array) {
+    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 = bytesToHex(this.toBytes())
+    if (/^0+$/.exec(hex)) {
+      return ''
+    }
+    return hex
+  }
+}
+
+export { Hash128 }

package/src/types/hash-160.ts

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

package/src/types/hash-192.ts

@@ -0,0 +1,19 @@
+import { Hash } from './hash'
+
+/**
+ * Hash with a width of 192 bits
+ */
+class Hash192 extends Hash {
+  static readonly width = 24
+  static readonly ZERO_192: Hash192 = new Hash192(new Uint8Array(Hash192.width))
+
+  constructor(bytes?: Uint8Array) {
+    if (bytes && bytes.byteLength === 0) {
+      bytes = Hash192.ZERO_192.bytes
+    }
+
+    super(bytes ?? Hash192.ZERO_192.bytes)
+  }
+}
+
+export { Hash192 }

package/src/types/hash-256.ts

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

package/src/types/hash.ts

@@ -0,0 +1,83 @@
+import { Comparable } from './serialized-type'
+import { BinaryParser } from '../serdes/binary-parser'
+import { hexToBytes } from '@xrplf/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') {
+      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,66 @@
+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 { 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,
+  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,96 @@
+import { concat } from '@xrplf/isomorphic/utils'
+import { BinaryParser } from '../serdes/binary-parser'
+
+import { AccountID } from './account-id'
+import { Currency } from './currency'
+import { JsonObject, SerializedType } from './serialized-type'
+
+/**
+ * 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(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, 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(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(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 }