From 7bb19b04f8126fe224d2d33bea3544b90b7aeab8 Mon Sep 17 00:00:00 2001 From: Vito Date: Tue, 18 Feb 2025 15:51:43 +0100 Subject: [PATCH 1/5] adds XLS specficiation --- XLS-0033d-multi-purpose-tokens/README.md | 3 +- XLS-0090-multi-purpose-token-domain/README.md | 143 ++++++++++++++++++ 2 files changed, 145 insertions(+), 1 deletion(-) create mode 100644 XLS-0090-multi-purpose-token-domain/README.md diff --git a/XLS-0033d-multi-purpose-tokens/README.md b/XLS-0033d-multi-purpose-tokens/README.md index 8cbc4cc6..8c5d33ec 100644 --- a/XLS-0033d-multi-purpose-tokens/README.md +++ b/XLS-0033d-multi-purpose-tokens/README.md @@ -1,6 +1,7 @@ 
 Title:       Multi-Purpose Tokens (MPTs)
 Type:        draft
+State:       Updated by: XLS-90
 
 Author:  
              David Fuelling
@@ -1145,4 +1146,4 @@ With allow-listing, there needs to be a bidirectional trust between the holder a
 
 **It is important to note that the holder always must first submit the `MPTokenAuthorize` transaction before the issuer.** This means that in the example above, steps 2 and 3 cannot be reversed where Alice submits the `MPTokenAuthorize` before Bob.
 
-Issuer also has the ability to de-authorize a holder. In that case, if the holder still has outstanding funds, then it's the issuer's responsibility to clawback these funds.
+Issuer also has the ability to de-authorize a holder. In that case, if the holder still has outstanding funds, then it's the issuer's responsibility to clawback these funds.
\ No newline at end of file
diff --git a/XLS-0090-multi-purpose-token-domain/README.md b/XLS-0090-multi-purpose-token-domain/README.md
new file mode 100644
index 00000000..81078906
--- /dev/null
+++ b/XLS-0090-multi-purpose-token-domain/README.md
@@ -0,0 +1,143 @@
+
+Title:       PermissionedDomain for Multi-Purpose Token
+Type:        draft
+State:       Updates: (XLS-33)[https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0033d-multi-purpose-tokens]
+Requires:   (XLS-80)[https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0080-permissioned-domains]
+
+Authors:  
+             Vito Tumas
+Affiliation: Ripple
+

