feat: add AMM support

packages/xrpl/HISTORY.md

@@ -8,6 +8,9 @@ Subscribe to [the **xrpl-announce** mailing list](https://groups.google.com/g/xr
 * `Wallet.fromMnemonic` detects when an invalid encoding is provided, and throws an error
 * Made unexpected errors in `submitAndWait` more verbose to make them easier to debug.
 
+### Added
+* Support for Automated Market Maker (AMM).
+
 ## 2.3.1 (2022-06-27)
 ### Fixed
 * Signing tx with standard currency codes with lowercase and allowed symbols causing an error on decode.

packages/xrpl/src/client/index.ts

@@ -24,6 +24,9 @@ import {
   AccountOffersResponse,
   AccountTxRequest,
   AccountTxResponse,
+  // AMM methods
+  AMMInfoRequest,
+  AMMInfoResponse,
   GatewayBalancesRequest,
   GatewayBalancesResponse,
   NoRippleCheckRequest,
@@ -298,6 +301,7 @@ class Client extends EventEmitter {
   ): Promise<AccountObjectsResponse>
   public async request(r: AccountOffersRequest): Promise<AccountOffersResponse>
   public async request(r: AccountTxRequest): Promise<AccountTxResponse>
+  public async request(r: AMMInfoRequest): Promise<AMMInfoResponse>
   public async request(r: BookOffersRequest): Promise<BookOffersResponse>
   public async request(r: ChannelVerifyRequest): Promise<ChannelVerifyResponse>
   public async request(

packages/xrpl/src/models/methods/ammInfo.ts

@@ -0,0 +1,81 @@
+import { Amount, IssuedCurrencyAmount } from '../common'
+
+import { BaseRequest, BaseResponse } from './baseMethod'
+
+/**
+ * The `amm_info` command retrieves information about an AMM instance.
+ * Returns an {@link AMMInfoResponse}.
+ *
+ * @category Requests
+ */
+export interface AMMInfoRequest extends BaseRequest {
+  command: 'amm_info'
+
+  /**
+   * A hash that uniquely identifies the AMM instance.
+   */
+  amm_id?: string
+
+  /**
+   * Specifies one of the pool assets (XRP or token) of the AMM instance.
+   */
+  asset1?: Amount
+
+  /**
+   * Specifies the other pool asset of the AMM instance.
+   */
+  asset2?: Amount
+}
+
+/**
+ * Response expected from an {@link AMMInfoRequest}.
+ *
+ * @category Responses
+ */
+export interface AMMInfoResponse extends BaseResponse {
+  result: {
+    /**
+     * The account that tracks the balance of LPTokens between the AMM instance via Trustline.
+     */
+    AMMAccount: string
+
+    /**
+     * Specifies one of the pool assets (XRP or token) of the AMM instance.
+     */
+    Asset1: Amount
+
+    /**
+     * Specifies the other pool asset of the AMM instance.
+     */
+    Asset2: Amount
+
+    /**
+     * Represents the liquidity providers' shares of the AMM instance's pools.
+     * LPTokens are tokens on XRPL. Each LPToken represents a proportional share of each pool of the AMM instance.
+     * The AMM instance account issues the LPTokens to LPs upon liquidity provision.
+     * LPTokens are balanced in the LPs trustline upon liquidity removal.
+     */
+    LPToken: IssuedCurrencyAmount
+
+    /**
+     * Specifies the fee, in basis point, to be charged to the traders for the trades
+     * executed against the AMM instance. Trading fee is a percentage of the trading volume.
+     * Valid values for this field are between 0 and 65000 inclusive.
+     * A value of 1 is equivalent to 1/10 bps or 0.001%, allowing trading fee
+     * between 0% and 65%. This field is required.
+     */
+    TradingFee: number
+
+    /**
+     * The ledger index of the current in-progress ledger, which was used when
+     * retrieving this information.
+     */
+    ledger_current_index?: number
+
+    /**
+     * True if this data is from a validated ledger version; if omitted or set
+     * to false, this data is not final.
+     */
+    validated?: boolean
+  }
+}

packages/xrpl/src/models/methods/index.ts

@@ -16,6 +16,7 @@ import {
   AccountOffersResponse,
 } from './accountOffers'
 import { AccountTxRequest, AccountTxResponse } from './accountTx'
+import { AMMInfoRequest, AMMInfoResponse } from './ammInfo'
 import { ErrorResponse } from './baseMethod'
 import { BookOffersRequest, BookOffer, BookOffersResponse } from './bookOffers'
 import { ChannelVerifyRequest, ChannelVerifyResponse } from './channelVerify'
@@ -87,6 +88,7 @@ type Request =
   | AccountObjectsRequest
   | AccountOffersRequest
   | AccountTxRequest
+  | AMMInfoRequest
   | GatewayBalancesRequest
   | NoRippleCheckRequest
   // ledger methods
@@ -137,6 +139,7 @@ type Response =
   | AccountObjectsResponse
   | AccountOffersResponse
   | AccountTxResponse
+  | AMMInfoResponse
   | GatewayBalancesResponse
   | NoRippleCheckResponse
   // ledger methods
@@ -195,6 +198,8 @@ export {
   AccountOffersResponse,
   AccountTxRequest,
   AccountTxResponse,
+  AMMInfoRequest,
+  AMMInfoResponse,
   GatewayBalancesRequest,
   GatewayBalancesResponse,
   NoRippleCheckRequest,

packages/xrpl/src/models/transactions/AMMBid.ts

@@ -0,0 +1,85 @@
+import { ValidationError } from '../../errors'
+import { Amount } from '../common'
+
+import { BaseTransaction, isAmount, validateBaseTransaction } from './common'
+
+const MAX_AUTH_ACCOUNTS = 4
+
+interface AuthAccount {
+  AuthAccount: {
+    Account: string
+  }
+}
+
+/**
+ * AMMBid is used for submitting a vote for the trading fee of an AMM Instance.
+ *
+ * Any XRPL account that holds LPToken for an AMM instance may submit this
+ * transaction to vote for the trading fee for that instance.
+ */
+export interface AMMBid extends BaseTransaction {
+  TransactionType: 'AMMBid'
+
+  /**
+   * A hash that uniquely identifies the AMM instance. This field is required.
+   */
+  AMMID: string
+
+  /**
+   * This field represents the minimum price that the bidder wants to pay for the slot.
+   * It is specified in units of LPToken. If specified let MinSlotPrice be X and let
+   * the slot-price computed by price scheduling algorithm be Y, then bidder always pays
+   * the max(X, Y).
+   */
+  MinSlotPrice?: Amount
+
+  /**
+   * This field represents the maximum price that the bidder wants to pay for the slot.
+   * It is specified in units of LPToken.
+   */
+  MaxSlotPrice?: Amount
+
+  /**
+   * This field represents an array of XRPL account IDs that are authorized to trade
+   * at the discounted fee against the AMM instance.
+   * A maximum of four accounts can be provided.
+   */
+  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.AMMID == null) {
+    throw new ValidationError('AMMBid: missing field AMMID')
+  }
+
+  if (typeof tx.AMMID !== 'string') {
+    throw new ValidationError('AMMBid: AMMID must be a string')
+  }
+
+  if (tx.MinSlotPrice != null && !isAmount(tx.MinSlotPrice)) {
+    throw new ValidationError('AMMBid: MinSlotPrice must be an Amount')
+  }
+
+  if (tx.MaxSlotPrice != null && !isAmount(tx.MaxSlotPrice)) {
+    throw new ValidationError('AMMBid: MaxSlotPrice must be an Amount')
+  }
+
+  if (tx.AuthAccounts != null) {
+    if (!Array.isArray(tx.AuthAccounts)) {
+      throw new ValidationError(`AMMBid: AuthAccounts must be a string array`)
+    }
+    if (tx.AuthAccounts.length > MAX_AUTH_ACCOUNTS) {
+      throw new ValidationError(
+        `AMMBid: AuthAccounts length must not be greater than ${MAX_AUTH_ACCOUNTS}`,
+      )
+    }
+  }
+}

packages/xrpl/src/models/transactions/AMMDeposit.ts

@@ -0,0 +1,99 @@
+/* eslint-disable complexity -- required for validateAMMDeposit */
+import { ValidationError } from '../../errors'
+import { Amount, IssuedCurrencyAmount } from '../common'
+
+import {
+  BaseTransaction,
+  isAmount,
+  isIssuedCurrency,
+  validateBaseTransaction,
+} from './common'
+
+/**
+ * AMMDeposit is the deposit transaction used to add liquidity to the AMM instance pool,
+ * thus obtaining some share of the instance's pools in the form of LPToken.
+ *
+ * The following are the recommended valid combinations:
+ * - LPToken
+ * - Asset1In
+ * - Asset1In and Asset2In
+ * - Asset1In and LPToken
+ * - Asset1In and EPrice
+ */
+export interface AMMDeposit extends BaseTransaction {
+  TransactionType: 'AMMDeposit'
+
+  /**
+   * A hash that uniquely identifies the AMM instance. This field is required.
+   */
+  AMMID: string
+
+  /**
+   * Specifies the amount of shares of the AMM instance pools that the trader
+   * wants to redeem or trade in.
+   */
+  LPToken?: IssuedCurrencyAmount
+
+  /**
+   * Specifies one of the pool assets (XRP or token) of the AMM instance to
+   * deposit more of its value.
+   */
+  Asset1In?: Amount
+
+  /**
+   * Specifies the other pool asset of the AMM instance to deposit more of
+   * its value.
+   */
+  Asset2In?: Amount
+
+  /**
+   * Specifies the maximum effective-price that LPToken can be traded out.
+   */
+  EPrice?: number
+}
+
+/**
+ * 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.AMMID == null) {
+    throw new ValidationError('AMMDeposit: missing field AMMID')
+  }
+
+  if (typeof tx.AMMID !== 'string') {
+    throw new ValidationError('AMMDeposit: AMMID must be a string')
+  }
+
+  if (tx.Asset2In != null && tx.Asset1In == null) {
+    throw new ValidationError('AMMDeposit: must set Asset1In with Asset2In')
+  } else if (tx.EPrice != null && tx.Asset1In == null) {
+    throw new ValidationError('AMMDeposit: must set Asset1In with EPrice')
+  } else if (tx.LPToken == null && tx.Asset1In == null) {
+    throw new ValidationError(
+      'AMMDeposit: must set either or both LPToken with Asset1In',
+    )
+  }
+
+  if (tx.LPToken != null && !isIssuedCurrency(tx.LPToken)) {
+    throw new ValidationError(
+      'AMMDeposit: LPToken must be an IssuedCurrencyAmount',
+    )
+  }
+
+  if (tx.Asset1In != null && !isAmount(tx.Asset1In)) {
+    throw new ValidationError('AMMDeposit: Asset1In must be an Amount')
+  }
+
+  if (tx.Asset2In != null && !isAmount(tx.Asset2In)) {
+    throw new ValidationError('AMMDeposit: Asset2In must be an Amount')
+  }
+
+  if (tx.EPrice != null && typeof tx.EPrice !== 'string') {
+    throw new ValidationError('AMMDeposit: EPrice must be a string')
+  }
+}