xrpl 2.10.0 → 2.12.0-beta.0

package/src/models/transactions/paymentChannelClaim.ts

@@ -0,0 +1,165 @@
+/* eslint-disable complexity -- Necessary for validatePaymentChannelClaim */
+import { ValidationError } from '../../errors'
+
+import { BaseTransaction, GlobalFlags, validateBaseTransaction } from './common'
+
+/**
+ * Enum representing values for PaymentChannelClaim transaction flags.
+ *
+ * @category Transaction Flags
+ */
+export enum PaymentChannelClaimFlags {
+  /**
+   * Clear the channel's Expiration time. (Expiration is different from the
+   * channel's immutable CancelAfter time.) Only the source address of the
+   * payment channel can use this flag.
+   */
+  tfRenew = 0x00010000,
+  /**
+   * Request to close the channel. Only the channel source and destination
+   * addresses can use this flag. This flag closes the channel immediately if it
+   * has no more XRP allocated to it after processing the current claim, or if
+   * the destination address uses it. If the source address uses this flag when
+   * the channel still holds XRP, this schedules the channel to close after
+   * SettleDelay seconds have passed. (Specifically, this sets the Expiration of
+   * the channel to the close time of the previous ledger plus the channel's
+   * SettleDelay time, unless the channel already has an earlier Expiration
+   * time.) If the destination address uses this flag when the channel still
+   * holds XRP, any XRP that remains after processing the claim is returned to
+   * the source address.
+   */
+  tfClose = 0x00020000,
+}
+
+/**
+ * Map of flags to boolean values representing {@link PaymentChannelClaim}
+ * transaction flags.
+ *
+ * @category Transaction Flags
+ *
+ * @example
+ * ```typescript
+ * const paymentChannelClaim: PaymentChannelClaim = {
+ *  Account: 'rMpxZpuy5RBSP47oK2hDWUtk3B5BNQHfGj,
+ *  TransactionType: 'PaymentChannelClaim',
+ *  Channel: hashes.hashPaymentChannel(
+ *    'rMpxZpuy5RBSP47oK2hDWUtk3B5BNQHfGj',
+ *    'rQGYqiyH5Ue9J96p4E6Qt6AvqxK4sDhnS5',
+ *    21970712,
+ *  ),
+ *  Amount: '100',
+ *  Flags: {
+ *    tfClose: true
+ *  }
+ *}
+ *
+ * // Autofill the tx to see how flags actually look compared to the interface usage.
+ * const autofilledTx = await client.autofill(paymentChannelClaim)
+ * console.log(autofilledTx)
+ * // {
+ * //  Account: 'rMpxZpuy5RBSP47oK2hDWUtk3B5BNQHfGj',
+ * //  TransactionType: 'PaymentChannelClaim',
+ * //  Channel: 'FC14BF9245D731DC1749EE0F070765E4EB4E993F8ECEE3D00F7E6E26D6EF98CF',
+ * //  Amount: '100',
+ * //  Flags: 131072,
+ * //  Sequence: 21970713,
+ * //  Fee: '12',
+ * //  LastLedgerSequence: 21970658
+ * // }
+ * ```
+ */
+export interface PaymentChannelClaimFlagsInterface extends GlobalFlags {
+  /**
+   * Clear the channel's Expiration time. (Expiration is different from the
+   * channel's immutable CancelAfter time.) Only the source address of the
+   * payment channel can use this flag.
+   */
+  tfRenew?: boolean
+  /**
+   * Request to close the channel. Only the channel source and destination
+   * addresses can use this flag. This flag closes the channel immediately if it
+   * has no more XRP allocated to it after processing the current claim, or if
+   * the destination address uses it. If the source address uses this flag when
+   * the channel still holds XRP, this schedules the channel to close after
+   * SettleDelay seconds have passed. (Specifically, this sets the Expiration of
+   * the channel to the close time of the previous ledger plus the channel's
+   * SettleDelay time, unless the channel already has an earlier Expiration
+   * time.) If the destination address uses this flag when the channel still
+   * holds XRP, any XRP that remains after processing the claim is returned to
+   * the source address.
+   */
+  tfClose?: boolean
+}
+
+/**
+ * Claim XRP from a payment channel, adjust the payment channel's expiration,
+ * or both.
+ *
+ * @category Transaction Models
+ */
+export interface PaymentChannelClaim extends BaseTransaction {
+  TransactionType: 'PaymentChannelClaim'
+  Flags?: number | PaymentChannelClaimFlagsInterface
+  /** The unique ID of the channel as a 64-character hexadecimal string. */
+  Channel: string
+  /**
+   * Total amount of XRP, in drops, delivered by this channel after processing
+   * this claim. Required to deliver XRP. Must be more than the total amount
+   * delivered by the channel so far, but not greater than the Amount of the
+   * signed claim. Must be provided except when closing the channel.
+   */
+  Balance?: string
+  /**
+   * The amount of XRP, in drops, authorized by the Signature. This must match
+   * the amount in the signed message. This is the cumulative amount of XRP that
+   * can be dispensed by the channel, including XRP previously redeemed.
+   */
+  Amount?: string
+  /**
+   * The signature of this claim, as hexadecimal. The signed message contains
+   * the channel ID and the amount of the claim. Required unless the sender of
+   * the transaction is the source address of the channel.
+   */
+  Signature?: string
+  /**
+   * The public key used for the signature, as hexadecimal. This must match the
+   * PublicKey stored in the ledger for the channel. Required unless the sender
+   * of the transaction is the source address of the channel and the Signature
+   * field is omitted.
+   */
+  PublicKey?: string
+}
+
+/**
+ * Verify the form and type of an PaymentChannelClaim at runtime.
+ *
+ * @param tx - An PaymentChannelClaim Transaction.
+ * @throws When the PaymentChannelClaim is Malformed.
+ */
+export function validatePaymentChannelClaim(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.Channel === undefined) {
+    throw new ValidationError('PaymentChannelClaim: missing Channel')
+  }
+
+  if (typeof tx.Channel !== 'string') {
+    throw new ValidationError('PaymentChannelClaim: Channel must be a string')
+  }
+
+  if (tx.Balance !== undefined && typeof tx.Balance !== 'string') {
+    throw new ValidationError('PaymentChannelClaim: Balance must be a string')
+  }
+
+  if (tx.Amount !== undefined && typeof tx.Amount !== 'string') {
+    throw new ValidationError('PaymentChannelClaim: Amount must be a string')
+  }
+
+  if (tx.Signature !== undefined && typeof tx.Signature !== 'string') {
+    throw new ValidationError('PaymentChannelClaim: Signature must be a string')
+  }
+
+  if (tx.PublicKey !== undefined && typeof tx.PublicKey !== 'string') {
+    throw new ValidationError('PaymentChannelClaim: PublicKey must be a string')
+  }
+}

