ripple-binary-codec 2.7.0 → 2.8.0-smartcontract.0

package/src/quality.ts

@@ -13,8 +13,13 @@ class quality {
    * @returns Serialized quality
    */
   static encode(quality: string): Uint8Array {
-    const decimal = BigNumber(quality)
-    const exponent = (decimal?.e || 0) - 15
+    let decimal: BigNumber
+    try {
+      decimal = new BigNumber(quality)
+    } catch (_err) {
+      throw new Error(`${quality} is not a valid 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
@@ -30,7 +35,12 @@ class 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))}`)
+    let mantissa: BigNumber
+    try {
+      mantissa = new BigNumber(`0x${bytesToHex(bytes.slice(1))}`)
+    } catch (_err) {
+      throw new Error(`${quality} is not a valid quality`)
+    }
     return mantissa.times(`1e${exponent}`)
   }
 }

package/src/serdes/binary-parser.ts

@@ -46,8 +46,13 @@ class BinaryParser {
    * @param n the number of bytes to skip
    */
   skip(n: number): void {
+    if (n < 0) {
+      throw new Error(`skip: negative length ${n}`)
+    }
     if (n > this.bytes.byteLength) {
-      throw new Error()
+      throw new Error(
+        `skip: requested ${n} bytes but only ${this.bytes.byteLength} available`,
+      )
     }
     this.bytes = this.bytes.slice(n)
   }
@@ -59,8 +64,13 @@ class BinaryParser {
    * @return The bytes
    */
   read(n: number): Uint8Array {
+    if (n < 0) {
+      throw new Error(`read: negative length ${n}`)
+    }
     if (n > this.bytes.byteLength) {
-      throw new Error()
+      throw new Error(
+        `read: requested ${n} bytes but only ${this.bytes.byteLength} available`,
+      )
     }
 
     const slice = this.bytes.slice(0, n)

package/src/serdes/binary-serializer.ts

@@ -99,7 +99,7 @@ class BinarySerializer {
    *
    * @param length the length of the bytes
    */
-  private encodeVariableLength(length: number): Uint8Array {
+  static encodeVariableLength(length: number): Uint8Array {
     const lenBytes = new Uint8Array(3)
     if (length <= 192) {
       lenBytes[0] = length
@@ -158,7 +158,7 @@ class BinarySerializer {
       // this part doesn't happen for the Account field in a UNLModify transaction
       value.toBytesSink(bytes)
     }
-    this.put(this.encodeVariableLength(bytes.getLength()))
+    this.put(BinarySerializer.encodeVariableLength(bytes.getLength()))
     this.writeBytesList(bytes)
   }
 }

package/src/types/account-id.ts

@@ -6,6 +6,7 @@ import {
 } from 'ripple-address-codec'
 import { Hash160 } from './hash-160'
 import { hexToBytes } from '@xrplf/isomorphic/utils'
+import { SerializedTypeID } from './serialized-type'
 
 const HEX_REGEX = /^[A-F0-9]{40}$/
 
@@ -81,6 +82,10 @@ class AccountID extends Hash160 {
   toBase58(): string {
     return encodeAccountID(this.bytes)
   }
+
+  getSType(): SerializedTypeID {
+    return SerializedTypeID.STI_ACCOUNT
+  }
 }
 
 export { AccountID }

package/src/types/amount.ts

@@ -2,7 +2,7 @@ import { BinaryParser } from '../serdes/binary-parser'
 
 import { AccountID } from './account-id'
 import { Currency } from './currency'
-import { JsonObject, SerializedType } from './serialized-type'
+import { JsonObject, SerializedType, SerializedTypeID } from './serialized-type'
 import BigNumber from 'bignumber.js'
 import { bytesToHex, concat, hexToBytes } from '@xrplf/isomorphic/utils'
 import { readUInt32BE, writeUInt32BE } from '../utils'
@@ -92,7 +92,7 @@ class Amount extends SerializedType {
       return value
     }
 
-    let amount = new Uint8Array(8)
+    let amount: Uint8Array = new Uint8Array(8)
     if (typeof value === 'string') {
       Amount.assertXrpIsValid(value)
 
@@ -110,7 +110,12 @@ class Amount extends SerializedType {
     }
 
     if (isAmountObjectIOU(value)) {
-      const number = new BigNumber(value.value)
+      let number: BigNumber
+      try {
+        number = new BigNumber(value.value)
+      } catch (_err) {
+        throw new Error(`${value.value} is an illegal amount`)
+      }
       Amount.assertIouIsValid(number)
 
       if (number.isZero()) {
@@ -189,7 +194,7 @@ class Amount extends SerializedType {
    */
   toJSON(): AmountObject | string {
     if (this.isNative()) {
-      const bytes = this.bytes
+      const bytes = this.bytes.slice()
       const isPositive = bytes[0] & 0x40
       const sign = isPositive ? '' : '-'
       bytes[0] &= 0x3f
@@ -261,7 +266,12 @@ class Amount extends SerializedType {
       throw new Error(`${amount.toString()} is an illegal amount`)
     }
 
-    const decimal = new BigNumber(amount)
+    let decimal: BigNumber
+    try {
+      decimal = new BigNumber(amount)
+    } catch (_err) {
+      throw new Error(`${amount.toString()} is an illegal amount`)
+    }
     if (!decimal.isZero()) {
       if (decimal.lt(MIN_XRP) || decimal.gt(MAX_DROPS)) {
         throw new Error(`${amount.toString()} is an illegal amount`)
@@ -301,7 +311,12 @@ class Amount extends SerializedType {
       throw new Error(`${amount.toString()} is an illegal amount`)
     }
 
-    const decimal = new BigNumber(amount)
+    let decimal: BigNumber
+    try {
+      decimal = new BigNumber(amount)
+    } catch (_err) {
+      throw new Error(`${amount.toString()} is an illegal amount`)
+    }
     if (!decimal.isZero()) {
       if (decimal < BigNumber(0)) {
         throw new Error(`${amount.toString()} is an illegal amount`)
@@ -357,6 +372,10 @@ class Amount extends SerializedType {
   private isIOU(): boolean {
     return (this.bytes[0] & 0x80) !== 0
   }
+
+  getSType(): SerializedTypeID {
+    return SerializedTypeID.STI_AMOUNT
+  }
 }
 
 export { Amount, AmountObject }

package/src/types/blob.ts

@@ -1,4 +1,4 @@
-import { SerializedType } from './serialized-type'
+import { SerializedType, SerializedTypeID } from './serialized-type'
 import { BinaryParser } from '../serdes/binary-parser'
 import { hexToBytes } from '@xrplf/isomorphic/utils'
 
@@ -41,6 +41,10 @@ class Blob extends SerializedType {
 
     throw new Error('Cannot construct Blob from value given')
   }
+
+  getSType(): SerializedTypeID {
+    return SerializedTypeID.STI_VL
+  }
 }
 
 export { Blob }

package/src/types/currency.ts

@@ -1,5 +1,6 @@
 import { Hash160 } from './hash-160'
 import { bytesToHex, hexToBytes, hexToString } from '@xrplf/isomorphic/utils'
+import { SerializedTypeID } from './serialized-type'
 
 const XRP_HEX_REGEX = /^0{40}$/
 const ISO_REGEX = /^[A-Z0-9a-z?!@#$%^&*(){}[\]|]{3}$/
@@ -135,6 +136,10 @@ class Currency extends Hash160 {
     }
     return bytesToHex(this.bytes)
   }
+
+  getSType(): SerializedTypeID {
+    return SerializedTypeID.STI_CURRENCY
+  }
 }
 
 export { Currency }

package/src/types/data.ts

@@ -0,0 +1,294 @@
+import { BinaryParser } from '../serdes/binary-parser'
+import {
+  JsonObject,
+  SerializedType,
+  SerializedTypeID,
+  TYPE_ID_TO_STRING,
+  TYPE_STRING_TO_ID,
+  TYPE_NUMBER_TO_ID,
+} from './serialized-type'
+import { readUInt16BE, writeUInt16BE } from '../utils'
+import { bytesToHex, concat } from '@xrplf/isomorphic/utils'
+import { Hash128 } from './hash-128'
+import { Hash160 } from './hash-160'
+import { Hash192 } from './hash-192'
+import { Hash256 } from './hash-256'
+import { AccountID } from './account-id'
+import { Amount } from './amount'
+import { Blob } from './blob'
+import { Currency } from './currency'
+import { STNumber } from './st-number'
+import { Issue } from './issue'
+import { UInt8 } from './uint-8'
+import { UInt16 } from './uint-16'
+import { UInt32 } from './uint-32'
+import { UInt64 } from './uint-64'
+import { BinarySerializer } from '../binary'
+
+/**
+ * Interface for Data JSON representation
+ */
+interface DataJSON extends JsonObject {
+  type: string
+  value: string | number | JsonObject
+}
+
+/**
+ * Map from SerializedTypeID to the corresponding type class.
+ * Types listed here use standard from()/fromParser()/toBytes() without
+ * any extra framing (unlike VL and Account which need length prefixes).
+ */
+const SIMPLE_TYPE_MAP: Partial<
+  Record<SerializedTypeID, typeof SerializedType>
+> = {
+  [SerializedTypeID.STI_UINT8]: UInt8,
+  [SerializedTypeID.STI_UINT16]: UInt16,
+  [SerializedTypeID.STI_UINT32]: UInt32,
+  [SerializedTypeID.STI_UINT64]: UInt64,
+  [SerializedTypeID.STI_UINT128]: Hash128,
+  [SerializedTypeID.STI_UINT160]: Hash160,
+  [SerializedTypeID.STI_UINT192]: Hash192,
+  [SerializedTypeID.STI_UINT256]: Hash256,
+  [SerializedTypeID.STI_AMOUNT]: Amount,
+  [SerializedTypeID.STI_ISSUE]: Issue,
+  [SerializedTypeID.STI_CURRENCY]: Currency,
+  [SerializedTypeID.STI_NUMBER]: STNumber,
+}
+
+/**
+ * Types whose from() method expects a numeric argument.
+ * For these, json.value is coerced to a number before calling from().
+ */
+const NUMERIC_TYPES = new Set<SerializedTypeID>([
+  SerializedTypeID.STI_UINT8,
+  SerializedTypeID.STI_UINT16,
+  SerializedTypeID.STI_UINT32,
+])
+
+/**
+ * STData: Encodes XRPL's "Data" type.
+ *
+ * This type wraps both a SerializedTypeID and the actual data value.
+ * It's encoded as a 2-byte type ID followed by the serialized data.
+ *
+ * Usage:
+ *   Data.from({ type: "Amount", value: "1000000" })
+ *   Data.from({ type: "UInt64", value: "123456789" })
+ *   Data.fromParser(parser)
+ */
+class Data extends SerializedType {
+  static readonly ZERO_DATA: Data = new Data(
+    concat([
+      new Uint8Array([0x00, 0x01]), // Type ID for UINT16 (SerializedTypeID.STI_UINT16 = 1) as uint16
+      new Uint8Array([0x00, 0x00]), // Value: two zero bytes for UINT16
+    ]),
+  )
+
+  /**
+   * Construct Data from bytes
+   * @param bytes - Uint8Array containing type ID and data
+   */
+  constructor(bytes: Uint8Array) {
+    super(bytes ?? Data.ZERO_DATA.bytes)
+  }
+
+  /**
+   * Create Data from various input types
+   *
+   * @param value - Can be:
+   *   - Data instance (returns as-is)
+   *   - DataJSON object with 'type' and 'value' fields
+   * @returns Data instance
+   * @throws Error if value type is not supported
+   */
+  static from(value: unknown): Data {
+    if (value instanceof Data) {
+      return value
+    }
+
+    if (
+      typeof value === 'object' &&
+      value !== null &&
+      'type' in value &&
+      'value' in value
+    ) {
+      const json = value as DataJSON
+      return Data.fromJSON(json)
+    }
+
+    throw new Error('Data.from: value must be Data instance or DataJSON object')
+  }
+
+  /**
+   * Create Data from JSON representation
+   *
+   * @param json - Object with 'type' and 'value' fields
+   * @returns Data instance
+   * @throws Error if type is not supported
+   */
+  static fromJSON(json: DataJSON): Data {
+    const typeId = TYPE_STRING_TO_ID[json.type]
+    if (typeId === undefined) {
+      throw new Error(`Data: unsupported type string: ${json.type}`)
+    }
+
+    let dataBytes: Uint8Array
+
+    const TypeClass = SIMPLE_TYPE_MAP[typeId]
+    if (TypeClass) {
+      // For UInt8/16/32, coerce value to number; all others pass through
+      const coercedValue = NUMERIC_TYPES.has(typeId)
+        ? typeof json.value === 'string'
+          ? parseInt(json.value, 10)
+          : Number(json.value)
+        : json.value
+      dataBytes = TypeClass.from(coercedValue).toBytes()
+    } else if (typeId === SerializedTypeID.STI_VL) {
+      const val =
+        typeof json.value === 'string' ? json.value : json.value.toString()
+      dataBytes = Blob.from(val).toBytes()
+      dataBytes = concat([
+        BinarySerializer.encodeVariableLength(dataBytes.length),
+        dataBytes,
+      ])
+    } else if (typeId === SerializedTypeID.STI_ACCOUNT) {
+      const val =
+        typeof json.value === 'string' ? json.value : json.value.toString()
+      dataBytes = concat([
+        new Uint8Array([0x14]),
+        AccountID.from(val).toBytes(),
+      ])
+    } else {
+      throw new Error(`Data.fromJSON(): unsupported type ID: ${typeId}`)
+    }
+
+    // Combine type header with data bytes
+    const typeBytes = new Uint8Array(2)
+    writeUInt16BE(typeBytes, typeId, 0)
+    return new Data(concat([typeBytes, dataBytes]))
+  }
+
+  /**
+   * Read Data from a BinaryParser stream
+   *
+   * @param parser - BinaryParser positioned at the start of Data
+   * @returns Data instance
+   */
+  static fromParser(parser: BinaryParser): Data {
+    // Read the 2-byte type ID
+    const typeBytes = parser.read(2)
+    const typeId = TYPE_NUMBER_TO_ID[readUInt16BE(typeBytes, 0)]
+
+    let dataBytes: Uint8Array
+
+    const TypeClass = SIMPLE_TYPE_MAP[typeId]
+    if (TypeClass) {
+      dataBytes = TypeClass.fromParser(parser).toBytes()
+    } else if (typeId === SerializedTypeID.STI_VL) {
+      const valueVL = parser.readVariableLength()
+      dataBytes = concat([
+        BinarySerializer.encodeVariableLength(valueVL.length),
+        valueVL,
+      ])
+    } else if (typeId === SerializedTypeID.STI_ACCOUNT) {
+      parser.skip(1)
+      dataBytes = concat([
+        new Uint8Array([0x14]),
+        AccountID.fromParser(parser).toBytes(),
+      ])
+    } else {
+      throw new Error(`Data: unsupported type ID when parsing: ${typeId}`)
+    }
+
+    return new Data(concat([typeBytes, dataBytes]))
+  }
+
+  /**
+   * Get the inner SerializedTypeID
+   *
+   * @returns The inner type ID
+   */
+  getInnerType(): SerializedTypeID {
+    return TYPE_NUMBER_TO_ID[readUInt16BE(this.bytes, 0)]
+  }
+
+  /**
+   * Get the string representation of the inner type
+   *
+   * @returns String name of the type
+   */
+  getInnerTypeString(): string {
+    const innerType = this.getInnerType()
+    return TYPE_ID_TO_STRING[innerType] || innerType.toString()
+  }
+
+  /**
+   * Get the data value
+   *
+   * @returns The stored data value
+   */
+  getValue(): SerializedType {
+    const innerType = this.getInnerType()
+    const parser = new BinaryParser(bytesToHex(this.bytes.slice(2)))
+
+    const TypeClass = SIMPLE_TYPE_MAP[innerType]
+    if (TypeClass) {
+      return TypeClass.fromParser(parser)
+    }
+
+    if (innerType === SerializedTypeID.STI_VL) {
+      const vlLength = parser.readVariableLengthLength()
+      return Blob.fromParser(parser, vlLength)
+    }
+
+    if (innerType === SerializedTypeID.STI_ACCOUNT) {
+      parser.skip(1)
+      return AccountID.fromParser(parser)
+    }
+
+    throw new Error(`Data.getValue(): unsupported type ID: ${typeof innerType}`)
+  }
+
+  /**
+   * Convert to JSON representation
+   *
+   * @returns JSON object with 'type' and 'value' fields
+   */
+  toJSON(): DataJSON {
+    return {
+      type: this.getInnerTypeString(),
+      value: this.getValue().toJSON() as string | number | JsonObject,
+    }
+  }
+
+  /**
+   * Compare with another Data for equality
+   *
+   * @param other - Another Data to compare with
+   * @returns true if both have the same inner type and data
+   */
+  equals(other: Data): boolean {
+    if (!(other instanceof Data)) {
+      return false
+    }
+
+    // Compare bytes directly
+    if (this.bytes.length !== other.bytes.length) {
+      return false
+    }
+
+    for (let i = 0; i < this.bytes.length; i++) {
+      if (this.bytes[i] !== other.bytes[i]) {
+        return false
+      }
+    }
+
+    return true
+  }
+
+  getSType(): SerializedTypeID {
+    return SerializedTypeID.STI_DATA
+  }
+}
+
+export { Data }

package/src/types/dataType.ts

@@ -0,0 +1,178 @@
+import { BinaryParser } from '../serdes/binary-parser'
+import {
+  JsonObject,
+  SerializedType,
+  SerializedTypeID,
+  TYPE_ID_TO_STRING,
+  TYPE_STRING_TO_ID,
+} from './serialized-type'
+import { readUInt16BE, writeUInt16BE } from '../utils'
+
+/**
+ * Interface for DataType JSON representation
+ */
+interface DataTypeJSON extends JsonObject {
+  type: string
+}
+
+/**
+ * STDataType: Encodes XRPL's "DataType" type.
+ *
+ * This type wraps an inner SerializedTypeID to indicate what type of data
+ * a field contains. It's encoded as a 2-byte unsigned integer representing
+ * the inner type.
+ *
+ * Usage:
+ *   DataType.from({ type: "Amount" })
+ *   DataType.from("UInt64")
+ *   DataType.fromParser(parser)
+ */
+class DataType extends SerializedType {
+  private innerType: SerializedTypeID
+
+  /**
+   * Default bytes for DataType (STI_NOTPRESENT)
+   */
+  static readonly defaultBytes = new Uint8Array([0x00, 0x01])
+
+  /**
+   * Construct a DataType from bytes
+   * @param bytes - 2-byte Uint8Array containing the inner type ID
+   * @param innerType - Optional explicit inner type (used when constructing from value)
+   * @throws Error if bytes is not a 2-byte Uint8Array
+   */
+  constructor(bytes?: Uint8Array, innerType?: SerializedTypeID) {
+    const used = bytes ?? DataType.defaultBytes
+    if (!(used instanceof Uint8Array) || used.length !== 2) {
+      throw new Error(
+        `DataType must be constructed from a 2-byte Uint8Array, got ${used?.length} bytes`,
+      )
+    }
+    super(used)
+
+    // If innerType is explicitly provided, use it; otherwise read from bytes
+    if (innerType !== undefined) {
+      this.innerType = innerType
+    } else {
+      this.innerType = readUInt16BE(used, 0) as unknown as SerializedTypeID
+    }
+  }
+
+  /**
+   * Construct from various input types
+   *
+   * @param value - Can be:
+   *   - DataType instance (returns as-is)
+   *   - DataTypeJSON object with 'type' field
+   *   - String type name (e.g., "Amount", "UInt64")
+   *   - SerializedTypeID enum value
+   * @returns DataType instance
+   * @throws Error if value type is not supported or type string is unknown
+   */
+  static from(value: unknown): DataType {
+    if (value instanceof DataType) {
+      return value
+    }
+
+    if (typeof value === 'object' && value !== null && 'type' in value) {
+      const json = value as DataTypeJSON
+      return DataType.fromTypeString(json.type)
+    }
+
+    if (typeof value === 'string') {
+      return DataType.fromTypeString(value)
+    }
+
+    if (typeof value === 'number') {
+      return DataType.fromTypeId(value as SerializedTypeID)
+    }
+
+    throw new Error(
+      'DataType.from: value must be DataType, DataTypeJSON, string, or SerializedTypeID',
+    )
+  }
+
+  /**
+   * Construct from a type string
+   *
+   * @param typeStr - Type string like "Amount", "UInt64", etc.
+   * @returns DataType instance
+   * @throws Error if type string is not recognized
+   */
+  static fromTypeString(typeStr: string): DataType {
+    const typeId = TYPE_STRING_TO_ID[typeStr]
+    if (typeId === undefined) {
+      throw new Error(`DataType: unsupported type string: ${typeStr}`)
+    }
+    return DataType.fromTypeId(typeId)
+  }
+
+  /**
+   * Construct from a SerializedTypeID
+   *
+   * @param typeId - The SerializedTypeID enum value
+   * @returns DataType instance
+   */
+  static fromTypeId(typeId: SerializedTypeID): DataType {
+    const bytes = new Uint8Array(2)
+    writeUInt16BE(bytes, typeId, 0)
+    return new DataType(bytes, typeId)
+  }
+
+  /**
+   * Read a DataType from a BinaryParser stream (2 bytes)
+   *
+   * @param parser - BinaryParser positioned at the start of a DataType
+   * @returns DataType instance
+   */
+  static fromParser(parser: BinaryParser): DataType {
+    const bytes = parser.read(2)
+    return new DataType(bytes)
+  }
+
+  /**
+   * Get the inner SerializedTypeID
+   *
+   * @returns The inner type ID
+   */
+  getInnerType(): SerializedTypeID {
+    return this.innerType
+  }
+
+  /**
+   * Set the inner SerializedTypeID
+   *
+   * @param typeId - The new inner type ID
+   */
+  setInnerType(typeId: SerializedTypeID): void {
+    this.innerType = typeId
+    writeUInt16BE(this.bytes, typeId, 0)
+  }
+
+  /**
+   * Get the string representation of the inner type
+   *
+   * @returns String name of the type, or numeric string if unknown
+   */
+  getInnerTypeString(): string {
+    return TYPE_ID_TO_STRING[this.innerType] || this.innerType.toString()
+  }
+
+  /**
+   * Convert to JSON representation
+   *
+   * @returns JSON object with 'type' field
+   */
+  toJSON(): DataTypeJSON {
+    return {
+      type: this.getInnerTypeString(),
+    }
+  }
+
+  getSType(): SerializedTypeID {
+    return SerializedTypeID.STI_DATATYPE
+  }
+}
+
+// Export the DataType class for external use
+export { DataType }

package/src/types/hash-128.ts

@@ -1,5 +1,6 @@
 import { Hash } from './hash'
 import { bytesToHex } from '@xrplf/isomorphic/utils'
+import { SerializedTypeID } from './serialized-type'
 
 /**
  * Hash with a width of 128 bits
@@ -28,6 +29,10 @@ class Hash128 extends Hash {
     }
     return hex
   }
+
+  getSType(): SerializedTypeID {
+    return SerializedTypeID.STI_UINT128
+  }
 }
 
 export { Hash128 }