0080 XLS-80d: Permissioned Domains

[mvadari]

Title:       Permissioned Domains
Revision:    2 (2024-09-25)

Author:      Mayukha Vadari

Affiliation: Ripple

Permissioned Domains

Abstract

This proposal introduces the concept of permissioned domains. Permissioned domains enable the creation of controlled environments within a broader system where specific rules and restrictions can be applied to user interactions and asset flow. This approach aims to bridge the gap between the transparency and security benefits of decentralized blockchain technology and the regulatory requirements of traditional financial institutions.

1. Overview

This proposal builds on top of XLS-70d, as credentials are needed for permissioning.

We propose:

• Creating a PermissionedDomain ledger object.
• Creating a PermissionedDomainSet transaction.
• Creating a PermissionedDomainDelete transaction.

This feature will require an amendment. Since this feature doesn't bring any functionality to the XRPL by itself, it will be gated by other amendments that use it instead.

1.1. Terminology

• Domain: A collection of rules indicating what accounts may be a part of it. This spec includes credential-gating, but more options could be added in the future. A domain is focused on "who can participate". The "how they can participate" (e.g. what tokens they may use) aspect can be done in other ways in the primitives they're used.
• Domain Rules: The set of rules that govern a domain, i.e. the credentials it accepts.
• Domain Owner: The account that created a domain, and is the only one that can modify its rules or delete it.
• Domain Member: An account that satisfies the rules of the domain (i.e. has one of the credentials that are accepted by the domain). There is no explicit joining step; as long as the account has a valid credential, it is a member.

2. On-Ledger Object: PermissionedDomain

This object represents a permissioned domain.

2.1. Fields

Field Name	Required?	JSON Type	Internal Type	Description
LedgerIndex	✔️	string	Hash256	The unique ID of the ledger object.
Flags	✔️	number	UInt32	Flag values associated with this object.
LedgerEntryType	✔️	string	UInt16	The ledger object's type (PermissionedDomain).
Owner	✔️	string	AccountID	The account that controls the settings of the domain.
Sequence	✔️	number	UInt32	The Sequence value of the PermissionedDomainSet transaction that created this domain. Used in combination with the Account to identify this domain.
AcceptedCredentials	✔️	array	STArray	The credentials that are accepted by the domain. Ownership of one of these credentials automatically makes you a member of the domain.
PreviousTxnID	✔️	string	Hash256	The identifying hash of the transaction that most recently modified this entry.
PreviousTxnLgrSeq	✔️	number	UInt32	The ledger index that contains the transaction that most recently modified this object.

2.1.1. LedgerIndex

The ID of this object will be a hash that incorporates the Owner and Sequence fields, combined with a unique space key for PermissionedDomain objects, which will be defined during implementation.

This value will be used wherever a DomainID is required.

2.1.2. AcceptedCredentials

This is an array of inner objects referencing a type of credential. The maximum length of this array is 10.

The array will be sorted by Issuer, so that searching it for a match is more performant.

If this field is not included in the domain, then credentials do not need to be used when interacting with anything using the domain (i.e. there are no credential-based rules).

Field Name	Required?	JSON Type	Internal Type	Description
Issuer	✔️	string	AccountID	The issuer of the credential.
CredentialType	✔️	string	Blob	A value to identify the type of credential from the issuer.

2.2. Account Deletion

The PermissionedDomain object is a deletion blocker.

3. Transaction: PermissionedDomainSet

This transaction creates or modifies a PermissionedDomain object.

3.1. Fields

Field Name	Required?	JSON Type	Internal Type	Description
TransactionType	✔️	string	UInt16	The transaction type (PermissionedDomainSet).
Flags		number	UInt32	Set of bit-flags for this transaction.
Account	✔️	string	AccountID	The account sending the transaction.
DomainID		string	Hash256	The domain to modify. Must be included if modifying an existing domain.
AcceptedCredentials	✔️	array	STArray	The credentials that are accepted by the domain. Ownership of one of these credentials automatically makes you a member of the domain. An empty array means deleting the field.

3.2. Failure Conditions

• Issuer doesn't exist on one or more of the credentials in AcceptedCredentials.
• The AcceptedCredentials array is empty or too long (limit 10).
• If DomainID is included:
  • That domain doesn't exist.
  • The Account isn't the domain owner.

3.3. State Changes

If the transaction is successful:

• It creates or modifies a PermissionedDomain object.

4. Transaction: PermissionedDomainDelete

This transaction deletes a PermissionedDomain object.

4.1. Fields

Field Name	Required?	JSON Type	Internal Type	Description
TransactionType	✔️	string	UInt16	The transaction type (PermissionedDomainDelete).
Account	✔️	string	AccountID	The account sending the transaction.
DomainID	✔️	string	Hash256	The domain to delete.

4.2. Failure Conditions

• The domain specified in DomainID doesn't exist.
• The account isn't the owner of the domain.

4.3. State Changes

