Skip to content
Documentation/
/
/
VaultCreate
Last updated

VaultCreate

[Source]

Creates a new Vault ledger entry, an MPTokenIssuance ledger entry for the vault’s shares, and an AccountRoot for the vault’s pseudo-account.

Note

Currently, the account that creates the vault must also create other protocols that utilize the vault, though this may change in the future.

Requires the SingleAssetVault amendment.

Requires the LendingProtocolV1_1 amendment.

Example VaultCreate JSON

{
  "TransactionType": "VaultCreate",
  "Account": "rNGHoQwNG753zyfDrib4qDvvswbrtmV8Es",
  "Asset": {
    "currency": "USD",
    "issuer": "rXJSJiZMxaLuH3kQBUV5DLipnYtrE6iVb"
  },
  "AssetsMaximum": "1000000",
  "Data": "5661756C74206D65746164617461",
  "Fee": "5000000",
  "Flags": 0,
  "MPTokenMetadata": "7B2274223A225473745368617265222C226E223A2254657374205661756C74205368617265222C2264223A22412074657374207661756C742073686172652E222C2269223A226578616D706C652E6F72672F73686172652D69636F6E2E706E67222C226163223A22727761222C226173223A22657175697479222C22696E223A224D53205465737420497373756572222C227573223A5B7B2275223A226578616D706C657969656C642E636F2F7473747368617265222C2263223A2277656273697465222C2274223A2250726F647563742050616765227D2C7B2275223A226578616D706C657969656C642E636F2F646F6373222C2263223A22646F6373222C2274223A225969656C6420546F6B656E20446F6373227D5D2C226169223A7B22766F6C6174696C697479223A226C6F77227D7D",
  "Scale": 6,
  "Sequence": 200370,
  "WithdrawalPolicy": 1
}

VaultCreate Fields

In addition to the common fields, VaultCreate transactions use the following fields:

Field NameJSON TypeInternal TypeRequired?Description
AssetObjectIssueYesThe asset to be held in the vault. This can be XRP, a trust line token, or an MPT. If the asset is a trust line token, the transaction creates a trust line between the vault's pseudo-account and the issuer of the asset. If the asset is an MPT, the transaction creates an MPToken object for the vault's pseudo-account.
AssetsMaximumStringNumberNoThe maximum asset amount that can be held in a vault.
DataStringBlobNoArbitrary vault metadata, in hex format, limited to 256 bytes. See Data Field Format for the recommended format.
DomainIDStringHash256NoThe PermissionedDomain object ID associated with the shares of this vault. If provided, the transaction creates a private vault, which restricts access to accounts with credentials in the specified Permissioned Domain.
MPTokenMetadataStringBlobNoArbitrary metadata about the shares issued by the vault, in hex format, limited to 1024 bytes.
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. Required when VaultKind is 1 and immutable after the vault is created.

Requires the LendingProtocolV1_1 amendment.

ScaleNumberUInt8No(Trust line tokens only) 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.
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. Required when VaultKind is 1 and immutable after the vault is created.

Requires the LendingProtocolV1_1 amendment.

VaultKindNumberUInt8NoThe kind of vault to create. If omitted, defaults to 0 and creates an open-ended vault; 1 creates a closed-ended vault. Immutable after the vault is created.

Requires the LendingProtocolV1_1 amendment.

WithdrawalPolicyNumberUInt8NoIndicates the withdrawal strategy used by the vault. The default value is 0x0001, mapped to the string vaultStrategyFirstComeFirstServe. See WithdrawalPolicy.
Note
  • The difference between RedemptionDate and SubscriptionDate must be at least 180 seconds and less than 946708560 seconds (30 years).
  • Both dates must be in the future relative to the parent ledger's close time.

VaultCreate Flags

VaultCreate transactions support additional values in the Flags field, as follows:

Flag NameValueDescription
tfVaultPrivate0x00010000Indicates that the vault is private. This flag can only be set when creating the vault.
tfVaultShareNonTransferable0x00020000Indicates the vault share is non-transferable. This flag can only be set when creating the vault.

WithdrawalPolicy

A WithdrawalPolicy defines the strategy for processing withdrawal requests from a vault. This policy governs how liquidity is removed. Currently, only one strategy is supported:

Policy NameValueDescription
vaultStrategyFirstComeFirstServe0x0001Requests are processed on a first-come, first-served basis. With this strategy, a depositor can redeem any amount of assets, provided they hold a sufficient number of shares.

Transaction Cost

Since the VaultCreate transaction creates a new AccountRoot object for a vault’s pseudo-account, it incurs a higher than usual transaction cost to deter ledger spam. Instead of the standard minimum of 0.00001 XRP, VaultCreate must destroy an incremental owner reserve, currently 0.2 XRP.

Error Cases

Besides errors that can occur for all transactions, VaultCreate transactions can result in the following transaction result codes:

Error CodeDescription
tecEXPIREDSubscriptionDate or RedemptionDate isn't ahead of the parent ledger's close time.

Requires the LendingProtocolV1_1 amendment.

tecNO_AUTHThe asset is an MPT and the lsfMPTCanTransfer flag is not set in the MPTokenIssuance object, meaning the vault cannot be created with a non-transferable MPT.
tecLOCKEDThe asset is an MPT and the lsfMPTLocked flag is set in the MPTokenIssuance object, meaning the asset is locked.
tecFROZENThe issuer has frozen the asset to be held in the vault.
tecOBJECT_NOT_FOUNDA ledger entry specified in the transaction does not exist. For example, the provided DomainID does not exist.
tecINSUFFICIENT_RESERVEThere is insufficient AccountRoot.Balance for the Owner Reserve.
tecWRONG_ASSETThe asset's issuer is a pseudo-account (vault shares or AMM LP tokens), which aren't allowed.
temDISABLED
  • The SingleAssetVault amendment isn't enabled.
  • A DomainID is provided and the PermissionedDomains amendment isn't enabled.
  • The MPTokensV1 amendment isn't enabled.
  • VaultKind, SubscriptionDate, or RedemptionDate is present and the LendingProtocolV1_1 amendment isn't enabled.
    • temMALFORMED
  • Data is present but empty, or longer than 256 bytes.
  • MPTokenMetadata is present but empty, or longer than 1024 bytes.
  • WithdrawalPolicy isn't a supported strategy.
  • DomainID is zero, or is set on a vault that isn't private.
  • AssetsMaximum is negative.
  • Scale is set on an XRP or MPT vault, or exceeds the maximum for a trust line token.
  • VaultKind is present with a value other than 0 or 1.

    Requires the LendingProtocolV1_1 amendment.

  • VaultKind is 0, but SubscriptionDate or RedemptionDate is present.

    Requires the LendingProtocolV1_1 amendment.

  • VaultKind is 1, but is missing SubscriptionDate or RedemptionDate, or the gap between them is out of range.

    Requires the LendingProtocolV1_1 amendment.

    • terNO_RIPPLEThe issuer of the asset has not enabled the Default Ripple flag.
    terNO_ACCOUNTThe issuer account of the vault's asset does not exist.

    See Also

    VaultClawback

    VaultDelete