KPI Option Configuration
KPI options are launched using Long Short Pair (LSP) financial contract and using
General_KPIprice 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.
Based on program objectives the
expirationTimestampparameter 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
enableEarlyExpirationparameter this is currently not yet supported for KPI options as verifiers would need additional instructions on how to check the condition for early expiration.
The chosen KPI option program name can be set by configuring LSP contract's
pairNamestring parameter. Name and symbol for the distributed long tokens is set in
longSynthSymbolparameters while short token naming is configured by setting
Collateral currency is chosen by setting LSP contract's
collateralTokenparameter 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
collateralPerPairparameter 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
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
collateralPerPairvalue as desired.
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
optimisticOracleProposerBondparameter 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
optimisticOracleLivenessTimeparameter 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.
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.
financialProductLibraryparameter 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.
The LSP contract's
customAncillaryDataparameter 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
customAncillaryDataparameter, 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
: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.