xrpl 2.9.1 → 2.11.0

package/src/models/transactions/AMMBid.ts

@@ -0,0 +1,140 @@
+/* eslint-disable complexity -- required for validateAMMBid */
+import { ValidationError } from '../../errors'
+import { Amount, AuthAccount, Currency } from '../common'
+
+import {
+  BaseTransaction,
+  isAmount,
+  isCurrency,
+  validateBaseTransaction,
+} from './common'
+
+const MAX_AUTH_ACCOUNTS = 4
+
+/**
+ * Bid on an Automated Market Maker's (AMM's) auction slot.
+ *
+ * If you win, you can trade against the AMM at a discounted fee until you are outbid or 24 hours have passed.
+ * If you are outbid before 24 hours have passed, you are refunded part of the cost of your bid based on how much time remains.
+ * You bid using the AMM's LP Tokens; the amount of a winning bid is returned to the AMM,
+ * decreasing the outstanding balance of LP Tokens.
+ */
+export interface AMMBid extends BaseTransaction {
+  TransactionType: 'AMMBid'
+
+  /**
+   * The definition for one of the assets in the AMM's pool.
+   */
+  Asset: Currency
+
+  /**
+   * The definition for the other asset in the AMM's pool.
+   */
+  Asset2: Currency
+
+  /**
+   * Pay at least this amount for the slot.
+   * Setting this value higher makes it harder for others to outbid you.
+   * If omitted, pay the minimum necessary to win the bid.
+   */
+  BidMin?: Amount
+
+  /**
+   * Pay at most this amount for the slot.
+   * If the cost to win the bid is higher than this amount, the transaction fails.
+   * If omitted, pay as much as necessary to win the bid.
+   */
+  BidMax?: Amount
+
+  /**
+   * A list of up to 4 additional accounts that you allow to trade at the discounted fee.
+   * This cannot include the address of the transaction sender.
+   */
+  AuthAccounts?: AuthAccount[]
+}
+
+/**
+ * Verify the form and type of an AMMBid at runtime.
+ *
+ * @param tx - An AMMBid Transaction.
+ * @throws When the AMMBid is Malformed.
+ */
+export function validateAMMBid(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.Asset == null) {
+    throw new ValidationError('AMMBid: missing field Asset')
+  }
+
+  if (!isCurrency(tx.Asset)) {
+    throw new ValidationError('AMMBid: Asset must be a Currency')
+  }
+
+  if (tx.Asset2 == null) {
+    throw new ValidationError('AMMBid: missing field Asset2')
+  }
+
+  if (!isCurrency(tx.Asset2)) {
+    throw new ValidationError('AMMBid: Asset2 must be a Currency')
+  }
+
+  if (tx.BidMin != null && !isAmount(tx.BidMin)) {
+    throw new ValidationError('AMMBid: BidMin must be an Amount')
+  }
+
+  if (tx.BidMax != null && !isAmount(tx.BidMax)) {
+    throw new ValidationError('AMMBid: BidMax must be an Amount')
+  }
+
+  if (tx.AuthAccounts != null) {
+    if (!Array.isArray(tx.AuthAccounts)) {
+      throw new ValidationError(
+        `AMMBid: AuthAccounts must be an AuthAccount array`,
+      )
+    }
+    if (tx.AuthAccounts.length > MAX_AUTH_ACCOUNTS) {
+      throw new ValidationError(
+        `AMMBid: AuthAccounts length must not be greater than ${MAX_AUTH_ACCOUNTS}`,
+      )
+    }
+    validateAuthAccounts(
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Only used by JS
+      tx.Account as string,
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Only used by JS
+      tx.AuthAccounts as Array<Record<string, unknown>>,
+    )
+  }
+}
+
+function validateAuthAccounts(
+  senderAddress: string,
+  authAccounts: Array<Record<string, unknown>>,
+): boolean {
+  for (const authAccount of authAccounts) {
+    if (
+      authAccount.AuthAccount == null ||
+      typeof authAccount.AuthAccount !== 'object'
+    ) {
+      throw new ValidationError(`AMMBid: invalid AuthAccounts`)
+    }
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment -- used for null check
+    // @ts-expect-error -- used for null check
+    if (authAccount.AuthAccount.Account == null) {
+      throw new ValidationError(`AMMBid: invalid AuthAccounts`)
+    }
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment -- used for null check
+    // @ts-expect-error -- used for null check
+    if (typeof authAccount.AuthAccount.Account !== 'string') {
+      throw new ValidationError(`AMMBid: invalid AuthAccounts`)
+    }
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment -- used for null check
+    // @ts-expect-error -- used for null check
+    if (authAccount.AuthAccount.Account === senderAddress) {
+      throw new ValidationError(
+        `AMMBid: AuthAccounts must not include sender's address`,
+      )
+    }
+  }
+
+  return true
+}

