ripple-binary-codec 1.7.1 → 1.9.0

package/src/ledger-hashes.ts

@@ -0,0 +1,187 @@
+import * as assert from 'assert'
+import { ShaMap, ShaMapNode, ShaMapLeaf } from './shamap'
+import { HashPrefix } from './hash-prefixes'
+import { Sha512Half } from './hashes'
+import { BinarySerializer, serializeObject } from './binary'
+import { Hash256 } from './types/hash-256'
+import { STObject } from './types/st-object'
+import { UInt64 } from './types/uint-64'
+import { UInt32 } from './types/uint-32'
+import { UInt8 } from './types/uint-8'
+import { BinaryParser } from './serdes/binary-parser'
+import { JsonObject } from './types/serialized-type'
+import bigInt = require('big-integer')
+import { XrplDefinitionsBase } from './enums'
+
+/**
+ * Computes the hash of a list of objects
+ *
+ * @param itemizer Converts an item into a format that can be added to SHAMap
+ * @param itemsJson Array of items to add to a SHAMap
+ * @returns the hash of the SHAMap
+ */
+function computeHash(
+  itemizer: (item: JsonObject) => [Hash256?, ShaMapNode?, ShaMapLeaf?],
+  itemsJson: Array<JsonObject>,
+): Hash256 {
+  const map = new ShaMap()
+  itemsJson.forEach((item) => map.addItem(...itemizer(item)))
+  return map.hash()
+}
+
+/**
+ * Interface describing a transaction item
+ */
+interface transactionItemObject extends JsonObject {
+  hash: string
+  metaData: JsonObject
+}
+
+/**
+ * Convert a transaction into an index and an item
+ *
+ * @param json transaction with metadata
+ * @returns a tuple of index and item to be added to SHAMap
+ */
+function transactionItemizer(
+  json: transactionItemObject,
+): [Hash256, ShaMapNode, undefined] {
+  assert.ok(json.hash)
+  const index = Hash256.from(json.hash)
+  const item = {
+    hashPrefix() {
+      return HashPrefix.transaction
+    },
+    toBytesSink(sink) {
+      const serializer = new BinarySerializer(sink)
+      serializer.writeLengthEncoded(STObject.from(json))
+      serializer.writeLengthEncoded(STObject.from(json.metaData))
+    },
+  } as ShaMapNode
+  return [index, item, undefined]
+}
+
+/**
+ * Interface describing an entry item
+ */
+interface entryItemObject extends JsonObject {
+  index: string
+}
+
+/**
+ * Convert an entry to a pair Hash256 and ShaMapNode
+ *
+ * @param json JSON describing a ledger entry item
+ * @returns a tuple of index and item to be added to SHAMap
+ */
+function entryItemizer(
+  json: entryItemObject,
+): [Hash256, ShaMapNode, undefined] {
+  const index = Hash256.from(json.index)
+  const bytes = serializeObject(json)
+  const item = {
+    hashPrefix() {
+      return HashPrefix.accountStateEntry
+    },
+    toBytesSink(sink) {
+      sink.put(bytes)
+    },
+  } as ShaMapNode
+  return [index, item, undefined]
+}
+
+/**
+ * Function computing the hash of a transaction tree
+ *
+ * @param param An array of transaction objects to hash
+ * @returns A Hash256 object
+ */
+function transactionTreeHash(param: Array<JsonObject>): Hash256 {
+  const itemizer = transactionItemizer as (
+    json: JsonObject,
+  ) => [Hash256, ShaMapNode, undefined]
+  return computeHash(itemizer, param)
+}
+
+/**
+ * Function computing the hash of accountState
+ *
+ * @param param A list of accountStates hash
+ * @returns A Hash256 object
+ */
+function accountStateHash(param: Array<JsonObject>): Hash256 {
+  const itemizer = entryItemizer as (
+    json: JsonObject,
+  ) => [Hash256, ShaMapNode, undefined]
+  return computeHash(itemizer, param)
+}
+
+/**
+ * Interface describing a ledger header
+ */
+interface ledgerObject {
+  ledger_index: number
+  total_coins: string | number | bigInt.BigInteger
+  parent_hash: string
+  transaction_hash: string
+  account_hash: string
+  parent_close_time: number
+  close_time: number
+  close_time_resolution: number
+  close_flags: number
+}
+
+/**
+ * Serialize and hash a ledger header
+ *
+ * @param header a ledger header
+ * @returns the hash of header
+ */
+function ledgerHash(header: ledgerObject): Hash256 {
+  const hash = new Sha512Half()
+  hash.put(HashPrefix.ledgerHeader)
+  assert.ok(header.parent_close_time !== undefined)
+  assert.ok(header.close_flags !== undefined)
+
+  UInt32.from<number>(header.ledger_index).toBytesSink(hash)
+  UInt64.from<bigInt.BigInteger>(
+    bigInt(String(header.total_coins)),
+  ).toBytesSink(hash)
+  Hash256.from<string>(header.parent_hash).toBytesSink(hash)
+  Hash256.from<string>(header.transaction_hash).toBytesSink(hash)
+  Hash256.from<string>(header.account_hash).toBytesSink(hash)
+  UInt32.from<number>(header.parent_close_time).toBytesSink(hash)
+  UInt32.from<number>(header.close_time).toBytesSink(hash)
+  UInt8.from<number>(header.close_time_resolution).toBytesSink(hash)
+  UInt8.from<number>(header.close_flags).toBytesSink(hash)
+  return hash.finish()
+}
+
+/**
+ * Decodes a serialized ledger header
+ *
+ * @param binary A serialized ledger header
+ * @param definitions Type definitions to parse the ledger objects.
+ *      Used if there are non-default ledger objects to decode.
+ * @returns A JSON object describing a ledger header
+ */
+function decodeLedgerData(
+  binary: string,
+  definitions?: XrplDefinitionsBase,
+): object {
+  assert.ok(typeof binary === 'string', 'binary must be a hex string')
+  const parser = new BinaryParser(binary, definitions)
+  return {
+    ledger_index: parser.readUInt32(),
+    total_coins: parser.readType(UInt64).valueOf().toString(),
+    parent_hash: parser.readType(Hash256).toHex(),
+    transaction_hash: parser.readType(Hash256).toHex(),
+    account_hash: parser.readType(Hash256).toHex(),
+    parent_close_time: parser.readUInt32(),
+    close_time: parser.readUInt32(),
+    close_time_resolution: parser.readUInt8(),
+    close_flags: parser.readUInt8(),
+  }
+}
+
+export { accountStateHash, transactionTreeHash, ledgerHash, decodeLedgerData }

