ripple-binary-codec 2.0.0 → 2.2.0

package/src/serdes/binary-parser.ts

@@ -144,14 +144,18 @@ class BinaryParser {
     if (type === 0) {
       type = this.readUInt8()
       if (type === 0 || type < 16) {
-        throw new Error('Cannot read FieldOrdinal, type_code out of range')
+        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 out of range')
+        throw new Error(
+          `Cannot read FieldOrdinal, field_code ${nth} out of range`,
+        )
       }
     }
 

package/src/types/amount.ts

@@ -6,6 +6,7 @@ import { JsonObject, SerializedType } from './serialized-type'
 import BigNumber from 'bignumber.js'
 import { bytesToHex, concat, hexToBytes } from '@xrplf/isomorphic/utils'
 import { readUInt32BE, writeUInt32BE } from '../utils'
+import { Hash192 } from './hash-192'
 
 /**
  * Constants for validating amounts
@@ -16,6 +17,7 @@ const MAX_IOU_PRECISION = 16
 const MAX_DROPS = new BigNumber('1e17')
 const MIN_XRP = new BigNumber('1e-6')
 const mask = BigInt(0x00000000ffffffff)
+const mptMask = BigInt(0x8000000000000000)
 
 /**
  * BigNumber configuration for Amount IOUs
@@ -27,20 +29,28 @@ BigNumber.config({
   ],
 })
 
-/**
- * Interface for JSON objects that represent amounts
- */
-interface AmountObject extends JsonObject {
+interface AmountObjectIOU extends JsonObject {
   value: string
   currency: string
   issuer: string
 }
 
+interface AmountObjectMPT extends JsonObject {
+  value: string
+  mpt_issuance_id: string
+}
+
+/**
+ * Interface for JSON objects that represent amounts
+ */
+type AmountObject = AmountObjectIOU | AmountObjectMPT
+
 /**
- * Type guard for AmountObject
+ * Type guard for AmountObjectIOU
  */
-function isAmountObject(arg): arg is AmountObject {
+function isAmountObjectIOU(arg): arg is AmountObjectIOU {
   const keys = Object.keys(arg).sort()
+
   return (
     keys.length === 3 &&
     keys[0] === 'currency' &&
@@ -49,6 +59,17 @@ function isAmountObject(arg): arg is AmountObject {
   )
 }
 
+/**
+ * Type guard for AmountObjectMPT
+ */
+function isAmountObjectMPT(arg): arg is AmountObjectMPT {
+  const keys = Object.keys(arg).sort()
+
+  return (
+    keys.length === 2 && keys[0] === 'mpt_issuance_id' && keys[1] === 'value'
+  )
+}
+
 /**
  * Class for serializing/Deserializing Amounts
  */
@@ -60,7 +81,7 @@ class Amount extends SerializedType {
   }
 
   /**
-   * Construct an amount from an IOU or string amount
+   * Construct an amount from an IOU, MPT or string amount
    *
    * @param value An Amount, object representing an IOU, or a string
    *     representing an integer amount
@@ -88,7 +109,7 @@ class Amount extends SerializedType {
       return new Amount(amount)
     }
 
-    if (isAmountObject(value)) {
+    if (isAmountObjectIOU(value)) {
       const number = new BigNumber(value.value)
       Amount.assertIouIsValid(number)
 
@@ -124,6 +145,24 @@ class Amount extends SerializedType {
       return new Amount(concat([amount, currency, issuer]))
     }
 
+    if (isAmountObjectMPT(value)) {
+      Amount.assertMptIsValid(value.value)
+
+      let leadingByte = new Uint8Array(1)
+      leadingByte[0] |= 0x60
+
+      const num = BigInt(value.value)
+
+      const intBuf = [new Uint8Array(4), new Uint8Array(4)]
+      writeUInt32BE(intBuf[0], Number(num >> BigInt(32)), 0)
+      writeUInt32BE(intBuf[1], Number(num & BigInt(mask)), 0)
+
+      amount = concat(intBuf)
+
+      const mptIssuanceID = Hash192.from(value.mpt_issuance_id).toBytes()
+      return new Amount(concat([leadingByte, amount, mptIssuanceID]))
+    }
+
     throw new Error('Invalid type to construct an Amount')
   }
 
@@ -134,8 +173,12 @@ class Amount extends SerializedType {
    * @returns An Amount object
    */
   static fromParser(parser: BinaryParser): Amount {
-    const isXRP = parser.peek() & 0x80
-    const numBytes = isXRP ? 48 : 8
+    const isIOU = parser.peek() & 0x80
+    if (isIOU) return new Amount(parser.read(48))
+
+    // the amount can be either MPT or XRP at this point
+    const isMPT = parser.peek() & 0x20
+    const numBytes = isMPT ? 33 : 8
     return new Amount(parser.read(numBytes))
   }
 
@@ -156,7 +199,9 @@ class Amount extends SerializedType {
       const num = (msb << BigInt(32)) | lsb
 
       return `${sign}${num.toString()}`
-    } else {
+    }
+
+    if (this.isIOU()) {
       const parser = new BinaryParser(this.toString())
       const mantissa = parser.read(8)
       const currency = Currency.fromParser(parser) as Currency
@@ -182,6 +227,27 @@ class Amount extends SerializedType {
         issuer: issuer.toJSON(),
       }
     }
+
+    if (this.isMPT()) {
+      const parser = new BinaryParser(this.toString())
+      const leadingByte = parser.read(1)
+      const amount = parser.read(8)
+      const mptID = Hash192.fromParser(parser) as Hash192
+
+      const isPositive = leadingByte[0] & 0x40
+      const sign = isPositive ? '' : '-'
+
+      const msb = BigInt(readUInt32BE(amount.slice(0, 4), 0))
+      const lsb = BigInt(readUInt32BE(amount.slice(4), 0))
+      const num = (msb << BigInt(32)) | lsb
+
+      return {
+        value: `${sign}${num.toString()}`,
+        mpt_issuance_id: mptID.toString(),
+      }
+    }
+
+    throw new Error('Invalid amount to construct JSON')
   }
 
   /**
@@ -224,6 +290,29 @@ class Amount extends SerializedType {
     }
   }
 
+  /**
+   * Validate MPT.value amount
+   *
+   * @param decimal BigNumber object representing MPT.value
+   * @returns void, but will throw if invalid amount
+   */
+  private static assertMptIsValid(amount: string): void {
+    if (amount.indexOf('.') !== -1) {
+      throw new Error(`${amount.toString()} is an illegal amount`)
+    }
+
+    const decimal = new BigNumber(amount)
+    if (!decimal.isZero()) {
+      if (decimal < BigNumber(0)) {
+        throw new Error(`${amount.toString()} is an illegal amount`)
+      }
+
+      if (Number(BigInt(amount) & BigInt(mptMask)) != 0) {
+        throw new Error(`${amount.toString()} is an illegal amount`)
+      }
+    }
+  }
+
   /**
    * Ensure that the value after being multiplied by the exponent does not
    * contain a decimal.
@@ -248,7 +337,25 @@ class Amount extends SerializedType {
    * @returns true if Native (XRP)
    */
   private isNative(): boolean {
-    return (this.bytes[0] & 0x80) === 0
+    return (this.bytes[0] & 0x80) === 0 && (this.bytes[0] & 0x20) === 0
+  }
+
+  /**
+   * Test if this amount is in units of MPT
+   *
+   * @returns true if MPT
+   */
+  private isMPT(): boolean {
+    return (this.bytes[0] & 0x80) === 0 && (this.bytes[0] & 0x20) !== 0
+  }
+
+  /**
+   * Test if this amount is in units of IOU
+   *
+   * @returns true if IOU
+   */
+  private isIOU(): boolean {
+    return (this.bytes[0] & 0x80) !== 0
   }
 }
 

package/src/types/blob.ts

@@ -33,6 +33,9 @@ class Blob extends SerializedType {
     }
 
     if (typeof value === 'string') {
+      if (!/^[A-F0-9]*$/iu.test(value)) {
+        throw new Error('Cannot construct Blob from a non-hex string')
+      }
       return new Blob(hexToBytes(value))
     }
 

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/index.ts

@@ -4,6 +4,7 @@ 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'
@@ -25,6 +26,7 @@ const coreTypes: Record<string, typeof SerializedType> = {
   Currency,
   Hash128,
   Hash160,
+  Hash192,
   Hash256,
   Issue,
   PathSet,
@@ -51,6 +53,7 @@ export {
   Currency,
   Hash128,
   Hash160,
+  Hash192,
   Hash256,
   PathSet,
   STArray,

package/src/types/serialized-type.ts

@@ -67,7 +67,7 @@ class SerializedType {
    *                          Can be customized for sidechains and amendments.
    * @returns any type, if not overloaded returns hexString representation of bytes
    */
-  toJSON(_definitions?: XrplDefinitionsBase): JSON {
+  toJSON(_definitions?: XrplDefinitionsBase, _fieldName?: string): JSON {
     return this.toHex()
   }
 

package/src/types/st-array.ts

@@ -14,7 +14,13 @@ const OBJECT_END_MARKER = Uint8Array.from([0xe1])
  */
 function isObjects(args): args is Array<JsonObject> {
   return (
-    Array.isArray(args) && (args.length === 0 || typeof args[0] === 'object')
+    Array.isArray(args) &&
+    args.every(
+      (arg) =>
+        typeof arg === 'object' &&
+        Object.keys(arg).length === 1 &&
+        typeof Object.values(arg)[0] === 'object',
+    )
   )
 }
 

package/src/types/st-object.ts

@@ -10,6 +10,7 @@ import { BinaryParser } from '../serdes/binary-parser'
 import { BinarySerializer, BytesList } from '../serdes/binary-serializer'
 
 import { STArray } from './st-array'
+import { UInt64 } from './uint-64'
 
 const OBJECT_END_MARKER_BYTE = Uint8Array.from([0xe1])
 const OBJECT_END_MARKER = 'ObjectEndMarker'
@@ -137,6 +138,8 @@ class STObject extends SerializedType {
           ? this.from(xAddressDecoded[field.name], undefined, definitions)
           : field.type.name === 'STArray'
           ? STArray.from(xAddressDecoded[field.name], definitions)
+          : field.type.name === 'UInt64'
+          ? UInt64.from(xAddressDecoded[field.name], field.name)
           : field.associatedType.from(xAddressDecoded[field.name])
 
       if (associatedValue == undefined) {
@@ -182,7 +185,7 @@ class STObject extends SerializedType {
 
       accumulator[field.name] = objectParser
         .readFieldValue(field)
-        .toJSON(definitions)
+        .toJSON(definitions, field.name)
     }
 
     return accumulator

package/src/types/uint-64.ts

@@ -2,10 +2,20 @@ import { UInt } from './uint'
 import { BinaryParser } from '../serdes/binary-parser'
 import { bytesToHex, concat, hexToBytes } from '@xrplf/isomorphic/utils'
 import { readUInt32BE, writeUInt32BE } from '../utils'
+import { DEFAULT_DEFINITIONS, XrplDefinitionsBase } from '../enums'
 
 const HEX_REGEX = /^[a-fA-F0-9]{1,16}$/
+const BASE10_REGEX = /^[0-9]{1,20}$/
 const mask = BigInt(0x00000000ffffffff)
 
+function useBase10(fieldName: string): boolean {
+  return (
+    fieldName === 'MaximumAmount' ||
+    fieldName === 'OutstandingAmount' ||
+    fieldName === 'MPTAmount'
+  )
+}
+
 /**
  * Derived UInt class for serializing/deserializing 64 bit UInt
  */
@@ -29,7 +39,10 @@ class UInt64 extends UInt {
    * @param val A UInt64, hex-string, bigInt, or number
    * @returns A UInt64 object
    */
-  static from<T extends UInt64 | string | bigint | number>(val: T): UInt64 {
+  static from<T extends UInt64 | string | bigint | number>(
+    val: T,
+    fieldName = '',
+  ): UInt64 {
     if (val instanceof UInt64) {
       return val
     }
@@ -51,11 +64,18 @@ class UInt64 extends UInt {
     }
 
     if (typeof val === 'string') {
-      if (!HEX_REGEX.test(val)) {
+      if (useBase10(fieldName)) {
+        if (!BASE10_REGEX.test(val)) {
+          throw new Error(`${fieldName} ${val} is not a valid base 10 string`)
+        }
+        val = BigInt(val).toString(16) as T
+      }
+
+      if (typeof val === 'string' && !HEX_REGEX.test(val)) {
         throw new Error(`${val} is not a valid hex-string`)
       }
 
-      const strBuf = val.padStart(16, '0')
+      const strBuf = (val as string).padStart(16, '0')
       buf = hexToBytes(strBuf)
       return new UInt64(buf)
     }
@@ -76,8 +96,16 @@ class UInt64 extends UInt {
    *
    * @returns a hex-string
    */
-  toJSON(): string {
-    return bytesToHex(this.bytes)
+  toJSON(
+    _definitions: XrplDefinitionsBase = DEFAULT_DEFINITIONS,
+    fieldName = '',
+  ): string {
+    const hexString = bytesToHex(this.bytes)
+    if (useBase10(fieldName)) {
+      return BigInt('0x' + hexString).toString(10)
+    }
+
+    return hexString
   }
 
   /**