package/src/models/transactions/AMMCreate.ts

@@ -0,0 +1,80 @@
+import { ValidationError } from '../../errors'
+import { Amount } from '../common'
+
+import { BaseTransaction, isAmount, validateBaseTransaction } from './common'
+
+export const AMM_MAX_TRADING_FEE = 1000
+
+/**
+ * Create a new Automated Market Maker (AMM) instance for trading a pair of assets (fungible tokens or XRP).
+ *
+ * Creates both an AMM object and a special AccountRoot object to represent the AMM.
+ * Also transfers ownership of the starting balance of both assets from the sender to the created AccountRoot
+ * and issues an initial balance of liquidity provider tokens (LP Tokens) from the AMM account to the sender.
+ *
+ * CAUTION: When you create the AMM, you should fund it with (approximately) equal-value amounts of each asset.
+ * Otherwise, other users can profit at your expense by trading with this AMM (performing arbitrage).
+ * The currency risk that liquidity providers take on increases with the volatility (potential for imbalance) of the asset pair.
+ * The higher the trading fee, the more it offsets this risk,
+ * so it's best to set the trading fee based on the volatility of the asset pair.
+ */
+export interface AMMCreate extends BaseTransaction {
+  TransactionType: 'AMMCreate'
+
+  /**
+   * The first of the two assets to fund this AMM with. This must be a positive amount.
+   */
+  Amount: Amount
+
+  /**
+   * The second of the two assets to fund this AMM with. This must be a positive amount.
+   */
+  Amount2: Amount
+
+  /**
+   * The fee to charge for trades against this AMM instance, in units of 1/100,000; a value of 1 is equivalent to 0.001%.
+   * The maximum value is 1000, indicating a 1% fee.
+   * The minimum value is 0.
+   */
+  TradingFee: number
+}
+
+/**
+ * Verify the form and type of an AMMCreate at runtime.
+ *
+ * @param tx - An AMMCreate Transaction.
+ * @throws When the AMMCreate is Malformed.
+ */
+export function validateAMMCreate(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.Amount == null) {
+    throw new ValidationError('AMMCreate: missing field Amount')
+  }
+
+  if (!isAmount(tx.Amount)) {
+    throw new ValidationError('AMMCreate: Amount must be an Amount')
+  }
+
+  if (tx.Amount2 == null) {
+    throw new ValidationError('AMMCreate: missing field Amount2')
+  }
+
+  if (!isAmount(tx.Amount2)) {
+    throw new ValidationError('AMMCreate: Amount2 must be an Amount')
+  }
+
+  if (tx.TradingFee == null) {
+    throw new ValidationError('AMMCreate: missing field TradingFee')
+  }
+
+  if (typeof tx.TradingFee !== 'number') {
+    throw new ValidationError('AMMCreate: TradingFee must be a number')
+  }
+
+  if (tx.TradingFee < 0 || tx.TradingFee > AMM_MAX_TRADING_FEE) {
+    throw new ValidationError(
+      `AMMCreate: TradingFee must be between 0 and ${AMM_MAX_TRADING_FEE}`,
+    )
+  }
+}

package/src/models/transactions/AMMDelete.ts

