@transia/ripple-binary-codec 1.4.6-alpha.8 → 2.5.1

package/src/index.ts

@@ -0,0 +1,166 @@
+import { quality, binary, HashPrefix } from './coretypes'
+import { decodeLedgerData } from './ledger-hashes'
+import { ClaimObject, BatchObject } from './binary'
+import { JsonObject } from './types/serialized-type'
+import {
+  XrplDefinitionsBase,
+  TRANSACTION_TYPES,
+  DEFAULT_DEFINITIONS,
+} from './enums'
+import { XrplDefinitions } from './enums/xrpl-definitions'
+import { coreTypes } from './types'
+import { bytesToHex } from '@transia/isomorphic/utils'
+
+const {
+  signingData,
+  signingClaimData,
+  multiSigningData,
+  signingBatchData,
+  binaryToJSON,
+  serializeObject,
+} = binary
+
+/**
+ * Decode a transaction
+ *
+ * @param binary hex-string of the encoded transaction
+ * @param definitions Custom rippled types to use instead of the default. Used for sidechains and amendments.
+ * @returns the JSON representation of the transaction
+ */
+function decode(binary: string, definitions?: XrplDefinitionsBase): JsonObject {
+  if (typeof binary !== 'string') {
+    throw new Error('binary must be a hex string')
+  }
+  return binaryToJSON(binary, definitions)
+}
+
+/**
+ * Encode a transaction
+ *
+ * @param json The JSON representation of a transaction
+ * @param definitions Custom rippled types to use instead of the default. Used for sidechains and amendments.
+ *
+ * @returns A hex-string of the encoded transaction
+ */
+function encode(json: object, definitions?: XrplDefinitionsBase): string {
+  if (typeof json !== 'object') {
+    throw new Error()
+  }
+  return bytesToHex(serializeObject(json as JsonObject, { definitions }))
+}
+
+/**
+ * Encode a transaction and prepare for signing
+ *
+ * @param json JSON object representing the transaction
+ * @param signer string representing the account to sign the transaction with
+ * @param definitions Custom rippled types to use instead of the default. Used for sidechains and amendments.
+ * @returns a hex string of the encoded transaction
+ */
+function encodeForSigning(
+  json: object,
+  definitions?: XrplDefinitionsBase,
+): string {
+  if (typeof json !== 'object') {
+    throw new Error()
+  }
+  return bytesToHex(
+    signingData(json as JsonObject, HashPrefix.transactionSig, {
+      definitions,
+    }),
+  )
+}
+
+/**
+ * Encode a payment channel claim for signing.
+ *
+ * @param json JSON object representing the claim.
+ * @returns a hex string of the encoded claim.
+ */
+function encodeForSigningClaim(json: object): string {
+  if (typeof json !== 'object') {
+    throw new Error()
+  }
+  return bytesToHex(signingClaimData(json as ClaimObject))
+}
+
+/**
+ * Encode a transaction and prepare for multi-signing.
+ *
+ * @param json JSON object representing the transaction.
+ * @param signer string representing the account to sign the transaction with.
+ * @param definitions Custom rippled types to use instead of the default. Used for sidechains and amendments.
+ * @returns a hex string of the encoded transaction.
+ */
+function encodeForMultisigning(
+  json: object,
+  signer: string,
+  definitions?: XrplDefinitionsBase,
+): string {
+  if (typeof json !== 'object') {
+    throw new Error()
+  }
+  if (json['SigningPubKey'] !== '') {
+    throw new Error()
+  }
+  const definitionsOpt = definitions ? { definitions } : undefined
+  return bytesToHex(
+    multiSigningData(json as JsonObject, signer, definitionsOpt),
+  )
+}
+
+/**
+ * Encode a Batch transaction for signing.
+ *
+ * @param json JSON object representing the transaction.
+ * @returns a hex string of the encoded transaction.
+ */
+function encodeForSigningBatch(json: object): string {
+  if (typeof json !== 'object') {
+    throw new Error('Need an object to encode a Batch transaction')
+  }
+  return bytesToHex(signingBatchData(json as BatchObject))
+}
+
+/**
+ * Encode a quality value
+ *
+ * @param value string representation of a number
+ * @returns a hex-string representing the quality
+ */
+function encodeQuality(value: string): string {
+  if (typeof value !== 'string') {
+    throw new Error()
+  }
+  return bytesToHex(quality.encode(value))
+}
+
+/**
+ * Decode a quality value
+ *
+ * @param value hex-string of a quality
+ * @returns a string representing the quality
+ */
+function decodeQuality(value: string): string {
+  if (typeof value !== 'string') {
+    throw new Error()
+  }
+  return quality.decode(value).toString()
+}
+
+export {
+  decode,
+  encode,
+  encodeForSigning,
+  encodeForSigningClaim,
+  encodeForMultisigning,
+  encodeForSigningBatch,
+  encodeQuality,
+  decodeQuality,
+  decodeLedgerData,
+  TRANSACTION_TYPES,
+  XrplDefinitions,
+  XrplDefinitionsBase,
+  DEFAULT_DEFINITIONS,
+  coreTypes,
+}

