TokenEscrowV1: Fixing MPT Escrow Accounting

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.