+
+# Multi-Purpose Token DomainID
+
+## _Abstract_
+
+The issuer of a Multi-Purpose Token may require explicit authorization for individuals to hold the token. This is done through the issuer submitting an `MPTokenAuthorize` transaction, which authorizes each account individually.
+
+The (XLS-80)[https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0080-permissioned-domains] specification introduces a new mechanism for broader authorization. The Permissioned Domain specifies a list of accepted `(Issuer, Type)` credential pairs within the domain. Any holder of valid credentials can interact with the protocols in this Permissioned Domain.
+
+This specification adds `PermissionedDomain` support to the Multi-Purpose Token. By allowing the issuer to set a `DomainID`, we provide a more unified and efficient mechanism for controlling who may hold or receive the asset.
+
+## 1. Introduction
+
+## 2. Ledger Entries
+
+### 2.1. `MPTokenIssuance` Ledger Entry
+
+This section outlines the changes made to the `MPTokenIssuance` object. In summary, the XLS adds a new `DomainID` field to the `MPTokenIssuance` object.
+
+#### 2.1.1. Fields
+
+| Field Name | Change Type | Modifiable? | Required? | JSON Type | Internal Type | Default Value | Description                                                               |
+| ---------- | :---------: | :---------: | :-------: | :-------: | :-----------: | :-----------: | :------------------------------------------------------------------------ |
+| `DomainID` |    `New`    |    `Yes`    |    No     | `string`  |   `HASH256`   |     None      | The `PermissionedDomain` object ID associated with the `MPTokenIssuance`. |
+
+##### 2.1.1.1. DomainID
+
+An optional identifier for the `PermissionedDomain` object linked to the `MPTokenIssuance`. If `DomainID` is specified, the account must possess credentials approved by the `PermissionedDomain` to hold the `MPT`.
+
+### 2.2. `MPToken` Ledger Entry
+
+This section outlines the changes made to the `MPToken` object. In summary, the XLS adds a new `Flags` value, `lsfMPTDomainCheck`.
+
+#### 2.2.1. Fields
+
+| Field Name | Change Type | Modifiable? | Required? | JSON Type | Internal Type | Default Value | Description                                                                                             |
+| ---------- | :---------: | :---------: | :-------: | :-------: | :-----------: | :-----------: | :------------------------------------------------------------------------------------------------------ |
+| `Flags`    |  `Update`   |    `Yes`    |    No     | `number`  |   `UINT16`    |       0       | A set of flags indicating properties or other options associated with the **`MPTokenIssuance`** object. |
+
+#### 2.2.1.1. Flags
+
+The `Vault` object supports the following flags:
+
+| Flag Name           | Change Type | Flag Value | Modifiable? | Description                                                                                                                                                                                                               |
+| ------------------- | :---------: | :--------: | :---------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `lsfMPTDomainCheck` |    `New`    |  `0x0004`  |    `No`     | If set, indicates that _individual_ holders must have credentials in the `PermissionedDomain` of the `MPTokenIssuance`. This flag is set automatically when the associated `MPTokenIssuance` object has a `DomainID` set. |
+
+## 3. Transactions
+
+## 3.1. `MPTokenIssuance` Transactions
+
+#### 3.1.1. `MPTokenIssuaceCreate` Transaction
+
+#### 3.1.1.1. Fields
+
+| Field Name | Change Type | Required? | JSON Type | Internal Type | Default Value | Description                                |
+| ---------- | :---------: | :-------: | :-------: | :-----------: | :-----------: | :----------------------------------------- |
+| `DomainID` |    `New`    |   `No`    | `string`  |   `HASH256`   |     None      | The ID of the `PermissionedDomain` object. |
+
+#### 3.1.1.2. Failure Conditions
+
+- The `PermissionedDomain(DomainID)` object does not exist on the ledger.
+
+#### 3.1.1.3. State Changes
+
+- No additional state changes are made to the ledger.
+
+#### 3.1.1.4. Example
+
+```js
+{
+  "TransactionType": "MPTokenIssuanceCreate",
+  "Account": "rajgkBmMxmz161r8bWYH7CQAFZP5bA9oSG",
+  "AssetScale": "2", // <-- Divisible into 100 units / 10^2
+  "MaximumAmount": "100000000", //  <-- 100,000,000
+  "Flags": 66, // <-- tfMPTCanLock and tfMPTCanClawback
+  "MPTokenMetadata": "464F4F", // <-- "FOO" (HEX)
+  "Fee": 10,
+  "DomainID": "ASOHFiufiuewfviwuisdvubiuwb"
+}
+```
+
+## 3.2. `MPToken` Transactions
+
+### 3.2.1.`MPTokenAuthorize` Transaction
+
+#### 3.2.1.1. Fields
+
+This change does not introduce additional fields.
+
+#### 3.2.1.2. Failure Conditions
+
+This change does not introduce additional failure conditions.
+
+#### 3.2.1.3. State Changes
+
+- If the `MPTokenIssuance(MPTokenIssuanceID).DomainID` field is set:
+  - Set the `lsftMPTDomainCheck` flag to the newly created `MPToken` object.
+
+## 3.3. Other Transactions
+
+### 3.3.1. `Payment` Transaction
+
+The following changes are made to the payment transaction.
+
+#### 3.3.1.1. Fields
+
+This change does not introduce additional fields.
+
+#### 3.3.1.2. Failure Conditions
+
+- If `Payment.Amount` is an `MPT` and `MPTokenIssuance(Amount.MPTIssuanceID).DomainID` is set:
+  - The `PermissionedDomain(MPTokenIssuance(Amount.MPTIssuanceID).DomainID)` object does not exist (the PermissionedDomain was deleted).
+  - The `Payment.Account` account does not have Credentials accepted by the `PermissionedDomain` and:
+    - The `MPToken` object of the `Payment.Account` account does not have the `lsfMPTAuthorized` flag set.
+  - The `Payment.Destination` account does not have Credentials accepted by the `PermissionedDomain` and:
+    - The `MPToken` object of the `Payment.Destination` account does not have the `lsfMPTAuthorized` flag set.
+
+#### 3.3.1.3. State Changes
+
+This change does not introduce additional state changes.
+
+# Appendix
+
+## A-1 F.A.Q
+
+### A-1.1. Why does `MPTokenIssuance` use `PermissionedDomain`?
+
+`PermissionedDomain` provides a less granular authorization mechanism to hold the `MPT`. Any account can hold the `MPT` as long as it has credentials issued by an Issuer accepted in the `PermissionedDomain`; in case the credentials expire or are revoked by the Credential Issuer, the holder can only transfer them back to the `MPT` Issuer and may not receive `MPTs`.
+
+#### A-1.2. What happens when `MPTokenIssuace` uses `PermissionedDomain` and explicit authorization to hold an asset in the `MPToken` object?
+
+Authorization is treated as a union. I.e. as long as the account has permission (either via `PermissionedDomain` of explicit authorization captured by the `MPToken.lsfMPTAuthorized` flag), it will be able to send and receive the `MPT`.

