0049 XLS-49d: Multiple Signer Lists

[mvadari]

Title:       Multiple Signer Lists
Revision:    1 (2023-11-13)

Author:      Mayukha Vadari

Affiliation: Ripple

Multiple Signer Lists

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-31d, but broader in scope.

1. Overview

We propose modifying one ledger object and one transaction:

• SignerList ledger object
• SignerListSet transaction

This change will require an amendment.

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

There is no change to the shape of a SignerList ledger object, only in how it's used.

2.1. Fields

As a reference, the SignerList object currently has the following fields:

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

The ledger index of this object is calculated by hashing together the owner's account ID with the value of 0.

The only field whose usage is changing is SignerListID. All other fields will be used the same as they are now.

2.1.1. SignerListID

This field is currently always set to 0. The original Multisign implementation 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.

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)).

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

The SignerListSet transaction already exists on the XRPL. We propose a slight modification to support per-transaction-type signer lists.

3.1. Fields

As a reference, the SignerListSet transaction already has the following fields:

Field Name	Required?	JSON Type	Internal Type
TransactionType	✔️	string	UInt16
SignerEntries	✔️	array	STARRAY
SignerQuorum	✔️	number	UInt32

We propose adding a new optional field:

Field Name	Required?	JSON Type	Internal Type
TransactionTypeBitmask		array	HASH256

3.1.1. TransactionTypeBitmask

This field accepts a bitmask of transaction types, much like the 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.

4. Security

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 proposing potential ways to prevent accidental high fees on transactions.

Also, any signer list that is added to SignerListSet can effectively give themselves powers over any other transaction(s) they desire.

Appendix

Appendix A: FAQ

A.1: Should global signer lists still be able to send transactions that have specific signer lists enabled?

Yes, because global signer lists should be able to act exactly like master and regular keys. This proposal does not support changing that.

A.2: Why not also use a bitmask for storage?

This design was strongly considered, but this spec is easier to use and understand. See Appendix B for more details.

A.3: Why not just take a transaction type in the TransactionTypeBitmask field?

That was part of the original design, because it would be more user-friendly and easier to read. It was changed to allow accounts to modify multiple signer lists with one transaction.

A.4: Can you remove the global signer list after removing the master and regular key?

No, you need to go through the standard blackhole procedure (setting the regular key to ACCOUNT_ZERO).

Theoretically, an account could only have a specific signer list on at least one of SignerListSet/SetRegularKey/AccountSet so that the blackholing can be changed. However, this addition seems unnecessary since the standard blackhole procedure already exists.

A.5: Why not use crypto-conditions?

This was briefly considered, but we decided to go with this design instead. See Appendix C for more details.

Appendix B: Bitmasks for SignerListID

Another design we developed (and seriously considered) was using a bitmask to determine which transaction types a signer list could sign for. This took inspiration from the HookOn field in the hooks proposal.

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.
• 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).

Ultimately, due to the pros and cons, we decided against this spec. If you have strong feelings about this design (positive or negative), please comment, because it's still in consideration.

B.1. Pros and Cons

Existing Spec

• Pros
  • Ease of use and understandability - same as existing processes
  • Only one signer list can access each transaction (technically two if you include the global signer list)
• Cons
  • One signer list per transaction, even if the same signer list is used for multiple transactions
  • One reserve per transaction
  • Only one signer list can access each transaction

Bitmask

• Pros
  • One signer list object regardless of how many transactions it controls (easier on ledger resources)
  • One reserve per signer list
  • Multiple signer lists can access each transaction
• Cons
  • More UX changes - you need to specify the SignerListID in the transaction. This is all less compatible with the existing UX for the global signer list.
  • Multiple signer lists can access each transaction (this could get messy and is more difficult to keep track of)
  • A larger change to the current usage of signer lists
  • What happens if/when we reach 256 transactions?

Appendix C: Crypto-Conditions

Using crypto-conditions for implementing per-transaction-type multisign was considered, but it seemed overly complex for the use-cases that people have. If a crypto-condition-based multisign approach is implemented, it should probably be integrated into all signatures, and apply to both multi-sign and single-sign.

[shortthefomo]

Any thoughts around maybe a fee limit on the list? Allow signing up to a fee limit.

One important fact to remember is that any signer list that can sign transactions can drain the account's XRP via fees.

[shortthefomo]

eg. Another very useful one would be transaction size. This would possibly make exchanges use signer lists over a standard signature.

Eg. 1-200 XRP list a can sign, 200-2000 list b can sign… and so on requiring more signatures with size.

[mvadari]

That adds a lot of complexity and configuration. This spec (and the alternate one) are both very efficient to run within the current multisig framework. If you need to add amount checks, that adds a lot of overhead.

[WietseWind]

Sounds like a perfect use case for 🪝 😇

[tequdev]

Will the TransactionTypeBitmask and SignerListID correspond?

If so, is it correct that there can be only one list with the same TransactionTypeBitmask, and that when deleting a SignerList, the TransactionTypeBitmask is used as the key?

[tequdev]

It looks like multiple SignerLists are created when multiple transaction types are specified in the TransactionTypeBitmask field of a single SignerListSet transaction.

[mvadari]

For the existing spec, yes, multiple Signer lists are created/modified. This was suggested so that it is easier to set up a signer list that can authorize multiple transaction types.

For the Appendix B spec, the bitmask does not need to be unique. It is not included in the key. Multiple signer lists can have the same bitmask.

[ckeshava]

Regarding the calculation of the SignerListID field, I'm concerned about the potential collisions (earlier than the 256 transactions threshold). Many ledger objects use ASCII characters to compute the key field (Source: https://github.com/XRPLF/rippled/blob/ca3198164c2869406e1f04020f3c1a74c7d35485/src/ripple/protocol/impl/Indexes.cpp#L56)

For instance, this proposal could cause a collision between LedgeNameSpace::BOOK_DIR and a SignerList ledger object with a transaction type of value 65. Is this correct?

I found it hard to test this, because sha512Half function takes an enum only.

[mvadari]

That is incorrect. The key field takes a prefix for the type of the object (which would be the value 65 for BOOK_DIR) and appends on the additional information. There cannot be collisions between objects of different types (assuming that you don't find a hash collision between two separate initial values, of course).

[ckeshava]

I see, okay. So ltSIGNER_LIST is the Space Key. This is used along with accountAddress + (1 + TxType) to get the final SignerListID 👍

[ckeshava]

I like that we can modify multiple transaction types in a single shot. Otherwise, it is difficult for the account administrators to set up a signer_list for every transaction type (assuming they don't want to fall back on the global signer_list)