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. Loading...
{
"LedgerEntryType": "Vault",
"Account": "rwCNM7SeUHTajEBQDiNqxDG8p1Mreizw85",
"Asset": {
"currency": "USD",
"issuer": "rXJSJiZMxaLuH3kQBUV5DLipnYtrE6iVb"
},
"AssetsAvailable": "0",
"AssetsMaximum": "1000000",
"AssetsTotal": "0",
"Data": "5661756C74206D65746164617461",
"Flags": 0,
"LossUnrealized": "0",
"Owner": "rNGHoQwNG753zyfDrib4qDvvswbrtmV8Es",
"OwnerNode": "0",
"Scale": 6,
"Sequence": 200370,
"ShareMPTID": "0000000169F415C9F1AB6796AB9224CE635818AFD74F8175",
"WithdrawalPolicy": 1,
}In addition to the common ledger entry fields, Vault entries have the following fields:
| Name | JSON Type | Internal Type | Required? | Description |
|---|---|---|---|---|
PreviousTxnID | String | Hash256 | Yes | Identifies the transaction ID that most recently modified this object. |
PreviousTxnLgrSeq | Number | UInt32 | Yes | The sequence of the ledger that contains the transaction that most recently modified this object. |
Sequence | Number | UInt32 | Yes | The transaction sequence number that created the vault. |
OwnerNode | Number | UInt64 | Yes | Identifies the page where this item is referenced in the owner's directory. |
Owner | String | AccountID | Yes | The account address of the Vault Owner. |
Account | String | AccountID | Yes | The address of the vault's pseudo-account. |
Data | String | Blob | No | Arbitrary metadata, in hex format, about the vault. Limited to 256 bytes. See Data Field Format for more information. |
Asset | Object | Issue | Yes | The asset of the vault. The vault supports XRP, trust line tokens, and MPTs. |
AssetsTotal | Number | Number | Yes | The total value of the vault. |
AssetsAvailable | Number | Number | Yes | The asset amount that is available in the vault. |
AssetsMaximum | Number | Number | No | The maximum asset amount that can be held in the vault. If set to 0, this indicates there is no cap. |
LossUnrealized | Number | Number | Yes | The 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. |
ShareMPTID | String | UInt192 | Yes | The identifier of the share MPTokenIssuance object. |
WithdrawalPolicy | String | UInt8 | Yes | Indicates the withdrawal strategy used by the vault. |
Scale | Number | UInt8 | No | Specifies 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. |
While any data structure is allowed in the Data field, the following format is recommended:
| Field Name | Key | Type | Description |
|---|---|---|---|
| Name | n | String | Human-readable name of the vault. Should clearly reflect the vault's strategy or mandate. |
| Website | w | String | Website 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.
For a vault named "LATAM Fund II" with website "examplefund.com":
{
"n": "LATAM Fund II",
"w": "examplefund.com"
}Remove any whitespace from the JSON:
{"n":"LATAM Fund II","w":"examplefund.com"}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
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
Scaleis 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
Scaleis 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
Scaleis 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.WarningIf 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 entries can have the following flags:
| Flag Name | Flag Value | Description |
|---|---|---|
lsfVaultPrivate | 0x00010000 | If set, indicates that the vault is private. This flag can only be set when creating the vault. |
The ID of a Vault entry is the SHA-512Half of the following values, concatenated in order:
- The
Vaultspace key0x0056(capital V). - The AccountID of the account submitting the transaction (for example, the vault owner).
- The transaction
Sequencenumber. If the transaction used a Ticket, use theTicketSequencevalue.
API Methods:
Transactions: