DEV Community: Shashwat Mittal

TokenEscrowV1: Fixing MPT Escrow Accounting

Shashwat Mittal — Wed, 17 Dec 2025 19:09:30 +0000

Escrow is the backbone of the XRPL’s settlement system, but historically it was limited to XRP only.

Token Escrow (XLS-85) extends this functionality to any issued token, including IOUs and Multi-Purpose Tokens, enabling time-locked or condition-based delivery of assets. This makes it essential for institutional workflows such as scheduled payouts, conditional settlements, and automated treasury operations.

During internal testing of the original Token Escrow amendment (which was never enabled on mainnet), a bug was discovered in how escrows involving MPTs with transfer fees were handled.

The TokenEscrowV1 amendment resolves this issue and restores correct accounting behaviour.

The Problem

Multi-Purpose Tokens (MPTs) are an XRPL-native token standard that blends fungible and non-fungible properties, allowing assets to have shared traits while carrying rich, asset-specific metadata directly onchain. They’re essential for institutional tokenization because they enable precise asset representation, embedded compliance rules, and full lifecycle management without relying on external smart contracts.

However, an existing issue was that when an MPT escrow finished and the MPT had a transfer fee, the ledger applied the fee during unlock.
Meaning:

If you held 100 tokens in escrow,
And the transfer fee was 1 token,
The recipient correctly received 99 tokens.

This behaviour was expected.

The bug was in the issuer’s accounting:

The ledger incorrectly reduced the issuer’s LockedAmount by only the net amount (99), even though 100 tokens were initially placed into escrow. This left 1 token permanently stuck in the locked state, causing supply inaccuracies and long-term accounting drift.

In other words: Instead of decreasing LockedAmount from 100 → 0, the system went from 100 → 1.

Over time, this would have led to various issues, such as changes in the actual supply, ledger inconsistencies, and a lack of trust in the issuer's metrics.

The Solution: TokenEscrowV1 Amendment

The fix restores correct behaviour by cleanly separating gross escrow logic from net delivery logic.

How the fix works:

LockedAmount now always decreases by the full escrowed amount (gross). For example, if escrow locks 100 tokens, then LockedAmount decreases by 100.
Outstanding supply adjusts only by the net difference (reflecting transfer fees). For example, if 100 tokens are escrowed and the recipient receives 99 after fees, then Outstanding decreases by 99, with the 1-token fee handled separately through the issuer’s transfer-fee mechanism.

This solves all preexisting issues, such as ensuring that no tokens become trapped, that total supply remains accurate, LockedAmount returns precisely to its pre-escrow value, and so forth.

In short: escrowed tokens unlock exactly as they were locked, regardless of transfer fees.

Validator Voting

The XRP Ledger is governed by validator consensus.

Because this fix modifies how the ledger processes escrow completions, it must be activated through an amendment vote.

Validator approval is essential to:

Ensure nodes use correct MPT escrow accounting, avoiding supply drift.
Guarantee consistent balances and ledger behavior across all implementations.
Give issuers accurate LockedAmount and supply metrics, especially for transfer-fee tokens.

We appreciate the validators’ review and support in enabling TokenEscrowV1, which strengthens the reliability and correctness of MPT-based token flows across the network.

Token Escrow Security Audit Findings

Shashwat Mittal — Tue, 24 Jun 2025 18:34:08 +0000

Token Escrow is a new feature that expands the XRPL’s native Escrow functionality beyond XRP, allowing users to escrow Trustline-based tokens (IOUs) and Multi-Purpose Tokens (MPTs). To ensure that the feature is ready for production and meets the highest standards, we have engaged the security experts at FYEO to perform a security audit. We are pleased to report that no security issues were identified. There was only one Informational recommendation that our team acknowledged.

The full, detailed report from FYEO is available for public review here: Link.

Summary of Key Findings

The FYEO team concluded that the code implements the documented functionality of Token Escrow, with one recommendation to be aware of future changes to the codebase that could adversely affect it.

Their specific recommendation, “Future-Proofing Advisory for Overflow/Underflow in Escrow Balance Adjustments”, means that we should be aware of how the code performs balance calculations. Under the XRPL’s current rules, these calculations are safe because existing ledger protections already prevent account balances from going too high (overflow) or too low (underflow) to cause an issue.

This is a forward-looking recommendation to add extra, explicit checks that would ensure calculations remain safe even if fundamental ledger rules are changed in the future.

Acknowledgement: The security and integrity of XRPL is our highest priority. We have acknowledged FYEO’s recommendation and will proactively monitor for future changes and incorporate additional safeguards as needed.

Security Audit for Multi-Purpose Tokens (MPT) on the XRP Ledger Completed with Softstack GmbH

Shashwat Mittal — Thu, 19 Dec 2024 19:01:55 +0000

As new innovations on the XRP Ledger continue to advance, maintaining robust security measures is critical to upholding trust and integrity throughout the ecosystem.

On October 22, the cybersecurity firm Softstack GmbH completed a comprehensive security audit of the Multi-Purpose Token (MPT) implementation on the XRP Ledger. The focus of this audit was to ensure that the MPT’s design, efficiency, and security assumptions met or exceeded industry standards. The Softstack team evaluated key aspects of the token’s functionality—from storage claims and operational performance to unidirectional trustline security.

Softstack GmbH’s audit covered five risk levels in relation to MPT functionality:

Critical: A vulnerability that can disrupt the codebase functioning in a number of scenarios, or creates a risk that the codebase may be broken.
High: A vulnerability that affects the desired outcome when using a codebase, or provides the opportunity to use a codebase in an unintended way.
Medium: A vulnerability that could affect the desired outcome of executing the codebase in a specific scenario.
Low: A vulnerability that does not have a significant impact on possible scenarios for the use of the codebase and is probably subjective.
Informational: A vulnerability that can have informational character but is not affecting any of the codebase.

Softstack’s findings were highly encouraging. The audit revealed no critical or high-severity vulnerabilities. Instead, the assessment identified only a few low-severity and informational issues, all of which have been fixed or acknowledged. In particular, recommendations were implemented to enhance memory safety in MPT issuer handling, improve locking mechanisms to prevent race conditions, and clarify certain function behaviors.

"The safety and transparency of blockchain technology are core to Softstack’s mission, and we're pleased to have supported Ripple in advancing the security and performance of the XRP Ledger," said Yannik Heinze, CEO at Softstack.

Reference material for the reports:

MPT Security Audit Results (Softstack GmbH)
Additional details: Softstack.io

Multi-Purpose Token (MPT) Audit Highlights

The audit team validated the token’s space and performance claims, confirming that MPT creation, transfer, locking, and destruction functioned as intended without introducing new vulnerabilities. They verified proper adherence to the relevant coding and security standards, ensuring that best practices continue to inform the MPT’s development.

No significant concerns were raised that would impact the MPT’s readiness for integration with the broader XRPL ecosystem. The resolved issues further reinforce the MPT’s operational integrity, making certain that the MPT implementation remains secure, efficient, and future-proof.

As with previous security efforts across the XRP Ledger, these steps reinforce the ecosystem’s commitment to rigorous evaluation. Ensuring the long-term reliability and resilience of innovative features, like the MPT, ultimately benefits developers, users, and stakeholders as the XRPL continues to evolve.

Important Step in Tokenized Future

Tokenization is at the heart of blockchain’s transformative potential, enabling seamless creation and transfer of value in various industries. As the digital asset economy continues to grow, security and efficiency are non-negotiable. The collaboration with Softstack GmbH ensures that MPT is ready to meet the demands of enterprise-grade tokenization while upholding the XRP Ledger’s trusted reputation.