Skip to content

Latest commit

 

History

History
74 lines (50 loc) · 2.86 KB

aip-87.md

File metadata and controls

74 lines (50 loc) · 2.86 KB
aip title author discussions-to (*optional) Status last-call-end-date (*optional) type created updated (*optional) requires (*optional)
87
Introduce native API to evaluate aggregator value is greater or equal to given amount
igor-aptos
<a url pointing to the official discussion thread>
Draft
<mm/dd/yyyy the last date to leave feedbacks and reviews>
Standard (Framework)
<mm/dd/yyyy>
<mm/dd/yyyy>
<AIP number(s)>

AIP-87 - Introduce native API to evaluate aggregator value is greater or equal to given amount

Summary

Adding efficient and parallel-friendly way to check if value in an aggregator is greater than a given limit.

High-level Overview

Calling aggregator_v2::is_at_least API, returns true if aggregator value is larger than or equal to the given min_amount, false otherwise.

Aggregators are concurrent counters, allowing for modification without introducing read/write conflicts. Revealing the actual value (read) introduces the read-write conflict back, but in cases where we need to reveal a property on the value - that can be done so efficiently and in a parallel friendly way, via existing branch prediction. And so this operation is more efficient and much more parallelization friendly than calling read(agg) > min_amount.

Impact

Allows for checking of minimal balance in FA, checking whether milestone is reached on a global counter, among other things, in a parallel friendly way.

Example usage shown in an Counter with milestone example.

Alternatives

Similar functionality can be achieved by combaining try_sub and add:

fun is_at_least<IntElement>(aggregator: &mut Aggregator<IntElement>, min_amount: IntElement): bool {
  if (aggregator_v2::try_sub(&mut agg, min_amount)) {
    aggregator_v2::add(&mut agg, min_amount);
    true
  } else {
    false 
  }
}

But that is less efficient / costs more gas, as well as mutates the aggregator to reveal the needed information.

Reference Implementation

Testing (Optional)

Performance is measured via single-node-performance benchmarks on CI, over a provided move example

Risks and Drawbacks

Security Considerations

None, provides the same functionality as before, just more efficiently

Future Potential

Once traits are deployed, is_at_most/is_equal utility methods will be provided as well. Until then, they can be derived from this one (assuming +1 doesn't overflow):

  • for is_at_most(agg, max_amount), you can do !is_at_least(max_amount + 1)
  • for is_equal(agg, value), you can do is_at_least(value) && !is_at_least(value + 1)

Timeline

Targetted to be part of 1.14 release