xrpl 2.10.0 → 2.11.0

package/src/models/transactions/NFTokenAcceptOffer.ts

@@ -0,0 +1,104 @@
+import { ValidationError } from '../../errors'
+import { Amount } from '../common'
+
+import {
+  BaseTransaction,
+  parseAmountValue,
+  validateBaseTransaction,
+} from './common'
+
+/**
+ *  The NFTokenOfferAccept transaction is used to accept offers
+ *  to buy or sell an NFToken. It can either:
+ *
+ *  1. Allow one offer to be accepted. This is called direct
+ *     mode.
+ *  2. Allow two distinct offers, one offering to buy a
+ *     given NFToken and the other offering to sell the same
+ *     NFToken, to be accepted in an atomic fashion. This is
+ *     called brokered mode.
+ *
+ *  To indicate direct mode, use either the `sell_offer` or
+ *  `buy_offer` fields, but not both. To indicate brokered mode,
+ *  use both the `sell_offer` and `buy_offer` fields. If you use
+ *  neither `sell_offer` nor `buy_offer`, the transaction is invalid.
+ */
+export interface NFTokenAcceptOffer extends BaseTransaction {
+  TransactionType: 'NFTokenAcceptOffer'
+  /**
+   *  Identifies the NFTokenOffer that offers to sell the NFToken.
+   *
+   *  In direct mode this field is optional, but either NFTokenSellOffer or
+   *  NFTokenBuyOffer must be specified. In brokered mode, both NFTokenSellOffer
+   *  and NFTokenBuyOffer must be specified.
+   */
+  NFTokenSellOffer?: string
+  /**
+   * Identifies the NFTokenOffer that offers to buy the NFToken.
+   *
+   * In direct mode this field is optional, but either NFTokenSellOffer or
+   * NFTokenBuyOffer must be specified. In brokered mode, both NFTokenSellOffer
+   * and NFTokenBuyOffer must be specified.
+   */
+  NFTokenBuyOffer?: string
+  /**
+   * This field is only valid in brokered mode. It specifies the
+   * amount that the broker will keep as part of their fee for
+   * bringing the two offers together; the remaining amount will
+   * be sent to the seller of the NFToken being bought. If
+   * specified, the fee must be such that, prior to accounting
+   * for the transfer fee charged by the issuer, the amount that
+   * the seller would receive is at least as much as the amount
+   * indicated in the sell offer.
+   *
+   * This functionality is intended to allow the owner of an
+   * NFToken to offer their token for sale to a third party
+   * broker, who may then attempt to sell the NFToken on for a
+   * larger amount, without the broker having to own the NFToken
+   * or custody funds.
+   *
+   * Note: in brokered mode, the offers referenced by NFTokenBuyOffer
+   * and NFTokenSellOffer must both specify the same NFTokenID; that is,
+   * both must be for the same NFToken.
+   */
+  NFTokenBrokerFee?: Amount
+}
+
+function validateNFTokenBrokerFee(tx: Record<string, unknown>): void {
+  const value = parseAmountValue(tx.NFTokenBrokerFee)
+  if (Number.isNaN(value)) {
+    throw new ValidationError('NFTokenAcceptOffer: invalid NFTokenBrokerFee')
+  }
+
+  if (value <= 0) {
+    throw new ValidationError(
+      'NFTokenAcceptOffer: NFTokenBrokerFee must be greater than 0; omit if there is no fee',
+    )
+  }
+
+  if (tx.NFTokenSellOffer == null || tx.NFTokenBuyOffer == null) {
+    throw new ValidationError(
+      'NFTokenAcceptOffer: both NFTokenSellOffer and NFTokenBuyOffer must be set if using brokered mode',
+    )
+  }
+}
+
+/**
+ * Verify the form and type of an NFTokenAcceptOffer at runtime.
+ *
+ * @param tx - An NFTokenAcceptOffer Transaction.
+ * @throws When the NFTokenAcceptOffer is Malformed.
+ */
+export function validateNFTokenAcceptOffer(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.NFTokenBrokerFee != null) {
+    validateNFTokenBrokerFee(tx)
+  }
+
+  if (tx.NFTokenSellOffer == null && tx.NFTokenBuyOffer == null) {
+    throw new ValidationError(
+      'NFTokenAcceptOffer: must set either NFTokenSellOffer or NFTokenBuyOffer',
+    )
+  }
+}

