VaultClawback.cpp

#include <xrpl/tx/transactors/vault/VaultClawback.h>
 
#include <xrpl/basics/Log.h>
#include <xrpl/basics/Number.h>
#include <xrpl/basics/base_uint.h>
#include <xrpl/beast/utility/Zero.h>
#include <xrpl/beast/utility/instrumentation.h>
#include <xrpl/core/ServiceRegistry.h>
#include <xrpl/ledger/helpers/AccountRootHelpers.h>
#include <xrpl/ledger/helpers/TokenHelpers.h>
#include <xrpl/ledger/helpers/VaultHelpers.h>
#include <xrpl/protocol/AccountID.h>
#include <xrpl/protocol/Asset.h>
#include <xrpl/protocol/Feature.h>
#include <xrpl/protocol/Indexes.h>
#include <xrpl/protocol/Issue.h>
#include <xrpl/protocol/LedgerFormats.h>
#include <xrpl/protocol/MPTIssue.h>
#include <xrpl/protocol/SField.h>
#include <xrpl/protocol/STAmount.h>
#include <xrpl/protocol/STLedgerEntry.h>
#include <xrpl/protocol/STNumber.h>  // IWYU pragma: keep
#include <xrpl/protocol/STTakesAsset.h>
#include <xrpl/protocol/STTx.h>
#include <xrpl/protocol/TER.h>
#include <xrpl/protocol/XRPAmount.h>
#include <xrpl/tx/Transactor.h>
 
#include <expected>
#include <optional>
#include <stdexcept>
#include <utility>
 
