ripple-binary-codec 1.7.1 → 1.9.0

package/src/shamap.ts

@@ -0,0 +1,186 @@
+import { strict as assert } from 'assert'
+import { coreTypes } from './types'
+import { HashPrefix } from './hash-prefixes'
+import { Sha512Half } from './hashes'
+import { Hash256 } from './types/hash-256'
+import { BytesList } from './serdes/binary-serializer'
+import { Buffer } from 'buffer/'
+
+/**
+ * Abstract class describing a SHAMapNode
+ */
+abstract class ShaMapNode {
+  abstract hashPrefix(): Buffer
+  abstract isLeaf(): boolean
+  abstract isInner(): boolean
+  abstract toBytesSink(list: BytesList): void
+  abstract hash(): Hash256
+}
+
+/**
+ * Class describing a Leaf of SHAMap
+ */
+class ShaMapLeaf extends ShaMapNode {
+  constructor(public index: Hash256, public item?: ShaMapNode) {
+    super()
+  }
+
+  /**
+   * @returns true as ShaMapLeaf is a leaf node
+   */
+  isLeaf(): boolean {
+    return true
+  }
+
+  /**
+   * @returns false as ShaMapLeaf is not an inner node
+   */
+  isInner(): boolean {
+    return false
+  }
+
+  /**
+   * Get the prefix of the this.item
+   *
+   * @returns The hash prefix, unless this.item is undefined, then it returns an empty Buffer
+   */
+  hashPrefix(): Buffer {
+    return this.item === undefined ? Buffer.alloc(0) : this.item.hashPrefix()
+  }
+
+  /**
+   * Hash the bytes representation of this
+   *
+   * @returns hash of this.item concatenated with this.index
+   */
+  hash(): Hash256 {
+    const hash = Sha512Half.put(this.hashPrefix())
+    this.toBytesSink(hash)
+    return hash.finish()
+  }
+
+  /**
+   * Write the bytes representation of this to a BytesList
+   * @param list BytesList to write bytes to
+   */
+  toBytesSink(list: BytesList): void {
+    if (this.item !== undefined) {
+      this.item.toBytesSink(list)
+    }
+    this.index.toBytesSink(list)
+  }
+}
+
+/**
+ * Class defining an Inner Node of a SHAMap
+ */
+class ShaMapInner extends ShaMapNode {
+  private slotBits = 0
+  private branches: Array<ShaMapNode> = Array(16)
+
+  constructor(private depth: number = 0) {
+    super()
+  }
+
+  /**
+   * @returns true as ShaMapInner is an inner node
+   */
+  isInner(): boolean {
+    return true
+  }
+
+  /**
+   * @returns false as ShaMapInner is not a leaf node
+   */
+  isLeaf(): boolean {
+    return false
+  }
+
+  /**
+   * Get the hash prefix for this node
+   *
+   * @returns hash prefix describing an inner node
+   */
+  hashPrefix(): Buffer {
+    return HashPrefix.innerNode
+  }
+
+  /**
+   * Set a branch of this node to be another node
+   *
+   * @param slot Slot to add branch to this.branches
+   * @param branch Branch to add
+   */
+  setBranch(slot: number, branch: ShaMapNode): void {
+    this.slotBits = this.slotBits | (1 << slot)
+    this.branches[slot] = branch
+  }
+
+  /**
+   * @returns true if node is empty
+   */
+  empty(): boolean {
+    return this.slotBits === 0
+  }
+
+  /**
+   * Compute the hash of this node
+   *
+   * @returns The hash of this node
+   */
+  hash(): Hash256 {
+    if (this.empty()) {
+      return (coreTypes.Hash256 as typeof Hash256).ZERO_256
+    }
+    const hash = Sha512Half.put(this.hashPrefix())
+    this.toBytesSink(hash)
+    return hash.finish()
+  }
+
+  /**
+   * Writes the bytes representation of this node to a BytesList
+   *
+   * @param list BytesList to write bytes to
+   */
+  toBytesSink(list: BytesList): void {
+    for (let i = 0; i < this.branches.length; i++) {
+      const branch = this.branches[i]
+      const hash = branch
+        ? branch.hash()
+        : (coreTypes.Hash256 as typeof Hash256).ZERO_256
+      hash.toBytesSink(list)
+    }
+  }
+
+  /**
+   * Add item to the SHAMap
+   *
+   * @param index Hash of the index of the item being inserted
+   * @param item Item to insert in the map
+   * @param leaf Leaf node to insert when branch doesn't exist
+   */
+  addItem(index?: Hash256, item?: ShaMapNode, leaf?: ShaMapLeaf): void {
+    assert.ok(index !== undefined)
+    if (index !== undefined) {
+      const nibble = index.nibblet(this.depth)
+      const existing = this.branches[nibble]
+
+      if (existing === undefined) {
+        this.setBranch(nibble, leaf || new ShaMapLeaf(index, item))
+      } else if (existing instanceof ShaMapLeaf) {
+        const newInner = new ShaMapInner(this.depth + 1)
+        newInner.addItem(existing.index, undefined, existing)
+        newInner.addItem(index, item, leaf)
+        this.setBranch(nibble, newInner)
+      } else if (existing instanceof ShaMapInner) {
+        existing.addItem(index, item, leaf)
+      } else {
+        throw new Error('invalid ShaMap.addItem call')
+      }
+    }
+  }
+}
+
+class ShaMap extends ShaMapInner {}
+
+export { ShaMap, ShaMapNode, ShaMapLeaf }

