feat: add support for Batch amendment (#2801)

* improve scripts

* Update settings.json

* update file locations after refactor

* add LedgerStateFix

* add Batch

* add BatchTxn autofill

* add multi-account signing

* add combine function

* add Batch support to hashing txs

* add autofill TxID support

* better validation

* add metadata

* update definitions.json

* clean up

* update binary codec for signing

* add Batchnet faucet

* get basic tests working

* add rbc tests

* add autofill tests

* add signMultiBatch tests

* refactor

* add basic tests for combineBatchSigners

* handle more edge cases

* better error validation

* rename

* update history

* fix import

* add more validation

* remove BatchTxn, fix autofill

* replace BatchTxn in some more places, fix tests

* fix linter issues

* update definitions

* Batch integration test

* remove debug statement

* fix TxnSignature

* fix BatchMetadata

* fix tests

* more updates

* remove TransactionIDs

* add more tests

* remove LedgerStateFix

* fix build issues

* uncomment now-passing test

* fix linter

* drive-by multisign fix

* add more tests

* better docstrings

* redo definitions.json

* fix error

* minor cleanup

* update vscode settings

* fix linter

* fix history

* fix tests

* fix build issue

* bump versions for beta

* update packagelock

* update package-lock

* back out unrelated changes

* more backing out

* rename test file

* update tfInnerBatchTxn handling

* respond to comments

* fix coderabbit issues

* improve type-checking

* fix errors

* fix errors

* fix autofill

* fix ts issues

* more fixes

* more fixes

* respond to comments

* disable

* update definitions

* add Batch to the list of non delegatable transactions

* fix definitions, update amendments in config

* fix test

* I tried to be too smart for my own good

* more flag tests

* roll back beta version changes

* clean up batchSigner file

* fix imports

* fix test

* fix 4 real

* roll back some typing changes

* remove faucet

* respond to comments

* respond to comments

* fix tests

* fix dependency cycle

* fix imports

* add address info

* fix browser tests

* respond to comments

* improve multisig fee calculations

* fix test

* address comment

Author: mvadari

.ci-config/rippled.cfg

@@ -173,18 +173,23 @@ fixPreviousTxnID
 fixAMMv1_1
 # 2.3.0 Amendments
 AMMClawback
-fixAMMv1_2
 Credentials
 NFTokenMintOffer
 MPTokensV1
+fixAMMv1_2
 fixNFTokenPageLinks
 fixInnerObjTemplate2
 fixEnforceNFTokenTrustline
 fixReducedOffersV2
+# 2.4.0 Amendments
 DeepFreeze
 DynamicNFT
 PermissionedDomains
+fixFrozenLPTokenTransfer
+fixInvalidTxFlags
+# 2.5.0 Amendments
 PermissionDelegation
+Batch
 
 # This section can be used to simulate various FeeSettings scenarios for rippled node in standalone mode
 [voting]

.vscode/settings.json

@@ -2,11 +2,13 @@
     "editor.tabSize": 2,
     "cSpell.words": [
         "altnet",
-        "Autofills",
+        "autofills",
+        "bignumber",
         "Clawback",
         "hostid",
         "keypair",
         "keypairs",
+        "MPToken",
         "multisign",
         "multisigned",
         "multisigning",
@@ -16,7 +18,8 @@
         "secp256k1",
         "Setf",
         "Sidechains",
-        "xchain"
+        "xchain",
+        "xrplf"
     ],
     "[javascript]": {
         "editor.defaultFormatter": "esbenp.prettier-vscode",

packages/ripple-binary-codec/HISTORY.md

@@ -3,7 +3,8 @@
 ## Unreleased
 
 ### Added
-* Support for `Account Permissions` and `Account Permission Delegation` (XLS-74d, XLS-75d)
+* Support for `Account Permissions` and `Account Permission Delegation` (XLS-74d, XLS-75d).
+* Support for the `Batch` amendment (XLS-56).
 
 ### Fixed
 * add `MPTCurrency` support in `Issue` (rippled internal type)
@@ -18,7 +19,7 @@
 ## 2.2.0 (2024-12-23)
 
 ### Added
-* Support for the Multi-Purpose Token amendment (XLS-33)
+* Support for the Multi-Purpose Token amendment (XLS-33).
 
 ## 2.1.0 (2024-06-03)
 

packages/ripple-binary-codec/src/binary.ts

@@ -177,11 +177,51 @@ function multiSigningData(
   })
 }
 