package/src/models/transactions/NFTokenBurn.ts

@@ -0,0 +1,48 @@
+import { ValidationError } from '../../errors'
+
+import { BaseTransaction, validateBaseTransaction } from './common'
+
+/**
+ * The NFTokenBurn transaction is used to remove an NFToken object from the
+ * NFTokenPage in which it is being held, effectively removing the token from
+ * the ledger ("burning" it).
+ *
+ * If this operation succeeds, the corresponding NFToken is removed. If this
+ * operation empties the NFTokenPage holding the NFToken or results in the
+ * consolidation, thus removing an NFTokenPage, the owner’s reserve requirement
+ * is reduced by one.
+ */
+export interface NFTokenBurn extends BaseTransaction {
+  TransactionType: 'NFTokenBurn'
+  /**
+   * Indicates the AccountID that submitted this transaction. The account MUST
+   * be either the present owner of the token or, if the lsfBurnable flag is set
+   * in the NFToken, either the issuer account or an account authorized by the
+   * issuer, i.e. MintAccount.
+   */
+  Account: string
+  /**
+   * Identifies the NFToken object to be removed by the transaction.
+   */
+  NFTokenID: string
+  /**
+   * Indicates which account currently owns the token if it is different than
+   * Account. Only used to burn tokens which have the lsfBurnable flag enabled
+   * and are not owned by the signing account.
+   */
+  Owner?: string
+}
+
+/**
+ * Verify the form and type of an NFTokenBurn at runtime.
+ *
+ * @param tx - An NFTokenBurn Transaction.
+ * @throws When the NFTokenBurn is Malformed.
+ */
+export function validateNFTokenBurn(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.NFTokenID == null) {
+    throw new ValidationError('NFTokenBurn: missing field NFTokenID')
+  }
+}

package/src/models/transactions/NFTokenCancelOffer.ts

@@ -0,0 +1,45 @@
+import { ValidationError } from '../../errors'
+
+import { BaseTransaction, validateBaseTransaction } from './common'
+
+/**
+ * The NFTokenCancelOffer transaction deletes existing NFTokenOffer objects.
+ * It is useful if you want to free up space on your account to lower your
+ * reserve requirement.
+ *
+ * The transaction can be executed by the account that originally created
+ * the NFTokenOffer, the account in the `Recipient` field of the NFTokenOffer
+ * (if present), or any account if the NFTokenOffer has an `Expiration` and
+ * the NFTokenOffer has already expired.
+ */
+export interface NFTokenCancelOffer extends BaseTransaction {
+  TransactionType: 'NFTokenCancelOffer'
+  /**
+   * An array of identifiers of NFTokenOffer objects that should be cancelled
+   * by this transaction.
+   *
+   * It is an error if an entry in this list points to an
+   * object that is not an NFTokenOffer object. It is not an
+   * error if an entry in this list points to an object that
+   * does not exist. This field is required.
+   */
+  NFTokenOffers: string[]
+}
+
+/**
+ * Verify the form and type of an NFTokenCancelOffer at runtime.
+ *
+ * @param tx - An NFTokenCancelOffer Transaction.
+ * @throws When the NFTokenCancelOffer is Malformed.
+ */
+export function validateNFTokenCancelOffer(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (!Array.isArray(tx.NFTokenOffers)) {
+    throw new ValidationError('NFTokenCancelOffer: missing field NFTokenOffers')
+  }
+
+  if (tx.NFTokenOffers.length < 1) {
+    throw new ValidationError('NFTokenCancelOffer: empty field NFTokenOffers')
+  }
+}