package/src/ledger-hashes.ts

@@ -0,0 +1,191 @@
+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 { 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] {
+  if (!json.hash) {
+    throw new Error()
+  }
+  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
+  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)
+  if (
+    header.parent_close_time === undefined ||
+    header.close_flags === undefined
+  ) {
+    throw new Error()
+  }
+
+  UInt32.from<number>(header.ledger_index).toBytesSink(hash)
+  UInt64.from<bigint>(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 {
+  if (typeof binary !== 'string') {
+    throw new Error('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,38 @@
+import { coreTypes } from './types'
+import BigNumber from 'bignumber.js'
+import { bytesToHex, hexToBytes } from '@transia/isomorphic/utils'
+
+/**
+ * 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): Uint8Array {
+    const decimal = BigNumber(quality)
+    const exponent = (decimal?.e || 0) - 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): BigNumber {
+    const bytes = hexToBytes(quality).slice(-8)
+    const exponent = bytes[0] - 100
+    const mantissa = new BigNumber(`0x${bytesToHex(bytes.slice(1))}`)
+    return mantissa.times(`1e${exponent}`)
+  }
+}
+
+export { quality }

package/src/serdes/binary-parser.ts

@@ -0,0 +1,228 @@
+import {
+  XrplDefinitionsBase,
+  DEFAULT_DEFINITIONS,
+  FieldInstance,
+} from '../enums'
+import { type SerializedType } from '../types/serialized-type'
+import { hexToBytes } from '@transia/isomorphic/utils'
+
+/**
+ * BinaryParser is used to compute fields and values from a HexString
+ */
+class BinaryParser {
+  private bytes: Uint8Array
+  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 = hexToBytes(hexBytes)
+    this.definitions = definitions
+  }
+
+  /**
+   * Peek the first byte of the BinaryParser
+   *
+   * @returns The first byte of the BinaryParser
+   */
+  peek(): number {
+    if (this.bytes.byteLength === 0) {
+      throw new Error()
+    }
+    return this.bytes[0]
+  }
+
+  /**
+   * Consume the first n bytes of the BinaryParser
+   *
+   * @param n the number of bytes to skip
+   */
+  skip(n: number): void {
+    if (n > this.bytes.byteLength) {
+      throw new Error()
+    }
+    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): Uint8Array {
+    if (n > this.bytes.byteLength) {
+      throw new Error()
+    }
+
+    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 {
+    if (0 >= n || n > 4) {
+      throw new Error('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(): Uint8Array {
+    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 ${type} out of range`,
+        )
+      }
+    }
+
+    if (nth === 0) {
+      nth = this.readUInt8()
+      if (nth === 0 || nth < 16) {
+        throw new Error(
+          `Cannot read FieldOrdinal, field_code ${nth} 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 }