0081 XLS-81d: Permissioned DEXes #229
mvadari
started this conversation in
Standard Proposals
Replies: 4 comments
-
This is fantastic. I hope to be a factoring contributor to this development. |
Beta Was this translation helpful? Give feedback.
0 replies
-
Really well thought out practical and comprehensive proposal. |
Beta Was this translation helpful? Give feedback.
0 replies
-
A minor update to this spec was published today, 2024-09-25. Token-gating support was removed, as per the change in XLS-80d. |
Beta Was this translation helpful? Give feedback.
0 replies
-
Great, looking forward to the next article. |
Beta Was this translation helpful? Give feedback.
0 replies
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
Permissioned DEXes
Abstract
Decentralized Exchanges (DEXes) are revolutionizing finance due to their ability to offer significant benefits such as intermediary elimination, lower transaction costs, enhanced security, and user asset custody. These advantages align perfectly with the growing demand for efficient financial systems. However, a major hurdle hinders wider adoption by traditional institutions: the anonymity of a DEX makes it difficult to comply with Anti-Money Laundering (AML) and Know Your Customer (KYC) regulations.
This challenge highlights a critical need for the development of a permissioned system within DEXes. Such a system would allow institutions to adhere to regulations while still benefiting from the core advantages of blockchain technology.
This proposal introduces a permissioned DEX system for the XRPL. By integrating permissioning features directly within the DEX protocol, regulated financial institutions gain the ability to participate in the XRPL's DEX while still adhering to their compliance requirements. This approach avoids the drawbacks of isolated, permissioned tokens or private blockchains, ensuring a vibrant and liquid marketplace that facilitates seamless arbitrage opportunities. Ultimately, this permissioned DEX system paves the way for wider institutional adoption of XRPL, fostering a more inclusive and efficient financial landscape.
1. Overview
This proposal builds on top of XLS-80d, Permissioned Domains, as Permissioned Domains are needed to handle the permissioning aspect.
We propose:
Offer
ledger object.OfferCreate
transaction.Payment
transaction.This feature will require an amendment, tentatively titled
featurePermissionedDEX
. The the orderbook and pathing-related RPCs will also need to be updated.1.1. Background: The Current State of Permissioning and Compliance on the XRPL
The XRPL has made significant strides toward a compliance-by-design framework, incorporating several features to enhance transparency and control. These tools aim to facilitate regulatory adherence while preserving the platform's decentralized ethos.
They include:
While these features provide an excellent foundation for compliance, they fall short in one crucial area: the use of the DEX.
1.2. Terminology
1.3. Basic Flow
1.3.1. Initial Setup
1.3.2. Trading Scenario 1
1.3.3. Trading Scenario 2
1.4. How Domains Work
A permissioned offer will only be filled by valid domain offers.
An open offer can be filled by any open offer on the open DEX, but cannot be filled by a permissioned offer. Likewise, any permissioned offer cannot be filled by an open offer.
2. On-Ledger Object:
Offer
The
Offer
object tracks an offer placed on the CLOB DEX. This object type already exists on the XRPL, but is being extended as a part of this spec to also support permissioned DEX domains.2.1. Fields
As a reference, here are the existing fields for the
Offer
object.Account
string
AccountID
BookDirectory
string
Hash256
BookNode
string
UInt64
Expiration
number
UInt32
LedgerEntryType
string
UInt16
0x006F
, mapped to the stringOffer
, indicates that this is an offer entry.OwnerNode
string
UInt64
PreviousTxnID
string
Hash256
PreviousTxnLgrSeq
number
UInt32
Sequence
number
UInt32
Sequence
value of theOfferCreate
transaction that created this offer. Used in combination with theAccount
to identify this offer.TakerPays
object
Amount
TakerGets
object
Amount
This spec proposes these additions:
DomainID
string
Hash256
2.1.1.
DomainID
A permissioned offer has a
DomainID
field included.An open offer does not include a
DomainID
field.2.2. Offer Invalidity
A permissioned offer on the orderbook can become invalid if:
DomainID
field is deleted.An invalid offer will be processed similarly to an unfunded offer, where it is deleted if and when processed/crossed.
3. On-Ledger Object:
DirectoryNode
The
Offer
object tracks an offer placed on the CLOB DEX.The
DirectoryNode
ledger entry type provides a list of links to other entries in the ledger's state data. A single conceptual Directory takes the form of a doubly linked list, with one or moreDirectoryNode
entries each containing up to 32 IDs of other entries. The firstDirectoryNode
entry is called the root of the directory, and all entries other than the root can be added or deleted as necessary.This object type already exists on the XRPL, but is being extended as a part of this spec to also support permissioned DEX domains.
There are three types of directories: owner directories (for the objects an account owns), offer directories (for offers in the orderbook), and NFT offer directories (for NFT offers). The proposed modifications only concern offer directories.
3.1. Fields
As a reference, here are the existing fields for the
DirectoryNode
object.Flags
number
UInt32
DirectoryNode
objects. The value is always0
.Indexes
array
Vector256
IndexNext
number
UInt64
IndexPrevious
number
UInt64
LedgerEntryType
string
UInt16
0x0064
, mapped to the stringDirectoryNode
, indicates that this object is part of a directory.RootIndex
string
Hash256
TakerGetsCurrency
string
Hash160
TakerGets
amount from the offers in this directory.TakerGetsIssuer
string
Hash160
TakerGets
amount from the offers in this directory.TakerPaysCurrency
string
Hash160
TakerPays
amount from the offers in this directory.TakerPaysIssuer
string
Hash160
TakerPays
amount from the offers in this directory.This spec proposes these additions:
DomainID
string
Hash256
3.1.1.
DomainID
A domain has its own set of orderbooks.
3.2. Object ID
The proposed modification is in bold.
There are three different formulas for creating the ID of a DirectoryNode, depending on which of the following the DirectoryNode represents:
The first page of an Offer directory has a special ID: the higher 192 bits define the order book, and the remaining 64 bits define the exchange rate of the offers in that directory. (The ID is big-endian, so the book is in the more significant bits, which come first, and the quality is in the less significant bits which come last.) This provides a way to iterate through an order book from best offers to worst. Specifically: the first 192 bits are the first 192 bits of the SHA-512Half of the following values, concatenated in order:
0x0042
)TakerPaysCurrency
TakerGetsCurrency
TakerPaysIssuer
TakerGetsIssuer
DomainID
of the orderbook, if applicableThe lower 64 bits of an Offer directory's ID represent the
TakerPays
amount divided byTakerGets
amount from the offer(s) in that directory as a 64-bit number in the XRP Ledger's internal amount format.If the DirectoryNode is not the first page in the directory, it has an ID that is the SHA-512Half of the following values, concatenated in order:
0x0064
)4. Transaction:
OfferCreate
The
OfferCreate
transaction creates an offer on the CLOB DEX. This transaction type already exists on the XRPL, but is being extended as a part of this spec to also support permissioned DEX domains.4.1. Fields
As a reference, here are the existing fields for the
OfferCreate
transaction.Expiration
number
UInt32
OfferSequence
number
UInt32
OfferCancel
.TakerGets
string
Amount
TakerPays
string
Amount
We propose these additions:
DomainID
string
Hash256
4.2. Failure Conditions
The existing set of failure conditions for
OfferCreate
will continue to exist.The following will be added, if the
DomainID
field is included:4.3. State Changes
The existing set of state changes for
OfferCreate
will continue to exist.If the
DomainID
is included in theOfferCreate
transaction, the DEX will use the domain-specific orderbook to process the offer.5. Transaction:
Payment
A
Payment
transaction represents a transfer of value from one account to another, and can involve currency conversions and crossing the orderbook. This transaction type already exists on the XRPL, but is being extended as a part of this spec to also support permissioned DEX domains.5.1. Fields
As a reference, here are the existing fields for the
Payment
transaction.Amount
string
Amount
tfPartialPayment
flag is set, deliver up to this amount instead.DeliverMin
string
Amount
Destination
string
AccountID
DestinationTag
number
UInt32
InvoiceID
string
Hash256
Paths
array
PathSet
SendMax
string
orobject
Amount
We propose these additions:
DomainID
string
Hash256
5.1.1.
DomainID
The
DomainID
can only be included if the payment is a cross-currency payment (i.e. if the payment is going to interact with the DEX). It should only be included if the payment is permissioned.5.2. Failure Conditions
The existing set of failure conditions for
Payment
will continue to exist.There will also be the following in addition, if the
DomainID
is included:Account
is not a domain member.Amount
,SendMax
, andDeliverMin
are not permitted as a part of the domain's rules.5.3. State Changes
The existing set of state changes for a successful
Payment
transaction will continue to exist.6. RPC:
book_offers
The
book_offers
RPC method already exists on the XRPL. This proposal suggests some modifications to also support permissioned DEX domains.6.1. Request Fields
As a reference, here are the fields that
book_offers
currently accepts:taker_gets
object
taker_pays
object
ledger_hash
string
ledger_index
number
orstring
limit
number
taker
string
This proposal puts forward the following addition:
domain
string
PermissionedDomain
object. If this field is included, then the offers will be filtered to only show the valid domain offers for that domain.6.2. Response Fields
This proposal does not suggest any changes to the response fields. As a reference, here are the fields that
book_offers
currently returns:ledger_current_index
number
orstring
ledger_index
number
orstring
ledger_hash
string
offers
array
7. RPC:
path_find
The
path_find
RPC method already exists on the XRPL. This proposal suggests some modifications to also support permissioned DEX domains.Only the
create
subcommand will be affected.7.1. Request Fields
As a reference, here are the fields that the
path_find
create
subcommand currently accepts:subcommand
string
"create"
to send the create sub-commandsource_account
string
destination_account
string
destination_amount
string
orobject
send_max
string
orobject
paths
array
This proposal puts forward the following addition:
domain
string
PermissionedDomain
object. If this field is included, then the paths will be filtered to only show the valid paths for that domain.7.2. Response Fields
As a reference, here are the fields that
path_find
currently returns:alternatives
array
destination_account
string
destination_amount
string
orobject
source_account
string
full_reply
boolean
false
, this is the result of an incomplete search. A later reply may have a better path. Iftrue
, then this is the best path found. (It is still theoretically possible that a better path could exist, butrippled
won't find it.) Until you close the pathfinding request,rippled
continues to send updates each time a new ledger closes.This proposal puts forward the following addition:
domain
string
PermissionedDomain
object, if the orderbook shown is for a specific domain.8. RPC:
ripple_path_find
The
ripple_path_find
RPC method already exists on the XRPL. This proposal suggests some modifications to also support permissioned DEX domains.8.1. Request Fields
As a reference, here are the fields that
ripple_path_find
currently accepts:source_account
string
destination_account
string
destination_amount
string
orobject
send_max
string
orobject
source_currencies
.source_currencies
array
currency
field and optionalissuer
field, like how currency amounts are specified.ledger_hash
string
ledger_index
string
ornumber
This proposal puts forward the following addition:
domain
string
PermissionedDomain
object. If this field is included, then the paths will be filtered to only show the valid paths for that domain.8.2. Response Fields
This proposal does not suggest any changes to the response fields. As a reference, here are the fields that
ripple_path_find
currently returns:alternatives
array
destination_account
string
destination_currencies
array
9. RPC:
books
SubscriptionThe
books
subscription option already exists on the XRPL. This proposal suggests some modifications to also support permissioned DEX domains.9.1. Request Fields
As a reference, here are the fields that
books
currently accepts:taker_gets
object
taker_pays
object
taker
string
snapshot
boolean
true
, return the current state of the order book once when you subscribe before sending updates. The default isfalse
.both
boolean
true
, return both sides of the order book. The default isfalse
.This proposal puts forward the following addition:
domain
string
PermissionedDomain
object. If this field is included, then the offers will be filtered to only show the valid domain offers for that domain.9.2. Response Fields
This proposal does not suggest any changes to the response fields. As a reference, here are the fields that the
books
subscription currently returns (as an array):type
string
transaction
indicates this is the notification of a transaction stream, which could come from several possible streams.engine_result
string
engine_result_code
number
engine_result_message
string
ledger_hash
string
ledger_index
number
meta
object
transaction
object
validated
boolean
true
, this transaction is included in a validated ledger and its outcome is final. Responses from thetransaction
stream should always be validated.10. RPC:
book_changes
The
book_changes
RPC method already exists on the XRPL. This proposal suggests some modifications to also support permissioned DEX domains.These changes also apply to the
book_changes
subscription stream.10.1. Request Fields
This proposal does not suggest any changes to the request fields. As a reference, here are the fields that
book_changes
currently accepts:ledger_hash
string
ledger_index
string
validated
.10.2. Response Fields
As a reference, here are the fields that the
book_changes
subscription currently returns:This proposal puts forward the following addition:
domain
string
PermissionedDomain
object, if the orderbook changes are for a specific domain.11. Examples
These examples will be using the following domain:
The domain ID will be
ABCDEF1234567890
.Both Tracy and Marko have a
123ABC
credential from Isabel.11.1. Placing a Permissioned Offer
In this sample
OfferCreate
transaction, Tracy is trading USD for EUR within Owen's domain.11.2. Placing an Unpermissioned Offer
In this sample
OfferCreate
transaction, Marko is trading EUR for USD on the open USD-EUR orderbook. This offer will not cross Tracy's offer, since Tracy's offer is inside the domain.12. Invariants
No permissioned offer with a
DomainID
field will be filled by:No permissioned offer will be placed in:
No open offer will be placed in a permissioned orderbook.
No open offer will be filled by a permissioned offer.
13. Security
The trust assumptions are the same as with permissioned domains.
n+1. Open Questions
DomainID
field should be replaced with aDomainIDs
field (to accommodate a list)Appendix
Appendix A: FAQ
A.1: How are AMMs handled?
AMMs are not explicitly supported within permissioned DEXes in this proposal. They could be added to permissioned DEXes in a future proposal.
A.2: How will performance/TPS be affected from all these additional checks?
Performance tests will need to be conducted once the implementation is done. The spec may be modified if such tests show serious performance reduction.
A.3: Why do you need a domain? Why not just indicate what credentials you accept on the offer itself?
It's much easier to specify a single domain instead of a list of credentials every time, especially since using an incorrect list of credentials would result in accessing a different orderbook.
A.4: Will an account with Deposit Authorization enabled be forced to use Permissioned DEXes?
No.
A.5: Can NFT offers use domains?
This proposal does not include support for NFT offers in domains. However, that could be added later.
A.6: Can an offer be part of multiple domains?
No, multiple offers would need to be placed for it to be in multiple domains.
A.7: Can direct IOU payments be permissioned?
No, because they don't go through the DEX. The issuer and destination can be directly verified for compliance and trust.
Appendix B: Alternate Designs
The Platonic ideal design would involve one orderbook per pair of assets. The trader indicates what domain they want to participate in, and the DEX automatically figures out what offers are okay for that domain to accept and what offers are not, based on the contents of the offer and the account that placed it.
This was essentially one design considered, which involved all of the offers staying in one orderbook. If an offer needed to be in a domain, each offer that crossed it would be checked for offer membership individually (in the same way that offers are checked on whether they're funded). This idea was scrapped due to performance concerns - a permissioned offer might have to iterate through the whole orderbook before finding a matching offer (if one exists).
Beta Was this translation helpful? Give feedback.
All reactions