package/src/models/transactions/NFTokenCreateOffer.ts

@@ -0,0 +1,145 @@
+import { ValidationError } from '../../errors'
+import { Amount } from '../common'
+import { isFlagEnabled } from '../utils'
+
+import {
+  BaseTransaction,
+  GlobalFlags,
+  validateBaseTransaction,
+  isAmount,
+  parseAmountValue,
+} from './common'
+
+/**
+ * Transaction Flags for an NFTokenCreateOffer Transaction.
+ *
+ * @category Transaction Flags
+ */
+export enum NFTokenCreateOfferFlags {
+  /**
+   * If set, indicates that the offer is a sell offer.
+   * Otherwise, it is a buy offer.
+   */
+  tfSellNFToken = 0x00000001,
+}
+
+/**
+ * Map of flags to boolean values representing {@link NFTokenCreateOffer} transaction
+ * flags.
+ *
+ * @category Transaction Flags
+ */
+export interface NFTokenCreateOfferFlagsInterface extends GlobalFlags {
+  tfSellNFToken?: boolean
+}
+
+/**
+ * The NFTokenCreateOffer transaction creates either an offer to buy an
+ * NFT the submitting account does not own, or an offer to sell an NFT
+ * the submitting account does own.
+ */
+export interface NFTokenCreateOffer extends BaseTransaction {
+  TransactionType: 'NFTokenCreateOffer'
+  /**
+   * Identifies the NFTokenID of the NFToken object that the
+   * offer references.
+   */
+  NFTokenID: string
+  /**
+   * Indicates the amount expected or offered for the Token.
+   *
+   * The amount must be non-zero, except when this is a sell
+   * offer and the asset is XRP. This would indicate that the current
+   * owner of the token is giving it away free, either to anyone at all,
+   * or to the account identified by the Destination field.
+   */
+  Amount: Amount
+  /**
+   * Indicates the AccountID of the account that owns the
+   * corresponding NFToken.
+   *
+   * If the offer is to buy a token, this field must be present
+   * and it must be different than Account (since an offer to
+   * buy a token one already holds is meaningless).
+   *
+   * If the offer is to sell a token, this field must not be
+   * present, as the owner is, implicitly, the same as Account
+   * (since an offer to sell a token one doesn't already hold
+   * is meaningless).
+   */
+  Owner?: string
+  /**
+   * Indicates the time after which the offer will no longer
+   * be valid. The value is the number of seconds since the
+   * Ripple Epoch.
+   */
+  Expiration?: number
+  /**
+   * If present, indicates that this offer may only be
+   * accepted by the specified account. Attempts by other
+   * accounts to accept this offer MUST fail.
+   */
+  Destination?: string
+  Flags?: number | NFTokenCreateOfferFlagsInterface
+}
+
+function validateNFTokenSellOfferCases(tx: Record<string, unknown>): void {
+  if (tx.Owner != null) {
+    throw new ValidationError(
+      'NFTokenCreateOffer: Owner must not be present for sell offers',
+    )
+  }
+}
+
+function validateNFTokenBuyOfferCases(tx: Record<string, unknown>): void {
+  if (tx.Owner == null) {
+    throw new ValidationError(
+      'NFTokenCreateOffer: Owner must be present for buy offers',
+    )
+  }
+
+  if (parseAmountValue(tx.Amount) <= 0) {
+    throw new ValidationError(
+      'NFTokenCreateOffer: Amount must be greater than 0 for buy offers',
+    )
+  }
+}
+
+/**
+ * Verify the form and type of an NFTokenCreateOffer at runtime.
+ *
+ * @param tx - An NFTokenCreateOffer Transaction.
+ * @throws When the NFTokenCreateOffer is Malformed.
+ */
+export function validateNFTokenCreateOffer(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.Account === tx.Owner) {
+    throw new ValidationError(
+      'NFTokenCreateOffer: Owner and Account must not be equal',
+    )
+  }
+
+  if (tx.Account === tx.Destination) {
+    throw new ValidationError(
+      'NFTokenCreateOffer: Destination and Account must not be equal',
+    )
+  }
+
+  if (tx.NFTokenID == null) {
+    throw new ValidationError('NFTokenCreateOffer: missing field NFTokenID')
+  }
+
+  if (!isAmount(tx.Amount)) {
+    throw new ValidationError('NFTokenCreateOffer: invalid Amount')
+  }
+
+  if (
+    typeof tx.Flags === 'number' &&
+    isFlagEnabled(tx.Flags, NFTokenCreateOfferFlags.tfSellNFToken)
+  ) {
+    validateNFTokenSellOfferCases(tx)
+  } else {
+    validateNFTokenBuyOfferCases(tx)
+  }
+}

