0065 XLS - 65d: Single Asset Vault

[Tapanito]

    
Title:        Single Asset Tokenized Vault
Revision:     1 (2024-09-30)

Authors:    
  Vytautas Vito Tumas
  Aanchal Malhotra

Affiliation:
  Ripple

Single Asset Vault

Abstract

A Single Asset Vault is a new on-chain primitive for aggregating assets from one or more depositors, and making the assets available for other on-chain protocols. The Single Asst Vault uses Multi-Purpose-Token to represent ownership shares of the vault. The vault serves diverse purposes, such as lending markets, aggregators, yield-bearing tokens, asset management, etc. The Single Asset Vault decouples the liquidity provision functionality from the specific protocol logic.

1. Introduction

1.1 Overview

The Single Asset Vault is an on-chain object that aggregates assets from one or more depositors and represents ownership through shares. Other protocols, such as the Lending Protocol, can access these assets via the vault, whether or not they generate yield. Currently, other protocols must be created by the same Account as the Vault. However, this may change in the future.

The specification introduces a new Vault ledger entry, which contains key details such as available assets, shares, total vault value, and other relevant information.

The vault specification includes the following transactions:

Vault Management:

• VaultSet: Creates a new or updates an existing vault object.
• VaultDelete: Deletes an existing vault object.

Asset Management:

• VaultDeposit: Deposits a specified number of assets into the vault in exchange for shares.
• VaultWithdraw: Withdraws a specified number of assets from the vault in exchange for shares.

Additionally, an issuer can perform a Clawback operation:

• VaultClawback: Allows the issuer of an IOU or MPT to claw back funds from the vault, as outlined in the Clawback documentation.

1.1.1 Vault Ownership and Management

A Single Asset Vault is owned and managed by an account called the Vault Owner. The account is reponsible for creating, updating and deleting the vault object.

1.1.2 Access Control

A Single Asset Vault can be either public or private. Any depositor can deposit and redeem liquidity from a public vault, provided they own sufficient shares. In contrast, access to private shares is controlled via Permissioned Domains, which use on-chain Credentials to manage access to the vault. Only depositors with the necessary credentials can deposit assets to a private vault. To prevent Vault Owner from locking away depositor funds, any share holder can withdraw funds.

1.1.3 Yield Bearing Shares

The shares represent the ownership of the portion of the vault's assets. On-chain shares are represented by a Multi-Purpose Token. When creating the vault, the Vault Owner can configure the shares to be non-transferable. Non-transferable shares cannot be transferred to any other account -- they can only be redeemed. If the vault is private, the shares can be transferred and used in other DeFi protocols as long as the account is authorized to hold the shares. The vault's shares may be yield-bearing, depending on the protocol connected to the vault, meaning that a holder may be able to withdraw more (or less) liquidity than they initially deposited.

1.2 Terminology

• Vault: A ledger entry for aggregating liquidity and providing this liquidity to one or more accessors.
• Asset: The currency of a vault. It is either XRP, a Fungible Token or a Multi-Purpose Token.
• Share: Shares represent the depositors' portion of the vault instances assets. Shares are a Multi-Purpose Token created by the pseudo-account of the vault.
  Protocol Instance: A separate XRP Ledger protocol requiring access to aggregated liquidity.

1.3 Actors

• Vault Owner: An account responsible for creating and deleting The Vault.
• Depositor: An entity that deposits and withdraws assets to and from the vault.

1.4 Connecting to the Vault

A protocol connecting to a Vault must track it's debt. Furthermore, the updates to the Vault state when funds are removed or added back must be handled in the transactors of the protocol. For an example, please refer to the Lending Protocol specification.

2. Ledger Entries

2.1 Vault Ledger Entry

The Vault ledger entry describes the state of the tokenized vault.

2.1.1 Object Identifier

The key of the Vault object is the result of SHA512-Half of the following values concatenated in order:

