From fec7a814e552e14f83a2980f6763c9313eacb0df Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Tue, 9 Sep 2025 12:04:04 -0700 Subject: [PATCH 1/4] Start pDEX use case --- ...rency-payments-using-a-permissioned-dex.md | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 docs/use-cases/defi/enable-compliant-cross-currency-payments-using-a-permissioned-dex.md diff --git a/docs/use-cases/defi/enable-compliant-cross-currency-payments-using-a-permissioned-dex.md b/docs/use-cases/defi/enable-compliant-cross-currency-payments-using-a-permissioned-dex.md new file mode 100644 index 0000000000..61a6606099 --- /dev/null +++ b/docs/use-cases/defi/enable-compliant-cross-currency-payments-using-a-permissioned-dex.md @@ -0,0 +1,47 @@ +--- +seo: + description: Learn how a payments provider business can enable regulation-compliant 24/7 cross-currency payments using a permissioned on-chain decentralized exchange (DEX). +--- +# Enable Regulation Compliant Cross-Currency Payments Using a Permissioned DEX + +Payments provider businesses today can leverage cryptocurrency to enable low-cost global settlement in a variety of assets. But currency conversion (FX) is still a challenge: it may use off-chain, centralized exchanges (CEX); or it may use an on-chain, open decentralized exchange (DEX). Both of these models come with significant friction, which can be alleviated by instead using an on-chain, permissioned decentralized exchange (pDEX). + +This page explains how a payments provider can use the features of the XRP Ledger to enable fast, efficient cross-currency payments by creating and managing a permissioned DEX. + + +## Background: The challenges with other modes of currency exchange + +Cross-border payments often involve two to three currencies, which need to be exchanged as part of the payment process: + +- The sending currency provided by the sender. +- The receiving currency paid out to the beneficiary. +- Possibly a bridge currency, such as a cryptocurrency that is used to connect two off-chain, centralized exchanges located in different countries. + +Whether or not you use a bridge currency, at least one currency exchange must happen to facilitate the payment, and there are different challenges depending on where that exchange takes place. + +### Open DEX: Compliance challenges + +Open DEX models are a non-starter for many businesses mindful about complying with global financial regulations, because the open and pseudonymous nature of the exchange makes it almost impossible to comply with Know-Your-Customer (KYC), Anti Money Laundering (AML), and global sanctions regulations. Because an open DEX is available for anyone to use, there are no guarantees that a trade won't be matched with trades placed by strangers or sanctioned entities. + +### Centralized Exchanges: Operational challenges + +Off-chain, centralized exchanges (CEX) are more commonly used by payments providers, but this business practice comes with significant downsides, including: + +- **Compliance Redundancy:** Users may need to go through KYC processes multiple times: once with the payment provider and once with the CEX. +- **Poor Reliability:** Centralized exchanges tend to have significantly more outages than on-chain decentralized exchanges. These incidents are disruptive, and payments that failed during an outage can take a long time to correct. Additionally, if the payment involves multiple centralized exchanges, that multiplies the chances that at least one of them will have an ongoing incident at any given time. +- **High Costs:** Centralized exchanges typically charge a trading fee, plus there may be costs for onboarding and KYC processes, in addition to the spread in the currency exchange rates. +- **Loss of Control:** Relying on a centralized exchange, an external entity from the perspective of the payment provider, limits how much oversight and control the provider can exert over the overall payment lifecycle. + + +## Solution: Permissioned DEX on the XRP Ledger + +By setting up a permissioned DEX (pDEX) on the XRP Ledger, a payments provider can run its own regulated marketplace for currency conversion, getting the benefits of a decentralized exchange without the compliance risk: + +- **Single KYC Touchpoint:** All parties can be verified and vetted using the same credential issuer, without having to repeatedly go through KYC steps with each business. +- **Automatic Compliance:** The payments provider only has to select an appropriate set of credentials, and the XRPL's Permissioned Domains feature automatically restricts access to the pDEX so that only those who hold the credentials can participate. +- **End-to-End Control:** The payments provider has full control over the payments lifecycle and isn't dependent on CEX processing times, opaque matching algorithms, or similar limitations. +- **Operational Resilience:** The XRP Ledger's battle-tested, highly stable blockchain and decentralized exchange technology powers the software side, so the payment provider can count on the DEX being operational, with no exposure to risk of outages at any CEX, and extremely high reliability. +- **Lower Cost Base:** Using a pDEX eliminates trading fees and reduces the onboarding overhead. + + +## How to Set Up a Permissioned DEX From 00c98cf68f2e700947769fbf31304603576fb152 Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Wed, 10 Sep 2025 17:54:27 -0700 Subject: [PATCH 2/4] Further flesh out pDEX use case page --- ...rency-payments-using-a-permissioned-dex.md | 40 ++++++++++++++++++- sidebars.yaml | 1 + 2 files changed, 40 insertions(+), 1 deletion(-) diff --git a/docs/use-cases/defi/enable-compliant-cross-currency-payments-using-a-permissioned-dex.md b/docs/use-cases/defi/enable-compliant-cross-currency-payments-using-a-permissioned-dex.md index 61a6606099..2b3142302c 100644 --- a/docs/use-cases/defi/enable-compliant-cross-currency-payments-using-a-permissioned-dex.md +++ b/docs/use-cases/defi/enable-compliant-cross-currency-payments-using-a-permissioned-dex.md @@ -44,4 +44,42 @@ By setting up a permissioned DEX (pDEX) on the XRP Ledger, a payments provider c - **Lower Cost Base:** Using a pDEX eliminates trading fees and reduces the onboarding overhead. -## How to Set Up a Permissioned DEX +## How to set up a permissioned DEX + +Running a permissioned DEX involves several steps: + +1. **Select a credential issuer.** +2. **Create a permissioned domain.** +3. **Use the domain ID in payments & offers.** + +### Select a credential issuer + +The credential issuer performs identity verification or compliance checks, and issues on-chain credentials to users who pass the checks. You can be a credential issuer yourself, or rely on another business to issue credentials that meet your requirements. + +{% admonition type="success" name="Tip" %} +If you run a credential issuing service, don't forget to issue yourself a credential too, so that you can access the permissioned DEX. +{% /admonition %} + +More information: + +- [Credentials](../../concepts/decentralized-storage/credentials.md) +- [Become a Credential Issuing Service](../../tutorials/python/build-apps/credential-issuing-service.md) + +### Create a permissioned domain + +A permissioned domain uses credentials to control who can access a permissioned DEX. As the owner of the permissioned domain, you control which credentials it accepts. + +More information: + +- [Permissioned Domains](../../concepts/tokens/decentralized-exchange/permissioned-domains.md) +- [Create Permissioned Domains](../../tutorials/javascript/compliance/create-permissioned-domains.md) + +### Use the domain ID in payments and offers + +After setting up the permissioned domain, you specify its ID in your offers and cross-currency payments to restrict them to the permissioned DEX. You need others to place offers in the same pDEX to have something to match, so it's important to make sure that one or more market makers hold the relevant credentials and place offers in the pDEX too. Market makers with different compliance requirements can also place hybrid offers that can use both a pDEX and the open DEX. + +More information: + +- [Permissioned DEXes](../../concepts/tokens/decentralized-exchange/permissioned-dexes.md) +- [Cross-Currency Payments](../../concepts/payment-types/cross-currency-payments.md) +- [Offers](../../concepts/tokens/decentralized-exchange/offers.md) diff --git a/sidebars.yaml b/sidebars.yaml index dd267c1267..1b9ec741ce 100644 --- a/sidebars.yaml +++ b/sidebars.yaml @@ -41,6 +41,7 @@ items: - page: docs/use-cases/defi/algorithmic-trading.md - page: docs/use-cases/defi/list-xrp-as-an-exchange.md + - page: docs/use-cases/defi/enable-compliant-cross-currency-payments-using-a-permissioned-dex.md - page: docs/concepts/index.md expanded: false From 4ef1a6cd83cf1da1d9386215baa0daebea7cfa44 Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Thu, 11 Sep 2025 17:14:34 -0700 Subject: [PATCH 3/4] Permissioned DEX use case & related edits --- .../decentralized-storage/credentials.md | 4 +- .../tokens/decentralized-exchange/offers.md | 10 +++++ .../permissioned-dexes.md | 2 + .../permissioned-domains.md | 2 +- ...rency-payments-using-a-permissioned-dex.md | 38 +++++++++++-------- 5 files changed, 38 insertions(+), 18 deletions(-) diff --git a/docs/concepts/decentralized-storage/credentials.md b/docs/concepts/decentralized-storage/credentials.md index 72504b4f66..dfb6791a44 100644 --- a/docs/concepts/decentralized-storage/credentials.md +++ b/docs/concepts/decentralized-storage/credentials.md @@ -5,11 +5,11 @@ status: not_enabled --- # Credentials -The Credentials feature is a set of tools for managing authorization and compliance requirements using the XRP Ledger blockchain, while respecting privacy and decentralization. This feature extends and interconnects with other features of the XRP Ledger including [Deposit Authorization](../../concepts/accounts/depositauth.md)). The goal of this feature is to streamline the process of compliance checks such as [KYC (Know Your Customer)](https://en.wikipedia.org/wiki/Know_your_customer) and to enable further trust-based applications within the XRP Ledger ecosystem. +The Credentials feature is a set of tools for managing authorization and compliance requirements using the XRP Ledger blockchain, while respecting privacy and decentralization. Credentials can be used for [Deposit Authorization](../accounts/depositauth.md) as well as [permissioned domains](../tokens/decentralized-exchange/permissioned-domains.md). Credentials can streamline the process of compliance checks such as [KYC (Know Your Customer)](https://en.wikipedia.org/wiki/Know_your_customer) and to enable further trust-based applications within the XRP Ledger ecosystem. The design of the Credentials standard draws from the [W3C Verifiable Credentials standard](https://www.w3.org/TR/vc-data-model-2.0/). It is intended to be compatible to an extent that makes sense in the context of the XRP Ledger. There are some differences in data structures and formatting: for example, the subject of a credential is identified by an XRP Ledger address rather than a URL. -_(Requires the [Credentials amendment][] {% not-enabled /%})_ +{% amendment-disclaimer name="Credentials" /%} ## Overview diff --git a/docs/concepts/tokens/decentralized-exchange/offers.md b/docs/concepts/tokens/decentralized-exchange/offers.md index 04b6af8f19..30e3c7ae89 100644 --- a/docs/concepts/tokens/decentralized-exchange/offers.md +++ b/docs/concepts/tokens/decentralized-exchange/offers.md @@ -98,6 +98,16 @@ This is a consequence of how the network reaches agreement. For the entire peer- {% admonition type="info" name="Note" %}Expired Offers remain in the ledger data until a transaction removes them. Until then, they can continue to appear in data retrieved from the API (for example, using the [ledger_entry method][]). Transactions automatically delete any expired and unfunded Offers they find, usually while executing Offers or cross-currency payments that would have matched or canceled them. The owner reserve associated with an Offer is only made available again when the Offer is actually deleted.{% /admonition %} +## Permissioned and Hybrid Offers + +{% amendment-disclaimer name="PermissionedDEX" /%} + +By specifying a valid **permissioned domain ID**, you can place offers into a permissioned DEX instead of using the open DEX. You can only place a _permissioned offer_ if you hold the [credentials](../../decentralized-storage/credentials.md) required by the permissioned domain, and permissioned offers can only match other offers in the same permissioned domain. You can also place a _hybrid offer_ by using a domain ID and the Hybrid flag. Hybrid offers work like permissioned offers except that they can also match offers in the open DEX. Businesses with strict compliance requirements may want to use a permissioned DEX exclusively while traders with more relaxed compliance requirements can use hybrid offers to provide liquidity in more places. + +In most ways, permissioned and hybrid offers function like regular offers. They support all the same options, such as Fill-or-Kill, and are subject to the same requirements like the reserve per offer. One difference is that offers in a permissioned DEX can become _invalid_ if the account placing the offer loses access to the permissioned domain, for example because their credentials expired. + +For more information, see [Permissioned DEXes](./permissioned-dexes.md). + ## See Also diff --git a/docs/concepts/tokens/decentralized-exchange/permissioned-dexes.md b/docs/concepts/tokens/decentralized-exchange/permissioned-dexes.md index a45b2fc144..dd3e996dcf 100644 --- a/docs/concepts/tokens/decentralized-exchange/permissioned-dexes.md +++ b/docs/concepts/tokens/decentralized-exchange/permissioned-dexes.md @@ -11,6 +11,8 @@ Permissioned DEXes are controlled environments for trading within the XRP Ledger There can be multiple permissioned DEXes within the XRP Ledger blockchain. Each one is uniquely associated with a permissioned domain, which acts as an allow-list for accessing that DEX. Trades placed within a permissioned DEX can only execute against other trades in the same permissioned DEX. Each permissioned DEX can have order books for any number of currency pairs, as needed. +{% amendment-disclaimer name="PermissionedDEX" /%} + ## Background: The Need for Permissioned DEXes diff --git a/docs/concepts/tokens/decentralized-exchange/permissioned-domains.md b/docs/concepts/tokens/decentralized-exchange/permissioned-domains.md index ab21159264..621c303c75 100644 --- a/docs/concepts/tokens/decentralized-exchange/permissioned-domains.md +++ b/docs/concepts/tokens/decentralized-exchange/permissioned-domains.md @@ -13,7 +13,7 @@ The only configurable rule for a domain is the set of accepted [credentials][]. Anyone can define a permissioned domain in the ledger. That person becomes the owner of that domain, and can update its settings or delete it. The only limit to the number of domains that can exist in the ledger is the reserve requirement: each Domain counts as one item toward its owner's reserve requirement. -_(Requires the [PermissionedDomains amendment][] {% not-enabled /%})_ +{% amendment-disclaimer name="PermissionedDomains" /%} {% admonition type="info" name="Note" %} The [Credentials amendment][] is also required. If the [PermissionedDomains amendment][] is enabled without Credentials, PermissionedDomainSet transactions are considered invalid. diff --git a/docs/use-cases/defi/enable-compliant-cross-currency-payments-using-a-permissioned-dex.md b/docs/use-cases/defi/enable-compliant-cross-currency-payments-using-a-permissioned-dex.md index 2b3142302c..b6596cfc1d 100644 --- a/docs/use-cases/defi/enable-compliant-cross-currency-payments-using-a-permissioned-dex.md +++ b/docs/use-cases/defi/enable-compliant-cross-currency-payments-using-a-permissioned-dex.md @@ -1,6 +1,7 @@ --- seo: description: Learn how a payments provider business can enable regulation-compliant 24/7 cross-currency payments using a permissioned on-chain decentralized exchange (DEX). +status: not_enabled --- # Enable Regulation Compliant Cross-Currency Payments Using a Permissioned DEX @@ -8,6 +9,7 @@ Payments provider businesses today can leverage cryptocurrency to enable low-cos This page explains how a payments provider can use the features of the XRP Ledger to enable fast, efficient cross-currency payments by creating and managing a permissioned DEX. +{% amendment-disclaimer name="PermissionedDEX" /%} ## Background: The challenges with other modes of currency exchange @@ -48,38 +50,44 @@ By setting up a permissioned DEX (pDEX) on the XRP Ledger, a payments provider c Running a permissioned DEX involves several steps: -1. **Select a credential issuer.** -2. **Create a permissioned domain.** -3. **Use the domain ID in payments & offers.** +1. **[Select a credential issuer.](#select-a-credential-issuer)** +2. **[Create a permissioned domain.](#create-a-permissioned-domain)** +3. **[Use the domain ID in payments & offers.](#use-the-domain-id-in-payments-and-offers)** ### Select a credential issuer -The credential issuer performs identity verification or compliance checks, and issues on-chain credentials to users who pass the checks. You can be a credential issuer yourself, or rely on another business to issue credentials that meet your requirements. +The credential issuer performs identity verification or compliance checks, and issues on-chain credentials to users who pass the checks. You can be a credential issuer yourself, or rely on another business to issue credentials that meet your requirements. Typically, the flow for using credentials involves three steps: + +1. The subject of the credential sends their personal documentation confidentially to the issuer, off-chain. The credential issuer has full discretion over which documents they request. +2. If the subject passes inspection, the credential issuer creates a credential on the XRP Ledger issued to the subject's XRPL account. +3. The subject needs to accept the credential, using their XRPL account, for it to become valid. + +For more information, see: + +- [Credentials](../../concepts/decentralized-storage/credentials.md) +- [Become a Credential Issuing Service](../../tutorials/python/build-apps/credential-issuing-service.md) {% admonition type="success" name="Tip" %} If you run a credential issuing service, don't forget to issue yourself a credential too, so that you can access the permissioned DEX. {% /admonition %} -More information: - -- [Credentials](../../concepts/decentralized-storage/credentials.md) -- [Become a Credential Issuing Service](../../tutorials/python/build-apps/credential-issuing-service.md) - ### Create a permissioned domain -A permissioned domain uses credentials to control who can access a permissioned DEX. As the owner of the permissioned domain, you control which credentials it accepts. - -More information: +A permissioned domain uses credentials to control who can access a permissioned DEX. As the owner of the permissioned domain, you control which credentials it accepts. A domain can accept one or several credentials, so that anyone who holds any of the specified credentials gains access. For more information, see: - [Permissioned Domains](../../concepts/tokens/decentralized-exchange/permissioned-domains.md) - [Create Permissioned Domains](../../tutorials/javascript/compliance/create-permissioned-domains.md) -### Use the domain ID in payments and offers +### Use the permissioned DEX to facilitate payments and offers -After setting up the permissioned domain, you specify its ID in your offers and cross-currency payments to restrict them to the permissioned DEX. You need others to place offers in the same pDEX to have something to match, so it's important to make sure that one or more market makers hold the relevant credentials and place offers in the pDEX too. Market makers with different compliance requirements can also place hybrid offers that can use both a pDEX and the open DEX. +After setting up a permissioned domain, the permissioned DEX is ready to use. Anyone who has the appropriate credentials automatically has access to trade in the pDEX by specifying its domain ID in their offers and cross-currency payments. Like any exchange, it needs liquidity to function, so this step actually consists of two parts: -More information: +1. Recruit market makers to place offers in the permissioned DEX. Make sure they have accepted a matching credential and they know what domain ID to use. +2. Use the permissioned DEX when making your own cross currency payments or offers. + +For more information, see: - [Permissioned DEXes](../../concepts/tokens/decentralized-exchange/permissioned-dexes.md) - [Cross-Currency Payments](../../concepts/payment-types/cross-currency-payments.md) - [Offers](../../concepts/tokens/decentralized-exchange/offers.md) +- [Trade in the Decentralized Exchange](../../tutorials/how-tos/use-tokens/trade-in-the-decentralized-exchange.md) From 47d56ceb118386904dff02041faa1389e92f016b Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Tue, 23 Sep 2025 11:47:18 -0700 Subject: [PATCH 4/4] Adjust pDEX use case title per review --- ...cused-cross-currency-payments-using-a-permissioned-dex.md} | 4 ++-- sidebars.yaml | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) rename docs/use-cases/defi/{enable-compliant-cross-currency-payments-using-a-permissioned-dex.md => enable-compliance-focused-cross-currency-payments-using-a-permissioned-dex.md} (97%) diff --git a/docs/use-cases/defi/enable-compliant-cross-currency-payments-using-a-permissioned-dex.md b/docs/use-cases/defi/enable-compliance-focused-cross-currency-payments-using-a-permissioned-dex.md similarity index 97% rename from docs/use-cases/defi/enable-compliant-cross-currency-payments-using-a-permissioned-dex.md rename to docs/use-cases/defi/enable-compliance-focused-cross-currency-payments-using-a-permissioned-dex.md index b6596cfc1d..0190a831d8 100644 --- a/docs/use-cases/defi/enable-compliant-cross-currency-payments-using-a-permissioned-dex.md +++ b/docs/use-cases/defi/enable-compliance-focused-cross-currency-payments-using-a-permissioned-dex.md @@ -1,9 +1,9 @@ --- seo: - description: Learn how a payments provider business can enable regulation-compliant 24/7 cross-currency payments using a permissioned on-chain decentralized exchange (DEX). + description: Learn how a payments provider business can enable cross-currency payments using a permissioned on-chain decentralized exchange (DEX). status: not_enabled --- -# Enable Regulation Compliant Cross-Currency Payments Using a Permissioned DEX +# Enable Compliance-Focused Cross-Currency Payments Using a Permissioned DEX Payments provider businesses today can leverage cryptocurrency to enable low-cost global settlement in a variety of assets. But currency conversion (FX) is still a challenge: it may use off-chain, centralized exchanges (CEX); or it may use an on-chain, open decentralized exchange (DEX). Both of these models come with significant friction, which can be alleviated by instead using an on-chain, permissioned decentralized exchange (pDEX). diff --git a/sidebars.yaml b/sidebars.yaml index 1b9ec741ce..acfe590278 100644 --- a/sidebars.yaml +++ b/sidebars.yaml @@ -41,7 +41,7 @@ items: - page: docs/use-cases/defi/algorithmic-trading.md - page: docs/use-cases/defi/list-xrp-as-an-exchange.md - - page: docs/use-cases/defi/enable-compliant-cross-currency-payments-using-a-permissioned-dex.md + - page: docs/use-cases/defi/enable-compliance-focused-cross-currency-payments-using-a-permissioned-dex.md - page: docs/concepts/index.md expanded: false