Skip to content

Add binary codec and transaction models for MPT#131

Open
e-desouza wants to merge 9 commits intomainfrom
feat/mpt-binary-codec
Open

Add binary codec and transaction models for MPT#131
e-desouza wants to merge 9 commits intomainfrom
feat/mpt-binary-codec

Conversation

@e-desouza
Copy link
Collaborator

High Level Overview of Change

Full MPT (Multi-Purpose Token) support for the binary codec and transaction/ledger models:

  • New Hash192 type in the binary codec (24-byte fixed-length hash for MPTokenIssuanceID)
  • Updated definitions.json with MPT transaction types, ledger entry types, and field definitions
  • Four new transaction models: MPTokenIssuanceCreate, MPTokenIssuanceDestroy, MPTokenIssuanceSet, MPTokenAuthorize
  • Two new ledger objects: MPToken, MPTokenIssuance
  • 40 tests covering field encoding, type codes, transaction serialization, signing prefixes, and serde roundtrips

Closes #119

Context of Change

The XRPL MPT amendment introduces four new transaction types (codes 54-57) and two new ledger entry types (codes 126-127). This required:

  1. A new Hash192 type -- MPTokenIssuanceID is a 24-byte (192-bit) hash, which didn't exist in the codec. Followed the same pattern as Hash128/Hash160/Hash256.

  2. Seven new field definitions in definitions.json: MPTokenIssuanceID (Hash192), ShareMPTID (Hash192), Holder (AccountID), AssetScale (UInt8), MaximumAmount (UInt64), MPTAmount (UInt64), MPTokenMetadata (Blob).

  3. Transaction models following existing patterns in the codebase (CommonFields with #[serde(flatten)], ValidateCurrencies derive macro, builder methods, flag enums with serde_repr).

  4. Validation logic where appropriate: MPTokenIssuanceCreate validates transfer_fee <= 50000, MPTokenIssuanceSet rejects mutually exclusive TfMPTLock + TfMPTUnlock flags.

The UInt192 type name in definitions.json was renamed to Hash192 to match the rippled naming convention (fixed-length hashes use the Hash prefix, not UInt).

Type of Change

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Refactor (non-breaking change that only restructures code)
  • Tests (You added tests for code that already exists, or your new feature included in this PR)
  • Documentation Updates
  • Release

Before / After

Before:

  • Binary codec has no awareness of Hash192 or any MPT fields/types
  • No MPT transaction types in TransactionType enum
  • No MPT ledger entry types
  • Attempting to encode an MPT transaction would fail

After:

  • Hash192 type handles 24-byte hashes correctly (fixed-length, no VL prefix)
  • All four MPT transaction types serialize/deserialize correctly through both JSON (serde) and binary codec (encode/encode_for_signing/encode_for_multisigning)
  • MPToken and MPTokenIssuance ledger objects deserialize from JSON
  • 40 new tests across the transaction models, ledger objects, and binary codec

Test Plan

# Run all tests (40 new MPT-specific tests + existing suite):
cargo test --all-features

# Run only MPT-related tests:
cargo test mptoken --all-features
cargo test mpt --all-features
cargo test hash192 --all-features

# Verify no regressions:
cargo clippy --all-features -- -D warnings
cargo fmt --check

All pass with zero warnings and zero failures. The binary codec tests verify:

  • Field ID encoding/decoding for all 7 MPT fields
  • Transaction type code resolution (54-57)
  • Ledger entry type code resolution (126-127)
  • Field instance metadata (type, nth, serialized, signing, vl_encoded flags)
  • Full encode() for all 4 transaction types with assertion on specific hex patterns
  • encode_for_signing() prefix verification
  • encode_for_multisigning() prefix and suffix verification
  • Deterministic encoding (same input -> same output)

@e-desouza e-desouza force-pushed the feat/mpt-binary-codec branch from baf2e82 to 841449f Compare February 21, 2026 00:01
@e-desouza e-desouza marked this pull request as draft February 21, 2026 00:11
Add a 192-bit (24-byte) hash type required by MPT fields such as
MPTokenIssuanceID. Follows the same implementation pattern as
Hash128/Hash160/Hash256 with full trait coverage (Hash, XRPLType,
TryFromParser, TryFrom<&str>, Display, AsRef<[u8]>) and unit tests.
Add Hash192 type (replacing unused UInt192 at type code 21), four MPT
transaction types (MPTokenIssuanceCreate/Destroy/Set/Authorize), two
MPT ledger entry types (MPTokenIssuance/MPToken), and seven MPT-related
fields (MPTokenIssuanceID, ShareMPTID, MaximumAmount, MPTAmount,
AssetScale, MPTokenMetadata, Holder) to definitions.json and types.rs.
Add MPTokenAuthorize, MPTokenIssuanceCreate, MPTokenIssuanceDestroy,
and MPTokenIssuanceSet to the TransactionType enum for use by MPT
transaction models.
Add the MPTokenIssuanceCreate transaction with fields for asset_scale,
maximum_amount, transfer_fee, and mptoken_metadata. Includes flags
(TfMPTCanLock, TfMPTRequireAuth, TfMPTCanEscrow, TfMPTCanTrade,
TfMPTCanTransfer, TfMPTCanClawback), transfer fee validation, builder
methods, and serde roundtrip tests.

Also adds InvalidFlagCombination variant to XRPLModelException for use
by MPTokenIssuanceSet validation.
Add the MPTokenIssuanceDestroy transaction with mptoken_issuance_id
field. Uses NoFlags since this transaction has no flag-specific
behavior. Includes builder method, serde roundtrip, and validation
tests.
Add the MPTokenIssuanceSet transaction with mptoken_issuance_id and
optional holder fields. Includes TfMPTLock/TfMPTUnlock flags with
validation that prevents setting both simultaneously. Builder methods,
serde roundtrip, and conflict detection tests included.
Add the MPTokenAuthorize transaction with mptoken_issuance_id and
optional holder fields. Includes TfMPTUnauthorize flag for opt-out
flows. Builder methods, serde roundtrip, holder opt-in, and
deauthorize flow tests included.
Add MPToken (account balance) and MPTokenIssuance (issuance definition)
ledger entry types with full serde support, LedgerEntryType enum
variants, and LedgerEntry enum variants. Includes serde roundtrip and
ledger entry type tests for both objects.
Tests cover:
- Field name encoding/decoding for all 7 new MPT fields (Hash192,
  AccountID, UInt8, UInt64, Blob types)
- Transaction type code resolution (codes 54-57)
- Ledger entry type code resolution (codes 126-127)
- Field instance metadata validation
- Full encode() roundtrip for all 4 MPT transaction types with
  hex pattern verification
- encode_for_signing() with signing prefix
- Flag serialization (combined TfMPTCanTransfer | TfMPTCanLock)
- Deterministic encoding output
@e-desouza e-desouza force-pushed the feat/mpt-binary-codec branch from 841449f to 7925f94 Compare February 21, 2026 05:20
@e-desouza e-desouza marked this pull request as ready for review February 22, 2026 18:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add binary codec support for MPT

1 participant