xrpl 2.10.0 → 2.11.0

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

package/src/utils/hashes/index.ts

@@ -0,0 +1,187 @@
+/* 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 { decodeAccountID } from 'ripple-address-codec'
+
+import hashLedger, {
+  hashLedgerHeader,
+  hashSignedTx,
+  hashTxTree,
+  hashStateTree,
+} from './hashLedger'
+import HashPrefix from './HashPrefix'
+import ledgerSpaces from './ledgerSpaces'
+import sha512Half from './sha512Half'
+
+const HEX = 16
+const BYTE_LENGTH = 4
+
+function addressToHex(address: string): string {
+  return Buffer.from(decodeAccountID(address)).toString('hex')
+}
+
+function ledgerSpaceHex(name: keyof typeof ledgerSpaces): string {
+  return ledgerSpaces[name].charCodeAt(0).toString(HEX).padStart(4, '0')
+}
+
+const MASK = 0xff
+function currencyToHex(currency: string): string {
+  if (currency.length !== 3) {
+    return currency
+  }
+
+  const bytes = Array(20).fill(0)
+  bytes[12] = currency.charCodeAt(0) & MASK
+  bytes[13] = currency.charCodeAt(1) & MASK
+  bytes[14] = currency.charCodeAt(2) & MASK
+  return Buffer.from(bytes).toString('hex')
+}
+
+/**
+ * Hash the given binary transaction data with the single-signing prefix.
+ *
+ * See [Serialization Format](https://xrpl.org/serialization.html).
+ *
+ * @param txBlobHex - The binary transaction blob as a hexadecimal string.
+ * @returns The hash to sign.
+ * @category Utilities
+ */
+export function hashTx(txBlobHex: string): string {
+  const prefix = HashPrefix.TRANSACTION_SIGN.toString(HEX).toUpperCase()
+  return sha512Half(prefix + txBlobHex)
+}
+
+/**
+ * Compute AccountRoot Ledger Object Index.
+ *
+ * All objects in a ledger's state tree have a unique Index.
+ * The AccountRoot Ledger Object Index is derived by hashing the
+ * address with a namespace identifier. This ensures every
+ * Index is unique.
+ *
+ * See [Ledger Object Indexes](https://xrpl.org/ledger-object-ids.html).
+ *
+ * @param address - The classic account address.
+ * @returns The Ledger Object Index for the account.
+ * @category Utilities
+ */
+export function hashAccountRoot(address: string): string {
+  return sha512Half(ledgerSpaceHex('account') + addressToHex(address))
+}
+
+/**
+ * [SignerList Index Format](https://xrpl.org/signerlist.html#signerlist-id-format).
+ *
+ * The Index of a SignerList object is the SHA-512Half of the following values, concatenated in order:
+ *   * The RippleState space key (0x0053)
+ *   * The AccountID of the owner of the SignerList
+ *   * The SignerListID (currently always 0).
+ *
+ * This method computes a SignerList Ledger Object Index.
+ *
+ * @param address - The classic account address of the SignerList owner (starting with r).
+ * @returns The Index of the account's SignerList object.
+ * @category Utilities
+ */
+export function hashSignerListId(address: string): string {
+  return sha512Half(
+    `${ledgerSpaceHex('signerList') + addressToHex(address)}00000000`,
+  )
+}
+
+/**
+ * [Offer Index Format](https://xrpl.org/offer.html#offer-id-format).
+ *
+ * The Index of a Offer object is the SHA-512Half of the following values, concatenated in order:
+ * * The Offer space key (0x006F)
+ * * The AccountID of the account placing the offer
+ * * The Sequence number of the OfferCreate transaction that created the offer.
+ *
+ * This method computes an Offer Index.
+ *
+ * @param address - The classic account address of the SignerList owner (starting with r).
+ * @param sequence - Sequence of the Offer.
+ * @returns The Index of the account's Offer object.
+ * @category Utilities
+ */
+export function hashOfferId(address: string, sequence: number): string {
+  const hexPrefix = ledgerSpaces.offer
+    .charCodeAt(0)
+    .toString(HEX)
+    .padStart(2, '0')
+  const hexSequence = sequence.toString(HEX).padStart(8, '0')
+  const prefix = `00${hexPrefix}`
+  return sha512Half(prefix + addressToHex(address) + hexSequence)
+}
+
+/**
+ * Compute the hash of a Trustline.
+ *
+ * @param address1 - One of the addresses in the Trustline.
+ * @param address2 - The other address in the Trustline.
+ * @param currency - Currency in the Trustline.
+ * @returns The hash of the Trustline.
+ * @category Utilities
+ */
+export function hashTrustline(
+  address1: string,
+  address2: string,
+  currency: string,
+): string {
+  const address1Hex = addressToHex(address1)
+  const address2Hex = addressToHex(address2)
+
+  const swap = new BigNumber(address1Hex, 16).isGreaterThan(
+    new BigNumber(address2Hex, 16),
+  )
+  const lowAddressHex = swap ? address2Hex : address1Hex
+  const highAddressHex = swap ? address1Hex : address2Hex
+
+  const prefix = ledgerSpaceHex('rippleState')
+  return sha512Half(
+    prefix + lowAddressHex + highAddressHex + currencyToHex(currency),
+  )
+}
+
+/**
+ * Compute the Hash of an Escrow LedgerEntry.
+ *
+ * @param address - Address of the Escrow.
+ * @param sequence - OfferSequence of the Escrow.
+ * @returns The hash of the Escrow LedgerEntry.
+ * @category Utilities
+ */
+export function hashEscrow(address: string, sequence: number): string {
+  return sha512Half(
+    ledgerSpaceHex('escrow') +
+      addressToHex(address) +
+      sequence.toString(HEX).padStart(BYTE_LENGTH * 2, '0'),
+  )
+}
+
+/**
+ * Compute the hash of a Payment Channel.
+ *
+ * @param address - Account of the Payment Channel.
+ * @param dstAddress - Destination Account of the Payment Channel.
+ * @param sequence - Sequence number of the Transaction that created the Payment Channel.
+ * @returns Hash of the Payment Channel.
+ * @category Utilities
+ */
+export function hashPaymentChannel(
+  address: string,
+  dstAddress: string,
+  sequence: number,
+): string {
+  return sha512Half(
+    ledgerSpaceHex('paychan') +
+      addressToHex(address) +
+      addressToHex(dstAddress) +
+      sequence.toString(HEX).padStart(BYTE_LENGTH * 2, '0'),
+  )
+}
+
+export { hashLedgerHeader, hashSignedTx, hashLedger, hashStateTree, hashTxTree }

