Amendment Idea: Vault Investment Extension

[dangell7]

  title: Vault Investment Extension
  description: Extension to Single Asset Vault enabling secure investment management through VaultBrokers with fee collection and liquidity management
  author: Denis Angell (@angell_denis)
  status: Idea
  category: Amendment
  requires: XLS-65 (Single Asset Vault)
  created: 2025-09-20

Vault Investment Extension

Abstract

This extension enables Single Asset Vaults to generate yield through authorized VaultBrokers who can invest vault assets. It introduces secure fee collection, two-phase withdrawals for liquidity management, and economic penalties for broker failures. The design prioritizes security and simplicity while enabling vaults to compete with traditional mutual fund economics.

1. Motivation

Single Asset Vaults currently hold assets idle, creating an opportunity cost that makes them economically unviable compared to traditional investment vehicles. This extension addresses:

• Yield Generation: Enable vaults to invest in AMMs, lending protocols, and other yield sources
• Liquidity Management: Handle redemptions when assets are invested
• Fee Economics: Sustainable management fees for brokers
• Security: Prevent malicious brokers from stealing funds

2. Overview

2.1. Core Components

1. VaultBroker: Regular account authorized to invest vault assets
2. Two-Phase Withdrawals: Request → Rebalance → Execute
3. Management Fees: Accrued automatically, collected via secure transaction
4. Investment Execution: Batch-like transaction arrays executed as vault

2.2. Key Principles

• VaultBroker cannot directly access vault funds
• Fees are protocol-calculated, not broker-determined
• Withdrawal requests create binding liquidity obligations
• Economic penalties enforce broker responsibilities

3. Specification

3.1. Modified Vault Fields

Add to existing Vault object from XLS-65:

Field Name	Required	Internal Type	Default Value	Description
VaultBroker	No	ACCOUNT	None	Authorized investment manager
InvestedAmount	Yes	AMOUNT	0	Currently invested assets
ManagementFeeRate	Yes	UINT16	0	Annual fee in basis points
AccruedFees	Yes	AMOUNT	0	Fees earned but not collected
LastFeeTime	Yes	UINT32	0	Last fee accrual timestamp
PendingRedemptions	Yes	AMOUNT	0	Total withdrawal requests
RedemptionDeadline	Yes	UINT32	0	When liquidity must be provided

3.2. Transactions

3.2.1. VaultBrokerSet

Assigns or removes a VaultBroker for a Vault.

3.2.1.1. Fields

Field Name	Required?	JSON Type	Internal Type	Description
TransactionType	Yes	string	UINT16	Value: 105
VaultID	Yes	string	HASH256	Vault to manage
VaultBroker	No	string	ACCOUNT	Broker account (empty to remove)
ManagementFeeRate	No	number	UINT16	Annual fee (basis points)

3.2.1.2. Failure Conditions

1. tecNO_PERMISSION: Not the Vault owner
2. tecNO_TARGET: Vault doesn't exist
3. temMALFORMED: Invalid VaultBroker account
4. temMALFORMED: ManagementFeeRate > 1000 (10% max)
5. tecNO_LINE: PendingRedemptions > 0 (cannot change during redemptions)

3.2.1.3. State Changes

1. Set Vault.VaultBroker = VaultBroker
2. Set Vault.ManagementFeeRate = ManagementFeeRate
3. If removing broker:
   • Require InvestedAmount = 0
   • Clear AccruedFees

3.2.2. VaultBrokerExecute

Executes investment transactions on behalf of vault pseudo-account.

3.2.2.1. Fields

Field Name	Required?	JSON Type	Internal Type	Description
TransactionType	Yes	string	UINT16	Value: 106
VaultID	Yes	string	HASH256	Vault being invested
Flags	Yes	number	UINT32	Execution mode
RawTransactions	Yes	array	STArray	Investment transactions

3.2.2.2. Execution Flags

Use same flags as Batch transactions (XLS-56):

Flag	Value	Description
tfAllOrNothing	0x00010000	All transactions must succeed
tfIndependent	0x00080000	Execute all regardless of failure

3.2.2.3. RawTransactions

Each transaction in array:

• Must be valid XRPL transaction type
• Account field replaced with vault's pseudo-account
• Cannot include fees
• Cannot be signed

Prohibited transaction types:

• AccountSet
• SignerListSet
• AccountDelete
• VaultCreate/VaultSet/VaultDelete
• Any transaction targeting the broker's own account

3.2.2.4. Failure Conditions

1. tecNO_PERMISSION: Sender is not Vault.VaultBroker
2. temMALFORMED: Contains prohibited transaction type
3. temMALFORMED: Transaction would send to broker account
4. tecUNFUNDED: Insufficient assets for investment

3.2.2.5. State Changes

1. Update fee accrual (see 3.3)
2. For each transaction in RawTransactions:
   • Replace Account with vault's pseudo-account
   • Execute transaction
   • Track asset movements
3. Update Vault.InvestedAmount based on flows
4. Update Vault.AssetsAvailable

3.2.3. VaultWithdraw (Modified)

Modified to support two-phase withdrawals.

3.2.3.1. Additional Flags

Flag	Value	Description
tfWithdrawRequest	0x00100000	Create withdrawal request
tfWithdrawCancel	0x00200000	Cancel withdrawal request

