docs: categorize utilities correctly (#1746)

* docs: categorize utilities correctly

src/models/transactions/paymentChannelClaim.ts

@@ -63,6 +63,8 @@ export interface PaymentChannelClaimFlagsInterface extends GlobalFlags {
 /**
  * Claim XRP from a payment channel, adjust the payment channel's expiration,
  * or both.
+ *
+ * @category Transaction Models
  */
 export interface PaymentChannelClaim extends BaseTransaction {
   TransactionType: 'PaymentChannelClaim'

src/models/transactions/transaction.ts

@@ -37,6 +37,9 @@ import { SignerListSet, validateSignerListSet } from './signerListSet'
 import { TicketCreate, validateTicketCreate } from './ticketCreate'
 import { TrustSet, validateTrustSet } from './trustSet'
 
+/**
+ * @category Transaction Models
+ */
 export type Transaction =
   | AccountDelete
   | AccountSet
@@ -58,6 +61,9 @@ export type Transaction =
   | TicketCreate
   | TrustSet
 
+/**
+ * @category Transaction Models
+ */
 export interface TransactionAndMetadata {
   transaction: Transaction
   metadata: TransactionMetadata
@@ -69,6 +75,7 @@ export interface TransactionAndMetadata {
  *
  * @param transaction - A Transaction.
  * @throws ValidationError When the Transaction is malformed.
+ * @category Utilities
  */
 export function validate(transaction: Record<string, unknown>): void {
   const tx = { ...transaction }

src/utils/balanceChanges.ts

@@ -155,11 +155,12 @@ function getTrustlineQuantity(node: NormalizedNode): BalanceChange[] | null {
 }
 
 /**
- *  Computes the complete list of every balance that changed in the ledger
- *  as a result of the given transaction.
+ * Computes the complete list of every balance that changed in the ledger
+ * as a result of the given transaction.
  *
- *  @param metadata - Transaction metada.
- *  @returns Parsed balance changes.
+ * @param metadata - Transaction metada.
+ * @returns Parsed balance changes.
+ * @category Utilities
  */
 export default function getBalanceChanges(
   metadata: TransactionMetadata,

src/utils/derive.ts

@@ -12,6 +12,7 @@ interface DeriveOptions {
  *
  * @param options - Public key and destination tag to encode as an X-Address.
  * @returns X-Address.
+ * @category Utilities
  */
 function deriveXAddress(options: DeriveOptions): string {
   const classicAddress = deriveAddress(options.publicKey)

src/utils/hashes/index.ts

@@ -47,6 +47,7 @@ function currencyToHex(currency: string): string {
  *
  * @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()
@@ -65,6 +66,7 @@ export function hashTx(txBlobHex: string): string {
  *
  * @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))
@@ -82,6 +84,7 @@ export function hashAccountRoot(address: string): string {
  *
  * @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(
@@ -102,6 +105,7 @@ export function hashSignerListId(address: string): string {
  * @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
@@ -120,6 +124,7 @@ export function hashOfferId(address: string, sequence: number): string {
  * @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,
@@ -147,6 +152,7 @@ export function hashTrustline(
  * @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(
@@ -163,6 +169,7 @@ export function hashEscrow(address: string, sequence: number): string {
  * @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,

src/utils/hashes/ledgerHash.ts

@@ -69,7 +69,8 @@ function addLengthPrefix(hex: string): string {
  *
  * @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.
+ * @throws ValidationError if the Transaction is unsigned.\
+ * @category Utilities
  */
 export function hashSignedTx(tx: Transaction | string): string {
   let txBlob: string
@@ -96,6 +97,7 @@ export function hashSignedTx(tx: Transaction | string): string {
  *
  * @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()
@@ -120,6 +122,7 @@ export function hashLedgerHeader(ledgerHeader: Ledger): string {
  *
  * @param transactions - List of Transactions.
  * @returns The root hash of the SHAMap.
+ * @category Utilities
  */
 export function hashTxTree(
   transactions: Array<Transaction & { metaData?: Metadata }>,
@@ -141,6 +144,7 @@ export function hashTxTree(
  *
  * @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()
@@ -214,6 +218,7 @@ function computeStateHash(
  * @param ledger - Ledger to compute the hash for.
  * @param options - Allow client to recompute Transaction and State Hashes.
  * @returns The has of ledger.
+ * @category Utilities
  */
 function hashLedger(
   ledger: Ledger,

src/utils/index.ts

@@ -14,8 +14,12 @@ import {
   isValidXAddress,
   xAddressToClassicAddress,
 } from 'ripple-address-codec'
+import * as rbc from 'ripple-binary-codec'
 
+import { LedgerEntry } from '../models/ledger'
 import { Response } from '../models/methods'
+import { PaymentChannelClaim } from '../models/transactions/paymentChannelClaim'
+import { Transaction } from '../models/transactions/transaction'
 
 import getBalanceChanges from './balanceChanges'
 import { deriveKeypair, deriveXAddress } from './derive'
@@ -67,12 +71,64 @@ function isValidSecret(secret: string): boolean {
   }
 }
 
+/**
+ * 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)
@@ -83,6 +139,7 @@ function isValidAddress(address: string): boolean {
  *
  * @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()
@@ -98,12 +155,16 @@ function convertStringToHex(string: string): string {
  *
  * @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,
@@ -156,4 +217,9 @@ export {
   decodeAccountPublic,
   encodeXAddress,
   decodeXAddress,
+  encode,
+  decode,
+  encodeForMultiSigning,
+  encodeForSigning,
+  encodeForSigningClaim,
 }

src/utils/quality.ts

@@ -27,6 +27,7 @@ function percentToDecimal(percent: string): string {
  * @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)
@@ -59,6 +60,7 @@ export function decimalToTransferRate(decimal: string): number {
  * @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))
@@ -72,6 +74,7 @@ export function percentToTransferRate(percent: string): number {
  * @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)
@@ -103,6 +106,7 @@ export function decimalToQuality(decimal: string): number {
  * @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)) {
@@ -127,7 +131,8 @@ export function qualityToDecimal(quality: number): string {
  *
  * @param rate - TransferRate to convert to decimal.
  * @returns decimal representation of transfer Rate.
- * @throws ValidationError when it cannot convert from billionths format
+ * @throws ValidationError when it cannot convert from billionths format.
+ * @category Utilities
  */
 export function transferRateToDecimal(rate: number): string {
   if (!Number.isInteger(rate)) {
@@ -157,6 +162,7 @@ export function transferRateToDecimal(rate: number): string {
  * @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))

src/utils/signPaymentChannelClaim.ts

@@ -10,6 +10,7 @@ import { xrpToDrops } from './xrpConversion'
  * @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,

src/utils/timeConversion.ts

@@ -5,6 +5,7 @@ const RIPPLE_EPOCH_DIFF = 0x386d4380
  *
  * @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
@@ -15,6 +16,7 @@ function rippleTimeToUnixTime(rpepoch: number): number {
  *
  * @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
@@ -25,6 +27,7 @@ function unixTimeToRippleTime(timestamp: number): number {
  *
  * @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()
@@ -35,6 +38,7 @@ function rippleTimeToISOTime(rippleTime: number): string {
  *
  * @param iso8601 - International standard date format.
  * @returns Seconds since ripple epoch (1/1/2000 GMT).
+ * @category Utilities
  */
 function ISOTimeToRippleTime(iso8601: string): number {
   return unixTimeToRippleTime(Date.parse(iso8601))

src/utils/verifyPaymentChannelClaim.ts

@@ -11,6 +11,7 @@ import { xrpToDrops } from './xrpConversion'
  * @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(

src/utils/xrpConversion.ts

@@ -13,6 +13,7 @@ const SANITY_CHECK = /^-?[0-9.]+$/u
  * @param dropsToConvert - Drops to convert to XRP.
  * @returns Amount in XRP.
  * @throws When drops amount is invalid.
+ * @category Utilities
  */
 export function dropsToXrp(dropsToConvert: BigNumber.Value): string {
   /*
@@ -58,6 +59,7 @@ export function dropsToXrp(dropsToConvert: BigNumber.Value): string {
  * @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'.

src/wallet/index.ts

@@ -105,7 +105,7 @@ interface FromMnemonicOptions extends WalletBaseOptions {
  * // }
  * ```
  *
- * @category Offline Signing
+ * @category Signing
  */
 class Wallet {
   public readonly publicKey: string

src/wallet/signer.ts

@@ -25,6 +25,7 @@ import Wallet from '.'
  * - There were no transactions given to sign
  * - The SigningPubKey field is not the empty string in any given transaction
  * - Any transaction is missing a Signers field.
+ * @category Signing
  */
 function multisign(transactions: Array<Transaction | string>): string {
   if (transactions.length === 0) {
@@ -70,6 +71,7 @@ function multisign(transactions: Array<Transaction | string>): string {
  * @param channelId - An id for the payment channel to redeem XRP from.
  * @param amount - The amount in drops to redeem.
  * @returns A signature that can be used to redeem a specific amount of XRP from a payment channel.
+ * @category Utilities
  */
 function authorizeChannel(
   wallet: Wallet,
@@ -89,6 +91,7 @@ function authorizeChannel(
  *
  * @param tx - A transaction to verify the signature of. (Can be in object or encoded string format).
  * @returns Returns true if tx has a valid signature, and returns false otherwise.
+ * @category Utilities
  */
 function verifySignature(tx: Transaction | string): boolean {
   const decodedTx: Transaction = getDecodedTransaction(tx)

typedoc.json

@@ -4,13 +4,14 @@
   "categoryOrder": [
     "Constructor",
     "Clients",
+    "Signing",
     "Transaction Models",
     "Transaction Flags",
     "Ledger Flags",
     "Utilities",
     "Requests",
     "Responses",
-    "Flags",
+    "Streams",
     "Errors"
   ],
   "categorizeByGroup": false