Spec for off-chain distribution metric

[barnabee]

This new dispatch metric will allow transfers (including competitions and rewards) to be creasted that are calculated off-chain.

The basic theory of operation is as follows:

1. A key submits a recurring transfer with this type, this recieives some form of (e.g. hash based) ID ("off-chain transfer ID") specifying:

   • one or more public keys ("metric submission keys") that can submit the final metric values for each key
   • the finalisation threshold, whicih is the number of public keys that must be in agreement for finalisation to occur (e.g. the "m" in "m of n", where n is the total number of public keys provided above)
   • optional metadata (e.g. a list of strings) to be used for things like a reward name/description, a link to and/or hash of the source code that wil be used for the off-chain calculation, etc.

2. At the end of each transfer period (i.e. something like when (current_epoch - RecurringTransfer.start_epoch) % DispatchStrategy.transfer_interval == 0) the system begins waiting for dispatch metric submission transactions from the metric submission keys. These contain:

   • the off-chain transfer ID
   • the epoch for the submission (this must be a valid "end" epoch takingin to account the start_epoch, end_epoch, and any transfer_interval)
   • The calculated results metrics int the form of a list of { key, metric_value } pairs for all public keys with a non-zero meteric/score (NB: keys scoring 0 should be accepted but can be omitted)
   • an optional transer cap (in case the off-chain calculation calls for less than the full payout)

3. Each time a valid dispatch metric submission is received it is recorded against the public key that sent it. Only the most recent valid submission for each end epoch is submitted. A submission is valid if:

   • it is from an allowed public key from those provided for the given off-chain transfer ID
   • the transfer period has passed and the end epoch has been reached (i.e. submissions sent before the period ends should be rejected)
   • the transfer for that epoch has not already been finalised

4. The transfer submission data for a given epoch becomes finalised when, for an epoch that is not already finalised:

   • the previous epoch (if fhis is not the first valid end epoch for the transfer) is finalised (NB: this means that submissions can be captured for any valid end epoch but payouts will always occur in order)
   • there are finalisation threshold dispatch metric submissions all containing exactly the same data (transfer ID, epoch, calculated results metrics after sorting and removing keys with metric == 0, and transfer cap if provided)

5. Once finalised, the payout is processed as for any other recurring transfer/dispatch metric using the metric values supplied, with the addition that if the submission also includes a transfer cap, the amount transferred must also be no larger than the transfer cap. Notes:

   • other caps (e.g. the fee multiple cap) must still also apply
   • if key doesn't meet any scope/eligibility requirements specified on the transfer, its score is 0 (e.g. it is as if it was removed from the submission)

NB: I have specified that payouts happen in order, the reasons for this is to ensure predictable behaviour if the paying account runs out of funds. Given the existence of caps, reserving the max transfer amount doesn't make sense, and it would seem suboptimal to allow the order of metric submissions to affect who would be short changed in that case.