package/src/models/transactions/paymentChannelCreate.ts

@@ -0,0 +1,116 @@
+/* eslint-disable complexity -- Necessary for validatePaymentChannelCreate */
+import { ValidationError } from '../../errors'
+
+import { BaseTransaction, validateBaseTransaction } from './common'
+
+/**
+ * Create a unidirectional channel and fund it with XRP. The address sending
+ * this transaction becomes the "source address" of the payment channel.
+ *
+ * @category Transaction Models
+ */
+export interface PaymentChannelCreate extends BaseTransaction {
+  TransactionType: 'PaymentChannelCreate'
+  /**
+   * Amount of XRP, in drops, to deduct from the sender's balance and set aside
+   * in this channel. While the channel is open, the XRP can only go to the
+   * Destination address. When the channel closes, any unclaimed XRP is returned
+   * to the source address's balance.
+   */
+  Amount: string
+  /**
+   * Address to receive XRP claims against this channel. This is also known as
+   * the "destination address" for the channel.
+   */
+  Destination: string
+  /**
+   * Amount of time the source address must wait before closing the channel if
+   * it has unclaimed XRP.
+   */
+  SettleDelay: number
+  /**
+   * The public key of the key pair the source will use to sign claims against
+   * this channel in hexadecimal. This can be any secp256k1 or ed25519 public
+   * key.
+   */
+  PublicKey: string
+  /**
+   * The time, in seconds since the Ripple Epoch, when this channel expires.
+   * Any transaction that would modify the channel after this time closes the
+   * channel without otherwise affecting it. This value is immutable; the
+   * channel can be closed earlier than this time but cannot remain open after
+   * this time.
+   */
+  CancelAfter?: number
+  /**
+   * Arbitrary tag to further specify the destination for this payment channel,
+   * such as a hosted recipient at the destination address.
+   */
+  DestinationTag?: number
+}
+
+/**
+ * Verify the form and type of an PaymentChannelCreate at runtime.
+ *
+ * @param tx - An PaymentChannelCreate Transaction.
+ * @throws When the PaymentChannelCreate is Malformed.
+ */
+// eslint-disable-next-line max-lines-per-function -- okay for this function, there's a lot of things to check
+export function validatePaymentChannelCreate(
+  tx: Record<string, unknown>,
+): void {
+  validateBaseTransaction(tx)
+
+  if (tx.Amount === undefined) {
+    throw new ValidationError('PaymentChannelCreate: missing Amount')
+  }
+
+  if (typeof tx.Amount !== 'string') {
+    throw new ValidationError('PaymentChannelCreate: Amount must be a string')
+  }
+
+  if (tx.Destination === undefined) {
+    throw new ValidationError('PaymentChannelCreate: missing Destination')
+  }
+
+  if (typeof tx.Destination !== 'string') {
+    throw new ValidationError(
+      'PaymentChannelCreate: Destination must be a string',
+    )
+  }
+
+  if (tx.SettleDelay === undefined) {
+    throw new ValidationError('PaymentChannelCreate: missing SettleDelay')
+  }
+
+  if (typeof tx.SettleDelay !== 'number') {
+    throw new ValidationError(
+      'PaymentChannelCreate: SettleDelay must be a number',
+    )
+  }
+
+  if (tx.PublicKey === undefined) {
+    throw new ValidationError('PaymentChannelCreate: missing PublicKey')
+  }
+
+  if (typeof tx.PublicKey !== 'string') {
+    throw new ValidationError(
+      'PaymentChannelCreate: PublicKey must be a string',
+    )
+  }
+
+  if (tx.CancelAfter !== undefined && typeof tx.CancelAfter !== 'number') {
+    throw new ValidationError(
+      'PaymentChannelCreate: CancelAfter must be a number',
+    )
+  }
+
+  if (
+    tx.DestinationTag !== undefined &&
+    typeof tx.DestinationTag !== 'number'
+  ) {
+    throw new ValidationError(
+      'PaymentChannelCreate: DestinationTag must be a number',
+    )
+  }
+}

