Create epoch duration oracle to get on-ledger epoch duration estimation #18
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
epoch_duration_oracle
The goal of this oracle is to provide an on-ledger duration of all passed epoch since creation of the component as well as a way to compute time elapsed between an epoch and the current epoch.
This does not mean to be a precise clock ticking every seconds, but more of an on-ledger information on whether a time milestone was reached or not. This can not be used as a precise timer for short delays, but can show useful to request time between multiple epochs (the bigger the range, the less significant will be the potential error).
Use cases
An example of usage could be a timed auction. We would:
Instead of providing an "erratic" epoch duration, this would make that auction more precise in terms of human intelligible duration.
Running
Feed the oracle
To run and test the epoch oracle, you can run one of the following:
Query time since epoch
To query from the start of the oracle state, you can use:
To see the difference, there is also a
since_epoch_{current_epoch_on_pte01 + 1}.manifest
to compute time elapsed from different epoch and asince_epoch_0.manifest
to query elapsed time from the start of the oracle.ABI
The available functions are:
EpochDurationOracle::new
: creates a new oracle starting from now and disregarding already elapsed time (does not consider elapsed time of the passed epochs).EpochDurationOracle::new_with_bootstrap(last_epoch: u64, millis_in_last_epoch: u64)
: creates a new oracle starting fromlast_epoch
which lastedmillis_in_last_epoch
. This is useful if you want to start the oracle at a given point in time (but after January 1st 1970).The available method for oracle creator is:
EpochDurationOracle::tick(millis_since_last_tick: u64)
: ticks the internal clock by the provided milliseconds. This can:The available open methods are:
EpochDurationOracle::millis_since_epoch(epoch: u64)
: measure time passed between providedepoch
and current epoch. This can give birth to few cases:epoch
is higher than on-ledger epoch: we will return an errorepoch
is equal to the on-ledger epoch: we will return the time spent on the current epochepoch
is lower than the on-ledger epoch: we will return the time spent between provided epoch and current epochepoch
does not appear for oracle was not created yet: we will return the time spent from the closest lower bound epoch and current epoch (e.g.: if you request time spent from epoch10
and oracle missed it, but we have epoch11
and12
and are in epoch13
, we will compute time spent between epoch13
and11
and consider epoch10
lasted0
. This is acceptable since we are using timestamp, the actual duration will remain correct)EpochDurationOracle::millis_in_epoch(epoch: u64)
: measure duration of providedepoch
. This can give birth to few cases:epoch
is higher than on-ledger epoch: we return an errorepoch
is equal to the on-ledger epoch: we will return the time spent on the current epochepoch
is lower than the on-ledger epoch: we will return the time spent between provided epoch and current epochepoch
is passed but not present on oracle: we will return 0 and suggest calling themillis_since_epoch
method