3.2.3.2. Behavior by Flag

No flags (Normal Withdrawal):

• Requires AssetsAvailable >= withdrawal amount
• Immediate execution
• Reduces PendingRedemptions if previously requested

tfWithdrawRequest:

• Locks shares
• Increases PendingRedemptions
• Sets RedemptionDeadline = CurrentTime + 86400 (24 hours)
• Does not transfer assets

tfWithdrawCancel:

• Unlocks shares
• Decreases PendingRedemptions
• Must match previous request amount

3.2.3.3. Additional Failure Conditions

For tfWithdrawRequest:

1. tecDUPLICATE: Already has pending request

For tfWithdrawCancel:

1. tecNO_ENTRY: No matching request found

For normal withdrawal:

1. tecNO_LINE: Insufficient AssetsAvailable
2. tecNO_ENTRY: No pending request matching amount

3.2.4. VaultFeeCollect

Collects accrued management fees.

3.2.4.1. Fields

Field Name	Required?	JSON Type	Internal Type	Description
TransactionType	Yes	string	UINT16	Value: 107
VaultID	Yes	string	HASH256	Vault to collect from

3.2.4.2. Failure Conditions

1. tecNO_PERMISSION: Account is not Vault.VaultBroker
2. tecNO_TARGET: Vault doesn't exist
3. tecNO_LINE: AccruedFees = 0
4. tecNO_AUTH: RedemptionDeadline passed (fees forfeited)
5. tecUNFUNDED: Vault has insufficient assets

3.2.4.3. State Changes

1. If CurrentTime > RedemptionDeadline AND PendingRedemptions > 0:
   • Set AccruedFees = 0
   • Fail transaction
2. Else:
   • Transfer AccruedFees from vault pseudo-account to VaultBroker
   • Set AccruedFees = 0
   • Update LastFeeTime = CurrentTime

3.3. Fee Accrual

Fees accrue automatically on any vault interaction:

DaysSinceLastFee = (CurrentTime - LastFeeTime) / 86400
DailyFeeRate = ManagementFeeRate / 365 / 10000
NewFees = AssetsTotal * DailyFeeRate * DaysSinceLastFee
AccruedFees += NewFees
LastFeeTime = CurrentTime

3.4. Investment Constraints

1. Liquidity Reserve: Cannot invest if it would prevent honoring PendingRedemptions
2. Insurance Vaults: InvestedAmount <= AssetsAvailable

4. Security Considerations

4.1. Broker Restrictions

• Cannot send funds to their own account via VaultBrokerExecute
• Can only collect protocol-calculated fees
• Cannot modify vault parameters
• Cannot prevent withdrawals

4.2. Penalty Mechanism

If RedemptionDeadline passes with unfulfilled redemptions:

• All AccruedFees forfeited
• ManagementFeeRate reduced by 50% (future)?
• Vault owner can remove broker?

4.3. Attack Prevention

1. Fund Theft: Prohibited transaction types prevent direct theft
2. Fee Manipulation: Fees calculated by protocol, not broker
3. Liquidity Trap: Two-phase withdrawal ensures notice period
4. Griefing: Withdrawal cancellation prevents fake requests

5. Example Flows

5.1. Investment Flow

// Broker invests in AMM
{
  TransactionType: "VaultBrokerExecute",
  Account: "rBroker123...",
  VaultID: "VAULT456...",
  Flags: 0x00010000, // tfAllOrNothing
  RawTransactions: [
    {
      TransactionType: "AMMDeposit",
      Account: "", // Replaced with vault pseudo-account
      AMMID: "AMM789...",
      Amount: "1000000",
      Amount2: {
        currency: "USD",
        issuer: "rIssuer...",
        value: "1000"
      }
    }
  ]
}

5.2. Withdrawal Request Flow

// Day 1: User requests withdrawal
{
  TransactionType: "VaultWithdraw",
  Account: "rUser...",
  VaultID: "VAULT456...",
  Amount: "1000", // Shares
  Flags: 0x00100000 // tfWithdrawRequest
}

// Broker sees PendingRedemptions increased
// Broker divests to provide liquidity

// Day 2: User executes withdrawal
{
  TransactionType: "VaultWithdraw",
  Account: "rUser...",
  VaultID: "VAULT456...",
  Amount: "1000",
  // No flags - normal withdrawal
}

5.3. Fee Collection Flow

// Monthly fee collection
{
  TransactionType: "VaultFeeCollect",
  Account: "rBroker...",
  VaultID: "VAULT456..."
}
// Transfers AccruedFees to broker

6. Integration with Life Insurance Protocol

For insurance vaults:

• VaultBroker can invest AssetsAvailable
• Claims trigger immediate liquidity requirements
• Conservative investment strategies recommended
• PolicyClaim can force divestment if needed

7. Economics

7.1. Fee Structure

Typical management fees:

• Index funds: 10-50 basis points (0.1-0.5%)
• Active funds: 50-200 basis points (0.5-2%)
• Maximum allowed: 1000 basis points (10%)

7.2. Broker Incentives

Brokers are incentivized to:

• Provide liquidity promptly (avoid fee forfeiture)
• Generate good returns (attract deposits)
• Maintain reasonable fees (market competition)