package/src/models/transactions/paymentChannelFund.ts

@@ -0,0 +1,65 @@
+import { ValidationError } from '../../errors'
+
+import { BaseTransaction, validateBaseTransaction } from './common'
+
+/**
+ * Add additional XRP to an open payment channel, and optionally update the
+ * expiration time of the channel. Only the source address of the channel can
+ * use this transaction.
+ *
+ * @category Transaction Models
+ */
+export interface PaymentChannelFund extends BaseTransaction {
+  TransactionType: 'PaymentChannelFund'
+  /**
+   * The unique ID of the channel to fund as a 64-character hexadecimal
+   * string.
+   */
+  Channel: string
+  /**
+   * Amount of XRP in drops to add to the channel. Must be a positive amount
+   * of XRP.
+   */
+  Amount: string
+  /**
+   * New Expiration time to set for the channel in seconds since the Ripple
+   * Epoch. This must be later than either the current time plus the SettleDelay
+   * of the channel, or the existing Expiration of the channel. After the
+   * Expiration time, any transaction that would access the channel closes the
+   * channel without taking its normal action. Any unspent XRP is returned to
+   * the source address when the channel closes. (Expiration is separate from
+   * the channel's immutable CancelAfter time.) For more information, see the
+   * PayChannel ledger object type.
+   */
+  Expiration?: number
+}
+
+/**
+ * Verify the form and type of an PaymentChannelFund at runtime.
+ *
+ * @param tx - An PaymentChannelFund Transaction.
+ * @throws When the PaymentChannelFund is Malformed.
+ */
+export function validatePaymentChannelFund(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.Channel === undefined) {
+    throw new ValidationError('PaymentChannelFund: missing Channel')
+  }
+
+  if (typeof tx.Channel !== 'string') {
+    throw new ValidationError('PaymentChannelFund: Channel must be a string')
+  }
+
+  if (tx.Amount === undefined) {
+    throw new ValidationError('PaymentChannelFund: missing Amount')
+  }
+
+  if (typeof tx.Amount !== 'string') {
+    throw new ValidationError('PaymentChannelFund: Amount must be a string')
+  }
+
+  if (tx.Expiration !== undefined && typeof tx.Expiration !== 'number') {
+    throw new ValidationError('PaymentChannelFund: Expiration must be a number')
+  }
+}