package/src/models/transactions/NFTokenMint.ts

@@ -0,0 +1,123 @@
+import { ValidationError } from '../../errors'
+import { isHex } from '../utils'
+
+import { BaseTransaction, GlobalFlags, validateBaseTransaction } from './common'
+
+/**
+ * Transaction Flags for an NFTokenMint Transaction.
+ *
+ * @category Transaction Flags
+ */
+export enum NFTokenMintFlags {
+  /**
+   * If set, indicates that the minted token may be burned by the issuer even
+   * if the issuer does not currently hold the token. The current holder of
+   * the token may always burn it.
+   */
+  tfBurnable = 0x00000001,
+  /**
+   * If set, indicates that the token may only be offered or sold for XRP.
+   */
+  tfOnlyXRP = 0x00000002,
+  /**
+   * If set, indicates that the issuer wants a trustline to be automatically
+   * created.
+   */
+  tfTrustLine = 0x00000004,
+  /**
+   * If set, indicates that this NFT can be transferred. This flag has no
+   * effect if the token is being transferred from the issuer or to the
+   * issuer.
+   */
+  tfTransferable = 0x00000008,
+}
+
+/**
+ * Map of flags to boolean values representing {@link NFTokenMint} transaction
+ * flags.
+ *
+ * @category Transaction Flags
+ */
+export interface NFTokenMintFlagsInterface extends GlobalFlags {
+  tfBurnable?: boolean
+  tfOnlyXRP?: boolean
+  tfTrustLine?: boolean
+  tfTransferable?: boolean
+}
+
+/**
+ * The NFTokenMint transaction creates an NFToken object and adds it to the
+ * relevant NFTokenPage object of the minter. If the transaction is
+ * successful, the newly minted token will be owned by the minter account
+ * specified by the transaction.
+ */
+export interface NFTokenMint extends BaseTransaction {
+  TransactionType: 'NFTokenMint'
+  /**
+   * Indicates the taxon associated with this token. The taxon is generally a
+   * value chosen by the minter of the token and a given taxon may be used for
+   * multiple tokens. The implementation reserves taxon identifiers greater
+   * than or equal to 2147483648 (0x80000000). If you have no use for this
+   * field, set it to 0.
+   */
+  NFTokenTaxon: number
+  /**
+   * Indicates the account that should be the issuer of this token. This value
+   * is optional and should only be specified if the account executing the
+   * transaction is not the `Issuer` of the `NFToken` object. If it is
+   * present, the `MintAccount` field in the `AccountRoot` of the `Issuer`
+   * field must match the `Account`, otherwise the transaction will fail.
+   */
+  Issuer?: string
+  /**
+   * Specifies the fee charged by the issuer for secondary sales of the Token,
+   * if such sales are allowed. Valid values for this field are between 0 and
+   * 50000 inclusive, allowing transfer rates between 0.000% and 50.000% in
+   * increments of 0.001%. This field must NOT be present if the
+   * `tfTransferable` flag is not set.
+   */
+  TransferFee?: number
+  /**
+   * URI that points to the data and/or metadata associated with the NFT.
+   * This field need not be an HTTP or HTTPS URL; it could be an IPFS URI, a
+   * magnet link, immediate data encoded as an RFC2379 "data" URL, or even an
+   * opaque issuer-specific encoding. The URI is NOT checked for validity, but
+   * the field is limited to a maximum length of 256 bytes.
+   *
+   * This field must be hex-encoded. You can use `convertStringToHex` to
+   * convert this field to the proper encoding.
+   *
+   * This field must not be an empty string. Omit it from the transaction or
+   * set to `undefined` value if you do not use it.
+   */
+  URI?: string | null
+  Flags?: number | NFTokenMintFlagsInterface
+}
+
+/**
+ * Verify the form and type of an NFTokenMint at runtime.
+ *
+ * @param tx - An NFTokenMint Transaction.
+ * @throws When the NFTokenMint is Malformed.
+ */
+export function validateNFTokenMint(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.Account === tx.Issuer) {
+    throw new ValidationError(
+      'NFTokenMint: Issuer must not be equal to Account',
+    )
+  }
+
+  if (typeof tx.URI === 'string' && tx.URI === '') {
+    throw new ValidationError('NFTokenMint: URI must not be empty string')
+  }
+
+  if (typeof tx.URI === 'string' && !isHex(tx.URI)) {
+    throw new ValidationError('NFTokenMint: URI must be in hex format')
+  }
+
+  if (tx.NFTokenTaxon == null) {
+    throw new ValidationError('NFTokenMint: missing field NFTokenTaxon')
+  }
+}