package/src/quality.ts

@@ -0,0 +1,39 @@
+import { coreTypes } from './types'
+import { Decimal } from 'decimal.js'
+import bigInt = require('big-integer')
+import { Buffer } from 'buffer/'
+
+/**
+ * class for encoding and decoding quality
+ */
+class quality {
+  /**
+   * Encode quality amount
+   *
+   * @param arg string representation of an amount
+   * @returns Serialized quality
+   */
+  static encode(quality: string): Buffer {
+    const decimal = new Decimal(quality)
+    const exponent = decimal.e - 15
+    const qualityString = decimal.times(`1e${-exponent}`).abs().toString()
+    const bytes = coreTypes.UInt64.from(bigInt(qualityString)).toBytes()
+    bytes[0] = exponent + 100
+    return bytes
+  }
+
+  /**
+   * Decode quality amount
+   *
+   * @param arg hex-string denoting serialized quality
+   * @returns deserialized quality
+   */
+  static decode(quality: string): Decimal {
+    const bytes = Buffer.from(quality, 'hex').slice(-8)
+    const exponent = bytes[0] - 100
+    const mantissa = new Decimal(`0x${bytes.slice(1).toString('hex')}`)
+    return mantissa.times(`1e${exponent}`)
+  }
+}
+
+export { quality }

package/src/serdes/binary-parser.ts