package/src/models/transactions/setFee.ts

@@ -0,0 +1,48 @@
+import { BaseTransaction } from './common'
+
+export interface SetFeePreAmendment extends BaseTransaction {
+  /**
+   * The charge, in drops of XRP, for the reference transaction, as hex. (This is the transaction cost before scaling for load.)
+   */
+  BaseFee: string
+  /**
+   * The cost, in fee units, of the [reference transaction](https://xrpl.org/transaction-cost.html#reference-transaction-cost)
+   */
+  ReferenceFeeUnits: number
+  /**
+   * The base reserve, in drops
+   */
+  ReserveBase: number
+  /**
+   * The incremental reserve, in drops
+   */
+  ReserveIncrement: number
+}
+
+export interface SetFeePostAmendment extends BaseTransaction {
+  /**
+   * The charge, in drops of XRP, for the reference transaction. (This is the transaction cost before scaling for load.)
+   */
+  BaseFeeDrops: string
+  /**
+   * The base reserve, in drops
+   */
+  ReserveBaseDrops: string
+  /**
+   * The incremental reserve, in drops
+   */
+  ReserveIncrementDrops: string
+}
+
+/**
+ * Marks a change in transaction cost or reserve requirements as a result of Fee Voting.
+ *
+ * The output will be based on the status of the `XRPFees` amendment at the time of this transaction.
+ * - Before: {@link SetFeePostAmendment}
+ * - After: {@link SetFeePostAmendment}
+ *
+ * @category Pseudo Transaction Models
+ */
+export type SetFee = {
+  TransactionType: 'SetFee'
+} & (SetFeePreAmendment | SetFeePostAmendment)

package/src/models/transactions/setRegularKey.ts

@@ -0,0 +1,33 @@
+import { ValidationError } from '../../errors'
+
+import { BaseTransaction, validateBaseTransaction } from './common'
+
+/**
+ * A SetRegularKey transaction assigns, changes, or removes the regular key
+ * pair associated with an account.
+ *
+ * @category Transaction Models
+ */
+export interface SetRegularKey extends BaseTransaction {
+  TransactionType: 'SetRegularKey'
+  /**
+   * A base-58-encoded Address that indicates the regular key pair to be
+   * assigned to the account. If omitted, removes any existing regular key pair.
+   * from the account. Must not match the master key pair for the address.
+   */
+  RegularKey?: string
+}
+
+/**
+ * Verify the form and type of a SetRegularKey at runtime.
+ *
+ * @param tx - A SetRegularKey Transaction.
+ * @throws When the SetRegularKey is malformed.
+ */
+export function validateSetRegularKey(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.RegularKey !== undefined && typeof tx.RegularKey !== 'string') {
+    throw new ValidationError('SetRegularKey: RegularKey must be a string')
+  }
+}

package/src/models/transactions/signerListSet.ts

