0092 XLS-92d: XRPL Sub-accounts

[sappenin]

Title:       XRPL Sub-accounts
Type:        draft

Author:      David Fuelling
Affiliation: Ripple

1. XRPL Sub-Accounts

1.1. Abstract

XRPL Sub-accounts enable a single XRPL account to track on-ledger balances representing tokens owned by a public-key/r-address. By enabling this type of sub-account balance tracking, the ledger can also optionally enable balance transfers
at the sub-account level using transactions signed by the private-key of any particular sub-account.

Today's XRPL ledger uses source and destination
tags to
help off-ledger entities track the balances of their customers whenever an on-ledger payment occurs. However,
these tagging mechanisms do not support hybrid-custody scenarios, where funds might sit on-ledger while being
available to both the custodian and the account holder at the same time (i.e., to enable end-user control, and to
provide 100% transparency to custodial customers that funds are not co-mingled with any other custodian assets).

Likewise, payment tags do not enable the XRP Ledger to support a very large number of self-custody accounts, because
today's account are somewhat large (from a space-on-ledger perspective) and somewhat expensive (from an account reserve
perspective). By enabling token custody and payments using very small -- with reduced functionality -- on-ledger
sub-accounts, this specification seeks to simultaneously reduce storage requirements for simple accounts while also
allowing for enhanced user-trust in institutional DeFi service providers.

1.2. Overview

XRPL Account owners use sub-accounts to track balances for entities that control their own private key
material.

1.2.1. Goals

1. Enable more users to control funds on-ledger without having to create an actual XRPL account (reducing overall reserve costs while also reducing ledger size).
2. Enable a centralized entity to provide transparent DeFi services to large numbers of users while maintaining control for compliance purposes.
3. Ensure that overall XRP Ledger state remains as small as possible while supporting larger numbers of users and accounts.

1.2.2. Terminology

1. Sub-Account: An on-ledger object that is associated with a parent account and tracks a balance for a single public
   key.
2. Sub-Account Page: A collection of sub-account balances tracked in an aggregate form to reduce space on-ledger.
3. Account Owner: An entity that controls a private key corresponding to an XRP Ledger account.
4. Sub-Account Owner: An entity that controls a private-key that has been associated with a particular XRPL
   Account to form a sub-account.

1.2.3. Example Use-cases

The following are example usages of XRPL Sub-accounts:

1. A single account that holds funds for multiple AI agents. Each agent has its own private key that can be used to
   control the agent's discrete portion of the overall omnibus balance. This saves account reserves by making each
   sub-account balance less expensive to track, while still allowing independent payments into and out of each sub-account
   using discrete private keys.
2. A human with a mobile device/phone that can hold private key material (e.g., using a Passkey) and then interact with
   funds that are accessible to a centralized entity like an exchange, stablecoin issuer, or otherwise. It is envisioned
   that this use-case would likely require some of the ideas presented
   in XLS-83d: Passkey Signature Support.
3. A non-custodial wallet that wishes to provide value-added services to large numbers of end-users who don't
   independetly need full account capabilities.
4. Hybrid-custody scenarios where a custodian (e.g., an exchange) and an account holder simultaneously control funds
   (i.e., either key-holder can potentially execute funds transfers). Useful for transparency purposes by allowing
   end-users to independently verify on-chain balances to ensure that a custodian is not co-mingling funds or
   otherwise putting funds at risk.

1.2.4. Protocol Flow

1.2.4.1. Initial Setup

We assume that a centralized entity (e.g., ExchangeCo) has one or more Ed25519 private keys that
allow it to control its own accounts on the XRP Ledger.

1.2.4.1.1. ExchangeCo

1. ExchangeCo creates and funds a regular XRPL account using a private key that it controls.
2. For each ExchangeCo customer, ExchangeCo creates a sub-account that defines what token is being held (and an initial
   balance of zero).

1.2.4.1.2. ExchangeCo Customer (End-User)

1. The customer navigates to the ExchangeCo website, and initiates a Passkey flow to register a new ExchangeCo account.
   For purposes of this document, this passkey is known as the authentication_key, allowing the user to control a (
   non-ledger) account at ExchangeCo using a private key that is bound both to the ExchangeCo website and the device the
   user used to register with ExchangeCo[1].
2. A second Passkey (a siging_key) is created on the user's device. This passkey is used for signing XRPL
   transactions, and is likewise registered with ExchangeCo. Note that ExchangeCo may allow multiple signing keys to be
   created.
