feat: Updates to PathSet binary-codec. Also included an additional Payment transaction integ test with explicit paths

ckeshava · ckeshava · commit 72b8422acfad · 2026-02-23T14:56:57.000-08:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Support for XLS-82d MPT-DEX
 - The `ledger_entry` RPC can now accept `AMM` input along with the two asset definitions.
 - The `MPTCurrency` model has been updated to validate the semantic correctness of `MPTIssuanceID` values. This is performed using regular-expression matching and does not involve any read-operations on the XRPL blockchain.
+- The binary-codec of `PathSet` type is updated to accommodate `mpt_issuance_id`. Please refer to XLS-82d MPT-DEX amendment for context behind this change.
 
 
 ## [[4.5.0]]
diff --git a/tests/integration/transactions/test_payment.py b/tests/integration/transactions/test_payment.py
@@ -1,14 +1,23 @@
 from tests.integration.integration_test_case import IntegrationTestCase
 from tests.integration.it_utils import (
+    create_mpt_token_and_authorize_source_async,
+    fund_wallet_async,
     sign_and_reliable_submission_async,
     test_async_and_sync,
 )
 from tests.integration.reusable_values import DESTINATION, WALLET
 from xrpl.models.amounts.mpt_amount import MPTAmount
 from xrpl.models.exceptions import XRPLModelException
+from xrpl.models.path import PathStep
 from xrpl.models.requests.account_objects import AccountObjects, AccountObjectType
 from xrpl.models.transactions import Payment
-from xrpl.models.transactions.mptoken_issuance_create import MPTokenIssuanceCreate
+from xrpl.models.transactions.amm_create import AMMCreate
+from xrpl.models.transactions.mptoken_authorize import MPTokenAuthorize
+from xrpl.models.transactions.mptoken_issuance_create import (
+    MPTokenIssuanceCreate,
+    MPTokenIssuanceCreateFlag,
+)
+from xrpl.wallet import Wallet
 
 
 class TestPayment(IntegrationTestCase):
@@ -179,3 +188,67 @@ async def test_mpt_payment(self, client):
             client,
         )
         self.assertTrue(response.is_successful())
+
+    @test_async_and_sync(globals())
+    async def test_payment_with_mpt_pathset(self, client):
+        issuer = Wallet.create()
+        await fund_wallet_async(issuer)
+        lp_wallet = Wallet.create()
+        await fund_wallet_async(lp_wallet)
+        destination = Wallet.create()
+        await fund_wallet_async(destination)
+
+        mpt_flags = [
+            MPTokenIssuanceCreateFlag.TF_MPT_CAN_TRADE,
+            MPTokenIssuanceCreateFlag.TF_MPT_CAN_TRANSFER,
+        ]
+
+        # Create MPT, authorize + fund LP wallet
+        mpt_id = await create_mpt_token_and_authorize_source_async(
+            issuer=issuer,
+            source=lp_wallet,
+            client=client,
+            flags=mpt_flags,
+        )
+
+        # Authorize destination to hold MPT
+        auth_dest = MPTokenAuthorize(
+            account=destination.classic_address,
+            mptoken_issuance_id=mpt_id,
+        )
+        response = await sign_and_reliable_submission_async(
+            auth_dest, destination, client
+        )
+        self.assertEqual(response.result["engine_result"], "tesSUCCESS")
+
+        # Create AMM pool: XRP / MPT
+        amm_create = AMMCreate(
+            account=lp_wallet.classic_address,
+            amount="1000000",
+            amount2=MPTAmount(mpt_issuance_id=mpt_id, value="1000"),
+            trading_fee=12,
+        )
+        response = await sign_and_reliable_submission_async(
+            amm_create, lp_wallet, client
+        )
+        self.assertEqual(response.result["engine_result"], "tesSUCCESS")
+
+        # Authorize sender to hold MPT
+        auth_sender = MPTokenAuthorize(
+            account=WALLET.classic_address,
+            mptoken_issuance_id=mpt_id,
+        )
+        response = await sign_and_reliable_submission_async(auth_sender, WALLET, client)
+        self.assertEqual(response.result["engine_result"], "tesSUCCESS")
+
+        # Cross-currency payment: XRP → MPT via XRP/MPT AMM pool
+        pay_tx = Payment(
+            account=WALLET.address,
+            destination=destination.address,
+            amount=MPTAmount(mpt_issuance_id=mpt_id, value="5"),
+            send_max="500000",
+            # Explicitly specify a Path with mpt_issuance_id intermediate Hop
+            paths=[[PathStep(mpt_issuance_id=mpt_id)]],
+        )
+        response = await sign_and_reliable_submission_async(pay_tx, WALLET, client)
+        self.assertEqual(response.result["engine_result"], "tesSUCCESS")
diff --git a/tests/unit/core/binarycodec/types/test_path_set.py b/tests/unit/core/binarycodec/types/test_path_set.py
@@ -2,6 +2,8 @@
 
 from xrpl.core.binarycodec import XRPLBinaryCodecException
 from xrpl.core.binarycodec.binary_wrappers.binary_parser import BinaryParser
