feat(xrpl): custom definitions support

packages/ripple-binary-codec/README.md

@@ -10,7 +10,7 @@ Functions to encode/decode to/from the ripple [binary serialization format](http
 ```
 
 
-### decode(binary: string): object
+### decode(binary: string, definitions?: XrplDefinitionsBase): object
 Decode a hex-string into a transaction object.
 ```js
 > api.decode('1100612200000000240000000125000000072D0000000055DF530FB14C5304852F20080B0A8EEF3A6BDD044F41F4EBBD68B8B321145FE4FF6240000002540BE4008114D0F5430B66E06498D4CEEC816C7B3337F9982337')
@@ -26,7 +26,7 @@ Decode a hex-string into a transaction object.
 }
 ```
 
-### encode(json: object): string
+### encode(json: object, definitions?: XrplDefinitionsBase): string
 Encode a transaction object into a hex-string. Note that encode filters out fields with undefined values.
 ```js
 > api.encode({
@@ -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,15 +54,15 @@ 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.
 
 ### 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.
 
@@ -72,7 +72,7 @@ Encode the transaction object for multi-signing.
 '5D06F4C3362FE1D0'
 ```
 
-### decodeQuality(value: string): string 
+### decodeQuality(value: string): string
 ```js
 > api.decodeQuality('5D06F4C3362FE1D0')
 '195796912.5171664'

packages/xrpl/HISTORY.md

@@ -38,6 +38,9 @@ Subscribe to [the **xrpl-announce** mailing list](https://groups.google.com/g/xr
 * Add missing `lsfAMMNode` flag to `RippleState` ledger object
 * Add `PreviousFields` to `DeletedNode` metadata type
 
+### Added
+* Custom definitions support for `util.encode`, `util.decode`, `util.encodeForSignning` and `Wallet.sign`.
+
 ## 3.0.0 (2024-02-01)
 
 ### BREAKING CHANGES

packages/xrpl/src/Wallet/index.ts

@@ -13,6 +13,7 @@ import {
   encodeForSigning,
   encodeForMultisigning,
   encode,
+  XrplDefinitionsBase,
 } from 'ripple-binary-codec'
 import {
   deriveAddress,
@@ -367,15 +368,17 @@ export class Wallet {
    * @param this - Wallet instance.
    * @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.
+   * @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
@@ -406,7 +409,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)
 
     const txToSignAndEncode = { ...tx }
 
@@ -420,20 +423,24 @@ export class Wallet {
           txToSignAndEncode,
           this.privateKey,
           multisignAddress,
+          definitions,
         ),
       }
       txToSignAndEncode.Signers = [{ Signer: signer }]
     } else {
       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),
     }
   }
 