@@ -0,0 +1,55 @@
+import { ValidationError } from '../../errors'
+import { Currency } from '../common'
+
+import { BaseTransaction, isCurrency, validateBaseTransaction } from './common'
+
+/**
+ * Delete an empty Automated Market Maker (AMM) instance that could not be fully deleted automatically.
+ *
+ * Tip: The AMMWithdraw transaction automatically tries to delete an AMM, along with associated ledger
+ * entries such as empty trust lines, if it withdrew all the assets from the AMM's pool.
+ * However, if there are too many trust lines to the AMM account to remove in one transaction,
+ * it may stop before fully removing the AMM. Similarly, an AMMDelete transaction removes up to
+ * a maximum number of trust lines; in extreme cases, it may take several AMMDelete transactions
+ * to fully delete the trust lines and the associated AMM.
+ * In all cases, the AMM ledger entry and AMM account are deleted by the last such transaction.
+ */
+export interface AMMDelete extends BaseTransaction {
+  TransactionType: 'AMMDelete'
+
+  /**
+   * The definition for one of the assets in the AMM's pool.
+   */
+  Asset: Currency
+
+  /**
+   * The definition for the other asset in the AMM's pool.
+   */
+  Asset2: Currency
+}
+
+/**
+ * Verify the form and type of an AMMDelete at runtime.
+ *
+ * @param tx - An AMMDelete Transaction.
+ * @throws When the AMMDelete is Malformed.
+ */
+export function validateAMMDelete(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.Asset == null) {
+    throw new ValidationError('AMMDelete: missing field Asset')
+  }
+
+  if (!isCurrency(tx.Asset)) {
+    throw new ValidationError('AMMDelete: Asset must be a Currency')
+  }
+
+  if (tx.Asset2 == null) {
+    throw new ValidationError('AMMDelete: missing field Asset2')
+  }
+
+  if (!isCurrency(tx.Asset2)) {
+    throw new ValidationError('AMMDelete: Asset2 must be a Currency')
+  }
+}

package/src/models/transactions/AMMDeposit.ts

@@ -0,0 +1,130 @@
+/* eslint-disable complexity -- required for validateAMMDeposit */
+import { ValidationError } from '../../errors'
+import { Amount, Currency, IssuedCurrencyAmount } from '../common'
+
+import {
+  BaseTransaction,
+  GlobalFlags,
+  isAmount,
+  isCurrency,
+  isIssuedCurrency,
+  validateBaseTransaction,
+} from './common'
+
+/**
+ * Enum representing values for AMMDeposit Transaction Flags.
+ *
+ * @category Transaction Flags
+ */
+export enum AMMDepositFlags {
+  tfLPToken = 0x00010000,
+  tfSingleAsset = 0x00080000,
+  tfTwoAsset = 0x00100000,
+  tfOneAssetLPToken = 0x00200000,
+  tfLimitLPToken = 0x00400000,
+}
+
+export interface AMMDepositFlagsInterface extends GlobalFlags {
+  tfLPToken?: boolean
+  tfSingleAsset?: boolean
+  tfTwoAsset?: boolean
+  tfOneAssetLPToken?: boolean
+  tfLimitLPToken?: boolean
+}
+
+/**
+ * Deposit funds into an Automated Market Maker (AMM) instance
+ * and receive the AMM's liquidity provider tokens (LP Tokens) in exchange.
+ *
+ * You can deposit one or both of the assets in the AMM's pool.
+ * If successful, this transaction creates a trust line to the AMM Account (limit 0) to hold the LP Tokens.
+ */
+export interface AMMDeposit extends BaseTransaction {
+  TransactionType: 'AMMDeposit'
+
+  /**
+   * The definition for one of the assets in the AMM's pool.
+   */
+  Asset: Currency
+
+  /**
+   * The definition for the other asset in the AMM's pool.
+   */
+  Asset2: Currency
+
+  /**
+   * The amount of one asset to deposit to the AMM.
+   * If present, this must match the type of one of the assets (tokens or XRP) in the AMM's pool.
+   */
+  Amount?: Amount
+
+  /**
+   * The amount of another asset to add to the AMM.
+   * If present, this must match the type of the other asset in the AMM's pool and cannot be the same asset as Amount.
+   */
+  Amount2?: Amount
+
+  /**
+   * The maximum effective price, in the deposit asset, to pay for each LP Token received.
+   */
+  EPrice?: Amount
+
+  /**
+   * How many of the AMM's LP Tokens to buy.
+   */
+  LPTokenOut?: IssuedCurrencyAmount
+}
+
+/**
+ * Verify the form and type of an AMMDeposit at runtime.
+ *
+ * @param tx - An AMMDeposit Transaction.
+ * @throws When the AMMDeposit is Malformed.
+ */
+export function validateAMMDeposit(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.Asset == null) {
+    throw new ValidationError('AMMDeposit: missing field Asset')
+  }
+
+  if (!isCurrency(tx.Asset)) {
+    throw new ValidationError('AMMDeposit: Asset must be a Currency')
+  }
+
+  if (tx.Asset2 == null) {
+    throw new ValidationError('AMMDeposit: missing field Asset2')
+  }
+
+  if (!isCurrency(tx.Asset2)) {
+    throw new ValidationError('AMMDeposit: Asset2 must be a Currency')
+  }
+
+  if (tx.Amount2 != null && tx.Amount == null) {
+    throw new ValidationError('AMMDeposit: must set Amount with Amount2')
+  } else if (tx.EPrice != null && tx.Amount == null) {
+    throw new ValidationError('AMMDeposit: must set Amount with EPrice')
+  } else if (tx.LPTokenOut == null && tx.Amount == null) {
+    throw new ValidationError(
+      'AMMDeposit: must set at least LPTokenOut or Amount',
+    )
+  }
+
+  if (tx.LPTokenOut != null && !isIssuedCurrency(tx.LPTokenOut)) {
+    throw new ValidationError(
+      'AMMDeposit: LPTokenOut must be an IssuedCurrencyAmount',
+    )
+  }
+
+  if (tx.Amount != null && !isAmount(tx.Amount)) {
+    throw new ValidationError('AMMDeposit: Amount must be an Amount')
+  }
+
+  if (tx.Amount2 != null && !isAmount(tx.Amount2)) {
+    throw new ValidationError('AMMDeposit: Amount2 must be an Amount')
+  }
+
+  if (tx.EPrice != null && !isAmount(tx.EPrice)) {
+    throw new ValidationError('AMMDeposit: EPrice must be an Amount')
+  }
+}

