xrpl 2.9.1 → 2.11.0

package/src/utils/derive.ts

@@ -0,0 +1,23 @@
+import { classicAddressToXAddress } from 'ripple-address-codec'
+import { deriveKeypair, deriveAddress } from 'ripple-keypairs'
+
+/**
+ * Derive an X-Address from a public key and a destination tag.
+ *
+ * @param options - Public key and destination tag to encode as an X-Address.
+ * @param options.publicKey - The public key corresponding to an address.
+ * @param options.tag - A destination tag to encode into an X-address. False indicates no destination tag.
+ * @param options.test - Whether this address is for use in Testnet.
+ * @returns X-Address.
+ * @category Utilities
+ */
+function deriveXAddress(options: {
+  publicKey: string
+  tag: number | false
+  test: boolean
+}): string {
+  const classicAddress = deriveAddress(options.publicKey)
+  return classicAddressToXAddress(classicAddress, options.tag, options.test)
+}
+
+export { deriveKeypair, deriveAddress, deriveXAddress }

package/src/utils/getBalanceChanges.ts

@@ -0,0 +1,186 @@
+import BigNumber from 'bignumber.js'
+import flatten from 'lodash/flatten'
+import groupBy from 'lodash/groupBy'
+
+import {
+  Amount,
+  Balance,
+  IssuedCurrencyAmount,
+  TransactionMetadata,
+  Node,
+} from '../models'
+
+import { dropsToXrp } from './xrpConversion'
+
+interface BalanceChange {
+  account: string
+  balance: Balance
+}
+interface Fields {
+  Account?: string
+  Balance?: Amount
+  LowLimit?: IssuedCurrencyAmount
+  HighLimit?: IssuedCurrencyAmount
+  // eslint-disable-next-line @typescript-eslint/member-ordering -- okay here, just some of the fields are typed to make it easier
+  [field: string]: unknown
+}
+
+interface NormalizedNode {
+  // 'CreatedNode' | 'ModifiedNode' | 'DeletedNode'
+  NodeType: string
+  LedgerEntryType: string
+  LedgerIndex: string
+  NewFields?: Fields
+  FinalFields?: Fields
+  PreviousFields?: Fields
+  PreviousTxnID?: string
+  PreviousTxnLgrSeq?: number
+}
+
+function normalizeNode(affectedNode: Node): NormalizedNode {
+  const diffType = Object.keys(affectedNode)[0]
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- not quite right, but close enough
+  const node = affectedNode[diffType] as NormalizedNode
+  return {
+    ...node,
+    NodeType: diffType,
+    LedgerEntryType: node.LedgerEntryType,
+    LedgerIndex: node.LedgerIndex,
+    NewFields: node.NewFields,
+    FinalFields: node.FinalFields,
+    PreviousFields: node.PreviousFields,
+  }
+}
+
+function normalizeNodes(metadata: TransactionMetadata): NormalizedNode[] {
+  if (metadata.AffectedNodes.length === 0) {
+    return []
+  }
+  return metadata.AffectedNodes.map(normalizeNode)
+}
+
+function groupByAccount(balanceChanges: BalanceChange[]): Array<{
+  account: string
+  balances: Balance[]
+}> {
+  const grouped = groupBy(balanceChanges, (node) => node.account)
+  return Object.entries(grouped).map(([account, items]) => {
+    return { account, balances: items.map((item) => item.balance) }
+  })
+}
+
+function getValue(balance: Amount): BigNumber {
+  if (typeof balance === 'string') {
+    return new BigNumber(balance)
+  }
+  return new BigNumber(balance.value)
+}
+
+function computeBalanceChange(node: NormalizedNode): BigNumber | null {
+  let value: BigNumber | null = null
+  if (node.NewFields?.Balance) {
+    value = getValue(node.NewFields.Balance)
+  } else if (node.PreviousFields?.Balance && node.FinalFields?.Balance) {
+    value = getValue(node.FinalFields.Balance).minus(
+      getValue(node.PreviousFields.Balance),
+    )
+  }
+  if (value === null || value.isZero()) {
+    return null
+  }
+  return value
+}
+
+function getXRPQuantity(
+  node: NormalizedNode,
+): { account: string; balance: Balance } | null {
+  const value = computeBalanceChange(node)
+
+  if (value === null) {
+    return null
+  }
+
+  return {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- okay here
+    account: (node.FinalFields?.Account ?? node.NewFields?.Account) as string,
+    balance: {
+      currency: 'XRP',
+      value: dropsToXrp(value).toString(),
+    },
+  }
+}
+
+function flipTrustlinePerspective(balanceChange: BalanceChange): BalanceChange {
+  const negatedBalance = new BigNumber(balanceChange.balance.value).negated()
+  return {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- we know this is true
+    account: balanceChange.balance.issuer as string,
+    balance: {
+      issuer: balanceChange.account,
+      currency: balanceChange.balance.currency,
+      value: negatedBalance.toString(),
+    },
+  }
+}
+
+function getTrustlineQuantity(node: NormalizedNode): BalanceChange[] | null {
+  const value = computeBalanceChange(node)
+
+  if (value === null) {
+    return null
+  }
+
+  /*
+   * A trustline can be created with a non-zero starting balance.
+   * If an offer is placed to acquire an asset with no existing trustline,
+   * the trustline can be created when the offer is taken.
+   */
+  const fields = node.NewFields == null ? node.FinalFields : node.NewFields
+
+  // the balance is always from low node's perspective
+  const result = {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- we know that this is true
+    account: fields?.LowLimit?.issuer as string,
+    balance: {
+      issuer: fields?.HighLimit?.issuer,
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- we know that this is true
+      currency: (fields?.Balance as IssuedCurrencyAmount).currency,
+      value: value.toString(),
+    },
+  }
+  return [result, flipTrustlinePerspective(result)]
+}
+
+/**
+ * Computes the complete list of every balance that changed in the ledger
+ * as a result of the given transaction.
+ *
+ * @param metadata - Transaction metadata.
+ * @returns Parsed balance changes.
+ * @category Utilities
+ */
+export default function getBalanceChanges(
+  metadata: TransactionMetadata,
+): Array<{
+  account: string
+  balances: Balance[]
+}> {
+  const quantities = normalizeNodes(metadata).map((node) => {
+    if (node.LedgerEntryType === 'AccountRoot') {
+      const xrpQuantity = getXRPQuantity(node)
+      if (xrpQuantity == null) {
+        return []
+      }
+      return [xrpQuantity]
+    }
+    if (node.LedgerEntryType === 'RippleState') {
+      const trustlineQuantity = getTrustlineQuantity(node)
+      if (trustlineQuantity == null) {
+        return []
+      }
+      return trustlineQuantity
+    }
+    return []
+  })
+  return groupByAccount(flatten(quantities))
+}