3. Using Passkeys, the end-user can control and manage where each passkey lives (e.g., in a password manager,
   on-device, or off-device, for example in a Yubikey or Ledger Nano).
4. For each siging_key, ExchangeCo will derive
   an XRPL address using the sub-account's public key.
5. Next, ExchangeCo will sign and publish a CreateSubAccount transaction to the XRPL, which
   will register the end-user's signing-key as controlling a sub-account in ExchangeCo's omnibus account on the XRPL.
6. In this fashion, a private-key held solely on an off-ledger device can be used to move funds without the address
   actually having an on-ledger account.

1.2.4.2. Payment Flow Examples

1.2.4.2.1. Example: End-user Moves Value Out of a Sub-account

In this example, an end-user with a phone wants to move 10 XRP out of their sub-account held with ExchangeCo.

1. The user assembles an XRPL payment
   transaction.

   1. The Account is the 20-byte address of ExchangeCo.
   2. The SubAccount (a new field proposed to be added to a payment) is the 20-byte address of the sub-account.
   3. The SigningPubKey is the public key corresponding to SubAccount.
   4. The Destination field works per-usual, and indicates where a payment should be sent.

2. The SubAccount user signs the transaction using the pre-registered sub-account signing_key stored on their
   phone/device, and publishes the signed transaction to the XRPL.

3. The payment transactor detectes that a SubAccount has been specified in the payment, so it searches for the correct
   SubAccountCollection page using an algorithm similar to that defined in XLS-20.

   1. If the tfCustodial flag is set but tfNonCustodial is unset, then the transaciton is valid only if signed by
      the Account private key. In this case, the transaction fails because it was signed by the SubAccount, but payments
      may only be executed by the custodian (i.e., the Account).
   2. If the tfCustodial flag is unset, but tfNonCustodial is set, then the transaciton is valid only if signed by
      the SubAccount private key. In this case, the transaction is valid and succeeds if the balance is sufficient.
   3. If both tfCustodial and tfNonCustodial flags are set, then the transaction is valid if signed by either
      the Account or SubAccount private key. In this case, the transaction is valid and succeeds if the balance
      is sufficient.

   (Note that one flag or both must be set in order for a SubAccountCollection to be created).

1.2.4.2.2. Example: ExchangeCo Moves Value Out of a Sub-account

In this example, ExchangeCo wants to move 10 XRP out of a sub-account under their control (e.g., in response to an
exchange order to sell XRP).

1. ExchangeCo assembles an XRPL payment
   transaction.
   1. The Account is the 20-byte address of ExchangeCo.
   2. The SubAccount (a new field proposed to be added to a payment) is the 20-byte address of the sub-account.
   3. The SigningPubKey is the public key corresponding to Account.
   4. The Destination field works per-usual, and indicates where a payment should be sent.
2. ExchangeCo signs the transaction using its own private key and publishes the signed transaction to the XRPL.
3. The payment transactor detectes that a SubAccount has been specified in the payment, so it searches for the correct
   SubAccountCollection page using an algorithm similar to that defined in XLS-20.
   1. If the tfCustodial flag is set but tfNonCustodial is unset, then the transaciton is valid only if signed by
      the Account private key. In this case, the transaction is valid and succeeds if the balance is sufficient.
   2. If the tfCustodial flag is unset, but tfNonCustodial is set, then the transaciton is valid only if signed by
      the SubAccount private key. In this case, the transaction fails because it was signed by the Account, but payments
      may only be executed by the SubAccount.
   3. If both tfCustodial and tfNonCustodial flags are set, then the transaction is valid if signed by either
      the Account or SubAccount private key. In this case, the transaction is valid and succeeds if the balance
      is sufficient.

1.2.4.2.3. Example: Move Value Into a Sub-account

In this example, a regular account signer wants to send 10 XRP into a sub-account held with ExchangeCo.

1. An XRPL payment transaction is
   assembled with the following:
   1. The Account and SigningPubKey (assuming single-sig) work per-usual for the sender of funds.
   2. The Destination field works per-usual, and is the 20-byte address of ExchangeCo.
   3. A new field, SubAccountDestination specifies the address of the sub-account.

The SubAccountDestination is a new field that, if persent, is used to locate the sub-account to credit funds to.

1.3. On-Ledger Data Structures