@@ -466,22 +473,28 @@ export class Wallet {
  * @param tx - A transaction to sign.
  * @param privateKey - A key to sign the transaction with.
  * @param signAs - Multisign only. An account address to include in the Signer field.
+ * @param definitions Custom rippled types to use instead of the default. Used for sidechains and amendments.
  * Can be either a classic address or an XAddress.
  * @returns A signed transaction in the proper format.
  */
+// eslint-disable-next-line max-params -- Needs 4 params
 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,7 @@
 
 /* eslint-disable max-lines -- Client is a large file w/ lots of imports/exports */
 import { EventEmitter } from 'eventemitter3'
+import { XrplDefinitionsBase } from 'ripple-binary-codec'
 
 import {
   RippledError,
@@ -218,6 +219,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
    *
@@ -526,6 +533,33 @@ class Client extends EventEmitter<EventTypes> {
     }
   }
 
+  /**
+   * Get Definitions from server_definitions
+   *
+   * @returns void
+   * @example
+   * ```ts
+   * const { Client } = require('xrpl')
+   * const client = new Client('wss://s.altnet.rippletest.net:51233')
+   * await client.getDefinitions()
+   * console.log(client.definitions)
+   * ```
+   */
+  public async getDefinitions(): Promise<void> {
+    try {
+      const response = await this.request({
+        command: 'server_definitions',
+      })
+      this.definitions = new XrplDefinitionsBase(
+        JSON.parse(JSON.stringify(response.result)),
+        {},
+      )
+    } catch (error) {
+      // eslint-disable-next-line no-console -- Print the error to console but allows client to be connected.
+      console.error(error)
+    }
+  }
+
   /**
    * Tells the Client instance to connect to its rippled server.
    *
@@ -760,7 +794,10 @@ class Client extends EventEmitter<EventTypes> {
       wallet?: Wallet
     },
   ): Promise<SubmitResponse> {
-    const signedTx = await getSignedTx(this, transaction, opts)
+    const signedTx = await getSignedTx(this, transaction, {
+      ...opts,
+      definitions: this.definitions,
+    })
     return submitRequest(this, signedTx, opts?.failHard)
   }
 
@@ -834,7 +871,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,5 +1,5 @@
 import { isValidClassicAddress, isValidXAddress } from 'ripple-address-codec'
-import { TRANSACTION_TYPES } from 'ripple-binary-codec'
+import { TRANSACTION_TYPES, XrplDefinitionsBase } from 'ripple-binary-codec'
 
 import { ValidationError } from '../../errors'
 import {
@@ -351,6 +351,30 @@ export function validateBaseTransaction(common: Record<string, unknown>): void {
   validateOptionalField(common, 'NetworkID', isNumber)
 }
 
+/**
+ * Validate that the passed transaction is a valid type against the types provided by the custom definitions.
+ *
+ * @param tx - A Transaction.
+ * @param definitions - Custom definitions
+ * @throws When the passed transaction type is not found in the definitions.
+ */
+export function validateTxAgainstCustomDefintions(
+  tx: Record<string, unknown>,
+  definitions: XrplDefinitionsBase,
+): void {
+  // Validate just transaction type for now, leaving it open for further validations against the custom definition spec.
+  const txType = tx.TransactionType
+  if (typeof txType !== 'string') {
+    throw new ValidationError(
+      'TransactionType field is not specified or not a string',
+    )
+  }
+
+  if (!definitions.transactionType[txType]) {
+    throw new ValidationError(`Invalid transaction type: ${txType}`)
+  }
+}
+
 /**
  * Parse the value of an amount, expressed either in XRP or as an Issued Currency, into a number.
  *

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 { IssuedCurrencyAmount, Memo } from '../common'
 import { isHex } from '../utils'
@@ -18,7 +20,11 @@ import { CheckCancel, validateCheckCancel } from './checkCancel'
 import { CheckCash, validateCheckCash } from './checkCash'
 import { CheckCreate, validateCheckCreate } from './checkCreate'
 import { Clawback, validateClawback } from './clawback'
-import { BaseTransaction, isIssuedCurrency } from './common'
+import {
+  BaseTransaction,
+  isIssuedCurrency,
+  validateTxAgainstCustomDefintions,
+} from './common'
 import { DepositPreauth, validateDepositPreauth } from './depositPreauth'
 import { DIDDelete, validateDIDDelete } from './DIDDelete'
 import { DIDSet, validateDIDSet } from './DIDSet'
@@ -170,10 +176,14 @@ 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 }
   if (tx.TransactionType == null) {
     throw new ValidationError('Object does not have a `TransactionType`')
@@ -407,8 +417,12 @@ export function validate(transaction: Record<string, unknown>): void {
       break
 
     default:
-      throw new ValidationError(
-        `Invalid field TransactionType: ${tx.TransactionType}`,
-      )
+      if (customDefinitions) {
+        validateTxAgainstCustomDefintions(tx, customDefinitions)
+      } else {
+        throw new ValidationError(
+          `Invalid field TransactionType: ${tx.TransactionType}`,
+        )
+      }
   }
 }