If the transaction is successful:

• It deletes a PermissionedDomain object.

5. Examples

A sample domain object may look like this (ignoring common fields):

{
  Owner: "rOWEN......",
  Sequence: 5,
  AcceptedCredentials: [
    {
      Credential: {
        Issuer: "rISABEL......",
        CredentialType: "123ABC"
      }
    }
  ]
}

6. Invariants

• You cannot have a domain with no rules.
• The AcceptedCredentials array must have length between 1 and 10, if included.

7. Security

7.1. Issuer Trust

Relying on external issuers for credentials requires a degree of trust. If issuer credentials are compromised or forged, the system will be vulnerable.

7.2. Domain Creator Trust

While users can create their own domains, trust in the domain creator remains crucial. Malicious domain creators (or hackers) could potentially expose domain users to illegal liquidity.

Appendix

Appendix A: FAQ

A.1: Why is the name PermissionedDomain so long? Why not shorten it to just Domain?

The term Domain is already used in the account settings, so it would be confusing to use just the term Domain for this.

A.2: Can a domain owner also be a credential issuer?

Yes.

A.3: Can other rule types be added to domains?

Yes, if there is a need (though they must be focused on "who can participate" rather than other aspects of participation, like tokens). If you have any in mind, please mention them below.

A.5: Can I AND credentials together?

No, because it is difficult to make a clean design for that capability.

A.6: Does the domain owner have any special powers over the accepted credentials?

No, unless they are also the issuer of said credential.

A.7: Does the domain owner need to hold the credentials?

No.

A.8: Why not have a ledger object for each domain rule, instead of having it all in one object? Then you wouldn't have any limitations on how many rules a domain could have.

This won't work.

The ledger needs to be able to iterate through the domain rules to ensure that all of them are being adhered to. If a domain owner has millions of objects (or millions of rules), then iterating through all of those objects becomes prohibitively expensive from a performance standpoint.

[XRPSezz]

No ability to clutter and congest, good.

[mvadari]

An update to this spec was published today, 2024-09-25. Token support was removed. This was to focus the feature on the "who can participate" aspect, rather than the "how they can participate" aspect. It makes it more flexible and easier to use in other primitives.

[mtrippled]

@mvadari The PR is ready for review, but I have some modifications to suggest for the spec, and some questions for the near future. Here's the PR: XRPLF/rippled#5149

Here are notes I have regarding the spec:

1. For the LedgerIndex field. This field is automatically implemented for the transaction MetaData, and not for the ledger object itself. However, the field that is automatically in the ledger object is called "index". This performs the same role. Please either remove LedgerIndex or replace it with the index field. Or just leave it out, since it's there automatically.

Here's what an object looks like from account_objects. The "index" field is there:
{
"AcceptedCredentials" :
[

            {
                    "AcceptedCredential" : 
                    {
                            "CredentialType" : "66697273742063726564656E7469616C",
                            "Issuer" : "rG1QQv2nh2gr7RCZ1P8YYcBUKCCN633jCn"
                    }
            }
    ],
    "Flags" : 0,
    "LedgerEntryType" : "PermissionedDomain",
    "Owner" : "rG1QQv2nh2gr7RCZ1P8YYcBUKCCN633jCn",
    "OwnerNode" : "0",
    "PreviousTxnID" : "0000000000000000000000000000000000000000000000000000000000000000",
    "PreviousTxnLgrSeq" : 0,
    "Sequence" : 4,
    "index" : "FA85CBC5681F03AE47E999450726403D824026D95FB490D0F5AC693F17436327"

}

2. The spec does not mention fees or reserves. But I made the assumption that each new PermissionedDomain object will increment the owner count and cost an increased fee accordingly, similar to other objects. Updates to the object don't change the reserve, and deleting the object decrements the owner count. This can be backed out or otherwise modified, but I think it's in line with how we treat other objects.

3. Regarding Credentials--I implemented as the spec described, but I believe it will need to be modified when Credentials gets approved and merged. The spec oughtn't need to change for this, but there might be a wrinkle when the time comes.
   But here are a couple of questions about credentials:
   Are duplicate issuers allowed for a set of credentials? If so, how should they be ordered for fast lookup? Should they be sorted by the CredentialType for identical issuers? What about duplicate credentials that are identical for both Issuer and CredentialType? Should that return temMALFORMED? Right now, I do no duplicate checks and AcceptedCredentials are ordered by Issuer.

Also related to this is the lookup for credentials--that has not been implemented nor specified yet. But it relates to how or whether duplicates Issuers may be sorted. The lookup can be done as part of this project, or, perhaps, for a project that depends on this and may have it's own way in mind for this. My suggestion is to allow duplicates, order by Issuer then by CredentialType. Then for quick lookup, do a binary search to find a match or not. What do you think?

[mvadari]

