xrpl 2.10.0 → 2.11.0

package/src/utils/parseNFTokenID.ts

@@ -0,0 +1,84 @@
+/* eslint-disable @typescript-eslint/no-magic-numbers -- Doing hex string parsing. */
+import BigNumber from 'bignumber.js'
+import { encodeAccountID } from 'ripple-address-codec'
+
+import { XrplError } from '../errors'
+
+/**
+ * An issuer may issue several NFTs with the same taxon; to ensure that NFTs are
+ * spread across multiple pages we lightly mix the taxon up by using the sequence
+ * (which is not under the issuer's direct control) as the seed for a simple linear
+ * congruential generator.
+ *
+ * From the Hull-Dobell theorem we know that f(x)=(m*x+c) mod n will yield a
+ * permutation of [0, n) when n is a power of 2 if m is congruent to 1 mod 4 and
+ * c is odd. By doing a bitwise XOR with this permutation we can scramble/unscramble
+ * the taxon.
+ *
+ * The XLS-20d proposal fixes m = 384160001 and c = 2459.
+ * We then take the modulus of 2^32 which is 4294967296.
+ *
+ * @param taxon - The scrambled or unscrambled taxon (The XOR is both the encoding and decoding)
+ * @param tokenSeq - The account sequence when the token was minted. Used as a psuedorandom seed.
+ * @returns the opposite taxon. If the taxon was scrambled it becomes unscrambled, and vice versa.
+ */
+function unscrambleTaxon(taxon: number, tokenSeq: number): number {
+  /* eslint-disable no-bitwise -- XOR is part of the encode/decode scheme. */
+  return (taxon ^ (384160001 * tokenSeq + 2459)) % 4294967296
+  /* eslint-enable no-bitwise */
+}
+
+/**
+ * Parses an NFTokenID into the information it is encoding.
+ *
+ * Example decoding:
+ *
+ * 000B 0539 C35B55AA096BA6D87A6E6C965A6534150DC56E5E 12C5D09E 0000000C
+ * +--- +--- +--------------------------------------- +------- +-------
+ * |    |    |                                        |        |
+ * |    |    |                                        |        `---> Sequence: 12
+ * |    |    |                                        |
+ * |    |    |                                        `---> Scrambled Taxon: 314,953,886
+ * |    |    |                                              Unscrambled Taxon: 1337
+ * |    |    |
+ * |    |    `---> Issuer: rJoxBSzpXhPtAuqFmqxQtGKjA13jUJWthE
+ * |    |
+ * |    `---> TransferFee: 1337.0 bps or 13.37%
+ * |
+ * `---> Flags: 11 -> lsfBurnable, lsfOnlyXRP and lsfTransferable
+ *
+ * @param nftokenID - A hex string which identifies an NFToken on the ledger.
+ * @throws XrplError when given an invalid nftokenID.
+ * @returns a decoded nftokenID with all fields encoded within.
+ */
+export default function parseNFTokenID(nftokenID: string): {
+  NFTokenID: string
+  Flags: number
+  TransferFee: number
+  Issuer: string
+  Taxon: number
+  Sequence: number
+} {
+  const expectedLength = 64
+  if (nftokenID.length !== expectedLength) {
+    throw new XrplError(`Attempting to parse a nftokenID with length ${nftokenID.length}
+    , but expected a token with length ${expectedLength}`)
+  }
+
+  const scrambledTaxon = new BigNumber(
+    nftokenID.substring(48, 56),
+    16,
+  ).toNumber()
+  const sequence = new BigNumber(nftokenID.substring(56, 64), 16).toNumber()
+
+  const NFTokenIDData = {
+    NFTokenID: nftokenID,
+    Flags: new BigNumber(nftokenID.substring(0, 4), 16).toNumber(),
+    TransferFee: new BigNumber(nftokenID.substring(4, 8), 16).toNumber(),
+    Issuer: encodeAccountID(Buffer.from(nftokenID.substring(8, 48), 'hex')),
+    Taxon: unscrambleTaxon(scrambledTaxon, sequence),
+    Sequence: sequence,
+  }
+
+  return NFTokenIDData
+}

package/src/utils/quality.ts

