Skip to content
Documentation/
/
/
VaultClawback
Last updated

VaultClawback

[Source]

Performs a Clawback from the vault, exchanging the shares of an account for assets.

Under the hood, the transaction performs a VaultWithdraw on behalf of the account from which assets are clawed back, converting its shares into assets and transferring the funds to the asset’s issuing account. Because of this, VaultClawback must respect any applicable fees or penalties (e.g., unrealized loss).

Warning

Clawbacks cannot be performed on native XRP.

Requires the SingleAssetVault amendment.

Example VaultClawback JSON

{
  "TransactionType": "VaultClawback",
  "Account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
  "Fee": "12",
  "Flags": 0,
  "LastLedgerSequence": 7108682,
  "Sequence": 8,
  "VaultID": "77D6234D074E505024D39C04C3F262997B773719AB29ACFA83119E4210328776",
  "Holder": "ruazs5h1qEsqpke88pcqnaseXdm6od2xc",
  "Amount" : "10000"
}

VaultClawback Fields

Field NameJSON TypeInternal TypeRequired?Description
VaultIDStringHash256YesThe unique identifier of the vault from which assets are withdrawn.
HolderStringAccountIDYesThe unique identifier of the account from which to claw back the assets.
AmountCurrency AmountAmountNoThe asset amount to claw back. When this field is set to 0, the transaction claws back all funds, up to the total shares the Holder owns. If omitted, the asset is chosen based on the account submitting the transaction; vault owners target vault shares while other accounts target vault assets.

If the requested amount exceeds the vault’s available assets, the transaction claws back only up to the vault's AssetsAvailable balance. Otherwise, it retrieves the exact asset amount specified in the transaction.

When converting between shares and assets, the clawback ignores unrealized losses if the Holder is the vault's only shareholder. If there are other shareholders, a discounted rate is used, which could leave some shares unburned even when clawing back all available assets.

Requires the fixCleanup3_4_0 amendment.

For a fixed-asset clawback, the recovered amount never exceeds the requested amount because the converted share count is rounded down, not to the nearest share. The recovered amount is also rounded down to match the vault's AssetsTotal precision, leaving any leftover dust for remaining shareholders.

Requires the fixCleanup3_4_0 amendment.

Stranded-Share Burn

You can specify Amount as either the vault's asset or its shares. Only the asset issuer can claw back the vault asset; the vault owner, however, can specify shares to burn instead. This is intended for winding down a vault when assets are gone, but shares remain outstanding and block VaultDelete.

  • Only the vault owner can submit a clawback transaction on vault shares, whether or not they're also the asset issuer.
  • The vault's AssetsTotal and AssetsAvailable must both be 0, and shares must still be outstanding.
  • A non-zero Amount must equal the holder's entire share balance, or you can specify 0 to claw back everything.

VaultClawback Flags

There are no flags defined for VaultClawback transactions.

Error Cases

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

Error CodeDescription
tecNO_ENTRYThe Vault object with the specified VaultID does not exist on the ledger.
tecNO_PERMISSIONWhen clawing back the vault's asset:
  • The vault's asset is XRP.
  • The Account isn't the issuer of the vault's asset.
  • The Account is also the Holder. An issuer can't claw back from itself.
  • The asset is an MPT whose issuance doesn't have the Can Clawback flag enabled.
  • The asset is a trust line token whose issuer doesn't have Allow Trust Line Clawback enabled, or has No Freeze enabled.
When clawing back the vault's shares:
  • The Account isn't the vault owner.
  • The vault still holds assets, or has no shares outstanding.
tecWRONG_ASSET
  • The asset in the transaction is neither the vault's asset nor its shares.
  • Amount was omitted and the vault owner is also the issuer of the vault's asset, so the intended asset (vault asset or share) is ambiguous. In this case, explicitly specify the Amount field.
    • tecINSUFFICIENT_FUNDSThe MPToken object for the vault share of the Holder account does not exist, or the MPToken.MPTAmount is 0.
    tecLIMIT_EXCEEDEDThe vault owner is clawing back shares, but the Amount isn't the Holder's entire share balance. Share clawback must burn all of the holder's shares.
    tecOBJECT_NOT_FOUNDThe mpt_issuance_id doesn't match the MPT in the vault.
    tecPRECISION_LOSSThe Holder has no shares, the requested amount is too small to convert into a whole share at the vault's Scale, or the recovered amount is too small to change the vault's stored balance.

    Requires the fixCleanup3_4_0 amendment.

    tecPSEUDO_ACCOUNTThe holder is a pseudo-account.

    Requires the fixCleanup3_4_0 amendment.

    temDISABLEDThe Single Asset Vault amendment is not enabled.
    temBAD_AMOUNTThe Amount is negative.
    temMALFORMEDThe transaction was not validly formatted. For example, if the VaultID is not provided.

    See Also

    TrustSet

    VaultCreate