diff --git a/XLS-0049-multiple-signer-lists/README.md b/XLS-0049-multiple-signer-lists/README.md index 6f86fab7..b45f7c35 100644 --- a/XLS-0049-multiple-signer-lists/README.md +++ b/XLS-0049-multiple-signer-lists/README.md @@ -6,24 +6,30 @@ proposal-from: https://github.com/XRPLF/XRPL-Standards/discussions/144 status: Draft category: Amendment + requires: 74 created: 2023-11-13 + updated: 2026-02-20 # Multiple Signer Lists -## Abstract +## 1. Abstract The XRP Ledger currently only supports one global signer list per account. However, many users (such as token issuers) require more granularity. For example, they might want to have one signer list with the ability to mint new tokens, and another signer list with the ability to create and edit trustlines. This document describes a proposal for supporting multiple signer lists per account. The current system of global signer lists will continue to be supported, but we propose adding **per-transaction-type signer lists**. Accounts can set up signer lists that only have the power to send **transactions of one specific type** on behalf of the account. -This proposal is related to [XLS-31](https://github.com/XRPLF/XRPL-Standards/discussions/77), but broader in scope. +## 2. Motivation -## 1. Overview +Global signer lists provide an "all or nothing" model of access control: any key that can sign for an account can submit all transaction types on its behalf. For complex operational setups, especially for issuers and institutional users, this makes it difficult to separate duties such as minting, trustline management, or account configuration. -We propose modifying one ledger object and one transaction: +Supporting multiple signer lists per account, each scoped to a specific transaction type, enables more granular permissioning. This reduces the blast radius of a compromised signer, and allows organizations to delegate narrowly scoped powers (for example, minting only, or trustline management only) without granting full control over the account. -- `SignerList` ledger object +## 3. Overview + +We propose modifying one ledger entry and one transaction: + +- `SignerList` ledger entry - `SignerListSet` transaction This change will require an amendment. @@ -33,63 +39,134 @@ The important considerations to keep in mind are: - `rippled` must be able to retrieve all possible signer lists for a transaction type quickly and easily, in order to check if a transaction has a valid multisign list. - Any signer list that can sign transactions can drain the account's XRP via fees. -## 2. On-Ledger Object: **`SignerList`** +## 4. Ledger Entry: `SignerList` -There is no change to the shape of a [`SignerList` ledger object](https://xrpl.org/signerlist.html), only in how it's used. +There is no change to the shape of a [`SignerList` ledger entry](https://xrpl.org/signerlist.html), only in how it's used. -### 2.1. Fields +This amendment repurposes the `SignerListID` field and generalizes how the ledger index is derived so that multiple signer lists can coexist for a single account. -As a reference, the **`SignerList`** object currently has the following fields: +### 4.1. Object Identifier -| Field Name | Required? | JSON Type | Internal Type | -| ------------------- | --------- | --------- | ------------- | -| `LedgerIndex` | ✔️ | `string` | `HASH256` | -| `LedgerEntryType` | ✔️ | `string` | `UINT16` | -| `SignerEntries` | ✔️ | `array` | `STARRAY` | -| `SignerQuorum` | ✔️ | `number` | `UINT32` | -| `SignerListID` | ✔️ | `number` | `UINT32` | -| `OwnerNode` | ✔️ | `string` | `UINT64` | -| `PreviousTxnID` | ✔️ | `string` | `HASH256` | -| `PreviousTxnLgrSeq` | ✔️ | `number` | `UINT32` | +Existing `SignerList` entries use an object identifier derived from the owner's account ID and a selector value of `0`. This amendment preserves that identifier for the global signer list (`SignerListID = 0`) and introduces additional identifiers of the form `account + (1 + TxType)` for per-transaction-type signer lists. The underlying tagged-hash key space for `SignerList` entries is unchanged. -The ledger index of this object is calculated by hashing together the owner's account ID with the value of `0`. +### 4.2. Fields -The only field whose usage is changing is `SignerListID`. All other fields will be used the same as they are now. +For the complete list of fields, types, and defaults, see the canonical [`SignerList` ledger entry documentation](https://xrpl.org/docs/references/protocol/ledger-data/ledger-entry-types/signerlist#signerlist-fields). This amendment does not add or remove any `SignerList` fields; it only changes how the existing `SignerListID` field is interpreted, as described in §4.2.1. -#### 2.1.1. `SignerListID` +#### 4.2.1. `SignerListID` This field is currently always set to `0`. The original [`Multisign` implementation](https://xrpl.org/known-amendments.html#multisign) only allowed for one signer list per account, but left the door open for the possibility of more. -We propose that this field is instead used for the transaction type that the signer is allowed to sign for, with `0` being the value for the global signer list (to ensure backwards compatibility). There is enough space in `SignerListID` for this field, because `TxType` is a `UInt16` and `SignerListID` is a `UInt32`. Since the `UInt32` is so much larger than the `UInt16`, there is extra room in the valid values for additional signer list usage proposals. The value of this field will also be used in the `index` calculation. +Under this amendment, `SignerListID` is used to scope signer lists: + +- `SignerListID = 0` denotes the global signer list for an account (backwards compatible with existing behavior). +- For each transaction type with serialized type code `TxType` (a `UInt16`), the per-transaction-type signer list for that transaction type uses `SignerListID = 1 + TxType`. -One problem: `Payment` has transaction type `0`, which would conflict with the global signer list. To get around that, we will instead use `1+TxType` in the `SignerListID` field. It is then very easy to check whether a multisign transaction is valid: the code can check the global signer list (look at the signer list with index `account + 0`), and the transaction-type-specific signer list (look at the signer list with index `account + (1+TxType)`). +There is enough space in `SignerListID` for this mapping because `TxType` is a `UInt16` and `SignerListID` is a `UInt32`. Since the `UInt32` is so much larger than the `UInt16`, there is extra room in the valid values for additional signer list usage proposals. + +One problem: `Payment` has transaction type `0`, which would conflict with the global signer list. Using `1 + TxType` in the `SignerListID` field avoids this collision. It is then very easy to check whether a multisign transaction is valid: the code can check the global signer list (look at the signer list with index `account + 0`), and the transaction-type-specific signer list (look at the signer list with index `account + (1 + TxType)`). Each additional `SignerList` that an account owns will, of course, cost an additional owner reserve (2 XRP at the time of writing). -## 3. Transaction: **`SignerListSet`** +### 4.3. Invariants + +- `.SignerQuorum > 0` implies `.SignerEntries` is non-empty and the sum of all `SignerWeight` values in `.SignerEntries` is greater than or equal to `.SignerQuorum`, and likewise for `'`. +- For any update to an existing `SignerList` entry, `.SignerListID == '.SignerListID`; the scope of a signer list (global vs. per-transaction-type) does not change in-place. + +### 4.4. Example JSON + +```json +{ + "LedgerEntryType": "SignerList", + "Flags": 0, + "OwnerNode": "0000000000000000", + "PreviousTxnID": "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF", + "PreviousTxnLgrSeq": 12345678, + "SignerQuorum": 3, + "SignerEntries": [ + { + "Account": "rExampleSigner1XXXXXXXXXXXXXXXX", + "SignerWeight": 1 + }, + { + "Account": "rExampleSigner2XXXXXXXXXXXXXXXX", + "SignerWeight": 2 + } + ], + "SignerListID": 1 +} +``` + +## 5. Transaction: `SignerListSet` + +The [`SignerListSet` transaction](https://xrpl.org/signerlistset.html) already exists on the XRPL. This amendment extends it to support per-transaction-type signer lists. + +### 5.1. Fields + +For the existing fields and validation rules, see the canonical [`SignerListSet` transaction documentation](https://xrpl.org/docs/references/protocol/transactions/types/signerlistset#signerlistset-fields). This amendment adds a single new optional field: + +| Field Name | Required? | JSON Type | Internal Type | Default Value | Description | +| ------------------------ | --------- | --------- | ------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TransactionTypeBitmask` | No | `array` | `HASH256` | `N/A` | Bitmask of transaction types this change applies to; JSON is a list of transaction type names. `0` updates the global signer list; other values map to scoped lists as defined in this XLS. | + +#### 5.1.1. `TransactionTypeBitmask` + +This field accepts a bitmask of transaction types, much like the [`HookOn` field](https://xrpl-hooks.readme.io/docs/hookon-field). A `0` bit is "on" and a `1` bit is "off". A value of `0` changes the global signer list (`SignerListID = 0`). All other values change the many signer lists of the transactions they apply to, so that it is easier to modify many signer lists at once. The JSON representation shows this field as a list of transaction types. + +### 5.2. Failure Conditions + +#### 5.2.1. Data Verification + +1. `TransactionTypeBitmask` is present but is not an array, contains elements that are not valid transaction type identifiers, or decodes to a malformed bitmask (implementation-defined `tem`-class error code). + +#### 5.2.2. Protocol-Level Failures + +1. Applying the requested changes would require creating additional `SignerList` entries but the account does not hold enough XRP to meet the resulting owner reserve requirement for all affected lists (implementation-defined `tec`-class error code). + +### 5.3. State Changes + +On success (`tesSUCCESS`): + +- If `TransactionTypeBitmask` is not present, the transaction behaves as the existing `SignerListSet` transaction: it creates, updates, or removes the global signer list (`SignerListID = 0`) for the account. +- If `TransactionTypeBitmask` is present, the transaction creates, updates, or removes one or more `SignerList` ledger entries whose `SignerListID` values are derived from the selected transaction types (for example, `SignerListID = 1 + TxType` for each enabled transaction type). +- The account's owner directory and owner reserve are updated to reflect any newly created or deleted `SignerList` entries. + +### 5.4. Example JSON -The [`SignerListSet` transaction](https://xrpl.org/signerlistset.html) already exists on the XRPL. We propose a slight modification to support per-transaction-type signer lists. +```json +{ + "TransactionType": "SignerListSet", + "Account": "rExampleAccountXXXXXXXXXXXXXXXXX", + "Fee": "10", + "Sequence": 12345, + "SignerQuorum": 3, + "SignerEntries": [ + { + "Account": "rExampleSigner1XXXXXXXXXXXXXXXX", + "SignerWeight": 1 + }, + { + "Account": "rExampleSigner2XXXXXXXXXXXXXXXX", + "SignerWeight": 2 + } + ], + "TransactionTypeBitmask": ["Payment", "TrustSet"] +} +``` -### 3.1. Fields +## 6. Rationale -As a reference, the **`SignerListSet`** transaction already has the following fields: +This proposal chooses a straightforward mapping from transaction types to separate `SignerList` entries: `SignerListID = 0` represents the existing global signer list, while `SignerListID = 1 + TxType` represents a signer list scoped to a single transaction type. This design keeps lookup logic simple, preserves existing semantics for the global list, and minimizes UX changes for wallets and other tooling. -| Field Name | Required? | JSON Type | Internal Type | -| ----------------- | --------- | --------- | ------------- | -| `TransactionType` | ✔️ | `string` | `UInt16` | -| `SignerEntries` | ✔️ | `array` | `STARRAY` | -| `SignerQuorum` | ✔️ | `number` | `UInt32` | +Alternative designs, such as encoding permissions via a bitmask in `SignerListID` or implementing per-transaction-type multisign using crypto-conditions, were considered. These alternatives offer additional flexibility but introduce more complexity and larger changes to transaction formats and signing workflows. They are described in more detail in Appendix B and Appendix C. -We propose adding a new optional field: -| Field Name | Required? | JSON Type | Internal Type | -|------------|-----------|-----------|---------------| -|`TransactionTypeBitmask` | |`array`|`HASH256` +## 7. Backwards Compatibility -#### 3.1.1. `TransactionTypeBitmask` +Existing signer lists with `SignerListID = 0` continue to function as global signer lists and retain their current behavior. No changes are required for accounts that only use a single global signer list. -This field accepts a bitmask of transaction types, much like the [`HookOn` field](https://xrpl-hooks.readme.io/docs/hookon-field). A `0` bit is "on" and a `1` bit is "off". A value of `0` changes the global signer list. All other values change the many signer lists of the transactions they apply to, so that it is easier to modify many signer lists at once. The JSON will show a list of transactions. +Per-transaction-type signer lists are added in a backward-compatible way by assigning nonzero `SignerListID` values derived from `1 + TxType`. Existing ledger entries and transactions remain valid, and transactions that do not use the new functionality behave exactly as before. Each additional signer list still consumes an owner reserve, as described above. -## 4. Security +## 8. Security Considerations One important fact to remember is that any signer list that can sign transactions can drain the account's XRP via fees. This was why multiple signer lists were never implemented originally. There is [an open issue](https://github.com/XRPLF/rippled/issues/4476) proposing potential ways to prevent accidental high fees on transactions. @@ -127,7 +204,7 @@ Another design we developed (and seriously considered) was using a bitmask to de The ledger modifications necessary for this design: -- The ledger object hash (`index`) is now derived from the sequence of the transaction that created the signer list (similar to how escrow hashes are derived). This sequence is stored in the `SignerListID` field. +- The ledger entry hash (`index`) is now derived from the sequence of the transaction that created the signer list (similar to how escrow hashes are derived). This sequence is stored in the `SignerListID` field. - Modifying or deleting a signer list that isn't the global one (instead of creating a new one) requires specifying the `SignerListID` in the `SignerListSet` transaction. - Using a signer list that isn't the global one requires specifying the `SignerListID` in the transaction (a new global optional field). diff --git a/XLS-0074-account-permissions/README.md b/XLS-0074-account-permissions/README.md index d33c1e79..5107b549 100644 --- a/XLS-0074-account-permissions/README.md +++ b/XLS-0074-account-permissions/README.md @@ -11,19 +11,25 @@ # Account Permissions -## Abstract +## 1. Abstract This document formalizes different types of transaction-based account permissions. Permissions include all transactions, a single transaction, or a subset of a transaction's capabilities. -## 1. Overview +## 2. Motivation -[XLS-49](../XLS-0049-multiple-signer-lists/README.md) proposed transaction-type-level permissions. These types of permissions can be used for multiple signer lists, as explained in XLS-49, but could also be used in conjunction with other features. +Global signer lists and regular keys currently provide an all-or-nothing model of access control: any key or signer list that can sign for an account can submit all transaction types on its behalf. For many operational setups—for example, token issuers that want separate controls for minting, trustline management, and account configuration—this makes it hard to apply least-privilege practices and increases the blast radius of compromised keys. + +This XLS defines a shared, transaction-oriented account-permission namespace that other features can build on, such as permission delegation in [XLS-75](../XLS-0075-permission-delegation/README.md) and multiple signer lists in [XLS-49](../XLS-0049-multiple-signer-lists/README.md). By standardizing how permissions are represented, implementations can provide more granular, interoperable authorization schemes while preserving compatibility with existing global signer lists. + +## 3. Overview + +This XLS introduces transaction-type-level permissions that can be used for multiple signer lists and other features which require fine-grained control over what transactions an account may authorize. Currently, it's all or nothing - global signer lists and regular keys can do all transactions. Sometimes you want to provide an account permissions to a subset of features, like with `NFTokenMinter` - maybe a few transaction types (e.g. all AMM transaction), or a single transaction type (e.g. `NFTokenMint`), or even some portion of a transaction type (e.g. authorizing trustlines). This standard formalizes those transaction-type permissions, and also adds more granular permission options. -### 1.1. Background: Integer Types +### 3.1. Background: Integer Types An [integer](https://www.techtarget.com/whatis/definition/integer) is a whole number, a number with no decimals. It is usually shortened to `int` in programming languages. @@ -59,31 +65,31 @@ The integer types that the XRPL supports are as follows: _The `sf` in the above table stands for "Serialized Field"._ -## 2. Permissions +## 4. Permissions A permission is represented by a `UInt32`. -### 2.1. Global Permission +### 4.1. Global Permission The global permission value is already used in existing signer lists; they have a `SignerListID` value of `0`. This is being retroactively redefined to mean that the signer list has global permissions (i.e. can submit any transaction on behalf of an account). **`0`: all permissions** -### 2.2. Transaction Type Permissions +### 4.2. Transaction Type Permissions A transaction type is represented by a `UInt16`. -Transaction type permissions were previously defined in [XLS-49](../XLS-0049-multiple-signer-lists/README.md), section `2.1.1`. +In this scheme, each transaction type is assigned a corresponding permission value derived from its serialized transaction type identifier. **`1` to `65536` ($2^{16}$): all transaction types** (1 + their serialized value, which is represented by a `UInt16`) Adding a new transaction type to the XRPL will automatically be supported by any feature that uses these permissions. -#### 2.2.1. `Batch` Transactions +#### 4.2.1. `Batch` Transactions The one exception to this rule is `Batch` transactions ([XLS-56](../XLS-0056-batch/README.md)). They will not have a separate permission, since `Batch` transactions on their own do not do anything. In order to execute a `Batch` transaction with a permission, the user will need to have permissions for all the inner transactions. -### 2.3. Granular Permissions +### 4.3. Granular Permissions These permissions would support control over some smaller portion of a transaction, rather than being able to do all of the functionality that the transaction allows. @@ -104,7 +110,7 @@ We are able to include these permissions because of the gap between the size of | `65547` | `MPTokenIssuanceLock` | Use the `MPTIssuanceSet` transaction to lock (freeze) a holder. | | `65548` | `MPTokenIssuanceUnlock` | Use the `MPTIssuanceSet` transaction to unlock (unfreeze) a holder. | -### 2.4. Adding Additional Granular Types +### 4.4. Adding Additional Granular Types Many other granular permissions may be added. There is capacity for a total of 4,294,901,759 granular permissions, given the limits of the size of the `UInt32` vs. the size of the `UInt16` (for transaction types). @@ -113,13 +119,19 @@ Some other potential examples include: - `SponsorFee` - the ability to sponsor the fee of another account (from [XLS-68](../XLS-0068-sponsored-fees-and-reserves/README.md)) - `SponsorReserve` - the ability to sponsor the fee of another account/object (from [XLS-68](../XLS-0068-sponsored-fees-and-reserves/README.md)) -#### 2.4.1. Limitations +#### 4.4.1. Limitations The set of permissions must be hard-coded. No custom configurations are allowed. For example, we cannot add permissions based on specific currencies - the best you could theoretically do on that front is XRP vs. issued currency. In addition, each permission needs to be implemented on its own in the source code, so adding a new permission requires an amendment. -## 3. Security +## 5. Rationale + +This XLS defines a shared `UInt32` namespace for account permissions so that multiple features (such as multiple signer lists, delegation, or other future mechanisms) can rely on a consistent set of values. Mapping the global permission to `0`, transaction-type permissions to `1 + TxType`, and granular permissions to higher values uses the gap between the `UInt16` transaction type space and the `UInt32` size of `SignerListID` efficiently while keeping the scheme easy to reason about. + +Alternative approaches, such as defining separate permission spaces for each feature or using feature-specific bitmasks, were rejected because they would fragment the permission model and make interoperability between features more difficult. + +## 6. Security Considerations Giving permissions to other parties requires a high degree of trust, especially when the delegated account can potentially access funds (the `Payment` permission) or charge reserves (any transaction that can create objects). In addition, any account that has permissions for the entire `AccountSet`, `SetRegularKey`, or `SignerListSet` transactions can give themselves any permissions even if this was not originally part of the intention.