xrpl 1.0.0-mpt-beta

package/src/utils/hashes/index.ts

@@ -0,0 +1,188 @@
+/* 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 { bytesToHex } from '@xrplf/isomorphic/utils'
+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 bytesToHex(decodeAccountID(address))
+}
+
+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 bytesToHex(Uint8Array.from(bytes))
+}
+
+/**
+ * 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,16 @@
+import { sha512 } from '@xrplf/isomorphic/sha512'
+import { bytesToHex, hexToBytes } from '@xrplf/isomorphic/utils'
+
+const HASH_BYTES = 32
+
+/**
+ * Compute a sha512Half Hash of a hex string.
+ *
+ * @param hex - Hex string to hash.
+ * @returns Hash of hex.
+ */
+function sha512Half(hex: string): string {
+  return bytesToHex(sha512(hexToBytes(hex)).slice(0, HASH_BYTES))
+}
+
+export default sha512Half

package/src/utils/index.ts

@@ -0,0 +1,233 @@
+import {
+  classicAddressToXAddress,
+  decodeAccountID,
+  decodeAccountPublic,
+  decodeNodePublic,
+  decodeSeed,
+  decodeXAddress,
+  encodeAccountID,
+  encodeAccountPublic,
+  encodeNodePublic,
+  encodeSeed,
+  encodeXAddress,
+  isValidClassicAddress,
+  isValidXAddress,
+  xAddressToClassicAddress,
+} from 'ripple-address-codec'
+import {
+  encode as rbcEncode,
+  decode as rbcDecode,
+  encodeForMultisigning as rbcEncodeForMultisigning,
+  encodeForSigning as rbcEncodeForSigning,
+  encodeForSigningClaim as rbcEncodeForSigningClaim,
+} 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 getXChainClaimID from './getXChainClaimID'
+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'
+import { mptUint64ToHex } from './mptConversion'
+
+/**
+ * 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 rbcEncode(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 rbcEncodeForSigning(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 rbcEncodeForSigningClaim(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 rbcEncodeForMultisigning(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 rbcDecode(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,
+  getXChainClaimID,
+  mptUint64ToHex,
+}

package/src/utils/mptConversion.ts

@@ -0,0 +1,52 @@
+import BigNumber from 'bignumber.js'
+import { ValidationError } from '../errors'
+
+const SANITY_CHECK = /^[0-9]+$/u
+
+/**
+ * Convert an unsigned 64-bit integer string to hex string. Mostly used for the MaximumAmount field
+ * in MPTokenIssuanceCreate.
+ *
+ * @param numberToConvert - Non-negative number string.
+ * @returns Amount in hex string.
+ * @throws When amount is invalid.
+ * @category Utilities
+ */
+export function mptUint64ToHex(numberToConvert: string): string {
+  // convert to base 10 string first for inputs like scientific notation
+  const number = new BigNumber(numberToConvert).toString(10)
+
+  // check that the value is valid and actually a number
+  if (typeof numberToConvert === 'string' && number === 'NaN') {
+    throw new ValidationError(
+      `mptUint64ToHex: invalid value '${numberToConvert}', should be a string-encoded number.`,
+    )
+  }
+
+  // mpts are only whole units
+  if (number.includes('.')) {
+    throw new ValidationError(
+      `mptUint64ToHex: value '${numberToConvert}' has too many decimal places.`,
+    )
+  }
+  if (number.includes('-')) {
+    throw new ValidationError(
+      `mptUint64ToHex: value '${numberToConvert}' cannot be negative.`,
+    )
+  }
+
+  if (!SANITY_CHECK.exec(number)) {
+    throw new ValidationError(
+      `mptUint64ToHex: failed sanity check -` +
+        ` value '${numberToConvert}',` +
+        ` does not match (^[0-9]+$).`,
+    )
+  }
+
+  if (Number(BigInt(number) & BigInt('0x8000000000000000')) != 0)
+    throw new ValidationError(
+      `mptUint64ToHex: invalid value '${numberToConvert}', should be within 63-bit range.`,
+    )
+
+  return BigInt(number).toString(16)
+}

package/src/utils/parseNFTokenID.ts

@@ -0,0 +1,95 @@
+/* eslint-disable @typescript-eslint/no-magic-numbers -- Doing hex string parsing. */
+import { hexToBytes } from '@xrplf/isomorphic/utils'
+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. */
+  const seed = 384160001
+  const increment = 2459
+  const max = 4294967296
+
+  const scramble = new BigNumber(seed)
+    .multipliedBy(tokenSeq)
+    .modulo(max)
+    .plus(increment)
+    .modulo(max)
+    .toNumber()
+  return (taxon ^ scramble) >>> 0
+  /* 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(hexToBytes(nftokenID.substring(8, 48))),
+    Taxon: unscrambleTaxon(scrambledTaxon, sequence),
+    Sequence: sequence,
+  }
+
+  return NFTokenIDData
+}