namespace xrpl {
NotTEC
VaultClawback::preflight(PreflightContext const& ctx)
{
    if (ctx.tx[sfVaultID] == beast::kZero)
    {
        JLOG(ctx.j.debug()) << "VaultClawback: zero/empty vault ID.";
        return temMALFORMED;
    }
 
    auto const amount = ctx.tx[~sfAmount];
    if (amount)
    {
        // Note, zero amount is valid, it means "all". It is also the default.
        if (*amount < beast::kZero)
        {
            return temBAD_AMOUNT;
        }
        if (isXRP(amount->asset()))
        {
            JLOG(ctx.j.debug()) << "VaultClawback: cannot clawback XRP.";
            return temMALFORMED;
        }
    }
 
    return tesSUCCESS;
}
 
[[nodiscard]] STAmount
clawbackAmount(
    SLE::ConstRef vault,
    std::optional<STAmount> const& maybeAmount,
    AccountID const& account)
{
    if (maybeAmount)
        return *maybeAmount;
 
    Asset const share = MPTIssue{vault->at(sfShareMPTID)};
    if (account == vault->at(sfOwner))
        return STAmount{share};
 
    return STAmount{vault->at(sfAsset)};
}
 
TER
VaultClawback::preclaim(PreclaimContext const& ctx)
{
    auto const vault = ctx.view.read(keylet::vault(ctx.tx[sfVaultID]));
    if (!vault)
        return tecNO_ENTRY;
 
    Asset const vaultAsset = vault->at(sfAsset);
    auto const account = ctx.tx[sfAccount];
    auto const holder = ctx.tx[sfHolder];
    auto const maybeAmount = ctx.tx[~sfAmount];
    auto const mptIssuanceID = vault->at(sfShareMPTID);
    auto const sleShareIssuance = ctx.view.read(keylet::mptokenIssuance(mptIssuanceID));
    if (!sleShareIssuance)
    {
        // LCOV_EXCL_START
        JLOG(ctx.j.error()) << "VaultClawback: missing issuance of vault shares.";
        return tefINTERNAL;
        // LCOV_EXCL_STOP
    }
 
    // A pseudo-account holds no vault shares, so a clawback naming one is a no-op: the vault's own
    // pseudo-account issues the shares, and no flow hands them to another one.
    // Pre-fixCleanup3_4_0: an implicit amount ends in tecPRECISION_LOSS, an explicit one debits the
    // vault and trips the "shares must move" invariant.
    // Post-fixCleanup3_4_0: refused here.
    if (ctx.view.rules().enabled(fixCleanup3_4_0) && isPseudoAccount(ctx.view, holder))
    {
        JLOG(ctx.j.debug()) << "VaultClawback: holder is a pseudo-account.";
        return tecPSEUDO_ACCOUNT;
    }
 
    Asset const share = MPTIssue{mptIssuanceID};
 
    // Ambiguous case: If Issuer is Owner they must specify the asset
    if (!maybeAmount && !vaultAsset.native() && vaultAsset.getIssuer() == vault->at(sfOwner))
    {
        JLOG(ctx.j.debug()) << "VaultClawback: must specify amount when issuer is owner.";
        return tecWRONG_ASSET;
    }
 
    auto const amount = clawbackAmount(vault, maybeAmount, account);
 
    // There is a special case that allows the VaultOwner to use clawback to
    // burn shares when Vault assets total and available are zero, but
    // shares remain. However, that case is handled in doApply() directly,
    // so here we just enforce checks.
    if (amount.asset() == share)
    {
        // Only the Vault Owner may clawback shares
        if (account != vault->at(sfOwner))
        {
            JLOG(ctx.j.debug()) << "VaultClawback: only vault owner can clawback shares.";
            return tecNO_PERMISSION;
        }
 
        auto const assetsTotal = vault->at(sfAssetsTotal);
        auto const assetsAvailable = vault->at(sfAssetsAvailable);
        auto const sharesTotal = sleShareIssuance->at(sfOutstandingAmount);
 
        // Owner can clawback funds when the vault has shares but no assets
        if (sharesTotal == 0 || (assetsTotal != 0 || assetsAvailable != 0))
        {
            JLOG(ctx.j.debug()) << "VaultClawback: vault owner can clawback shares only"
                                   " when vault has no assets.";
            return tecNO_PERMISSION;
        }
 
        // If amount is non-zero, the VaultOwner must burn all shares
        if (amount != beast::kZero)
        {
            Number const& sharesHeld = accountHolds(
                ctx.view,
                holder,
                share,
                FreezeHandling::IgnoreFreeze,
                AuthHandling::IgnoreAuth,
                ctx.j);
 
            // The VaultOwner must burn all shares
            if (amount != sharesHeld)
            {
                JLOG(ctx.j.debug()) << "VaultClawback: vault owner must clawback all "
                                       "shares.";
                return tecLIMIT_EXCEEDED;
            }
        }
 
        return tesSUCCESS;
    }
 
    // The asset that is being clawed back is the vault asset
    if (amount.asset() == vaultAsset)
    {
        // XRP cannot be clawed back
        if (vaultAsset.native())
        {
            JLOG(ctx.j.debug()) << "VaultClawback: cannot clawback XRP.";
            return tecNO_PERMISSION;
        }
 
        // Only the Asset Issuer may clawback the asset
        if (account != vaultAsset.getIssuer())
        {
            JLOG(ctx.j.debug()) << "VaultClawback: only asset issuer can clawback asset.";
            return tecNO_PERMISSION;
        }
 
        // The issuer cannot clawback from itself
        if (account == holder)
        {
            JLOG(ctx.j.debug()) << "VaultClawback: issuer cannot be the holder.";
            return tecNO_PERMISSION;
        }
 
        return vaultAsset.visit(
            [&](MPTIssue const& issue) -> TER {
                auto const mptIssue = ctx.view.read(keylet::mptokenIssuance(issue.getMptID()));
                if (mptIssue == nullptr)
                    return tecOBJECT_NOT_FOUND;
 
                if (!mptIssue->isFlag(lsfMPTCanClawback))
                {
                    JLOG(ctx.j.debug()) << "VaultClawback: cannot clawback "
                                           "MPT vault asset.";
                    return tecNO_PERMISSION;
                }
 
                return tesSUCCESS;
            },
            [&](Issue const&) -> TER {
                auto const issuerSle = ctx.view.read(keylet::account(account));
                if (!issuerSle)
                {
                    // LCOV_EXCL_START
                    JLOG(ctx.j.error()) << "VaultClawback: missing submitter account.";
                    return tefINTERNAL;
                    // LCOV_EXCL_STOP
                }
 
                if (!issuerSle->isFlag(lsfAllowTrustLineClawback) || issuerSle->isFlag(lsfNoFreeze))
                {
                    JLOG(ctx.j.debug()) << "VaultClawback: cannot clawback "
                                           "IOU vault asset.";
                    return tecNO_PERMISSION;
                }
 
                return tesSUCCESS;
            });
    }
 
    // Invalid asset
    return tecWRONG_ASSET;
}
 
std::expected<std::pair<STAmount, STAmount>, TER>
VaultClawback::assetsToClawback(
    SLE::Ref vault,
    SLE::ConstRef sleShareIssuance,
    AccountID const& holder,
    STAmount const& clawbackAmount)
{
    bool const fix340Enabled = ctx_.view().rules().enabled(fixCleanup3_4_0);
    if (clawbackAmount.asset() != vault->at(sfAsset))
    {
        // preclaim should have blocked this , now it's an internal error
        // LCOV_EXCL_START
        JLOG(j_.error()) << "VaultClawback: asset mismatch in clawback.";
        return std::unexpected(tecINTERNAL);
        // LCOV_EXCL_STOP
    }
 
    auto const assetsAvailable = vault->at(sfAssetsAvailable);
    auto const mptIssuanceID = *vault->at(sfShareMPTID);
    MPTIssue const share{mptIssuanceID};
 
    // Pre-fixCleanup3_1_3: zero-amount clawback returned early without
    // clamping to assetsAvailable, allowing more assets to be recovered
    // than available when there was an outstanding loan. Retained for
    // ledger replay compatibility.
    if (!ctx_.view().rules().enabled(fixCleanup3_1_3) && clawbackAmount == beast::kZero)
    {
        auto const sharesDestroyed = accountHolds(
            view(), holder, share, FreezeHandling::IgnoreFreeze, AuthHandling::IgnoreAuth, j_);
        auto const maybeAssets = sharesToAssetsWithdraw(vault, sleShareIssuance, sharesDestroyed);
        if (!maybeAssets)
            return std::unexpected(tecINTERNAL);  // LCOV_EXCL_LINE
 
        return std::make_pair(*maybeAssets, sharesDestroyed);
    }
 
    STAmount sharesDestroyed;
    STAmount assetsRecovered;
 
    // Number arithmetic can throw overflow_error when Scale and totals are large. Caught below.
    try
    {
        // Do not discount a sole holder's shares: clawing back AssetsAvailable
        // at the discounted rate can burn every share while loan assets remain.
        auto const waiveUnrealizedLoss =
            fix340Enabled && isSoleShareholder(view(), holder, sleShareIssuance)
            ? WaiveUnrealizedLoss::Yes
            : WaiveUnrealizedLoss::No;
 
        if (clawbackAmount == beast::kZero)
        {
            // Zero amount means clawback all shares the holder has; derive the corresponding asset
            // amount from the share balance.
            // isSoleShareholder already established that the holder owns the
            // entire outstanding share supply whenever the waiver applies, so
            // sfOutstandingAmount gives sharesDestroyed directly, avoiding a
            // redundant MPToken read via accountHolds.
            sharesDestroyed = waiveUnrealizedLoss == WaiveUnrealizedLoss::Yes
                ? STAmount{share, sleShareIssuance->at(sfOutstandingAmount)}
                : accountHolds(
                      view(),
                      holder,
                      share,
                      FreezeHandling::IgnoreFreeze,
                      AuthHandling::IgnoreAuth,
                      j_);
            auto const maybeAssets = sharesToAssetsWithdraw(
                vault, sleShareIssuance, sharesDestroyed, waiveUnrealizedLoss);
            if (!maybeAssets)
                return std::unexpected(tecINTERNAL);  // LCOV_EXCL_LINE
 
            assetsRecovered = *maybeAssets;
        }
        else
        {
            // Pre-fixCleanup3_4_0: shares were rounded to nearest, so the
            // round-trip back to assets could exceed clawbackAmount.
            // Post-amendment: truncate shares so assetsRecovered <=
            // clawbackAmount by construction (matches the clamp branch
            // below).
            auto const truncate = fix340Enabled ? TruncateShares::Yes : TruncateShares::No;
            auto const maybeShares = assetsToSharesWithdraw(
                vault, sleShareIssuance, clawbackAmount, truncate, waiveUnrealizedLoss);
            if (!maybeShares)
                return std::unexpected(tecINTERNAL);  // LCOV_EXCL_LINE
            sharesDestroyed = *maybeShares;
 
            auto const maybeAssets = sharesToAssetsWithdraw(
                vault, sleShareIssuance, sharesDestroyed, waiveUnrealizedLoss);
            if (!maybeAssets)
                return std::unexpected(tecINTERNAL);  // LCOV_EXCL_LINE
            assetsRecovered = *maybeAssets;
        }
        // Clamp assetsRecovered to sfAssetsAvailable, then re-derive shares and assets so the pair
        // stays consistent.
        if (assetsRecovered > *assetsAvailable)
        {
            assetsRecovered = *assetsAvailable;
            {
                auto const maybeShares = assetsToSharesWithdraw(
                    vault,
                    sleShareIssuance,
                    assetsRecovered,
                    TruncateShares::Yes,
                    waiveUnrealizedLoss);
                if (!maybeShares)
                    return std::unexpected(tecINTERNAL);  // LCOV_EXCL_LINE
                sharesDestroyed = *maybeShares;
            }
 
            auto const maybeAssets = sharesToAssetsWithdraw(
                vault, sleShareIssuance, sharesDestroyed, waiveUnrealizedLoss);
            if (!maybeAssets)
                return std::unexpected(tecINTERNAL);  // LCOV_EXCL_LINE
            assetsRecovered = *maybeAssets;
            // Truncation should guarantee the invariant holds. If it does not, a conversion
            // helper is broken; refuse rather than over-recover.
            if (assetsRecovered > *assetsAvailable)
            {
                // LCOV_EXCL_START
                JLOG(j_.error()) << "VaultClawback: invalid rounding of shares.";
                return std::unexpected(tecINTERNAL);
                // LCOV_EXCL_STOP
            }
        }
 
        // Post-fixCleanup3_4_0: round the recovery down at the posterior sfAssetsTotal scale so all
        // rails change by the same representable delta. sharesDestroyed is intentionally NOT
        // re-derived here: the holder's shares are burned for their pre-clamp value, so any
        // sub-ULP trimmed off stays in the vault for the remaining shareholders.
        if (ctx_.view().rules().enabled(fixCleanup3_4_0) && assetsRecovered > beast::kZero)
        {
            auto const maybeClamped = clampToAssetsTotalScale(vault, -assetsRecovered);
            if (!maybeClamped)
                return std::unexpected(maybeClamped.error());
            assetsRecovered = *maybeClamped;
        }
    }
    catch (std::overflow_error const&)
    {
        // It's easy to hit this exception from Number with large enough
        // Scale so we avoid spamming the log and only use debug here.
        JLOG(j_.debug())  //
            << "VaultClawback: overflow error with"
            << " scale=" << (int)vault->at(sfScale).value()  //
            << ", assetsTotal=" << vault->at(sfAssetsTotal).value()
            << ", sharesTotal=" << sleShareIssuance->at(sfOutstandingAmount)
            << ", amount=" << clawbackAmount.value();
        // Overflow means this transaction cannot apply, but ledger state is still consistent.
        // Return tecPATH_DRY rather than a hard internal error.
        return std::unexpected(tecPATH_DRY);
    }
 
    return std::make_pair(assetsRecovered, sharesDestroyed);
}
 
TER
VaultClawback::doApply()
{
    auto const& tx = ctx_.tx;
    auto const vault = view().peek(keylet::vault(tx[sfVaultID]));
    if (!vault)
        return tefINTERNAL;  // LCOV_EXCL_LINE
 
    auto const mptIssuanceID = *vault->at(sfShareMPTID);
    auto const sleIssuance = view().read(keylet::mptokenIssuance(mptIssuanceID));
    if (!sleIssuance)
    {
        // LCOV_EXCL_START
        JLOG(j_.error()) << "VaultClawback: missing issuance of vault shares.";
        return tefINTERNAL;
        // LCOV_EXCL_STOP
    }
    MPTIssue const share{mptIssuanceID};
 
    Asset const vaultAsset = vault->at(sfAsset);
    STAmount const amount = clawbackAmount(vault, tx[~sfAmount], accountID_);
 
    auto assetsAvailable = vault->at(sfAssetsAvailable);
    auto assetsTotal = vault->at(sfAssetsTotal);
 
    AccountID const holder = tx[sfHolder];
    STAmount sharesDestroyed = {share};
    STAmount assetsRecovered = {vault->at(sfAsset)};
 
    // The Owner is burning shares
    if (accountID_ == vault->at(sfOwner) && amount.asset() == share)
    {
        sharesDestroyed = accountHolds(
            view(), holder, share, FreezeHandling::IgnoreFreeze, AuthHandling::IgnoreAuth, j_);
    }
    else  // The Issuer is clawbacking vault assets
    {
        XRPL_ASSERT(amount.asset() == vaultAsset, "xrpl::VaultClawback::doApply : matching asset");
 
        auto const clawbackParts = assetsToClawback(vault, sleIssuance, holder, amount);
        if (!clawbackParts)
            return clawbackParts.error();
 
        assetsRecovered = clawbackParts->first;
        sharesDestroyed = clawbackParts->second;
    }
 
    // The holder has no shares (or the recovery clamped to zero). Nothing to burn; refuse rather
    // than modifying vault state.
    if (sharesDestroyed == beast::kZero)
        return tecPRECISION_LOSS;
 
    // Number arithmetic can throw overflow_error when Scale and totals are large.
    if (view().rules().enabled(fixCleanup3_4_0))
    {
        try
        {
            // A non-zero recovery can be too small to change the stored sfAssetsTotal at
            // STAmount's precision. Shares would still be burned, reject it instead.
            if (debitIsNonZeroDust(vaultAsset, assetsTotal, assetsRecovered))
            {
                // LCOV_EXCL_START
                JLOG(j_.debug())
                    << "VaultClawback: clawback amount too small to change stored vault"
                       " balance";
                return tecPRECISION_LOSS;
                // LCOV_EXCL_STOP
            }
        }
        // LCOV_EXCL_START
        catch (std::overflow_error const&)
        {
            // It's easy to hit this exception from Number with large enough Scale
            // so we avoid spamming the log and only use debug here.
            JLOG(j_.debug())  //
                << "VaultClawback: overflow error with"
                << " scale=" << (int)vault->at(sfScale).value()  //
                << ", assetsTotal=" << vault->at(sfAssetsTotal).value()
                << ", sharesTotal=" << sleIssuance->at(sfOutstandingAmount)
                << ", amount=" << amount.value();
            // Overflow means this transaction cannot apply, but ledger state is still
            // consistent. Return tecPATH_DRY rather than a hard internal error.
            return tecPATH_DRY;
        }
        // LCOV_EXCL_STOP
    }
 
    assetsTotal -= assetsRecovered;
    assetsAvailable -= assetsRecovered;
    view().update(vault);
 
    auto const& vaultAccount = vault->at(sfAccount);
    // Transfer shares from holder to vault.
    if (auto const ter = accountSend(
            view(), holder, vaultAccount, sharesDestroyed, j_, {}, WaiveTransferFee::Yes);
        !isTesSuccess(ter))
        return ter;
 
    // Try to remove MPToken for shares, if the holder balance is zero. Vault
    // pseudo-account will never set lsfMPTAuthorized, so we ignore flags.
    // Keep MPToken if holder is the vault owner.
    if (holder != vault->at(sfOwner))
    {
        if (auto const ter =
                removeEmptyHolding(ctx_.getApplyViewContext(), holder, sharesDestroyed.asset(), j_);
            isTesSuccess(ter))
        {
            JLOG(j_.debug())  //
                << "VaultClawback: removed empty MPToken for vault shares"
                << " MPTID=" << to_string(mptIssuanceID)  //
                << " account=" << toBase58(holder);
        }
        else if (ter != tecHAS_OBLIGATIONS)
        {
            // LCOV_EXCL_START
            JLOG(j_.error())  //
                << "VaultClawback: failed to remove MPToken for vault shares"
                << " MPTID=" << to_string(mptIssuanceID)  //
                << " account=" << toBase58(holder)        //
                << " with result: " << transToken(ter);
            return ter;
            // LCOV_EXCL_STOP
        }
        // else quietly ignore, holder balance is not zero
    }
 
    if (assetsRecovered > beast::kZero)
    {
        // Transfer assets from vault to issuer.
        if (auto const ter = accountSend(
                view(), vaultAccount, accountID_, assetsRecovered, j_, {}, WaiveTransferFee::Yes);
            !isTesSuccess(ter))
            return ter;
 
        // Sanity check
        if (accountHolds(
                view(),
                vaultAccount,
                assetsRecovered.asset(),
                FreezeHandling::IgnoreFreeze,
                AuthHandling::IgnoreAuth,
                j_) < beast::kZero)
        {
            // LCOV_EXCL_START
            JLOG(j_.error()) << "VaultClawback: negative balance of vault assets.";
            return tefINTERNAL;
            // LCOV_EXCL_STOP
        }
    }
 
    associateAsset(*vault, vaultAsset);
 
    return tesSUCCESS;
}
 
void
VaultClawback::visitInvariantEntry(bool, SLE::ConstRef, SLE::ConstRef)
{
    // No transaction-specific invariants yet (future work).
}
 
bool
VaultClawback::finalizeInvariants(
    STTx const&,
    TER,
    XRPAmount,
    ReadView const&,
    beast::Journal const&)
{
    // No transaction-specific invariants yet (future work).
    return true;
}
 
}  // namespace xrpl