package/src/models/transactions/AMMVote.ts

@@ -0,0 +1,71 @@
+import { ValidationError } from '../../errors'
+import { Currency } from '../common'
+
+import { AMM_MAX_TRADING_FEE } from './AMMCreate'
+import { BaseTransaction, isCurrency, validateBaseTransaction } from './common'
+
+/**
+ * Vote on the trading fee for an Automated Market Maker (AMM) instance.
+ *
+ * Up to 8 accounts can vote in proportion to the amount of the AMM's LP Tokens they hold.
+ * Each new vote re-calculates the AMM's trading fee based on a weighted average of the votes.
+ */
+export interface AMMVote extends BaseTransaction {
+  TransactionType: 'AMMVote'
+
+  /**
+   * The definition for one of the assets in the AMM's pool.
+   */
+  Asset: Currency
+
+  /**
+   * The definition for the other asset in the AMM's pool.
+   */
+  Asset2: Currency
+
+  /**
+   * The proposed fee to vote for, in units of 1/100,000; a value of 1 is equivalent to 0.001%.
+   * The maximum value is 1000, indicating a 1% fee.
+   */
+  TradingFee: number
+}
+
+/**
+ * Verify the form and type of an AMMVote at runtime.
+ *
+ * @param tx - An AMMVote Transaction.
+ * @throws When the AMMVote is Malformed.
+ */
+export function validateAMMVote(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.Asset == null) {
+    throw new ValidationError('AMMVote: missing field Asset')
+  }
+
+  if (!isCurrency(tx.Asset)) {
+    throw new ValidationError('AMMVote: Asset must be a Currency')
+  }
+
+  if (tx.Asset2 == null) {
+    throw new ValidationError('AMMVote: missing field Asset2')
+  }
+
+  if (!isCurrency(tx.Asset2)) {
+    throw new ValidationError('AMMVote: Asset2 must be a Currency')
+  }
+
+  if (tx.TradingFee == null) {
+    throw new ValidationError('AMMVote: missing field TradingFee')
+  }
+
+  if (typeof tx.TradingFee !== 'number') {
+    throw new ValidationError('AMMVote: TradingFee must be a number')
+  }
+
+  if (tx.TradingFee < 0 || tx.TradingFee > AMM_MAX_TRADING_FEE) {
+    throw new ValidationError(
+      `AMMVote: TradingFee must be between 0 and ${AMM_MAX_TRADING_FEE}`,
+    )
+  }
+}

package/src/models/transactions/AMMWithdraw.ts