1. Yes, that's what I meant. I can update the name if you'd prefer.
2. Yes, standard reserves/fees was what I was assuming. The only reason I'd consider something else is if we consider 10 credentials to be too much data to be able to store in one object (we could charge higher reserves for more credentials, like price oracles).
3. I believe the way @oleks-rip ordered the credentials in Deposit Auth was via the hash of the issuer and credential type. I don't have a strong opinion. I would say duplicate credentials should be silently de-duped (since that's what's done in the Credentials PR).

I don't think I understand your concern about lookup. Why do you want to allow duplicates, and why do you need binary search when the list has a max length of 10?

[mtrippled]

@mvadari
In the PR, I've fixed "3" above so that duplicate credentials are silently removed instead of causing the transaction to fail.

Regarding lookup, I guess it could be a linear check, too, which sorting helps with. Or binary, which might be faster since there won't need to be as many steps through the array. I don't want to allow duplicates, but was just trying to clarify if they were to be included or not. It seems like the specific query mechanism can be implemented when the permissioned domains start to be used by another feature--it shouldn't be a big deal to implement when the time comes. Anyway, all of my questions are answered now, and the PR is finished (pending reviewer signoff).

[mvadari]

Per the XLS Contributing process, it is my opinion that we have reached a "well-refined standard."

As such, I propose that we move this discussion to a file (via #234) and work on final changes using additional PRs, for better change-tracking.

Please comment here if you would like to object to moving this spec/discussion forward in the process into a DRAFT spec.

(Note that per the Contributing guidelines, moving a spec into the DRAFT state does not mean any kind of endorsement, nor does it mean that this specification will become adopted. It is solely meant as a mechanism to enable better change tracking using PRs.)

[mvadari]

Closing this discussion since the spec has been initially merged via #234.

For further discussion or changes, please open a PR in this repo on XLS-80d.

[ckeshava]

If you agree with Point-6, I can open a PR:

1. How does the PermissionedDomain (shortened as PD henceforth) ledger object interact with the rest of the XRPL eco-system? I'm looking for examples of how to use PD with other ledger objects and/or transactions.

2. Regarding the Ledger Object format of PD, what is the consensus on the nomenclature for the LedgerIndex field ? Is it "index" or "LedgerIndex" ? Additionally, this ledger object does not accomodate any flags (i.e. flags == 0). Is that correct?

3. Apropos the behavior of the PD feature: If the owner of a PD updates the list of "AcceptedCredentials", what happens to the funds of non-compliant members? Specifically, these members held complaint Verifiable Credentials before the update but they don't comply with the newly updated "AcceptedCredentials".

4. Format of AcceptedCredentials: Certain transactions like Payment, EscrowFinish, AccountDelete and PaymentChannelClaim accept a list of base-16 encoded strings. However, this amendment proposes to specify a list of InnerObjects. What is the cause for this difference?

5. Do you have any examples for the PDSet and PDDelete transaction JSON ? If not, I can print the same from cpp tests, no worries.

6. Do you accept empty list of AcceptedCredentials in the PDSet transaction? Based on the cpp implementation, I suspect not. Sections 3.1, 3.2, 6 (obviates the first bullet point) need to be updated.

7. Compliance with a PD: I don't fully understand when an account is compliant with a PD. If an account holds at least one Verified Credentials in the list of AcceptedCredentials, then is it considered compliant? Is that correct?

8. RPCs that are used for interacting with PD: If I want to find out all the PD's owned by an account, I have three choices:

• ledger_data: I do not know the ledger_index or ledger_hash
• ledger_entry: I do not know the sequence number pertaining to the PD creation.
• account_objects: Even if I use the type: PD filter, I'll probably need to page through several markers to find a specific PD.

Is there any other way to accomplish this? Would developers want to search for a specific PD?

[mvadari]

1. See XLS-81d or XLS-65d.
2. It doesn't really matter what you call it in the spec, in the code it's always going to be index.
3. The funds aren't touched. See the above specs for how those situations are handled.
4. Just like in XLS-70d's DepositPreauth modifications, it has to be a list of inner objects because the subject isn't specified.
5. No, those are easy enough to generate.
6. No. Updated.
7. Yes.
8. That's it, unless you run an indexer for all the PDs. That's true of any on-ledger object.

[ckeshava]

Regarding the available RPCs (point 8), the difference between PD and other ledger objects is the ease of access. Since PD uses the account_sequence_number in the LedgerIndex generation, how can users remember a specific Sequence number? On the other hand, an AMM account root can be retrieved with the two asset pairs. Similarly, a PriceOracle can be retrieved with the account and oracle_document_id value.

I feel this makes contorts the user experience (similar to the difficulties in fetching Check, Escrow ledger objects)

[mvadari]

The idea is you'll be using the DomainID and you don't really care about what different pieces are used to construct the DomainID. So users won't be expected to remember the sequence number.

[ckeshava]

It's also a little confusing that the Owner field in the PermissionedDomain ledger object uses an alias of Account in the ledger_entry RPC. It would have been nicer if both the fields were named using identical words.