feat(xrpl): custom definitions support

packages/ripple-binary-codec/README.md

@@ -10,8 +10,8 @@ Functions to encode/decode to/from the ripple [binary serialization format](http
 ```
 
 
-### decode(binary: string): object
-Decode a hex-string into a transaction object.
+### decode(binary: string, definitions?: XrplDefinitionsBase): object
+Decode a hex-string into a transaction object. Optionally, a custom definition may be provided and utilized during the decoding process
 ```js
 > api.decode('1100612200000000240000000125000000072D0000000055DF530FB14C5304852F20080B0A8EEF3A6BDD044F41F4EBBD68B8B321145FE4FF6240000002540BE4008114D0F5430B66E06498D4CEEC816C7B3337F9982337')
 {
@@ -26,8 +26,8 @@ Decode a hex-string into a transaction object.
 }
 ```
 
-### encode(json: object): string
-Encode a transaction object into a hex-string. Note that encode filters out fields with undefined values.
+### encode(json: object, definitions?: XrplDefinitionsBase): string
+Encode a transaction object into a hex-string. Note that encode filters out fields with undefined values. Optionally, a custom definition may be provided and utilized during the encoding process
 ```js
 > api.encode({
   LedgerEntryType: 'AccountRoot',
@@ -37,12 +37,12 @@ Encode a transaction object into a hex-string. Note that encode filters out fiel
   OwnerCount: 0,
   PreviousTxnID: 'DF530FB14C5304852F20080B0A8EEF3A6BDD044F41F4EBBD68B8B321145FE4FF',
   Balance: '10000000000',
-  Account: 'rLs1MzkFWCxTbuAHgjeTZK4fcCDDnf2KRv' 
+  Account: 'rLs1MzkFWCxTbuAHgjeTZK4fcCDDnf2KRv'
 })
 '1100612200000000240000000125000000072D0000000055DF530FB14C5304852F20080B0A8EEF3A6BDD044F41F4EBBD68B8B321145FE4FF6240000002540BE4008114D0F5430B66E06498D4CEEC816C7B3337F9982337'
 ```
 
-#### X-Address Compatibility 
+#### X-Address Compatibility
   * ripple-binary-codec handles X-addresses by looking for a few specific files (Account/SourceTag, Destination/DestinationTag).
   * If other fields (in the future) must to support X-addresses with tags, this library will need to be updated.
   * When decoding rippled binary, the output will always output classic address + tag, with no X-addresses. X-address support only applies when encoding to binary.
@@ -54,25 +54,25 @@ Encode a transaction object into a hex-string. Note that encode filters out fiel
   * When _decoding_, if a currency code is three uppercase letters or numbers (`/^[A-Z0-9]{3}$/`), then it will be decoded into that string. For example,`0000000000000000000000004142430000000000` decodes as `ABC`.
   * When decoding, if a currency code is does not match the regex, then it is not considered to be an ISO 4217 or pseudo-ISO currency. ripple-binary-codec will return a 160-bit hex-string (40 hex characters). For example, `0000000000000000000000006142430000000000` (`aBC`) decodes as `0000000000000000000000006142430000000000` because it contains a lowercase letter.
 
-### encodeForSigning(json: object): string
+### encodeForSigning(json: object, definitions?: XrplDefinitionsBase): string
 
-Encode the transaction object for signing.
+Encode the transaction object for signing. Optionally, a custom definition may be provided and utilized during the encoding process
 
 ### encodeForSigningClaim(json: object): string
 
 Encode the transaction object for payment channel claim.
 
-### encodeForMultisigning(json: object, signer: string): string
+### encodeForMultisigning(json: object, signer: string, definitions?: XrplDefinitionsBase): string
 
-Encode the transaction object for multi-signing.
+Encode the transaction object for multi-signing. Optionally, a custom definition may be provided and utilized during the encoding process
 
 ### encodeQuality(value: string): string
 ```js
 > api.encodeQuality('195796912.5171664')
 '5D06F4C3362FE1D0'
 ```
 
-### decodeQuality(value: string): string 
+### decodeQuality(value: string): string
 ```js
 > api.decodeQuality('5D06F4C3362FE1D0')
 '195796912.5171664'

packages/xrpl/HISTORY.md

@@ -10,6 +10,8 @@ Subscribe to [the **xrpl-announce** mailing list](https://groups.google.com/g/xr
 
 ### Added
 * Add new fields to `ServerDefinitionsResponse`: `ACCOUNT_SET_FLAGS`, `LEDGER_ENTRY_FLAGS`, `LEDGER_ENTRY_FORMATS`, `TRANSACTION_FLAGS`, and `TRANSACTION_FORMATS`, reflecting new sections returned by `server_definitions` in rippled.
+* Adds support for Custom Definitions to `client.submit()` and `client.submitAndWait()`
+* Custom definitions support for `util.encode`, `util.decode`, `util.encodeForSigning` and `Wallet.sign`.
 
 ### Fixed
 * Fix event listener accumulation bug where `'connected'` event handlers would fire multiple times after each reconnection. The fix cleans up stale listeners from previous reconnect attempts to prevent duplicate event emissions on flaky connections with multiple sequential reconnect attempts.

packages/xrpl/src/Wallet/index.ts

@@ -4,7 +4,7 @@ import { wordlist } from '@scure/bip39/wordlists/english.js'
 import { bytesToHex } from '@xrplf/isomorphic/utils'
 import BigNumber from 'bignumber.js'
 import { classicAddressToXAddress, encodeSeed } from 'ripple-address-codec'
-import { encode } from 'ripple-binary-codec'
+import { encode, XrplDefinitionsBase } from 'ripple-binary-codec'
 import { deriveAddress, deriveKeypair, generateSeed } from 'ripple-keypairs'
 
 import ECDSA from '../ECDSA'
@@ -356,15 +356,17 @@ export class Wallet {
    * @param transaction - A transaction to be signed offline.
    * @param multisign - Specify true/false to use multisign or actual address (classic/x-address) to make multisign tx request.
    *                    The actual address is only needed in the case of regular key usage.
+   * @param definitions Custom rippled types to use instead of the default. Used for sidechains and amendments.
    * @returns A signed transaction.
    * @throws ValidationError if the transaction is already signed or does not encode/decode to same result.
    * @throws XrplError if the issued currency being signed is XRP ignoring case.
    */
-  // eslint-disable-next-line max-lines-per-function -- introduced more checks to support both string and boolean inputs.
+  // eslint-disable-next-line max-lines-per-function, max-params -- introduced more checks to support string and boolean inputs.
   public sign(
     this: Wallet,
     transaction: Transaction,
     multisign?: boolean | string,
+    definitions?: XrplDefinitionsBase,
   ): {
     tx_blob: string
     hash: string
@@ -395,7 +397,7 @@ export class Wallet {
      * This will throw a more clear error for JS users if the supplied transaction has incorrect formatting
      */
     // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- validate does not accept Transaction type
-    validate(tx as unknown as Record<string, unknown>)
+    validate(tx as unknown as Record<string, unknown>, definitions)
     if (hasFlag(tx, GlobalFlags.tfInnerBatchTxn, 'tfInnerBatchTxn')) {
       throw new ValidationError('Cannot sign a Batch inner transaction.')
     }
@@ -411,6 +413,7 @@ export class Wallet {
           txToSignAndEncode,
           this.privateKey,
           multisignAddress,
+          definitions,
         ),
       }
       txToSignAndEncode.Signers = [{ Signer: signer }]
@@ -419,13 +422,16 @@ export class Wallet {
       txToSignAndEncode.TxnSignature = computeSignature(
         txToSignAndEncode,
         this.privateKey,
+        undefined,
+        definitions,
       )
     }
 
-    const serialized = encode(txToSignAndEncode)
+    const serialized = encode(txToSignAndEncode, definitions)
+
     return {
       tx_blob: serialized,
-      hash: hashSignedTx(serialized),
+      hash: hashSignedTx(serialized, definitions),
     }
   }
 

packages/xrpl/src/Wallet/utils.ts

@@ -10,6 +10,7 @@ import {
   encode,
   encodeForMultisigning,
   encodeForSigning,
+  XrplDefinitionsBase,
 } from 'ripple-binary-codec'
 import { sign } from 'ripple-keypairs'
 
@@ -61,20 +62,25 @@ export function addressToBigNumber(address: string): BigNumber {
  * Decodes a transaction or transaction blob into a Transaction object.
  *
  * @param txOrBlob - A Transaction object or a hex string representing a transaction blob.
+ * @param definitions - Custom rippled types to use instead of the default. Used for sidechains and amendments.
  * @returns A Transaction object.
  * @throws If the input is not a valid Transaction or transaction blob.
  */
 export function getDecodedTransaction(
   txOrBlob: Transaction | string,
+  definitions?: XrplDefinitionsBase,
 ): Transaction {
   if (typeof txOrBlob === 'object') {
     // We need this to handle X-addresses in multisigning
     // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- We are casting here to get strong typing
-    return decode(encode(txOrBlob)) as unknown as Transaction
+    return decode(
+      encode(txOrBlob, definitions),
+      definitions,
+    ) as unknown as Transaction
   }
 
   // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- We are casting here to get strong typing
-  return decode(txOrBlob) as unknown as Transaction
+  return decode(txOrBlob, definitions) as unknown as Transaction
 }
 
 /**
@@ -84,19 +90,25 @@ export function getDecodedTransaction(
  * @param privateKey - A key to sign the transaction with.
  * @param signAs - Multisign only. An account address to include in the Signer field.
  * Can be either a classic address or an XAddress.
+ * @param definitions Custom rippled types to use instead of the default. Used for sidechains and amendments.
  * @returns A signed transaction in the proper format.
  */
+// eslint-disable-next-line max-params -- Needs 4 params
 export function computeSignature(
   tx: Transaction,
   privateKey: string,
   signAs?: string,
+  definitions?: XrplDefinitionsBase,
 ): string {
   if (signAs) {
     const classicAddress = isValidXAddress(signAs)
       ? xAddressToClassicAddress(signAs).classicAddress
       : signAs
 
-    return sign(encodeForMultisigning(tx, classicAddress), privateKey)
+    return sign(
+      encodeForMultisigning(tx, classicAddress, definitions),
+      privateKey,
+    )
   }
-  return sign(encodeForSigning(tx), privateKey)
+  return sign(encodeForSigning(tx, definitions), privateKey)
 }

packages/xrpl/src/client/index.ts

@@ -2,6 +2,8 @@
 
 /* eslint-disable max-lines -- Client is a large file w/ lots of imports/exports */
 import { EventEmitter } from 'eventemitter3'
+import { XrplDefinitions, XrplDefinitionsBase } from 'ripple-binary-codec'
+import type { DefinitionsData } from 'ripple-binary-codec/dist/enums/xrpl-definitions-base'
 
 import {
   RippledError,
@@ -225,6 +227,12 @@ class Client extends EventEmitter<EventTypes> {
    */
   public buildVersion: string | undefined
 
+  /**
+   * Custom rippled types to use instead of the default. Used for sidechains and amendments.
+   *
+   */
+  public definitions: XrplDefinitionsBase | undefined
+
   /**
    * API Version used by the server this client is connected to
    *
@@ -642,6 +650,14 @@ class Client extends EventEmitter<EventTypes> {
     return this.connection.isConnected()
   }
 
+  public async getDefinitions(): Promise<void> {
+    const response = await this.request({
+      command: 'server_definitions',
+    })
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- response.result is the DefinitionsData
+    this.definitions = new XrplDefinitions(response.result as DefinitionsData)
+  }
+
   /**
    * Autofills fields in a transaction. This will set `Sequence`, `Fee`,
    * `lastLedgerSequence` according to the current state of the server this Client
@@ -801,8 +817,11 @@ class Client extends EventEmitter<EventTypes> {
       wallet?: Wallet
     },
   ): Promise<SubmitResponse> {
-    const signedTx = await getSignedTx(this, transaction, opts)
-    return submitRequest(this, signedTx, opts?.failHard)
+    const signedTx = await getSignedTx(this, transaction, {
+      ...opts,
+      definitions: this.definitions,
+    })
+    return submitRequest(this, signedTx, opts?.failHard, this.definitions)
   }
 
   /**
@@ -875,7 +894,10 @@ class Client extends EventEmitter<EventTypes> {
       wallet?: Wallet
     },
   ): Promise<TxResponse<T>> {
-    const signedTx = await getSignedTx(this, transaction, opts)
+    const signedTx = await getSignedTx(this, transaction, {
+      ...opts,
+      definitions: this.definitions,
+    })
 
     const lastLedger = getLastLedgerSequence(signedTx)
     if (lastLedger == null) {

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

@@ -1,7 +1,7 @@
 /* eslint-disable max-lines -- common utility file */
 import { HEX_REGEX } from '@xrplf/isomorphic/utils'
 import { isValidClassicAddress, isValidXAddress } from 'ripple-address-codec'
-import { TRANSACTION_TYPES } from 'ripple-binary-codec'
+import { DEFAULT_DEFINITIONS, XrplDefinitionsBase } from 'ripple-binary-codec'
 
 import { ValidationError } from '../../errors'
 import {
@@ -542,11 +542,13 @@ export interface BaseTransaction extends Record<string, unknown> {
  * any time a transaction will be verified.
  *
  * @param common - An interface w/ common transaction fields.
+ * @param definitions - Custom rippled types to use instead of the default. Used for sidechains and amendments.
  * @throws When the common param is malformed.
  */
 // eslint-disable-next-line max-statements, max-lines-per-function -- lines required for validation
 export function validateBaseTransaction(
   common: unknown,
+  definitions: XrplDefinitionsBase = DEFAULT_DEFINITIONS,
 ): asserts common is BaseTransaction {
   if (!isRecord(common)) {
     throw new ValidationError(
@@ -562,7 +564,7 @@ export function validateBaseTransaction(
     throw new ValidationError('BaseTransaction: TransactionType not string')
   }
 
-  if (!TRANSACTION_TYPES.includes(common.TransactionType)) {
+  if (!definitions.transactionNames.includes(common.TransactionType)) {
     throw new ValidationError(
       `BaseTransaction: Unknown TransactionType ${common.TransactionType}`,
     )

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

@@ -1,6 +1,8 @@
 /* eslint-disable max-lines -- need to work with a lot of transactions in a switch statement */
 /* eslint-disable max-lines-per-function -- need to work with a lot of Tx verifications */
 
+import { XrplDefinitionsBase } from 'ripple-binary-codec'
+
 import { ValidationError } from '../../errors'
 import { convertTxFlagsToNumber } from '../utils/flags'
 
@@ -252,14 +254,18 @@ export interface TransactionAndMetadata<
  * Encode/decode and individual type validation.
  *
  * @param transaction - A Transaction.
+ * @param customDefinitions - Optional parameter to validate against a custom definition.
  * @throws ValidationError When the Transaction is malformed.
  * @category Utilities
  */
-export function validate(transaction: Record<string, unknown>): void {
+export function validate(
+  transaction: Record<string, unknown>,
+  customDefinitions?: XrplDefinitionsBase,
+): void {
   const tx = { ...transaction }
 
   // should already be done in the tx-specific validation, but doesn't hurt to check again
-  validateBaseTransaction(tx)
+  validateBaseTransaction(tx, customDefinitions)
 
   Object.keys(tx).forEach((key) => {
     const standard_currency_code_len = 3
@@ -325,8 +331,11 @@ export function validate(transaction: Record<string, unknown>): void {
       // @ts-expect-error -- already checked
       // eslint-disable-next-line @typescript-eslint/no-unsafe-call -- already checked above
       tx.RawTransactions.forEach((innerTx: Record<string, unknown>) => {
-        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- already checked above
-        validate(innerTx.RawTransaction as Record<string, unknown>)
+        validate(
+          // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- already checked above
+          innerTx.RawTransaction as Record<string, unknown>,
+          customDefinitions,
+        )
       })
       break
 
@@ -575,8 +584,10 @@ export function validate(transaction: Record<string, unknown>): void {
       break
 
     default:
-      throw new ValidationError(
-        `Invalid field TransactionType: ${tx.TransactionType}`,
-      )
+      if (!customDefinitions?.transactionNames.includes(tx.TransactionType)) {
+        throw new ValidationError(
+          `Invalid field TransactionType: ${tx.TransactionType}`,
+        )
+      }
   }
 }