@@ -0,0 +1,217 @@
+import * as assert from 'assert'
+import {
+  XrplDefinitionsBase,
+  DEFAULT_DEFINITIONS,
+  FieldInstance,
+} from '../enums'
+import { type SerializedType } from '../types/serialized-type'
+import { Buffer } from 'buffer/'
+
+/**
+ * BinaryParser is used to compute fields and values from a HexString
+ */
+class BinaryParser {
+  private bytes: Buffer
+  definitions: XrplDefinitionsBase
+
+  /**
+   * Initialize bytes to a hex string
+   *
+   * @param hexBytes a hex string
+   * @param definitions Rippled definitions used to parse the values of transaction types and such.
+   *                          Can be customized for sidechains and amendments.
+   */
+  constructor(
+    hexBytes: string,
+    definitions: XrplDefinitionsBase = DEFAULT_DEFINITIONS,
+  ) {
+    this.bytes = Buffer.from(hexBytes, 'hex')
+    this.definitions = definitions
+  }
+
+  /**
+   * Peek the first byte of the BinaryParser
+   *
+   * @returns The first byte of the BinaryParser
+   */
+  peek(): number {
+    assert.ok(this.bytes.byteLength !== 0)
+    return this.bytes[0]
+  }
+
+  /**
+   * Consume the first n bytes of the BinaryParser
+   *
+   * @param n the number of bytes to skip
+   */
+  skip(n: number): void {
+    assert.ok(n <= this.bytes.byteLength)
+    this.bytes = this.bytes.slice(n)
+  }
+
+  /**
+   * read the first n bytes from the BinaryParser
+   *
+   * @param n The number of bytes to read
+   * @return The bytes
+   */
+  read(n: number): Buffer {
+    assert.ok(n <= this.bytes.byteLength)
+
+    const slice = this.bytes.slice(0, n)
+    this.skip(n)
+    return slice
+  }
+
+  /**
+   * Read an integer of given size
+   *
+   * @param n The number of bytes to read
+   * @return The number represented by those bytes
+   */
+  readUIntN(n: number): number {
+    assert.ok(0 < n && n <= 4, 'invalid n')
+    return this.read(n).reduce((a, b) => (a << 8) | b) >>> 0
+  }
+
+  readUInt8(): number {
+    return this.readUIntN(1)
+  }
+
+  readUInt16(): number {
+    return this.readUIntN(2)
+  }
+
+  readUInt32(): number {
+    return this.readUIntN(4)
+  }
+
+  size(): number {
+    return this.bytes.byteLength
+  }
+
+  end(customEnd?: number): boolean {
+    const length = this.bytes.byteLength
+    return length === 0 || (customEnd !== undefined && length <= customEnd)
+  }
+
+  /**
+   * Reads variable length encoded bytes
+   *
+   * @return The variable length bytes
+   */
+  readVariableLength(): Buffer {
+    return this.read(this.readVariableLengthLength())
+  }
+
+  /**
+   * Reads the length of the variable length encoded bytes
+   *
+   * @return The length of the variable length encoded bytes
+   */
+  readVariableLengthLength(): number {
+    const b1 = this.readUInt8()
+    if (b1 <= 192) {
+      return b1
+    } else if (b1 <= 240) {
+      const b2 = this.readUInt8()
+      return 193 + (b1 - 193) * 256 + b2
+    } else if (b1 <= 254) {
+      const b2 = this.readUInt8()
+      const b3 = this.readUInt8()
+      return 12481 + (b1 - 241) * 65536 + b2 * 256 + b3
+    }
+    throw new Error('Invalid variable length indicator')
+  }
+
+  /**
+   * Reads the field ordinal from the BinaryParser
+   *
+   * @return Field ordinal
+   */
+  readFieldOrdinal(): number {
+    let type = this.readUInt8()
+    let nth = type & 15
+    type >>= 4
+
+    if (type === 0) {
+      type = this.readUInt8()
+      if (type === 0 || type < 16) {
+        throw new Error('Cannot read FieldOrdinal, type_code out of range')
+      }
+    }
+
+    if (nth === 0) {
+      nth = this.readUInt8()
+      if (nth === 0 || nth < 16) {
+        throw new Error('Cannot read FieldOrdinal, field_code out of range')
+      }
+    }
+
+    return (type << 16) | nth
+  }
+
+  /**
+   * Read the field from the BinaryParser
+   *
+   * @return The field represented by the bytes at the head of the BinaryParser
+   */
+  readField(): FieldInstance {
+    return this.definitions.field.fromString(this.readFieldOrdinal().toString())
+  }
+
+  /**
+   * Read a given type from the BinaryParser
+   *
+   * @param type The type that you want to read from the BinaryParser
+   * @return The instance of that type read from the BinaryParser
+   */
+  readType(type: typeof SerializedType): SerializedType {
+    return type.fromParser(this)
+  }
+
+  /**
+   * Get the type associated with a given field
+   *
+   * @param field The field that you wan to get the type of
+   * @return The type associated with the given field
+   */
+  typeForField(field: FieldInstance): typeof SerializedType {
+    return field.associatedType
+  }
+
+  /**
+   * Read value of the type specified by field from the BinaryParser
+   *
+   * @param field The field that you want to get the associated value for
+   * @return The value associated with the given field
+   */
+  readFieldValue(field: FieldInstance): SerializedType {
+    const type = this.typeForField(field)
+    if (!type) {
+      throw new Error(`unsupported: (${field.name}, ${field.type.name})`)
+    }
+    const sizeHint = field.isVariableLengthEncoded
+      ? this.readVariableLengthLength()
+      : undefined
+    const value = type.fromParser(this, sizeHint)
+    if (value === undefined) {
+      throw new Error(
+        `fromParser for (${field.name}, ${field.type.name}) -> undefined `,
+      )
+    }
+    return value
+  }
+
+  /**
+   * Get the next field and value from the BinaryParser
+   *
+   * @return The field and value
+   */
+  readFieldAndValue(): [FieldInstance, SerializedType] {
+    const field = this.readField()
+    return [field, this.readFieldValue(field)]
+  }
+}
+
+export { BinaryParser }

package/src/serdes/binary-serializer.ts

