Skip to content
Documentation/
/
/
VaultWithdraw
Last updated

VaultWithdraw

[Source]

Redeem vault shares for assets. The amount of assets received depends on the exchange rate, which adjusts based on the vault’s total assets and any unrealized losses.

Note

Withdrawing to yourself does not respect the Permissioned Domain rules: any account that holds the shares of a private vault can redeem them to itself, even without valid credentials. This is to avoid a situation where a depositor deposits assets to a private vault to then have their access revoked by invalidating their credentials, and thus losing access to their funds. Withdrawing to a different account requires both the sender and the destination to hold valid credentials in the vault's domain, unless the destination is the vault asset's issuer.

Requires the fixCleanup3_4_0 amendment.

A depositor cannot redeem liquidity if the trust line between the pseudo-account and the issuer of the vault asset is frozen, or the MPToken is locked.

Additionally, if you already hold the asset, a self-destination withdrawal will succeed regardless of the issuer's DefaultRipple setting, which is only checked when creating a new trust line.

Requires the fixCleanup3_4_0 amendment.

A withdrawal whose destination is the issuer of the vault asset is never blocked by a freeze, not even a global freeze. When you withdraw to your own account, you are both the sender and the destination: for a trust line asset, a regular freeze does not block the withdrawal but a deep freeze does, and for an MPT any lock blocks it.

Requires the fixCleanup3_3_0 amendment.

Requires the SingleAssetVault amendment.

Requires the LendingProtocolV1_1 amendment.

Example VaultWithdraw JSON

{
  "TransactionType": "VaultWithdraw",
  "Account": "rGFBE8WA2ZKfqGGB7CFkLusVt7hsVT4r8H",
  "Amount": {
    "mpt_issuance_id": "000000016E1417CA9DFD23400B05E43FDE5BB8D8FFA817CA",
    "value": "5"
  },
  "Destination": "rGFBE8WA2ZKfqGGB7CFkLusVt7hsVT4r8H",
  "Fee": "12",
  "Flags": 0,
  "Sequence": 200380,
  "VaultID": "A7B7B3ED3F5BD8E58C9064278EB29519CD6475D87A4517707DE108E65AE9C08C",
}

VaultWithdraw Fields

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

Field NameJSON TypeInternal TypeRequired?Description
VaultIDStringHash256YesThe unique identifier of the vault to which the assets are deposited.
AmountCurrency AmountAmountYesThe exact amount of vault asset to withdraw or vault share to redeem.
DestinationStringAccountIDNoAn account to receive the assets. This account must be able to receive the vault asset or the transaction fails.
DestinationTagNumberUInt32NoArbitrary tag identifying the reason for the withdrawal to the destination.
CredentialIDsArrayVector256NoAn array of credential identifiers used to authorize the transaction, if credential-based deposit authorization is required.

Requires the Credentials amendment.

Requires the fixCleanup3_4_0 amendment.

There are two ways to specify the transaction Amount field:

Specify AssetsSpecify Shares
  • If the Amount field specifies an asset amount (e.g., 100 XRP), the transaction burns the necessary number of shares to provide the requested amount.
  • If the vault has an unrealized loss, withdrawing the same amount of assets requires burning more shares.
  • If the Amount field specifies a share amount (e.g., 500 vault shares), the transaction converts those shares into the corresponding amount of assets.
  • If the vault has an unrealized loss, each share is worth less, meaning fewer assets are received.

For fixed-asset withdrawals, the payout never exceeds the requested amount. Both the converted share count and the final payout are rounded down to match the vault's AssetsTotal precision, leaving any leftover dust for remaining shareholders. However, if a withdrawal redeems all outstanding shares, it is exempt from these rounding checks and succeeds, even if it moves 0 assets (for example, if the vault has lost all its value to unrealized loss).

Requires the fixCleanup3_4_0 amendment.

VaultWithdraw Flags

There are no flags defined for VaultWithdraw transactions.

Transfer Fees

A single asset vault does not apply the transfer fee to VaultWithdraw transactions. Additionally, whenever a protocol moves assets from or to a vault, the Transfer Fee must not be charged.

Error Cases

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

Error CodeDescription
tecEXPIREDFor private vaults, the sender's or destination's credentials have expired.

Requires the fixCleanup3_4_0 amendment.

tecFROZENThe vault asset is frozen globally for the vault's pseudo-account, or deep frozen for the destination. A freeze on the sender also causes this error when Destination is another account. A regular freeze on the destination alone does not cause this error.

Requires the fixCleanup3_3_0 amendment.

tecINSUFFICIENT_FUNDSEither the account doesn't hold enough shares, or the vault doesn't hold enough available assets to fill the request.

Requires the fixCleanup3_4_0 amendment.

tecLOCKEDThe MPT vault asset is locked globally for the vault's pseudo-account, for the sender, or for the destination account. Unlike a trust line freeze, an MPT lock also blocks a withdrawal to the sender's own account.

Requires the fixCleanup3_3_0 amendment.

tecNO_AUTH
  • The asset is a non-transferable MPT.
  • For private vaults, this can also occur if the sender or destination lacks valid credentials in the vault's domain.

    Requires the fixCleanup3_4_0 amendment.

    • tecNO_ENTRYThe Vault object with the provided VaultID does not exist on the ledger.
    tecNO_LINEThe Destination doesn't have a trust line for the vault asset with a high enough limit to receive the withdrawal. It doesn't apply to MPT assets, or when the Destination is the sender or the asset's issuer.

    Requires the fixCleanup3_1_3 amendment.

    tecNO_PERMISSIONThe destination account specified does not have permission to receive the asset.
    tecOBJECT_NOT_FOUNDA ledger entry specified in the transaction does not exist.
    tecPATH_DRYConverting between assets and shares overflowed the largest number the protocol can represent. This usually means the vault's Scale is high and the Amount is large.
    tecPRECISION_LOSSThe withdrawal rounds to nothing, either producing no shares to redeem or being too small to change the vault's stored balance.

    Requires the fixCleanup3_4_0 amendment.

    tecPSEUDO_ACCOUNTThe Destination is a pseudo-account, which belongs to a ledger entry rather than a person and can't receive a withdrawal.

    Requires the fixCleanup3_4_0 amendment.

    tecTOO_SOONThe vault is closed-ended and in its Investment phase.

    Requires the LendingProtocolV1_1 amendment.

    tecWRONG_ASSETThe unit of Amount is neither a share or asset of the vault.
    temBAD_AMOUNTThe Amount field of the transaction is invalid. For example, the provided amount is set to 0.
    temDISABLEDThe SingleAssetVault amendment is not enabled.
    temMALFORMED
  • VaultID is zero.
  • Destination is zero.

    • See Also

    VaultSet

    XChainAccountCreateCommit