From a59c3e00add226928dce48bcae172c274a9e9a72 Mon Sep 17 00:00:00 2001
From: Vito 
Date: Tue, 18 Feb 2025 16:09:30 +0100
Subject: [PATCH 2/5] adds MPTIssuanceSet changes

---
 XLS-0090-multi-purpose-token-domain/README.md | 34 +++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/XLS-0090-multi-purpose-token-domain/README.md b/XLS-0090-multi-purpose-token-domain/README.md
index 81078906..05e51cef 100644
--- a/XLS-0090-multi-purpose-token-domain/README.md
+++ b/XLS-0090-multi-purpose-token-domain/README.md
@@ -61,6 +61,8 @@ The `Vault` object supports the following flags:
 
 #### 3.1.1. `MPTokenIssuaceCreate` Transaction
 
+This section outlines changes made to the `MPTokenIssuanceCreate` transaction. In summary, the specification adds a new `DomainID` field to the transaction.
+
 #### 3.1.1.1. Fields
 
 | Field Name | Change Type | Required? | JSON Type | Internal Type | Default Value | Description                                |
@@ -90,6 +92,38 @@ The `Vault` object supports the following flags:
 }
 ```
 
+### 3.1.2. `MPTokenIssuanceSet` Transaction
+
+This section outlines changes made to the `MPTokenIssuanceSet` transaction. In summary, the specification adds a new `DomainID` field to the transaction.
+
+#### 3.1.2.1. Fields
+
+| Field Name | Change Type | Required? | JSON Type | Internal Type | Default Value | Description                                |
+| ---------- | :---------: | :-------: | :-------: | :-----------: | :-----------: | :----------------------------------------- |
+| `DomainID` |    `New`    |   `No`    | `string`  |   `HASH256`   |     None      | The ID of the `PermissionedDomain` object. |
+
+#### 3.1.2.2. Failure Conditions
+
+- The `PermissionedDomain(DomainID)` object does not exist on the ledger.
+- If the ` MPTokenIssuance.lsfMPTRequireAuth` flag is NOT set and `DomainID` is provided (a Domain cannot be added to a public Multi-Purpose Token). 
+
+#### 3.1.2.3. State Changes
+
+- Update the `MPTokenIssuance.DomainID` field.
+
+#### 3.1.1.4. Example
+
+```js
+{
+  "TransactionType": "MPTokenIssuanceSet",
+  "Fee": 10,
+  "MPTokenIssuanceID": "000004C463C52827307480341125DA0577DEFC38405B0E3E",
+  "Flags": 1,
+  "DomainID": "ASOHFiufiuewfviwuisdvubiuwb"
+}
+```
+
+
 ## 3.2. `MPToken` Transactions
 
 ### 3.2.1.`MPTokenAuthorize` Transaction

From 3cca2d2429baa59759c94819d4833a7c5765cfd3 Mon Sep 17 00:00:00 2001
From: Vito 
Date: Tue, 18 Feb 2025 16:18:16 +0100
Subject: [PATCH 3/5] removes markdown from the header

---
 XLS-0090-multi-purpose-token-domain/README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/XLS-0090-multi-purpose-token-domain/README.md b/XLS-0090-multi-purpose-token-domain/README.md
index 05e51cef..15fee57a 100644
--- a/XLS-0090-multi-purpose-token-domain/README.md
+++ b/XLS-0090-multi-purpose-token-domain/README.md
@@ -1,8 +1,8 @@
 
 Title:       PermissionedDomain for Multi-Purpose Token
 Type:        draft
-State:       Updates: (XLS-33)[https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0033d-multi-purpose-tokens]
-Requires:   (XLS-80)[https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0080-permissioned-domains]
+State:       Updates: XLS-33
+Requires:   XLS-80
 
 Authors:  
              Vito Tumas

From 19c80231e020c3f5df1ec3ad9cce2ab8e007784d Mon Sep 17 00:00:00 2001
From: Vito 
Date: Wed, 19 Feb 2025 13:45:12 +0100
Subject: [PATCH 4/5] adds a description to the behaviour of transactions

---
 XLS-0090-multi-purpose-token-domain/README.md | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/XLS-0090-multi-purpose-token-domain/README.md b/XLS-0090-multi-purpose-token-domain/README.md
index 15fee57a..a263c17d 100644
--- a/XLS-0090-multi-purpose-token-domain/README.md
+++ b/XLS-0090-multi-purpose-token-domain/README.md
@@ -2,7 +2,7 @@
 Title:       PermissionedDomain for Multi-Purpose Token
 Type:        draft
 State:       Updates: XLS-33
-Requires:   XLS-80
+Requires:    XLS-80
 
 Authors:  
              Vito Tumas
@@ -15,7 +15,7 @@ Affiliation: Ripple
 
 The issuer of a Multi-Purpose Token may require explicit authorization for individuals to hold the token. This is done through the issuer submitting an `MPTokenAuthorize` transaction, which authorizes each account individually.
 
-The (XLS-80)[https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0080-permissioned-domains] specification introduces a new mechanism for broader authorization. The Permissioned Domain specifies a list of accepted `(Issuer, Type)` credential pairs within the domain. Any holder of valid credentials can interact with the protocols in this Permissioned Domain.
+The [XLS-80](https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0080-permissioned-domains) specification introduces a new mechanism for broader authorization. The Permissioned Domain specifies a list of accepted `(Issuer, Type)` credential pairs within the domain. Any holder of valid credentials can interact with the protocols in this Permissioned Domain.
 
 This specification adds `PermissionedDomain` support to the Multi-Purpose Token. By allowing the issuer to set a `DomainID`, we provide a more unified and efficient mechanism for controlling who may hold or receive the asset.
 
@@ -25,7 +25,8 @@ This specification adds `PermissionedDomain` support to the Multi-Purpose Token.
 
 ### 2.1. `MPTokenIssuance` Ledger Entry
 
-This section outlines the changes made to the `MPTokenIssuance` object. In summary, the XLS adds a new `DomainID` field to the `MPTokenIssuance` object.
+This section outlines the changes made to the `MPTokenIssuance` object. In summary, the XLS adds a new `DomainID` field to the `MPTokenIssuance` object. The `DomainID` is used to track which `PermissionedDomain` the `MPT` uses to controll access rules.
+
 
 #### 2.1.1. Fields
 
@@ -39,7 +40,7 @@ An optional identifier for the `PermissionedDomain` object linked to the `MPToke
 
 ### 2.2. `MPToken` Ledger Entry
 
