# Outcome Outcome's mission is to provide tools for DAOs to achieve better results within the areas of financing, governance and community incentives. Outcome products are powered by UMA's Optimistic Oracle. For information about UMA, refer [here](https://docs.umaproject.org/). ## [KPI Options](broken://pages/gl96D6mflHQ1zQraO8XX) ## [Success Tokens](/success-tokens/what-are-success-tokens) ## [Optimistic Governance](/optimistic-governance/what-is-the-optimistic-governor) ## [Other Outcome Products](/other-outcome-products/other-outcome-products) ## [Resources](/resources/lsp-prerequisites) ## [Links](#undefined) # What are KPI Options? Key Performance Indicator (KPI) Options are expiring synthetic tokens that are worth varying amounts of backing collateral dependent on the value of an arbitrary metric at a pre-defined expiry date. Projects can handpick the metric (KPI) they wish to eventually determine the option redemption value, and then use these ERC20 tokens to create a better form of incentives or payments within their ecosystem. ### **Background** KPI options are expiring synthetic tokens. A synthetic token is a simply a tokenized derivative, or a token that's redemption value is "derived" from a separate underlying metric. Most synthetic tokens derive their value from metrics such as the price of stocks or the value of commodities. KPI options instead derive their redemption value at expiry from the performance of target KPIs for DeFi protocols. As a simple example, a project that wishes to increase the TVL of their protocol could lock some amount of project tokens and mint TVL KPI options that expire in six months. They could then issue these tokens to large DeFi users. In six months, those DeFi users would be able to redeem their KPI options for a linearly increasing amount of the project's token dependent on how much the project's TVL increased. This structure is intended to directly incentivize holders of KPI options to participate in improving the selected KPI, since the value of their KPI option based payment/airdrop/liquidity mining rewards is dependent on the success of that KPI. ### **KPI Data Sources** To price KPI options at expiry an oracle is needed. In this case, [UMA's optimistic oracle](https://docs.umaproject.org/) is used to bring the value of the selected KPI on-chain. Defining secure and accurate oracle measurement methodologies for arbitrary protocol metrics is a complex and arduous task, and thus KPI options can only be used with pre-approved canonical data sources and request methodologies. Today, you can create KPI options based on: * Any protocol TVL metric available on [DefiLlama](https://defillama.com/) * Any on-chain metric available through [the Graph](https://thegraph.com/en/) Using these pre-approved sources allows developers to be confident that their KPI will be returned correctly by UMA's optimistic oracle, and also means that devs should be able to create new KPI options in as little as 30 minutes. ### **Next Steps** To read more about KPI options, please refer to: * [Deploying a KPI option](/kpi-options/deployment-tutorial) * [KPI Option Industry Examples](/kpi-options/examples) # Designing your own KPI options program The impact of KPI options on a project's target KPI is largely dependent on how well users understand and react to KPI options. KPI design, user communication & distribution experience all have an impact on this. This page covers some additional topics that you may need to consider when designing your own KPI option program. ### Pick your Metric The first step is to choose the metric you want your options to track. Today, Outcome supports: * Any protocol TVL metric available on [DefiLlama](https://defillama.com/) * Any on-chain metric available through [the Graph](https://thegraph.com/en/) ### Decide on additional KPI option parameters The following parameters need to be decided on by your team for each KPI option program: 1. **Expiration date:** The timestamp for when the options expire. 2. **The payout function:** The rewards and the associated payout for each KPI option token. Examples here can be linear, binary or step-wise. 3. **The collateral token:** The reward token. Please note that tokens will need to be approved by governance. If not part of the approved list, please reach out to the team to add the token. 4. **The name of the KPI option token:** Each KPI option contract requires a name. For example, "Outcome Airdrop 2023". ### Deploy the contract The [deployment tutorial](/kpi-options/deployment-tutorial) and [launch-lsp repo](https://github.com/UMAprotocol/launch-lsp) can be used to deploy the KPI option contract. ### Mint the KPI options [UMAverse](https://projects.umaproject.org/) is a user interface created to assist teams in minting tokens for newly created KPI options. A minter deposits collateral into a KPI option contract and then receives an equal number of long and short tokens in return. The long token is the "KPI option" that should be distributed/sold to KPI option recipients. The short token is simply tokenized over-collateralization, or the (required minting collateral amount - the settlement value of the KPI option). If your KPI option is not displayed on UMAverse, please reach out on Discord to get it added. ### **Distribution methods** Because each user's needs are different, Outcome does not provide a distribution interface or custom distribution methodology for KPI options. As some options on how to distribute the options, a project could use: * [disperse.app](https://disperse.app/) * Build a claims interface to allow users to interact with a merkle distribution contract. ### **Redeeming the options** [UMAverse](https://projects.umaproject.org/), the UI used to mint options, can also be used by KPI option participants to redeem their tokens for collateral. Options will be available to redeem after the expiration timestamp of the contract and a price proposal goes through the Optimistic Oracle liveness period. # KPI Option Configuration KPI options are launched using [Long Short Pair](https://github.com/UMAprotocol/protocol/tree/master/packages/core/contracts/financial-templates/long-short-pair) (LSP) financial contract and using `General_KPI` price identifier as detailed in [UMIP-117](https://github.com/UMAprotocol/UMIPs/blob/master/UMIPs/umip-117.md). While technical LSP contract deployment instructions are provided in the [deployment tutorial](/kpi-options/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](https://docs.umaproject.org/resources/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](https://docs.umaproject.org/protocol-overview/how-does-umas-oracle-work). 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](/kpi-options/supported-payout-functions) while the [deployment tutorial](/kpi-options/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](https://github.com/UMAprotocol/launch-lsp) 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. # 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. # DefiLlama TVL Any project that has implemented a functioning [DefiLlama adapter](https://github.com/DefiLlama/DefiLlama-Adapters/tree/main/projects) can configure KPI options to track its TVL measured in USD. In addition to [common ancillary data parameters](/kpi-options/kpi-option-configuration/common-ancillary-data-parameters) the deployer should configure DefiLlama TVL specific settings as documented below. Full specification of DefiLlama TVL data source is available in its [implementation document](https://github.com/UMAprotocol/UMIPs/blob/master/Implementations/defillama-tvl.md) to be referenced by verifiers. ### Endpoint `Endpoint` string value should be set to project's DefiLlama TVL API endpoint in the format `"https://api.llama.fi/protocol/"` where `` should be replaced with project slug name used in DefiLlama TVL adapter. ### Metric Selector In order to instruct verifiers on the location of TVL value within returned `Endpoint` response `Key` string parameter should be set to `tvl[i].totalLiquidityUSD where tvl[i].date is the latest daily timestamp before the evaluated timestamp`. By default TVL across all chains would be tracked. If however the KPI metric was to track TVL on a particular chain additional optional `ChainName` string parameter should be set to the selected chain name. Names of supported chains can be observed as key names under the returned `chainTvls` object when querying the `Endpoint`. # Subgraph Query Any project that has implemented a functioning [subgraph](https://thegraph.com/docs/en/developing/creating-a-subgraph/) can configure KPI options to track any custom metric as provided by selected subgraph. In addition to [common ancillary data parameters](/kpi-options/kpi-option-configuration/common-ancillary-data-parameters) the deployer should configure subgraph specific settings as documented below. Full specification of subgraph query data source is available in its [implementation document](https://github.com/UMAprotocol/UMIPs/blob/master/Implementations/subgraph-query.md) to be referenced by verifiers. ### Endpoint When using subgraph on the hosted service `Endpoint` string value should be set to API endpoint in the format `"https://api.thegraph.com/subgraphs/name//"` where `` should be replaced with project's GitHub user name (used when creating hosted subgraph) and `` should be replaced with the name of the tracked subgraph. Users of the subgraph implementation should be aware that the Graph protocol is planning to sunset the hosted service in Q1 2023. Hence, all contracts that are expected to expire after end of 2022 should use the decentralized subgraph network. When using the decentralized network the `Endpoint` parameter should not be provided and instead the `SubgraphId` string value should be set to the identifier of deployed subgraph on the decentralized network. When publicly available deployers should also pass `Source` parameter with string URL link to the repository containing source code for the relevant subgraph. This would allow verifiers to check if returned data is consistent with the tracked `Metric` parameter and provide transparency on any subgraph implementation upgrades. ### Query Configuration `QueryString` string value should be set to configure desired subgraph query as documented in [GraphQL API](https://thegraph.com/docs/en/querying/graphql-api/). Both single entity queries and querying multiple entities within a collection are supported, though a collection of entities (array) can only be used once within the returned data object. #### Single Entities When querying for a single entity `MetricKey` string value should be set to key path to the tracked metric relative to the returned `data` object where nested elements are joined by dots (`.`). `MetricKey` should always be consistent with the requested `QueryString` so that returned `data` object returns the tracked metric in location defined by `MetricKey` parameter. As an illustration consider request on [UMA voting subgraph](https://api.thegraph.com/subgraphs/name/umaprotocol/mainnet-voting) for total number of voters who participated in a particular governance vote where `QueryString` is constructed as: ``` { priceRequest(id: "Admin 123-1626827369") { latestRound { votersAmount } } } ``` The above query would result in following returned data object: ``` { "data": { "priceRequest": { "latestRound": { "votersAmount": "57" } } } } ``` In order to locate the tracked metric (`votersAmount`) the `MetricKey` should have been set to `priceRequest.latestRound.votersAmount`. #### Collection of Entities When querying for a collection of entities `CollectionKey` string value should be set to key path to the relevant collection relative to the returned `data` object and `MetricKey` string value should be set to key path to the tracked metric within the returned collection of entities. Unless data aggregation method is explicitly set the values of tracked metric would be summed together across the returned collection of entities. As an illustration consider request on [UMA voting subgraph](https://api.thegraph.com/subgraphs/name/umaprotocol/mainnet-voting) for voting activity in July 2022 where `QueryString` is constructed as: ``` { priceRequests( where: { resolutionTimestamp_lt: 1659312000, resolutionTimestamp_gte: 1656633600 } ) { latestRound { votersAmount } } } ``` The above query would result in following returned data object (truncated): ``` { "data": { "priceRequests": [ { "latestRound": { "votersAmount": "64" } }, { "latestRound": { "votersAmount": "74" } }, ... ] } } ``` In order to locate the tracked metric (`votersAmount`) within the returned collection the `CollectionKey` should have been set to `priceRequests` (as its value is an array) while `MetricKey` set to `latestRound.votersAmount`. #### Dynamic query configuration Most commonly dynamic query configuration would be useful when due to aggregation the subgraph queries should be iterated with differing timestamp filter parameters or to support repeated queries with pagination. This can be achieved by using angle bracket (`<>`) enclosed macros in `QueryString` that would be expanded at the time of verification. KPI options on subgraph queries support following macros: * `` would be replaced with the value of daily query timestamp that normally is rounded down to 24:00 UTC from the actual request timestamp (or value of `RequestTimestampOverride` when provided). In case of iterative aggregation the verifiers would repeat the query replacing `` with daily timestamps over the configured aggregation period. * `` with `[N]` set to integer value of days would be replaced by the value of daily query timestamp subtracted by `[N] * 86400` seconds. As an illustration, the query above on voting activity in July 2022 can be rewritten to track last 30 days before contract expiration: ``` { priceRequests( where: { resolutionTimestamp_lt: , resolutionTimestamp_gte: } ) { latestRound { votersAmount } } } ``` * `` would be replaced with the latest block number that is at or before the daily query timestamp. This macro operates similar to ``, but is useful when subgraph schema does not support filtering by timestamps directly. Please consult Graph protocol documentation on [time-travel queries](https://thegraph.com/docs/en/querying/graphql-api/#time-travel-queries) for querying subgraph state at any given block number. When querying subgraphs on other chains than Ethereum mainnet the deployer would also need to pass `ChainId` parameter set to the relevant numeric chain identifier so that verifiers can correctly translate daily query timestamp to the corresponding block number. * `` with `[N]` set to integer value of days would be replaced with the latest block number that is at or before the daily query timestamp that had been reduced by `[N] * 86400` seconds. As an illustration, `` would be replaced by the corresponding block number for the timestamp that is 30 days before the daily query timestamp. Similarly as for `` `ChainId` parameter should be provided when querying subgraphs on other chains than Ethereum mainnet. * `` would inform verifiers that the returned collection could include more than 1000 entities and the query should be repeated multiple times as documented in the Graph protocol [pagination](https://thegraph.com/docs/en/querying/graphql-api/#pagination) instructions. `` should be properly located within the selected entity parameters section, so that the verifiers can safely replace it with `first:1000` on the first run or `first:1000,skip:X000` on any subsequent runs iterating over `X`. When `` macro is used it should not conflict with any other `first` or `skip` parameters. As an illustration consider request on [UMA voting subgraph](Endpoint:https://api.thegraph.com/subgraphs/name/umaprotocol/mainnet-voting) for cumulative amount of tokens revealed in voting till expiry where `QueryString` is constructed as: ``` { revealedVotes( , where: { time_lte: } ) { numTokens } } ``` When relying on paginated queries the deployers should be aware that the Graph protocol does not support `skip` argument higher than 5000, hence only maximum of 6000 data entries can be handled. ### Time Series Aggregation In order to support time series aggregation for subgraph queries as documented in [common ancillary data parameters](/kpi-options/kpi-option-configuration/common-ancillary-data-parameters) section the `QueryString` should include macro for timestamp / block number based filtering. This would instruct verifiers to iterate over daily interval timestamps within the period set in `AggregationPeriod` parameter and repeat the query by using macro substitution. #### Single Query Aggregation If subgraph schema provides timestamps it is also possible to construct `QueryString` so that one request (or multiple pagination requests) returns all the data points and their corresponding timestamps that could be used for time series aggregation. The `AggregationPeriod` parameter is redundant in this mode as the desired aggregation time range filtering should be performed within the query definition. This mode can be enabled by providing `TimestampKey` parameter string value set to key path to the timestamp of the returned metric within the returned collection of entities. This would instruct verifiers to slice returned timestamp / metric series in daily intervals ending at 24:00 UTC and pick the last metric - timestamp pairs by its timestamp value within each daily interval (if it includes any data). In case there are more than one data items for the same last daily timestamp the values of such metrics would be summed together. As a real application example consider request on [Idle Finance tranche subgraph](https://api.thegraph.com/subgraphs/name/samster91/idle-tranches) for total value locked in senior wstETH tranche denominated in Wei where `QueryString` is constructed as: ``` { trancheInfos ( , where: { Tranche: \"0x2688fc68c4eac90d9e5e1b94776cf14eade8d877\", timeStamp_lte: , timeStamp_gte: } ) { timeStamp, contractValue } } ``` When above example `QueryString` is accompanied with below listed ancillary data parameters the verifiers would combine results of paginated queries and select last `timeStamp` `contractValue` metric for each day within the 90 day period before contract expiration for time weighted average processing: ``` CollectionKey:trancheInfos, MetricKey:contractValue, TimestampKey:timeStamp, AggregationMethod:TWAP ``` #### Daily Aggregation Single query aggregation method documented above can be modified by providing additional `DailyAggregation` parameter set to `true` that would allow summing up metric values within separate daily intervals before processing them for further aggregation. This would be mostly useful for tracking daily volume metric if subgraph provides only transaction data. As an illustration consider request on [SushiSwap exchange subgraph](https://api.thegraph.com/subgraphs/name/sushiswap/exchange) for daily volume in UMA-WETH pair where `QueryString` is constructed as: ``` { swaps( , where: { timestamp_lte: , timestamp_gte: , pair: \"0x001b6450083e531a5a7bf310bd2c1af4247e23d4\" } ) { timestamp, amountUSD, } } ``` When above example `QueryString` is accompanied with below listed ancillary data parameters the verifiers would first calculate daily total values of `amountUSD` and then calculate average daily volume over the last 30 day period before contract expiration: ``` CollectionKey:swaps, MetricKey:amountUSD, TimestampKey:timestamp, DailyAggregation:true, AggregationMethod:TWAP ``` # 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](https://github.com/UMAprotocol/UMIPs/blob/master/Implementations/metric-operations.md) to be referenced by verifiers. In order to use metric operations `Operation` parameter should be set to string choice from the [supported operations](#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](/kpi-options/kpi-option-configuration/common-ancillary-data-parameters#data-source-method) 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](https://docs.umaproject.org/resources/approved-price-identifiers) 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. # Supported Payout Functions Outcome supports linear and binary payout functions performed on-chain while step-wise function should additionally involve off-chain calculation. On-chain payout function should be configured by pointing the [LSP contract](https://github.com/UMAprotocol/protocol/tree/master/packages/core/contracts/financial-templates/long-short-pair) to the relevant financial product library (FPL) and providing additional parameters for FPL. ### Linear payout When pointing LSP contract to [Linear FPL](https://github.com/UMAprotocol/protocol/blob/master/packages/core/contracts/financial-templates/common/financial-product-libraries/long-short-pair-libraries/LinearLongShortPairFinancialProductLibrary.sol) the recipients of KPI options (long tokens) would be able to claim: * nothing when lower bound of target metric threshold (set in `lowerBound` parameter to FPL) is not met; * maximum amount of `collateralPerPair` (scaled down by 18 decimals) per each long token when upper bound of target metric threshold (set in `upperBound` parameter to FPL) is met; * proportional amount between zero and maximum amount when target metric is resolved between its lower and upper bounds. Note that also `lowerBound` and `upperBound` threshold parameter values should be scaled up by 18 decimals when configuring the KPI options deployment. ### Binary payout When pointing LSP contract to [Binary FPL](https://github.com/UMAprotocol/protocol/blob/master/packages/core/contracts/financial-templates/common/financial-product-libraries/long-short-pair-libraries/BinaryOptionLongShortPairFinancialProductLibrary.sol) the recipients of KPI options (long tokens) would be able to claim: * nothing when target metric threshold (set in `strikePrice` parameter to FPL) is not met; * maximum amount of `collateralPerPair` (scaled down by 18 decimals) per each long token when target metric is at or above its defined threshold (set in `strikePrice` parameter to FPL). Note that also `strikePrice` threshold parameter values should be scaled up by 18 decimals when configuring the KPI options deployment. ### Step-wise payout When using step-wise payout function the verifiers of target metric would be also tasked to transform it to desired payout amounts before resolving final price through Optimistic Oracle. Step-wise function can be configured by `PostProcessingMethod` and `PostProcessingParameters` as documented in [common ancillary data parameters](/kpi-options/kpi-option-configuration/common-ancillary-data-parameters#off-chain-payout-function) section. Since the LSP contract logic is not aware of any off-chain post processing it also requires the configuration of FPL parameters. When using off-chain payout function the deployers should point LSP contract to [Linear FPL](https://github.com/UMAprotocol/protocol/blob/master/packages/core/contracts/financial-templates/common/financial-product-libraries/long-short-pair-libraries/LinearLongShortPairFinancialProductLibrary.sol) and set its `lowerBound` to `0` and `upperBound` matching the highest resolvable price from `PostProcessingParameters` (scaled up by 18 decimals). #### Example step-wise payout As an illustration KPI option program targeting following payouts: * If project TVL is below USD 10 million minimum payout of 100'000 UMA should be distributed; * If project TVL is at least USD 10 million but lower than USD 100 million total payout of 200'000 UMA should be distributed; * If project TVL is USD 100 million or higher maximum payout of 1'000'000 UMA should be distributed. Assuming the resolved TVL is scaled in millions of USD the above example payouts can be achieved by setting following ancillary data parameters: ``` PostProcessingMethod:STEPWISE, PostProcessingParameters:{"milestones":[[0,100],[10,200],[100,1000]]} ``` When deploying KPI options following additional parameters should be set: * `collateralPerPair` to `1` (scaled up by 18 decimals); * FPL pointing to [Linear FPL](https://github.com/UMAprotocol/protocol/blob/master/packages/core/contracts/financial-templates/common/financial-product-libraries/long-short-pair-libraries/LinearLongShortPairFinancialProductLibrary.sol); * FPL `lowerBound` to `0`; * FPL `upperBound` to `1000` (scaled up by 18 decimals); The sponsor in above example should lock 1'000'000 UMA by minting the same amount of long/short pair tokens where long tokens are distributed to KPI option recipients. Depending on resolved TVL the payout function would work as follows: * If TVL is below USD 10 million Optimistic Oracle resolves price to 100 (scaled up by 18 decimals) that corresponds to 10% of `upperBound`, hence KPI option recipients would be able to claim 100'000 UMA; * If TVL is at least USD 10 million but lower than USD 100 million Optimistic Oracle resolves price to 200 (scaled up by 18 decimals) that corresponds to 20% of `upperBound`, hence KPI option recipients would be able to claim 200'000 UMA; * If TVL is USD 100 million or higher Optimistic Oracle resolves price to 1000 (scaled up by 18 decimals) that corresponds to 100% of `upperBound`, hence KPI option recipients would be able to claim 1'000'000 UMA; # Deployment Tutorial This tutorial will demonstrate how to deploy a KPI Option using the `launch-lsp` repository. ### Deployment process The following is an overview of the deployment steps below. 1. Set up LSP deployment prerequisites 2. Decide on your contract parameters 3. Run the deployment on testnet (Kovan) 4. Run the deployment on mainnet (Ethereum) ### LSP Prerequisites Please follow the instructions [here](/resources/lsp-prerequisites) to set up your dev environment for deploying an LSP. ### Setting your parameters For our deployment tutorial, we are going to use the example KPI Option based on UMA's TVL tracked on DefiLlama (UMA-TVL-1222) as a reference when setting the LSP parameters and customizing the deployment script. #### Mandatory deployment parameters Each deployment requires the following parameters to be set at the point of deployment: * `gasprice:` The gas price used for your contract deployment. * `url:` your node URL. * `mnemonic:` Your 12 word seed phrase. * `expirationTimestamp:` Unix timestamp when the KPI Options expire. The UMA team wants to incentivize a TVL over $1 billion by the end of 2022. Therefore, the UMA-TVL-1222 contract uses 1672473600 which represents the Unix timestamp for December 31, 2022. * `collateralPerPair:` The amount of collateral required to mint each long and short pair. The UMA-TVL-1222 contract uses 1 $UMA, meaning 1 $UMA mints 1 long and 1 short token. If 4 $UMA was used as collateral to mint, the minter would receive 4 long and 4 short tokens. * `priceIdentifier:` Should be set to `General_KPI`. * `collateralToken:` Approved collateral currency to be used. The UMA-TVL-1222 contract uses the [UMA token](https://etherscan.io/address/0x04Fa0d235C4abf4BcF4787aF4CF447DE572eF828) as collateral. * `pairName:` The desired name of the token pair. The UMA-TVL-1222 contract uses 'UMA TVL KPI Option December 2022'. * `longSynthName:` The full-length name of the long token. The UMA-TVL-1222 contract uses 'UMA TVL KPI Option December 2022'. * `longSynthSymbol:` The ticker name of the long token. The UMA-TVL-1222 contract uses 'UMA-TVL-1222'. * `shortSynthName:` The full-length name of the short token. The UMA-TVL-1222 contract uses 'UMA TVL KPI Option Short Token December 2022'. * `shortSynthSymbol:` The ticker name of the short token or ticker symbol. The UMA-TVL-1222 contract uses 'UMA-TVL-1222s'. #### Optional deployment parameters * `proposerReward:` Proposal reward to be forwarded to the created contract to be used to incentivize price proposals. This defaults to zero if not provided. * `optimisticOracleLivenessTime:` Time in seconds, the proposed expiration price can be disputed. This generally should be at least a couple of hours for KPI options but might require longer time for more complex KPI options target metric calculations. This defaults to 2 hours if not provided. * `optimisticOracleProposerBond:` Additional bond a proposer must post with the optimistic oracle. This defaults to match the final fee if not provided. #### Ancillary Data Specifications The `customAncillaryData` parameter is used for KPI Options to instruct voters on how to resolve a price request for the price identifier and request timestamp. The ancillary data used for the UMA-TVL-1222 KPI Option is shown below for example purposes. Please reference the section on [KPI Option Configuration](/kpi-options/kpi-option-configuration) for more details on constructing ancillary data for your contract. ``` Metric: TVL in UMA financial contracts measured in millions of USD, Endpoint: "https://api.llama.fi/protocol/outcome-finance", Method: "https://github.com/UMAprotocol/UMIPs/blob/master/Implementations/defillama-tvl.md", Key: tvl[i].totalLiquidityUSD where tvl[i].date is the latest daily timestamp before the evaluated timestamp, Scaling: -6, Rounding: -6 ``` Key-value pairs above are formatted just for readability, but no white-spaces should be used in real application. When this ancillary data dictionary (without white-spaces) is stored as bytes, the result would be: ``` 4d65747269633a54564c20696e20554d412066696e616e6369616c20636f6e747261637473206d6561737572656420696e206d696c6c696f6e73206f66205553442c456e64706f696e743a2268747470733a2f2f6170692e6c6c616d612e66692f70726f746f636f6c2f6f7574636f6d652d66696e616e6365222c4d6574686f643a2268747470733a2f2f6769746875622e636f6d2f554d4170726f746f636f6c2f554d4950732f626c6f622f6d61737465722f496d706c656d656e746174696f6e732f646566696c6c616d612d74766c2e6d64222c4b65793a74766c5b695d2e746f74616c4c69717569646974795553442077686572652074766c5b695d2e6461746520697320746865206c6174657374206461696c792074696d657374616d70206265666f726520746865206576616c75617465642074696d657374616d702c5363616c696e673a2d362c526f756e64696e673a2d36 ``` #### FPL deployment parameters The `fpl` parameter determines the type of financial product library (FPL) used for the payout function based on a resolved target KPI metric as documented in [supported payout functions section](/kpi-options/supported-payout-functions). The most applicable FPLs for KPI options might be: * `BinaryOption` to select [Binary Options](https://github.com/UMAprotocol/protocol/blob/master/packages/core/contracts/financial-templates/common/financial-product-libraries/long-short-pair-libraries/BinaryOptionLongShortPairFinancialProductLibrary.sol) type that would either pay out nothing or maximum amount (set in `collateralPerPair`) to KPI options token holders depending on whether the target metric threshold is met. * `Linear` to select [Linear](https://github.com/UMAprotocol/protocol/blob/master/packages/core/contracts/financial-templates/common/financial-product-libraries/long-short-pair-libraries/LinearLongShortPairFinancialProductLibrary.sol) type that would pay out nothing when lower bound of target metric threshold is not met, a maximum amount (set in `collateralPerPair`) when upper bound of target metric threshold is met, and proportional payout when target metric is between its lower and upper bounds. The UMA-TVL-1222 contract uses `Linear` as the FPL parameter which instructs voters on how to resolve a price request for the price identifier and request timestamp. The `Linear` FPL requires `lowerBound` and `upperBound` parameters to be set to determine the payout function. Based on the desired UMA-TVL-1222 payout logic, the `lowerBound` parameter should be set to 0 and the `upperBound` parameter should be set to 1000 (scaled up by 18 decimals) interpreted as reaching 1 billion USD (one thousand millions). ### Simulating Deployment Before running this command, you should customize the parameters to your needs and passing `--simulate` parameter. `YOUR_NODE_URL` should be filled in with a url for the network that you wish to deploy to. The deployment script has been pre-filled with the parameters for the UMA-TVL-1222 contract. If using Infura for mainnet simulation, `YOUR_NODE_URL` will follow this format: ``` wss://mainnet.infura.io/ws/v3/{projectId} ``` Run the simulation script with your specific parameters. ``` node index.js --gasprice 100 --url YOUR_NODE_URL --mnemonic "your mnemonic (12 word seed phrase)" --pairName "UMA TVL KPI Option December 2022" --expirationTimestamp 1672473600 --collateralPerPair 1000000000000000000 --priceIdentifier General_KPI --longSynthName "UMA TVL KPI Option December 2022" --longSynthSymbol UMA-KPI-1222 --shortSynthName "UMA TVL KPI Option Short Token December 2022" --shortSynthSymbol UMA-KPI-1222s --collateralToken 0x04Fa0d235C4abf4BcF4787aF4CF447DE572eF828 --customAncillaryData "Metric:TVL in UMA financial contracts measured in millions of USD,Endpoint:\"https://api.llama.fi/protocol/outcome-finance\",Method:\"https://github.com/UMAprotocol/UMIPs/blob/master/Implementations/defillama-tvl.md\",Key:tvl[i].totalLiquidityUSD where tvl[i].date is the latest daily timestamp before the evaluated timestamp,Scaling:-6,Rounding:-6" --optimisticOracleLivenessTime 3600 --fpl Linear --lowerBound 0 --upperBound 1000000000000000000000 --proposerReward 20000000000000000000 --optimisticOracleProposerBond 40000000000000000000 --simulate ``` ### Deploying to Mainnet The method to deploy onto mainnet is the exact same as with simulation, except for skipping `--simulate` parameter`.` You can now run the deployment script. From within the `launch-lsp` directory, run: ``` node index.js --gasprice 100 --url YOUR_NODE_URL --mnemonic "your mnemonic (12 word seed phrase)" --pairName "UMA TVL KPI Option December 2022" --expirationTimestamp 1672473600 --collateralPerPair 1000000000000000000 --priceIdentifier General_KPI --longSynthName "UMA TVL KPI Option December 2022" --longSynthSymbol UMA-KPI-1222 --shortSynthName "UMA TVL KPI Option Short Token December 2022" --shortSynthSymbol UMA-KPI-1222s --collateralToken 0x04Fa0d235C4abf4BcF4787aF4CF447DE572eF828 --customAncillaryData "Metric:TVL in UMA financial contracts measured in millions of USD,Endpoint:\"https://api.llama.fi/protocol/outcome-finance\",Method:\"https://github.com/UMAprotocol/UMIPs/blob/master/Implementations/defillama-tvl.md\",Key:tvl[i].totalLiquidityUSD where tvl[i].date is the latest daily timestamp before the evaluated timestamp,Scaling:-6,Rounding:-6" --optimisticOracleLivenessTime 3600 --fpl Linear --lowerBound 0 --upperBound 1000000000000000000000 --proposerReward 20000000000000000000 --optimisticOracleProposerBond 40000000000000000000 ``` Once deployed, the script will list the address of your newly deployed LSP. A successful output will look like this: ``` Simulating Deployment...Simulation successful. Expected Address: 0x44978157afE92c926619EBB54599bbc483eBe871 ``` # Examples **Example Projects:** * [Boba Network Launches ‘WAGMI’ Options](https://boba.network/wagmi/) * [Boba Network Partners with UMA to create “WAGMI” KPI Options](https://medium.com/uma-project/boba-network-partners-with-uma-to-create-wagmi-kpi-options-d967427ebad6) * [BadgerDAO’s “Rebase Mining” Implementation](https://medium.com/uma-project/badgerdaos-rebase-mining-kicks-off-now-using-uma-s-kpi-options-cd75f71dc1fa) * [GYSR KPI Options Integration](https://medium.com/uma-project/learn-about-gysr-streamed-kpi-options-41ac26cbc613) * [QiDao Strategic Partnership Program](https://0xlaozi.medium.com/qidao-partners-with-uma-to-power-strategic-partner-program-cfd0d29adbf6) * [See KPI Options tab in UMAverse for current and expired KPI Options](https://umaverse.vercel.app) **Other Links:** * [KPI Options explainer video](https://www.youtube.com/watch?v=U1xNkCbuiPA\&%3Bfeature=youtu.be) * [KPI Options Product Page](https://umaproject.org/products/kpi-options) # What are Success Tokens? Success tokens offer an alternative way for DAOs to diversify their treasury and sell tokens to investors in an incentive-aligned way. Success tokens are just two financial products wrapped into one token: a predetermined amount of a token combined with a covered call option for that token. ### Success Token Parameters Before contract deployment, the following parameters should be negotiated between a DAO and investors: * The strike price of the call option. * The expiry date. * The price at which the success token is sold. * The units of collateral that should be used as the floor value per success token. In the graphic below, this is referenced as `Number of Project Tokens`. * The units of collateral backing each covered call option per success token. In the graphic, this is referenced as `Call Option Collateral`. The success token payout calculation uses these parameters to determine the following payout at expiry: ![](https://2868101861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9MaSF2pKlPEvo9UlKGAr%2Fuploads%2FVZFk1tiYKoj4BMAcFCWb%2Fsuccess-token-payout2.png?alt=media\&token=9e73c8f0-2d9b-4cc6-9609-8b4c4fe99224) If the expiration price is below the strike price, the investor only receives the project token portion and does not receive any portion of the collateral backing the covered call option. If the expiration price is above the strike price, the call option pays investors an additional amount demonstrated as the bonus value below: ![](https://2868101861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9MaSF2pKlPEvo9UlKGAr%2Fuploads%2FOEGiYLUEChzV8I2ShTRe%2Fsuccess-graph.png?alt=media\&token=f05706d5-3b09-4cbc-9a16-bdc1c7228f56) #### Note on Success Token Parameters On-chain, `Number of Project Tokens` and `Call Option Collateral` are actually determined by two other parameters. These are called `collateralPerPair` and `basePercentage`. `collateralPerPair` is simply the total units of collateral backing one success token. `basePercentage` determines the percentage of the total success token collateral (`collateralPerPair`) that is used as the floor value for the success token versus the percentage that is used to collateralize the covered call option. As an example, a success token with a `collateralPerPair` of 2 and a `basePercentage` of 0.75 would have a floor value of 1.5 units of collateral combined with a covered call option backed by 0.5 units of collateral. ### Success Token Example An example contract we will refer to throughout the success token sections is a success token issued by the UMA treasury (stUMA-1222) with several VC investors that agree to create a success token which combines 1 $UMA token with a $15 strike $UMA call option backed by 0.5 $UMA tokens. The value of the success token would depend on the UMAUSD price at expiry: * If the price is less than $15, each long is worth 1 $UMA, because the embedded call option expired worthless. * If the price expired at $30, the success token value in UMA would be calculated using 1 + (( 0.5 ) \* ( $30 - $15 ) / $30 ) = 1.25 $UMA per success token. In dollar value, 1 stUMA-1222 with a $30 expiry price would be worth $30.00 \* 1.25 = $37.50. ### Why would an investor buy a Success Token? * Success tokens provide investors the kind of risk and upside exposure potential they are looking for without forcing a project or DAO to sell tokens at a discount. Investors are receiving compensation for capital lock-up time in the form of a call option instead of a token discount. This provides a strong incentive for investors to participate in the project's growth, while also giving the investor a large amount of upside. This is a mutually beneficial situation for both parties involved, where the investor is *only* specially compensated if the project succeeds. * Success tokens allow more flexibility for investors to negotiate terms with a DAO along with an increased likeliness of the deal being well received by decentralized communities. ### Why should DAOs use Success Tokens? * Selling upside optionality to the success token holder in return for downside protection is generally a desirable outcome for DAOs that are already extremely exposed to the price of their own token. * Success tokens allow DAOs to borrow funds without the risk of liquidation and utilizes their native token which dominates most of their treasury. In contrast, yield dollars and CDPs require borrowers to maintain a certain collateral ratio or face liquidation. Maintaining healthy collateralization ratios could be very detrimental DAO if the price of its native token drops aggressively and the DAO is forced to put a significant amount of its treasury at risk. * Success tokens can give the DAO access to VC capital and expertise which helps projects succeed without selling their tokens at a discount. # Deployment Tutorial This tutorial will show you how to deploy a success token using the `launch-lsp` repository. ### Deployment process The following is an overview of the deployment steps below. 1. Set up LSP deployment prerequisites 2. Decide on your contract parameters 3. Run the deployment on testnet (Kovan) 4. Run the deployment on mainnet (Ethereum) ### LSP Prerequisites Please follow the instructions [here](/resources/lsp-prerequisites) to set up your dev environment for deploying an LSP. ### Setting your parameters For our deployment tutorial, we are going to continue using the UMA success token example (stUMA-1222) as a reference when setting the LSP parameters and customizing the deployment script. #### Mandatory deployment parameters Each deployment requires the following parameters to be set at the point of deployment: * `gasprice:` The gas price used for your contract deployment. * `url:` your node URL. * `mnemonic:` Your 12 word seed phrase. * `expirationTimestamp:` Timestamp at which your contract will expire. The stUMA-1222 contract uses 1672473600 which represents the Unix timestamp for December 31, 2022. * `collateralPerPair:` The amount of collateral required to mint each long and short pair. The stUMA-1222 contract uses 1 UMA, meaning 1 UMA minted 1 long and 1 short token. If you minted using 4 $UMA as collateral, you would receive 4 long and 4 short tokens. * `priceIdentifier:` The approved price identifier to be used. The stUMA-1222 contract uses UMAUSD. * `collateralToken:` Approved collateral currency to be used. The stUMA-1222 contract uses the [UMA token](https://etherscan.io/address/0x04Fa0d235C4abf4BcF4787aF4CF447DE572eF828) as collateral. * `pairName:` The desired name of the token pair. The stUMA-1222 contract uses 'UMA Success Token $15 Strike December 2022'. * `longSynthName:` The full-length name of the long token. The stUMA-1222 contract uses 'UMA Success Token $15 Strike December 2022'. * `longSynthSymbol:` The ticker name of the long token. The stUMA-1222 contract uses 'stUMA-1222'. * `shortSynthName:` The full-length name of the short token. The stUMA-1222 contract uses 'UMA Success Short Token $15 Strike December 2022'. * `shortSynthSymbol:` The ticker name of the short token or ticker symbol. The stUMA-1222 contract uses 'stUMA-1222s'. #### Optional deployment parameters * `enableEarlyExpiration:` If set to true, the LSP contract can request to be settled early by calling the optimistic oracle. If not needed, the parameter will be set to false. * `customAncillaryData:` Custom ancillary data to be passed along with the price request. If not needed, this flag can be excluded and will be left as a 0-length bytes array. The stUMA-1222 contract uses 'twapLength:3600'. * `proposerReward:` Proposal reward to be forwarded to the created contract to be used to incentivize price proposals. * `optimisticOracleLivenessTime:` Custom liveness window for disputing optimistic oracle price proposals in seconds. A longer liveness time provides more security, while a shorter one provides faster settlement. By default, this is set to 7200 seconds. * `optimisticOracleProposerBond:` Additional bond a proposer must post with the optimistic oracle. A higher bond makes incorrect disputes and proposals more costly. #### FPL deployment parameters The `fpl` parameter is used in the deployment script to designate `SuccessToken` or `SimpleSuccessToken` as the financial library used to calculate the payout at expiry. `SuccessToken` requires `strikePrice` and `basePercentage` parameters to be added to the deployment script while `SimpleSuccessToken` only requires `strikePrice`. The `basePercentage` parameter is the percentage of collateral per pair used as the floor. This parameter is always set to 50% for `SimpleSuccessToken` but you can set this to a custom value for `SuccessToken`. As an example, if `basePercentage` is set to 40%, then 40% of the success token would act as collateral with 60% functioning as an embedded covered call. The `strikePrice` parameter is used for the strike price of the embedded call option. The stUMA-1222 contract uses `SuccessToken` as the fpl parameter, `strikePrice` is set to $15, and `basePercentage` is set to 0.5. If the expiration price is below the `strikePrice`, the investor only receives the collateral. If the expiration price is above the strike price, the call option pays investors an additional amount based on the value of the embedded call option. ### Deploying to Kovan Before running this command, you should customize the parameters to your needs. YOUR\_NODE\_URL should be filled in with a url for the network that you wish to deploy to. The deployment script has been pre-filled with the parameters for the stUMA-1222 contract. If using Infura for a Kovan deployment, `YOUR_NODE_URL` will follow this format: ``` wss://kovan.infura.io/ws/v3/{projectId} ``` Run the deployment script with your specific parameters. ``` node index.js --gasprice 1 --url YOUR_NODE_URL --mnemonic "your mnemonic (12 word seed phrase)" --pairName "UMA Success Token \$15 Strike December 2022" --expirationTimestamp 1672473600 --collateralPerPair 250000000000000000 --priceIdentifier UMAUSD --longSynthName "UMA Success Token \$15 Strike December 2022" --longSynthSymbol stUMA-1222 --shortSynthName "UMA Success Short Token \$15 Strike December 2022" --shortSynthSymbol stUMA-1222s --collateralToken 0x489Bf230d4Ab5c2083556E394a28276C22c3B580 --customAncillaryData "twapLength:3600" --optimisticOracleLivenessTime 3600 --fpl SuccessToken --strikePrice 15000000000000000000 --basePercentage 500000000000000000 --proposerReward 20000000000000000000 --optimisticOracleProposerBond 40000000000000000000 ``` ### Deploying to Ethereum Mainnet The method to deploy onto mainnet is the exact same as with Kovan, except `url` will need to be amended for use on Ethereum mainnet. If using Infura for mainnet, `YOUR_NODE_URL` will follow this format: ``` wss://mainnet.infura.io/ws/v3/{projectId} ``` You can now run the deployment script. From within the `launch-lsp` directory, run: ``` node index.js --gasprice 80 --url YOUR_NODE_URL --mnemonic "your mnemonic (12 word seed phrase)" --pairName "UMA Success Token \$15 Strike December 2022" --expirationTimestamp 1672473600 --collateralPerPair 250000000000000000 --priceIdentifier UMAUSD --longSynthName "UMA Success Token \$15 Strike December 2022" --longSynthSymbol stUMA-1222 --shortSynthName "UMA Success Short Token \$15 Strike December 2022" --shortSynthSymbol stUMA-1222s --collateralToken 0x04Fa0d235C4abf4BcF4787aF4CF447DE572eF828 --customAncillaryData "twapLength:3600" --optimisticOracleLivenessTime 3600 --fpl SuccessToken --strikePrice 15000000000000000000 --basePercentage 500000000000000000 --proposerReward 20000000000000000000 --optimisticOracleProposerBond 40000000000000000000 ``` Once deployed, the script will list the address of your newly deployed LSP. A successful output will look like this: ``` Simulating Deployment...Simulation successful. Expected Address: 0x44978157afE92c926619EBB54599bbc483eBe871 ``` # Examples **Links:** * [Success Tokens: An Incentive Aligned Way for VC Funds to Invest in DAOs](https://medium.com/uma-project/success-tokens-an-incentive-aligned-way-for-vc-funds-to-invest-in-daos-1e8b8244f2f4) * [Success Token tab in UMAverse for current and expired success tokens](https://umaverse.vercel.app) * [ShapeShift DAO FOX success token raise with participation from Coinbase Ventures and Chapter One](https://www.prnewswire.com/news-releases/coinbase-ventures-and-chapter-one-take-significant-share-of-shapeshift-daos-new-fox-success-tokens-301509221.html) # What is the Optimistic Governor? The Optimistic Governor contract is used to govern a [Gnosis Safe](https://gnosis-safe.io/) based on a set of rules defined off-chain. These rules are enforced using UMA's [Optimistic Oracle](https://umaproject.org/optimistic-oracle.html) and the [ZODIAC identifier](https://github.com/UMAprotocol/UMIPs/blob/master/UMIPs/umip-152.md) allowing for a new era of flexible "optimistic governance". Management of DAO treasuries and other multi-signature wallets no longer need to be limited to X-of-Y signing schemes or tokenholder votes. Instead, a DAO can publish rules in plain English with sufficient detail for a neutral third-party observer to determine whether transactions submitted to a Gnosis Safe follow the rules or not. The Optimistic Governor then allows any address to propose transactions that follow the predetermined set of rules. These transactions then go through a challenge period where any address can dispute the transaction. If a transaction is not disputed, it can then be executed. However, if any address believes the proposed transaction does not follow the rules, the transaction can be disputed. A dispute is resolved by neutral human voters brought in to vote on the outcome based on the predetermined set of rules. The Optimistic Governor has been audited by OpenZeppelin and the audit report can be viewed [here](https://blog.openzeppelin.com/uma-optimistic-governor-audit/). # Other Outcome Products The UMA Long Short Pair (LSP) contract template allows for many use cases involving unliquidatable capped-payout financial contracts. While [KPI Options ](broken://pages/gl96D6mflHQ1zQraO8XX)and [Success Tokens](/success-tokens/what-are-success-tokens) have been addressed in previous sections, below are other products built using the LSP contract. ### Range Tokens The range token enables a DAO or nascent project to use its native token as collateral to borrow funds. At maturity, if the debt is not paid, the range token holder is instead compensated with an equivalent amount of the collateral (the native token) using the settlement price of the native token to determine the number of tokens. A range token can be viewed similarly to convertible debt. In the venture capital world, convertible debt allows startup companies to receive funding today without issuing equity upfront. The range token holder is effectively short a put option and will have exposure to the downside of the native token below a certain price. To compensate the range token holder for taking on this “default” risk, the holder is rewarded a call option on the native token. A minimum number of native tokens is given to the range token holder no matter how much the native token rallies. The combination of the structure creates a tradeoff between the seller and the buyer. ### Protected Tokens Protected token pairs use the UMA Long-Short Pair contract to wrap any ERC20 asset and create protected and recovery tokens. The protected tokens are put in a wallet or contract address where you want an extra layer of protection and the recovery tokens are held in a secure wallet elsewhere and can be used to recover the underlying assets in the event of a hack, bug, or other cause of lost funds. Therefore, the protected tokens can be used with confidence that they do not expose your assets to additional smart contract risk beyond the relatively simple (and OpenZeppelin audited) Long-Short Pair contract, which is particularly useful for new protocols or new features added to existing protocols. ### Call Options A call option is a building block for the derivatives market. It gives the buyer the right but not the obligation to buy the asset at a specific price (strike) at a specific time. There are a number of reasons for call options in the traditional financial world. Some of the reasons translate to the DeFi space as well as open new use cases such as: **Leveraged Speculation** — The simplest use for a long call position is the ability to speculate on the appreciation of an asset with leverage while also limiting your downside. To obtain the right to be long 1 ETH at a price of 2000 in our example above, the token holder only needs to pay 5% of 1 ETH. However, the flip side to that is the value of the option will depreciate or decay very quickly to zero if it does not trade above the strike price. **Strategic DeFi Project Uses** — Many DeFi projects have distributed their governance tokens either via airdrops or through liquidity mining or developer mining programs. The one downside is many recipients of the tokens may not be long term community members and instead are just looking to dump acquired tokens which could cause a depression in the token price. Distributing a mix of governance tokens and call options could help align the incentives of token recipients by giving recipients a vested interest in contributing to the long-term success of the project. **Better Airdrops and Farms** - Options are a popular form of compensation because they align incentives. A token economics benefit is that they only result in sell pressure if the market is bullish. A certain price target is set by the deployer, and option recipients can only cash out if the token price exceeds the strike price at expiry. ### Additional Resources * [UMA Launches Hats Finance Vault with Protected Tokens](https://medium.com/uma-project/uma-launches-hats-finance-vault-with-protected-tokens-2ad4587fcdf) * [Treasury Diversification with Range Tokens](https://medium.com/uma-project/treasury-diversification-with-range-tokens-145d4b12614e) If you are interested in deploying one of the above products, refer to our [launch-lsp Github Repository](https://github.com/UMAprotocol/launch-lsp) for setting parameters and expected payouts. To receive additional support in your build process, please make sure to reach out in the [UMA Discord](https://discord.com/invite/jsb9XQJ). # LSP Prerequisites To deploy KPI options or Success tokens, we will use the launch-lsp repo. To prepare your dev environment, please follow these prerequisites. ### Clone the launch-lsp stub repo 1. Clone the repo: * [launch-lsp](https://github.com/UMAprotocol/launch-lsp) ``` git clone https://github.com/UMAprotocol/launch-lsp.git ``` ### Install dependencies You will need to install nodejs v14 (we recommend nvm to manage node versions) and yarn. Note: these additional dependencies are required -- you may or may not have them on your system already: * libudev * libusb These dependencies are installed on MacOS by installing the XCode Developer Tools. For Linux, the example ubuntu installation command for additional deps is: ``` sudo apt-get update && sudo apt-get install -y libudev-dev libusb-1.0-0-dev ``` ### Install packages ``` yarn ``` # Network Addresses | Network | UMA Contract Addresses | | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Ethereum](https://ethereum.org/) | [Mainnet](https://github.com/UMAprotocol/protocol/blob/master/packages/core/networks/1.json), [Kovan](https://github.com/UMAprotocol/protocol/blob/master/packages/core/networks/42.json), [Rinkeby](https://github.com/UMAprotocol/protocol/blob/master/packages/core/networks/4.json) | | [Polygon](https://polygon.technology/) | [Mainnet](https://github.com/UMAprotocol/protocol/blob/master/packages/core/networks/137.json), [Mumbai](https://github.com/UMAprotocol/protocol/blob/master/packages/core/networks/80001.json) | | [Boba Network](https://boba.network/) | [Mainnet](https://github.com/UMAprotocol/protocol/blob/master/packages/core/networks/288.json) | | [Optimism](https://www.optimism.io/) | [Mainnet](https://github.com/UMAprotocol/protocol/blob/master/packages/core/networks/10.json) | | [Arbitrum](https://arbitrum.io/) | [Mainnet](https://github.com/UMAprotocol/protocol/blob/master/packages/core/networks/42161.json) | | [xDAI](https://www.xdaichain.com/) | [Mainnet](https://github.com/UMAprotocol/protocol/blob/master/packages/core/networks/100.json) | # Audit & Bug Bounty Programs Security of the platform is our highest priority. All contract code and balances are publicly verifiable, and security researchers are eligible for a bug bounty for reporting undiscovered vulnerabilities. ### Audits OpenZeppelin has performed the following audits on UMA contracts: * [Common and oracle directory contracts: April 28, 2020](https://blog.openzeppelin.com/uma-audit-phase-1/) * [Financial-templates directory contracts: May 12, 2020](https://blog.openzeppelin.com/uma-audit-phase-2/) * [Updates to the Expiring Multiparty contracts and flash loan mitigations for the voting contracts: September 9, 2020](https://blog.openzeppelin.com/uma-audit-phase-3/) * [Perpetual Multiparty template contracts: February 2, 2021](https://blog.openzeppelin.com/uma-audit-phase-4/) * [Insured Bridge contracts: December 1, 2021](https://blog.openzeppelin.com/uma-audit-l2-bridges/) * [Governance, cross-chain oracle, and optimistic rewarder contracts: January 7, 2022](https://blog.openzeppelin.com/uma-audit-phase-6/) * [UMA Optimistic Governor Audit: July 21, 2022](https://blog.openzeppelin.com/uma-optimistic-governor-audit/) * [Across Token and Token Distributor Audit: July 21, 2022](https://blog.openzeppelin.com/across-token-and-token-distributor-audit/) Additionally, OpenZeppelin audits incremental upgrades to UMA's contracts on a continuous basis. The continuous audit report can be found [here](https://blog.openzeppelin.com/uma-continuous-audit/). ### Bug Bounty Rewards UMA encourages the community to audit our contracts and security; we also encourage the responsible disclosure of any issues. The bug bounty program is intended to recognize the value of working with the community of independent security researchers and sets out our definition of good faith in the context of finding and reporting vulnerabilities, as well as what you can expect from us in return. UMA offers substantial rewards for discoveries that can prevent the loss of assets, the freezing of assets, or harm to users. All rewards will be paid in $UMA, and the amount of compensation will vary depending on bug severity. Reward amounts typically correspond to severity in the following manner. | Severity | Reward amount in USD | | -------- | -------------------- | | Low | $250 | | Medium | $3,000 | | High | $10,000 | | Critical | 10% of funds at risk | Severity is calculated according to the [OWASP](https://owasp.org/www-project-risk-assessment-framework/) risk rating model based on Impact and Likelihood. ![](https://2868101861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9MaSF2pKlPEvo9UlKGAr%2Fuploads%2F7xCRgPqzbv507bjegyRW%2Fseverity.png?alt=media\&token=5568df15-34a4-4b4a-b127-710c02a4bd3c) ### Hats Vault UMA offers additional rewards through [Hats.finance](https://app.hats.finance/vaults), which pay out [UMA-backed protected tokens](https://medium.com/uma-project/uma-launches-hats-finance-vault-with-protected-tokens-2ad4587fcdf) for reports of smart contract vulnerabilities based on severity. Whitehat hackers are encouraged to submit smart contract vulnerabilities through Hats.finance in addition to e-mailing to claim these rewards. Note that *only* smart contract vulnerabilities are eligible for rewards from the Hats vault. Any vulnerability or bug reports not related to UMA or Across Protocol smart contracts, such as front-end or hosting configuration issues, will not receive rewards. ### Scope The scope of our bug bounty program includes any and all of UMA's production smart contracts. It does not include known issues with the intended behavior. #### In scope: * All UMA smart contracts that are deployed to mainnet: [link](https://github.com/UMAprotocol/protocol/tree/master/packages/core/contracts/). * Note: this does not include smart contracts that have not been deployed in a production capacity (test deployments for instance). * Bot code to support actively deployed smart contracts: [link](https://github.com/UMAprotocol/protocol/tree/master/packages/). #### Examples of what’s in scope: * Being able to steal funds * Being able to freeze funds or render them inaccessible by their owners #### Out of scope: * Issues that have already been submitted by another user or are already known to the UMA team * Note: this includes bugs known to the UMA team, but have not been disclosed due to active mitigation efforts. * Vulnerabilities in contracts built on top of the protocol by third-party developers (such as smart contract wallets) * Vulnerabilities that require ownership of an admin key * Any files, modules or libraries other than the ones mentioned above * More efficient gas solutions * Any points listed as an already known weaknesses * Any points listed in an audit report ### Submissions Please email your submissions to . The submission must include clear and concise steps to reproduce the discovered vulnerability. ### Terms & Conditions If you comply with the policies below when reporting a security issue to us, we will not initiate a lawsuit or law enforcement investigation against you in response to your report. We ask that you: * Report any vulnerability you’ve discovered promptly. * Avoid violating the privacy of others, disrupting our systems, destroying data, or harming user experience. * Use only to discuss vulnerabilities with us. * Keep the details of any discovered vulnerabilities confidential until they are publicly announced by Risk Labs. * Perform testing only on in-scope systems, and respect systems and activities which are out-of-scope. * Not engage in blackmail, extortion, or any other unlawful conduct. * Not be a current or former UMA Foundation employee, vendor, contractor, or the employee of an UMA vendor or contractor. Public disclosure of the bug or the indication of an intention to exploit it on Mainnet will make the report ineligible for a bounty. If in doubt about other aspects of the bounty, most of the [Ethereum Foundation bug bounty program rules](https://bounty.ethereum.org/) will apply. Any questions? Reach us via email (). For more information on the UMA platform, check out our [website](http://www.umaproject.org/) and [Github](https://github.com/UMAprotocol/). All reward determinations, including eligibility and payment amount, are made at UMA’s sole discretion. UMA reserves the right to reject submissions and alter the terms and conditions of this program without notice. # Glossary ### UMA Ecosystem #### Optimistic Oracle The "Optimistic Oracle" (OO) allows contracts to quickly request and receive price information. Unlike mechanically restrictive price feed oracles, an optimistic oracle can serve any arbitrary data on-chain. #### DVM The “Data Verification Mechanism” (DVM) is the name of the oracle service provided by UMA. The DVM does not provide an on-chain price feed. Instead, it is only used to resolve disputes of liquidations and to settle synthetic token contracts upon expiration. ### Parameters of a Long Short Pair (LSP) smart contract: #### Financial Product Library (FPL) The financial product libraries are used to transform the value returned by the price identifier into a final settlement value. Financial product libraries can be applied to create different types of financial contracts and payout functions. Refer to [github](https://github.com/UMAprotocol/protocol/tree/master/packages/core/networks) for a list of deployed financial product libraries for each network. If your desired financial product library is not already deployed, refer [here](https://github.com/UMAprotocol/launch-emp#deploying-financial-product-libraries) for instructions on deploying and verifying your own financial product library contract. #### collateralPerPair The collateralPerPair parameter determines the amount of collateral required to mint each pair of long and short tokens. * Example: If a contract uses WETH as collateral and the collateralPerPair parameter is set to 0.25 on deployment, each long and short token that is minted would require 0.25 WETH as collateral. #### expiryPercentLong ExpiryPercentLong is used to determine the redemption rate between long and short tokens. ExpiryPercentLong is a number between 0 and 1, where 0 assigns all collateral to the short tokens and 1 assigns all collateral to the long tokens. ### UMA Product Types: #### Range Tokens Range tokens enable a DAO to use its native token as collateral to borrow funds. At maturity, if the debt is not paid, the range token holder is instead compensated with an amount of the collateral (the native token) using the settlement price of the native token to determine the number of tokens. This is similar to a tokenized convertible debt structure. Go [here](https://docs.umaproject.org/range-tokens/summary) to learn more about range tokens and how to deploy your own contract. #### Success Tokens Success tokens offer an alternative way for DAOs to diversify their treasury and sell tokens to investors in an incentive-aligned way. Success tokens are two financial products wrapped into one token: a set amount of a project token which is combined with a covered call option on that token backed by a set amount of the same token. Go [here](https://docs.umaproject.org/success-tokens/summary) to learn more about success tokens and how to create your own. #### KPI Options Key Performance Indicator (KPI) Options are synthetic tokens that will pay out more rewards if a project’s KPI reaches predetermined targets before a given expiry date. Every KPI Option holder has an incentive to improve that KPI because their option will be worth more. This is intended to align individual token holder interests with the collective interests of the protocol. Go [here](https://docs.umaproject.org/kpi-options/summary) to learn more about KPI options and how to create your own. # Links You can keep up to date with what is happening with Outcome across our various social media platforms and community resources: * [Discord](https://discord.com/channels/718590743446290492/971001643854352425) * [Medium](https://medium.com/outcomeprotocol) * [Twitter](https://twitter.com/0xOutcome) * [Discourse](https://discourse.umaproject.org/) * [UMAverse](https://projects.umaproject.org/)