+from xrpl.core.binarycodec.types.account_id import AccountID
+from xrpl.core.binarycodec.types.currency import Currency
 from xrpl.core.binarycodec.types.path_set import PathSet
 
 buffer = (
@@ -108,3 +110,130 @@ def test_from_parser_to_json(self):
     def test_raises_invalid_value_type(self):
         invalid_value = 1
         self.assertRaises(XRPLBinaryCodecException, PathSet.from_value, invalid_value)
+
+    # ── MPT PathSet serialization tests ──
+    #
+    # PathSet binary format reference (from rippled STPathSet.cpp):
+    #
+    # Each path step starts with a 1-byte type flag bitmask:
+    #   0x01 = account    (followed by 20-byte AccountID)
+    #   0x10 = currency   (followed by 20-byte Currency)
+    #   0x20 = issuer     (followed by 20-byte AccountID)
+    #   0x40 = MPT        (followed by 24-byte MPTID)
+    #
+    # Special marker bytes:
+    #   0xFF = path boundary (separates alternative paths within a PathSet)
+    #   0x00 = end of PathSet (terminates the entire PathSet)
+    #
+    # Currency (0x10) and MPT (0x40) are mutually exclusive within a
+    # single path step — a step cannot carry both flags.
+
+    def test_one_path_with_one_mpt_hop(self):
+        mpt_issuance_id = "00000001B5F762798A53D543A014CAF8B297CFF8F2F937E8"
+        path = [[{"mpt_issuance_id": mpt_issuance_id}]]
+
+        pathset = PathSet.from_value(path)
+        # "40"               → type byte: MPT flag (0x40)
+        # mpt_issuance_id    → raw 24-byte MPTID
+        # "00"               → end of PathSet
+        expected_hex = "40" + mpt_issuance_id + "00"
+        self.assertEqual(str(pathset).upper(), expected_hex)
+
+        # round-trip JSON equivalence
+        self.assertEqual(pathset.to_json(), path)
+
+        # deserialization via BinaryParser
+        parser = BinaryParser(expected_hex)
+        self.assertEqual(str(PathSet.from_parser(parser)), str(pathset))
+
+    def test_two_paths_with_mpt_hops(self):
+        mpt_id_1 = "00000001B5F762798A53D543A014CAF8B297CFF8F2F937E8"
+        mpt_id_2 = "000004C463C52827307480341125DA0577DEFC38405B0E3E"
+        path = [
+            [{"mpt_issuance_id": mpt_id_1}],
+            [{"mpt_issuance_id": mpt_id_2}],
+        ]
+
+        pathset = PathSet.from_value(path)
+        # "40" + mpt_id_1    → first path: one MPT hop
+        # "FF"               → path boundary separating alternative paths
+        # "40" + mpt_id_2    → second path: one MPT hop
+        # "00"               → end of PathSet
+        expected_hex = "40" + mpt_id_1 + "FF" + "40" + mpt_id_2 + "00"
+        self.assertEqual(str(pathset).upper(), expected_hex)
+
+        self.assertEqual(pathset.to_json(), path)
+
+        parser = BinaryParser(expected_hex)
+        self.assertEqual(str(PathSet.from_parser(parser)), str(pathset))
+
+    def test_path_with_mpt_and_currency_path_elements(self):
+        """One path with two distinct steps: an MPT hop followed by a Currency hop."""
+        mpt_issuance_id = "00000001B5F762798A53D543A014CAF8B297CFF8F2F937E8"
+        currency_code = "ABC"
+        path = [
+            [
+                {"mpt_issuance_id": mpt_issuance_id},
+                {"currency": currency_code},
+            ]
+        ]
+
+        pathset = PathSet.from_value(path)
+        currency_hex = str(Currency.from_value(currency_code)).upper()
+        # "40" + mpt_id      → first step: MPT hop (0x40 type flag)
+        # "10" + currency_hex → second step: Currency hop (0x10 type flag)
+        # "00"               → end of PathSet
+        expected_hex = "40" + mpt_issuance_id + "10" + currency_hex + "00"
+        self.assertEqual(str(pathset).upper(), expected_hex)
+
+        self.assertEqual(pathset.to_json(), path)
+
+        parser = BinaryParser(expected_hex)
+        self.assertEqual(str(PathSet.from_parser(parser)), str(pathset))
+
+    def test_path_with_mpt_and_issuer_path_elements(self):
+        """One path with two distinct steps: an MPT hop followed by an Issuer hop."""
+        mpt_issuance_id = "00000001B5F762798A53D543A014CAF8B297CFF8F2F937E8"
+        issuer_account = "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh"
+        path = [
+            [
+                {"mpt_issuance_id": mpt_issuance_id},
+                {"issuer": issuer_account},
+            ]
+        ]
+
+        pathset = PathSet.from_value(path)
+        issuer_hex = str(AccountID.from_value(issuer_account)).upper()
+        # "40" + mpt_id     → first step: MPT hop (0x40 type flag)
+        # "20" + issuer_hex  → second step: Issuer hop (0x20 type flag)
+        # "00"               → end of PathSet
+        expected_hex = "40" + mpt_issuance_id + "20" + issuer_hex + "00"
+        self.assertEqual(str(pathset).upper(), expected_hex)
+
+        self.assertEqual(pathset.to_json(), path)
+
+        parser = BinaryParser(expected_hex)
+        self.assertEqual(str(PathSet.from_parser(parser)), str(pathset))
+
+    def test_currency_and_mpt_mutually_exclusive_in_serialization(self):
+        """Providing both currency and mpt_issuance_id in a single step must raise."""
+        path = [
+            [
+                {
+                    "currency": "ABC",
+                    "mpt_issuance_id": "00000001B5F762798A53"
+                    "D543A014CAF8B297CFF8F2F937E8",
+                }
+            ]
+        ]
+        self.assertRaises(XRPLBinaryCodecException, PathSet.from_value, path)
+
+    def test_currency_and_mpt_mutually_exclusive_in_deserialization(self):
+        """A type byte with both Currency (0x10) and MPT (0x40) flags must raise."""
+        # "50" = 0x10 | 0x40 — an invalid combination
+        currency_hex = str(Currency.from_value("ABC")).upper()
+        mpt_hex = "00000001B5F762798A53D543A014CAF8B297CFF8F2F937E8"
+        invalid_hex = "50" + currency_hex + mpt_hex + "00"
+
+        parser = BinaryParser(invalid_hex)
+        self.assertRaises(XRPLBinaryCodecException, PathSet.from_parser, parser)
diff --git a/xrpl/core/binarycodec/types/path_set.py b/xrpl/core/binarycodec/types/path_set.py
@@ -12,12 +12,16 @@
 from xrpl.core.binarycodec.exceptions import XRPLBinaryCodecException
 from xrpl.core.binarycodec.types.account_id import AccountID
 from xrpl.core.binarycodec.types.currency import Currency
+from xrpl.core.binarycodec.types.hash192 import Hash192
 from xrpl.core.binarycodec.types.serialized_type import SerializedType
 
 # Constant for masking types of a PathStep
 _TYPE_ACCOUNT: Final[int] = 0x01
 _TYPE_CURRENCY: Final[int] = 0x10
 _TYPE_ISSUER: Final[int] = 0x20
+_TYPE_MPT: Final[int] = 0x40
+
+_HASH192_BYTES: Final[int] = 24
 
 # Constants for separating Paths in a PathSet
 _PATHSET_END_BYTE: Final[int] = 0x00
@@ -26,7 +30,12 @@
 
 def _is_path_step(value: Dict[str, str]) -> bool:
     """Helper function to determine if a dictionary represents a valid path step."""
-    return "issuer" in value or "account" in value or "currency" in value
+    return (
+        "issuer" in value
+        or "account" in value
+        or "currency" in value
+        or "mpt_issuance_id" in value
+    )
 
 
 def _is_path_set(value: List[List[Dict[str, str]]]) -> bool:
@@ -57,6 +66,11 @@ def from_value(cls: Type[Self], value: Dict[str, str]) -> Self:
                 f" received {value.__class__.__name__}."
             )
 
