xrpl 3.0.0-beta.0 → 3.0.0

package/src/models/ledger/Ledger.ts

@@ -1,8 +1,4 @@
-import {
-  PseudoTransaction,
-  Transaction,
-  TransactionMetadata,
-} from '../transactions'
+import { Transaction, TransactionMetadata } from '../transactions'
 
 import { LedgerEntry } from './LedgerEntry'
 
@@ -65,7 +61,5 @@ export default interface Ledger {
    * either JSON or binary depending on whether the request specified binary
    * as true.
    */
-  transactions?: Array<
-    (Transaction | PseudoTransaction) & { metaData?: TransactionMetadata }
-  >
+  transactions?: Array<Transaction & { metaData?: TransactionMetadata }>
 }

package/src/models/ledger/LedgerEntry.ts

@@ -44,6 +44,7 @@ type LedgerEntryFilter =
   | 'bridge'
   | 'check'
   | 'deposit_preauth'
+  | 'did'
   | 'directory'
   | 'escrow'
   | 'fee'

package/src/models/ledger/index.ts

@@ -7,6 +7,7 @@ import AMM, { VoteSlot } from './AMM'
 import Bridge from './Bridge'
 import Check from './Check'
 import DepositPreauth from './DepositPreauth'
+import DID from './DID'
 import DirectoryNode from './DirectoryNode'
 import Escrow from './Escrow'
 import FeeSettings, {
@@ -39,6 +40,7 @@ export {
   Check,
   DepositPreauth,
   DirectoryNode,
+  DID,
   Escrow,
   FEE_SETTINGS_ID,
   FeeSettings,

package/src/models/methods/index.ts

@@ -114,6 +114,10 @@ import {
   RipplePathFindResponse,
   SourceCurrencyAmount,
 } from './ripplePathFind'
+import {
+  ServerDefinitionsRequest,
+  ServerDefinitionsResponse,
+} from './serverDefinitions'
 import {
   JobType,
   ServerInfoRequest,
@@ -192,6 +196,7 @@ type Request =
   // server info methods
   | FeeRequest
   | ManifestRequest
+  | ServerDefinitionsRequest
   | ServerInfoRequest
   | ServerStateRequest
   // utility methods
@@ -245,6 +250,7 @@ type Response =
   // server info methods
   | FeeResponse
   | ManifestResponse
+  | ServerDefinitionsResponse
   | ServerInfoResponse
   | ServerStateResponse
   // utility methods
@@ -385,6 +391,8 @@ export type RequestResponseMap<T> = T extends AccountChannelsRequest
   ? ServerInfoResponse
   : T extends ServerStateRequest
   ? ServerStateResponse
+  : T extends ServerDefinitionsRequest
+  ? ServerDefinitionsResponse
   : T extends PingRequest
   ? PingResponse
   : T extends RandomRequest
@@ -535,6 +543,8 @@ export {
   FeeResponse,
   ManifestRequest,
   ManifestResponse,
+  ServerDefinitionsRequest,
+  ServerDefinitionsResponse,
   ServerInfoRequest,
   ServerInfoResponse,
   ServerStateRequest,

package/src/models/methods/ledgerEntry.ts

@@ -74,6 +74,12 @@ export interface LedgerEntryRequest extends BaseRequest, LookupByLedgerRequest {
       }
     | string
 
+  /**
+   * Specify a DID object to retrieve. If a string, must be the
+   * object ID of the DID object, as hexadecimal, or the account ID.
+   */
+  did?: string
+
   /**
    * The DirectoryNode to retrieve. If a string, must be the object ID of the
    * directory, as hexadecimal. If an object, requires either `dir_root` o

package/src/models/methods/nftInfo.ts

@@ -16,7 +16,7 @@ export interface NFTInfoRequest extends BaseRequest, LookupByLedgerRequest {
 }
 
 /**
- * Response expected from an {@link NFTInfoResponse}.
+ * Response expected from an {@link NFTInfoRequest}.
  *
  * @category Responses
  */

package/src/models/methods/serverDefinitions.ts

@@ -0,0 +1,61 @@
+import { BaseRequest, BaseResponse } from './baseMethod'
+
+/**
+ * The `server_definitions` method retrieves information about the definition
+ * enums available in this rippled node. Expects a response in the form of a
+ * {@link ServerDefinitionsResponse}.
+ *
+ * @category Requests
+ */
+export interface ServerDefinitionsRequest extends BaseRequest {
+  command: 'server_definitions'
+  /**
+   * The hash of a `server_definitions` response.
+   */
+  hash?: string
+}
+
+/**
+ * Response expected from an {@link ServerDefinitionsRequest}.
+ *
+ * @category Responses
+ */
+export interface ServerDefinitionsResponse extends BaseResponse {
+  result: {
+    hash: string
+  } & (
+    | {
+        FIELDS: Array<
+          [
+            string,
+            {
+              nth: number
+              isVLEncoded: boolean
+              isSerialized: boolean
+              isSigningField: boolean
+              type: string
+            },
+          ]
+        >
+
+        LEDGER_ENTRY_TYPES: Record<string, number>
+
+        TRANSACTION_RESULTS: Record<string, number>
+
+        TRANSACTION_TYPES: Record<string, number>
+
+        TYPES: Record<string, number>
+      }
+    | {
+        FIELDS?: never
+
+        LEDGER_ENTRY_TYPES?: never
+
+        TRANSACTION_RESULTS?: never
+
+        TRANSACTION_TYPES?: never
+
+        TYPES?: never
+      }
+  )
+}

package/src/models/methods/submit.ts

@@ -1,4 +1,4 @@
-import { Transaction } from '../transactions'
+import { SubmittableTransaction } from '../transactions'
 
 import { BaseRequest, BaseResponse } from './baseMethod'
 
@@ -39,7 +39,7 @@ export interface SubmitResponse extends BaseResponse {
     /** The complete transaction in hex string format. */
     tx_blob: string
     /** The complete transaction in JSON format. */
-    tx_json: Transaction & { hash?: string }
+    tx_json: SubmittableTransaction & { hash?: string }
     /**
      * The value true indicates that the transaction was applied, queued,
      * broadcast, or kept for later. The value `false` indicates that none of

package/src/models/methods/subscribe.ts

@@ -39,7 +39,7 @@ export interface SubscribeBook {
 
 /**
  * The subscribe method requests periodic notifications from the server when
- * certain events happen. Expects a response in the form of a.
+ * certain events happen. Expects a response in the form of a
  * {@link SubscribeResponse}.
  *
  * @category Requests

package/src/models/methods/tx.ts

@@ -1,6 +1,5 @@
 import { Transaction, TransactionMetadata } from '../transactions'
 import { BaseTransaction } from '../transactions/common'
-import { PseudoTransaction } from '../transactions/transaction'
 
 import { BaseRequest, BaseResponse } from './baseMethod'
 
@@ -12,8 +11,14 @@ import { BaseRequest, BaseResponse } from './baseMethod'
  */
 export interface TxRequest extends BaseRequest {
   command: 'tx'
-  /** The 256-bit hash of the transaction, as hex. */
-  transaction: string
+  /**
+   * The transaction hash to look up. Exactly one of `transaction` or `ctid` must be specified for a TxRequest.
+   */
+  transaction?: string
+  /**
+   * The Concise Transaction ID to look up. Exactly one of `transaction` or `ctid` must be specified for a TxRequest.
+   */
+  ctid?: string
   /**
    * If true, return transaction data and metadata as binary serialized to
    * hexadecimal strings. If false, return transaction data and metadata as.
@@ -41,12 +46,15 @@ export interface TxRequest extends BaseRequest {
  *
  * @category Responses
  */
-export interface TxResponse<
-  T extends BaseTransaction = Transaction | PseudoTransaction,
-> extends BaseResponse {
+export interface TxResponse<T extends BaseTransaction = Transaction>
+  extends BaseResponse {
   result: {
     /** The SHA-512 hash of the transaction. */
     hash: string
+    /**
+     * The Concise Transaction Identifier of the transaction (16-byte hex string)
+     */
+    ctid?: string
     /** The ledger index of the ledger that includes this transaction. */
     ledger_index?: number
     /** Transaction metadata, which describes the results of the transaction.

package/src/models/transactions/DIDDelete.ts

@@ -0,0 +1,20 @@
+import { BaseTransaction, validateBaseTransaction } from './common'
+
+// TODO: add docs
+
+/**
+ * @category Transaction Models
+ */
+export interface DIDDelete extends BaseTransaction {
+  TransactionType: 'DIDDelete'
+}
+
+/**
+ * Verify the form and type of a DIDDelete at runtime.
+ *
+ * @param tx - A DIDDelete Transaction.
+ * @throws When the DIDDelete is malformed.
+ */
+export function validateDIDDelete(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+}

package/src/models/transactions/DIDSet.ts

@@ -0,0 +1,49 @@
+import { ValidationError } from '../../errors'
+
+import {
+  BaseTransaction,
+  isString,
+  validateBaseTransaction,
+  validateOptionalField,
+} from './common'
+
+// TODO: add docs
+
+/**
+ * @category Transaction Models
+ */
+export interface DIDSet extends BaseTransaction {
+  TransactionType: 'DIDSet'
+
+  Data?: string
+
+  DIDDocument?: string
+
+  URI?: string
+}
+
+/**
+ * Verify the form and type of a DIDSet at runtime.
+ *
+ * @param tx - A DIDSet Transaction.
+ * @throws When the DIDSet is malformed.
+ */
+export function validateDIDSet(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  validateOptionalField(tx, 'Data', isString)
+
+  validateOptionalField(tx, 'DIDDocument', isString)
+
+  validateOptionalField(tx, 'URI', isString)
+
+  if (
+    tx.Data === undefined &&
+    tx.DIDDocument === undefined &&
+    tx.URI === undefined
+  ) {
+    throw new ValidationError(
+      'DIDSet: Must have at least one of `Data`, `DIDDocument`, and `URI`',
+    )
+  }
+}

package/src/models/transactions/XChainAccountCreateCommit.ts

@@ -14,7 +14,7 @@ import {
  * The XChainAccountCreateCommit transaction creates a new account on one of the
  * chains a bridge connects, which serves as the bridge entrance for that chain.
  *
- * Warning: This transaction should only be executed if the witness attestations
+ * WARNING: This transaction should only be executed if the witness attestations
  * will be reliably delivered to the destination chain. If the signatures aren't
  * delivered, then account creation will be blocked until attestations are received.
  * This can be used maliciously; to disable this transaction on XRP-XRP bridges,

package/src/models/transactions/index.ts

@@ -2,6 +2,7 @@ export { BaseTransaction } from './common'
 export {
   validate,
   PseudoTransaction,
+  SubmittableTransaction,
   TransactionAndMetadata,
   Transaction,
 } from './transaction'
@@ -31,6 +32,8 @@ export { CheckCancel } from './checkCancel'
 export { CheckCash } from './checkCash'
 export { CheckCreate } from './checkCreate'
 export { Clawback } from './clawback'
+export { DIDDelete } from './DIDDelete'
+export { DIDSet } from './DIDSet'
 export { DepositPreauth } from './depositPreauth'
 export { EscrowCancel } from './escrowCancel'
 export { EscrowCreate } from './escrowCreate'

package/src/models/transactions/transaction.ts

@@ -20,6 +20,8 @@ import { CheckCreate, validateCheckCreate } from './checkCreate'
 import { Clawback, validateClawback } from './clawback'
 import { BaseTransaction, isIssuedCurrency } from './common'
 import { DepositPreauth, validateDepositPreauth } from './depositPreauth'
+import { DIDDelete, validateDIDDelete } from './DIDDelete'
+import { DIDSet, validateDIDSet } from './DIDSet'
 import { EnableAmendment } from './enableAmendment'
 import { EscrowCancel, validateEscrowCancel } from './escrowCancel'
 import { EscrowCreate, validateEscrowCreate } from './escrowCreate'
@@ -88,21 +90,25 @@ import {
 } from './XChainModifyBridge'
 
 /**
+ * Transactions that can be submitted by clients
+ *
  * @category Transaction Models
  */
-export type Transaction =
-  | AccountDelete
-  | AccountSet
+export type SubmittableTransaction =
   | AMMBid
+  | AMMCreate
   | AMMDelete
   | AMMDeposit
-  | AMMCreate
   | AMMVote
   | AMMWithdraw
+  | AccountDelete
+  | AccountSet
   | CheckCancel
   | CheckCash
   | CheckCreate
   | Clawback
+  | DIDDelete
+  | DIDSet
   | DepositPreauth
   | EscrowCancel
   | EscrowCreate
@@ -122,17 +128,29 @@ export type Transaction =
   | SignerListSet
   | TicketCreate
   | TrustSet
+  | XChainAccountCreateCommit
   | XChainAddAccountCreateAttestation
   | XChainAddClaimAttestation
   | XChainClaim
   | XChainCommit
   | XChainCreateBridge
   | XChainCreateClaimID
-  | XChainAccountCreateCommit
   | XChainModifyBridge
 
+/**
+ * Transactions that can only be created by validators.
+ *
+ * @category Transaction Models
+ */
 export type PseudoTransaction = EnableAmendment | SetFee | UNLModify
 
+/**
+ * All transactions that can live on the XRPL
+ *
+ * @category Transaction Models
+ */
+export type Transaction = SubmittableTransaction | PseudoTransaction
+
 /**
  * @category Transaction Models
  */
@@ -212,18 +230,14 @@ export function validate(transaction: Record<string, unknown>): void {
   // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- okay here
   setTransactionFlagsToNumber(tx as unknown as Transaction)
   switch (tx.TransactionType) {
-    case 'AccountDelete':
-      validateAccountDelete(tx)
-      break
-
-    case 'AccountSet':
-      validateAccountSet(tx)
-      break
-
     case 'AMMBid':
       validateAMMBid(tx)
       break
 
+    case 'AMMCreate':
+      validateAMMCreate(tx)
+      break
+
     case 'AMMDelete':
       validateAMMDelete(tx)
       break
@@ -232,10 +246,6 @@ export function validate(transaction: Record<string, unknown>): void {
       validateAMMDeposit(tx)
       break
 
-    case 'AMMCreate':
-      validateAMMCreate(tx)
-      break
-
     case 'AMMVote':
       validateAMMVote(tx)
       break
@@ -244,6 +254,14 @@ export function validate(transaction: Record<string, unknown>): void {
       validateAMMWithdraw(tx)
       break
 
+    case 'AccountDelete':
+      validateAccountDelete(tx)
+      break
+
+    case 'AccountSet':
+      validateAccountSet(tx)
+      break
+
     case 'CheckCancel':
       validateCheckCancel(tx)
       break
@@ -260,6 +278,14 @@ export function validate(transaction: Record<string, unknown>): void {
       validateClawback(tx)
       break
 
+    case 'DIDDelete':
+      validateDIDDelete(tx)
+      break
+
+    case 'DIDSet':
+      validateDIDSet(tx)
+      break
+
     case 'DepositPreauth':
       validateDepositPreauth(tx)
       break
@@ -336,6 +362,10 @@ export function validate(transaction: Record<string, unknown>): void {
       validateTrustSet(tx)
       break
 
+    case 'XChainAccountCreateCommit':
+      validateXChainAccountCreateCommit(tx)
+      break
+
     case 'XChainAddAccountCreateAttestation':
       validateXChainAddAccountCreateAttestation(tx)
       break
@@ -360,10 +390,6 @@ export function validate(transaction: Record<string, unknown>): void {
       validateXChainCreateClaimID(tx)
       break
 
-    case 'XChainAccountCreateCommit':
-      validateXChainAccountCreateCommit(tx)
-      break
-
     case 'XChainModifyBridge':
       validateXChainModifyBridge(tx)
       break

package/src/sugar/submit.ts

@@ -1,10 +1,16 @@
 import { decode, encode } from 'ripple-binary-codec'
 
-import type { Client, SubmitRequest, SubmitResponse, Wallet } from '..'
+import type {
+  Client,
+  SubmitRequest,
+  SubmitResponse,
+  SubmittableTransaction,
+  Transaction,
+  Wallet,
+} from '..'
 import { ValidationError, XrplError } from '../errors'
 import { Signer } from '../models/common'
 import { TxRequest, TxResponse } from '../models/methods'
-import { Transaction } from '../models/transactions'
 import { BaseTransaction } from '../models/transactions/common'
 
 /** Approximate time for a ledger to close, in milliseconds */
@@ -42,7 +48,7 @@ async function sleep(ms: number): Promise<void> {
  */
 export async function submitRequest(
   client: Client,
-  signedTransaction: Transaction | string,
+  signedTransaction: SubmittableTransaction | string,
   failHard = false,
 ): Promise<SubmitResponse> {
   if (!isSigned(signedTransaction)) {
@@ -104,7 +110,7 @@ export async function submitRequest(
  */
 // eslint-disable-next-line max-params, max-lines-per-function -- this function needs to display and do with more information.
 export async function waitForFinalTransactionOutcome<
-  T extends BaseTransaction = Transaction,
+  T extends BaseTransaction = SubmittableTransaction,
 >(
   client: Client,
   txHash: string,
@@ -159,7 +165,7 @@ export async function waitForFinalTransactionOutcome<
 }
 
 // checks if the transaction has been signed
-function isSigned(transaction: Transaction | string): boolean {
+function isSigned(transaction: SubmittableTransaction | string): boolean {
   const tx = typeof transaction === 'string' ? decode(transaction) : transaction
   if (typeof tx === 'string') {
     return false
@@ -218,7 +224,7 @@ function isSigned(transaction: Transaction | string): boolean {
  */
 export async function getSignedTx(
   client: Client,
-  transaction: Transaction | string,
+  transaction: SubmittableTransaction | string,
   {
     autofill = true,
     wallet,
@@ -228,7 +234,7 @@ export async function getSignedTx(
     // A wallet to sign a transaction. It must be provided when submitting an unsigned transaction.
     wallet?: Wallet
   } = {},
-): Promise<Transaction | string> {
+): Promise<SubmittableTransaction | string> {
   if (isSigned(transaction)) {
     return transaction
   }
@@ -242,7 +248,7 @@ export async function getSignedTx(
   let tx =
     typeof transaction === 'string'
       ? // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- converts JsonObject to correct Transaction type
-        (decode(transaction) as unknown as Transaction)
+        (decode(transaction) as unknown as SubmittableTransaction)
       : transaction
 
   if (autofill) {

package/src/utils/collections.ts

@@ -14,20 +14,24 @@ type ValueOf<T> = T[keyof T]
  */
 export function groupBy<T>(
   array: T[],
-  iteratee: (value: T, index: number, array: T[]) => string,
-): { [p: string]: T[] } {
+  iteratee: (value: T, index: number, array: T[]) => string | number,
+): Record<string | number, T[]> {
   // eslint-disable-next-line max-params -- need all the params for the fallback
-  return array.reduce<{ [key: string]: T[] }>(function predicate(
-    acc,
-    value,
-    index,
-    arrayReference,
-  ) {
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- being safe for js users
-    ;(acc[iteratee(value, index, arrayReference)] ||= []).push(value)
+  function predicate(
+    acc: Record<string | number, T[]>,
+    value: T,
+    index: number,
+    arrayReference: T[],
+  ): Record<string | number, T[]> {
+    const key = iteratee(value, index, arrayReference) || 0
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- Find existing group or create a new one
+    const group = acc[key] || []
+    group.push(value)
+    acc[key] = group
     return acc
-  },
-  {})
+  }
+
+  return array.reduce(predicate, {})
 }
 
 /**

package/src/utils/hashes/hashLedger.ts

@@ -3,6 +3,7 @@
 /* eslint-disable no-bitwise  -- this file mimics behavior in rippled. It uses
    bitwise operators for and-ing numbers with a mask and bit shifting. */
 
+import { bytesToHex } from '@xrplf/isomorphic/utils'
 import BigNumber from 'bignumber.js'
 import { decode, encode } from 'ripple-binary-codec'
 
@@ -10,7 +11,6 @@ import { ValidationError, XrplError } from '../../errors'
 import type { Ledger } from '../../models/ledger'
 import { LedgerEntry } from '../../models/ledger'
 import { Transaction, TransactionMetadata } from '../../models/transactions'
-import { PseudoTransaction } from '../../models/transactions/transaction'
 
 import HashPrefix from './HashPrefix'
 import sha512Half from './sha512Half'
@@ -30,10 +30,6 @@ function intToHex(integer: number, byteLength: number): string {
   return foo
 }
 
-function bytesToHex(bytes: number[]): string {
-  return Buffer.from(bytes).toString('hex')
-}
-
 function bigintToHex(
   integerString: string | number | BigNumber,
   byteLength: number,
@@ -84,7 +80,11 @@ export function hashSignedTx(tx: Transaction | string): string {
     txObject = tx
   }
 
-  if (txObject.TxnSignature === undefined && txObject.Signers === undefined) {
+  if (
+    txObject.TxnSignature === undefined &&
+    txObject.Signers === undefined &&
+    txObject.SigningPubKey === undefined
+  ) {
     throw new ValidationError('The transaction must be signed to hash it.')
   }
 
@@ -125,9 +125,7 @@ export function hashLedgerHeader(ledgerHeader: Ledger): string {
  * @category Utilities
  */
 export function hashTxTree(
-  transactions: Array<
-    (Transaction | PseudoTransaction) & { metaData?: TransactionMetadata }
-  >,
+  transactions: Array<Transaction & { metaData?: TransactionMetadata }>,
 ): string {
   const shamap = new SHAMap()
   for (const txJSON of transactions) {

package/src/utils/hashes/index.ts

@@ -3,6 +3,7 @@
 /* eslint-disable no-bitwise  -- this file mimics behavior in rippled. It uses
    bitwise operators for and-ing numbers with a mask and bit shifting. */
 
+import { bytesToHex } from '@xrplf/isomorphic/utils'
 import BigNumber from 'bignumber.js'
 import { decodeAccountID } from 'ripple-address-codec'
 
@@ -20,7 +21,7 @@ const HEX = 16
 const BYTE_LENGTH = 4
 
 function addressToHex(address: string): string {
-  return Buffer.from(decodeAccountID(address)).toString('hex')
+  return bytesToHex(decodeAccountID(address))
 }
 
 function ledgerSpaceHex(name: keyof typeof ledgerSpaces): string {
@@ -37,7 +38,7 @@ function currencyToHex(currency: string): string {
   bytes[12] = currency.charCodeAt(0) & MASK
   bytes[13] = currency.charCodeAt(1) & MASK
   bytes[14] = currency.charCodeAt(2) & MASK
-  return Buffer.from(bytes).toString('hex')
+  return bytesToHex(Uint8Array.from(bytes))
 }
 
 /**