ripple-binary-codec 1.7.1 → 1.9.0

package/src/enums/field.ts

@@ -0,0 +1,85 @@
+import { Bytes } from './bytes'
+import { SerializedType } from '../types/serialized-type'
+import { TYPE_WIDTH } from './constants'
+import { Buffer } from 'buffer/'
+
+/**
+ * Encoding information for a rippled field, often used in transactions.
+ * See the enums [README.md](https://github.com/XRPLF/xrpl.js/tree/main/packages/ripple-binary-codec/src/enums) for more details on what each means.
+ */
+export interface FieldInfo {
+  nth: number
+  isVLEncoded: boolean
+  isSerialized: boolean
+  isSigningField: boolean
+  type: string
+}
+
+export interface FieldInstance {
+  readonly nth: number
+  readonly isVariableLengthEncoded: boolean
+  readonly isSerialized: boolean
+  readonly isSigningField: boolean
+  readonly type: Bytes
+  readonly ordinal: number
+  readonly name: string
+  readonly header: Buffer
+  readonly associatedType: typeof SerializedType
+}
+
+/*
+ * @brief: Serialize a field based on type_code and Field.nth
+ */
+function fieldHeader(type: number, nth: number): Buffer {
+  const header: Array<number> = []
+  if (type < 16) {
+    if (nth < 16) {
+      header.push((type << 4) | nth)
+    } else {
+      header.push(type << 4, nth)
+    }
+  } else if (nth < 16) {
+    header.push(nth, type)
+  } else {
+    header.push(0, type, nth)
+  }
+  return Buffer.from(header)
+}
+
+function buildField(
+  [name, info]: [string, FieldInfo],
+  typeOrdinal: number,
+): FieldInstance {
+  const field = fieldHeader(typeOrdinal, info.nth)
+  return {
+    name: name,
+    nth: info.nth,
+    isVariableLengthEncoded: info.isVLEncoded,
+    isSerialized: info.isSerialized,
+    isSigningField: info.isSigningField,
+    ordinal: (typeOrdinal << 16) | info.nth,
+    type: new Bytes(info.type, typeOrdinal, TYPE_WIDTH),
+    header: field,
+    associatedType: SerializedType, // For later assignment in ./types/index.js or Definitions.updateAll(...)
+  }
+}
+
+/*
+ * @brief: The collection of all fields as defined in definitions.json
+ */
+export class FieldLookup {
+  constructor(
+    fields: Array<[string, FieldInfo]>,
+    types: Record<string, number>,
+  ) {
+    fields.forEach(([name, field_info]) => {
+      const typeOrdinal = types[field_info.type]
+      this[name] = buildField([name, field_info], typeOrdinal)
+      this[this[name].ordinal.toString()] = this[name]
+    })
+  }
+
+  fromString(value: string): FieldInstance {
+    return this[value] as FieldInstance
+  }
+}

package/src/enums/index.ts

@@ -0,0 +1,34 @@
+import * as enums from './definitions.json'
+import {
+  XrplDefinitionsBase,
+  FieldInstance,
+  Bytes,
+} from './xrpl-definitions-base'
+/**
+ * By default, coreTypes from the `types` folder is where known type definitions are initialized to avoid import cycles.
+ */
+const DEFAULT_DEFINITIONS = new XrplDefinitionsBase(enums, {})
+
+const Type = DEFAULT_DEFINITIONS.type
+const LedgerEntryType = DEFAULT_DEFINITIONS.ledgerEntryType
+const TransactionType = DEFAULT_DEFINITIONS.transactionType
+const TransactionResult = DEFAULT_DEFINITIONS.transactionResult
+const Field = DEFAULT_DEFINITIONS.field
+
+/*
+ * @brief: All valid transaction types
+ */
+const TRANSACTION_TYPES = DEFAULT_DEFINITIONS.transactionNames
+
+export {
+  Bytes,
+  XrplDefinitionsBase,
+  DEFAULT_DEFINITIONS,
+  Field,
+  FieldInstance,
+  Type,
+  LedgerEntryType,
+  TransactionResult,
+  TransactionType,
+  TRANSACTION_TYPES,
+}

package/src/enums/utils-renumber.ts