@@ -0,0 +1,126 @@
+/* eslint-disable complexity -- required for validateAMMWithdraw */
+import { ValidationError } from '../../errors'
+import { Amount, Currency, IssuedCurrencyAmount } from '../common'
+
+import {
+  BaseTransaction,
+  GlobalFlags,
+  isAmount,
+  isCurrency,
+  isIssuedCurrency,
+  validateBaseTransaction,
+} from './common'
+
+/**
+ * Enum representing values for AMMWithdrawFlags Transaction Flags.
+ *
+ * @category Transaction Flags
+ */
+export enum AMMWithdrawFlags {
+  tfLPToken = 0x00010000,
+  tfWithdrawAll = 0x00020000,
+  tfOneAssetWithdrawAll = 0x00040000,
+  tfSingleAsset = 0x00080000,
+  tfTwoAsset = 0x00100000,
+  tfOneAssetLPToken = 0x00200000,
+  tfLimitLPToken = 0x00400000,
+}
+
+export interface AMMWithdrawFlagsInterface extends GlobalFlags {
+  tfLPToken?: boolean
+  tfWithdrawAll?: boolean
+  tfOneAssetWithdrawAll?: boolean
+  tfSingleAsset?: boolean
+  tfTwoAsset?: boolean
+  tfOneAssetLPToken?: boolean
+  tfLimitLPToken?: boolean
+}
+
+/**
+ * Withdraw assets from an Automated Market Maker (AMM) instance by returning the AMM's liquidity provider tokens (LP Tokens).
+ */
+export interface AMMWithdraw extends BaseTransaction {
+  TransactionType: 'AMMWithdraw'
+
+  /**
+   * The definition for one of the assets in the AMM's pool.
+   */
+  Asset: Currency
+
+  /**
+   * The definition for the other asset in the AMM's pool.
+   */
+  Asset2: Currency
+
+  /**
+   * The amount of one asset to withdraw from the AMM.
+   * This must match the type of one of the assets (tokens or XRP) in the AMM's pool.
+   */
+  Amount?: Amount
+
+  /**
+   * The amount of another asset to withdraw from the AMM.
+   * If present, this must match the type of the other asset in the AMM's pool and cannot be the same type as Amount.
+   */
+  Amount2?: Amount
+
+  /**
+   * The minimum effective price, in LP Token returned, to pay per unit of the asset to withdraw.
+   */
+  EPrice?: Amount
+
+  /**
+   * How many of the AMM's LP Tokens to redeem.
+   */
+  LPTokenIn?: IssuedCurrencyAmount
+}
+
+/**
+ * Verify the form and type of an AMMWithdraw at runtime.
+ *
+ * @param tx - An AMMWithdraw Transaction.
+ * @throws When the AMMWithdraw is Malformed.
+ */
+export function validateAMMWithdraw(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.Asset == null) {
+    throw new ValidationError('AMMWithdraw: missing field Asset')
+  }
+
+  if (!isCurrency(tx.Asset)) {
+    throw new ValidationError('AMMWithdraw: Asset must be a Currency')
+  }
+
+  if (tx.Asset2 == null) {
+    throw new ValidationError('AMMWithdraw: missing field Asset2')
+  }
+
+  if (!isCurrency(tx.Asset2)) {
+    throw new ValidationError('AMMWithdraw: Asset2 must be a Currency')
+  }
+
+  if (tx.Amount2 != null && tx.Amount == null) {
+    throw new ValidationError('AMMWithdraw: must set Amount with Amount2')
+  } else if (tx.EPrice != null && tx.Amount == null) {
+    throw new ValidationError('AMMWithdraw: must set Amount with EPrice')
+  }
+
+  if (tx.LPTokenIn != null && !isIssuedCurrency(tx.LPTokenIn)) {
+    throw new ValidationError(
+      'AMMWithdraw: LPTokenIn must be an IssuedCurrencyAmount',
+    )
+  }
+
+  if (tx.Amount != null && !isAmount(tx.Amount)) {
+    throw new ValidationError('AMMWithdraw: Amount must be an Amount')
+  }
+
+  if (tx.Amount2 != null && !isAmount(tx.Amount2)) {
+    throw new ValidationError('AMMWithdraw: Amount2 must be an Amount')
+  }
+
+  if (tx.EPrice != null && !isAmount(tx.EPrice)) {
+    throw new ValidationError('AMMWithdraw: EPrice must be an Amount')
+  }
+}