package/src/types/account-id.ts

@@ -0,0 +1,86 @@
+import {
+  decodeAccountID,
+  encodeAccountID,
+  isValidXAddress,
+  xAddressToClassicAddress,
+} from 'ripple-address-codec'
+import { Hash160 } from './hash-160'
+import { Buffer } from 'buffer/'
+
+const HEX_REGEX = /^[A-F0-9]{40}$/
+
+/**
+ * Class defining how to encode and decode an AccountID
+ */
+class AccountID extends Hash160 {
+  static readonly defaultAccountID: AccountID = new AccountID(Buffer.alloc(20))
+
+  constructor(bytes?: Buffer) {
+    super(bytes ?? AccountID.defaultAccountID.bytes)
+  }
+
+  /**
+   * Defines how to construct an AccountID
+   *
+   * @param value either an existing AccountID, a hex-string, or a base58 r-Address
+   * @returns an AccountID object
+   */
+  static from<T extends Hash160 | string>(value: T): AccountID {
+    if (value instanceof AccountID) {
+      return value
+    }
+
+    if (typeof value === 'string') {
+      if (value === '') {
+        return new AccountID()
+      }
+
+      return HEX_REGEX.test(value)
+        ? new AccountID(Buffer.from(value, 'hex'))
+        : this.fromBase58(value)
+    }
+
+    throw new Error('Cannot construct AccountID from value given')
+  }
+
+  /**
+   * Defines how to build an AccountID from a base58 r-Address
+   *
+   * @param value a base58 r-Address
+   * @returns an AccountID object
+   */
+  static fromBase58(value: string): AccountID {
+    if (isValidXAddress(value)) {
+      const classic = xAddressToClassicAddress(value)
+
+      if (classic.tag !== false)
+        throw new Error('Only allowed to have tag on Account or Destination')
+
+      value = classic.classicAddress
+    }
+
+    return new AccountID(Buffer.from(decodeAccountID(value)))
+  }
+
+  /**
+   * Overload of toJSON
+   *
+   * @returns the base58 string for this AccountID
+   */
+  toJSON(): string {
+    return this.toBase58()
+  }
+
+  /**
+   * Defines how to encode AccountID into a base58 address
+   *
+   * @returns the base58 string defined by this.bytes
+   */
+  toBase58(): string {
+    /* eslint-disable @typescript-eslint/no-explicit-any */
+    return encodeAccountID(this.bytes as any)
+    /* eslint-enable @typescript-eslint/no-explicit-any */
+  }
+}
+
+export { AccountID }

package/src/types/amount.ts