package/src/utils/hashes/ledgerSpaces.ts

@@ -0,0 +1,34 @@
+/**
+ * XRP Ledger namespace prefixes.
+ *
+ * The XRP Ledger is a key-value store. In order to avoid name collisions,
+ * names are partitioned into namespaces.
+ *
+ * Each namespace is just a single character prefix.
+ *
+ * See [LedgerNameSpace enum](https://github.com/ripple/rippled/blob/master/src/ripple/protocol/LedgerFormats.h#L100).
+ */
+const ledgerSpaces = {
+  account: 'a',
+  dirNode: 'd',
+  generatorMap: 'g',
+  rippleState: 'r',
+  // Entry for an offer.
+  offer: 'o',
+  // Directory of things owned by an account.
+  ownerDir: 'O',
+  // Directory of order books.
+  bookDir: 'B',
+  contract: 'c',
+  skipList: 's',
+  escrow: 'u',
+  amendment: 'f',
+  feeSettings: 'e',
+  ticket: 'T',
+  signerList: 'S',
+  paychan: 'x',
+  check: 'C',
+  depositPreauth: 'p',
+}
+
+export default ledgerSpaces

package/src/utils/hashes/sha512Half.ts

@@ -0,0 +1,19 @@
+import { createHash } from 'crypto'
+
+const HASH_SIZE = 64
+
+/**
+ * Compute a sha512Half Hash of a hex string.
+ *
+ * @param hex - Hex string to hash.
+ * @returns Hash of hex.
+ */
+function sha512Half(hex: string): string {
+  return createHash('sha512')
+    .update(Buffer.from(hex, 'hex'))
+    .digest('hex')
+    .toUpperCase()
+    .slice(0, HASH_SIZE)
+}
+
+export default sha512Half

package/src/utils/index.ts