@@ -0,0 +1,89 @@
+import { ValidationError } from '../../errors'
+import { SignerEntry } from '../common'
+
+import { BaseTransaction, validateBaseTransaction } from './common'
+
+/**
+ * The SignerListSet transaction creates, replaces, or removes a list of
+ * signers that can be used to multi-sign a transaction.
+ *
+ * @category Transaction Models
+ */
+export interface SignerListSet extends BaseTransaction {
+  TransactionType: 'SignerListSet'
+  /**
+   * A target number for the signer weights. A multi-signature from this list
+   * is valid only if the sum weights of the signatures provided is greater than
+   * or equal to this value. To delete a signer list, use the value 0.
+   */
+  SignerQuorum: number
+  /**
+   * Array of SignerEntry objects, indicating the addresses and weights of
+   * signers in this list. This signer list must have at least 1 member and no
+   * more than 32 members. No address may appear more than once in the list, nor
+   * may the Account submitting the transaction appear in the list.
+   */
+  SignerEntries?: SignerEntry[]
+}
+
+const MAX_SIGNERS = 32
+
+const HEX_WALLET_LOCATOR_REGEX = /^[0-9A-Fa-f]{64}$/u
+
+/**
+ * Verify the form and type of an SignerListSet at runtime.
+ *
+ * @param tx - An SignerListSet Transaction.
+ * @throws When the SignerListSet is Malformed.
+ */
+// eslint-disable-next-line complexity -- validation can be complex
+export function validateSignerListSet(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.SignerQuorum === undefined) {
+    throw new ValidationError('SignerListSet: missing field SignerQuorum')
+  }
+
+  if (typeof tx.SignerQuorum !== 'number') {
+    throw new ValidationError('SignerListSet: invalid SignerQuorum')
+  }
+
+  // All other checks are for if SignerQuorum is greater than 0
+  if (tx.SignerQuorum === 0) {
+    return
+  }
+
+  if (tx.SignerEntries === undefined) {
+    throw new ValidationError('SignerListSet: missing field SignerEntries')
+  }
+
+  if (!Array.isArray(tx.SignerEntries)) {
+    throw new ValidationError('SignerListSet: invalid SignerEntries')
+  }
+
+  if (tx.SignerEntries.length === 0) {
+    throw new ValidationError(
+      'SignerListSet: need at least 1 member in SignerEntries',
+    )
+  }
+
+  if (tx.SignerEntries.length > MAX_SIGNERS) {
+    throw new ValidationError(
+      `SignerListSet: maximum of ${MAX_SIGNERS} members allowed in SignerEntries`,
+    )
+  }
+
+  for (const entry of tx.SignerEntries) {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Should be a SignerEntry
+    const signerEntry = entry as SignerEntry
+    const { WalletLocator } = signerEntry.SignerEntry
+    if (
+      WalletLocator !== undefined &&
+      !HEX_WALLET_LOCATOR_REGEX.test(WalletLocator)
+    ) {
+      throw new ValidationError(
+        `SignerListSet: WalletLocator in SignerEntry must be a 256-bit (32-byte) hexadecimal value`,
+      )
+    }
+  }
+}

package/src/models/transactions/ticketCreate.ts

@@ -0,0 +1,50 @@
+import { ValidationError } from '../../errors'
+
+import { BaseTransaction, validateBaseTransaction } from './common'
+
+/**
+ * A TicketCreate transaction sets aside one or more sequence numbers as
+ * Tickets.
+ *
+ * @category Transaction Models
+ */
+export interface TicketCreate extends BaseTransaction {
+  TransactionType: 'TicketCreate'
+  /**
+   * How many Tickets to create. This must be a positive number and cannot
+   * cause the account to own more than 250 Tickets after executing this
+   * transaction.
+   */
+  TicketCount: number
+}
+
+const MAX_TICKETS = 250
+
+/**
+ * Verify the form and type of a TicketCreate at runtime.
+ *
+ * @param tx - A TicketCreate Transaction.
+ * @throws When the TicketCreate is malformed.
+ */
+export function validateTicketCreate(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+  const { TicketCount } = tx
+
+  if (TicketCount === undefined) {
+    throw new ValidationError('TicketCreate: missing field TicketCount')
+  }
+
+  if (typeof TicketCount !== 'number') {
+    throw new ValidationError('TicketCreate: TicketCount must be a number')
+  }
+
+  if (
+    !Number.isInteger(TicketCount) ||
+    TicketCount < 1 ||
+    TicketCount > MAX_TICKETS
+  ) {
+    throw new ValidationError(
+      'TicketCreate: TicketCount must be an integer from 1 to 250',
+    )
+  }
+}