AOS: Document oracle pre-sampling window

[cmjc]

Description

PR https://github.com/autonity/autonity-oracle/pull/17 adds to the autonity-oracle repo README an explanation of the pre-sampling window whereby the oracle server (AOS) will in the last 15 seconds before the next voting round query the data source for the latest price per its configured refresh rate (either default of 30s or another rate if specified by the AOS operator according to their rate limit service agreement with their data source provider)

This is not documented in the AOS content of the docs - either in the AOS Concept descriptions for AOS and oracle network, or in the Run AOS guide section on plugin configuration.

Generally the docs point to content documented elsewhere rather than duplicate it where this is feasible.

However, in this case it would improve docs if the pre-sampling window concept and rationale for it (get the latest price closest to the next round start time to mitigate the risk of a stale price caused by network latency across the distributed system) was described as a concept and flagged as a recommendation to review and set in the Run AOS guide.

Rationale

Node operators need to know, and to be able to predict, how many requests the oracle server is going to make and at what frequency, in order to allocate plan, budget, and allocate resources including API limits.

Implementation

However, in this case it would improve docs if:

• the pre-sampling window was explained in the Concepts - this looks like the right place as the Round event is mentioned here and Round event data is used to parameterise the pre-sampling - https://docs.autonity.org/concepts/oracle-network/#voting-rounds
• a note or info box was added to the Run AOS guide to recommend reviewing and setting the refresh parameter according to your data provider service agreement, and pointing to the pre-sampling window description in the Concepts or in the README.

[aiman]

Rationale: node operators need to know, and to be able to predict, how many requests the oracle server is going to make and at what frequency, in order to allocate plan, budget, and allocate resources including API limits.

[cmjc]

Much better, updated!

[cmjc]

Closing as this was done in the linked PR #147