xrpl 4.0.0 → 4.1.0

package/src/client/partialPayment.ts

@@ -4,22 +4,35 @@ import { decode } from 'ripple-binary-codec'
 import type {
   TransactionEntryResponse,
   TransactionStream,
+  TransactionV1Stream,
   TxResponse,
 } from '..'
-import type { Amount, APIVersion, DEFAULT_API_VERSION } from '../models/common'
+import type {
+  Amount,
+  IssuedCurrency,
+  APIVersion,
+  DEFAULT_API_VERSION,
+  MPTAmount,
+} from '../models/common'
 import type {
   AccountTxTransaction,
   RequestResponseMap,
 } from '../models/methods'
 import { AccountTxVersionResponseMap } from '../models/methods/accountTx'
 import { BaseRequest, BaseResponse } from '../models/methods/baseMethod'
-import { PaymentFlags, Transaction } from '../models/transactions'
+import { PaymentFlags, Transaction, isMPTAmount } from '../models/transactions'
 import type { TransactionMetadata } from '../models/transactions/metadata'
 import { isFlagEnabled } from '../models/utils'
 
 const WARN_PARTIAL_PAYMENT_CODE = 2001
 
-function amountsEqual(amt1: Amount, amt2: Amount): boolean {
+/* eslint-disable complexity -- check different token types */
+/* eslint-disable @typescript-eslint/consistent-type-assertions -- known currency type */
+function amountsEqual(
+  amt1: Amount | MPTAmount,
+  amt2: Amount | MPTAmount,
+): boolean {
+  // Compare XRP
   if (typeof amt1 === 'string' && typeof amt2 === 'string') {
     return amt1 === amt2
   }
@@ -28,15 +41,32 @@ function amountsEqual(amt1: Amount, amt2: Amount): boolean {
     return false
   }
 
+  // Compare MPTs
+  if (isMPTAmount(amt1) && isMPTAmount(amt2)) {
+    const aValue = new BigNumber(amt1.value)
+    const bValue = new BigNumber(amt2.value)
+
+    return (
+      amt1.mpt_issuance_id === amt2.mpt_issuance_id && aValue.isEqualTo(bValue)
+    )
+  }
+
+  if (isMPTAmount(amt1) || isMPTAmount(amt2)) {
+    return false
+  }
+
+  // Compare issued currency (IOU)
   const aValue = new BigNumber(amt1.value)
   const bValue = new BigNumber(amt2.value)
 
   return (
-    amt1.currency === amt2.currency &&
-    amt1.issuer === amt2.issuer &&
+    (amt1 as IssuedCurrency).currency === (amt2 as IssuedCurrency).currency &&
+    (amt1 as IssuedCurrency).issuer === (amt2 as IssuedCurrency).issuer &&
     aValue.isEqualTo(bValue)
   )
 }
+/* eslint-enable complexity */
+/* eslint-enable @typescript-eslint/consistent-type-assertions */
 
 function isPartialPayment(
   tx?: Transaction,
@@ -159,10 +189,10 @@ export function handlePartialPayment<
  * @param log - The method used for logging by the connection (to report the partial payment).
  */
 export function handleStreamPartialPayment(
-  stream: TransactionStream,
+  stream: TransactionStream | TransactionV1Stream,
   log: (id: string, message: string) => void,
 ): void {
-  if (isPartialPayment(stream.transaction, stream.meta)) {
+  if (isPartialPayment(stream.tx_json ?? stream.transaction, stream.meta)) {
     const warnings = stream.warnings ?? []
 
     const warning = {

package/src/models/common/index.ts

@@ -20,6 +20,11 @@ export interface IssuedCurrencyAmount extends IssuedCurrency {
   value: string
 }
 
+export interface MPTAmount {
+  mpt_issuance_id: string
+  value: string
+}
+
 export type Amount = IssuedCurrencyAmount | string
 
 export interface Balance {
@@ -157,6 +162,16 @@ export interface AuthAccount {
   }
 }
 
+export interface AuthorizeCredential {
+  Credential: {
+    /** The issuer of the credential. */
+    Issuer: string
+
+    /** A hex-encoded value to identify the type of credential from the issuer. */
+    CredentialType: string
+  }
+}
+
 export interface XChainBridge {
   LockingChainDoor: string
   LockingChainIssue: Currency

package/src/models/index.ts

@@ -10,6 +10,7 @@ export * as LedgerEntry from './ledger'
 export {
   setTransactionFlagsToNumber,
   parseAccountRootFlags,
+  parseTransactionFlags,
 } from './utils/flags'
 export * from './methods'
 export * from './transactions'

package/src/models/ledger/Credential.ts

@@ -0,0 +1,47 @@
+import { GlobalFlags } from '../transactions/common'
+
+import { BaseLedgerEntry, HasPreviousTxnID } from './BaseLedgerEntry'
+
+export interface CredentialFlags extends GlobalFlags {
+  lsfAccepted?: boolean
+}
+
+/**
+ *
+ * A Credential object describes a credential, similar to a passport, which is an issuable identity verifier
+ * that can be used as a prerequisite for other transactions
+ *
+ * @category Ledger Entries
+ */
+export default interface Credential extends BaseLedgerEntry, HasPreviousTxnID {
+  LedgerEntryType: 'Credential'
+  /**
+   * A bit-map of boolean flags
+   */
+  Flags: number | CredentialFlags
+
+  /** The account that the credential is for. */
+  Subject: string
+
+  /** The issuer of the credential. */
+  Issuer: string
+
+  /** A hex-encoded value to identify the type of credential from the issuer. */
+  CredentialType: string
+
+  /** A hint indicating which page of the subject's owner directory links to this object,
+   * in case the directory consists of multiple pages.
+   */
+  SubjectNode: string
+
+  /** A hint indicating which page of the issuer's owner directory links to this object,
+   * in case the directory consists of multiple pages.
+   */
+  IssuerNode: string
+
+  /** Credential expiration. */
+  Expiration?: number
+
+  /** Additional data about the credential (such as a link to the VC document). */
+  URI?: string
+}

package/src/models/ledger/DepositPreauth.ts

@@ -1,3 +1,5 @@
+import { AuthorizeCredential } from '../common'
+
 import { BaseLedgerEntry, HasPreviousTxnID } from './BaseLedgerEntry'
 
 /**
@@ -12,8 +14,6 @@ export default interface DepositPreauth
   LedgerEntryType: 'DepositPreauth'
   /** The account that granted the preauthorization. */
   Account: string
-  /** The account that received the preauthorization. */
-  Authorize: string
   /**
    * A bit-map of boolean flags. No flags are defined for DepositPreauth
    * objects, so this value is always 0.
@@ -24,4 +24,8 @@ export default interface DepositPreauth
    * object, in case the directory consists of multiple pages.
    */
   OwnerNode: string
+  /** The account that received the preauthorization. */
+  Authorize?: string
+  /** The credential(s) that received the preauthorization. */
+  AuthorizeCredentials?: AuthorizeCredential[]
 }

package/src/models/ledger/Ledger.ts

@@ -31,6 +31,11 @@ interface BaseLedger {
    * by which the close_time could be rounded.
    */
   close_time_resolution: number
+  /**
+   * The approximate time this ledger was closed, in date time string format.
+   * Always uses the UTC time zone.
+   */
+  close_time_iso: string
   /** Whether or not this ledger has been closed. */
   closed: boolean
   /**

package/src/models/ledger/LedgerEntry.ts

@@ -3,6 +3,7 @@ import Amendments from './Amendments'
 import AMM from './AMM'
 import Bridge from './Bridge'
 import Check from './Check'
+import Credential from './Credential'
 import DepositPreauth from './DepositPreauth'
 import DirectoryNode from './DirectoryNode'
 import Escrow from './Escrow'
@@ -24,6 +25,7 @@ type LedgerEntry =
   | AMM
   | Bridge
   | Check
+  | Credential
   | DepositPreauth
   | DirectoryNode
   | Escrow
@@ -45,12 +47,15 @@ type LedgerEntryFilter =
   | 'amm'
   | 'bridge'
   | 'check'
+  | 'credential'
   | 'deposit_preauth'
   | 'did'
   | 'directory'
   | 'escrow'
   | 'fee'
   | 'hashes'
+  | 'mpt_issuance'
+  | 'mptoken'
   | 'nft_offer'
   | 'nft_page'
   | 'offer'

package/src/models/ledger/MPToken.ts

@@ -0,0 +1,11 @@
+import { MPTAmount } from '../common'
+
+import { BaseLedgerEntry, HasPreviousTxnID } from './BaseLedgerEntry'
+
+export interface MPToken extends BaseLedgerEntry, HasPreviousTxnID {
+  LedgerEntryType: 'MPToken'
+  MPTokenIssuanceID: string
+  MPTAmount?: MPTAmount
+  Flags: number
+  OwnerNode?: string
+}

package/src/models/ledger/MPTokenIssuance.ts

@@ -0,0 +1,13 @@
+import { BaseLedgerEntry, HasPreviousTxnID } from './BaseLedgerEntry'
+
+export interface MPTokenIssuance extends BaseLedgerEntry, HasPreviousTxnID {
+  LedgerEntryType: 'MPTokenIssuance'
+  Flags: number
+  Issuer: string
+  AssetScale?: number
+  MaximumAmount?: string
+  OutstandingAmount: string
+  TransferFee?: number
+  MPTokenMetadata?: string
+  OwnerNode?: string
+}

package/src/models/ledger/index.ts

@@ -6,6 +6,7 @@ import Amendments, { Majority, AMENDMENTS_ID } from './Amendments'
 import AMM, { VoteSlot } from './AMM'
 import Bridge from './Bridge'
 import Check from './Check'
+import Credential from './Credential'
 import DepositPreauth from './DepositPreauth'
 import DID from './DID'
 import DirectoryNode from './DirectoryNode'
@@ -18,6 +19,8 @@ import FeeSettings, {
 import { Ledger, LedgerV1 } from './Ledger'
 import { LedgerEntry, LedgerEntryFilter } from './LedgerEntry'
 import LedgerHashes from './LedgerHashes'
+import { MPToken } from './MPToken'
+import { MPTokenIssuance } from './MPTokenIssuance'
 import NegativeUNL, { NEGATIVE_UNL_ID } from './NegativeUNL'
 import { NFTokenOffer } from './NFTokenOffer'
 import { NFToken, NFTokenPage } from './NFTokenPage'
@@ -39,6 +42,7 @@ export {
   AMM,
   Bridge,
   Check,
+  Credential,
   DepositPreauth,
   DirectoryNode,
   DID,
@@ -55,6 +59,8 @@ export {
   Majority,
   NEGATIVE_UNL_ID,
   NegativeUNL,
+  MPTokenIssuance,
+  MPToken,
   NFTokenOffer,
   NFTokenPage,
   NFToken,

package/src/models/methods/depositAuthorized.ts

@@ -15,6 +15,12 @@ export interface DepositAuthorizedRequest
   source_account: string
   /** The recipient of a possible payment. */
   destination_account: string
+  /**
+   * The object IDs of Credential objects. If this field is included, then the
+   * credential will be taken into account when analyzing whether the sender can send
+   * funds to the destination.
+   */
+  credentials?: string[]
 }
 
 /**
@@ -52,5 +58,9 @@ export interface DepositAuthorizedResponse extends BaseResponse {
     source_account: string
     /** If true, the information comes from a validated ledger version. */
     validated?: boolean
+    /** The object IDs of `Credential` objects. If this field is included,
+     * then the credential will be taken into account when analyzing whether
+     * the sender can send funds to the destination. */
+    credentials?: string[]
   }
 }

package/src/models/methods/index.ts

@@ -168,6 +168,7 @@ import {
   SubscribeRequest,
   SubscribeResponse,
   TransactionStream,
+  TransactionV1Stream,
   ValidationStream,
 } from './subscribe'
 import {
@@ -583,6 +584,7 @@ export {
   LedgerStreamResponse,
   ValidationStream,
   TransactionStream,
+  TransactionV1Stream,
   PathFindStream,
   PeerStatusStream,
   OrderBookStream,

package/src/models/methods/ledgerEntry.ts

@@ -21,6 +21,22 @@ import { BaseRequest, BaseResponse, LookupByLedgerRequest } from './baseMethod'
  */
 export interface LedgerEntryRequest extends BaseRequest, LookupByLedgerRequest {
   command: 'ledger_entry'
+
+  /**
+   * Retrieve a MPTokenIssuance object from the ledger.
+   */
+  mpt_issuance?: string
+
+  /**
+   * Retrieve a MPToken object from the ledger.
+   */
+  mptoken?:
+    | {
+        mpt_issuance_id: string
+        account: string
+      }
+    | string
+
   /**
    * Retrieve an Automated Market Maker (AMM) object from the ledger.
    * This is similar to amm_info method, but the ledger_entry version returns only the ledger entry as stored.
@@ -35,7 +51,14 @@ export interface LedgerEntryRequest extends BaseRequest, LookupByLedgerRequest {
       issuer?: string
     }
   }
-
+  /**
+   * (Optional) If set to true and the queried object has been deleted,
+   * return its complete data prior to its deletion.
+   * If set to false or not provided and the queried object has been deleted,
+   * return objectNotFound (current behavior).
+   * This parameter is supported only by Clio servers
+   */
+  include_deleted?: boolean
   /**
    * If true, return the requested ledger object's contents as a hex string in
    * the XRP Ledger's binary format. Otherwise, return data in JSON format. The
@@ -60,6 +83,23 @@ export interface LedgerEntryRequest extends BaseRequest, LookupByLedgerRequest {
   /** The object ID of a Check object to retrieve. */
   check?: string
 
+  /* Specify the Credential to retrieve. If a string, must be the ledger entry ID of
+   * the entry, as hexadecimal. If an object, requires subject, issuer, and
+   * credential_type sub-fields.
+   */
+  credential?:
+    | {
+        /** The account that is the subject of the credential. */
+        subject: string
+
+        /** The account that issued the credential. */
+        issuer: string
+
+        /** The type of the credential, as issued. */
+        credentialType: string
+      }
+    | string
+
   /**
    * Specify a DepositPreauth object to retrieve. If a string, must be the
    * object ID of the DepositPreauth object, as hexadecimal. If an object,
@@ -204,5 +244,9 @@ export interface LedgerEntryResponse<T = LedgerEntry> extends BaseResponse {
     /** The binary representation of the ledger object, as hexadecimal. */
     node_binary?: string
     validated?: boolean
+    /**
+     * (Optional) Indicates the ledger index at which the object was deleted.
+     */
+    deleted_ledger_index?: number
   }
 }

package/src/models/methods/subscribe.ts

@@ -4,6 +4,10 @@ import type {
   Path,
   StreamType,
   ResponseOnlyTxInfo,
+  APIVersion,
+  DEFAULT_API_VERSION,
+  RIPPLED_API_V1,
+  RIPPLED_API_V2,
 } from '../common'
 import { Offer } from '../ledger'
 import { OfferCreate, Transaction } from '../transactions'
@@ -262,9 +266,16 @@ export interface ValidationStream extends BaseStream {
  *
  * @category Streams
  */
-export interface TransactionStream extends BaseStream {
+interface TransactionStreamBase<
+  Version extends APIVersion = typeof DEFAULT_API_VERSION,
+> extends BaseStream {
   status: string
   type: 'transaction'
+  /**
+   * The approximate time this ledger was closed, in date time string format.
+   * Always uses the UTC time zone.
+   */
+  close_time_iso: string
   /** String Transaction result code. */
   engine_result: string
   /** Numeric transaction response code, if applicable. */
@@ -285,8 +296,14 @@ export interface TransactionStream extends BaseStream {
    * in detail.
    */
   meta?: TransactionMetadata
-  /** The definition of the transaction in JSON format. */
-  transaction: Transaction & ResponseOnlyTxInfo
+  /** JSON object defining the transaction. */
+  tx_json?: Version extends typeof RIPPLED_API_V2
+    ? Transaction & ResponseOnlyTxInfo
+    : never
+  /** JSON object defining the transaction in rippled API v1. */
+  transaction?: Version extends typeof RIPPLED_API_V1
+    ? Transaction & ResponseOnlyTxInfo
+    : never
   /**
    * If true, this transaction is included in a validated ledger and its
    * outcome is final. Responses from the transaction stream should always be
@@ -296,6 +313,20 @@ export interface TransactionStream extends BaseStream {
   warnings?: Array<{ id: number; message: string }>
 }
 
+/**
+ * Expected response from an {@link AccountTxRequest}.
+ *
+ * @category Streams
+ */
+export type TransactionStream = TransactionStreamBase
+
+/**
+ * Expected response from an {@link AccountTxRequest} with `api_version` set to 1.
+ *
+ * @category Streams
+ */
+export type TransactionV1Stream = TransactionStreamBase<typeof RIPPLED_API_V1>
+
 /**
  * The admin-only `peer_status` stream reports a large amount of information on
  * the activities of other rippled servers to which this server is connected, in

package/src/models/transactions/CredentialAccept.ts

@@ -0,0 +1,44 @@
+import {
+  BaseTransaction,
+  isString,
+  validateBaseTransaction,
+  validateCredentialType,
+  validateRequiredField,
+} from './common'
+
+/**
+ * Accepts a credential issued to the Account (i.e. the Account is the Subject of the Credential object).
+ * Credentials are represented in hex. Whilst they are allowed a maximum length of 64
+ * bytes, every byte requires 2 hex characters for representation.
+ * The credential is not considered valid until it has been transferred/accepted.
+ *
+ * @category Transaction Models
+ * */
+export interface CredentialAccept extends BaseTransaction {
+  TransactionType: 'CredentialAccept'
+
+  /** The subject of the credential. */
+  Account: string
+
+  /** The issuer of the credential. */
+  Issuer: string
+
+  /** A hex-encoded value to identify the type of credential from the issuer. */
+  CredentialType: string
+}
+
+/**
+ * Verify the form and type of a CredentialAccept at runtime.
+ *
+ * @param tx - A CredentialAccept Transaction.
+ * @throws When the CredentialAccept is Malformed.
+ */
+export function validateCredentialAccept(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  validateRequiredField(tx, 'Account', isString)
+
+  validateRequiredField(tx, 'Issuer', isString)
+
+  validateCredentialType(tx)
+}

package/src/models/transactions/CredentialCreate.ts

@@ -0,0 +1,81 @@
+import { HEX_REGEX } from '@xrplf/isomorphic/utils'
+
+import { ValidationError } from '../../errors'
+
+import {
+  BaseTransaction,
+  isNumber,
+  isString,
+  validateBaseTransaction,
+  validateCredentialType,
+  validateOptionalField,
+  validateRequiredField,
+} from './common'
+
+const MAX_URI_LENGTH = 256
+
+/**
+ * Creates a Credential object. It must be sent by the issuer.
+ *
+ * @category Transaction Models
+ * */
+export interface CredentialCreate extends BaseTransaction {
+  TransactionType: 'CredentialCreate'
+
+  /** The issuer of the credential. */
+  Account: string
+
+  /** The subject of the credential. */
+  Subject: string
+
+  /** A hex-encoded value to identify the type of credential from the issuer. */
+  CredentialType: string
+
+  /** Credential expiration. */
+  Expiration?: number
+
+  /** Additional data about the credential (such as a link to the VC document). */
+  URI?: string
+}
+
+/**
+ * Verify the form and type of a CredentialCreate at runtime.
+ *
+ * @param tx - A CredentialCreate Transaction.
+ * @throws When the CredentialCreate is Malformed.
+ */
+export function validateCredentialCreate(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  validateRequiredField(tx, 'Account', isString)
+
+  validateRequiredField(tx, 'Subject', isString)
+
+  validateCredentialType(tx)
+
+  validateOptionalField(tx, 'Expiration', isNumber)
+
+  validateURI(tx.URI)
+}
+
+function validateURI(URI: unknown): void {
+  if (URI === undefined) {
+    return
+  }
+
+  if (typeof URI !== 'string') {
+    throw new ValidationError('CredentialCreate: invalid field URI')
+  }
+
+  if (URI.length === 0) {
+    throw new ValidationError('CredentialCreate: URI cannot be an empty string')
+  } else if (URI.length > MAX_URI_LENGTH) {
+    throw new ValidationError(
+      `CredentialCreate: URI length must be <= ${MAX_URI_LENGTH}`,
+    )
+  }
+
+  if (!HEX_REGEX.test(URI)) {
+    throw new ValidationError('CredentialCreate: URI must be encoded in hex')
+  }
+}

package/src/models/transactions/CredentialDelete.ts

@@ -0,0 +1,55 @@
+import { ValidationError } from '../../errors'
+
+import {
+  BaseTransaction,
+  isString,
+  validateBaseTransaction,
+  validateCredentialType,
+  validateOptionalField,
+  validateRequiredField,
+} from './common'
+
+/**
+ * Deletes a Credential object.
+ *
+ * @category Transaction Models
+ * */
+export interface CredentialDelete extends BaseTransaction {
+  TransactionType: 'CredentialDelete'
+
+  /** The transaction submitter. */
+  Account: string
+
+  /** A hex-encoded value to identify the type of credential from the issuer. */
+  CredentialType: string
+
+  /** The person that the credential is for. If omitted, Account is assumed to be the subject. */
+  Subject?: string
+
+  /** The issuer of the credential. If omitted, Account is assumed to be the issuer. */
+  Issuer?: string
+}
+
+/**
+ * Verify the form and type of a CredentialDelete at runtime.
+ *
+ * @param tx - A CredentialDelete Transaction.
+ * @throws When the CredentialDelete is Malformed.
+ */
+export function validateCredentialDelete(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (!tx.Subject && !tx.Issuer) {
+    throw new ValidationError(
+      'CredentialDelete: either `Issuer` or `Subject` must be provided',
+    )
+  }
+
+  validateRequiredField(tx, 'Account', isString)
+
+  validateCredentialType(tx)
+
+  validateOptionalField(tx, 'Subject', isString)
+
+  validateOptionalField(tx, 'Issuer', isString)
+}