Common Ancillary Data Parameters

All KPI options with canonical data sources share a set of common ancillary data parameters that are documented below.

Tracked Metric

Metric string value should be set to a short description and units of the metric that will be tracked as part of KPI options program. This description should be concise and consistent with all the remaining configuration parameters.

Data Source Method

Method string value should be set to URL link referencing the methodology for the verification of target metric against any of supported data sources. Outcome supports following data sources:

• For DefiLlama TVL the Method should be set to "https://github.com/UMAprotocol/UMIPs/blob/master/Implementations/defillama-tvl.md".

• For subgraph query the Method should be set to "https://github.com/UMAprotocol/UMIPs/blob/master/Implementations/subgraph-query.md".

• For operations on KPI metric data sources the Method should be set to "https://github.com/UMAprotocol/UMIPs/blob/master/Implementations/metric-operations.md".

Override Request Timestamp

RequestTimestampOverride is an optional parameter that allows setting override value for request timestamp expressed in seconds since UNIX Epoch. Setting this parameter before contract expiration would allow to implement a vesting period where KPI option recipients are able to claim the underlying collateral with some delay after KPI metric is measured. Alternatively this parameter might be useful when a change of the metric over different timestamps (e.g. change in cumulative trading volume) should be tracked.

Note that RequestTimestampOverride would be ignored by verifiers if it happens to be past the actual request timestamp, hence to avoid any unintended side effects this must not exceed the expiration timestamp of KPI options.

Time Series Aggregation

AggregationMethod is an optional string parameter that allows processing tracked metric as aggregate over evaluated time period. Outcome supports following aggregation methods:

• TWAP would calculate time weighted average.

• MAX would select the highest metric value.

• MIN would select the lowest metric value.

All supported data sources would be processed at 24h interval granularity so only up to 1 data point per day would be used for aggregation processing. Within each daily interval only the last available data point would be used where 24:00 UTC is the latest possible value still belonging to the previous day.

When using aggregation AggregationPeriod parameter should be set to natural number representing time period in seconds for any time series data processing to be used in conjunction with the AggregationMethod parameter. This time period is relative to the effective request timestamp that marks the end of the aggregation period (contract expiration or value of RequestTimestampOverride when provided).

As an example, KPI options that measures average metric over November 2022 and expiring at year end would need to set:

RequestTimestampOverride:1669852800,
AggregationMethod:TWAP,
AggregationPeriod:2592000

Rounding and Scaling

In order to round raw resolved metric (before any potential post-processing) RawRounding parameter should be set to integer number. If RawRounding is set to non-negative integer the raw metric would be rounded with half away from zero method leaving RawRounding number of digits after the decimal delimiter. In case the RawRounding parameter is set negative then the raw metric would be rounded to the nearest 10 to the power of absolute RawRounding value. For example, rounding raw metric to the nearest million (10 ^ 6) can be achieved by setting RawRounding:-6.

It is also possible to scale the raw metric by setting Scaling parameter to integer value representing power of 10 scaling to be applied on top of rounded raw metric. For example, Scaling:6 would multiply it by 1 million while Scaling:-3 would effectively divide it by 1 thousand.

If rounding is desired to be performed on top of scaling or after applying off-chain payout function (see section below) one can set the Rounding parameter that would work similarly as the RawRounding parameter. Note that by default verifiers would be instructed to apply 0 value for Rounding parameter, hence one should set it to higher value if more precise granularity is required.

Off-chain Payout Function

PostProcessingMethod is an optional parameter that should be used when off-chain post-processing of the resolved KPI metric is required to implement desired payout function. Currently Outcome supports step-wise payout function that can be used by setting PostProcessingMethod value to STEPWISE string.

When using off-chain payout function PostProcessingParameters should be set to stringified JSON object with key-value pairs representing named function parameters specific to the chosen function as detailed below.

Step-wise payout function requires to set milestones parameter within the PostProcessingParameters object. The milestones parameter is a dynamic array containing 2 element arrays where the first element represents KPI metric milestone and the second element represents its resolved price value.

Assuming following desired payout function:

• If KPI metric is negative 0 price should be resolved;

• If KPI metric is at least 0 but lower than 10000 resolve price to 1;

• If KPI metric is at least 10000 but lower than 20000 resolve price to 2;

• If KPI metric is 20000 or higher resolve price to 5.

The above example stepwise function can be achieved by setting following ancillary data parameters:

PostProcessingMethod:STEPWISE,
PostProcessingParameters:{"milestones":[[0,1],[10000,2],[20000,5]]}

Please see full implementation details on supported off-chain payout functions here.

Unresolved Value

In case verifiers could not reasonably figure out the resolvable price either due to unavailable data or misconfiguration of KPI option parameters it is recommended to set numeric value for the fallback price in the Unresolved parameter. If not provided in case of ambiguity this would default to 0.

Note that Unresolved parameter is also used as fallback value in step-wise function when resolved metric is below all defined KPI milestones.