# 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](https://github.com/UMAprotocol/UMIPs/blob/master/Implementations/post-processing-functions.md). ### 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.outcome.finance/kpi-options/kpi-option-configuration/common-ancillary-data-parameters.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.