KPI Option Configuration

KPI options are launched using Long Short Pair (LSP) financial contract and using General_KPI price identifier as detailed in UMIP-117. While technical LSP contract deployment instructions are provided in the deployment tutorial this section guides on how to choose the configuration parameters that would be required in actual deployment.

Expiration

Based on program objectives the expirationTimestamp parameter should be set to Unix timestamp when the KPI options would expire. After expiration once the tracked metric is resolved through UMA Optimistic Oracle KPI option recipients would be able to settle their long tokens and program sponsor would settle their short tokens for any potential collateral remainder.

Even though LSP contract allows enabling early contract expiration through setting enableEarlyExpiration parameter this is currently not yet supported for KPI options as verifiers would need additional instructions on how to check the condition for early expiration.

Naming

The chosen KPI option program name can be set by configuring LSP contract's pairName string parameter. Name and symbol for the distributed long tokens is set in longSynthName and longSynthSymbol parameters while short token naming is configured by setting shortSynthName and shortSynthSymbol parameters.

Collateral Settings

Collateral currency is chosen by setting LSP contract's collateralToken parameter address from the list of UMA governance approved collateral types.

The amount of maximum claimable collateral per unit of KPI option token can be controlled by setting collateralPerPair parameter of LSP contract. Long and short tokens will have the same decimals scaling as underlying collateral currency. For simplicity it should be sufficient to set collateralPerPair to 1 (scaled up by 18 decimals) as the maximum KPI option budget can be controlled by the sponsor choosing the amount of KPI option tokens when minting them. Though for optics reasons the LSP contract deployer might want to choose any other collateralPerPair value as desired.

Proposal / Dispute Settings

The value of tracked metric is resolved through UMA Oracle as documented here. In order to secure this process, economic incentives of proposers and disputers should be aligned. The value of optimisticOracleProposerBond parameter sets the raw amount of collateral currency (scaled up to its decimals) that both proposer or disputer should post in addition to any UMA final fees. In case of dispute the winning side would get half of losing party's bond, hence this should be sufficiently significant to motivate independent verifiers to check the resolved metric for a potential gain. At the same time the bonding amount should not be too high as proposers / disputers might be reluctant to participate in fear of losing too much capital. It is recommended to set bonding amount worth 2 thousand USD for most common KPI option applications.

KPI option deployer also should configure optimisticOracleLivenessTime parameter set to time in seconds for how long after proposing the tracked metric value it can be disputed through Optimistic Oracle. It is recommended to set this liveness to 24 hours for KPI options so that verifiers can have the opportunity to check the resolved metric independently.

Payout Function

After expiration LSP contract would ensure that all locked collateral in KPI options would be claimable among the owners of long and short token holders. The ratio of collateral claimable by long token holders (recipients of KPI option program) would fall within 0%-100% range depending on the value of resolved metric and the configured payout function while short token holders (sponsor of KPI option program) would be able to claim all remainder collateral.

LSP contract's financialProductLibrary parameter is used to select the desired payout logic. Please consult the documentation on selecting among supported payout functions while the deployment tutorial provides a helper selector to choose among the readily available financial product library implementations.

Ancillary Data

The LSP contract's customAncillaryData parameter is used for KPI options to instruct verifiers on how to resolve a particular data request for the price identifier (General_KPI) and request timestamp (KPI option expiration). LSP contract deployment script allows passing ancillary data parameters as string to script's customAncillaryData parameter, though the configuration data is stored on-chain as bytes. Ancillary data string must contain price request parameters expressed as a list of key-value pairs delimited by , (commas) and each key-value pair further delimited by : (colons). If a value should contain , or : characters, such value should be enclosed in double quotes (").

The following sub-sections first cover common ancillary data parameters applicable to all data sources that are followed by data source specific parameters.