From 9bc6bc91ff3e27ce815492a0bea95e5338498b57 Mon Sep 17 00:00:00 2001 From: Peter Chen Date: Wed, 13 May 2026 12:17:11 -0400 Subject: [PATCH 1/6] update spec --- XLS-0094-dynamic-MPT/README.md | 2 +- XLS-0096-confidential-mpt/README.md | 42 ++++++++++++++++++++++++----- 2 files changed, 37 insertions(+), 7 deletions(-) diff --git a/XLS-0094-dynamic-MPT/README.md b/XLS-0094-dynamic-MPT/README.md index 4b0add39..c2bd86ac 100644 --- a/XLS-0094-dynamic-MPT/README.md +++ b/XLS-0094-dynamic-MPT/README.md @@ -182,7 +182,7 @@ The `MutableFlags` use `tmf` as prefix. | `Flags` (except `tfUniversal`) is provided when `MutableFlags`, `MPTokenMetadata`, or `TransferFee` is present | `temMALFORMED` | | `TransferFee` exceeds the limit, which is 50000 | `temBAD_TRANSFER_FEE` | | `MPTokenMetadata` length exceeds the limit, which is 1024 | `temMALFORMED` | -| Setting and clearing the same flag simultaneously, e.g., specifying both `tmfMPTSetCanLock` and `tmfMPTClearCanLock` | `temMALFORMED` | +| Setting and clearing the same flag simultaneously, e.g., specifying both `tmfMPTSetCanLock` and `tmfMPTClearCanLock` | `temINVALID_FLAG` | | Including a non-zero `TransferFee` when `lsfMPTCanTransfer` was not set | `temMALFORMED` | | Including a non-zero `TransferFee` and `tmfMPTClearCanTransfer` in the same transaction | `temMALFORMED` | | `MutableFlags`, `MPTokenMetadata`, or `TransferFee` is present but `featureDynamicMPT` is disabled | `temDISABLED` | diff --git a/XLS-0096-confidential-mpt/README.md b/XLS-0096-confidential-mpt/README.md index 5e6119a5..afb23e80 100644 --- a/XLS-0096-confidential-mpt/README.md +++ b/XLS-0096-confidential-mpt/README.md @@ -24,7 +24,7 @@ The design provides the following properties: (i) a trust-minimized, on-chain auditor model based on encrypted balance mirroring and zero-knowledge consistency proofs, which is extensible to additional auditors via re-encryption; and (ii) a simpler, trust-based alternative using issuer-controlled view keys for on-demand disclosure. - **Compatibility:** Public and confidential balances may coexist for the same token. A designated issuer second account is treated identically to other non-issuer holders, preserving XLS-33 issuance semantics. -- **Issuer control:** Existing issuer controls are preserved and extended to confidential balances, including issuer-initiated freezing and clawback to the issuer’s reserve. +- **Issuer control:** Existing issuer controls are preserved and extended to confidential balances, including issuer-initiated freezing and clawback that burns the clawed-back funds. Confidential MPTs align directly with XLS-33 by maintaining `OutstandingAmount` as the sum of all non-issuer balances. Supply consistency is enforced deterministically by validators using plaintext ledger fields, while confidentiality is achieved at the transaction level through AND-composed compact sigma proofs and range proofs. @@ -59,7 +59,7 @@ The design maintains the standard definition of OutstandingAmount (OA) as the su - **Spending (CB_S):** Stable balance used for spending and proofs. - **Inbox (CB_IN):** Receives incoming transfers and must be explicitly merged into `CB_S`, preventing stale-proof rejection. - **Auditor Policy:** An optional issuance-level configuration that enables selective disclosure by encrypting balances under an auditor’s public key. -- **Clawback:** A privileged issuer-only operation performed via a `ConfidentialMPTClawback` transaction, which forcibly converts a holder’s confidential balance back into the issuer’s public reserve while preserving ledger accounting consistency through ZKPs. +- **Clawback:** A privileged issuer-only operation performed via a `ConfidentialMPTClawback` transaction, which forcibly burns a holder’s entire confidential balance (decreasing both COA and OA) while preserving ledger accounting consistency through ZKPs. Unlike public MPT clawback, the burned funds are not returned to the issuer’s reserve; they are permanently removed from circulation. ## 4. Scope @@ -123,6 +123,10 @@ The protocol relies on a set of ZKPs to validate confidential transactions witho - **Aggregated Bulletproof (754 bytes)**: Used in `ConfidentialMPTSend`. Proves both the transfer amount and the remaining balance are in [0, 2^64). - **Single Bulletproof (688 bytes)**: Used in `ConfidentialMPTConvertBack`. Proves the remaining balance after withdrawal is non-negative. +### 5.5. Delegate Accounts + +The issuer may designate one or more **delegate accounts** to act on its behalf, for example, to submit `ConfidentialMPTClawback` transactions or to manage the confidential vault (second account). Delegate accounts must be considered **fully trusted** by the issuer. A delegate account has complete operational authority within the scope delegated to it, and the protocol does not impose additional on-chain restrictions on delegate actions beyond those that apply to the issuer itself. Issuers should apply the same key-management standards to delegate accounts as to their primary issuer account. + ## 6. Ledger Entry: `MPTokenIssuance` To support confidential MPTs, the existing `MPTokenIssuance` ledger object is extended. These new fields and flags serve as the global configuration and control settings for the token's confidential features. @@ -146,6 +150,21 @@ Two new flags are introduced for the `MPTokenIssuance` ledger object. Note that **Note**: `sfMutableFlags` is introduced in the amendment [`DynamicMPT`](https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0094-dynamic-MPT). To use this field,the `DynamicMPT` amendment must be enabled. +### 6.2.1. Prerequisite: Enabling Freeze and Clawback for Confidential Funds + +The ability to freeze (lock) a holder's confidential balance and to perform `ConfidentialMPTClawback` depends on the `lsfMPTCanLock` and `lsfMPTCanClawback` flags respectively. These flags are governed by XLS-94 (`DynamicMPT`) mutable flags. + +**`lsmfMPTCanMutateCanLock` defaults to `false`**. Unless the issuer explicitly opts in at issuance time, the `lsfMPTCanLock` flag cannot be set or cleared after creation, meaning confidential balances cannot be frozen. + +To enable freeze and clawback of confidential funds, the issuer **must** set `tmfMPTCanMutateCanLock` (and, for clawback, `tmfMPTCanMutateCanClawback`) in the `MutableFlags` field of the `MPTokenIssuanceCreate` transaction. Once set, the issuer may later use `MPTokenIssuanceSet` with `tmfMPTSetCanLock` / `tmfMPTSetCanClawback` to activate those controls. + +| `MutableFlags` bit (creation) | On-ledger flag | Effect when later set via `MPTokenIssuanceSet` | +| :---------------------------- | :-------------------------- | :---------------------------------------------------------------- | +| `tmfMPTCanMutateCanLock` | `lsmfMPTCanMutateCanLock` | Allows issuer to freeze/unfreeze individual or global balances. | +| `tmfMPTCanMutateCanClawback` | `lsmfMPTCanMutateCanClawback` | Allows issuer to enable `lsfMPTCanClawback` for `ConfidentialMPTClawback`. | + +If `lsmfMPTCanMutateCanLock` is **not** set, any attempt to freeze a confidential balance or perform `ConfidentialMPTClawback` will fail with `tecNO_PERMISSION`. + ### 6.3. Managing Confidentiality Settings The `lsfMPTCanConfidentialAmount` flag enables the use of confidential transactions for an `MPTokenIssuance`. Only when this flag is enabled can the token support confidential transfers. @@ -256,7 +275,7 @@ This transaction is a **self-conversion only**. Issuers introduce supply exclusi ### 7.4. Invariants -- **Deletion Blocker:** An `MPToken` cannot be deleted from the ledger if it contains an `sfIssuerEncryptedBalance`, `sfConfidentialBalanceInbox`, or `sfConfidentialBalanceSpending` field. +- **Deletion Blocker:** A holder's `MPToken` cannot be deleted from the ledger once confidential fields have been initialized, even if `sfConfidentialBalanceSpending`, `sfConfidentialBalanceInbox`, and `sfIssuerEncryptedBalance` all contain the canonical encrypted zero (i.e., the holder's confidential balance is zero). The issuer may delete the `MPTokenIssuance` object only when `sfConfidentialOutstandingAmount` is 0 (in addition to the standard XLS-33 deletion requirements). - **Confidential Amount Flag Consistency:** If an `MPToken` contains any encrypted balance fields, then its corresponding `MPTokenIssuance` must have the `lsfMPTCanConfidentialAmount` flag enabled. - **Encrypted Field Consistency:** If an `MPToken` contains `sfConfidentialBalanceSpending` or `sfConfidentialBalanceInbox`, then it must also contain `sfIssuerEncryptedBalance` (and vice versa). - **Version Modification:** If `sfConfidentialBalanceSpending != sfConfidentialBalanceSpending` (the spending balance is modified), then `sfConfidentialBalanceVersion != sfConfidentialBalanceVersion` (the version must be changed). @@ -438,6 +457,7 @@ return (R = r·G, S = r·Pk), Pk: ElGamal public key of Acct - Deterministic across validators (no randomness beacon). - Represents encryption of 0 under account’s key. - Keeps inbox proofs well-formed. +- **Public zero visibility:** Because the canonical encrypted zero is fully deterministic, validators can compare any stored ciphertext against the known `EncZero` value for that account. If they match, the balance is publicly known to be exactly 0. This allows validators to verify that a newly initialized spending balance or a reset inbox contains no hidden value, without requiring the holder’s private key. Non-zero ciphertexts remain opaque. ### 9.5. Example JSON @@ -566,7 +586,7 @@ Step 3. _ConvertBack_ (Alice’s second account → issuer reserve, 30\) Clawback involves the issuer forcibly reclaiming funds from a holder's account. This action is fundamentally incompatible with standard confidential transfers, as the issuer does not possess the holder's private ElGamal key and therefore cannot generate the required ZKPs for a normal ConfidentialMPTSend. To solve this, the protocol introduces a single and privileged transaction that allows an issuer to verifiably reclaim funds in one uninterruptible step. -This issuer-only transaction is designed to convert a holder's entire confidential balance directly into the issuer's public reserve. +This issuer-only transaction is designed to forcibly burn a holder's entire confidential balance, permanently removing those tokens from circulation. Both `OutstandingAmount` (OA) and `ConfidentialOutstandingAmount` (COA) are reduced, effectively destroying the tokens rather than returning them to the issuer's reserve. ### 11.1 How the Clawback Process Works @@ -578,7 +598,7 @@ This issuer-only transaction is designed to convert a holder's entire confidenti 1. The ConfidentialBalance_Spending and ConfidentialBalance_Inbox are set to a valid encryption of zero. 2. The global COA is decreased by the RevealedAmount. 3. The global OA is also decreased by the RevealedAmount. - 4. The Issuer's public issuance capacity is restored (Global OutstandingAmount is decreased by the RevealedAmount), effectively burning the clawed-back tokens. + 4. The global `OutstandingAmount` is decreased by `RevealedAmount`, burning the clawed-back tokens. The funds are permanently removed from circulation and are **not** credited to any account. ### 11.2. Fields @@ -738,7 +758,17 @@ This transaction enables the confidential amount feature by setting the `tmfMPTS This transaction disables the confidential amount feature by setting the `tmfMPTClearCanConfidentialAmount` bit flag in the `MutableFlags` field. This will only succeed if `ConfidentialOutstandingAmount` is zero and the feature was marked as mutable during creation. -## 13. Security Considerations +## 13. Transfer Fees and Confidential Transfers + +Confidential MPTs are **incompatible with non-zero transfer fees**. An `MPTokenIssuance` that has a non-zero `TransferFee` cannot be used for confidential transfers. + +Transfer fees in XLS-33 are applied as a percentage of the transferred amount. Because `ConfidentialMPTSend` hides the transfer amount, it is impossible to enforce or validate a percentage-based fee without revealing the hidden value. To preserve confidentiality guarantees, the protocol prohibits non-zero transfer fees on issuances that enable confidential transfers. + +### 13.1. Implication for Issuers + +Issuers must choose between enabling transfer fees and enabling confidential transfers — these two features are mutually exclusive on the same `MPTokenIssuance`. `ConfidentialMPTSend` will fail with `tecNO_PERMISSION` if the issuance has a non-zero `sfTransferFee`. + +## 14. Security Considerations Confidential MPTs introduce cryptographic mechanisms that require careful validation and enforcement. This section summarizes key privacy guarantees, auditability mechanisms, proof requirements, and considerations against potential attack vectors. From e6dec7a5e17eaa8d8631befefe65c1cda416609b Mon Sep 17 00:00:00 2001 From: Peter Chen Date: Wed, 13 May 2026 12:25:51 -0400 Subject: [PATCH 2/6] fix CI --- XLS-0096-confidential-mpt/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/XLS-0096-confidential-mpt/README.md b/XLS-0096-confidential-mpt/README.md index afb23e80..e39322ba 100644 --- a/XLS-0096-confidential-mpt/README.md +++ b/XLS-0096-confidential-mpt/README.md @@ -158,9 +158,9 @@ The ability to freeze (lock) a holder's confidential balance and to perform `Con To enable freeze and clawback of confidential funds, the issuer **must** set `tmfMPTCanMutateCanLock` (and, for clawback, `tmfMPTCanMutateCanClawback`) in the `MutableFlags` field of the `MPTokenIssuanceCreate` transaction. Once set, the issuer may later use `MPTokenIssuanceSet` with `tmfMPTSetCanLock` / `tmfMPTSetCanClawback` to activate those controls. -| `MutableFlags` bit (creation) | On-ledger flag | Effect when later set via `MPTokenIssuanceSet` | -| :---------------------------- | :-------------------------- | :---------------------------------------------------------------- | -| `tmfMPTCanMutateCanLock` | `lsmfMPTCanMutateCanLock` | Allows issuer to freeze/unfreeze individual or global balances. | +| `MutableFlags` bit (creation) | On-ledger flag | Effect when later set via `MPTokenIssuanceSet` | +| :---------------------------- | :---------------------------- | :------------------------------------------------------------------------- | +| `tmfMPTCanMutateCanLock` | `lsmfMPTCanMutateCanLock` | Allows issuer to freeze/unfreeze individual or global balances. | | `tmfMPTCanMutateCanClawback` | `lsmfMPTCanMutateCanClawback` | Allows issuer to enable `lsfMPTCanClawback` for `ConfidentialMPTClawback`. | If `lsmfMPTCanMutateCanLock` is **not** set, any attempt to freeze a confidential balance or perform `ConfidentialMPTClawback` will fail with `tecNO_PERMISSION`. From 4667b062b729e2fdade3959407d8c9cfe618919e Mon Sep 17 00:00:00 2001 From: Peter Chen Date: Wed, 13 May 2026 12:53:07 -0400 Subject: [PATCH 3/6] remove 2nd account --- XLS-0096-confidential-mpt/README.md | 74 ++++++++++++++--------------- 1 file changed, 37 insertions(+), 37 deletions(-) diff --git a/XLS-0096-confidential-mpt/README.md b/XLS-0096-confidential-mpt/README.md index e39322ba..c6d1cc10 100644 --- a/XLS-0096-confidential-mpt/README.md +++ b/XLS-0096-confidential-mpt/README.md @@ -23,7 +23,7 @@ The design provides the following properties: - **Selective disclosure / view keys:** The protocol supports flexible auditability through two models: (i) a trust-minimized, on-chain auditor model based on encrypted balance mirroring and zero-knowledge consistency proofs, which is extensible to additional auditors via re-encryption; and (ii) a simpler, trust-based alternative using issuer-controlled view keys for on-demand disclosure. -- **Compatibility:** Public and confidential balances may coexist for the same token. A designated issuer second account is treated identically to other non-issuer holders, preserving XLS-33 issuance semantics. +- **Compatibility:** Public and confidential balances may coexist for the same token. The issuer account itself cannot hold confidential balances; issuers who wish to participate in confidential circulation must use a separate dedicated holder account, which is treated identically to other non-issuer holders, preserving XLS-33 issuance semantics. - **Issuer control:** Existing issuer controls are preserved and extended to confidential balances, including issuer-initiated freezing and clawback that burns the clawed-back funds. Confidential MPTs align directly with XLS-33 by maintaining `OutstandingAmount` as the sum of all non-issuer balances. Supply consistency is enforced deterministically by validators using plaintext ledger fields, while confidentiality is achieved at the transaction level through AND-composed compact sigma proofs and range proofs. @@ -39,17 +39,17 @@ The design maintains the standard definition of OutstandingAmount (OA) as the su - Confidentiality: Hides individual balances and transfer amounts using EC-ElGamal encryption and ZKPs. - Auditability: Public auditability is preserved via XLS-33’s existing OA semantics. - Flexible Compliance: Enables selective disclosure through multiple mechanisms, including a trust-minimized on-chain model and a simpler issuer-controlled view key model. -- Compatibility: Maintains backward compatibility with XLS-33 by treating the issuer’s second account as a standard holder. -- Enhanced Issuer Control: Provides optional Freeze and a Clawback transaction, giving issuers the tools needed to manage assets and enforce compliance. +- Compatibility: Maintains backward compatibility with XLS-33. The issuer account cannot hold confidential balances; any issuer-controlled dedicated holder account is treated as a standard holder. +- Enhanced Issuer Control: Provides optional Freeze and a Clawback transaction, giving issuers the tools needed to manage assets and enforce compliance. Clawback burns the holder’s confidential balance; the tokens are not returned to the issuer’s reserve. ## 3. Definitions & Terminology - **MPT (Multi-Purpose Token):** A token standard defined by XLS-33, extended here to support confidential balances and transfers. - **MPTokenIssuance (Object):** Ledger object storing metadata for an MPT, including `Currency`, `Issuer`, `MaxAmount` (MA), and `OutstandingAmount` (OA). - **MPToken (Object):** Ledger object representing a holder’s balance of a given MPT. Extended to include confidential balance fields. -- **Second Account (Issuer-as-Holder):** A designated account controlled by the issuer but treated by the ledger as a standard non-issuer holder. -- **OutstandingAmount (OA):** The total of all non-issuer balances (public and confidential), including the issuer’s second account. -- **ConfidentialOutstandingAmount (COA):** The total amount of an MPT currently held in confidential balances by non-issuers, including the issuer’s second account. +- **Dedicated Account (Issuer-as-Holder):** An optional account controlled by the issuer but treated by the ledger as a standard non-issuer holder. The issuer account itself cannot hold confidential balances; an issuer that wishes to participate in confidential circulation must use a dedicated account. This account is sometimes called the "Confidential Vault." +- **OutstandingAmount (OA):** The total of all non-issuer balances (public and confidential), including any issuer-controlled dedicated account. +- **ConfidentialOutstandingAmount (COA):** The total amount of an MPT currently held in confidential balances by non-issuers, including any issuer-controlled dedicated account. - **MaxAmount (MA):** The maximum allowed token supply. Invariant: `OA ≤ MA`. - **EC-ElGamal Encryption:** A public-key encryption scheme with additive homomorphism, used for encrypted balances and homomorphic balance updates. - **Zero-Knowledge Proofs (ZKPs):** Cryptographic proofs used to validate confidential transactions without revealing amounts, including: @@ -71,24 +71,24 @@ This XLS specifies the protocol changes required to support confidential MPTs, i - ConfidentialMPTSend: Confidential transfer of tokens between accounts, with encrypted amounts validated by ZKPs. - ConfidentialMPTMergeInbox: Merges a holder’s inbox balance into their spending balance, preventing stale-proof issues. - ConfidentialMPTConvertBack: Converts confidential balances back into public form, restoring visible balances or returning funds to the issuer’s reserve. -- ConfidentialMPTClawback: An issuer-only transaction to forcibly convert a holder’s confidential balance back to the issuer's public reserve. +- ConfidentialMPTClawback: An issuer-only transaction to forcibly burn a holder’s entire confidential balance, permanently removing those tokens from circulation. ## 5. Protocol Overview -The Confidential MPT protocol is built on three core design principles: the **Issuer Second Account** model, the **Split-Balance** model for reliable transfers, and a **Multi-Ciphertext** architecture for privacy and compliance. +The Confidential MPT protocol is built on three core design principles: the **Dedicated Account** model, the **Split-Balance** model for reliable transfers, and a **Multi-Ciphertext** architecture for privacy and compliance. -### 5.1 The Issuer Second Account Model +### 5.1 The Dedicated Account Model -The protocol recommends the use of an issuer-controlled **Dedicated Account** (also known as a "Confidential Vault" or "Second Account"). While this account remains under the control of the issuer, it is treated by the ledger as a standard **Holder**. +The issuer account itself **cannot** hold or convert to confidential balances. To participate in confidential circulation, the issuer may optionally use an issuer-controlled **Dedicated Account** (also known as a "Confidential Vault"). While this account remains under the control of the issuer, it is treated by the ledger as a standard **Holder** with no special privileges. -The operational setup follows these steps: +The operational setup, when the issuer wishes to seed confidential circulation, follows these steps: 1. The **Issuer** creates an `MPTokenIssuance` object. -2. The **Issuer** creates a **Dedicated Account** to act as the "Confidential Vault." +2. The **Issuer** optionally creates a **Dedicated Account** to act as the "Confidential Vault." 3. The **Issuer** sends a public MPT amount to the **Dedicated Account**. 4. The **Dedicated Account** converts the public balance to a confidential balance. -- **Preserving invariants:** Because the second account is a non-issuer, its balance is included in `OutstandingAmount` (OA). This preserves the existing `OA ≤ MaxAmount` invariant and allows validators to enforce the supply cap without decrypting confidential balances. All subsequent confidential transfers between non-issuer holders are redistributions that do not modify OA. +- **Preserving invariants:** Because the dedicated account is a non-issuer, its balance is included in `OutstandingAmount` (OA). This preserves the existing `OA ≤ MaxAmount` invariant and allows validators to enforce the supply cap without decrypting confidential balances. All subsequent confidential transfers between non-issuer holders are redistributions that do not modify OA. ### 5.2 The Split-Balance Model @@ -125,7 +125,7 @@ The protocol relies on a set of ZKPs to validate confidential transactions witho ### 5.5. Delegate Accounts -The issuer may designate one or more **delegate accounts** to act on its behalf, for example, to submit `ConfidentialMPTClawback` transactions or to manage the confidential vault (second account). Delegate accounts must be considered **fully trusted** by the issuer. A delegate account has complete operational authority within the scope delegated to it, and the protocol does not impose additional on-chain restrictions on delegate actions beyond those that apply to the issuer itself. Issuers should apply the same key-management standards to delegate accounts as to their primary issuer account. +The issuer may designate one or more **delegate accounts** to act on its behalf, for example, to submit `ConfidentialMPTClawback` transactions or to manage the dedicated account (Confidential Vault). Delegate accounts must be considered **fully trusted** by the issuer. A delegate account has complete operational authority within the scope delegated to it, and the protocol does not impose additional on-chain restrictions on delegate actions beyond those that apply to the issuer itself. Issuers should apply the same key-management standards to delegate accounts as to their primary issuer account. ## 6. Ledger Entry: `MPTokenIssuance` @@ -221,14 +221,14 @@ If the issuance is mutable (tmfMPTCannotMutateCanConfidentialAmount is not set, **Purpose:** Converts a holder’s own visible (public) MPT balance into confidential form. The converted amount is credited to the holder’s confidential inbox balance (`CB_IN`) to avoid immediate proof staleness, requiring an explicit merge into the spending balance (`CB_S`) before use. This transaction also serves as the opt-in mechanism for confidential MPT participation: by executing it (including a zero-amount conversion), a holder’s `HolderEncryptionKey` is recorded on their `MPToken` object, enabling the holder to receive and manage confidential funds. -This transaction is a **self-conversion only**. Issuers introduce supply exclusively through existing XLS-33 public issuance mechanisms. The issuer’s designated second account participates in confidential MPTs by executing `ConfidentialMPTConvert` as a regular holder, with no special privileges. In all cases, `OutstandingAmount` (OA) and `ConfidentialOutstandingAmount` (COA) are maintained in plaintext according to existing invariants. +This transaction is a **self-conversion only**. The issuer account itself **cannot** execute this transaction; only non-issuer holders may convert public balances to confidential form. Issuers introduce supply exclusively through existing XLS-33 public issuance mechanisms. An issuer-controlled dedicated account participates in confidential MPTs by executing `ConfidentialMPTConvert` as a regular holder, with no special privileges. In all cases, `OutstandingAmount` (OA) and `ConfidentialOutstandingAmount` (COA) are maintained in plaintext according to existing invariants. ### 7.1 Use Cases - **Holder → self (public → confidential):** Public balance decreases and confidential balance increases; OA unchanged, COA increases (both in plaintext). -- **Issuer second account → self (public → confidential):** - After being funded publicly via XLS-33 issuance, the second account converts its own balance like any holder; OA unchanged, COA increases. +- **Issuer dedicated account → self (public → confidential):** + After being funded publicly via XLS-33 issuance, the dedicated account converts its own balance like any holder; OA unchanged, COA increases. - **Hybrid circulation:** Tokens may coexist in public and confidential form. @@ -250,7 +250,7 @@ This transaction is a **self-conversion only**. Issuers introduce supply exclusi **Notes:** - This transaction performs **self-conversion only**; there is no `Receiver` field. -- Issuers introduce supply via existing 00 public issuance. The issuer’s second account executes this transaction as a regular holder. +- Issuers introduce supply via existing XLS-33 public issuance. An issuer-controlled dedicated account executes this transaction as a regular holder; the issuer account itself cannot. ### 7.3. Failure Conditions @@ -315,9 +315,9 @@ This transaction honors **Deposit Authorization** and **Credentials** (XLS-70), ### 8.1 Use Cases -- **Holder → holder (including the issuer’s second account):** +- **Holder → holder (including any issuer-controlled dedicated account):** Confidential redistribution of value with the transfer amount hidden. -- **Second account ↔ holder:** +- **Dedicated account ↔ holder:** Confidential redistribution among non-issuer holders under identical rules. ### 8.2. Fields @@ -405,7 +405,7 @@ This transaction respects **authorization** and **lock** constraints, ensuring t ### 9.1 Use Cases - A holder merges newly received confidential transfers into their spendable balance. -- The issuer merges its own inbox into the spending balance (applies to the second account). +- An issuer-controlled dedicated account merges its own inbox into the spending balance, like any holder. - Required periodically to combine funds before subsequent confidential sends. ### 9.2 Fields @@ -474,7 +474,7 @@ return (R = r·G, S = r·Pk), Pk: ElGamal public key of Acct ### 10.1 Purpose: Convert confidential into public MPT value. - For a holder: restore public balance from CB_S. -- For the issuer’s second account: return confidential supply to issuer reserve. +- For an issuer-controlled dedicated account: return confidential supply to public form (credited to the dedicated account’s public balance). ### 10.2 Account Effects @@ -549,21 +549,21 @@ If the transaction is successful: ### 10.7. Edge Case Analysis (Low-Volume Transaction Flow): -\*\* Alice, the issuer, converts 50 ConfidentialMPT into her second account, performs a single confidential send of 20 to Bob (a holder), and then executes a ConvertBack of 30\. +\*\* Alice, the issuer, funds her dedicated account with 50 ConfidentialMPT publicly, the dedicated account converts to confidential, performs a single confidential send of 20 to Bob (a holder), and then executes a ConvertBack of 30\. -Step 1. Issuer Convert (Alice → second account, 50\) +Step 1. Issuer funds dedicated account, dedicated account converts (50\) - Publicly revealed: Amount \= 50\. - Ledger effect: OA ↑ 50, COA ↑ 50, IPB ↓ 50\. - Outsiders now know: 50 CMPT entered confidential circulation. -Step 2. Confidential Send (Alice’s second account → Bob, amount 20\) +Step 2. Confidential Send (Alice’s dedicated account → Bob, amount 20\) -- Public sees: sender \= Alice’s second account, receiver \= Bob, ciphertexts, ZKPs. +- Public sees: sender \= Alice’s dedicated account, receiver \= Bob, ciphertexts, ZKPs. - Amount 20 is hidden. - Ledger effect: OA, COA, IPB unchanged (just redistribution). -Step 3. _ConvertBack_ (Alice’s second account → issuer reserve, 30\) +Step 3. _ConvertBack_ (Alice’s dedicated account, 30\) - Publicly revealed: Amount \= 30\. - Ledger effect: OA ↓ 30, COA ↓ 30, IPB ↑ 30 @@ -572,13 +572,13 @@ Step 3. _ConvertBack_ (Alice’s second account → issuer reserve, 30\) ### 10.7.1 What Outsiders can Infer: - Net change in the confidential pool is 50  −  30  = 20\. So, 20 CMPT remain somewhere in confidential circulation. -- But they cannot know whether Bob got 20, 15, 5, or even 0 — because Alice’s second account may still hold some of the 20\. +- But they cannot know whether Bob got 20, 15, 5, or even 0 — because Alice’s dedicated account may still hold some of the 20\. ### 10.7.2 Why no exact leakage: - ElGamal ciphertexts are randomized: encrypting 0 produces a different-looking ciphertext each time. -- Outsiders cannot look at the second account’s balance ciphertext and say it is zero. -- Thus, they cannot deduce whether Alice’s second account was emptied or kept some confidential balance. +- Outsiders cannot look at the dedicated account’s balance ciphertext and say it is zero. +- Thus, they cannot deduce whether Alice’s dedicated account was emptied or kept some confidential balance. **Note:** This design allows tokens to move between public and private states. While the Convert and ConvertBack transactions show their amounts to provide this flexibility, they still protect the privacy of individual balances and transfers. Observers can only see the total change in circulation, not how the private supply is shared among holders. ElGamal randomization makes it impossible to tell the difference between accounts with zero balances. This ensures that outsiders cannot know if a specific account is empty or still holds private tokens. @@ -783,7 +783,7 @@ Confidential MPT transactions are designed to minimize information leakage while - Currency code (e.g., "USD"). - Ciphertexts (ElGamal pairs under holder, issuer, optional auditor keys). - ZKPs (non-interactive proofs of correctness). -- For issuer funding (Convert → second account): Amount is revealed, consistent with visible mint events in XLS-33. +- For issuer funding (issuer sends public MPT to dedicated account, which then converts): Amount is revealed, consistent with visible mint events in XLS-33. #### 13.1.2 Hidden Information @@ -878,18 +878,18 @@ Every confidential transaction must carry appropriate ZKPs: - Auditor key(s), if enabled. - Validators require a proof that all ciphertexts encrypt the same plaintext, preventing divergence between views. -### 13.5 Issuer Second Account Model +### 13.5 Dedicated Account Model -- Issuer must use a designated second account for confidential issuance. +- The issuer account cannot hold or convert to confidential balances. Issuers who wish to participate in confidential circulation may optionally use a dedicated holder account (Confidential Vault), which is treated as a standard non-issuer holder. - Prevents redefinition of OA semantics and keeps compatibility with XLS-33. -- Validators enforce that direct confidential issuance from the issuer account is invalid. +- Validators enforce that `ConfidentialMPTConvert` from the issuer account is invalid. ### 13.6 Privacy Guarantees - Transaction amounts are hidden in all confidential transfers except: - Issuer mint events (already visible in legacy MPTs). - Conversion from public → confidential, where only the converted amount is disclosed once. -- Redistribution among holders (including issuer’s second account) leaks no amounts. +- Redistribution among holders (including any issuer-controlled dedicated account) leaks no amounts. ### 13.7 Auditor & Compliance Controls @@ -966,9 +966,9 @@ Yes, confidential transactions are more expensive than standard MPT transactions If validators cannot verify a ZKP, the transaction is rejected during consensus, functioning identically to an invalid signature and thus preventing malformed or incorrect confidential balances from entering the ledger. -### A.10 Why does the issuer need a second account? +### A.10 Why can't the issuer account hold confidential balances? -The issuer utilizes a second account as a designated holder account to convert their public reserve into the confidential supply. This approach is primarily used to keep the existing XLS-33 semantics intact, ensuring that the OutstandingAmount accurately reflects non-issuer balances. +The issuer account has a special role on the ledger: its balance is excluded from `OutstandingAmount` to preserve the XLS-33 accounting invariant. Allowing the issuer to hold confidential balances directly would break this invariant, since COA and OA would need to account for the issuer's hidden balance. Instead, an issuer that wishes to participate in confidential circulation uses an optional dedicated holder account (Confidential Vault), which is treated as a standard non-issuer holder. Its confidential balance is included in both OA and COA, keeping all accounting consistent and validators able to enforce `OA ≤ MaxAmount` without decryption. ### A.11 Will proofs be optimized in future versions? From 179713d5637b860a7154999b2df6fbfb6a368bc8 Mon Sep 17 00:00:00 2001 From: Peter Chen Date: Fri, 15 May 2026 13:03:06 -0400 Subject: [PATCH 4/6] fix comments --- XLS-0096-confidential-mpt/README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/XLS-0096-confidential-mpt/README.md b/XLS-0096-confidential-mpt/README.md index c6d1cc10..bc1cf573 100644 --- a/XLS-0096-confidential-mpt/README.md +++ b/XLS-0096-confidential-mpt/README.md @@ -40,14 +40,14 @@ The design maintains the standard definition of OutstandingAmount (OA) as the su - Auditability: Public auditability is preserved via XLS-33’s existing OA semantics. - Flexible Compliance: Enables selective disclosure through multiple mechanisms, including a trust-minimized on-chain model and a simpler issuer-controlled view key model. - Compatibility: Maintains backward compatibility with XLS-33. The issuer account cannot hold confidential balances; any issuer-controlled dedicated holder account is treated as a standard holder. -- Enhanced Issuer Control: Provides optional Freeze and a Clawback transaction, giving issuers the tools needed to manage assets and enforce compliance. Clawback burns the holder’s confidential balance; the tokens are not returned to the issuer’s reserve. +- Enhanced Issuer Control: Provides optional Freeze and a Clawback transaction, giving issuers the tools needed to manage assets and enforce compliance. Clawback burns the holder’s confidential balance. ## 3. Definitions & Terminology - **MPT (Multi-Purpose Token):** A token standard defined by XLS-33, extended here to support confidential balances and transfers. - **MPTokenIssuance (Object):** Ledger object storing metadata for an MPT, including `Currency`, `Issuer`, `MaxAmount` (MA), and `OutstandingAmount` (OA). - **MPToken (Object):** Ledger object representing a holder’s balance of a given MPT. Extended to include confidential balance fields. -- **Dedicated Account (Issuer-as-Holder):** An optional account controlled by the issuer but treated by the ledger as a standard non-issuer holder. The issuer account itself cannot hold confidential balances; an issuer that wishes to participate in confidential circulation must use a dedicated account. This account is sometimes called the "Confidential Vault." +- **Dedicated Account (Issuer-as-Holder):** An optional account controlled by the issuer but treated by the ledger as a standard non-issuer holder. The issuer account itself cannot hold confidential balances for it's own issuance; an issuer that wishes to participate in confidential circulation must use a dedicated account. This account is sometimes called the "Confidential Vault." - **OutstandingAmount (OA):** The total of all non-issuer balances (public and confidential), including any issuer-controlled dedicated account. - **ConfidentialOutstandingAmount (COA):** The total amount of an MPT currently held in confidential balances by non-issuers, including any issuer-controlled dedicated account. - **MaxAmount (MA):** The maximum allowed token supply. Invariant: `OA ≤ MA`. @@ -59,7 +59,7 @@ The design maintains the standard definition of OutstandingAmount (OA) as the su - **Spending (CB_S):** Stable balance used for spending and proofs. - **Inbox (CB_IN):** Receives incoming transfers and must be explicitly merged into `CB_S`, preventing stale-proof rejection. - **Auditor Policy:** An optional issuance-level configuration that enables selective disclosure by encrypting balances under an auditor’s public key. -- **Clawback:** A privileged issuer-only operation performed via a `ConfidentialMPTClawback` transaction, which forcibly burns a holder’s entire confidential balance (decreasing both COA and OA) while preserving ledger accounting consistency through ZKPs. Unlike public MPT clawback, the burned funds are not returned to the issuer’s reserve; they are permanently removed from circulation. +- **Clawback:** A privileged issuer-only operation performed via a `ConfidentialMPTClawback` transaction, which forcibly burns a holder’s entire confidential balance (decreasing both COA and OA) while preserving ledger accounting consistency through ZKPs. The burned funds are not returned to the issuer’s reserve; they are permanently removed from circulation. ## 4. Scope @@ -79,7 +79,7 @@ The Confidential MPT protocol is built on three core design principles: the **De ### 5.1 The Dedicated Account Model -The issuer account itself **cannot** hold or convert to confidential balances. To participate in confidential circulation, the issuer may optionally use an issuer-controlled **Dedicated Account** (also known as a "Confidential Vault"). While this account remains under the control of the issuer, it is treated by the ledger as a standard **Holder** with no special privileges. +The issuer account itself **cannot** hold or convert to it's own token to confidential balances. To participate in confidential circulation, the issuer may optionally use an issuer-controlled **Dedicated Account** (also known as a "Confidential Vault"). While this account remains under the control of the issuer, it is treated by the ledger as a standard **Holder** with no special privileges. The operational setup, when the issuer wishes to seed confidential circulation, follows these steps: @@ -221,7 +221,7 @@ If the issuance is mutable (tmfMPTCannotMutateCanConfidentialAmount is not set, **Purpose:** Converts a holder’s own visible (public) MPT balance into confidential form. The converted amount is credited to the holder’s confidential inbox balance (`CB_IN`) to avoid immediate proof staleness, requiring an explicit merge into the spending balance (`CB_S`) before use. This transaction also serves as the opt-in mechanism for confidential MPT participation: by executing it (including a zero-amount conversion), a holder’s `HolderEncryptionKey` is recorded on their `MPToken` object, enabling the holder to receive and manage confidential funds. -This transaction is a **self-conversion only**. The issuer account itself **cannot** execute this transaction; only non-issuer holders may convert public balances to confidential form. Issuers introduce supply exclusively through existing XLS-33 public issuance mechanisms. An issuer-controlled dedicated account participates in confidential MPTs by executing `ConfidentialMPTConvert` as a regular holder, with no special privileges. In all cases, `OutstandingAmount` (OA) and `ConfidentialOutstandingAmount` (COA) are maintained in plaintext according to existing invariants. +This transaction is a **self-conversion only**. The issuer account itself **cannot** execute this transaction; only non-issuer holders may convert public balances to confidential form of its own MPT issuance. Issuers introduce supply exclusively through existing XLS-33 public issuance mechanisms. An issuer-controlled dedicated account participates in confidential MPTs by executing `ConfidentialMPTConvert` as a regular holder, with no special privileges. In all cases, `OutstandingAmount` (OA) and `ConfidentialOutstandingAmount` (COA) are maintained in plaintext according to existing invariants. ### 7.1 Use Cases @@ -250,7 +250,7 @@ This transaction is a **self-conversion only**. The issuer account itself **cann **Notes:** - This transaction performs **self-conversion only**; there is no `Receiver` field. -- Issuers introduce supply via existing XLS-33 public issuance. An issuer-controlled dedicated account executes this transaction as a regular holder; the issuer account itself cannot. +- Issuers introduce supply via existing XLS-33 public issuance. An issuer-controlled dedicated account executes this transaction as a regular holder. ### 7.3. Failure Conditions @@ -880,7 +880,7 @@ Every confidential transaction must carry appropriate ZKPs: ### 13.5 Dedicated Account Model -- The issuer account cannot hold or convert to confidential balances. Issuers who wish to participate in confidential circulation may optionally use a dedicated holder account (Confidential Vault), which is treated as a standard non-issuer holder. +- The issuer account cannot hold or convert to confidential balances. Issuers who wish to participate in confidential circulation may optionally use a dedicated holder account (Confidential Vault), which is treated as a standard non-issuer holder of its own MPT issuance. - Prevents redefinition of OA semantics and keeps compatibility with XLS-33. - Validators enforce that `ConfidentialMPTConvert` from the issuer account is invalid. @@ -966,7 +966,7 @@ Yes, confidential transactions are more expensive than standard MPT transactions If validators cannot verify a ZKP, the transaction is rejected during consensus, functioning identically to an invalid signature and thus preventing malformed or incorrect confidential balances from entering the ledger. -### A.10 Why can't the issuer account hold confidential balances? +### A.10 Why can't the issuer account hold confidential balances of its own MPT Issuance? The issuer account has a special role on the ledger: its balance is excluded from `OutstandingAmount` to preserve the XLS-33 accounting invariant. Allowing the issuer to hold confidential balances directly would break this invariant, since COA and OA would need to account for the issuer's hidden balance. Instead, an issuer that wishes to participate in confidential circulation uses an optional dedicated holder account (Confidential Vault), which is treated as a standard non-issuer holder. Its confidential balance is included in both OA and COA, keeping all accounting consistent and validators able to enforce `OA ≤ MaxAmount` without decryption. From 60fc34e5f1472d1516c7970948f89557712ea043 Mon Sep 17 00:00:00 2001 From: Peter Chen Date: Fri, 15 May 2026 14:11:36 -0400 Subject: [PATCH 5/6] fix comment --- XLS-0096-confidential-mpt/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/XLS-0096-confidential-mpt/README.md b/XLS-0096-confidential-mpt/README.md index bc1cf573..583fd2d3 100644 --- a/XLS-0096-confidential-mpt/README.md +++ b/XLS-0096-confidential-mpt/README.md @@ -59,7 +59,7 @@ The design maintains the standard definition of OutstandingAmount (OA) as the su - **Spending (CB_S):** Stable balance used for spending and proofs. - **Inbox (CB_IN):** Receives incoming transfers and must be explicitly merged into `CB_S`, preventing stale-proof rejection. - **Auditor Policy:** An optional issuance-level configuration that enables selective disclosure by encrypting balances under an auditor’s public key. -- **Clawback:** A privileged issuer-only operation performed via a `ConfidentialMPTClawback` transaction, which forcibly burns a holder’s entire confidential balance (decreasing both COA and OA) while preserving ledger accounting consistency through ZKPs. The burned funds are not returned to the issuer’s reserve; they are permanently removed from circulation. +- **Clawback:** A privileged issuer-only operation performed via a `ConfidentialMPTClawback` transaction, which forcibly burns a holder’s entire confidential balance (decreasing both COA and OA) while preserving ledger accounting consistency through ZKPs. The burned funds are permanently removed from circulation. ## 4. Scope From 1013e1891198fe17453ccf4a993faf598c99456a Mon Sep 17 00:00:00 2001 From: Peter Chen Date: Fri, 15 May 2026 15:00:36 -0400 Subject: [PATCH 6/6] fix comments --- XLS-0096-confidential-mpt/README.md | 27 ++++++++++++++++++--------- 1 file changed, 18 insertions(+), 9 deletions(-) diff --git a/XLS-0096-confidential-mpt/README.md b/XLS-0096-confidential-mpt/README.md index 583fd2d3..423c942d 100644 --- a/XLS-0096-confidential-mpt/README.md +++ b/XLS-0096-confidential-mpt/README.md @@ -192,13 +192,28 @@ If the issuance is mutable (tmfMPTCannotMutateCanConfidentialAmount is not set, - **Zero Confidential Supply:** The transaction will fail if the `ConfidentialOutstandingAmount` (COA) is greater than 0. This constraint prevents user funds from being trapped in a confidential state that the ledger no longer recognizes. -### 6.4. Invariants +### 6.4. Transfer Fee Compatibility + +Confidential MPTs are incompatible with non-zero `TransferFee`. An `MPTokenIssuance` MUST NOT have both a non-zero `TransferFee` and `lsfMPTCanConfidentialAmount` enabled. + +This restriction is required because XLS-33 transfer fees are percentage-based, while `ConfidentialMPTSend` hides the transferred amount. Enforcing a percentage-based fee would require revealing, trusting, or separately proving the hidden transfer amount, which is outside the scope of this amendment. + +The following cases are invalid: + +- `MPTokenIssuanceCreate` with both a non-zero `TransferFee` and `tfMPTCanConfidentialAmount`. (`temBAD_TRANSFER_FEE`) +- `MPTokenIssuanceSet` that sets `tmfMPTSetCanConfidentialAmount` while the issuance already has a non-zero `TransferFee`. (`tecNO_PERMISSION`) +- `MPTokenIssuanceSet` that sets a non-zero `TransferFee` while the issuance already has `lsfMPTCanConfidentialAmount`. (`tecNO_PERMISSION`) +- `MPTokenIssuanceSet` that sets a non-zero `TransferFee` and `tmfMPTSetCanConfidentialAmount` in the same transaction. (`temBAD_TRANSFER_FEE`) + +`ConfidentialMPTSend` will fail with `tecNO_PERMISSION` if the issuance has a non-zero `TransferFee`. + +### 6.5. Invariants - `ConfidentialOutstandingAmount` >= 0 - `ConfidentialOutstandingAmount` <= `OutstandingAmount` - Any change to `ConfidentialOutstandingAmount` during a `Convert` or `ConvertBack` transaction must be exactly offset by an inverse change to the corresponding `MPTAmount` (i.e., `ΔCOA = -ΔMPTAmount`). -### 6.5. Example JSON +### 6.6. Example JSON ```json { @@ -758,13 +773,7 @@ This transaction enables the confidential amount feature by setting the `tmfMPTS This transaction disables the confidential amount feature by setting the `tmfMPTClearCanConfidentialAmount` bit flag in the `MutableFlags` field. This will only succeed if `ConfidentialOutstandingAmount` is zero and the feature was marked as mutable during creation. -## 13. Transfer Fees and Confidential Transfers - -Confidential MPTs are **incompatible with non-zero transfer fees**. An `MPTokenIssuance` that has a non-zero `TransferFee` cannot be used for confidential transfers. - -Transfer fees in XLS-33 are applied as a percentage of the transferred amount. Because `ConfidentialMPTSend` hides the transfer amount, it is impossible to enforce or validate a percentage-based fee without revealing the hidden value. To preserve confidentiality guarantees, the protocol prohibits non-zero transfer fees on issuances that enable confidential transfers. - -### 13.1. Implication for Issuers +## 13. Operational Considerations Issuers must choose between enabling transfer fees and enabling confidential transfers — these two features are mutually exclusive on the same `MPTokenIssuance`. `ConfidentialMPTSend` will fail with `tecNO_PERMISSION` if the issuance has a non-zero `sfTransferFee`.