@@ -0,0 +1,134 @@
+/**
+ * Quick script to re-number values
+ */
+
+const input = {
+  temBAD_SEND_XRP_PATHS: -283,
+  temBAD_SEQUENCE: -282,
+  temBAD_SIGNATURE: -281,
+  temBAD_SRC_ACCOUNT: -280,
+  temBAD_TRANSFER_RATE: -279,
+  temDST_IS_SRC: -278,
+  temDST_NEEDED: -277,
+  temINVALID: -276,
+  temINVALID_FLAG: -275,
+  temREDUNDANT: -274,
+  temRIPPLE_EMPTY: -273,
+  temDISABLED: -272,
+  temBAD_SIGNER: -271,
+  temBAD_QUORUM: -270,
+  temBAD_WEIGHT: -269,
+  temBAD_TICK_SIZE: -268,
+  temINVALID_ACCOUNT_ID: -267,
+  temCANNOT_PREAUTH_SELF: -266,
+
+  temUNCERTAIN: -265,
+  temUNKNOWN: -264,
+
+  tefFAILURE: -199,
+  tefALREADY: -198,
+  tefBAD_ADD_AUTH: -197,
+  tefBAD_AUTH: -196,
+  tefBAD_LEDGER: -195,
+  tefCREATED: -194,
+  tefEXCEPTION: -193,
+  tefINTERNAL: -192,
+  tefNO_AUTH_REQUIRED: -191,
+  tefPAST_SEQ: -190,
+  tefWRONG_PRIOR: -189,
+  tefMASTER_DISABLED: -188,
+  tefMAX_LEDGER: -187,
+  tefBAD_SIGNATURE: -186,
+  tefBAD_QUORUM: -185,
+  tefNOT_MULTI_SIGNING: -184,
+  tefBAD_AUTH_MASTER: -183,
+  tefINVARIANT_FAILED: -182,
+  tefTOO_BIG: -181,
+
+  terRETRY: -99,
+  terFUNDS_SPENT: -98,
+  terINSUF_FEE_B: -97,
+  terNO_ACCOUNT: -96,
+  terNO_AUTH: -95,
+  terNO_LINE: -94,
+  terOWNERS: -93,
+  terPRE_SEQ: -92,
+  terLAST: -91,
+  terNO_RIPPLE: -90,
+  terQUEUED: -89,
+
+  tesSUCCESS: 0,
+
+  tecCLAIM: 100,
+  tecPATH_PARTIAL: 101,
+  tecUNFUNDED_ADD: 102,
+  tecUNFUNDED_OFFER: 103,
+  tecUNFUNDED_PAYMENT: 104,
+  tecFAILED_PROCESSING: 105,
+  tecDIR_FULL: 121,
+  tecINSUF_RESERVE_LINE: 122,
+  tecINSUF_RESERVE_OFFER: 123,
+  tecNO_DST: 124,
+  tecNO_DST_INSUF_XRP: 125,
+  tecNO_LINE_INSUF_RESERVE: 126,
+  tecNO_LINE_REDUNDANT: 127,
+  tecPATH_DRY: 128,
+  tecUNFUNDED: 129,
+  tecNO_ALTERNATIVE_KEY: 130,
+  tecNO_REGULAR_KEY: 131,
+  tecOWNERS: 132,
+  tecNO_ISSUER: 133,
+  tecNO_AUTH: 134,
+  tecNO_LINE: 135,
+  tecINSUFF_FEE: 136,
+  tecFROZEN: 137,
+  tecNO_TARGET: 138,
+  tecNO_PERMISSION: 139,
+  tecNO_ENTRY: 140,
+  tecINSUFFICIENT_RESERVE: 141,
+  tecNEED_MASTER_KEY: 142,
+  tecDST_TAG_NEEDED: 143,
+  tecINTERNAL: 144,
+  tecOVERSIZE: 145,
+  tecCRYPTOCONDITION_ERROR: 146,
+  tecINVARIANT_FAILED: 147,
+  tecEXPIRED: 148,
+  tecDUPLICATE: 149,
+  tecKILLED: 150,
+  tecHAS_OBLIGATIONS: 151,
+  tecTOO_SOON: 152,
+}
+
+let startingFromTemBADSENDXRPPATHS = -284
+
+let startingFromTefFAILURE = -199
+
+let startingFromTerRETRY = -99
+
+const tesSUCCESS = 0
+
+let startingFromTecCLAIM = 100
+
+const startingFromTecDIRFULL = 121
+
+let previousKey = 'tem'
+Object.keys(input).forEach((key) => {
+  if (key.substring(0, 3) !== previousKey.substring(0, 3)) {
+    console.log()
+    previousKey = key
+  }
+  if (key.substring(0, 3) === 'tem') {
+    console.log(`    "${key}": ${startingFromTemBADSENDXRPPATHS++},`)
+  } else if (key.substring(0, 3) === 'tef') {
+    console.log(`    "${key}": ${startingFromTefFAILURE++},`)
+  } else if (key.substring(0, 3) === 'ter') {
+    console.log(`    "${key}": ${startingFromTerRETRY++},`)
+  } else if (key.substring(0, 3) === 'tes') {
+    console.log(`    "${key}": ${tesSUCCESS},`)
+  } else if (key.substring(0, 3) === 'tec') {
+    if (key === 'tecDIR_FULL') {
+      startingFromTecCLAIM = startingFromTecDIRFULL
+    }
+    console.log(`    "${key}": ${startingFromTecCLAIM++},`)
+  }
+})

