Market Halting

[dangell7]

Market Halting

Title: Market Halting
Revision: 1 (2025-08-22)
Type: Draft
Author: Denis Angell, XRPL-Labs [dangell7](https://github.com/dangell7)
Affiliation: XRPL-Labs

Abstract

This amendment introduces regulatory compliance capabilities for halting market trading activities on private XRPL-based blockchains. It provides mechanisms to halt trading for specific assets either in specific domains or across all domains, while preserving the functionality of non-trading transactions such as payments, checks, and escrows.

The amendment operates independently and affects DEX activity across open DEX and permissioned domains, providing granular control for token issuers.

Amendment

The proposed amendment introduces efficient halting mechanisms for market trading using asset-specific and domain-specific ledger entries, providing token issuers with the ability to temporarily suspend trading of their assets while maintaining other blockchain functionalities.

The amendment adds:

New Ledger Entry Types

• ltMARKET_HALT (0x0086): Represents halt state for a specific asset in a specific domain.

New Serialized Fields

• sfHaltTimestamp (UInt32, code 55): Timestamp when the halt was initiated.

New Transaction Types

• MarketHalt (ttMARKET_HALT, code 66): Halts or unhalts market trading for specific assets.

New Transaction Flags

For MarketHalt Transactions

• tfAssetHalt (0x00010000): Indicates intent to halt/unhalt specific asset.
• tfAllDomains (0x00020000): When combined with tfAssetHalt, indicates halt should apply to all domains.
• Mask: tfMarketHaltMask = ~(tfUniversal | tfAssetHalt | tfAllDomains)

Flag Combinations:

• Domain-Specific Halt: tfAssetHalt only
• All-Domains Halt: tfAssetHalt | tfAllDomains

Note: The transaction toggles the halt state of the target asset.

Market Activity Definition

For the purposes of this amendment:

• Market Activity: Any DEX transaction (OfferCreate, cross-currency Payment) in any domain (open DEX, permissioned domains, AMMs)
• Asset Halt: Affects all trading pairs involving the specified asset
  • Domain-Specific: Only affects trading in the specified domain (DomainID with tfAssetHalt only)
  • All-Domains: Affects trading across all domains (tfAllDomains flag set)
• Non-Market Activity: All other transactions including:
  • Direct payments without currency conversion
  • Check transactions
  • Token swap transactions
  • Escrow transactions
  • Payment channel transactions
  • All account management transactions

Ledger Object Types

New Ledger Object: MarketHalt

The MarketHalt ledger entry represents halt state for a specific asset in a specific domain.

Object ID

The ID of a MarketHalt entry is generated using:

keylet::marketHalt(Asset, DomainID) = SHA512Half(0x0087, Asset, DomainID)

Halt Types:

• Domain-Specific Asset Halt: keylet::marketHalt(asset, domainID) with Flags unset
• All-Domains Asset Halt: keylet::marketHalt(asset, domainID) with lsfAllDomains flag set

Fields

Field	JSON Name	Type	Required	Description
LedgerEntryType	MarketHalt	UInt16	Required	The type of ledger object (value 0x0086).
Flags	Flags	UInt32	Required	Ledger entry flags (see below for flag definitions).
Asset	Asset	Issue	Required	The asset being halted.
DomainID	DomainID	Hash256	Required	Domain ID (uint256{0} for open DEX halts).
HaltTimestamp	HaltTimestamp	UInt32	Optional	Timestamp when halt was initiated (if applicable).
Account	Account	AccountID	Optional	Account that initiated the halt (if applicable).

MarketHalt Flags

Flag Name	Hex Value	Description
lsfAllDomains	0x00010000	Set to halt asset across all domains.

Flag Usage:

• Unset (Flags = 0): Halt applies only to the specified DomainID
• Set (Flags = lsfAllDomains): Halt applies to all domains for this asset

Example MarketHalt Objects

Domain-Specific Asset Halt:

{
  "LedgerEntryType": "MarketHalt",
  "Flags": 1,
  "Asset": {
    "currency": "GME",
    "issuer": "rGMEissuerAddress"
  },
  "DomainID": "0000000000000000000000000000000000000000000000000000000000000000",
  "HaltTimestamp": 743171558,
  "Account": "rGMEissuerAddress"
}

All-Domains Asset Halt:

{
  "LedgerEntryType": "MarketHalt",
  "Flags": 65536,
  "Asset": {
    "currency": "GME",
    "issuer": "rGMEissuerAddress"
  },
  "DomainID": "0000000000000000000000000000000000000000000000000000000000000000",
  "HaltTimestamp": 743171558,
  "Account": "rGMEissuerAddress"
}

New Transaction Type

Transaction Type: MarketHalt

The MarketHalt transaction is used to halt or unhalt market trading for specific assets in specific domains or across all domains.

Fields

Field	Type	Required	Description
TransactionType	UInt16	Required	The type of transaction (MarketHalt, value 66).
Account	AccountID	Required	The account initiating the halt/unhalt (must have appropriate authority).
Asset	Issue	Required	Asset to halt/unhalt.
DomainID	Hash256	Optional	Domain ID for domain-specific halts (defaults to uint256{0} if omitted).
Flags	UInt32	Required	Must be set to tfAssetHalt with optional additional flags.

Halt vs Unhalt Logic

The transaction operates as follows:

• To Halt: Submit transaction when the asset is currently active
• To Unhalt: Submit transaction when the asset is currently halted
• Domain-Specific: Use tfAssetHalt flag only - affects only the specified DomainID
• All-Domains: Use tfAssetHalt | tfAllDomains flags - affects all domains for this asset

The transaction toggles the halt state of the specified asset.

Authority Requirements

• Asset Halt: Only the issuer of the Asset can halt that specific asset
  • Domain-Specific: Issuer can halt their asset in specific domain
  • All-Domains: Issuer can halt their asset across all domains

Failure Conditions

The MarketHalt transaction MUST fail if:

• The transaction does not meet the generic transaction requirements.
• tfAssetHalt flag is not set.
• Asset field is missing or invalid.
• Account is not the issuer of Asset.
• If DomainID is specified, the domain must exist.
• tfAllDomains flag is set without tfAssetHalt flag.

State Changes

If the transaction is successful:

• MarketHalt object for the specified Asset/DomainID is created, updated, or removed.
• Appropriate flags set. (tfAssetHalt)
• For unhalt operations: Object is removed from the ledger.
• For all-domains halts: lsfAllDomains flag is set on the ledger object.
• The transaction fee is deducted from the account's balance.

Example Transactions

// Halt ALL GME trading on open DEX only - submitted by GME issuer
{
  "TransactionType": "MarketHalt",
  "Account": "rGMEissuerAddress",
  "Asset": {
    "currency": "GME",
    "issuer": "rGMEissuerAddress"
  },
  "Flags": 65536 // tfAssetHalt only
  // DomainID defaults to uint256{0} (open DEX)
}

// Halt ALL GME trading across ALL domains - submitted by GME issuer
{
  "TransactionType": "MarketHalt",
  "Account": "rGMEissuerAddress",
  "Asset": {
    "currency": "GME",
    "issuer": "rGMEissuerAddress"
  },
  "Flags": 196608 // tfAssetHalt | tfAllDomains (65536 + 131072)
}

// Halt ALL GME trading in specific domain only - submitted by GME issuer
{
  "TransactionType": "MarketHalt",
  "Account": "rGMEissuerAddress",
  "Asset": {
    "currency": "GME",
    "issuer": "rGMEissuerAddress"
  },
  "DomainID": "ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890",
  "Flags": 65536 // tfAssetHalt only
}

// Unhalt ALL GME trading (same transaction when already halted)
{
  "TransactionType": "MarketHalt",
  "Account": "rGMEissuerAddress",
  "Asset": {
    "currency": "GME",
    "issuer": "rGMEissuerAddress"
  },
  "Flags": 65536 // tfAssetHalt only
}

Modified Transaction Processing

OfferCreate Transaction Changes

When processing an OfferCreate transaction, the transaction MUST fail with tecMARKET_HALTED if:

1. Any all-domains halt exists for either asset: Check for MarketHalt with matching asset and lsfAllDomains flag set, OR
2. A domain-specific halt exists for either asset in the relevant domain: Check for MarketHalt with matching asset and matching DomainID

Cross-Currency Payment Transaction Changes

When processing a Payment transaction that involves currency conversion, the transaction MUST fail with tecMARKET_HALTED if:

Any asset in the payment path has a halt (applying same logic as offers - check all-domains halts first, then domain-specific halts)

Unaffected Transactions

The following transactions are NOT affected by market halts:

• Payment transactions without currency conversion (direct payments)
• Check transactions (CheckCreate, CheckCash, CheckCancel)
• Escrow transactions
• PaymentChannel transactions
• All account management transactions
• All credential and domain management transactions

Note: AMM transactions may be included in future versions of this amendment.

Efficient Halt Checking Implementation

DEX Transaction Processing Logic

When processing OfferCreate or cross-currency Payment transactions, the implementation must perform efficient halt checks:

Asset Halt Check (O(1) operation)

// Pseudo-code for implementation
bool isAssetHalted(Issue const& asset, Hash256 const& userDomainID) {
    // First check for all-domains halt (could be stored with any domain ID)
    auto allDomainsKeylet = keylet::marketHalt(asset, uint256{0});
    auto allHalt = view.read(allDomainsKeylet);
    if (allHalt && (allHalt->getFlags() & lsfAllDomains) && allHalt->getFlags() & tfAssetHalt) {
        return true;
    }
    
    // Then check domain-specific halt
    auto domainHalt = view.read(keylet::marketHalt(asset, userDomainID));
    return domainHalt && domainHalt->getFlags() & tfAssetHalt;
}

Check Logic

// In OfferCreate/Payment processing
auto takerGets = tx.getFieldAmount(sfTakerGets);
auto takerPays = tx.getFieldAmount(sfTakerPays);
Hash256 domainID = tx.isFieldPresent(sfDomainID) ? 
    tx.getFieldH256(sfDomainID) : uint256{0};

// Check if either asset is halted
if (isAssetHalted(takerGets.issue(), domainID) || 
    isAssetHalted(takerPays.issue(), domainID)) {
    return tecMARKET_HALTED;
}

This approach ensures:

• O(1) performance: Each check involves at most two keylet lookups per asset
• Minimal overhead: Four lookups maximum per transaction (two assets × two checks each)
• Efficient caching: Keylets can be cached for repeated access within a ledger
• Anti-circumvention: All-domains halts prevent trading domain bypassing
• Comprehensive coverage: Single asset halt blocks all trading pairs involving that asset

RPC Changes

New RPC Method: market_state

Returns the current state of market halts.

Request Format

{
  "method": "market_state",
  "params": [
    {
      "ledger_index": "validated", // Optional
      "assets": [                  // Optional - check specific assets
        {
          "asset": {"currency": "GME", "issuer": "rGMEissuer"},
          "domain_id": "ABCD..." // Optional - defaults to open DEX
        }
      ]
    }
  ]
}

Response Format

{
  "result": {
    "ledger_hash": "ABCD1234...",
    "ledger_index": 54321,
    "asset_halts": [
      {
        "asset": {"currency": "GME", "issuer": "rGMEissuer"},
        "domain_id": "0000000000000000000000000000000000000000000000000000000000000000",
        "domain": "open_dex",
        "all_domains": false,
        "halted": true,
        "halt_timestamp": 743171558,
        "account": "rGMEissuer"
      }
    ]
  }
}

Modified RPC Methods

The following existing RPC methods will return appropriate error responses when querying halted assets:

• book_offers: Returns rpcMARKET_HALTED error for halted assets
• path_find: Excludes halted assets from path calculations
• ripple_path_find: Excludes halted assets from path calculations

Error Codes

New Transaction Error Codes

• tecMARKET_HALTED: Market trading is currently halted
• tecNO_PERMISSION: Account lacks authority to halt/unhalt
• tecMALFORMED: Asset is already halted
• tecMALFORMED: Asset is not currently halted

New RPC Error Codes

• rpcMARKET_HALTED: Requested operation involves halted market

Security Considerations

Authority Management

• Asset halt authority is limited to token issuers only

Race Conditions

The distributed nature of the XRPL means there may be a brief window where:

1. A halt transaction is submitted at time T
2. Offer transactions are submitted before time T but processed after the halt takes effect
3. These offers will be rejected with tecMARKET_HALTED

This is the intended behavior and provides the guarantee that no offers will be accepted once a halt is in a validated ledger.

Audit Trail

All halt/unhalt activities are permanently recorded in the ledger, providing a complete audit trail for regulatory compliance.

Performance Analysis

Memory Overhead

• Per-asset halt: New ledger object per halted asset per domain (~200 bytes each)
• Total overhead: Minimal - scales linearly with number of halted assets

Processing Overhead

• Asset check: O(1) keylet lookup per asset
• Combined overhead: Maximum four keylet lookups per transaction (two assets, two checks each)
• Cache efficiency: High - halt objects likely cached

Network Impact

• Halt transactions: Standard transaction processing overhead
• RPC queries: Minimal additional load
• Consensus impact: Negligible

Implementation Notes

Keylet Definitions

// New keylet for market halt state including domain
inline Keylet marketHalt(Issue const& asset, Hash256 const& domainID) noexcept {
    return {ltMARKET_HALT, sha512Half(HashPrefix::marketHalt, asset, domainID)};
}

Backward Compatibility

This amendment maintains full backward compatibility with:

• All existing XRPL functionality
• XLS-81d (Permissioned DEXes) - operates independently
• Existing RPC interfaces (with additions only)

Examples

Example 1: All-Domains Asset Halt

1. Major GME corporate event requires complete trading halt
2. GME issuer submits MarketHalt with tfAssetHalt | tfAllDomains flags
3. ALL GME trading is halted across all domainIDs
4. Users cannot circumvent by switching domains
5. Direct GME payments continue unaffected

Example 2: Domain-Specific Asset Halt

1. GME issuer wants to halt trading on a specific DomainID
2. Submits MarketHalt with GME asset, DomainID=uint256{1234...}, and tfAssetHalt flag
3. All GME trading pairs halted on DomainID 1234...

Example 1: All-Pairs Asset Halt

1. GME issuer wants to halt trading on all pairs
2. Submits MarketHalt with GME asset and tfAssetHalt flag
3. All GME trading pairs halted
4. GME trading in permissioned domains continues normally