Skip to content
Documentation/
/
/
Vault
Last updated

Vault

[Source]

A Vault object defines the state of a tokenized vault. It contains key details such as available assets, shares, total value, and other relevant information. You can create a Vault object with the VaultCreate transaction.

The Vault object is tracked in an Owner Directory owned by the Vault Owner account. Additionally, to facilitate Vault object lookup, the object is tracked in the owner directory of the vault's pseudo-account.

Requires the SingleAssetVault amendment.

Requires the LendingProtocolV1_1 amendment.

Example Vault JSON

{
  "LedgerEntryType": "Vault",
  "Account": "rwCNM7SeUHTajEBQDiNqxDG8p1Mreizw85",
  "Asset": {
      "currency": "USD",
      "issuer": "rXJSJiZMxaLuH3kQBUV5DLipnYtrE6iVb"
  },
  "AssetsAvailable": "0",
  "AssetsMaximum": "1000000",
  "AssetsTotal": "0",
  "Data": "5661756C74206D65746164617461",
  "Flags": 0,
  "LEVersion": 1,
  "LossUnrealized": "0",
  "Owner": "rNGHoQwNG753zyfDrib4qDvvswbrtmV8Es",
  "OwnerNode": "0",
  "RedemptionDate": 883008000,
  "Scale": 6,
  "Sequence": 200370,
  "ShareMPTID": "0000000169F415C9F1AB6796AB9224CE635818AFD74F8175",
  "SubscriptionDate": 851472000,
  "VaultKind": 1,
  "WithdrawalPolicy": 1
}

Vault Fields

In addition to the common ledger entry fields, Vault entries have the following fields:

NameJSON TypeInternal TypeRequired?Description
AccountStringAccountIDYesThe address of the vault's pseudo-account.
AssetObjectIssueYesThe asset of the vault. The vault supports XRP, trust line tokens, and MPTs.
AssetsTotalStringNumberYesThe total value of the vault. Calculated as: assets available + assets on loan.
  • Cash-basis vaults: Potential interest from scheduled, unpaid loans doesn't count toward the total.

    Requires the LendingProtocolV1_1 amendment.

  • Instant interest recognition vaults: Potential interest from scheduled, unpaid loans does count toward the total.
AssetsAvailableStringNumberYesThe amount of assets available for loans and withdrawals.
AssetsMaximumStringNumberNoThe maximum amount of assets that can be deposited into the vault. Set to 0 for no cap.
DataStringBlobNoArbitrary metadata, in hex format, about the vault. Limited to 256 bytes. See Data Field Format for more information.
LEVersionNumberUInt8NoIndicates what type of accounting the vault uses. 1 indicates the vault uses cash-basis accounting. If this field is omitted, the vault uses instant interest recognition accounting.

Requires the LendingProtocolV1_1 amendment.

LossUnrealizedStringNumberYesThe potential loss amount that is not yet realized, expressed as the vault's asset. Only a protocol connected to the vault can modify this attribute.
  • Cash-basis vaults: Unrealized losses from interest aren't included in this value.

    Requires the LendingProtocolV1_1 amendment.

  • Instant interest recognition vaults: Unrealized losses from interest are included in this value.
OwnerNodeStringUInt64YesIdentifies the page where this item is referenced in the owner's directory.
OwnerStringAccountIDYesThe account address of the Vault Owner.
PreviousTxnIDStringHash256YesIdentifies the transaction ID that most recently modified this object.
RedemptionDateNumberUInt32No(Closed-ended vaults only) The time, in seconds since the Ripple Epoch, when the vault's investment period ends and depositors can redeem their shares.

Requires the LendingProtocolV1_1 amendment.