• The Vault space key 0x0056 (capital V)
• The AccountID(https://xrpl.org/docs/references/protocol/binary-format/#accountid-fields) of the account submitting the VaultSettransaction, i.e.VaultOwner.
• The transaction Sequence number. If the transaction used a Ticket, use the TicketSequence value.

2.1.2 Fields

A vault has the following fields:

Field Name	Modifiable?	Required?	JSON Type	Internal Type	Default Value	Description
LedgerEntryType	N/A	✔️	string	UINT16	TODO	Ledger object type.
LedgerIndex	N/A	✔️	string	UINT16	N/A	Ledger object identifier.
Flags	Yes	✔️	string	UINT32	0	Ledger object flags.
PreviousTxnID	N/A	✔️	string	HASH256	N/A	Identifies the transaction ID that most recently modified this object.
PreviousTxnLgrSeq	N/A	✔️	number	UINT32	N/A	The sequence of the ledger that contains the transaction that most recently modified this object.
Sequence	N/A	✔️	number	UINT32	N/A	The transaction sequence number that created the vault.
OwnerNode	N/A	✔️	number	UINT64	N/A	Identifies the page where this item is referenced in the owner's directory.
Owner	No	✔️	string	AccountID	N/A	The account address of the vault owner.
Account	N/A	✔️	string	ACCOUNTID	N/A	The ID of the Vault's pseudo-account.
Data	Yes		string	BLOB	None	Arbitrary metadata about the Vault. Limited to 256 bytes.
Asset	No	✔️	string or object	ISSUE	N/A	The asset of the vault. The vault supports XRP, Fungible Token and Multi-Purpose Token.
AssetsTotal	N/A	✔️	number	NUMBER	0	The total value of the vault.
AssetsAvailable	N/A	✔️	number	NUMBER	0	The asset amount that is available in the vault.
AssetsMaximum	Yes	✔️	number	NUMBER	0	The maximum asset amount that can be held in the vault. Zero value 0 indicates there is no cap.
Share	N/A	✔️	object	MPT	0	The identifier of the share MPTokenIssuance object.
SharesTotal	N/A	✔️	number	UINT64	0	The total amount of shares issued by the vault.
WithdrawalPolicy	No	✔️	string	UINT8	N/A	Indicates the withdrawal strategy used by the Vault.
PermissionedDomainID	No		string	HASH256	None	The permissioned domain identifier of the Vault. This value is ignored if the vault is public.

2.1.2.1 Flags

The Vault object supports the following flags:

Flag Name	Flag Value	Modifiable?	Description
lsfFrozen	0x0001	Yes	If set, indicates that the vault is frozen.
lsfPrivate	0x0002	No	If set, indicates that the vault is private.

2.1.3 Vault _pseudo-account_

An AccountRoot entry holds the XRP, IOU or MPT deposited into the vault. It also acts as the issuer of the Vault's LP Tokens. The pseudo-account follows the XLS-64d specification for pseudo accounts. The AccountRoot object is created when creating the Vault object.

2.1.4 Ownership

The Vault objects are stored in the ledger and tracked in an Owner Directory owned by the account submitting the VaultSet transaction. Furthermore, to facilitate Vault object lookup from the vault shares, the object is also tracked in the OwnerDirectory of the pseudo-account.

2.1.5 Owner Reserve

The Vault object costs one owner reserve for the account creating it.

2.1.6 Vault Shares

Shares represent the portion of the Vault assets a depositor owns. Vault Owners set the currency code of the share and whether the token is transferable during the vault's creation. These two values are immutable. The share is represented by a Multi-Purpose Token. The MPT is issued by the vault's pseudo-account.

2.1.6.1 MPTokenIssuance

The MPTokenIssuance object represents the share on the ledger. It is created and deleted together with the Vault object.

2.1.6.1.1 MPTokenIssuance Values

Here’s the table with the headings "Field," "Description," and "Value":

Field	Description	Value
Issuer	The AccountID of the Vault's pseudo-account.	pseudo-account ID
AssetScale	TODO	-
MaximumAmount	No limit to the number of shares that can be issued.	0xFFFFFFFFFFFFFFFF
TransferFee	The fee paid to transfer the shares.	0
MPTokenMetadata	Arbitrary metadata about the share MPT, in hex format.	-

Flags

The following flags are set based on whether the shares are transferable and if the vault is public or private.

Condition	Transferable	Non-Transferable
Public Vault	lsfMPTCanEscrow lsfMPTCanTrade lsfMPTCanTransfer	No Flags
Private Vault	lsfMPTCanEscrow lsfMPTCanTrade lsfMPTCanTransfer lsfMPTRequireAuth	lsfMPTRequireAuth

2.1.6.2 MPToken

The MPToken object represents the amount of shares held by a depositor. It is created when the account deposits liquidity into the vault and is deleted when a depositor redeems (or transfers) all shares.

2.1.6.2.1 MPToken Values

The MPToken values should be set as per the MPT specification.

Condition	Transferable	Non-Transferable
Public Vault	No Flags	lsfMPTAuthorized
Private Vault	lsfMPTAuthorized	lsfMPTAuthorized

2.1.7 Exchange Algorithm

Exchange Algorithm refers to the logic that is used to exchange assets into shares and shares into assets. This logic is executed when depositing or redeeming liquidity. A Vault comes with the default exchange algorithm, which is detailed below.

2.1.7.1 Computing shares

Variables

The following variables define the Vault balance:

• $\Gamma_{share}$ - the total number of shares issued by the vault.

• $\Gamma_{asset}$ - the total assets in the vault, including any future yield.

• $\Delta_{asset}$ - the change in the total amount of assets after a deposit, withdrawal, or redemption.

• $\Delta_{share}$ - che change in the total amount of shares after a deposit, withdrawal, or redemption.

2.1.7.1.1 Deposit

We compute the number of shares ($\Delta_{share}$) a depositor will receive as follows:

$$\Delta_{share} = \frac{\Delta_{asset} \times (\Gamma_{share} + 0^{share})}{\Gamma_{asset} + 0^{asset}} $$

The following equations govern the updated vault composition after a successful deposit:

• $\Gamma_{asset} = \Gamma_{asset} + \Delta_{asset}$ New balance of assets in the vault.
• $\Gamma_{share} = \Gamma_{share} + \Delta_{share}$ New share balance in the vault.

2.1.7.1.2 Redeem

We compute the number of assets ($\Delta_{asset}$) returned by burning $\Delta_{share}$ as follows:

$$\Delta_{asset} = \frac{\Delta_{share} \times (\Gamma_{asset} + 0^{asset})}{\Gamma_{share} + 0^{share}} $$

The following equations govern the updated vault composition after a successful redemption:

• $\Gamma_{asset} = \Gamma_{asset} - \Delta_{asset}$ New balance of assets in the vault.
• $\Gamma_{share} = \Gamma_{share} - \Delta_{share}$ New share balance in the vault.

2.1.7.1.3 Withdraw

We compute the number of shares to burn to withdraw $\Delta_{asset}$ as follows:
$$\Delta_{share} = \frac{\Delta_{asset} \times (\Gamma_{share} + 0^{\Gamma_{share}})}{\Gamma_{asset} + 0^{\Gamma_{asset}}} $$

The following equations govern the updated vault composition after a successful withdrawal:

• $\Gamma_{asset} = \Gamma_{asset} - \Delta_{asset}$ New balance of assets in the vault.
• $\Gamma_{share} = \Gamma_{share} - \Delta_{share}$ New share balance in the vault.

2.1.7.2 Withdrawal Policy

Withdrawal policy controls the logic used when removing liquidity from a vault. Each strategy has its own implementation, but it can be used in multiple vaults once implemented. Therefore, different vaults may have different withdrawal policies. The specification introduces the following options:

2.1.7.2.1 first-come-first-serve

The First Come, First Serve strategy treats all requests equally, allowing a depositor to redeem any amount of assets provided they have a sufficient number of shares.

2.1.7 Frozen Assets

The issuer of the Vaults asset may enact a freeze either through a Global Freeze for IOUs or locking MPT. When the vaults asset is frozen, it can only be withdrawn by specifying the Destination account as the Issuer of the asset. Similarly, a frozen asset may not be deposited into a vault. Furthermore, when the asset of a vault is frozen, the shares corresponding to the asset may not be transferred.

3. Transactions

All transactions introduced by this proposal incorporate the common transaction fields that are shared by all transactions. Standard fields are only documented in this proposal if needed because this proposal introduces new possible values for such fields.

3.1 VaultSet, VaultDelete transactions

The Vault object is managed with VaultSet and VaultDelete transactions.

3.1.1 VaultSet Transaction

The VaultSet transaction creates a new Vault object or updates an existing one.

Field Name	Required?	JSON Type	Internal Type	Default Value	Description
TransactionType	✔️	string	Uint16	TODO	The transaction type.
VaultID	✔️	string	Hash256	N/A	The ID of the Vault to be modified. When not specified, the transaction will create a new Vault object.
Flags	✔️	string	Uint32	0	Specifies the flags for the Vault.
Data		string	Blob		Vault metadata.
Asset	✔️	string or object	Issue	N/A	The asset (XRP, IOU or MPT) of the Vault. This value is non-modifiable.
AssetMaximum		number	Uint64	0	The maximum asset amount that can be held in a vault. The value cannot be lower than the current AssetsTotal of the Vault unless the value is 0.
MPTokenMetadata	✔️	string	Blob		Arbitrary metadata about the share MPT, in hex format. The limit for this field is 1024 bytes.
WithdrawalPolicy	✔️	string	UINT8	N/A	Indicates the withdrawal strategy used by the Vault.
PermissionedDomainID		string	Hash256		The identifier of the PermissionedDomain associated with this Vault object.

3.1.1.1 Flags

Flag Name	Flag Value	Description
tfFreeze	0x0001	Indicates that the vault should be frozen.
tfUnfreeze	0x0002	Indicates that the vault should be unfrozen.
tfPrivate	0x0003	Indicates that the vault is private. It can only be set during Vault creation.
tfShareNonTransferable	0x0004	Indicates the vault share is non-transferable. It can only be set during Vault creation.

3.1.1.2 WithdrawalPolicy

The type indicates the withdrawal strategy supported by the vault. The following values are supported:

Strategy Name	Value	Description
strFirstComeFirstServe	0x0001	Requests are processed on a first-come-first-serve basis.

3.1.1.3 Failure Conditions

• The VaultID is not specified AND:

  • The Asset is MPT, and lsfMPTCanTransfer is not set (the asset is not transferable).
    The Asset is MPT, and the lsfMPTLocked flag is set (the asset is frozen).
    The Asset is an IOU, and the lsfGlobalFreeze flag is set on the issuing account (the asset is frozen).

• The VaultID is specified AND:

  • The submitting account is not the Owner of the vault.
  • The URI field is larger than 256 bytes.
  • The AssetMaximum value is lower than the current AssetsTotal.

3.1.1.4 State Changes

• The VaultID is not specified:

  • Create a new Vault ledger object.
  • Create a new MPTokenIssuance ledger object for the vault shares.
  • Create a new AccountRoot object with VaultID in the ledger entries field.

• The VaultID is specified:

  • Vault object fields are updated.

3.1.2 VaultDelete Transaction

The VaultDelete transaction deletes an existing vault object.

Field Name	Required?	JSON Type	Internal Type	Default Value	Description
TransactionType	✔️	string	Uint16	TODO	Transaction type.
VaultID	✔️	string	Hash256	N/A	The ID of the vault to be deleted.

3.1.2.1 Failure Conditions

• A vault with VaultID does not exist on the ledger.
• The account submitting the transaction is not the VaultOwner.
• AssetsTotal, AssetsAvailable, and SharesTotal are greater than zero.
• The OwnerDirectory if the Vault pseudo-account contains other objects than the vault.

3.1.2.2 State Changes

• Delete MPTokenIssuance and any remaining MPToken objects for the vault shares.
• Delete all trustlines of the vaults pseudo-account.
• Delete the DirectoryNode object.
• Delete the AccountRoot object of the pseudo-account.
• Delete the Vault object.

3.2 VaultDeposit and VaultWithdraw transactions

Depositors call the VaultDeposit and VaultWithdraw transactions to add or remove assets from the Tokenized Vault.

3.2.1 VaultDeposit transaction

The VaultDeposit transaction adds Liqudity in exchange for vault shares.

Field Name	Required?	JSON Type	Internal Type	Default Value	Description
TransactionType	✔️	string	UINT16	TODO	Transaction type.
VaultID	✔️	string	HASH256	N/A	The ID of the vault to which the assets are deposited.
Amount	✔️	string or object	AMOUNT	N/A	Asset amount to deposit.

3.2.1.1 Failure conditions

• The Vault with the VaultID does not exist.
• The asset type of the vault does not match the asset type the depositor is depositing.
• The depositor does not have sufficient funds to make a deposit.
• Adding the Amount to the AssetsTotal of the vault would exceed the AssetsMaximum.
• The Vault is Private and the Account depositing the assets does not have permission to deposit the asset.
• The Vault lsfFrozen flag is set.

3.2.1.2 State Changes

If no MPToken object exists for the depositor, create one. For object details, see 3.4.2 MPToken.

• Increment the MPToken MPTAmount field by $\Delta_{share}$.

• If the deposited Asset is XRP, it is transferred from the depositor account to the AccountRoot of the Vault, updating the Balance field of both accounts.

• If the deposited asset is an IOU, the balance between the Vault pseudo-account and the issuer account is adjusted.

• If the deposited asset is an MPT, the balance of the Vault pseudo-account MPToken is incremented, and the balance of the depositor is decremented by Amount.

• Increase the SharesTotal by $\Delta_{share}$.

• Increase the AssetsTotal and AssetsAvailable by $\Delta_{asset}$.

3.2.2 VaultWithdraw transaction

The VaultWithdraw transaction withdraws Tokens in exchange for the vault's shares.

Field Name	Required?	JSON Type	Internal Type	Default Value	Description
TransactionType	✔️	string	UINT16	TODO	Transaction type.
VaultID	✔️	string	HASH256	N/A	The ID of the vault from which assets are withdrawn.
AssetAmount	✔️	number	UINT64	0	The amount of Vault asset to withdraw.
ShareAmount	✔️	number	UINT64	0	The maximum amount of shares the account is willing to redeem.
Destination		string	AccountID	Empty	An account to receive the assets. It must meet the requirements to hold the asset.

3.2.2.1 Failure conditions

• The Vault with the provided ID does not exist.
• Both AssetAmount and ShareAmount are specified.
• The depositor does not have sufficient shares.
• The account redeeming the funds cannot interact with the vault.
• The issuer of shares does not match the pseudo-account of the vault.
• There is insufficient liquidity in the vault to fill the request.
• If the Destination account is specified, the account does not have permission to hold the asset.
• The Vault lsfFrozen flag is set.

3.2.2.2 State Changes

• If the withdrawn Asset is XRP, it is transferred from the Vault pseudo-accoount to the redeemer, updating each account's Balance field.

• If the withdrawn asset is an IOU, the balance between the Vault pseudo-account and the issuer account is adjusted.

• If the deposited asset is an MPT, the balance of the Vault pseudo-account MPToken is decremented, and the redeemer's balance is decremented by $\Delta_{asset}$.

• Changes to the MPToken object of the share.

  • Decrease the MPTAmount value by $\Delta_{share}$.
  • If MPTAmount is zero, delete the object.

• Decrease the SharesTotal of the Vault by $\Delta_{share}$.

• Decrease the AssetsTotal and AssetsAvailable by $\Delta_{asset}$

3.3 VaultClawback Transaction

3.3.1 VaultClawback transaction

The VaultClawback transaction performs a Clawback from the Vault, exchanging the Shares of an account. Conceptually, the transaction performs VaultWithdraw on behalf of the Holder, sending the funds to the Issuer account of the asset. In case there are insufficient funds for the entire Amount the transaction will perform a partial Clawback, up to the Vault.AssetsAvailable. The Clawback transaction MUST respect any future fees or penalties.

Field Name	Required?	JSON Type	Internal Type	Default Value	Description
TransactionType	✔️	string	UINT16	TODO	Transaction type.
VaultID	✔️	string	HASH256	N/A	The ID of the vault from which assets are withdrawn.
Holder	✔️	string	AccountID	N/A	The account ID from which to clawback the assets.
Amount		number	NUMBER	0	The asset amount to clawback. When Amount is 0 clawback all funds, up to the total Shares the Holder owns.

3.3.1.1 Failure conditions

• The Vault with the provided ID does not exist.
• The account submitting the transactions is NOT the issuer of the Vault's asset.
• The Holder account does not hold any Vault Shares.

3.3.1.2 State Changes

• If the Clawback asset is an IOU, the balance between the Vault pseudo-account and the Issuer account is decreased by up to Amount.

• If the deposited asset is an MPT, the balance of the Vault pseudo-account MPToken is decreased by up to Amount.

• Changes to the MPToken object of the share:

  • Decrease the MPTAmount value by $\Delta_{share}$.
  • If MPTAmount is zero, delete the object.

• Decrease the SharesTotal of the Vault by $\Delta_{share}$.

• Decrease the AssetsTotal and AssetsAvailable by $\Delta_{asset}$

Appendix

A-1 F.A.Q.

A-1.1 What is the difference between a Withdraw and Redeem configuration in the VaultWithdrawtransaction?

The depositor uses the VaultWithdraw transaction to convert their shares for the assets held in the Vault. The depositor does so by specifying either AssetAmount or ShareAmount field. These work as a Withdraw or Redeem.

A Withdraw is performed when the depositor provides the AssetAmount field. The depositor specifies the amount of assets they want to withdraw, and the Vault calculates the cost in terms of Shares.

In contrast, a Redeem is performed when the depositor provides the ShareAmount field. The depositor specifies the mount of share they are willing to burn, and the Vault calculates the Assets amount that will return.

A-1.2 Why does the specification allow both Withdraw and Redeem and not just one of them?

We chose this design in order to reduce the amount of off-chain math required to be implemented by XRPL users and/or developers

[xVet]

For the CUD operations, i wonder, why is the PoolDelegate the only account able to perform update operations and delete operations. Including updates to the PoolDelegateID.

I would expect that the AccountID creating the Pool is the owner and delegates to the PoolDelegate limited functionality.

[rothexD]

Yes Flash-Loan-Pool would be a type of public Pool that would have weighted fee voting shares. I just used it as an example because it was the first hing that came to mind, will have to think about how this applies to protocol based amms

Another shared governance scenario that I was thinking about for a longer time would be a type of Pool where users can lock up assets up to a specific date and after that date if at least 50% of LP-token holders and 50% of LP-tokens agree the funds will be released to a beneficiary. If a quorum is not reached until an end date the assets can be reclaimed by their original holders. This would allow some type of shared community investment/funding (I am not sure about the legal side of this). You could then also do some type of release rounds where x% of assets get released. I have done no research yet if the community would even be interested in something like that. For example a community could fund the development of a video game using that and their next round of fund/ will only be released if milestones are reached and agreed on in a quorum.

I think a lot of what i think about lately can be solved using hooks but not sure if those ever come to main :D

[rothexD]

I think flash loans would only be useful if aams have experienced single side deposits and you can then use this imbalance to balance out all of the aams that have related pairs.

For example:

XRP-Flash-Loan-Pool

XRP/USDX
USDX/KUI
KUI/XRP

For example a lot of KUI are single side deposited into the USDX/KUI pair, you could then flash-loan and get XRP to trade for USDX and put those USDX back into the USDX/KUI pair while taking out KUI to swap it back to XRP.

I hope I didn't miss something there... :D

[xVet]

Thanks @xVet !

The idea is that a PoolDelegate is the pool's owner, and thus, the PoolDelegateID is not changeable. However, now that I think about it, there is no "delegacy" in this case.

Do you think it would be better to have a separate PoolOwner and PoolDelegate where the PoolOwner has all permissions of the Delegate, including deleting the pool and changing the PoolDelegate. Whereas the PoolDelegate may only perform protocol specific operations?

Exactly! I think it makes sense to change the name to PoolOwner and give the owner AccountID the ability to do a AccountSet Flag asfPoolDelegate for delegating functionality to a delegate.

Thoughts on that ?

[mvadari]

I think it makes sense to change the name to PoolOwner and give the owner AccountID the ability to do a AccountSet Flag asfPoolDelegate for delegating functionality to a delegate.

I don't quite understand the need for the flag. Do you mean something similar to NFTokenMinter? If so, IMO in this case that should be on the pool and not on the account.

[Tapanito]

Exactly! I think it makes sense to change the name to PoolOwner and give the owner AccountID the ability to do an AccountSet Flag asfPoolDelegate for delegating functionality to a delegate.

If we introduce a second entity, PoolOwner, I agree with 1). However, I'm not sure about the asfPoolDelegate flag. I think the Pool should be self-contained. The spec should not introduce Pool specific changes to other ledger entries. That is primarily to minimize coupling with other ledger entries. By minimizing coupling, we make the ledger entry easier to change. Or that is the hope at least.

That said, we can achieve the same functionality by introducing two fields, PoolDelegate and PoolOwner to the Pool object. What do you think about that?

[mvadari]

Can the Preview RPC be replaced with XLS-69d?