@@ -0,0 +1,169 @@
+import BigNumber from 'bignumber.js'
+
+import { ValidationError } from '../errors'
+
+const BASE_TEN = 10
+const ONE_BILLION = '1000000000'
+const TWO_BILLION = '2000000000'
+
+function percentToDecimal(percent: string): string {
+  if (!percent.endsWith('%')) {
+    throw new ValidationError(`Value ${percent} must end with %`)
+  }
+
+  // Split the string on % and filter out any empty strings
+  const split = percent.split('%').filter((str) => str !== '')
+  if (split.length !== 1) {
+    throw new ValidationError(`Value ${percent} contains too many % signs`)
+  }
+
+  return new BigNumber(split[0]).dividedBy('100').toString(BASE_TEN)
+}
+
+/**
+ * Converts a string decimal to "billionths" format for use with TransferRate.
+ *
+ * @param decimal - A string decimal between 0 and 1.00
+ * @returns A number in the "billionths" format.
+ * @throws ValidationError when the parameter is not convertible to
+ * "billionths" format.
+ * @category Utilities
+ */
+export function decimalToTransferRate(decimal: string): number {
+  const rate = new BigNumber(decimal).times(ONE_BILLION).plus(ONE_BILLION)
+
+  if (rate.isLessThan(ONE_BILLION) || rate.isGreaterThan(TWO_BILLION)) {
+    throw new ValidationError(`Decimal value must be between 0 and 1.00.`)
+  }
+
+  const billionths = rate.toString(BASE_TEN)
+
+  if (billionths === ONE_BILLION) {
+    return 0
+  }
+
+  if (billionths === 'NaN') {
+    throw new ValidationError(`Value is not a number`)
+  }
+
+  if (billionths.includes('.')) {
+    throw new ValidationError(`Decimal exceeds maximum precision.`)
+  }
+
+  return Number(billionths)
+}
+
+/**
+ * Converts a string percent to "billionths" format for use with TransferRate.
+ *
+ * @param percent - A string percent between 0% and 100%.
+ * @returns A number in the "billionths" format.
+ * @throws ValidationError when the percent parameter is not convertible to
+ * "billionths" format.
+ * @category Utilities
+ */
+export function percentToTransferRate(percent: string): number {
+  return decimalToTransferRate(percentToDecimal(percent))
+}
+
+/**
+ * Converts a string decimal to the "billionths" format for use with QualityIn/
+ * QualityOut
+ *
+ * @param decimal - A string decimal (i.e. ".00034").
+ * @returns A number in the "billionths" format.
+ * @throws ValidationError when the parameter is not convertible to
+ * "billionths" format.
+ * @category Utilities
+ */
+export function decimalToQuality(decimal: string): number {
+  const rate = new BigNumber(decimal).times(ONE_BILLION)
+
+  const billionths = rate.toString(BASE_TEN)
+
+  if (billionths === 'NaN') {
+    throw new ValidationError(`Value is not a number`)
+  }
+
+  if (billionths.includes('-')) {
+    throw new ValidationError('Cannot have negative Quality')
+  }
+
+  if (billionths === ONE_BILLION) {
+    return 0
+  }
+
+  if (billionths.includes('.')) {
+    throw new ValidationError(`Decimal exceeds maximum precision.`)
+  }
+
+  return Number(billionths)
+}
+
+/**
+ * Converts a quality in "billionths" format to a decimal.
+ *
+ * @param quality - Quality to convert to decimal.
+ * @returns decimal representation of quality.
+ * @throws ValidationError when quality is not convertible to decimal format.
+ * @category Utilities
+ */
+export function qualityToDecimal(quality: number): string {
+  if (!Number.isInteger(quality)) {
+    throw new ValidationError('Quality must be an integer')
+  }
+
+  if (quality < 0) {
+    throw new ValidationError('Negative quality not allowed')
+  }
+
+  if (quality === 0) {
+    return '1'
+  }
+
+  const decimal = new BigNumber(quality).dividedBy(ONE_BILLION)
+
+  return decimal.toString(BASE_TEN)
+}
+
+/**
+ * Converts a transfer rate in "billionths" format to a decimal.
+ *
+ * @param rate - TransferRate to convert to decimal.
+ * @returns decimal representation of transfer Rate.
+ * @throws ValidationError when it cannot convert from billionths format.
+ * @category Utilities
+ */
+export function transferRateToDecimal(rate: number): string {
+  if (!Number.isInteger(rate)) {
+    throw new ValidationError(
+      'Error decoding, transfer Rate must be an integer',
+    )
+  }
+
+  if (rate === 0) {
+    return '0'
+  }
+
+  const decimal = new BigNumber(rate).minus(ONE_BILLION).dividedBy(ONE_BILLION)
+
+  if (decimal.isLessThan(0)) {
+    throw new ValidationError('Error decoding, negative transfer rate')
+  }
+
+  return decimal.toString(BASE_TEN)
+}
+
+/**
+ * Converts a string percent to the "billionths" format for use with QualityIn/
+ * QualityOut
+ *
+ * @param percent - A string percent (i.e. ".034%").
+ * @returns A number in the "billionths" format.
+ * @throws ValidationError when the percent parameter is not convertible to
+ * "billionths" format.
+ * @category Utilities
+ */
+export function percentToQuality(percent: string): number {
+  return decimalToQuality(percentToDecimal(percent))
+}