package/src/enums/xrpl-definitions-base.ts

@@ -0,0 +1,111 @@
+import { SerializedType } from '../types/serialized-type'
+import { Bytes, BytesLookup } from './bytes'
+import { FieldInfo, FieldLookup, FieldInstance } from './field'
+import {
+  TYPE_WIDTH,
+  LEDGER_ENTRY_WIDTH,
+  TRANSACTION_TYPE_WIDTH,
+  TRANSACTION_RESULT_WIDTH,
+} from './constants'
+
+interface DefinitionsData {
+  TYPES: Record<string, number>
+  LEDGER_ENTRY_TYPES: Record<string, number>
+  FIELDS: (string | FieldInfo)[][]
+  TRANSACTION_RESULTS: Record<string, number>
+  TRANSACTION_TYPES: Record<string, number>
+}
+
+/**
+ * Stores the various types and fields for rippled to be used to encode/decode information later on.
+ * XrplDefinitions should be instantiated instead of this class.
+ */
+class XrplDefinitionsBase {
+  // A collection of fields that can be included in transactions
+  field: FieldLookup
+  // A collection of ids corresponding to types of ledger objects
+  ledgerEntryType: BytesLookup
+  // A collection of type flags used to determine how to serialize a field's data
+  type: BytesLookup
+  // Errors and result codes for transactions
+  transactionResult: BytesLookup
+  // Defined transactions that can be submitted to the ledger
+  transactionType: BytesLookup
+  // Valid transaction names
+  transactionNames: string[]
+  // Maps serializable types to their TypeScript class implementation
+  dataTypes: Record<string, typeof SerializedType>
+
+  /**
+   * Present rippled types in a typed and updatable format.
+   * For an example of the input format see `definitions.json`
+   * To generate a new definitions file from rippled source code, use this tool: https://github.com/RichardAH/xrpl-codec-gen
+   *
+   * See the definitions.test.js file for examples of how to create your own updated definitions.json.
+   *
+   * @param enums - A json encoding of the core types, transaction types, transaction results, transaction names, and fields.
+   * @param types - A list of type objects with the same name as the fields defined.
+   *              You can use the coreTypes object if you are not adding new types.
+   */
+  constructor(
+    enums: DefinitionsData,
+    types: Record<string, typeof SerializedType>,
+  ) {
+    this.type = new BytesLookup(enums.TYPES, TYPE_WIDTH)
+    this.ledgerEntryType = new BytesLookup(
+      enums.LEDGER_ENTRY_TYPES,
+      LEDGER_ENTRY_WIDTH,
+    )
+    this.transactionType = new BytesLookup(
+      enums.TRANSACTION_TYPES,
+      TRANSACTION_TYPE_WIDTH,
+    )
+    this.transactionResult = new BytesLookup(
+      enums.TRANSACTION_RESULTS,
+      TRANSACTION_RESULT_WIDTH,
+    )
+    this.field = new FieldLookup(
+      enums.FIELDS as Array<[string, FieldInfo]>,
+      enums.TYPES,
+    )
+    this.transactionNames = Object.entries(enums.TRANSACTION_TYPES)
+      .filter(([_key, value]) => value >= 0)
+      .map(([key, _value]) => key)
+
+    this.dataTypes = {} // Filled in via associateTypes
+    this.associateTypes(types)
+  }
+
+  /**
+   * Associates each Field to a corresponding class that TypeScript can recognize.
+   *
+   * @param types a list of type objects with the same name as the fields defined.
+   *              Defaults to xrpl.js's core type definitions.
+   */
+  public associateTypes(types: Record<string, typeof SerializedType>): void {
+    // Overwrite any existing type definitions with the given types
+    this.dataTypes = Object.assign({}, this.dataTypes, types)
+
+    Object.values(this.field).forEach((field) => {
+      field.associatedType = this.dataTypes[field.type.name]
+    })
+
+    this.field['TransactionType'].associatedType = this.transactionType
+    this.field['TransactionResult'].associatedType = this.transactionResult
+    this.field['LedgerEntryType'].associatedType = this.ledgerEntryType
+  }
+
+  public getAssociatedTypes(): Record<string, typeof SerializedType> {
+    return this.dataTypes
+  }
+}
+
+export {
+  DefinitionsData,
+  XrplDefinitionsBase,
+  FieldLookup,
+  FieldInfo,
+  FieldInstance,
+  Bytes,
+  BytesLookup,
+}

