Permissioned DEX use case & related edits

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
 

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
 

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
 

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.

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)