+        if "currency" in value and "mpt_issuance_id" in value:
+            raise XRPLBinaryCodecException(
+                "Currency and mpt_issuance_id are mutually exclusive in a path step"
+            )
+
         data_type = 0x00
         buffer = b""
         if "account" in value:
@@ -67,6 +81,10 @@ def from_value(cls: Type[Self], value: Dict[str, str]) -> Self:
             currency = Currency.from_value(value["currency"])
             buffer += bytes(currency)
             data_type |= _TYPE_CURRENCY
+        elif "mpt_issuance_id" in value:
+            mpt_id = Hash192.from_value(value["mpt_issuance_id"])
+            buffer += bytes(mpt_id)
+            data_type |= _TYPE_MPT
         if "issuer" in value:
             issuer = AccountID.from_value(value["issuer"])
             buffer += bytes(issuer)
@@ -90,12 +108,21 @@ def from_parser(
         data_type = parser.read_uint8()
         buffer = b""
 
+        if (data_type & _TYPE_CURRENCY) and (data_type & _TYPE_MPT):
+            raise XRPLBinaryCodecException(
+                "Invalid binary input: Currency and mpt_issuance_id are "
+                "mutually exclusive in a path step"
+            )
+
         if data_type & _TYPE_ACCOUNT:
             account_id = parser.read(AccountID.LENGTH)
             buffer += account_id
         if data_type & _TYPE_CURRENCY:
             currency = parser.read(Currency.LENGTH)
             buffer += currency
+        elif data_type & _TYPE_MPT:
+            mpt_id = parser.read(_HASH192_BYTES)
+            buffer += mpt_id
         if data_type & _TYPE_ISSUER:
             issuer = parser.read(AccountID.LENGTH)
             buffer += issuer
@@ -119,6 +146,9 @@ def to_json(self: Self) -> Dict[str, str]:
         if data_type & _TYPE_CURRENCY:
             currency = Currency.from_parser(parser).to_json()
             json["currency"] = currency
+        elif data_type & _TYPE_MPT:
+            mpt_id = parser.read(_HASH192_BYTES).hex().upper()
+            json["mpt_issuance_id"] = mpt_id
         if data_type & _TYPE_ISSUER:
             issuer = AccountID.from_parser(parser).to_json()
             json["issuer"] = issuer
diff --git a/xrpl/models/path.py b/xrpl/models/path.py
@@ -22,6 +22,7 @@ class PathStep(BaseModel):
     account: Optional[str] = None
     currency: Optional[str] = None
     issuer: Optional[str] = None
+    mpt_issuance_id: Optional[str] = None
     type: Optional[int] = None
     type_hex: Optional[str] = None
 
@@ -33,6 +34,7 @@ def _get_errors(self: Self) -> Dict[str, str]:
                 "account": self._get_account_error(),
                 "currency": self._get_currency_error(),
                 "issuer": self._get_issuer_error(),
+                "mpt_issuance_id": self._get_mpt_issuance_id_error(),
             }.items()
             if value is not None
         }
@@ -49,6 +51,8 @@ def _get_currency_error(self: Self) -> Optional[str]:
             return None
         if self.account is not None:
             return "Cannot set currency if account is set"
+        if self.mpt_issuance_id is not None:
+            return "Cannot set both currency and mpt_issuance_id"
         if self.issuer is not None and self.currency.upper() == "XRP":
             return "Cannot set issuer if currency is XRP"
         return None
@@ -62,6 +66,13 @@ def _get_issuer_error(self: Self) -> Optional[str]:
             return "Cannot set issuer if currency is XRP"
         return None
 
+    def _get_mpt_issuance_id_error(self: Self) -> Optional[str]:
+        if self.mpt_issuance_id is None:
+            return None
+        if self.currency is not None:
+            return "Cannot set both mpt_issuance_id and currency"
+        return None
+
 
 Path = List[PathStep]
 """