package/src/utils/signPaymentChannelClaim.ts

@@ -0,0 +1,27 @@
+import { encodeForSigningClaim } from 'ripple-binary-codec'
+import { sign } from 'ripple-keypairs'
+
+import { xrpToDrops } from './xrpConversion'
+
+/**
+ * Sign a payment channel claim.
+ *
+ * @param channel - Channel identifier specified by the paymentChannelClaim.
+ * @param amount - Amount specified by the paymentChannelClaim.
+ * @param privateKey - Private Key to sign paymentChannelClaim with.
+ * @returns True if the channel is valid.
+ * @category Utilities
+ */
+function signPaymentChannelClaim(
+  channel: string,
+  amount: string,
+  privateKey: string,
+): string {
+  const signingData = encodeForSigningClaim({
+    channel,
+    amount: xrpToDrops(amount),
+  })
+  return sign(signingData, privateKey)
+}
+
+export default signPaymentChannelClaim

package/src/utils/stringConversion.ts

@@ -0,0 +1,27 @@
+/**
+ * Converts a string to its hex equivalent. Useful for Memos.
+ *
+ * @param string - The string to convert to Hex.
+ * @returns The Hex equivalent of the string.
+ * @category Utilities
+ */
+function convertStringToHex(string: string): string {
+  return Buffer.from(string, 'utf8').toString('hex').toUpperCase()
+}
+
+/**
+ * Converts hex to its string equivalent. Useful to read the Domain field and some Memos.
+ *
+ * @param hex - The hex to convert to a string.
+ * @param encoding - The encoding to use. Defaults to 'utf8' (UTF-8). 'ascii' is also allowed.
+ * @returns The converted string.
+ * @category Utilities
+ */
+function convertHexToString(
+  hex: string,
+  encoding: BufferEncoding = 'utf8',
+): string {
+  return Buffer.from(hex, 'hex').toString(encoding)
+}
+
+export { convertHexToString, convertStringToHex }

package/src/utils/timeConversion.ts

@@ -0,0 +1,53 @@
+const RIPPLE_EPOCH_DIFF = 0x386d4380
+
+/**
+ * Convert a ripple timestamp to a unix timestamp.
+ *
+ * @param rpepoch - (seconds since 1/1/2000 GMT).
+ * @returns Milliseconds since unix epoch.
+ * @category Utilities
+ */
+function rippleTimeToUnixTime(rpepoch: number): number {
+  return (rpepoch + RIPPLE_EPOCH_DIFF) * 1000
+}
+
+/**
+ * Convert a unix timestamp to a ripple timestamp.
+ *
+ * @param timestamp - (ms since unix epoch).
+ * @returns Seconds since Ripple Epoch (1/1/2000 GMT).
+ * @category Utilities
+ */
+function unixTimeToRippleTime(timestamp: number): number {
+  return Math.round(timestamp / 1000) - RIPPLE_EPOCH_DIFF
+}
+
+/**
+ * Convert a ripple timestamp to an Iso8601 timestamp.
+ *
+ * @param rippleTime - Is the number of seconds since Ripple Epoch (1/1/2000 GMT).
+ * @returns Iso8601 international standard date format.
+ * @category Utilities
+ */
+function rippleTimeToISOTime(rippleTime: number): string {
+  return new Date(rippleTimeToUnixTime(rippleTime)).toISOString()
+}
+
+/**
+ * Convert an ISO8601 timestmap to a ripple timestamp.
+ *
+ * @param iso8601 - International standard date format.
+ * @returns Seconds since ripple epoch (1/1/2000 GMT).
+ * @category Utilities
+ */
+function isoTimeToRippleTime(iso8601: string | Date): number {
+  const isoDate = typeof iso8601 === 'string' ? new Date(iso8601) : iso8601
+  return unixTimeToRippleTime(isoDate.getTime())
+}
+
+export {
+  rippleTimeToUnixTime,
+  unixTimeToRippleTime,
+  rippleTimeToISOTime,
+  isoTimeToRippleTime,
+}

package/src/utils/verifyPaymentChannelClaim.ts