@@ -0,0 +1,166 @@
+import * as assert from 'assert'
+import { FieldInstance } from '../enums'
+import { type SerializedType } from '../types/serialized-type'
+import { Buffer } from 'buffer/'
+
+/**
+ * Bytes list is a collection of buffer objects
+ */
+class BytesList {
+  private bytesArray: Array<Buffer> = []
+
+  /**
+   * Get the total number of bytes in the BytesList
+   *
+   * @return the number of bytes
+   */
+  public getLength(): number {
+    return Buffer.concat(this.bytesArray).byteLength
+  }
+
+  /**
+   * Put bytes in the BytesList
+   *
+   * @param bytesArg A Buffer
+   * @return this BytesList
+   */
+  public put(bytesArg: Buffer): BytesList {
+    const bytes = Buffer.from(bytesArg) // Temporary, to catch instances of Uint8Array being passed in
+    this.bytesArray.push(bytes)
+    return this
+  }
+
+  /**
+   * Write this BytesList to the back of another bytes list
+   *
+   *  @param list The BytesList to write to
+   */
+  public toBytesSink(list: BytesList): void {
+    list.put(this.toBytes())
+  }
+
+  public toBytes(): Buffer {
+    return Buffer.concat(this.bytesArray)
+  }
+
+  toHex(): string {
+    return this.toBytes().toString('hex').toUpperCase()
+  }
+}
+
+/**
+ * BinarySerializer is used to write fields and values to buffers
+ */
+class BinarySerializer {
+  private sink: BytesList = new BytesList()
+
+  constructor(sink: BytesList) {
+    this.sink = sink
+  }
+
+  /**
+   * Write a value to this BinarySerializer
+   *
+   * @param value a SerializedType value
+   */
+  write(value: SerializedType): void {
+    value.toBytesSink(this.sink)
+  }
+
+  /**
+   * Write bytes to this BinarySerializer
+   *
+   * @param bytes the bytes to write
+   */
+  put(bytes: Buffer): void {
+    this.sink.put(bytes)
+  }
+
+  /**
+   * Write a value of a given type to this BinarySerializer
+   *
+   * @param type the type to write
+   * @param value a value of that type
+   */
+  writeType(type: typeof SerializedType, value: SerializedType): void {
+    this.write(type.from(value))
+  }
+
+  /**
+   * Write BytesList to this BinarySerializer
+   *
+   * @param bl BytesList to write to BinarySerializer
+   */
+  writeBytesList(bl: BytesList): void {
+    bl.toBytesSink(this.sink)
+  }
+
+  /**
+   * Calculate the header of Variable Length encoded bytes
+   *
+   * @param length the length of the bytes
+   */
+  private encodeVariableLength(length: number): Buffer {
+    const lenBytes = Buffer.alloc(3)
+    if (length <= 192) {
+      lenBytes[0] = length
+      return lenBytes.slice(0, 1)
+    } else if (length <= 12480) {
+      length -= 193
+      lenBytes[0] = 193 + (length >>> 8)
+      lenBytes[1] = length & 0xff
+      return lenBytes.slice(0, 2)
+    } else if (length <= 918744) {
+      length -= 12481
+      lenBytes[0] = 241 + (length >>> 16)
+      lenBytes[1] = (length >> 8) & 0xff
+      lenBytes[2] = length & 0xff
+      return lenBytes.slice(0, 3)
+    }
+    throw new Error('Overflow error')
+  }
+
+  /**
+   * Write field and value to BinarySerializer
+   *
+   * @param field field to write to BinarySerializer
+   * @param value value to write to BinarySerializer
+   */
+  writeFieldAndValue(
+    field: FieldInstance,
+    value: SerializedType,
+    isUnlModifyWorkaround = false,
+  ): void {
+    const associatedValue = field.associatedType.from(value)
+    assert.ok(associatedValue.toBytesSink !== undefined)
+    assert.ok(field.name !== undefined)
+
+    this.sink.put(field.header)
+
+    if (field.isVariableLengthEncoded) {
+      this.writeLengthEncoded(associatedValue, isUnlModifyWorkaround)
+    } else {
+      associatedValue.toBytesSink(this.sink)
+    }
+  }
+
+  /**
+   * Write a variable length encoded value to the BinarySerializer
+   *
+   * @param value length encoded value to write to BytesList
+   */
+  public writeLengthEncoded(
+    value: SerializedType,
+    isUnlModifyWorkaround = false,
+  ): void {
+    const bytes = new BytesList()
+    if (!isUnlModifyWorkaround) {
+      // this part doesn't happen for the Account field in a UNLModify transaction
+      value.toBytesSink(bytes)
+    }
+    this.put(this.encodeVariableLength(bytes.getLength()))
+    this.writeBytesList(bytes)
+  }
+}
+
+export { BytesList, BinarySerializer }