0064 XLS - 64d: Pseudo-Account

[Tapanito]

    
Title:        Pseudo-Account
Type:         draft
Revision:     1 (2025-03-04)

 Authors:    
  Vytautas Vito Tumas

Affiliation: 
  Ripple

Pseudo-Account

Abstract

In this document, we propose a standard for a pseudo-account, an AccountRoot object that can be associated with one or more other ledger entries to hold and/or issue assets on behalf of the associated entries.

1. Introduction

The XRP Ledger is an account-based blockchain in which assets—such as XRP, IOUs, or MPT—can only be held by an account represented by an AccountRoot ledger entry. However, certain use cases, such as Automated Market Makers (AMM), Single Asset Vaults, and the Lending Protocol—require assets to be transferable to and from an object.

The XLS-30 specification introduced the AMMID field in the AccountRoot ledger entry. This field associates a pseudo-account with an AMM instance, allowing it to track XRP and token balances in the pool and issue LPTokens on behalf of the AMM instance.

This specification formalises the requirements for an AccountRoot when used as a pseudo-account. Specifically, it defines:

• A set of flags that must be enabled.
• A naming convention for the field identifying the object the AccountRoot is associated with.
• Minimum requirements for any protocol implementing a pseudo-account.

2. Ledger Entries

2.1. AccountRoot Ledger Entry

2.1.1. Object Identifier

The address of the AccountRoot must be randomised to prevent users from identifying and funding the address before its creation. The protocol that creates an AccountRoot must ensure the account address is unoccupied.

The unique ID of the AccountRoot object, a.k.a. AccountRootID is computed as follows:

• for (i = 0; i <= 256; i--)
  • Compute AccountRootID = SHA512-Half(i || Parent Ledger Hash || <Object>ID>)
  • If the computed AccountRootID exists, repeat
    • else, return AccountRootID

2.1.2. Fields

Field Name	Modifiable?	Required?	JSON Type	Internal Type	Default Value	Description
<Object>ID	N/A	no	string	HASH256	N/A	The object identifier the pseudo-account is associated with.
Flags	no	yes	number	UINT32	N/A	A set of flags that must be set for a pseudo-account.
Sequence	no	yes	number	UINT32	0	The sequence number of the pseudo-account.
RegularKey	no	yes	string	ACCOUNTID	N/A	The address of a key pair that can be used to sign transactions for this account instead of the master key.

2.1.2.1. <Object>ID

The <Object>ID field uniquely identifies the ledger entry associated with an account. Any protocol introducing a pseudo-account must include a new, optional <Object>ID field.

The naming convention for this field follows these rules:

• <Object> represents the name of the related object:
  • All letters must be capitalised if the name is an acronym (e.g., AMM).
  • Otherwise, capitalise the first letter of each noun (e.g., Vault or LoanBroker).
• ID must always be appended as a suffix.

2.1.2.2. Flags

The following flags must be set for a pseudo-account:

Flag Name	Flag Value	Modifiable?	Description
lsfDisableMaster	0x01	No	Ensure that no one can control the account directly and send transactions on its behalf.
lsfDepositAuth	0x001	No	Ensure that the only way to add funds to the account is by using a deposit transaction.

2.1.2.3. Sequence

The Sequence number of a _pseudo-account_ must be 0. A pseudo-account cannot submit valid transactions.

2.1.2.4. RegularKey

A pseudo-account must not have a RegularKey set.

2.1.3. Cost

A transaction that creates a pseudo-account must incur a higher-than-usual transaction fee to deter ledger spam. Additionally, the transaction must destroy at least the incremental owner reserve amount, currently 2 XRP.

2.1.4. Invariant

The following invariants must hold for a pseudo-account:

• The object identified by <Object>ID must exist on the ledger.
• Exactly one <Object>ID must be set (e.g., a pseudo-account cannot have both AMMID and VaultID at the same time).
• The lsfDepositAuth and lsfDisableMaster flags must be set.
• The Sequence number must be 0.
• The RegularKey must not be set.

[dangell7]

Why do you need LedgerEntries? Can you not just use the ownerDir?

[mvadari]

The owner directory can have many additional objects in it. For example, an AMM account has one AMM object and lots of trustlines.

[gregtatcam]

There are a number of cases where AMMID is used as a flag to indicate that the pseudo-account is AMM's account. Once AMMID is replaced with PseudoOwner, all these checks need another call to check if AMM exists for this ID. This level of indirection might be ok for transactions like Clawback, CreateCheck, or Escrow, which are not submitted at high frequency. But it might impact Payment transaction throughput. I think it makes sense to have the associated ledger object type.

[ximinez]

Unpopular opinions:

1. If we're going to include a ledger object type field for the PseudoOwner, then we may as well instead use separate fields for each pseudo-owner object type. Reasoning:
   1. It will actually take less space in the Account Root, because only one of those fields will be populated at a time (this should be enforced by an Invariant). Optional fields take no space on disk or the protocol message, whereas a type field will take a non-zero amount of space.
   2. There is basically no overhead to read multiple fields from the Account Root object compared to reading another ledger object off of disk.
   3. I suspect that many transactions that need to check for a pseudo-owner are not going to need to check for all possible pseudo-owners. (e.g. Don't create a trust line to a X, but Y and Z are ok.) I also suspect that many of the checks will be a simple is it a pseudo-account and not care about the type at all, or the checks can be enforced by other existing functionality. (e.g. If we don't want trust lines created to an X pseudo-account, set the disallow trust lines flag on the account when it's created.)
   4. A minor benefit will be that there will be no need to deprecate AMMID.
2. If we use a single PseudoOwner without a type field, I suspect that caching will negate most or all of the real world overhead of loading the pseudo-owner from the node store to check its type. e.g. If 1,000 payments all touch the same AMM in a relatively short amount of time, then only the first one to load the AMM will actually hit disk. The remaining will just read it from cache, which has negligible overhead. Similarly, if a transaction modifies the same AMM object, it'll also be in cache.

Speculation aside, the only way to really be sure is to implement a proof of concept and test the different options to see which has the best performance properties.

[mvadari]

One additional advantage to having an AMMID-like concept is you can easily check what kind of pseudo-account an account is - e.g. AMM vs loan - without needing to iterate through this list.

[Bronek]

I agree with both @mvadari and @ximinez arguments. Adding an optional fields, specific to the type of the owner (e.g. AMMID, VaultID etc.), makes the resulting code both more performant and type safe, without adding an extra overhead in space, and only a minimal (tiny) overhead if we ever need to check if any of such fields is set. Which probably is not very common use case anyway.

[ximinez]

A couple more thoughts:

1. I think it would make sense to add an invariant that checks the state of a pseudo-account.
   • Create all pseudo-accounts with Sequence 0. (I believe an existing invariant will need to be updated to allow this. Also AMMs are not currently created this way (but we can change it so they are!), so we'll have to account for that.)
   • Define a pseudo-account as any account that has either:
     • A Sequence of 0.
     • One or more of the pseudo-account fields set (AMMID, PseudoOwner if we go that way, or the individual fields if not).
     • lsfDisableMaster and lsfDisableAuth and no RegularKey and no signer list.
   • Add an invariant that finds created/modified/deleted pseudo-accounts (i.e. account roots that have any of those states). The check is that it must have all of those states (accounting for backward compatibility), and exactly one of the pseudo-account fields is set.
2. I can imagine circumstances where it might make more sense to increment the owner count instead of requiring the fee to be >= one owner reserve.
   • For example, imagine an implementation of Escrow that supported tokens. It could create a pseudo-account to hold all the escrowed trust lines for the account. The account would be created automatically when the first escrow is created, and deleted when the last one is finished or cancelled. It wouldn't make sense to require a high fee, because it might not be clear if a pseudo-account is going to be needed or not. And the pseudo-account would be expected to be relatively short-lived, lasting only as long as the funds are escrowed, as opposed to an AMM, which would be expected to live indefinitely.

[Bronek]

Re point 1. I think, in the current use cases we have for a pseudo-account, all three conditions (1. Sequence = 0, 2. set some kind of "owner" field and 3. specific set of flags) must hold, with possible future relaxation re. points 1. and 3.

Points 1. and 3. are invariants i.e. properties of a pseudo-account which could be, in time, altered by future amendments if we see a use case for such alterations while point 2. is an inherent property, without which an account cannot be considered a pseudo-account. The reason why point 2. is exceptional is because the only valid (IMO) use of a pseudo-account is in service to some other object, to which it must be linked via such an "owner" field.

[Tapanito]

Hi everyone,

I have updated the specification in-line with your comments, namely any object associated with a pseudo-account must be identified by an optional unique field. I also added invariants and additional constraints as per @ximinez comment.

Let's move the discussion to the specification pull request: #274

[ximinez]

I think section 2.1.3 Cost should be updated to say something like:

A pseudo-account must increase the owning / controlling account's reserve by 1 in addition to any increases required by the creation of other objects. A transaction that creates a pseudo-account that is not owned or controlled by the creating account must incur a higher-than-usual transaction fee to deter ledger spam, and must destroy at least the incremental owner reserve amount, currently 0.2 XRP.

I believe this spec was written based on the experiences with AMM.

From #240 (comment)

AMMCreate doesn't increase anyone's owner count, partly because the object isn't owned by anyone once it's created, but that's the point - the fee is partly high because there's no one to require a reserve from.

In the case of other objects like Vault or LoanBroker where there is an account that effectively owns and controls the created-pseudo-account I think it makes way more sense to increase the owner count by 2 (1 for the pseudo-account, and 1 for the vault or broker object), and charge a normal transaction fee.

As a ledger object, there is nothing special or unusual about a pseudo-account if it has a single, defined owner. It's not unusually large. It doesn't function independently. It's just needed as a placeholder to allow other objects to work properly.

[Tapanito]

@ximinez could you move this comment to the #274 PR? This discussion is closed, and the spec. version here is out of date.

[mvadari]

I locked the conversation to prevent additional comments here.

[ximinez]

could you move this comment to the #274 PR? This discussion is closed, and the spec. version here is out of date.

Oops. Yes.