package/src/utils/getNFTokenID.ts

@@ -0,0 +1,97 @@
+import flatMap from 'lodash/flatMap'
+import { decode } from 'ripple-binary-codec'
+
+import { NFToken } from '../models/ledger/NFTokenPage'
+import {
+  CreatedNode,
+  isCreatedNode,
+  isModifiedNode,
+  ModifiedNode,
+  TransactionMetadata,
+} from '../models/transactions/metadata'
+
+/**
+ * Ensures that the metadata is in a deserialized format to parse.
+ *
+ * @param meta - the metadata from a `tx` method call. Can be in json format or binary format.
+ * @returns the metadata in a deserialized format.
+ */
+function ensureDecodedMeta(
+  meta: TransactionMetadata | string,
+): TransactionMetadata {
+  if (typeof meta === 'string') {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Meta is either metadata or serialized metadata.
+    return decode(meta) as unknown as TransactionMetadata
+  }
+  return meta
+}
+
+/**
+ * Gets the NFTokenID for an NFT recently minted with NFTokenMint.
+ *
+ * @param meta - Metadata from the response to submitting and waiting for an NFTokenMint transaction or from a `tx` method call.
+ * @returns The NFTokenID for the minted NFT.
+ * @throws if meta is not TransactionMetadata.
+ */
+export default function getNFTokenID(
+  meta: TransactionMetadata | string | undefined,
+): string | undefined {
+  if (typeof meta !== 'string' && meta?.AffectedNodes === undefined) {
+    throw new TypeError(`Unable to parse the parameter given to getNFTokenID.
+      'meta' must be the metadata from an NFTokenMint transaction. Received ${JSON.stringify(
+        meta,
+      )} instead.`)
+  }
+
+  const decodedMeta = ensureDecodedMeta(meta)
+
+  /*
+   * When a mint results in splitting an existing page,
+   * it results in a created page and a modified node. Sometimes,
+   * the created node needs to be linked to a third page, resulting
+   * in modifying that third page's PreviousPageMin or NextPageMin
+   * field changing, but no NFTs within that page changing. In this
+   * case, there will be no previous NFTs and we need to skip.
+   * However, there will always be NFTs listed in the final fields,
+   * as rippled outputs all fields in final fields even if they were
+   * not changed. Thus why we add the additional condition to check
+   * if the PreviousFields contains NFTokens
+   */
+
+  const affectedNodes = decodedMeta.AffectedNodes.filter((node) => {
+    if (isCreatedNode(node)) {
+      return node.CreatedNode.LedgerEntryType === 'NFTokenPage'
+    }
+    if (isModifiedNode(node)) {
+      return (
+        node.ModifiedNode.LedgerEntryType === 'NFTokenPage' &&
+        Boolean(node.ModifiedNode.PreviousFields?.NFTokens)
+      )
+    }
+    return false
+  })
+  /* eslint-disable @typescript-eslint/consistent-type-assertions -- Necessary for parsing metadata */
+  const previousTokenIDSet = new Set(
+    flatMap(affectedNodes, (node) => {
+      const nftokens = isModifiedNode(node)
+        ? (node.ModifiedNode.PreviousFields?.NFTokens as NFToken[])
+        : []
+      return nftokens.map((token) => token.NFToken.NFTokenID)
+    }).filter((id) => Boolean(id)),
+  )
+
+  /* eslint-disable @typescript-eslint/no-unnecessary-condition -- Cleaner to read */
+  const finalTokenIDs = flatMap(affectedNodes, (node) =>
+    (
+      (((node as ModifiedNode).ModifiedNode?.FinalFields?.NFTokens ??
+        (node as CreatedNode).CreatedNode?.NewFields?.NFTokens) as NFToken[]) ??
+      []
+    ).map((token) => token.NFToken.NFTokenID),
+  ).filter((nftokenID) => Boolean(nftokenID))
+  /* eslint-enable @typescript-eslint/consistent-type-assertions -- Necessary for parsing metadata */
+  /* eslint-enable @typescript-eslint/no-unnecessary-condition -- Cleaner to read */
+
+  const nftokenID = finalTokenIDs.find((id) => !previousTokenIDSet.has(id))
+
+  return nftokenID
+}