PreviousTxnLgrSeqNumberUInt32YesThe sequence of the ledger that contains the transaction that most recently modified this object.
ScaleNumberUInt8NoSpecifies decimal precision for share calculations. Assets are multiplied by 10Scale to convert fractional amounts into whole number shares. For example, with a Scale of 6, depositing 20.3 units creates 20,300,000 shares (20.3 × 10Scale). For trust line tokens this can be configured at vault creation, and valid values are between 0-18, with the default being 6. For XRP and MPTs, this is fixed at 0. See Scaling Factor for more information.
SequenceNumberUInt32YesThe transaction sequence number that created the vault.
ShareMPTIDStringUInt192YesThe identifier of the share MPTokenIssuance object.
SubscriptionDateNumberUInt32No(Closed-ended vaults only) The time, in seconds since the Ripple Epoch, when the vault's subscription window closes and its investment period begins.

Requires the LendingProtocolV1_1 amendment.

VaultKindNumberUInt8NoIndicates the kind of vault. 1 is a closed-ended vault. If this field is omitted, it's an open-ended vault.

Requires the LendingProtocolV1_1 amendment.

WithdrawalPolicyNumberUInt8YesIndicates the withdrawal strategy used by the vault.
Note

LEVersion is set by the VaultCreate transaction, but the value is determined by if the LendingProtocolV1_1 amendment is enabled.

Data Field Format

While any data structure is allowed in the Data field, the following format is recommended:

Field NameKeyTypeDescription
NamenStringHuman-readable name of the vault. Should clearly reflect the vault's strategy or mandate.
WebsitewStringWebsite associated with the vault. Omit protocol (https://) and www to conserve space.

To fit within the 256-byte limit, vault metadata should use the compressed JSON keys.

Following this format helps XRPL explorers and other tools parse and display vault information in a standardized way, improving discoverability and user experience.

Example JSON

For a vault named "LATAM Fund II" with website "examplefund.com":

{
  "n": "LATAM Fund II",
  "w": "examplefund.com"
}

  1. Remove any whitespace from the JSON:

    {"n":"LATAM Fund II","w":"examplefund.com"}

  2. Hex-encode the JSON. For example:

    # Using xxd (macOS/Linux)
echo -n '{"n":"LATAM Fund II","w":"examplefund.com"}' | xxd -p | tr -d '\n'

    You should see this result: 7b226e223a224c4154414d2046756e64204949222c2277223a226578616d706c6566756e642e636f6d227d

Scaling Factor

The Scale field enables the vault to accurately represent fractional asset values using integer-only MPT shares, which prevents the loss of value from decimal truncation. It defines a scaling factor, calculated as 10Scale, that converts a decimal asset amount into a corresponding whole number of shares.

The scaling factor behavior varies by asset type:

  • Trust line token: When a vault holds a trust line token, the Scale is configurable by the Vault Owner when creating the vault. The value can range from 0 to a maximum of 18, with a default of 6. This flexibility allows issuers to set a level of precision appropriate for their specific token.

  • XRP: When a vault holds XRP, the Scale is fixed at 0. This aligns with XRP's native structure, where one share represents one drop, and one XRP equals 1,000,000 drops. Therefore, a deposit of 10 XRP to an empty vault will result in the issuance of 10,000,000 shares.

  • MPT: When a vault holds an MPT, its Scale is fixed at 0. This creates a 1-to-1 relationship between deposited MPT units and the shares issued. For example, depositing 10 MPTs to an empty vault issues 10 shares. The value of a single MPT is determined at the issuer's discretion.

    Warning

    If an MPT is set to represent a large value, the vault owner and the depositor must be cautious. Since only whole MPT units are used in calculations, any value that is not a multiple of a single MPT's value may be lost due to rounding during a transaction.

Vault Flags

Vault entries can have the following flags:

Flag NameFlag ValueDescription
lsfVaultPrivate0x00010000If set, indicates that the vault is private. This flag can only be set when creating the vault.

Vault ID Format

The ID of a Vault entry is the SHA-512Half of the following values, concatenated in order:

  • The Vault space key 0x0056 (capital V).
  • The AccountID of the account submitting the transaction (for example, the vault owner).
  • The transaction Sequence number. If the transaction used a Ticket, use the TicketSequence value.

See Also

API Methods:

Transactions:

Ticket

XChainOwnedClaimID