-This section outlines the changes made to the `MPToken` object. In summary, the XLS adds a new `Flags` value, `lsfMPTDomainCheck`.
+This section outlines the changes made to the `MPToken` object. In summary, the XLS adds a new `Flags` value, `lsfMPTDomainCheck`. The `lsfMPTDomainCheck` flag indicates that the credentials of the MPT holder must be verified. This flag is set automatically when the `MPToken` object is created and the associated `MPTokenIssuance` object has the `DomainID` set.
 
 #### 2.2.1. Fields
 
@@ -61,7 +62,7 @@ The `Vault` object supports the following flags:
 
 #### 3.1.1. `MPTokenIssuaceCreate` Transaction
 
-This section outlines changes made to the `MPTokenIssuanceCreate` transaction. In summary, the specification adds a new `DomainID` field to the transaction.
+This section outlines changes made to the `MPTokenIssuanceCreate` transaction. The specification adds a new `DomainID` field to the transaction. If the `DomainID` is specified when creating a new `MPTokenIssuance` it can be later changed by submitting a `MPTokenIssuanceSet` transaction. If the `DomainID` was not set when creating the `MPTokenIssuance` it cannot be assigned later. See [3.1.2.](#312-mptokenissuanceset-transaction) for additional details.
 
 #### 3.1.1.1. Fields
 
@@ -94,7 +95,7 @@ This section outlines changes made to the `MPTokenIssuanceCreate` transaction. I
 
 ### 3.1.2. `MPTokenIssuanceSet` Transaction
 
-This section outlines changes made to the `MPTokenIssuanceSet` transaction. In summary, the specification adds a new `DomainID` field to the transaction.
+This section describes the modifications made to the `MPTokenIssuanceSet` transaction. A new `DomainID` field has been added to the transaction specification. The `DomainID` can only be changed if the `MPTokenIssuance` object was initially created with a `DomainID`. Additionally, all `MPToken` objects linked to an `MPTokenIssuance` with a PermissionedDomain must have the `lsfMPTDomainCheck` flag enabled. However, there is currently no method to identify all `MPToken` objects associated with a specific `MPTokenIssuance`. Retroactively assigning a `DomainID` would necessitate updating the `lsfMPTDomainCheck` for all related `MPToken` objects. Since these objects cannot be retrieved, this process could lead to inconsistencies.
 
 #### 3.1.2.1. Fields
 
@@ -105,7 +106,7 @@ This section outlines changes made to the `MPTokenIssuanceSet` transaction. In s
 #### 3.1.2.2. Failure Conditions
 
 - The `PermissionedDomain(DomainID)` object does not exist on the ledger.
-- If the ` MPTokenIssuance.lsfMPTRequireAuth` flag is NOT set and `DomainID` is provided (a Domain cannot be added to a public Multi-Purpose Token). 
+- The ` MPTokenIssuance.DomainID` field is not set (a Domain cannot be added to a to a Multi-Purpose Token was not created with a PermissionedDomain). 
 
 #### 3.1.2.3. State Changes
 
@@ -123,7 +124,6 @@ This section outlines changes made to the `MPTokenIssuanceSet` transaction. In s
 }
 ```
 
-
 ## 3.2. `MPToken` Transactions
 
 ### 3.2.1.`MPTokenAuthorize` Transaction
@@ -145,7 +145,7 @@ This change does not introduce additional failure conditions.
 
 ### 3.3.1. `Payment` Transaction
 
-The following changes are made to the payment transaction.
+The following changes have been made to the Payment transaction. When transferring Multi-Purpose Tokens (MPTs) that belong to a PermissionedDomain, both the sender and the receiver must either have credentials accepted in the Domain or receive explicit authorization from the `Issuer`, as indicated by the `MPToken.lsfMPTAuthorized` flag. However, Payment transactions involving the `Issuer` of the Multi-Purpose Token are exempt from this requirement.
 
 #### 3.3.1.1. Fields
 

From 74b0af10e83151eadaf52d5e766d8a600a6a43be Mon Sep 17 00:00:00 2001
From: Vito 
Date: Tue, 4 Mar 2025 10:10:27 +0100
Subject: [PATCH 5/5] fixes typos

---
 XLS-0090-multi-purpose-token-domain/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/XLS-0090-multi-purpose-token-domain/README.md b/XLS-0090-multi-purpose-token-domain/README.md
index a263c17d..e8aa0a4b 100644
--- a/XLS-0090-multi-purpose-token-domain/README.md
+++ b/XLS-0090-multi-purpose-token-domain/README.md
@@ -166,7 +166,7 @@ This change does not introduce additional state changes.
 
 # Appendix
 
-## A-1 F.A.Q
+## A-1 F.A.Q.
 
 ### A-1.1. Why does `MPTokenIssuance` use `PermissionedDomain`?