package/src/utils/hashes/HashPrefix.ts

@@ -0,0 +1,40 @@
+/**
+ * Prefix for hashing functions.
+ *
+ * These prefixes are inserted before the source material used to
+ * generate various hashes. This is done to put each hash in its own
+ * "space." This way, two different types of objects with the
+ * same binary data will produce different hashes.
+ *
+ * Each prefix is a 4-byte value with the last byte set to zero
+ * and the first three bytes formed from the ASCII equivalent of
+ * some arbitrary string. For example "TXN".
+ */
+
+enum HashPrefix {
+  // transaction plus signature to give transaction ID 'TXN'
+  TRANSACTION_ID = 0x54584e00,
+
+  // transaction plus metadata 'TND'
+  TRANSACTION_NODE = 0x534e4400,
+
+  // inner node in tree 'MIN'
+  INNER_NODE = 0x4d494e00,
+
+  // leaf node in tree 'MLN'
+  LEAF_NODE = 0x4d4c4e00,
+
+  // inner transaction to sign 'STX'
+  TRANSACTION_SIGN = 0x53545800,
+
+  // inner transaction to sign (TESTNET) 'stx'
+  TRANSACTION_SIGN_TESTNET = 0x73747800,
+
+  // inner transaction to multisign 'SMT'
+  TRANSACTION_MULTISIGN = 0x534d5400,
+
+  // ledger 'LWR'
+  LEDGER = 0x4c575200,
+}
+
+export default HashPrefix

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
+}