package/src/models/transactions/UNLModify.ts

@@ -0,0 +1,20 @@
+/**
+ * Mark a change to the Negative UNL.
+ *
+ * @category Pseudo Transaction Models
+ */
+export interface UNLModify {
+  TransactionType: 'UNLModify'
+  /**
+   * The ledger index where this pseudo-transaction appears.
+   * This distinguishes the pseudo-transaction from other occurrences of the same change.
+   */
+  LedgerSequence: number
+  /**
+   * If 0, this change represents removing a validator from the Negative UNL.
+   * If 1, this change represents adding a validator to the Negative UNL.
+   */
+  UNLModifyDisabling: 0 | 1
+  /** The validator to add or remove, as identified by its master public key. */
+  UNLModifyValidator: string
+}

package/src/models/transactions/accountDelete.ts

@@ -0,0 +1,50 @@
+import { ValidationError } from '../../errors'
+
+import { BaseTransaction, validateBaseTransaction } from './common'
+
+/**
+ * An AccountDelete transaction deletes an account and any objects it owns in
+ * the XRP Ledger, if possible, sending the account's remaining XRP to a
+ * specified destination account.
+ *
+ * @category Transaction Models
+ */
+export interface AccountDelete extends BaseTransaction {
+  TransactionType: 'AccountDelete'
+  /**
+   * The address of an account to receive any leftover XRP after deleting the
+   * sending account. Must be a funded account in the ledger, and must not be.
+   * the sending account.
+   */
+  Destination: string
+  /**
+   * Arbitrary destination tag that identifies a hosted recipient or other.
+   * information for the recipient of the deleted account's leftover XRP.
+   */
+  DestinationTag?: number
+}
+
+/**
+ * Verify the form and type of an AccountDelete at runtime.
+ *
+ * @param tx - An AccountDelete Transaction.
+ * @throws When the AccountDelete is Malformed.
+ */
+export function validateAccountDelete(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.Destination === undefined) {
+    throw new ValidationError('AccountDelete: missing field Destination')
+  }
+
+  if (typeof tx.Destination !== 'string') {
+    throw new ValidationError('AccountDelete: invalid Destination')
+  }
+
+  if (
+    tx.DestinationTag !== undefined &&
+    typeof tx.DestinationTag !== 'number'
+  ) {
+    throw new ValidationError('AccountDelete: invalid DestinationTag')
+  }
+}