We propose two new objects and one new ledger structure:

1. A SubAccountCollection is a is a new object that describes an overall collection of balances tracked by an
   account.
2. A SubAccount is a new object that describes a balance owned by a public-key.
3. A SubAccountPage is a ledger structure that contains a set of SubAccount objects contained inside a
   SubAccountCollection.

1.3.1. The SubAccountCollection object

The SubAccountCollection object represents a collection of sub-accounts and their associated data.

SubAccountCollections are created using the SubAccountCollectionCreate transaction and can be destroyed using the
SubAccountCollectionDelete transaction, if certain conditions are met.

1.3.1.1. SubAccountCollection Identifier

The identifier of a SubAccountCollection is defined as a SubAccountCollectionID, and is the result of SHA512-Half
of the following values, concatenated in order:

• The SubAccountCollection space key (0x009F).
• The AccountID of the collection creator.
• The IssuanceID of the token that this sub-account holds.

1.3.1.2. Fields

SubAccountCollection objects are stored in the ledger and tracked in
an Owner Directory owned by the collection creator. These collections
have the following required and optional fields:

Field Name	Required?	JSON Type	Internal Type	Bytes
LedgerEntryType	✔️	number	UINT16	2
Flags	✔️	number	UINT32	4
Account	✔️	string	ACCOUNTID	20
Issuance	✔️	object	STIssue	32-40
TransferFee	️(default)	number	UINT16	2
PreviousTxnID	✔️	string	HASH256	32
PreviousTxnLgrSeq	️:heavy_check_mark:	number	UINT32	4
OwnerNode	(default)	number	UINT64	8

1.3.1.3.1. LedgerEntryType

The value 0x009E, mapped to the string SubAccountCollection, indicates that this object describes a
SubAccountCollection.

1.3.1.3.2. Flags

Flags for a SubAccountCollection.

1.3.1.3.2.1. SubAccountCollection Flags

Flag Name	Flag Value	Description
tfCustodial	️0x0001	If set, the omnibus account owner can move funds out of the account.
tfNonCustodial	️0x0020	If set, the sub-account owner may move funds out of the account.

Note that shared-custody (also known as hybrid-custody) can be enabled by setting both flags.

1.3.1.3.3. Account

The Account that owns this collection.

1.3.1.3.4. Issuance

An STIssue that uniquely identifies the token type for balances tracked by this collection. For Issued Currencies, this will contain the currency code and issuer address (approx 40 bytes). For MPTs, this will contain an MPTokenIssuanceID (approximately 24 bytes). Note that in any single account, there must be a distinct SubAccountCollection for each token type.

1.3.1.3.5. TransferFee

This value specifies the fee, in tenths of a basis point, charged by
the omnibus account owner for transfers out of sales of the omnibus account (if such transfers are allowed at all).
Valid values for this field are between 0 and 50,000 inclusive. A value of 1 is equivalent to 1/10 of a basis point or
0.001%, allowing transfer rates between 0% and 50%. A TransferFee of 50,000 corresponds to 50%. The default value for
this field is 0. Any decimals in the transfer fee will be rounded down, hence the fee can be rounded down to zero if the
payment is small.

1.3.1.3.6. PreviousTxnID

The identifying hash of the transaction that most recently modified this object.

1.3.1.3.7. PreviousTxnLgrSeq

The index of the ledger that contains the transaction that most recently modified this object.

1.3.1.3.8. OwnerNode

Identifies the page in the owner's directory where this item is referenced.

1.3.1.4. Examples

This section contains example SubAccount objects.

1.3.1.4.1. Example SubAccountCollection JSON

 {
  "LedgerEntryType": "SubAccountCollection",
  "PreviousTxnID": "...",
  "PreviousTxnLgrSeq": "82658009",
  "Issuance": "57AB27D414752E6E17D4D375509BFD851CA0EABF454C703CB6EE577543A794DD",
  "Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
  "SubAccounts": [
    {
      "SubAccount": "r93cLcQdjAH4Gz9FDhgPz1N4K4hXvHBP5N",
      "Balance": "200"
    }
  ],
  "OwnerNode": "74"
}

1.3.2. The SubAccount Ledger Object

This structure defines a single sub-account.

1.3.2.1. Fields

SubAccount objects have the following required and optional fields:

Field Name	Required?	JSON Type	Internal Type	# Bytes
SubAccount	✔️	string	ACCOUNTID	20
Balance	(default)	number	UINT64	8
Sequence	✔️	number	UINT32	4

1.3.2.2.1. SubAccount

The address of the sub-account.

1.3.2.2.2. Balance

An STAmount representing the amount of token (XRP/MPT/IOU) that this sub-account currently holds.

1.3.2.3. Examples

This section contains example SubAccount objects.

1.3.2.3.1. Example SubAccount JSON

{
 "SubAccount": "r93cLcQdjAH4Gz9FDhgPz1N4K4hXvHBP5N",
 "Balance": "2500"
}

1.3.3. The SubAccountPage object

TODO: See
XLS-20d

1.4. Transactions

This proposal introduces several new transactions to allow for the creation and deletion of SubAccounts.

All transactions introduced by this proposal incorporate
the common transaction fields that are shared by all transactions.
Common fields are not documented in this proposal unless this proposal introduces new possible values for such fields.

1.4.1. The SubAccountCreate Transaction

TODO (only allowed by the owner of the SubAccount)

1.4.2. The SubAccountDelete Transaction

TODO (only allowed if the account is empty)

1.4.1. The SubAccountCollectionCreate Transaction

TODO

1.4.2. The SubAccountCollectionDelete Transaction

TODO (only allowed if there are no sub-accounts)

1.4.3. Changes to Payment Transaction

This specification proposes adding a SubAccount field to the Payment transaction. This field mirrors the Account
field, as follows:

Field Name	Required?	JSON Type	Internal Type	# Bytes
SubAccount		string	ACCOUNTID	20

2. Footnotes

• [1] This is generally true, but with nuance. Read more about device-bound
  Passkeys here, and consult this
  discussion here as well for some
  of the nuances.

3. Appendices

3.1. Appendix: Non-normative Examples

This appendix contains non-normative descriptions of various example use-cases.

3.1.1. Example: TBD

TBD

3.2. Appendix: FAQs

This appendix answers frequently asked questions (FAQs) relating to this specification.

3.2.1. Why not use LiteAccounts?

This proposal requires fewer bytes on-ledger for each sub-account (sub-accounts require ~32 bytes compared to ~87 bytes
for Lite Accounts). In addition, Lite Accounts cost 1 owner reserve per account. SubAccounts, on the other hand, should cost approx 1/32 of the base reserve.

3.2.2. What are the benefits of hybrid-custody sub-accounts?

Hybrid custody sub-accounts allow both a custodian (e.g., an exchange) and an account holder to simultaneously control
funds; i.e., either key-holder can potentially execute funds transfers.

This is useful for transparency purposes and also allows end-users to independently verify on-chain balance to ensure that
a custodian is not co-mingling funds or otherwise putting funds at risk. In this way, if an account holder ever wants to
move funds out of an exchange's omnibus account, that end-user always has full control over their own funds. At the same
time, the centralized entity can also move funds out of the shared account and into a transactional account to ensure
proper funding of any transactions initiated by the account holder.

3.2.3. Doesn't existing multisig already enable hybrid-custody?

Yes, it does (hybrid-custody is equivalent to a 1-of-2 multisig). However, today's XRPL full-accounts are expensive, both from a ledger-space perspective and historically also from a reserves perspective. Until recently, every new account on the XRPL cost 10 XRP. While the base reserve is now only 1 XRP, sub-accounts cost 1/32nd of the owner reserve (currently 0.2 XRP) meaning each new sub-account balance should cost approximately 0.00625 XRP.

3.2.4 Does a Sub-account have less capability/functionality than a regular account?

Yes, much less. That's the tradeoff this document is proposing: a less-functional account primitive that only tracks a balance and allows for value movement, in exchange for much lower fees and fewer required on-ledger resources.

[ximinez]

payment tags do not enable the XRP Ledger to support a very large number of self-custody accounts

I may be misunderstanding your point here, but payment tags are 32-bits, which allows for over 4 billion options. But if you're talking about self-custody accounts, yeah, we wouldn't want 4 billion of those.

Other thoughts:

1. A Sub-Account (intentionally) has no way to link back to the SubAccountCollection, Sub-Account Page, or Sub-Account Owner. I'm a little wary of having a balance stored as a "plain" number with no indication of what it represents. However, I also note that the transaction requires the Sub-Account Owner, and thus would have to go through the collection to get to the Sub-Account. I assume any lookup methods will also have this requirement, and should be less risky.
2. However, I think that also means that if an exchange wants to allow custody of different assets (e.g. XRP and USD), then it would need different SubAccountCollections, and each SubAccount would have a different AccountID. That may lead to a sub-optimal user experience. e.g. "My XRP sub-account is rABCD..., and my USD sub-account is rWXYZ...."
3. Another use case I've seen discussed for centralized custody is for holding NFTs. It would be cool if this proposal could support that, or even just have the potential to support that in the future.

[sappenin]

I may be misunderstanding your point here, but payment tags are 32-bits, which allows for over 4 billion options. But if you're talking about self-custody accounts, yeah, we wouldn't want 4 billion of those

Yeah, I think we're seeing things the same. Basically I just meant that "payment tags != self/hybrid-custody" so if we want things like broad self/hybrid-custody or otherwise, payment tags will be insufficient.

[sappenin]

I'm a little wary of having a balance stored as a "plain" number with no indication of what it represents

Agreed. My intention was to mitigate this by having each SubAccountCollection have a single Issuance that applies to all of its sub-accounts. So, the UInt64 stored in each SubAccount will always only represent a single issuance of XRP, IOU, or MPT depending on value set in the collection.

the transaction requires the Sub-Account Owner, and thus would have to go through the collection to get to the Sub-Account

Correct. The current proposal imagines something like NFT page storage, so basically the lookup is: (1) Find the page by SubAccountID which is basically just one lookup; (2) Cycle through up to 32 objects to find the SubAccount.

I assume any lookup methods will also have this requirement.

I think so, yes.

[sappenin]

If an exchange wants to allow custody of different assets (e.g. XRP and USD), then it would need different SubAccountCollections, and each SubAccount would have a different AccountID.

I was thinking that any SubAccountCollection owner could determine whether or not to allow their end-users to associate the same public-key to different collections. That would preclude different sub-accounts across the same collection owner's collections from having different AccountID values.

But you're point about sub-optimal user experience is still valid depending on the final design here. For example, even though My XRP sub-account is rABCD..., and my USD sub-account is rWXYZ.... won't happen in that circumstance, what would happen is sort of the inverse, which is still sub-optimal: My XRP sub-account is rABCD..., and my USD sub-account is rABCD...but the exchange accounts are different for each issuance. (i.e., paying me XRP vs. USD means two different exchange accounts). I think that part is unavoidable (but open to ideas).

Another criticism of my current design is that Payments need to specify a 2nd address in order to target a sub-account, which is a pretty big change to existing software. As I was thinking about solving this, it occurred to me that on-ledger we could store an a destination_tag on a SubAccount and then potentially the Payment transaction wouldn't need to specify a 2nd address; instead, payments would specify exchange_dst+dst_tag, but rippled could look up by the actual sub-account associated with the specified destination_tag in order to validate a signature.

I need to think a bit more about that one, but I think it could work and wouldn't require existing software to change.

[tequdev]

should cost approx 1/32 of the base reserve.

What about the ledger size aspect used in one incremental reserve?
For example, NFTokenPage is very large compared to other ledger object types.

[sappenin]

Hmmm... good point, I haven't computed the size of each page to be certain, so worth thinking about. I was instead focusing more on the idea that any SubAccountCollection owner (e.g., an exchange or FI) would probably have lots of sub-accounts, so what's the ideal structure to use if we assume that.

[tequdev]

Instead of using one incremental reserve for each SubAccountCollection, I propose increasing the incremental reserve according to the size of the collection, as is the case with Oracle objects.

[shortthefomo]

This sounds great at the surface, how does the amendment encourage exchanges to use this? We also saw something similar in the past with x addresses but no one was incentivized to adopt the newer standard...

[sappenin]

Great critique. I would say if institutions/exchanges/FIs etc. don't want to use this, we likely shouldn't activate it (or even build it).

[shrey32]

@sappenin Is there any progress on this? We're working on a project where we could leverage this feature on XRPL than creating one fat wallet and manage everything via tags.

[sappenin]

Is there any progress on this?

Hi @shrey32 - thanks for your comment! Outside of this issue, I don't have updates (we're still exploring feasibility and utility of this feature, but it's not currently on any of our Roadmaps).

Would you mind sharing more info about your use-case? It's always helpful for a new feature to have really clear use-cases (so others in the community can better form an opinion around whether or not this is something to pursue).