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 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 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 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. The most applicable FPLs for KPI options might be:

  • BinaryOption to select Binary Options 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 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
PreviousSupported Payout FunctionsNextExamples

Last updated