Metric Operations

In some scenarios results from supported data sources require further operations to obtain the tracked KPI options metric. Simple arithmetic operations allow to combine together multiple data sources or transform them to desired denomination currency. Full specification of metric operations is available in its implementation document to be referenced by verifiers.

In order to use metric operations Operation parameter should be set to string choice from the supported operations. OperationParameters should be set to JSON object with parameter key-value pairs to be used with the chosen Operation.

Configuring Operand Data Sources

Depending on the chosen Operation one of OperationParameters keys should be set either to metricParameters or metricParametersArray. Value of metricParameters should be set to nested JSON object with key-value pairs configuring ancillary data parameters required for the operand data source. Similarly, metricParametersArray should be set to an array of JSON objects configuring multiple operand data sources. All of supported data sources can be used as operands, including nested operations allowing to chain together multiple operations on metric data sources.

Alternatively, deployers of KPI options can opt to store operand data source configuration off-chain by using metricParametersURL instead of metricParameters or metricParametersArrayURL instead of metricParametersArray that would reference the URL where the required JSON object / array is stored. This would allow reducing on-chain storage size in ancillary data and reduce gas costs on contract deployment and KPI option expiration. Though this introduces certain level of centralization risk that can be mitigated by storing operand configuration on decentralized storage platforms (e.g. IPFS). Alternatively, there might be a use case to append additional configuration when part of contracts contributing to the tracked metric are deployed after the launch of KPI options, though this should be done by storing operand configuration on a hosting platform with full version control visibility so that verifiers could check that the referenced configuration is consistent with the measured Metric parameter.

Supported Operations

Summation

Setting Operation string to SUM allows summation of metric data sources configured in metricParametersArray (or referenced in metricParametersArrayURL).

Averaging

Setting Operation string to AVG allows tracking average value of metric data sources configured in metricParametersArray (or referenced in metricParametersArrayURL).

Maximum

Setting Operation string to MAX allows picking the highest value among value of metric data sources configured in metricParametersArray (or referenced in metricParametersArrayURL).

Minimum

Setting Operation string to MIN allows picking the lowest value among value of metric data sources configured in metricParametersArray (or referenced in metricParametersArrayURL).

Difference

Setting Operation string to DIFF allows calculating the difference between the value of two metric data sources configured in metricParametersArray (or referenced in metricParametersArrayURL). This requires that exactly two data sources are provided where the value of the second metric would be subtracted from the value of the first metric.

Conversion

Setting Operation string to CONV allows converting the value of metric data source configured in metricParameters (or referenced in metricParametersURL) to other denomination currency set in priceIdentifier parameter. priceIdentifier parameter should be set to string choice among price identifiers approved by UMA governance though only price identifiers with available base and quote currencies are supported.

By default value of metric data source would be multiplied with the value of resolved price identifier. If optional inverse parameter is set to true the value of metric data source would be divided by the value of resolved price identifier.

Mode of operation

Single Timestamp Operation

If AggregationMethod and AggregationPeriod parameters were not provided in the ancillary data the operation on the operand metrics would be performed at single daily timestamp, though the operand metrics themselves still can be calculated as aggregated over required time period if provided in operand configuration.

Operation Over Time Series

If AggregationMethod and AggregationPeriod parameters were provided in the ancillary data at the operation level the operation on the operand metrics would be performed at every daily timestamp (24:00 UTC) over the configured time period before processing results with the chosen aggregation method. Note that MAX, MIN and DIFF methods do not support operation over time series aggregation.

In case of multiple operands they should be configured to target the same time period for each operand. If any operand data starts at a later timestamp the values of all other operands before that would be discarded. Though, if any of operand data ends at a later timestamp than others the values of all other operands before that would be filled up with their last available values.