@@ -0,0 +1,256 @@
+import { Decimal } from 'decimal.js'
+
+import { BinaryParser } from '../serdes/binary-parser'
+
+import { AccountID } from './account-id'
+import { Currency } from './currency'
+import { JsonObject, SerializedType } from './serialized-type'
+import bigInt = require('big-integer')
+import { Buffer } from 'buffer/'
+
+/**
+ * Constants for validating amounts
+ */
+const MIN_IOU_EXPONENT = -96
+const MAX_IOU_EXPONENT = 80
+const MAX_IOU_PRECISION = 16
+const MAX_DROPS = new Decimal('1e17')
+const MIN_XRP = new Decimal('1e-6')
+const mask = bigInt(0x00000000ffffffff)
+
+/**
+ * decimal.js configuration for Amount IOUs
+ */
+Decimal.config({
+  toExpPos: MAX_IOU_EXPONENT + MAX_IOU_PRECISION,
+  toExpNeg: MIN_IOU_EXPONENT - MAX_IOU_PRECISION,
+})
+
+/**
+ * Interface for JSON objects that represent amounts
+ */
+interface AmountObject extends JsonObject {
+  value: string
+  currency: string
+  issuer: string
+}
+
+/**
+ * Type guard for AmountObject
+ */
+function isAmountObject(arg): arg is AmountObject {
+  const keys = Object.keys(arg).sort()
+  return (
+    keys.length === 3 &&
+    keys[0] === 'currency' &&
+    keys[1] === 'issuer' &&
+    keys[2] === 'value'
+  )
+}
+
+/**
+ * Class for serializing/Deserializing Amounts
+ */
+class Amount extends SerializedType {
+  static defaultAmount: Amount = new Amount(
+    Buffer.from('4000000000000000', 'hex'),
+  )
+
+  constructor(bytes: Buffer) {
+    super(bytes ?? Amount.defaultAmount.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 Amount | AmountObject | string>(value: T): Amount {
+    if (value instanceof Amount) {
+      return value
+    }
+
+    let amount = Buffer.alloc(8)
+    if (typeof value === 'string') {
+      Amount.assertXrpIsValid(value)
+
+      const number = bigInt(value)
+
+      const intBuf = [Buffer.alloc(4), Buffer.alloc(4)]
+      intBuf[0].writeUInt32BE(Number(number.shiftRight(32)), 0)
+      intBuf[1].writeUInt32BE(Number(number.and(mask)), 0)
+
+      amount = Buffer.concat(intBuf)
+
+      amount[0] |= 0x40
+
+      return new Amount(amount)
+    }
+
+    if (isAmountObject(value)) {
+      const number = new Decimal(value.value)
+      Amount.assertIouIsValid(number)
+
+      if (number.isZero()) {
+        amount[0] |= 0x80
+      } else {
+        const integerNumberString = number
+          .times(`1e${-(number.e - 15)}`)
+          .abs()
+          .toString()
+
+        const num = bigInt(integerNumberString)
+        const intBuf = [Buffer.alloc(4), Buffer.alloc(4)]
+        intBuf[0].writeUInt32BE(Number(num.shiftRight(32)), 0)
+        intBuf[1].writeUInt32BE(Number(num.and(mask)), 0)
+
+        amount = Buffer.concat(intBuf)
+
+        amount[0] |= 0x80
+
+        if (number.gt(new Decimal(0))) {
+          amount[0] |= 0x40
+        }
+
+        const exponent = number.e - 15
+        const exponentByte = 97 + exponent
+        amount[0] |= exponentByte >>> 2
+        amount[1] |= (exponentByte & 0x03) << 6
+      }
+
+      const currency = Currency.from(value.currency).toBytes()
+      const issuer = AccountID.from(value.issuer).toBytes()
+      return new Amount(Buffer.concat([amount, 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): Amount {
+    const isXRP = parser.peek() & 0x80
+    const numBytes = isXRP ? 48 : 8
+    return new Amount(parser.read(numBytes))
+  }
+
+  /**
+   * Get the JSON representation of this Amount
+   *
+   * @returns the JSON interpretation of this.bytes
+   */
+  toJSON(): AmountObject | string {
+    if (this.isNative()) {
+      const bytes = this.bytes
+      const isPositive = bytes[0] & 0x40
+      const sign = isPositive ? '' : '-'
+      bytes[0] &= 0x3f
+
+      const msb = bigInt(bytes.slice(0, 4).readUInt32BE(0))
+      const lsb = bigInt(bytes.slice(4).readUInt32BE(0))
+      const num = msb.shiftLeft(32).or(lsb)
+
+      return `${sign}${num.toString()}`
+    } else {
+      const parser = new BinaryParser(this.toString())
+      const mantissa = parser.read(8)
+      const currency = Currency.fromParser(parser) as Currency
+      const issuer = AccountID.fromParser(parser) as AccountID
+
+      const b1 = mantissa[0]
+      const b2 = mantissa[1]
+
+      const isPositive = b1 & 0x40
+      const sign = isPositive ? '' : '-'
+      const exponent = ((b1 & 0x3f) << 2) + ((b2 & 0xff) >> 6) - 97
+
+      mantissa[0] = 0
+      mantissa[1] &= 0x3f
+      const value = new Decimal(`${sign}0x${mantissa.toString('hex')}`).times(
+        `1e${exponent}`,
+      )
+      Amount.assertIouIsValid(value)
+
+      return {
+        value: value.toString(),
+        currency: currency.toJSON(),
+        issuer: issuer.toJSON(),
+      }
+    }
+  }
+
+  /**
+   * Validate XRP amount
+   *
+   * @param amount String representing XRP amount
+   * @returns void, but will throw if invalid amount
+   */
+  private static assertXrpIsValid(amount: string): void {
+    if (amount.indexOf('.') !== -1) {
+      throw new Error(`${amount.toString()} is an illegal amount`)
+    }
+
+    const decimal = new Decimal(amount)
+    if (!decimal.isZero()) {
+      if (decimal.lt(MIN_XRP) || decimal.gt(MAX_DROPS)) {
+        throw new Error(`${amount.toString()} is an illegal amount`)
+      }
+    }
+  }
+
+  /**
+   * Validate IOU.value amount
+   *
+   * @param decimal Decimal.js object representing IOU.value
+   * @returns void, but will throw if invalid amount
+   */
+  private static assertIouIsValid(decimal: Decimal): void {
+    if (!decimal.isZero()) {
+      const p = decimal.precision()
+      const e = decimal.e - 15
+      if (
+        p > MAX_IOU_PRECISION ||
+        e > MAX_IOU_EXPONENT ||
+        e < MIN_IOU_EXPONENT
+      ) {
+        throw new Error('Decimal precision out of range')
+      }
+      this.verifyNoDecimal(decimal)
+    }
+  }
+
+  /**
+   * Ensure that the value after being multiplied by the exponent does not
+   * contain a decimal.
+   *
+   * @param decimal a Decimal object
+   * @returns a string of the object without a decimal
+   */
+  private static verifyNoDecimal(decimal: Decimal): void {
+    const integerNumberString = decimal
+      .times(`1e${-(decimal.e - 15)}`)
+      .abs()
+      .toString()
+
+    if (integerNumberString.indexOf('.') !== -1) {
+      throw new Error('Decimal place found in integerNumberString')
+    }
+  }
+
+  /**
+   * Test if this amount is in units of Native Currency(XRP)
+   *
+   * @returns true if Native (XRP)
+   */
+  private isNative(): boolean {
+    return (this.bytes[0] & 0x80) === 0
+  }
+}
+
+export { Amount, AmountObject }

package/src/types/blob.ts

@@ -0,0 +1,43 @@
+import { SerializedType } from './serialized-type'
+import { BinaryParser } from '../serdes/binary-parser'
+import { Buffer } from 'buffer/'
+
+/**
+ * Variable length encoded type
+ */
+class Blob extends SerializedType {
+  constructor(bytes: Buffer) {
+    super(bytes)
+  }
+
+  /**
+   * Defines how to read a Blob from a BinaryParser
+   *
+   * @param parser The binary parser to read the Blob from
+   * @param hint The length of the blob, computed by readVariableLengthLength() and passed in
+   * @returns A Blob object
+   */
+  static fromParser(parser: BinaryParser, hint: number): Blob {
+    return new Blob(parser.read(hint))
+  }
+
+  /**
+   * Create a Blob object from a hex-string
+   *
+   * @param value existing Blob object or a hex-string
+   * @returns A Blob object
+   */
+  static from<T extends Blob | string>(value: T): Blob {
+    if (value instanceof Blob) {
+      return value
+    }
+
+    if (typeof value === 'string') {
+      return new Blob(Buffer.from(value, 'hex'))
+    }
+
+    throw new Error('Cannot construct Blob from value given')
+  }
+}
+
+export { Blob }

package/src/types/currency.ts

@@ -0,0 +1,140 @@
+import { Hash160 } from './hash-160'
+import { Buffer } from 'buffer/'
+
+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): Buffer {
+  const bytes = Buffer.alloc(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: Buffer): string | null {
+  const iso = code.toString()
+  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 Buffer is a valid representation of a currency
+ */
+function isBytesArray(bytes: Buffer): boolean {
+  return bytes.byteLength === 20
+}
+
+/**
+ * Ensures that a value is a valid representation of a currency
+ */
+function isValidRepresentation(input: Buffer | string): boolean {
+  return input instanceof Buffer
+    ? isBytesArray(input)
+    : isStringRepresentation(input)
+}
+
+/**
+ * Generate bytes from a string or buffer representation of a currency
+ */
+function bytesFromRepresentation(input: string): Buffer {
+  if (!isValidRepresentation(input)) {
+    throw new Error(`Unsupported Currency representation: ${input}`)
+  }
+  return input.length === 3 ? isoToBytes(input) : Buffer.from(input, 'hex')
+}
+
+/**
+ * Class defining how to encode and decode Currencies
+ */
+class Currency extends Hash160 {
+  static readonly XRP = new Currency(Buffer.alloc(20))
+  private readonly _iso: string | null
+
+  constructor(byteBuf: Buffer) {
+    super(byteBuf ?? Currency.XRP.bytes)
+    const hex = this.bytes.toString('hex')
+
+    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 this.bytes.toString('hex').toUpperCase()
+  }
+}
+
+export { Currency }