package/src/enums/xrpl-definitions.ts

@@ -0,0 +1,32 @@
+import {
+  type DefinitionsData,
+  XrplDefinitionsBase,
+} from './xrpl-definitions-base'
+import { coreTypes } from '../types'
+import { SerializedType } from '../types/serialized-type'
+
+/**
+ * Stores the various types and fields for rippled to be used to encode/decode information later on.
+ * Should be used instead of XrplDefinitionsBase since this defines default `types` for serializing/deserializing
+ * ledger data.
+ */
+export class XrplDefinitions extends XrplDefinitionsBase {
+  /**
+   * Present rippled types in a typed and updatable format.
+   * For an example of the input format see `definitions.json`
+   * To generate a new definitions file from rippled source code, use this tool: https://github.com/RichardAH/xrpl-codec-gen
+   *
+   * See the definitions.test.js file for examples of how to create your own updated definitions.json.
+   *
+   * @param enums - A json encoding of the core types, transaction types, transaction results, transaction names, and fields.
+   * @param additionalTypes - A list of SerializedType objects with the same name as the fields defined.
+   *              These types will be included in addition to the coreTypes used on mainnet.
+   */
+  constructor(
+    enums: DefinitionsData,
+    additionalTypes?: Record<string, typeof SerializedType>,
+  ) {
+    const types = Object.assign({}, coreTypes, additionalTypes)
+    super(enums, types)
+  }
+}

package/src/hash-prefixes.ts

@@ -0,0 +1,40 @@
+import { Buffer } from 'buffer/'
+
+/**
+ * Write a 32 bit integer to a Buffer
+ *
+ * @param uint32 32 bit integer to write to buffer
+ * @returns a buffer with the bytes representation of uint32
+ */
+function bytes(uint32: number): Buffer {
+  const result = Buffer.alloc(4)
+  result.writeUInt32BE(uint32, 0)
+  return result
+}
+
+/**
+ * Maps HashPrefix names to their byte representation
+ */
+const HashPrefix: Record<string, Buffer> = {
+  transactionID: bytes(0x54584e00),
+  // transaction plus metadata
+  transaction: bytes(0x534e4400),
+  // account state
+  accountStateEntry: bytes(0x4d4c4e00),
+  // inner node in tree
+  innerNode: bytes(0x4d494e00),
+  // ledger master data for signing
+  ledgerHeader: bytes(0x4c575200),
+  // inner transaction to sign
+  transactionSig: bytes(0x53545800),
+  // inner transaction to sign
+  transactionMultiSig: bytes(0x534d5400),
+  // validation for signing
+  validation: bytes(0x56414c00),
+  // proposal for signing
+  proposal: bytes(0x50525000),
+  // payment channel claim
+  paymentChannelClaim: bytes(0x434c4d00),
+}
+
+export { HashPrefix }

package/src/hashes.ts