@@ -0,0 +1,30 @@
+import { encodeForSigningClaim } from 'ripple-binary-codec'
+import { verify } from 'ripple-keypairs'
+
+import { xrpToDrops } from './xrpConversion'
+
+/**
+ * Verify the signature of a payment channel claim.
+ *
+ * @param channel - Channel identifier specified by the paymentChannelClaim.
+ * @param amount - Amount specified by the paymentChannelClaim.
+ * @param signature - Signature produced from signing paymentChannelClaim.
+ * @param publicKey - Public key that signed the paymentChannelClaim.
+ * @returns True if the channel is valid.
+ * @category Utilities
+ */
+// eslint-disable-next-line max-params -- Needs 4 params
+function verifyPaymentChannelClaim(
+  channel: string,
+  amount: string,
+  signature: string,
+  publicKey: string,
+): boolean {
+  const signingData = encodeForSigningClaim({
+    channel,
+    amount: xrpToDrops(amount),
+  })
+  return verify(signingData, signature, publicKey)
+}
+
+export default verifyPaymentChannelClaim

package/src/utils/xrpConversion.ts

@@ -0,0 +1,104 @@
+import BigNumber from 'bignumber.js'
+
+import { ValidationError } from '../errors'
+
+const DROPS_PER_XRP = 1000000.0
+const MAX_FRACTION_LENGTH = 6
+const BASE_TEN = 10
+const SANITY_CHECK = /^-?[0-9.]+$/u
+
+/**
+ * Convert Drops to XRP.
+ *
+ * @param dropsToConvert - Drops to convert to XRP. This can be a string, number, or BigNumber.
+ * @returns Amount in XRP.
+ * @throws When drops amount is invalid.
+ * @category Utilities
+ */
+export function dropsToXrp(dropsToConvert: BigNumber.Value): string {
+  /*
+   * Converting to BigNumber and then back to string should remove any
+   * decimal point followed by zeros, e.g. '1.00'.
+   * Important: specify base BASE_10 to avoid exponential notation, e.g. '1e-7'.
+   */
+  const drops = new BigNumber(dropsToConvert).toString(BASE_TEN)
+
+  // check that the value is valid and actually a number
+  if (typeof dropsToConvert === 'string' && drops === 'NaN') {
+    throw new ValidationError(
+      `dropsToXrp: invalid value '${dropsToConvert}', should be a BigNumber or string-encoded number.`,
+    )
+  }
+
+  // drops are only whole units
+  if (drops.includes('.')) {
+    throw new ValidationError(
+      `dropsToXrp: value '${drops}' has too many decimal places.`,
+    )
+  }
+
+  /*
+   * This should never happen; the value has already been
+   * validated above. This just ensures BigNumber did not do
+   * something unexpected.
+   */
+  if (!SANITY_CHECK.exec(drops)) {
+    throw new ValidationError(
+      `dropsToXrp: failed sanity check -` +
+        ` value '${drops}',` +
+        ` does not match (^-?[0-9]+$).`,
+    )
+  }
+
+  return new BigNumber(drops).dividedBy(DROPS_PER_XRP).toString(BASE_TEN)
+}
+
+/**
+ * Convert an amount in XRP to an amount in drops.
+ *
+ * @param xrpToConvert - Amount in XRP.
+ * @returns Amount in drops.
+ * @throws When amount in xrp is invalid.
+ * @category Utilities
+ */
+export function xrpToDrops(xrpToConvert: BigNumber.Value): string {
+  // Important: specify base BASE_TEN to avoid exponential notation, e.g. '1e-7'.
+  const xrp = new BigNumber(xrpToConvert).toString(BASE_TEN)
+
+  // check that the value is valid and actually a number
+  if (typeof xrpToConvert === 'string' && xrp === 'NaN') {
+    throw new ValidationError(
+      `xrpToDrops: invalid value '${xrpToConvert}', should be a BigNumber or string-encoded number.`,
+    )
+  }
+
+  /*
+   * This should never happen; the value has already been
+   * validated above. This just ensures BigNumber did not do
+   * something unexpected.
+   */
+  if (!SANITY_CHECK.exec(xrp)) {
+    throw new ValidationError(
+      `xrpToDrops: failed sanity check - value '${xrp}', does not match (^-?[0-9.]+$).`,
+    )
+  }
+
+  const components = xrp.split('.')
+  if (components.length > 2) {
+    throw new ValidationError(
+      `xrpToDrops: failed sanity check - value '${xrp}' has too many decimal points.`,
+    )
+  }
+
+  const fraction = components[1] || '0'
+  if (fraction.length > MAX_FRACTION_LENGTH) {
+    throw new ValidationError(
+      `xrpToDrops: value '${xrp}' has too many decimal places.`,
+    )
+  }
+
+  return new BigNumber(xrp)
+    .times(DROPS_PER_XRP)
+    .integerValue(BigNumber.ROUND_FLOOR)
+    .toString(BASE_TEN)
+}