+/**
+ * Interface describing fields required for a Batch signer
+ * @property flags - Flags indicating Batch transaction properties
+ * @property txIDs - Array of transaction IDs included in the Batch
+ */
+interface BatchObject extends JsonObject {
+  flags: number
+  txIDs: string[]
+}
+
+/**
+ * Serialize a signingClaim
+ *
+ * @param batch A Batch object to serialize.
+ * @returns the serialized object with appropriate prefix
+ */
+function signingBatchData(batch: BatchObject): Uint8Array {
+  if (batch.flags == null) {
+    throw Error("No field `flags'")
+  }
+  if (batch.txIDs == null) {
+    throw Error('No field `txIDs`')
+  }
+  const prefix = HashPrefix.batch
+  const flags = coreTypes.UInt32.from(batch.flags).toBytes()
+  const txIDsLength = coreTypes.UInt32.from(batch.txIDs.length).toBytes()
+
+  const bytesList = new BytesList()
+
+  bytesList.put(prefix)
+  bytesList.put(flags)
+  bytesList.put(txIDsLength)
+  batch.txIDs.forEach((txID: string) => {
+    bytesList.put(coreTypes.Hash256.from(txID).toBytes())
+  })
+
+  return bytesList.toBytes()
+}
+
 export {
   BinaryParser,
   BinarySerializer,
   BytesList,
   ClaimObject,
+  BatchObject,
   makeParser,
   serializeObject,
   readJSON,
@@ -191,4 +231,5 @@ export {
   binaryToJSON,
   sha512Half,
   transactionID,
+  signingBatchData,
 }

packages/ripple-binary-codec/src/hash-prefixes.ts

@@ -35,6 +35,8 @@ const HashPrefix: Record<string, Uint8Array> = {
   proposal: bytes(0x50525000),
   // payment channel claim
   paymentChannelClaim: bytes(0x434c4d00),
+  // batch
+  batch: bytes(0x42434800),
 }
 
 export { HashPrefix }

packages/ripple-binary-codec/src/index.ts

@@ -1,6 +1,6 @@
 import { quality, binary, HashPrefix } from './coretypes'
 import { decodeLedgerData } from './ledger-hashes'
-import { ClaimObject } from './binary'
+import { ClaimObject, BatchObject } from './binary'
 import { JsonObject } from './types/serialized-type'
 import {
   XrplDefinitionsBase,
@@ -15,6 +15,7 @@ const {
   signingData,
   signingClaimData,
   multiSigningData,
+  signingBatchData,
   binaryToJSON,
   serializeObject,
 } = binary
@@ -71,12 +72,10 @@ function encodeForSigning(
 }
 
 /**
- * Encode a transaction and prepare for signing with a claim
+ * Encode a payment channel claim for signing.
  *
- * @param json JSON object representing the transaction
- * @param signer string representing the account to sign the transaction with
- * @param definitions Custom rippled types to use instead of the default. Used for sidechains and amendments.
- * @returns a hex string of the encoded transaction
+ * @param json JSON object representing the claim.
+ * @returns a hex string of the encoded claim.
  */
 function encodeForSigningClaim(json: object): string {
   if (typeof json !== 'object') {
@@ -86,12 +85,12 @@ function encodeForSigningClaim(json: object): string {
 }
 
 /**
- * Encode a transaction and prepare for multi-signing
+ * Encode a transaction and prepare for multi-signing.
  *
- * @param json JSON object representing the transaction
- * @param signer string representing the account to sign the transaction with
+ * @param json JSON object representing the transaction.
+ * @param signer string representing the account to sign the transaction with.
  * @param definitions Custom rippled types to use instead of the default. Used for sidechains and amendments.
- * @returns a hex string of the encoded transaction
+ * @returns a hex string of the encoded transaction.
  */
 function encodeForMultisigning(
   json: object,
@@ -110,6 +109,19 @@ function encodeForMultisigning(
   )
 }
 
+/**
+ * Encode a Batch transaction for signing.
+ *
+ * @param json JSON object representing the transaction.
+ * @returns a hex string of the encoded transaction.
+ */
+function encodeForSigningBatch(json: object): string {
+  if (typeof json !== 'object') {
+    throw new Error('Need an object to encode a Batch transaction')
+  }
+  return bytesToHex(signingBatchData(json as BatchObject))
+}
+
 /**
  * Encode a quality value
  *
@@ -142,6 +154,7 @@ export {
   encodeForSigning,
   encodeForSigningClaim,
   encodeForMultisigning,
+  encodeForSigningBatch,
   encodeQuality,
   decodeQuality,
   decodeLedgerData,

packages/ripple-binary-codec/src/types/hash.ts

@@ -1,6 +1,6 @@
 import { Comparable } from './serialized-type'
 import { BinaryParser } from '../serdes/binary-parser'
-import { hexToBytes } from '@xrplf/isomorphic/utils'
+import { HEX_REGEX, hexToBytes } from '@xrplf/isomorphic/utils'
 import { compare } from '../utils'
 
 /**
@@ -27,6 +27,9 @@ class Hash extends Comparable<Hash | string> {
     }
 
     if (typeof value === 'string') {
+      if (!HEX_REGEX.test(value)) {
+        throw new Error(`Invalid hash string ${value}`)
+      }
       return new this(hexToBytes(value))
     }
 

packages/ripple-binary-codec/test/signing-data-encoding.test.ts

@@ -1,9 +1,10 @@
 import { XrplDefinitions } from '../src/enums/xrpl-definitions'
-const {
+import {
   encodeForSigning,
   encodeForSigningClaim,
   encodeForMultisigning,
-} = require('../src')
+  encodeForSigningBatch,
+} from '../src'
 
 const normalDefinitions = require('../src/enums/definitions.json')
 
@@ -124,8 +125,8 @@ describe('Signing data', function () {
       TransactionType: 'NotAPayment',
     }
 
-    expect(() => encodeForSigning(invalidTransactionType)).toThrowError(
-      /NotAPayment/u,
+    expect(() => encodeForSigning(invalidTransactionType)).toThrow(
+      new TypeError('Unable to interpret "TransactionType: NotAPayment".'),
     )
   })
 
@@ -244,4 +245,35 @@ describe('Signing data', function () {
       ].join(''),
     )
   })
+
+  it('can create batch blob', function () {
+    const flags = 1
+    const txIDs = [
+      'ABE4871E9083DF66727045D49DEEDD3A6F166EB7F8D1E92FE868F02E76B2C5CA',
+      '795AAC88B59E95C3497609749127E69F12958BC016C600C770AEEB1474C840B4',
+    ]
+    const json = { flags, txIDs }
+    const actual = encodeForSigningBatch(json)
+    expect(actual).toBe(
+      [
+        // hash prefix
+        '42434800',
+        // flags
+        '00000001',
+        // txIds length
+        '00000002',
+        // txIds
+        'ABE4871E9083DF66727045D49DEEDD3A6F166EB7F8D1E92FE868F02E76B2C5CA',
+        '795AAC88B59E95C3497609749127E69F12958BC016C600C770AEEB1474C840B4',
+      ].join(''),
+    )
+  })
+
+  it('encodeForSigningBatch fails on non-object', function () {
+    const flags = 1
+    // @ts-expect-error - testing invalid input for JS users
+    expect(() => encodeForSigningBatch(flags)).toThrow(
+      new Error('Need an object to encode a Batch transaction'),
+    )
+  })
 })

packages/xrpl/.eslintrc.js

@@ -66,6 +66,7 @@ module.exports = {
     'tsdoc/syntax': 'off',
     'jsdoc/require-description-complete-sentence': 'off',
     'import/prefer-default-export': 'off',
+    'max-depth': ['warn', 3],
   },
   overrides: [
     {
@@ -155,7 +156,6 @@ module.exports = {
         'max-lines-per-function': ['off'],
         'max-statements': ['off'],
         complexity: ['off'],
-        'max-depth': ['warn', 3],
       },
     },
   ],

packages/xrpl/HISTORY.md

@@ -8,13 +8,15 @@ Subscribe to [the **xrpl-announce** mailing list](https://groups.google.com/g/xr
 * Support for `NFTokenMintOffer` (XLS-52)
 * Add Github Actions step to auto-generate documentation
 * Support for `Account Permissions` and `Account Permission Delegation` (XLS-74d, XLS-75d)
+* Add support for `Batch` amendment (XLS-56)
 
 ### Fixed
 * Fix `OracleSet` transaction to accept hexadecimal string values for `AssetPrice` field
 * `TransactionStream` model includes `hash` field in APIv2
 * `TransactionStream` model includes `close_time_iso` field only for APIv2
 * Adds `MPTCurrency` type
 * Better faucet support
+* Improve multisign fee calculations
 
 ## 4.2.0 (2025-2-13)