@@ -0,0 +1,223 @@
+import {
+  classicAddressToXAddress,
+  decodeAccountID,
+  decodeAccountPublic,
+  decodeNodePublic,
+  decodeSeed,
+  decodeXAddress,
+  encodeAccountID,
+  encodeAccountPublic,
+  encodeNodePublic,
+  encodeSeed,
+  encodeXAddress,
+  isValidClassicAddress,
+  isValidXAddress,
+  xAddressToClassicAddress,
+} from 'ripple-address-codec'
+import * as rbc from 'ripple-binary-codec'
+import { verify as verifyKeypairSignature } from 'ripple-keypairs'
+
+import { LedgerEntry } from '../models/ledger'
+import { Response } from '../models/methods'
+import { PaymentChannelClaim } from '../models/transactions/paymentChannelClaim'
+import { Transaction } from '../models/transactions/transaction'
+
+import { deriveKeypair, deriveAddress, deriveXAddress } from './derive'
+import getBalanceChanges from './getBalanceChanges'
+import getNFTokenID from './getNFTokenID'
+import {
+  hashSignedTx,
+  hashTx,
+  hashAccountRoot,
+  hashSignerListId,
+  hashOfferId,
+  hashTrustline,
+  hashTxTree,
+  hashStateTree,
+  hashLedger,
+  hashLedgerHeader,
+  hashEscrow,
+  hashPaymentChannel,
+} from './hashes'
+import parseNFTokenID from './parseNFTokenID'
+import {
+  percentToTransferRate,
+  decimalToTransferRate,
+  transferRateToDecimal,
+  percentToQuality,
+  decimalToQuality,
+  qualityToDecimal,
+} from './quality'
+import signPaymentChannelClaim from './signPaymentChannelClaim'
+import { convertHexToString, convertStringToHex } from './stringConversion'
+import {
+  rippleTimeToISOTime,
+  isoTimeToRippleTime,
+  rippleTimeToUnixTime,
+  unixTimeToRippleTime,
+} from './timeConversion'
+import verifyPaymentChannelClaim from './verifyPaymentChannelClaim'
+import { xrpToDrops, dropsToXrp } from './xrpConversion'
+
+/**
+ * Check if a secret is valid.
+ *
+ * @param secret - Secret to test for validity.
+ * @returns True if secret can be derived into a keypair.
+ * @category Utilities
+ */
+function isValidSecret(secret: string): boolean {
+  try {
+    deriveKeypair(secret)
+    return true
+  } catch (_err) {
+    return false
+  }
+}
+
+/**
+ * Encodes a LedgerEntry or Transaction into a hex string
+ *
+ * @param object - LedgerEntry or Transaction in JSON format.
+ * @returns A hex string representing the encoded object.
+ */
+function encode(object: Transaction | LedgerEntry): string {
+  return rbc.encode(object)
+}
+
+/**
+ * Encodes a Transaction for signing
+ *
+ * @param object - LedgerEntry in JSON or Transaction format.
+ * @returns A hex string representing the encoded object.
+ */
+function encodeForSigning(object: Transaction): string {
+  return rbc.encodeForSigning(object)
+}
+
+/**
+ * Encodes a PaymentChannelClaim for signing
+ *
+ * @param object - PaymentChannelClaim in JSON format.
+ * @returns A hex string representing the encoded object.
+ */
+function encodeForSigningClaim(object: PaymentChannelClaim): string {
+  return rbc.encodeForSigningClaim(object)
+}
+
+/**
+ * Encodes a Transaction for multi-signing
+ *
+ * @param object - Transaction in JSON format.
+ * @param signer - The address of the account signing this transaction
+ * @returns A hex string representing the encoded object.
+ */
+function encodeForMultiSigning(object: Transaction, signer: string): string {
+  return rbc.encodeForMultisigning(object, signer)
+}
+
+/**
+ * Decodes a hex string into a transaction | ledger entry
+ *
+ * @param hex - hex string in the XRPL serialization format.
+ * @returns The hex string decoded according to XRPL serialization format.
+ */
+function decode(hex: string): Record<string, unknown> {
+  return rbc.decode(hex)
+}
+
+/**
+ * Validates that a given address is a valid X-Address or a valid classic
+ * address.
+ *
+ * @param address - Address to validate.
+ * @returns True if address is a valid X-Address or classic address.
+ * @category Utilities
+ */
+function isValidAddress(address: string): boolean {
+  return isValidXAddress(address) || isValidClassicAddress(address)
+}
+
+/**
+ * Returns true if there are more pages of data.
+ *
+ * When there are more results than contained in the response, the response
+ * includes a `marker` field.
+ *
+ * See https://ripple.com/build/rippled-apis/#markers-and-pagination.
+ *
+ * @param response - Response to check for more pages on.
+ * @returns Whether the response has more pages of data.
+ * @category Utilities
+ */
+function hasNextPage(response: Response): boolean {
+  // eslint-disable-next-line @typescript-eslint/dot-notation -- only checking if it exists
+  return Boolean(response.result['marker'])
+}
+
+/**
+ * @category Utilities
+ */
+const hashes = {
+  hashSignedTx,
+  hashTx,
+  hashAccountRoot,
+  hashSignerListId,
+  hashOfferId,
+  hashTrustline,
+  hashTxTree,
+  hashStateTree,
+  hashLedger,
+  hashLedgerHeader,
+  hashEscrow,
+  hashPaymentChannel,
+}
+
+export {
+  getBalanceChanges,
+  dropsToXrp,
+  xrpToDrops,
+  hasNextPage,
+  rippleTimeToISOTime,
+  isoTimeToRippleTime,
+  rippleTimeToUnixTime,
+  unixTimeToRippleTime,
+  percentToQuality,
+  decimalToQuality,
+  percentToTransferRate,
+  decimalToTransferRate,
+  transferRateToDecimal,
+  qualityToDecimal,
+  isValidSecret,
+  isValidAddress,
+  hashes,
+  deriveKeypair,
+  deriveAddress,
+  deriveXAddress,
+  signPaymentChannelClaim,
+  verifyKeypairSignature,
+  verifyPaymentChannelClaim,
+  convertStringToHex,
+  convertHexToString,
+  classicAddressToXAddress,
+  xAddressToClassicAddress,
+  isValidXAddress,
+  isValidClassicAddress,
+  encodeSeed,
+  decodeSeed,
+  encodeAccountID,
+  decodeAccountID,
+  encodeNodePublic,
+  decodeNodePublic,
+  encodeAccountPublic,
+  decodeAccountPublic,
+  encodeXAddress,
+  decodeXAddress,
+  encode,
+  decode,
+  encodeForMultiSigning,
+  encodeForSigning,
+  encodeForSigningClaim,
+  getNFTokenID,
+  parseNFTokenID,
+}