xrpl 2.10.0 → 2.12.0-beta.0

package/src/utils/hashes/README.md

@@ -0,0 +1,65 @@
+# XRP Ledger Hashes
+
+Methods to hash XRP Ledger objects
+
+## Computing a transaction hash (ID)
+
+### computeBinaryTransactionHash = (txBlobHex: string): string
+
+Compute the hash of a binary transaction blob.
+
+### computeTransactionHash = (txJSON: any): string
+
+Compute the hash of a transaction in txJSON format.
+
+## [Hash Prefixes](https://xrpl.org/basic-data-types.html#hash-prefixes)
+
+In many cases, the XRP Ledger prefixes an object's binary data with a 4-byte code before calculating its hash, so that objects of different types have different hashes even if the binary data is the same. The existing 4-byte codes are structured as 3 alphabetic characters, encoded as ASCII, followed by a zero byte.
+
+Some types of hashes appear in API requests and responses. Others are only calculated as the first step of signing a certain type of data, or calculating a higher-level hash. Some of following methods internally use some of the 4-byte hash prefixes in order to calculate the appropriate hash.
+
+### hashTx = (txBlobHex: string): string
+
+In order to single-sign a transaction, you must perform these steps:
+
+1. Assuming the transaction is in JSON format (txJSON), `encode` the transaction in the XRP Ledger's binary format.
+2. Hash the data with the appropriate prefix (`0x53545800` if single-signing, or `0x534D5400` if multi-signing).
+3. After signing, you must re-serialize the transaction with the `TxnSignature` field included.
+
+The `hashTx` helps with step 2, automatically using the `0x53545800` prefix needed for single-signing a transaction.
+
+For details, see [Serialization Format](https://xrpl.org/serialization.html).
+
+_Removed:_ `computeTransactionSigningHash`, which took txJSON as a parameter. It was part of the deprecated ripple-hashes library. If you have txJSON, `encode` it with [ripple-binary-codec](https://github.com/ripple/ripple-binary-codec) first. Example: `return hashTx(encode(txJSON))`
+
+### computeAccountLedgerObjectID = (address: string): string
+
+Compute the hash of an account, given the account's classic address (starting with `r`).
+
+### computeSignerListLedgerObjectID = (address: string): string
+
+Compute the hash of an account's SignerList.
+
+### computeOfferID = (address: string, sequence: number): string
+
+Compute the hash of an order, given the owner's classic address (starting with `r`) and the account sequence number of the `OfferCreate` order transaction.
+
+### hashTrustline = (address1: string, address2: string, currency: string): string
+
+Compute the hash of a trustline, given the two parties' classic addresses (starting with `r`) and the currency code.
+
+### hashTxTree = (transactions: any[]): string
+
+### hashStateTree = (entries: any[]): string
+
+### hashLedger = (ledgerHeader): string
+
+Compute the hash of a ledger.
+
+### hashEscrow = (address, sequence): string
+
+Compute the hash of an escrow, given the owner's classic address (starting with `r`) and the account sequence number of the `EscrowCreate` escrow transaction.
+
+### hashPaymentChannel = (address, dstAddress, sequence): string
+
+Compute the hash of a payment channel, given the owner's classic address (starting with `r`), the classic address of the destination, and the account sequence number of the `PaymentChannelCreate` payment channel transaction.

package/src/utils/hashes/SHAMap/InnerNode.ts

@@ -0,0 +1,124 @@
+import { XrplError } from '../../../errors'
+import HashPrefix from '../HashPrefix'
+import sha512Half from '../sha512Half'
+
+import LeafNode from './LeafNode'
+import { NodeType, Node } from './node'
+
+const HEX_ZERO =
+  '0000000000000000000000000000000000000000000000000000000000000000'
+
+const SLOT_MAX = 15
+const HEX = 16
+
+/**
+ * Class for SHAMap InnerNode.
+ */
+class InnerNode extends Node {
+  public leaves: { [slot: number]: Node | undefined }
+  public type: NodeType
+  public depth: number
+  public empty: boolean
+
+  /**
+   * Define an Inner (non-leaf) node in a SHAMap tree.
+   *
+   * @param depth - I.e. How many parent inner nodes.
+   */
+  public constructor(depth = 0) {
+    super()
+    this.leaves = {}
+    this.type = NodeType.INNER
+    this.depth = depth
+    this.empty = true
+  }
+
+  /**
+   * Get the hash of a LeafNode.
+   *
+   * @returns Hash of the LeafNode.
+   */
+  public get hash(): string {
+    if (this.empty) {
+      return HEX_ZERO
+    }
+    let hex = ''
+    for (let iter = 0; iter <= SLOT_MAX; iter++) {
+      const child = this.leaves[iter]
+      const hash: string = child == null ? HEX_ZERO : child.hash
+      hex += hash
+    }
+
+    const prefix = HashPrefix.INNER_NODE.toString(HEX)
+    return sha512Half(prefix + hex)
+  }
+
+  /**
+   * Adds an item to the InnerNode.
+   *
+   * @param tag - Equates to a ledger entry `index`.
+   * @param node - Node to add.
+   * @throws If there is a index collision.
+   */
+  public addItem(tag: string, node: Node): void {
+    const existingNode = this.getNode(parseInt(tag[this.depth], HEX))
+
+    if (existingNode === undefined) {
+      this.setNode(parseInt(tag[this.depth], HEX), node)
+      return
+    }
+
+    // A node already exists in this slot
+    if (existingNode instanceof InnerNode) {
+      // There is an inner node, so we need to go deeper
+      existingNode.addItem(tag, node)
+    } else if (existingNode instanceof LeafNode) {
+      if (existingNode.tag === tag) {
+        // Collision
+        throw new XrplError(
+          'Tried to add a node to a SHAMap that was already in there.',
+        )
+      } else {
+        const newInnerNode = new InnerNode(this.depth + 1)
+
+        // Parent new and existing node
+        newInnerNode.addItem(existingNode.tag, existingNode)
+        newInnerNode.addItem(tag, node)
+
+        // And place the newly created inner node in the slot
+        this.setNode(parseInt(tag[this.depth], HEX), newInnerNode)
+      }
+    }
+  }
+
+  /**
+   * Overwrite the node that is currently in a given slot.
+   *
+   * @param slot - A number 0-15.
+   * @param node - To place.
+   * @throws If slot is out of range.
+   */
+  public setNode(slot: number, node: Node): void {
+    if (slot < 0 || slot > SLOT_MAX) {
+      throw new XrplError('Invalid slot: slot must be between 0-15.')
+    }
+    this.leaves[slot] = node
+    this.empty = false
+  }
+
+  /**
+   * Get the node that is currently in a given slot.
+   *
+   * @param slot - A number 0-15.
+   * @returns Node currently in a slot.
+   * @throws If slot is out of range.
+   */
+  public getNode(slot: number): Node | undefined {
+    if (slot < 0 || slot > SLOT_MAX) {
+      throw new XrplError('Invalid slot: slot must be between 0-15.')
+    }
+    return this.leaves[slot]
+  }
+}
+
+export default InnerNode

package/src/utils/hashes/SHAMap/LeafNode.ts

@@ -0,0 +1,69 @@
+import { XrplError } from '../../../errors'
+import HashPrefix from '../HashPrefix'
+import sha512Half from '../sha512Half'
+
+import { NodeType, Node } from './node'
+
+const HEX = 16
+
+/**
+ * Class for SHAMap Leaf Node.
+ */
+class LeafNode extends Node {
+  public tag: string
+  public type: NodeType
+  public data: string
+
+  /**
+   * Leaf node in a SHAMap tree.
+   *
+   * @param tag - Equates to a ledger entry `index`.
+   * @param data - Hex of account state, transaction etc.
+   * @param type - One of TYPE_ACCOUNT_STATE, TYPE_TRANSACTION_MD etc.
+   */
+  public constructor(tag: string, data: string, type: NodeType) {
+    super()
+    this.tag = tag
+    this.type = type
+    this.data = data
+  }
+
+  /**
+   * Get the hash of a LeafNode.
+   *
+   * @returns Hash or undefined.
+   * @throws If node is of unknown type.
+   */
+  public get hash(): string {
+    switch (this.type) {
+      case NodeType.ACCOUNT_STATE: {
+        const leafPrefix = HashPrefix.LEAF_NODE.toString(HEX)
+        return sha512Half(leafPrefix + this.data + this.tag)
+      }
+      case NodeType.TRANSACTION_NO_METADATA: {
+        const txIDPrefix = HashPrefix.TRANSACTION_ID.toString(HEX)
+        return sha512Half(txIDPrefix + this.data)
+      }
+      case NodeType.TRANSACTION_METADATA: {
+        const txNodePrefix = HashPrefix.TRANSACTION_NODE.toString(HEX)
+        return sha512Half(txNodePrefix + this.data + this.tag)
+      }
+      default:
+        throw new XrplError('Tried to hash a SHAMap node of unknown type.')
+    }
+  }
+
+  /**
+   * Add item to Leaf.
+   *
+   * @param tag - Index of the Node.
+   * @param node - Node to insert.
+   * @throws When called, because LeafNodes cannot addItem.
+   */
+  public addItem(tag: string, node: Node): void {
+    throw new XrplError('Cannot call addItem on a LeafNode')
+    this.addItem(tag, node)
+  }
+}
+
+export default LeafNode

package/src/utils/hashes/SHAMap/index.ts

@@ -0,0 +1,41 @@
+import InnerNode from './InnerNode'
+import LeafNode from './LeafNode'
+import { NodeType } from './node'
+
+/**
+ * SHAMap is the hash structure used to model ledgers.
+ * If the root hash is equivalent, that means all nodes should be equivalent as well.
+ */
+class SHAMap {
+  public root: InnerNode
+
+  /**
+   * SHAMap tree constructor.
+   */
+  public constructor() {
+    this.root = new InnerNode(0)
+  }
+
+  /**
+   * Get the hash of the SHAMap.
+   *
+   * @returns The hash of the root of the SHAMap.
+   */
+  public get hash(): string {
+    return this.root.hash
+  }
+
+  /**
+   * Add an item to the SHAMap.
+   *
+   * @param tag - Index of the Node to add.
+   * @param data - Data to insert into the tree.
+   * @param type - Type of the node to add.
+   */
+  public addItem(tag: string, data: string, type: NodeType): void {
+    this.root.addItem(tag, new LeafNode(tag, data, type))
+  }
+}
+
+export * from './node'
+export default SHAMap

package/src/utils/hashes/SHAMap/node.ts

@@ -0,0 +1,14 @@
+export enum NodeType {
+  INNER = 1,
+  TRANSACTION_NO_METADATA = 2,
+  TRANSACTION_METADATA = 3,
+  ACCOUNT_STATE = 4,
+}
+
+/**
+ * Abstract base class for SHAMapNode.
+ */
+export abstract class Node {
+  public abstract get hash(): string
+  public abstract addItem(_tag: string, _node: Node): void
+}

package/src/utils/hashes/hashLedger.ts

@@ -0,0 +1,236 @@
+/* eslint-disable @typescript-eslint/no-magic-numbers -- this file mimics
+   behavior in rippled. Magic numbers are used for lengths and conditions */
+/* eslint-disable no-bitwise  -- this file mimics behavior in rippled. It uses
+   bitwise operators for and-ing numbers with a mask and bit shifting. */
+
+import BigNumber from 'bignumber.js'
+import { decode, encode } from 'ripple-binary-codec'
+
+import { ValidationError, XrplError } from '../../errors'
+import type { Ledger } from '../../models/ledger'
+import { LedgerEntry } from '../../models/ledger'
+import { Transaction, TransactionMetadata } from '../../models/transactions'
+
+import HashPrefix from './HashPrefix'
+import sha512Half from './sha512Half'
+import SHAMap, { NodeType } from './SHAMap'
+
+const HEX = 16
+
+interface HashLedgerHeaderOptions {
+  computeTreeHashes?: boolean
+}
+
+function intToHex(integer: number, byteLength: number): string {
+  const foo = Number(integer)
+    .toString(HEX)
+    .padStart(byteLength * 2, '0')
+
+  return foo
+}
+
+function bytesToHex(bytes: number[]): string {
+  return Buffer.from(bytes).toString('hex')
+}
+
+function bigintToHex(
+  integerString: string | number | BigNumber,
+  byteLength: number,
+): string {
+  const hex = new BigNumber(integerString).toString(HEX)
+  return hex.padStart(byteLength * 2, '0')
+}
+
+function addLengthPrefix(hex: string): string {
+  const length = hex.length / 2
+  if (length <= 192) {
+    return bytesToHex([length]) + hex
+  }
+  if (length <= 12480) {
+    const prefix = length - 193
+    return bytesToHex([193 + (prefix >>> 8), prefix & 0xff]) + hex
+  }
+  if (length <= 918744) {
+    const prefix = length - 12481
+    return (
+      bytesToHex([
+        241 + (prefix >>> 16),
+        (prefix >>> 8) & 0xff,
+        prefix & 0xff,
+      ]) + hex
+    )
+  }
+  throw new XrplError('Variable integer overflow.')
+}
+
+/**
+ * Hashes the Transaction object as the ledger does. Throws if the transaction is unsigned.
+ *
+ * @param tx - A transaction to hash. Tx may be in binary blob form. Tx must be signed.
+ * @returns A hash of tx.
+ * @throws ValidationError if the Transaction is unsigned.\
+ * @category Utilities
+ */
+export function hashSignedTx(tx: Transaction | string): string {
+  let txBlob: string
+  let txObject: Transaction
+  if (typeof tx === 'string') {
+    txBlob = tx
+    /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Required until updated in binary codec. */
+    txObject = decode(tx) as unknown as Transaction
+  } else {
+    txBlob = encode(tx)
+    txObject = tx
+  }
+
+  if (txObject.TxnSignature === undefined && txObject.Signers === undefined) {
+    throw new ValidationError('The transaction must be signed to hash it.')
+  }
+
+  const prefix = HashPrefix.TRANSACTION_ID.toString(16).toUpperCase()
+  return sha512Half(prefix.concat(txBlob))
+}
+
+/**
+ * Compute the hash of a ledger.
+ *
+ * @param ledgerHeader - Ledger to compute the hash of.
+ * @returns The hash of the ledger.
+ * @category Utilities
+ */
+export function hashLedgerHeader(ledgerHeader: Ledger): string {
+  const prefix = HashPrefix.LEDGER.toString(HEX).toUpperCase()
+
+  const ledger =
+    prefix +
+    intToHex(Number(ledgerHeader.ledger_index), 4) +
+    bigintToHex(ledgerHeader.total_coins, 8) +
+    ledgerHeader.parent_hash +
+    ledgerHeader.transaction_hash +
+    ledgerHeader.account_hash +
+    intToHex(ledgerHeader.parent_close_time, 4) +
+    intToHex(ledgerHeader.close_time, 4) +
+    intToHex(ledgerHeader.close_time_resolution, 1) +
+    intToHex(ledgerHeader.close_flags, 1)
+
+  return sha512Half(ledger)
+}
+
+/**
+ * Compute the root hash of the SHAMap containing all transactions.
+ *
+ * @param transactions - List of Transactions.
+ * @returns The root hash of the SHAMap.
+ * @category Utilities
+ */
+export function hashTxTree(
+  transactions: Array<Transaction & { metaData?: TransactionMetadata }>,
+): string {
+  const shamap = new SHAMap()
+  for (const txJSON of transactions) {
+    const txBlobHex = encode(txJSON)
+    const metaHex = encode(txJSON.metaData ?? {})
+    const txHash = hashSignedTx(txBlobHex)
+    const data = addLengthPrefix(txBlobHex) + addLengthPrefix(metaHex)
+    shamap.addItem(txHash, data, NodeType.TRANSACTION_METADATA)
+  }
+
+  return shamap.hash
+}
+
+/**
+ * Compute the state hash of a list of LedgerEntries.
+ *
+ * @param entries - List of LedgerEntries.
+ * @returns Hash of SHAMap that consists of all entries.
+ * @category Utilities
+ */
+export function hashStateTree(entries: LedgerEntry[]): string {
+  const shamap = new SHAMap()
+
+  entries.forEach((ledgerEntry) => {
+    const data = encode(ledgerEntry)
+    shamap.addItem(ledgerEntry.index, data, NodeType.ACCOUNT_STATE)
+  })
+
+  return shamap.hash
+}
+
+function computeTransactionHash(
+  ledger: Ledger,
+  options: HashLedgerHeaderOptions,
+): string {
+  const { transaction_hash } = ledger
+
+  if (!options.computeTreeHashes) {
+    return transaction_hash
+  }
+
+  if (ledger.transactions == null) {
+    throw new ValidationError('transactions is missing from the ledger')
+  }
+
+  const transactionHash = hashTxTree(ledger.transactions)
+
+  if (transaction_hash !== transactionHash) {
+    throw new ValidationError(
+      'transactionHash in header' +
+        ' does not match computed hash of transactions',
+      {
+        transactionHashInHeader: transaction_hash,
+        computedHashOfTransactions: transactionHash,
+      },
+    )
+  }
+
+  return transactionHash
+}
+
+function computeStateHash(
+  ledger: Ledger,
+  options: HashLedgerHeaderOptions,
+): string {
+  const { account_hash } = ledger
+
+  if (!options.computeTreeHashes) {
+    return account_hash
+  }
+
+  if (ledger.accountState == null) {
+    throw new ValidationError('accountState is missing from the ledger')
+  }
+
+  const stateHash = hashStateTree(ledger.accountState)
+
+  if (account_hash !== stateHash) {
+    throw new ValidationError(
+      'stateHash in header does not match computed hash of state',
+    )
+  }
+
+  return stateHash
+}
+
+/**
+ * Compute the hash of a ledger.
+ *
+ * @param ledger - Ledger to compute the hash for.
+ * @param options - Allow client to recompute Transaction and State Hashes.
+ * @param options.computeTreeHashes - Whether to recompute the Transaction and State Hashes.
+ * @returns The has of ledger.
+ * @category Utilities
+ */
+function hashLedger(
+  ledger: Ledger,
+  options: {
+    computeTreeHashes?: boolean
+  } = {},
+): string {
+  const subhashes = {
+    transaction_hash: computeTransactionHash(ledger, options),
+    account_hash: computeStateHash(ledger, options),
+  }
+  return hashLedgerHeader({ ...ledger, ...subhashes })
+}
+
+export default hashLedger