@@ -0,0 +1,76 @@
+import { HashPrefix } from './hash-prefixes'
+import createHash = require('create-hash')
+import { Hash256 } from './types/hash-256'
+import { BytesList } from './serdes/binary-serializer'
+import { Buffer } from 'buffer/'
+
+/**
+ * Class for hashing with SHA512
+ * @extends BytesList So SerializedTypes can write bytes to a Sha512Half
+ */
+class Sha512Half extends BytesList {
+  private hash = createHash('sha512')
+
+  /**
+   * Construct a new Sha512Hash and write bytes this.hash
+   *
+   * @param bytes bytes to write to this.hash
+   * @returns the new Sha512Hash object
+   */
+  static put(bytes: Buffer): Sha512Half {
+    return new Sha512Half().put(bytes)
+  }
+
+  /**
+   * Write bytes to an existing Sha512Hash
+   *
+   * @param bytes bytes to write to object
+   * @returns the Sha512 object
+   */
+  put(bytes: Buffer): Sha512Half {
+    this.hash.update(bytes)
+    return this
+  }
+
+  /**
+   * Compute SHA512 hash and slice in half
+   *
+   * @returns half of a SHA512 hash
+   */
+  finish256(): Buffer {
+    return Buffer.from(this.hash.digest().slice(0, 32))
+  }
+
+  /**
+   * Constructs a Hash256 from the Sha512Half object
+   *
+   * @returns a Hash256 object
+   */
+  finish(): Hash256 {
+    return new Hash256(this.finish256())
+  }
+}
+
+/**
+ * compute SHA512 hash of a list of bytes
+ *
+ * @param args zero or more arguments to hash
+ * @returns the sha512half hash of the arguments.
+ */
+function sha512Half(...args: Buffer[]): Buffer {
+  const hash = new Sha512Half()
+  args.forEach((a) => hash.put(a))
+  return hash.finish256()
+}
+
+/**
+ * Construct a transactionID from a Serialized Transaction
+ *
+ * @param serialized bytes to hash
+ * @returns a Hash256 object
+ */
+function transactionID(serialized: Buffer): Hash256 {
+  return new Hash256(sha512Half(HashPrefix.transactionID, serialized))
+}
+
+export { Sha512Half, sha512Half, transactionID }

package/src/index.ts

@@ -0,0 +1,141 @@
+import * as assert from 'assert'
+import { quality, binary, HashPrefix } from './coretypes'
+import { decodeLedgerData } from './ledger-hashes'
+import { ClaimObject } 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'
+
+const {
+  signingData,
+  signingClaimData,
+  multiSigningData,
+  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 {
+  assert.ok(typeof binary === 'string', '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 {
+  assert.ok(typeof json === 'object')
+  return serializeObject(json as JsonObject, { definitions })
+    .toString('hex')
+    .toUpperCase()
+}
+
+/**
+ * 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 {
+  assert.ok(typeof json === 'object')
+  return signingData(json as JsonObject, HashPrefix.transactionSig, {
+    definitions,
+  })
+    .toString('hex')
+    .toUpperCase()
+}
+
+/**
+ * Encode a transaction and prepare for signing with a claim
+ *
+ * @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 encodeForSigningClaim(json: object): string {
+  assert.ok(typeof json === 'object')
+  return signingClaimData(json as ClaimObject)
+    .toString('hex')
+    .toUpperCase()
+}
+
+/**
+ * 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 {
+  assert.ok(typeof json === 'object')
+  assert.equal(json['SigningPubKey'], '')
+  const definitionsOpt = definitions ? { definitions } : undefined
+  return multiSigningData(json as JsonObject, signer, definitionsOpt)
+    .toString('hex')
+    .toUpperCase()
+}
+
+/**
+ * Encode a quality value
+ *
+ * @param value string representation of a number
+ * @returns a hex-string representing the quality
+ */
+function encodeQuality(value: string): string {
+  assert.ok(typeof value === 'string')
+  return quality.encode(value).toString('hex').toUpperCase()
+}
+
+/**
+ * Decode a quality value
+ *
+ * @param value hex-string of a quality
+ * @returns a string representing the quality
+ */
+function decodeQuality(value: string): string {
+  assert.ok(typeof value === 'string')
+  return quality.decode(value).toString()
+}
+
+export {
+  decode,
+  encode,
+  encodeForSigning,
+  encodeForSigningClaim,
+  encodeForMultisigning,
+  encodeQuality,
+  decodeQuality,
+  decodeLedgerData,
+  TRANSACTION_TYPES,
+  XrplDefinitions,
+  XrplDefinitionsBase,
+  DEFAULT_DEFINITIONS,
+  coreTypes,
+}