xrpld
Loading...
Searching...
No Matches
VaultGridTests.cpp
1#include <xrpl/basics/Number.h>
2#include <xrpl/basics/base_uint.h>
3#include <xrpl/beast/hash/uhash.h>
4#include <xrpl/beast/utility/Zero.h>
5#include <xrpl/ledger/helpers/VaultHelpers.h>
6#include <xrpl/protocol/Asset.h>
7#include <xrpl/protocol/Feature.h>
8#include <xrpl/protocol/Indexes.h>
9#include <xrpl/protocol/Issue.h>
10#include <xrpl/protocol/MPTIssue.h>
11#include <xrpl/protocol/Protocol.h>
12#include <xrpl/protocol/Rules.h>
13#include <xrpl/protocol/SField.h>
14#include <xrpl/protocol/STAmount.h>
15#include <xrpl/protocol/STLedgerEntry.h>
16#include <xrpl/protocol/STNumber.h> // IWYU pragma: keep
17#include <xrpl/protocol/STTakesAsset.h>
18#include <xrpl/protocol/TER.h>
19#include <xrpl/protocol/UintTypes.h>
20
21#include <gtest/gtest.h>
22#include <helpers/Account.h>
23#include <protocol/VaultTestHelpers.h>
24
25#include <cstdint>
26#include <memory>
27#include <optional>
28#include <unordered_set>
29
30namespace xrpl {
31namespace {
32
33TEST(VaultGrid, base_and_live_scale)
34{
35 test::Account const issuer{"issuer"};
36 Issue const iou{toCurrency("USD"), issuer.id()};
37
38 auto const legacy = makeVault(iou, Number{1'000'000}, VaultVersion::Legacy, 6);
39 EXPECT_EQ(getVaultScale(legacy), -9);
40 EXPECT_EQ(getVaultBaseScale(legacy), getVaultScale(legacy));
41
42 auto const empty = makeVault(iou, Number{0}, VaultVersion::FixedPrecision, 6);
43 EXPECT_EQ(getVaultScale(empty), -6);
44 EXPECT_EQ(getVaultBaseScale(empty), -6);
45
46 auto const small = makeVault(iou, Number{1'000'000}, VaultVersion::FixedPrecision, 6);
47 EXPECT_EQ(getVaultScale(small), -6);
48 EXPECT_EQ(getVaultBaseScale(small), -6);
49
50 auto const coarsened = makeVault(iou, Number{10'000'000'000}, VaultVersion::FixedPrecision, 6);
51 EXPECT_GT(getVaultScale(coarsened), getVaultBaseScale(coarsened));
52 EXPECT_EQ(getVaultBaseScale(coarsened), -6);
53}
54
55TEST(VaultGrid, pre_v12_behavior_is_preserved)
56{
57 test::Account const issuer{"issuer"};
58 Issue const iou{toCurrency("USD"), issuer.id()};
59 Number const assetsTotal{1'000'000};
60 STAmount const onGrid{iou, Number{2, -9}};
61 STAmount const dust{iou, Number{4, -10}};
62 STAmount const overOpen{iou, Number{10, 9}};
63 auto const downward = Number::RoundingMode::Downward;
64
65 auto const legacy = makeVault(iou, assetsTotal, VaultVersion::Legacy);
66 int const expectedLive = getVaultScale(legacy);
67 int const expectedPosterior = detail::getPosteriorVaultScale(legacy, onGrid);
68 STAmount const expectedPosteriorRound = roundToPosteriorVaultScale(legacy, dust, downward);
69
70 for (auto const version : {
71 std::optional<VaultVersion>{},
72 std::optional{VaultVersion::Legacy},
73 std::optional{VaultVersion::CashBasis},
74 })
75 {
76 auto const vault = makeVault(iou, assetsTotal, version);
77 EXPECT_EQ(getVaultScale(vault), expectedLive);
78 EXPECT_EQ(getVaultBaseScale(vault), expectedLive);
79 EXPECT_EQ(detail::getPosteriorVaultScale(vault, onGrid), expectedPosterior);
80 EXPECT_EQ(roundToPosteriorVaultScale(vault, dust, downward), expectedPosteriorRound);
81 EXPECT_EQ(checkOptionalVaultInflow(vault, overOpen), tesSUCCESS);
82 }
83}
84
85TEST(VaultGrid, pre_v12_credit_clamp_floors_posterior_total)
86{
87 test::Account const issuer{"issuer"};
88 Issue const iou{toCurrency("USD"), issuer.id()};
89 Number const assetsTotal{9'999'999'999'999'999LL, -15};
90 STAmount const delta{iou, Number{5}};
91 STAmount const expected{iou, Number{4'999'999'999'999'991LL, -15}};
92
93 for (auto const version : {
94 std::optional<VaultVersion>{},
95 std::optional{VaultVersion::Legacy},
96 std::optional{VaultVersion::CashBasis},
97 })
98 {
99 auto const result = clampToAssetsTotalScale(makeVault(iou, assetsTotal, version), delta);
100 ASSERT_TRUE(result.has_value());
101 EXPECT_EQ(*result, expected);
102 }
103}
104
105TEST(VaultGrid, integral_scale_is_zero)
106{
107 auto const vault = makeVault(xrpIssue(), Number{1'000}, VaultVersion::FixedPrecision, 0);
108 STAmount const delta{xrpIssue(), 7};
109
110 EXPECT_EQ(getVaultScale(vault), 0);
111 EXPECT_EQ(getVaultBaseScale(vault), 0);
112 EXPECT_EQ(detail::getPosteriorVaultScale(vault, delta), 0);
113 EXPECT_EQ(roundToPosteriorVaultScale(vault, delta, Number::RoundingMode::TowardsZero), delta);
114}
115
116TEST(VaultGrid, posterior_scale_rounds_delta)
117{
118 test::Account const issuer{"issuer"};
119 Issue const iou{toCurrency("USD"), issuer.id()};
120 auto const vault =
121 makeVault(iou, Number{9'999'999'999'999'999, -6}, VaultVersion::FixedPrecision, 6);
122 STAmount const delta{iou, Number{21, -6}};
123
124 EXPECT_EQ(getVaultScale(vault), -6);
125 EXPECT_EQ(detail::getPosteriorVaultScale(vault, delta), -5);
126 EXPECT_EQ(
128 STAmount(iou, Number{20, -6}));
129}
130
131TEST(VaultGrid, posterior_scale_rejects_dust_at_call_site)
132{
133 test::Account const issuer{"issuer"};
134 Issue const iou{toCurrency("USD"), issuer.id()};
135 auto const vault = makeVault(iou, Number{10'000'000'000}, VaultVersion::FixedPrecision, 6);
136 STAmount const dust{iou, Number{1, -6}};
137
138 EXPECT_EQ(
140}
141
142TEST(VaultGrid, posterior_outflow_can_refine_scale)
143{
144 test::Account const issuer{"issuer"};
145 Issue const iou{toCurrency("USD"), issuer.id()};
146 auto const vault =
147 makeVault(iou, Number{1'000'000'000'000'001, -5}, VaultVersion::FixedPrecision, 6);
148 STAmount const delta{iou, -Number{11, -6}};
149
150 EXPECT_EQ(getVaultScale(vault), -5);
151 EXPECT_EQ(detail::getPosteriorVaultScale(vault, delta), -6);
152 EXPECT_EQ(roundToPosteriorVaultScale(vault, delta, Number::RoundingMode::TowardsZero), delta);
153}
154
155TEST(VaultGrid, optional_inflow_capacity_boundaries)
156{
157 test::Account const issuer{"issuer"};
158 Issue const iou{toCurrency("USD"), issuer.id()};
159
160 auto const fixedIou = makeVault(iou, Number{9, 5}, VaultVersion::FixedPrecision, 10);
161 STAmount const iouDust{iou, Number{1, -10}};
162 EXPECT_EQ(getVaultOpenLimit(fixedIou), (Number{9, 5}));
163 EXPECT_EQ(checkOptionalVaultInflow(fixedIou, STAmount{iou}), tesSUCCESS);
164 EXPECT_EQ(checkOptionalVaultInflow(fixedIou, iouDust), tecLIMIT_EXCEEDED);
165
166 auto const fixedXrp = makeVault(xrpIssue(), Number{9, 15}, VaultVersion::FixedPrecision, 0);
167 STAmount const xrpUnit{xrpIssue(), 1};
168 EXPECT_EQ(getVaultOpenLimit(fixedXrp), (Number{9, 15}));
169 EXPECT_EQ(checkOptionalVaultInflow(fixedXrp, STAmount{xrpIssue()}), tesSUCCESS);
170 EXPECT_EQ(checkOptionalVaultInflow(fixedXrp, xrpUnit), tecLIMIT_EXCEEDED);
171
172 auto const legacy = makeVault(iou, Number{10, 5}, VaultVersion::Legacy, 10);
173 EXPECT_EQ(checkOptionalVaultInflow(legacy, iouDust), tesSUCCESS);
174
175 auto const coarsening =
176 makeVault(iou, Number{9'999'999'999'999'999, -6}, VaultVersion::FixedPrecision, 6);
177 STAmount const coarseningDelta{iou, Number{21, -6}};
178 EXPECT_EQ(checkOptionalVaultInflow(coarsening, coarseningDelta), tecLIMIT_EXCEEDED);
179}
180
181TEST(VaultGrid, optional_inflow_includes_yield_unrealized)
182{
183 test::Account const issuer{"issuer"};
184 Issue const iou{toCurrency("USD"), issuer.id()};
185 auto const vault = makeVault(iou, Number{8'999'999'999}, VaultVersion::FixedPrecision, 6);
186 STAmount const amount{iou, Number{1}};
187
188 EXPECT_EQ(checkOptionalVaultInflow(vault, amount), tesSUCCESS);
189
190 vault->at(sfYieldUnrealized) = Number{1};
191 associateAsset(*vault, iou);
192 EXPECT_EQ(checkOptionalVaultInflow(vault, amount), tecLIMIT_EXCEEDED);
193}
194
195// AssetsAvailable + raw needs 20 digits. Under the ToNearest ambient mode the
196// sum would round up to the next 10^-6 before the Downward floor, crediting
197// 0.000001 for a raw 0.0000009996.
198TEST(VaultGrid, credit_floors_sum_in_requested_mode)
199{
200 test::Account const issuer{"issuer"};
201 Issue const iou{toCurrency("USD"), issuer.id()};
202 auto const vault = makeVault(
203 iou,
204 Number{0},
206 6,
207 Number{0},
208 Number{1'234'567'890'123'456LL, -6});
209 Number const raw{9'996, -10};
210
212 STAmount const credit =
214 EXPECT_EQ(credit, STAmount(iou, 0));
215 EXPECT_LE(Number(credit), raw);
216}
217
218TEST(VaultGrid, is_on_vault_base_grid)
219{
220 test::Account const issuer{"issuer"};
221 Issue const iou{toCurrency("USD"), issuer.id()};
222 int const baseScale = vaultBaseScale(iou, 6);
223
224 struct Row
225 {
226 Number value;
227 bool expected{};
228 };
229 Row const rows[] = {
230 {.value = Number{0}, .expected = true},
231 {.value = Number{1}, .expected = true},
232 {.value = Number{1, -6}, .expected = true},
233 {.value = Number{1, 20}, .expected = true},
234 {.value = Number{1'234'567'890'123'456LL, -6}, .expected = true},
235 // A digit below baseScale.
236 {.value = Number{1, -7}, .expected = false},
237 {.value = Number{15, -7}, .expected = false},
238 // A 17th significant digit, on the base grid but not an STAmount.
239 {.value = Number{12'345'678'901'234'567LL, 0}, .expected = false},
240 };
241 for (auto const& row : rows)
242 EXPECT_EQ(isOnVaultBaseGrid(iou, row.value, baseScale), row.expected) << row.value;
243
244 EXPECT_EQ(vaultBaseScale(xrpIssue(), 6), 0);
245 EXPECT_TRUE(isOnVaultBaseGrid(xrpIssue(), Number{7}, 0));
246
247 // Out of range for the asset: rejected instead of throwing.
248 EXPECT_FALSE(isOnVaultBaseGrid(
249 xrpIssue(), Number{static_cast<std::int64_t>(STAmount::kMaxNativeN)} + 1, 0));
250 EXPECT_FALSE(isOnVaultBaseGrid(iou, Number{1, 100}, baseScale));
251}
252
253TEST(VaultGrid, clamp_vault_outflow)
254{
255 test::Account const issuer{"issuer"};
256 Issue const iou{toCurrency("USD"), issuer.id()};
257 Asset const mpt{MPTIssue{makeMptID(1, issuer.id())}};
258
259 struct Row
260 {
261 char const* name = nullptr;
262 Asset asset;
263 Number available;
264 Number delta;
265 std::optional<Number> expected; // nullopt: tecPRECISION_LOSS
266 };
267 Row const rows[] = {
268 {
269 .name = "XRP outflow is returned unrounded",
270 .asset = xrpIssue(),
271 .available = Number{1'000},
272 .delta = Number{-7},
273 .expected = Number{7},
274 },
275 {
276 .name = "MPT outflow is returned unrounded",
277 .asset = mpt,
278 .available = Number{1'000},
279 .delta = Number{-7},
280 .expected = Number{7},
281 },
282 {
283 .name = "IOU outflow rounds towards zero at the posterior scale",
284 .asset = iou,
285 .available = Number{1'000'000},
286 .delta = Number{-15, -7},
287 .expected = Number{1, -6},
288 },
289 {
290 .name = "IOU outflow below one unit at the posterior scale is rejected",
291 .asset = iou,
292 .available = Number{1'000'000},
293 .delta = Number{-4, -7},
294 .expected = std::nullopt,
295 },
296 };
297 for (auto const& row : rows)
298 {
299 auto const vault = makeVault(
300 row.asset,
301 row.available,
303 row.asset.integral() ? 0 : 6,
304 Number{0},
305 row.available);
306 auto const result = clampVaultOutflow(vault, STAmount{row.asset, row.delta});
307 if (row.expected)
308 {
309 ASSERT_TRUE(result.has_value()) << row.name;
310 EXPECT_EQ(*result, (STAmount{row.asset, *row.expected})) << row.name;
311 }
312 else
313 {
314 ASSERT_FALSE(result.has_value()) << row.name;
315 EXPECT_EQ(result.error(), tecPRECISION_LOSS) << row.name;
316 }
317 }
318}
319
320TEST(VaultGrid, get_vault_default_version)
321{
322 struct Row
323 {
324 char const* name = nullptr;
325 std::unordered_set<UInt256, beast::Uhash<>> enabled;
326 VaultVersion expected;
327 };
328 Row const rows[] = {
329 {.name = "no lending amendments: Legacy", .enabled = {}, .expected = VaultVersion::Legacy},
330 {
331 .name = "LendingProtocolV1_1: CashBasis",
332 .enabled = {featureLendingProtocolV1_1},
333 .expected = VaultVersion::CashBasis,
334 },
335 {
336 .name = "V1_1 and V1_2 without the cleanups: CashBasis",
337 .enabled = {featureLendingProtocolV1_1, featureLendingProtocolV1_2},
338 .expected = VaultVersion::CashBasis,
339 },
340 {
341 .name = "V1_1, V1_2 and fixCleanup3_2_0 without fixCleanup3_4_0: CashBasis",
342 .enabled = {featureLendingProtocolV1_1, featureLendingProtocolV1_2, fixCleanup3_2_0},
343 .expected = VaultVersion::CashBasis,
344 },
345 {
346 .name = "V1_1, V1_2 and fixCleanup3_4_0: FixedPrecision",
347 .enabled = {featureLendingProtocolV1_1, featureLendingProtocolV1_2, fixCleanup3_4_0},
349 },
350 {
351 .name = "V1_2 and both cleanups without V1_1: Legacy",
352 .enabled = {featureLendingProtocolV1_2, fixCleanup3_2_0, fixCleanup3_4_0},
353 .expected = VaultVersion::Legacy,
354 },
355 {
356 .name = "V1_1, V1_2 and both cleanups: FixedPrecision",
357 .enabled =
358 {
359 featureLendingProtocolV1_1,
360 featureLendingProtocolV1_2,
361 fixCleanup3_2_0,
362 fixCleanup3_4_0,
363 },
365 },
366 };
367 for (auto const& row : rows)
368 {
369 // Rules keeps a reference to the preset set; row.enabled outlives it.
370 Rules const rules{row.enabled};
371 EXPECT_EQ(getVaultDefaultVersion(rules), row.expected) << row.name;
372 }
373}
374
375} // namespace
376} // namespace xrpl
A currency issued by an account.
Definition Issue.h:18
Number is a floating point type that can represent a wide range of values.
Definition Number.h:351
Rules controlling protocol behavior.
Definition Rules.h:40
static constexpr std::uint64_t kMaxNativeN
Definition STAmount.h:72
Immutable cryptographic account descriptor.
Definition jtx/Account.h:21
T empty(T... args)
constexpr Zero kZero
Definition Zero.h:30
int getPosteriorVaultScale(SLE::ConstRef vault, STAmount const &delta)
Return the Vault's posterior live exponent after applying an unrounded delta.
Keylet vault(AccountID const &owner, SeqProxy const &seq) noexcept
Definition Indexes.cpp:565
Use hash_* containers for keys that do not need a cryptographically secure hashing algorithm.
Definition algorithm.h:5
Issue const & xrpIssue()
Returns an asset specifier that represents XRP.
Definition Issue.h:108
std::expected< STAmount, TER > clampVaultOutflow(SLE::ConstRef vault, STAmount const &delta)
Outflow clamp dispatcher for VaultWithdraw and VaultClawback: rounds a negative delta to the scale ap...
bool isOnVaultBaseGrid(Asset const &asset, Number const &value, int baseScale)
Returns true iff value is exactly representable both as an STAmount of asset and on the base grid at ...
TEST(FileUtilitiesTest, get_file_contents)
int getVaultScale(SLE::ConstRef vault)
Return the Vault's current live exponent.
std::shared_ptr< SLE > makeVault(Asset const &asset, Number const &assetsTotal, std::optional< VaultVersion > version, std::uint8_t scaleValue=kVaultDefaultIouScale, Number const &assetsDeployed=Number{0}, std::optional< Number > assetsAvailable=std::nullopt)
std::expected< STAmount, TER > clampToAssetsTotalScale(SLE::ConstRef vault, STAmount const &delta)
Adjusts a requested asset change (delta) to match the decimal scale of the updated total vault assets...
bool toCurrency(Currency &, std::string const &)
Tries to convert a string to a Currency, returns true on success.
Definition UintTypes.cpp:65
VaultVersion getVaultDefaultVersion(Rules const &rules)
Resolves which LEVersion a newly-created Vault should get under the currently active amendments.
VaultVersion
Vault ledger-entry schema versions, persisted as sfLEVersion.
Definition Protocol.h:342
STAmount roundToPosteriorVaultScale(SLE::ConstRef vault, STAmount const &amount, Number::RoundingMode roundingMode)
Round an amount at the Vault's posterior live exponent.
int getVaultBaseScale(SLE::ConstRef vault)
Return the Vault's base exponent.
TER checkOptionalVaultInflow(SLE::ConstRef vault, STAmount const &amount)
Check whether amount is an admissible optional inflow.
MPTID makeMptID(std::uint32_t const sequence, AccountID const &account)
Definition Indexes.cpp:219
Number getVaultOpenLimit(SLE::ConstRef vault)
Open-zone capacity ceiling: 9 * 10^(15 + baseScale).
int vaultBaseScale(Asset const &asset, std::uint8_t scale)
Returns the Vault's base exponent for asset at scale, before a Vault object exists to read it from: 0...
@ tecPRECISION_LOSS
Definition TER.h:374
@ tecLIMIT_EXCEEDED
Definition TER.h:372
void associateAsset(STLedgerEntry &sle, Asset const &asset)
Associate an Asset with all sMD_NeedsAsset fields in a ledger entry.
STAmount creditToPosteriorAvailableScale(SLE::ConstRef vault, Number const &raw, Number::RoundingMode roundingMode)
Round a FixedPrecision cash inflow (LoanPay's credit, LoanManage's default cover credit) into AssetsA...
@ tesSUCCESS
Definition TER.h:253