diff --git a/docs/assets/asset_list.png b/docs/assets/asset_list.png new file mode 100644 index 000000000..342b349b8 Binary files /dev/null and b/docs/assets/asset_list.png differ diff --git a/docs/assets/createpool.png b/docs/assets/createpool.png new file mode 100644 index 000000000..e0d7dce49 Binary files /dev/null and b/docs/assets/createpool.png differ diff --git a/docs/assets/deploymentpreview.png b/docs/assets/deploymentpreview.png new file mode 100644 index 000000000..1ab101486 Binary files /dev/null and b/docs/assets/deploymentpreview.png differ diff --git a/docs/osmosis-core/modules/gov/README.md b/docs/osmosis-core/modules/gov/README.md index fc21bcd61..cebc2329b 100644 --- a/docs/osmosis-core/modules/gov/README.md +++ b/docs/osmosis-core/modules/gov/README.md @@ -31,15 +31,21 @@ The network parameters for the gov module are: ### The Governance Procedure -**Phase 0 - Submit a proposal along with an initial deposit** +**Phase 0 - Post your proposal draft on the Governance forums** + +Osmosis governance defined a requirement for waiting periods before going to chain to allow feedback and refinement on proposals in [Proposal 438](https://www.mintscan.io/osmosis/proposals/438). + +Post any drafts on the [Governance forum](https://gov.osmosis.zone/) as a first step. + +**Phase 1 - Submit a proposal along with an initial deposit** Users submits a proposal with an initial deposit. The proposal will then become "active" and enters the deposit period. -**Phase 1 - Deposit period** +**Phase 2 - Deposit period** During the deposit period, users can deposit and support an active proposal. Once the deposit of the proposal reaches the ```min_deposit```, it will enter the voting period. Otherwise, if the proposal is not successfully funded within ```max_deposit_period```, It will become inactive and **all the deposits will be burned**. -**Phase 2 - Voting period** +**Phase 3 - Voting period** During the voting period, staked (bonded) tokens will be able to participate in the voting process. Users can choose one of the following options: ```yes```, ```no```, ```no_with_veto``` and ```abstain```. @@ -64,46 +70,55 @@ Otherwise, the proposal will be accepted and changes will be implemented accordi Submit a proposal along with an initial deposit ``` -tx gov submit-proposal [flags] +osmosisd tx gov submit-proposal [flags] ``` -There are different types of proposal submission types, of them include `text`, `param-change`, `community-pool-spend`, `software-upgrade`, and `cancel-software-upgrade`. We will go over each of these submission types in detail now: +typical flags would be: +* `--gas=auto --gas-prices 0.0025uosmo --gas-adjustment 1.3` to auto-calculate gas required +* `--from WALLET_ADDRESS` to set the running wallet +* `--deposit=400000000uosmo` to provide the initial 400 OSMO (25% of total) deposit for putting a proposal on chain +There are different types of proposal submission types, including +* [`text`](https://docs.osmosis.zone/osmosis-core/modules/gov#submit-proposal-text) +* [`param-change`](https://docs.osmosis.zone/osmosis-core/modules/gov#submit-proposal-param-change) +* [`community-pool-spend`](https://docs.osmosis.zone/osmosis-core/modules/gov#submit-proposal-community-pool-spend) +* [`software-upgrade`](https://docs.osmosis.zone/osmosis-core/modules/gov#submit-proposal-software-upgrade) and [`cancel-software-upgrade`](https://docs.osmosis.zone/osmosis-core/modules/gov#submit-proposal-cancel-software-upgrade) +* [`update-pool-incentives`](https://docs.osmosis.zone/osmosis-core/modules/gov#submit-proposal-update-pool-incentives) +* [`set-superfluid-asset`](https://docs.osmosis.zone/osmosis-core/modules/gov#submit-proposal-set-superfluid-asset) and [`remove-superfluid-asset`](https://docs.osmosis.zone/osmosis-core/modules/gov#submit-proposal-community-pool-spend) +* [`wasm-store`](https://docs.osmosis.zone/osmosis-core/modules/gov#submit-proposal-wasm-store) +* [`update-unpool-whitelist`](https://docs.osmosis.zone/osmosis-core/modules/gov#submit-proposal-update-unpool-whitelist) + +We will go over each of these submission types in detail now: ### submit-proposal (text) -Submit a proposal in text form +Text proposals differ from other proposal submission types in that after it passes, no logic is automatically executed. This is good for proposing changes to Osmosis that are not linked to a specific daemon parameter. ```bash -tx gov submit-proposal --title --description --type="Text" --from --chain-id +osmosisd tx gov submit-proposal --type=text --title="" --description="" --from WALLET_ADDRESS --deposit=400000000uosmo [flags] ``` - -Text proposals differ from other proposal submission types in that after it passes, no logic is automatically executed. This is good for proposing changes to Osmosis that are not linked to a specific daemon parameter. - -::: details Example +**Example** Create a text signaling proposals to match external incentives for a `DOGE/OSMO` and `DOGE/ATOM` pair. ```bash -osmosisd tx gov submit-proposal --title="Match External Incentives for DOGE/OSMO and DOGE/ATOM pairs" --description="Input description" --type="Text" --from=WALLET_NAME --chain-id=CHAIN_ID +osmosisd tx gov submit-proposal --type=text --title="Match External Incentives for DOGE/OSMO and DOGE/ATOM pairs" --description="Input description" --from WALLET_ADDRESS --deposit=400000000uosmo --gas=auto --gas-prices 0.0025uosmo --gas-adjustment 1.3 ``` -::: - ### submit-proposal (param change) -Submit a proposal to modify network parameters during run time +Submit a proposal to modify network parameters during run time, ideally these should be tested on Testnet before proposing. -``` -tx gov submit-proposal param-change [proposal-file] --from --chain-id +```bash +osmosisd tx gov submit-proposal param-change [proposal-file] --from WALLET_ADDRESS [flags] ``` -::: details Example +**Example** Change the parameter MaxValidators (maximum number of validator) in the staking module: ```bash -osmosisd tx gov submit-proposal param-change proposal.json --from WALLET_NAME --chain-id CHAIN_ID +osmosisd tx gov submit-proposal param-change proposal.json --from WALLET_ADDRESS --gas=auto --gas-prices 0.0025uosmo --gas-adjustment 1.3 ``` The proposal.json file would look as follows: @@ -117,26 +132,25 @@ The proposal.json file would look as follows: "key": "MaxValidators", "value": 150 } - ] + ], + "deposit": "400000000uosmo" } ``` -::: - ### submit-proposal (community pool spend) -Submit a proposal and request funds from the community pool to support projects or other activities +Request funds from the community pool to support projects or other activities. ```bash -tx gov submit-proposal community-pool-spend [proposal-file] --from --chain-id +osmosisd tx gov submit-proposal community-pool-spend [proposal-file] --from WALLET_ADDRESS [flags] ``` -::: details Example +**Example** Submit a proposal to use community funds to fund a DAO: -``` -osmosisd tx gov submit-proposal community-pool-spend proposal.json --from WALLET_NAME --chain-id CHAIN_ID +```bash +osmosisd tx gov submit-proposal community-pool-spend proposal.json --from WALLET_ADDRESS --gas=auto --gas-prices 0.0025uosmo --gas-adjustment 1.3 ``` The proposal.json would look as follows: @@ -146,140 +160,152 @@ The proposal.json would look as follows: "title": "Osmosis DAO", "description": "Establish a DAO for Osmosis. Potentially add external links for more information or allow discussion", "recipient": "osmo1r9pjvsuahxwkxg8cnhacd6alkmxq330fl9pqqt", - "amount": [ - { - "denom": "uosmo", - "amount": "60000000000" - } - ] + "amount": "10000000000uosmo", + "deposit": "400000000uosmo" } ``` If passed, the requested community funds would be sent to the recipient address provided in the json file. -::: - ### submit-proposal (software upgrade) -Submit an upgrade proposal and suggest a software upgrade at a specific block height +Submit an upgrade proposal and suggest a software upgrade at a specific block height. -``` -tx gov submit-proposal software-upgrade [proposal-file] --from --chain-id +```bash +osmosisd tx gov submit-proposal software-upgrade [proposal-file] --from WALLET_ADDRESS [flags] ``` -::: details Example +**Example** -Update osmosis to V4: +Update Osmosis to V11: ```bash -osmosisd tx gov submit-proposal software-upgrade proposal.json --from WALLET_NAME --chain-id CHAIN_ID +osmosisd tx gov submit-proposal software-upgrade v11 --upgrade-height 5432450 --upgrade-info https://raw.githubusercontent.com/osmosis-labs/osmosis/main/networks/osmosis-1/upgrades/v11/mainnet/upgrade_11_binaries.json --title="Osmosis v11 Upgrade" --description="" --from WALLET_ADDRESS --gas=auto --gas-prices 0.0025uosmo --gas-adjustment 1.3 ``` -The proposal.json would look as follows: +### submit-proposal (cancel upgrade) -```json -{ - "name": "v4", - "time": "0001-01-01T00:00:00Z", - "height": "1314500", - "info": "https://raw.githubusercontent.com/osmosis-labs/networks/main/osmosis-1/upgrades/v4/mainnet/upgrade_4_binaries.json", -}, +Cancel the planned software upgrade before the upgrade height is reached. + +```bash +osmosisd tx gov submit-proposal cancel-software-upgrade --title="" --description"" --from WALLET_ADDRESS --gas=auto --gas-prices 0.0025uosmo --gas-adjustment 1.3 ``` -::: +The software upgrade does not have to be specified, as this will cancel the currently active software upgrade proposal. -### submit-proposal (cancel upgrade) -Cancel the planned software upgrade before the upgrade height is reached +### submit-proposal (update pool incentives) + +Update the weight of specified pool gauges in regards to their share of incentives. +```bash +osmosisd tx gov submit-proposal update-pool-incentives [gaugeIDs] [weights] --from WALLET_ADDRESS --gas=auto --gas-prices 0.0025uosmo --gas-adjustment 1.3 ``` -tx gov submit-proposal cancel-software-upgrade --title= --description + +**Example** + +Update the pool incentives weights for `gauge_id` 0 and 1 to be 5000 and 20,000. + +```bash +osmosisd tx gov submit-proposal update-pool-incentives 0,1 5000,20000 --from WALLET_ADDRESS --chain-id CHAIN_ID ``` -The software upgrade does not have to be specified, as this will cancel the currently active software upgrade proposal. -::: details Example +### submit-proposal (set superfluid asset) -If the above software upgrade proposal in the previous example was active, to propose its cancellation, run the following: +Enable a pool as eligible for Superfluid Staking, allowing a portion of the OSMO within the pool to be staked - providing additional security for Osmosis as well as staking rewards and voting power for Liquidity Providers ```bash -osmosisd tx gov submit-proposal cancel-software-upgrade --title="cancel v4" --description="cancel v4 upgrade" --from=WALLET_NAME --chain-id=CHAIN_ID +osmosisd tx gov submit-proposal set-superfluid-assets-proposal --superfluid-assets= [GAMM] --from WALLET_ADDRESS --gas=auto --gas-prices 0.0025uosmo --gas-adjustment 1.3 ``` -::: +**Example** -### submit-proposal (update pool incentives) +Add Superfluid Staking to Pool 831. -Update the weight of specified pool gauges in regards to their share of incentives +```bash +osmosisd tx gov submit-proposal set-superfluid-assets-proposal --superfluid-assets="gamm/pool/831" --from WALLET_ADDRESS --gas=auto --gas-prices 0.0025uosmo --gas-adjustment 1.3 +``` + +### submit-proposal (remove superfluid asset) +Disable a pool as eligible for Superfluid Staking, this prevents OSMO in a pool from being able to also be staked. + +```bash +osmosisd tx gov submit-proposal remove-superfluid-assets-proposal --superfluid-assets= [GAMM] --from WALLET_ADDRESS --gas=auto --gas-prices 0.0025uosmo --gas-adjustment 1.3 ``` -tx gov submit-proposal update-pool-incentives [proposal-file] --from --chain-id + +**Example** + +Remove Superfluid Staking from Pool 831. + +```bash +osmosisd tx gov submit-proposal remove-superfluid-assets-proposal --superfluid-assets="gamm/pool/831" --from WALLET_ADDRESS --gas=auto --gas-prices 0.0025uosmo --gas-adjustment 1.3 ``` -::: details Example +### submit-proposal (wasm-store) -Update the pool incentives for `gauge_id` 0 and 1: +Upload a CosmWasm contract to Osmosis for subsequent instantiation. ```bash -osmosisd tx gov submit-proposal update-pool-incentives proposal.json --from WALLET_NAME --chain-id CHAIN_ID +osmosisd tx gov wasm-store [contract.wasm] --title="" --description="" --code-hash [checksum] --code-source-url [source] --builder [builder] --from WALLET_ADDRESS --gas=auto --gas-prices 0.0025uosmo --gas-adjustment 1.3 ``` -The proposal.json would look as follows: +**Example** +Upload Crosschain Swaps contract. -```json -{ - "title": "Pool Incentive Adjustment", - "description": "Adjust pool incentives", - "records": [ - { - "gauge_id": "0", - "weight": "100000" - }, - { - "gauge_id": "1", - "weight": "1766249" - }, - ] -} +```bash +osmosisd tx gov submit-proposal wasm-store crosschain_swaps.wasm --title="Upload Crosschain Swaps contract" --description="" --code-hash e7cfd4ec2cf594de9d15863c6e324025045de39236186c03483af7c9e06d4949 --code-source-url "https://github.com/osmosis-labs/osmosis/raw/v15.x/tests/ibc-hooks/bytecode/crosschain_swaps.wasm" --builder "cosmwasm/workspace-optimizer:0.12.10" --from WALLET_ADDRESS --gas=auto --gas-prices 0.0025uosmo --gas-adjustment 1.3 +``` + +### submit-proposal (update unpool whitelist) + +Enable immediate unpooling on a pool, allowing users to choose to freeze their impermanent loss during the unbonding period in the event of unexpected severe conditions. + +```bash +osmosisd tx gov submit-proposal update-unpool-whitelist --pool-ids [PoolIDs] --title="" --description="" --from WALLET_ADDRESS --gas=auto --gas-prices 0.0025uosmo --gas-adjustment 1.3 ``` -::: +**Example** + +Allow immediate unpooling of pools 1, 2 and 3. + +```bash +osmosisd tx gov submit-proposal update-unpool-whitelist --pool-ids "1, 2, 3" --title="Allow Immediate Unpooling of Pools 1, 2 and 3" --description="" --from WALLET_ADDRESS --gas=auto --gas-prices 0.0025uosmo --gas-adjustment 1.3 +``` ### deposit Deposit tokens for an active proposal -``` -tx gov deposit [proposal-id] [deposit] --from --chain-id +```bash +osmosisd tx gov deposit [proposal-id] [deposit] --from WALLET_ADDRESS --gas=auto --gas-prices 0.0025uosmo --gas-adjustment 1.3 ``` -::: details Example +**Example** -If proposal number 12 is in the deposit period and you would like to help bring it to a vote, you could deposit 500 OSMO to that proposal as follows: +If proposal number 12 is in the deposit period and you would like to help bring it to a vote, you could deposit 1200 OSMO to that proposal as follows: ```bash -osmosisd tx gov deposit 12 500000000uosmo --from WALLET_NAME --chain-id CHAIN_ID +osmosisd tx gov deposit 12 1200000000uosmo --from WALLET_ADDRESS --gas=auto --gas-prices 0.0025uosmo --gas-adjustment 1.3 ``` -::: - ### vote Vote for an active proposal -``` -tx gov vote [proposal-id] [option] --from --chain-id +```bash +osmosisd tx gov vote [proposal-id] [option] --from WALLET_ADDRESS --gas=auto --gas-prices 0.0025uosmo --gas-adjustment 1.3 ``` Valid value of ```option``` field is ```yes```, ```no```, ```no_with_veto``` and ```abstain```. -::: details Example +**Example** To vote yes for proposal 12: ```bash -osmosisd tx gov vote 12 yes --from WALLET_NAME --chain-id CHAIN_ID +osmosisd tx gov vote 12 yes --from WALLET_ADDRESS --gas=auto --gas-prices 0.0025uosmo --gas-adjustment 1.3 ``` -::: ## Queries @@ -288,11 +314,11 @@ osmosisd tx gov vote 12 yes --from WALLET_NAME --chain-id CHAIN_ID Query all proposals -``` -query gov proposals [proposal-id] +```bash +osmosisd query gov proposals [proposal-id] ``` -::: details Example +**Example** We can list all proposals in json format by: @@ -347,36 +373,34 @@ An example of the output: ``` In the above example, there is only one proposal with ```"proposal_id": "1"```, with the title: ```"Staking Param Change"``` that change the ```MaxValidators``` parameter of the ```staking``` module to ```150```. We can also see that the status of the proposal is ```"PROPOSAL_STATUS_PASSED"```, which means that this proposal has been passed. In reality, the output would be much longer with all proposals listed. -::: ### proposal Query details of a single proposal -``` -query gov proposal [proposal-id] +```bash +osmosisd query gov proposal [proposal-id] ``` -::: details Example +**Example** To check proposal 13 and list in json format: ```bash osmosisd query gov proposal 13 -o json | jq ``` -::: ### tally -Get the tally of a proposal vote +Get the tally of a proposal vote that shows how the community voted on a specific proposal. -``` +```bash query gov tally [proposal-id] ``` -::: details Example +**Example** To check the tally of proposal 13 and output in json: @@ -395,19 +419,15 @@ Which outputs: } ``` -This shows how the community voted on a specific proposal. -::: - - ### params Query the current gov parameters -``` -query gov params +```bash +osmosisd query gov params ``` -::: details Example +**Example** To check the current gov parameters and output in json: @@ -420,27 +440,36 @@ Which outputs: ```json { "voting_params": { - "voting_period": "259200000000000" + "voting_period": "432000000000000", + "proposal_voting_periods": null, + "expedited_voting_period": "86400000000000" }, "tally_params": { "quorum": "0.200000000000000000", "threshold": "0.500000000000000000", - "veto_threshold": "0.334000000000000000" + "veto_threshold": "0.334000000000000000", + "expedited_threshold": "0.666666666666666667" }, "deposit_params": { "min_deposit": [ { "denom": "uosmo", - "amount": "500000000" + "amount": "1600000000" + } + ], + "max_deposit_period": "1209600000000000", + "min_expedited_deposit": [ + { + "denom": "uosmo", + "amount": "5000000000" } ], - "max_deposit_period": "1209600000000000" + "min_initial_deposit_ratio": "0.250000000000000000" } } ``` See the network parameters section for a detailed explanation of the above parameters. -::: ## Appendix @@ -460,11 +489,11 @@ The following tables show overall effects on different configurations of the ``` string (time ns) string (time ns) Higher -Larger window for calculating the downtime +More collateral required to bring a proposal to vote More time to solicit funds to reach min_deposit Longer voting period Lower -Smaller window for calculating the downtime +Less collateral required to bring a proposal to vote Less time to solicit funds to reach min_deposit Shorter voting period Constraints @@ -472,7 +501,7 @@ The following tables show overall effects on different configurations of the ``` Value has to be positive Value has to be positive Current configuration -500000000 (500 OSMO) 1209600000000000 (2 weeks) 259200000000000 (3 days) +1600000000 (1600 OSMO) 1209600000000000 (2 weeks) 432000000000000 (5 days) @@ -499,4 +528,30 @@ The following tables show overall effects on different configurations of the ``` +
0.2 (20%) 0.5 (50%) 0.334 (33.4%)
+ + + + + + + + + + + + + + + + + + + + + + + + +
min_expedited_depositexpedited_thresholdexpedited_voting_period
Typestring (time ns)string (dec)string (dec)
HigherMore collateral required to bring an expedited proposal to voteEasier for an expedited proposal to be passedLonger expedited voting period
LowerLess collateral required to bring an expedited proposal to voteHarder for an expedited proposal to be passedShorter expedited voting period
ConstraintsValue has to be a positive integerValue has to be less or equal to 1Value has to be positive
Current configuration5000000000 (5000 OSMO)0.666666666666666667 (66.6%)86400000000000 (1 day)
\ No newline at end of file diff --git a/docs/osmosis-core/modules/incentives/README.md b/docs/osmosis-core/modules/incentives/README.md index 156b2c5b2..64dffcf4b 100644 --- a/docs/osmosis-core/modules/incentives/README.md +++ b/docs/osmosis-core/modules/incentives/README.md @@ -164,6 +164,55 @@ type MsgAddToGauge struct { - Modify the `Gauge` record by adding `msg.Rewards` - Transfer the tokens from the `Owner` to incentives `ModuleAccount`. +## Transactions + +### create-gauge + +Create a gauge to distribute rewards to users + +```sh +osmosisd tx incentives create-gauge [lockup_denom] [reward] [flags] +``` + +**Example 1** + +I want to make incentives for LP tokens of pool 3, namely gamm/pool/3 that have been locked up for at least 1 day. +I want to reward 100 AKT to this pool over 2 days (2 epochs). (50 rewarded on each day) +I want the rewards to start dispersing on 21 December 2021 (1640081402 UNIX time) + +```bash +osmosisd tx incentives create-gauge gamm/pool/3 10000ibc/1480B8FD20AD5FCAE81EA87584D269547DD4D436843C1D20F15E00EB64743EF4 \ +--duration 24h --start-time 1640081402 --epochs 2 --from WALLET_NAME --chain-id osmosis-1 +``` + +**Example 2** + +I want to make incentives for ATOM (ibc/27394FB092D2ECCD56123C74F36E4C1F926001CEADA9CA97EA622B25F41E5EB2) that have been locked up for at least 1 week (168h). +I want to reward 1000 JUNO (ibc/46B44899322F3CD854D2D46DEEF881958467CDD4B3B10086DA49296BBED94BED) to ATOM holders perpetually (perpetually meaning I must add more tokens to this gauge myself every epoch). I want the reward to start dispersing immediately. + +```bash +osmosisd tx incentives create-gauge ibc/27394FB092D2ECCD56123C74F36E4C1F926001CEADA9CA97EA622B25F41E5EB2 \ +1000000000ibc/46B44899322F3CD854D2D46DEEF881958467CDD4B3B10086DA49296BBED94BED --perpetual --duration 168h \ +--from WALLET_NAME --chain-id osmosis-1 +``` + +### add-to-gauge + +Add coins to a gauge previously created to distribute more rewards to users + +```sh +osmosisd tx incentives add-to-gauge [gauge_id] [rewards] [flags] +``` + +**Example** + +I want to refill the gauge with 500 JUNO to a previously created gauge (gauge ID 1914) after the distribution. + +```bash +osmosisd tx incentives add-to-gauge 1914 500000000ibc/46B44899322F3CD854D2D46DEEF881958467CDD4B3B10086DA49296BBED94BED \ +--from WALLET_NAME --chain-id osmosis-1 +``` + ## Events The incentives module emits the following events: @@ -236,62 +285,6 @@ epochs, the identifier is required to check if distribution should be done at `AfterEpochEnd` hook - -## Transactions - -### create-gauge - -Create a gauge to distribute rewards to users - -```sh -osmosisd tx incentives create-gauge [lockup_denom] [reward] [flags] -``` - -::: details Example 1 - -I want to make incentives for LP tokens of pool 3, namely gamm/pool/3 that have been locked up for at least 1 day. -I want to reward 100 AKT to this pool over 2 days (2 epochs). (50 rewarded on each day) -I want the rewards to start dispersing on 21 December 2021 (1640081402 UNIX time) - -```bash -osmosisd tx incentives create-gauge gamm/pool/3 10000ibc/1480B8FD20AD5FCAE81EA87584D269547DD4D436843C1D20F15E00EB64743EF4 \ ---duration 24h --start-time 1640081402 --epochs 2 --from WALLET_NAME --chain-id osmosis-1 -``` - -::: - -::: details Example 2 - -I want to make incentives for ATOM (ibc/27394FB092D2ECCD56123C74F36E4C1F926001CEADA9CA97EA622B25F41E5EB2) that have been locked up for at least 1 week (168h). -I want to reward 1000 JUNO (ibc/46B44899322F3CD854D2D46DEEF881958467CDD4B3B10086DA49296BBED94BED) to ATOM holders perpetually (perpetually meaning I must add more tokens to this gauge myself every epoch). I want the reward to start dispersing immediately. - -```bash -osmosisd tx incentives create-gauge ibc/27394FB092D2ECCD56123C74F36E4C1F926001CEADA9CA97EA622B25F41E5EB2 \ -1000000000ibc/46B44899322F3CD854D2D46DEEF881958467CDD4B3B10086DA49296BBED94BED --perpetual --duration 168h \ ---from WALLET_NAME --chain-id osmosis-1 -``` - -::: - -### add-to-gauge - -Add coins to a gauge previously created to distribute more rewards to users - -```sh -osmosisd tx incentives add-to-gauge [gauge_id] [rewards] [flags] -``` - -::: details Example - -I want to refill the gauge with 500 JUNO to a previously created gauge (gauge ID 1914) after the distribution. - -```bash -osmosisd tx incentives add-to-gauge 1914 500000000ibc/46B44899322F3CD854D2D46DEEF881958467CDD4B3B10086DA49296BBED94BED \ ---from WALLET_NAME --chain-id osmosis-1 -``` - -::: - ## Queries In this section we describe the queries required on grpc server. @@ -326,7 +319,7 @@ Query active gauges osmosisd query incentives active-gauges [flags] ``` -::: details Example +**Example** ```bash osmosisd query incentives active-gauges @@ -364,9 +357,6 @@ pagination: total: "0" ... ``` - -::: - ### active-gauges-per-denom Query active gauges per denom @@ -375,7 +365,7 @@ Query active gauges per denom osmosisd query incentives active-gauges-per-denom [denom] [flags] ``` -::: details Example +**Example** Query all active gauges distributing incentives to holders of gamm/pool/341 @@ -416,8 +406,6 @@ pagination: ... ``` -::: - ### distributed-coins Query coins distributed so far @@ -426,7 +414,7 @@ Query coins distributed so far osmosisd query incentives distributed-coins [flags] ``` -::: details Example +**Example** ```bash osmosisd query incentives distributed-coins @@ -466,8 +454,6 @@ coins: denom: uosmo ``` -::: - ### gauge-by-id Query gauge by id @@ -476,7 +462,7 @@ Query gauge by id osmosisd query incentives gauge-by-id [id] [flags] ``` -::: details Example +**Example** Query the incentive distribution for gauge ID 1: @@ -504,8 +490,6 @@ gauge: start_time: "2021-06-19T04:30:19.082462364Z" ``` -::: - ### gauges Query available gauges @@ -514,7 +498,7 @@ Query available gauges osmosisd query incentives gauges [flags] ``` -::: details Example +**Example** Query ALL gauges (by default the limit is 100, so here I will define a much larger number to output all gauges) @@ -559,8 +543,6 @@ pagination: ... ``` -::: - ### rewards-estimation Query rewards estimation @@ -575,7 +557,7 @@ Query coins that is going to be distributed osmosisd query incentives to-distribute-coins [flags] ``` -::: details Example +**Example** ```bash osmosisd query incentives to-distribute-coins @@ -611,8 +593,6 @@ coins: denom: uosmo ``` -::: - ### upcoming-gauges Query scheduled gauges (gauges whose `start_time` has not yet occurred) @@ -621,7 +601,7 @@ Query scheduled gauges (gauges whose `start_time` has not yet occurred) osmosisd query incentives upcoming-gauges [flags] ``` -::: details Example +**Example** ```bash osmosisd query incentives upcoming-gauges @@ -645,6 +625,4 @@ Using this command, we will see the gauge we created earlier, among all other up num_epochs_paid_over: "2" start_time: "2021-12-21T10:10:02Z" ... -``` - -::: +``` \ No newline at end of file diff --git a/docs/overview/educate/_category_.json b/docs/overview/educate/_category_.json new file mode 100644 index 000000000..cff9b4b23 --- /dev/null +++ b/docs/overview/educate/_category_.json @@ -0,0 +1,14 @@ +{ + "position": 4, + "label": "Overview", + "collapsible": true, + "collapsed": true, + "className": "red", + "link": { + + "title": "Overview" + }, + "customProps": { + "description": "The guides on this page will give a grounding on Osmosis functionality." + } +} \ No newline at end of file diff --git a/docs/overview/educate/getting-started.md b/docs/overview/educate/getting-started.md new file mode 100644 index 000000000..12ac8593e --- /dev/null +++ b/docs/overview/educate/getting-started.md @@ -0,0 +1,101 @@ +--- +sidebar_position: 3 +--- +# Getting Started +## Set up a Wallet +Before opening the Osmosis AMM App, make sure to install the [Keplr Wallet](wallets/keplr/README.md). + +## Open the App +Go to [https://app.osmosis.zone/](https://app.osmosis.zone/) + +![](../../assets/started-trade-page.png) + +## Connect Wallet +![](../../assets/connect-wallet.png) + +Click Approve. This confirms that you are connecting to the app.osmosis.zone and the chain osmosis-1. + +![](../../assets/keplr-connect.png) + + +Always make sure you are connected to app.osmosis.zone name and network (osmosis-1) + + +## Deposit Funds + +![](../../assets/started-assets-page.png) + +Click Assets. Then click on the deposit link next to the asset name. For this example we are clicking the ATOM deposit link. + +Accept connection to cosmoshub-4 + + ![](../../assets/connect-cosmoshub.png) + + +Once connected, select how much you would like to deposit, then click the deposit button + +[](../../assets/deposit-dialog.png) + +Approve the transaction + +![](../../assets/approve-tramsaction.png) + +Once the transaction is completed a series if confirmations notifications will be displayed including the IBC confirmation. + +![](../../assets/confirm-2.png) + +## Swapping Tokens + +Trading tokens is as easy as clicking on the Trade link and then selecting the pair you would like to trade. Check out the [glossary](terminology.md) to learn about terms such as [slipage](terminology.md#slippage). +![](../../assets/swap.png) + + +## Adding Liquidity to a Pool +Select a pool from the [Pools](https://app.osmosis.zone/pools) page. +![](../../assets/add-liquidity.png) + +Then click Add/Remove Liquidity +![](../../assets/add-remove-liquidity.png) + +Input a quantity of one of the assets. The quantity of the other asset(s) will auto-complete. (Pools require assets to be deposited in pre-determined weights.) + +:::warning Warning +Please note that simply adding liquidity will not give you rewards. In order to get rewards you must bond LP tokens. +::: + +![](../../assets/add-liquidity.png) + +To remove liquidity, input the percentage amount to withdraw. + +![](../../assets/remove-liquidity.png) + +Incentivized pools receive OSMO liquidity mining rewards. Rewards are distributed to bonded LP tokens in these pools that meeting the bonding length criteria. + +Swap fees are fees charged for making a swap in an LP pool. The fee is paid by the trader in the form of the input asset. Pool creators specify the swap fee when establishing the pool. The total fee for a particular trade is calculated as percentage of swap size. Fees are added to the pool, effectively resulting in pro-rata distribution to LPs proportional to their share of the total pool. + +## Bonding LP Tokens + Start Earning! Users can choose to bond their LP tokens after depositing liquidity. LP tokens remain bonded for a length of their time of their choosing. Bonded LP tokens are eligible for liquidity mining rewards if they meet the minimum bonding length requirement. + +Click Start Earning and choose a bonding length. + +![](../../assets/start-earning.png) + + + +### Internal Incentives + +### External Incentives + +Osmosis not only allows the community to add incentives to gauges. Anyone can deposit tokens into a gauge to be distributed. This feature allows outside parties to augment Osmosis’ own liquidity incentive program. + +For example, there may be an ATOM< >FOOCOIN pool that has a one-day gauge incentivized by governance OSMO rewards. However, the Foo Foundation may also choose to add additional incentives to the one-day gauge or even add incentives to a new gauge (such as one-week gauge). + +These external incentive providers can also set up long-lasting incentive programs that distribute rewards over an extended time period. For example, the Foo Foundation can deposit 30,000 Foocoins to be distributed over a one-month liquidity program. The program will automatically distribute 1000 Foocoins per day to the gauge. + +## Go Superfluid! + +## Unbonding LP Tokens +When a user wants to stop bonding an LP token, they submit a transaction that begins the unbonding period. After the end of the timer, they can submit another transaction to withdraw the tokens. + + + diff --git a/docs/overview/educate/index.mdx b/docs/overview/educate/index.mdx new file mode 100644 index 000000000..ae0703cd5 --- /dev/null +++ b/docs/overview/educate/index.mdx @@ -0,0 +1,12 @@ +--- +title: Overview +sidebar_position: 0 +--- +import DocCardList from '@theme/DocCardList'; + +# Introduction + +The guides on this page will explain background information on Osmosis. + + + diff --git a/docs/overview/educate/osmo.md b/docs/overview/educate/osmo.md new file mode 100644 index 000000000..4a3dc4335 --- /dev/null +++ b/docs/overview/educate/osmo.md @@ -0,0 +1,36 @@ +--- +sidebar_position: 2 +--- +# The OSMO Token + +The OSMO token is a governance token that allows staked token holders to decide the future of the protocol, including every implementation detail. OSMO is currently used for the following (although governance is free to add or remove these functions): + +## Voting +Governance is the critical component of how Osmosis evolves. Active stakeholders of the network will be responsible for proposing, vetting, and passing protocol upgrades. + +The pools eligible for liquidity rewards are selected by OSMO governance participants, allowing the stakeholders to formulate an incentivization strategy that best aligns with the long-term interests of the protocol. + +## Transaction Fees +Transaction fees are paid by any user to post a transaction on the chain. The fee amount is determined by the computation and storage costs of the transaction. Minimum gas costs are determined by the proposer of a block in which the transaction is included. This transaction fee is distributed to OSMO stakers on the network. +Validators can choose which assets to accept for fees in the blocks that they propose, but all accepted assets are converted to OSMO before distribution. + +## ProtoRev +The ProtoRev module mints and burns the OSMO token in order to perform priviledged arbitrage transactions on chain to ensure prices are balanced across liquidity sources on chain. +No use for this revenue has currently been decided, but will be allocated by governance in the future. +Protocol Revenue collected so far is currently stored in the [module address](https://www.mintscan.io/osmosis/account/osmo17qdmjdumw4xawam4g46gtwzle5rd4zwyfqvvza) + +## Taker Fees +Osmosis charges a small taker fee on all trades with a 0.1% default. +Several routes have reductions or exemptions and these are managed by the [Protocol Fee Controller](https://daodao.zone/dao/osmo162wk8qc3w5s9hfs8dm76wrqnk6fjmsez2t4kk6zyugmrlzgds8sqfesmlm) subDAO. +Taker fees are collected in the Quote asset involved in the trade. All OSMO collected is distributed to stakers. Non-OSMO collected is divided, with 33% going to the Community Pool and 67% being converted to OSMO before being distributed to stakers. + +## Superfluid Staking +The OSMO token is also minted and burned in the context of Superfluid Staking. As a Osmosis-specific feature, Superfluid Staking provides the consensus layer more security with a sort of "Proof of Useful Stake". Each person gets an amount of OSMO representative of the value of their share of liquidity pool tokens staked and delegated to validators, resulting in the security guarantee of the consensus layer to also be based on GAMM LP shares. This is available in pools that contain OSMO in the pairing and have had this feature enabled by governance. + +Further details can be seen in the [Superfluid module specifications](/osmosis-core/modules/superfluid/) + +## Other Fees +The OSMO token is required as fees for several tasks on chain to prevent spam and encourage considered usage of features. All fees paid go to the Community Pool. +Creating a pool: 1000 OSMO +Adding External Incentives to a pool: 50 OSMO +Topping up External Incentives on an existing stream: 25 OSMO \ No newline at end of file diff --git a/docs/overview/README.md b/docs/overview/educate/osmosis.md old mode 100755 new mode 100644 similarity index 67% rename from docs/overview/README.md rename to docs/overview/educate/osmosis.md index 493a28206..e643b7607 --- a/docs/overview/README.md +++ b/docs/overview/educate/osmosis.md @@ -1,36 +1,27 @@ --- sidebar_position: 1 --- -# Introduction - -## What is Osmosis? +# What is Osmosis? Osmosis is the premier cross-chain DeFi hub. As the liquidity center and primary trading venue of Cosmos – the open, emergent ecosystem of sovereign Layer 1s connected with the [Inter-Blockchain Communication protocol](https://ibcprotocol.org/) (IBC) – it is the access point for the wide world of appchains, the gateway to the interchain. As IBC continues to explode – with more than 50 blockchains connected and dozens more in development, including [dYdX chain](https://dydx.exchange/blog/dydx-chain), and with teams working to enable IBC on [Avalanche](https://www.landslide.network/), [Polkadot](https://docs.composable.finance/products/centauri-overview/), [NEAR](https://medium.com/composable-finance/near-foundation-issues-grant-to-composable-for-extending-ibc-to-near-via-the-centauri-bridge-e1d6c291ffb8), and others, potentially even [Ethereum](https://ethresear.ch/t/bringing-ibc-to-ethereum-using-zk-snarks/13634) – Osmosis will be there to welcome new users, developers, and protocols to the Internet of Blockchains. -![](../assets/welcome.png) +![](../../assets/welcome.png) -The [Osmosis Ecosystem](https://osmosis.zone/ecosystem) is a suite of premier, DAO-gated dApps that are tightly integrated into the Osmosis AMMs and IBC routing capabilities. Most recently, [Mars Protocol](https://marsprotocol.io/) launched its lending and credit protocol on Osmosis, and dozens of other developer teams are building index tokens, options, perps, stops and limit orders, automated trading, yield vaults, NFTs, and more. +The [Osmosis Ecosystem](https://osmosis.zone/ecosystem) is a suite of premier, DAO-gated dApps that are tightly integrated into the Osmosis AMMs and IBC routing capabilities. Dozens of developer teams are building index tokens, options, perps, stops and limit orders, automated trading, yield vaults, NFTs, and more. With new apps and features like stableswap, concentrated liquidity, rate-limiting, in-protocol MEV capture, and more going live all the time, Osmosis is continuing to expand its moat as the only full-service, cross-chain exchange and DeFi hub, one that rivals the smooth user experience of a CEX without compromising on the benefits of decentralized finance – self-custody, trust-minimized transactions, direct on-chain access, and privacy. -### Why Osmosis? +# Why Osmosis? -### On customizability of liquidity pools +## On customizability of liquidity pools Most major AMMs limit the changeable parameters of liquidity pools. For example, Uniswap only allows the creation of a two-token pool of equal ratio with the swap fee of 0.3%. The simplicity of Uniswap protocol allowed quick onboarding of the average user that previously had little to no experience in market making. However, as the DeFi market size grows and market participants such as arbitrageurs and liquidity providers mature, the need for liquidity pools to react to market conditions becomes apparent. The optimal swap fee for a AMM trade may depend on various factors such as block times, slippage, transaction fee, market volatility and more. There is no one-size-fits-all solution as the mix of characteristics of blockchain protocol, tokens in the liquidity pool, market conditions, and others can change the optimal strategy for the liquidity providers and the market makers to carry out. The tools Osmosis provides allow the market participants to self-identify opportunities and allow them to react by adjusting the various parameters. An optimal equilibrium between fee and liquidity can be reached through autonomous experiments and iterations, rather than setting a centrally planned 'most acceptable compromise' value. This extends the addressable market for AMMs and bonding curves beyond simple token swaps, as a limitation on the customizability of liquidity pools may have been the inhibiting factor for more experimental use-cases of AMMs. -### Self-governing liquidity pools -As important as the ability to change the parameters of a liquidity pool is, the feature would mean very little without a method to coordinate a decision amongst the stakeholders. The pool governance feature of Osmosis allows a diverse spectrum of liquidity pools with risk tolerance and strategies to not only exist, but evolve. - -In Osmosis, the liquidity pool shares are not only used to calculate the fractional ownership of a liquidity pool, but also the right to participate in the strategic decision making of the liquidity pool as well. To incentivize long-term liquidity commitment, shares must be locked up for an extended period. Longer term commitments are awarded by additional voting power / additional liquidity mining revenue. The long-term liquidity commitment by the liquidity providers prevent the impact of potential vampire attacks, where ownership of the shares are delegated and potentially used to migrate liquidity to an external AMM. This provides equity of power amongst liquidity providers, where those with greater skin-in-the-game are given their rightful power to steer the strategic direction of its pool in proportion to the risk they are taking with their assets. - -As AMMs mostly guarantee a level of constant total value output, those who may disagree with the changes made to the pool are able to withdraw their funds with little to no loss of their principles. As Osmosis expects the market to self-discover the optimal value of each adjustable parameter, if a significant dissenting opinion exists–they are able to start a competing liquidity pool with their own strategy. - -### AMM as serviced infrastructure +## AMM as serviced infrastructure The number and complexity of decentralized financial products are consistently increasing. Instruments such as pegged assets, derivatives, options, and tokenized leveraged positions each have their own characteristics that produce optimal market efficiency when paired with the correct bonding curve. That being said, the traditional notion of AMMs have evolved around putting the AMM first, and the financial product being traded second. As AMMs substantially increase the market accessibility for these instruments, assets with diverse characteristics either had to: diff --git a/docs/overview/terminology.md b/docs/overview/educate/terminology.md similarity index 99% rename from docs/overview/terminology.md rename to docs/overview/educate/terminology.md index 177016d42..9762ec73f 100644 --- a/docs/overview/terminology.md +++ b/docs/overview/educate/terminology.md @@ -1,12 +1,14 @@ -# Glossary +--- +sidebar_position: 5 +--- +# Glossary Use this glossary to learn about terms used in Osmosis and the Cosmos ecosystem. ## Active set -The top 150 -validators that participate in consensus and receive rewards. +The top 150 validators that participate in consensus and receive rewards. ## Air drops diff --git a/docs/overview/getting-started.md b/docs/overview/getting-started.md deleted file mode 100644 index ff5adace9..000000000 --- a/docs/overview/getting-started.md +++ /dev/null @@ -1,171 +0,0 @@ ---- -sidebar_position: 2 ---- -# Getting Started -Before opening the Osmosis AMM App, make sure to install the [Keplr Wallet](wallets/keplr/README.md). - -## Open the App -Go to [https://app.osmosis.zone/](https://app.osmosis.zone/) - -![](../assets/started-trade-page.png) - -## Connect Wallet -![](../assets/connect-wallet.png) - -Click Approve. This confirms that you are connecting to the app.osmosis.zone and the chain osmosis-1. - -![](../assets/keplr-connect.png) - -::: danger -Always make sure you are connected to app.osmosis.zone name and network (osmosis-1) -::: - -## Deposit Funds - -![](../assets/started-assets-page.png) - -Click Assets. Then click on the deposit link next to the asset name. For this example we are clicking the ATOM deposit link. - -Accept connection to cosmoshub-4 - - ![](../assets/connect-cosmoshub.png) - - -Once connected, select how much you would like to deposit, then click the deposit button - -[](../assets/deposit-dialog.png) - -Approve the transaction - -![](../assets/approve-tramsaction.png) - -Once the transaction is completed a series if confirmations notifications will be displayed including the IBC confirmation. - -![](../assets/confirm-2.png) - -## Swapping Tokens - -Trading tokens is as easy as clicking on the Trade link and then selecting the pair you would like to trade. Check out the [glossary](terminology.md) to learn about terms such as [slipage](terminology.md#slippage). -![](../assets/swap.png) - - -# Adding Liquidity to a Pool -Select a pool from the [Pools](https://app.osmosis.zone/pools) page. -![](../assets/add-liquidity.png) - -Then click Add/Remove Liquidity -![](../assets/add-remove-liquidity.png) - -Input a quantity of one of the assets. The quantity of the other asset(s) will auto-complete. (Pools require assets to be deposited in pre-determined weights.) - -:::warning Warning -Please note that simply adding liquidity will not give you rewards. In order to get rewards you must bond LP tokens. -::: - -![](../assets/add-liquidity.png) - -To remove liquidity, input the percentage amount to withdraw. - -![](../assets/remove-liquidity.png) - -Incentivized pools receive OSMO liquidity mining rewards. Rewards are distributed to bonded LP tokens in these pools that meeting the bonding length criteria. - -## Bonding LP Tokens - Start Earning! Users can choose to bond their LP tokens after depositing liquidity. LP tokens remain bonded for a length of their time of their choosing. Bonded LP tokens are eligible for liquidity mining rewards if they meet the minimum bonding length requirement. - -Click Start Earning and choose a bonding length. - -![](../assets/start-earning.png) - -When a user wants to stop bonding an LP token, they submit a transaction that begins the unbonding period. After the end of the timer, they can submit another transaction to withdraw the tokens. - - - - -## Create a New Pool - -Creating pools in Osmosis is permissionless, meaning any user can create a pool with two or more supported assets. -Go to Pools > Create a Pool. Select from your wallet the assets that will comprise the pool. Choose a weight for each asset. - -![](../assets/creating-pool.png) - -Choose a quantity of each asset to deposit into the pool. - -Input a swap fee for the pool. (An explanation of swap fees can be found [here](terminology.md#fees).) - -Click Create a Pool and voilà! The pool is launched. The parameters chosen when creating the pool (token weights, swap fees) cannot be changed later. - - - - ## Liquidity Bootstrapping Pools - -Osmosis offers a convenient design for Liquidity Bootstrapping Pools (LBPs), a special type of AMM designed for token sales. New protocols can use Osmosis’ LBP feature to distribute tokens and achieve initial price discovery. - -LBPs differ from other liquidity pools in terms of the ratio of assets within the pool. In LBPs, the ratio adjusts over time. LBPs involve an initial ratio, a target ratio, and an interval of time over which the ratio adjusts. These weights are customizable before launch. One can create an LBP with an initial ratio of 90-10, with the goal of reaching 50-50 over a month. The ratio continues to gradually adjust until the weights are equal within the pool. Like traditional LPs, the prices of assets within the pool is based on the ratio at the time of trade. - -After the LBP period ends or the final ratio is reached, the pool converts into a traditional LP pool. - -LBPs facilitate price discovery by demonstrating the acceptable market price of an asset. Ideally, LBPs will have very few buyers at the time of launch. The price slowly declines until traders are willing to step in and buy the asset. Arbitrage maintains this price for the remainder of the LBP. The process is shown by the blue line below. The price declines as the ratios adjust. Buyers step in until the acceptable price is again reached. - -![](../assets/lbp.png) - -Choosing the correct parameters is very important to price discovery for an LBP. If the initial price is too low, the asset will get bought up as soon as the pool is launched. It is also possible that the targeted final price is too high, creating little demand for the asset. The green line above shows this scenario. A buyer places a large order, but afterwards the price continues to decline as no additional buyers are willing to bite. - -Osmosis aims to provide an intuitive, easy-to-use LBP design to give protocols the best chance of a successful sale. The LBP feature facilitates initial price discovery for tokens and allows protocols to fairly distribute tokens to project stakeholders. - - -## Bonded Liquidity Gauges - -Bonded Liquidity Gauges are mechanisms for distributing liquidity incentives to LP tokens that have been bonded for a minimum amount of time. 45% of the daily issuance of OSMO goes towards these liquidity incentives. - -For instance, a Pool 1 LP share, 1-week gauge would distribute rewards to users who have bonded Pool1 LP tokens for one week or longer. The amount that each user receives is in proportion to the number of their bonded tokens. - -A bonded LP position can be eligible for multiple gauges. Qualifications for a gauge only involve a minimum bonding time. - -![Tux, the Linux mascot](../assets/gauges.png) - - -The rewards earned from liquidity mining are not subject to unbonding. Rewards are liquid and transferable immediately. Only the principal bonded shares are subject to the unbonding period. - - -## Allocation Points - -Not all pools have incentivized gauges. In Osmosis, staked OSMO holders choose which pools to incentivize via on-chain governance proposals. To incentivize a pool, governance can assign “allocation points” to specific gauges. At the end of every daily epoch, 45% of the newly released OSMO (the portions designated for liquidity incentives) is distributed proportionally to the allocation points that each gauge has. The percent of the OSMO liquidity rewards that each gauge receives is calculated as its number of points divided by the total number of allocation points. - -Take, for example, a scenario in which three gauges are incentivized: - -- Gauge #3 – 10 allocation points -- Gauge #4 – 5 allocation points -- Gauge #7 – 5 allocation points - -20 total allocation points are assigned in this scenario. At the end of the daily epochs, Gauge #3 will receive 50% (10 out of 20) of the liquidity incentives minted. Gauges #4 and #7 will receive 25% each. - -Governance can pass an UpdatePoolIncentives proposal to edit the existing allocation points of any gauge. By setting a gauge’s allocation to zero, it can remove it from the list of incentivized gauges entirely. Proposals can also set the allocation points of new gauges. When a new gauge is added, the total number of allocation points increases, thus diluting all the existing incentivized gauges. -Gauge #0 is a special gauge that sends its incentives directly to the chain community pool. Assigning allocation points to gauge #0 allows governance to save some of the current liquidity mining incentives to be spent at a later time. - -At genesis, the only gauge that will be incentivized is Gauge #0, (the community pool gauge). However, a governance proposal can come immediately after launch to choose which gauges/pools to incentivize. Governance voting period at launch is only 3 days at launch, so liquidity incentives may be activated as soon as 3 days after genesis. - -## External Incentives - -Osmosis not only allows the community to add incentives to gauges. Anyone can deposit tokens into a gauge to be distributed. This feature allows outside parties to augment Osmosis’ own liquidity incentive program. - -For example, there may be an ATOM< >FOOCOIN pool that has a one-day gauge incentivized by governance OSMO rewards. However, the Foo Foundation may also choose to add additional incentives to the one-day gauge or even add incentives to a new gauge (such as one-week gauge). - -These external incentive providers can also set up long-lasting incentive programs that distribute rewards over an extended time period. For example, the Foo Foundation can deposit 30,000 Foocoins to be distributed over a one-month liquidity program. The program will automatically distribute 1000 Foocoins per day to the gauge. - -## Fees - -In addition to liquidity mining, Osmosis provides three sources of revenue: transaction fees, swap fees, and exit fees. - -### TX Fees -Transaction fees are paid by any user to post a transaction on the chain. The fee amount is determined by the computation and storage costs of the transaction. Minimum gas costs are determined by the proposer of a block in which the transaction is included. This transaction fee is distributed to OSMO stakers on the network. -Validators can choose which assets to accept for fees in the blocks that they propose. This optionality is a unique feature of Osmosis. - -### Swap Fees -Swap fees are fees charged for making a swap in an LP pool. The fee is paid by the trader in the form of the input asset. Pool creators specify the swap fee when establishing the pool. The total fee for a particular trade is calculated as percentage of swap size. Fees are added to the pool, effectively resulting in pro-rata distribution to LPs proportional to their share of the total pool. - -### Exit Fees -Osmosis LPs pay a small fee when withdrawing from the pool. Similar to swap fees, exit fees per pool are set by the pool creator. -Exit fees are paid in LP tokens. Users withdraw their tokens, minus a percent for the exit fee. These LP shares are burned, resulting in pro-rata distribution to remaining LPs. - - diff --git a/docs/overview/governance.md b/docs/overview/governance.md deleted file mode 100644 index 57c555351..000000000 --- a/docs/overview/governance.md +++ /dev/null @@ -1,23 +0,0 @@ -# Governance - -## Voting - -Staked OSMO holders are eligible to vote on governance proposals. Browse the available proposals, and use one's staked tokens to cast a vote. - -![](../assets/voting.png) - -## Creating a Proposal - -Governance proposals can be added through CLI. -Proposers should use the following format when recommending allocation points for a new gauge: - -```bash -osmosisd tx gov submit-proposal update-pool-incentives [gaugeIds] [weights] -``` - -For example, to designate 100 weight to Gauge ID 2 and 200 weight to Gauge ID 3, the following command can be used: - -``` -osmosisd tx gov submit-proposal update-pool-incentives 2,3 100,200 -``` - diff --git a/docs/overview/integrate/airdrops.md b/docs/overview/integrate/airdrops.md index 4965b9487..a5cbdaded 100644 --- a/docs/overview/integrate/airdrops.md +++ b/docs/overview/integrate/airdrops.md @@ -1,38 +1,43 @@ -# Airdrop Guide +--- +sidebar_position: 2 +--- + +# Airdrop Distribution ## Overview -As more chains enter the cosmos ecosystem, more projects may desire to airdrop their tokens to osmosis accounts. +As more chains enter the cosmos ecosystem, more projects may desire to airdrop their tokens to Osmosis accounts. -This document lays out the process of creating a state export to derive all osmosis account addresses that exists at a specified height. We will then show how to further filter this list to also airdrop to accounts providing liquidity to specific osmosis pools. +This document lays out the process of creating a state export to derive all Osmosis account addresses that existed at a specified height. We will then show how to further filter this list to also airdrop to accounts providing liquidity to specific Osmosis pools. ### Prerequisites -1. Know what height you want to take the snapshot at +1. Know what block height you want to take the snapshot at 2. Know the pool IDs if looking to airdrop to accounts LPing to specific pools -3. Run an osmosis node with enough state history to state export at the desired height - +3. Run an Osmosis node with enough state history to state export at the desired height ### Choosing a block height -The current Osmosis block height can be found on the [Mintscan blocks page.](https://www.mintscan.io/osmosis/blocks)To find the date/time of a specific block height in the past, type the desired block height in the Mintscan search bar and press enter. Here is the Mintscan block height page for block 2138101: +The current Osmosis block height can be found on the [Mintscan blocks page](https://www.mintscan.io/osmosis/blocks). To find the date/time of a specific block height in the past, type the desired block height in the Mintscan search bar and press enter. Here is the Mintscan block height page for block 2138101: ![](../../assets/mintscan_height.png) In this example, block height 2138101 happened on 25 November 2021 at 12:59:55AM local time. +Change this value until you have a block height at the time you want to perform the snapshot. + ### Choosing pool IDs -If your organization also wants to airdrop tokens to liquidity providers of specific osmosis pools, you must first determine the pool IDs of the pools in question. The easiest way to find the pool ID is to go to the [info.osmosis.zone pools page ](https://info.osmosis.zone/pools)and note the number in the furthest left column for all the desired pools. You will need these pool IDs later. +If your organization also wants to airdrop tokens to liquidity providers of specific Osmosis pools, you must first determine the pool IDs of the pools in question. The easiest way to find the pool ID is to go to the [info.osmosis.zone pools page](https://info.osmosis.zone/pools) and note the number in the furthest left column for all the desired pools. You will need these pool IDs later. ![](../../assets/osmosis_pools.png) -### Determine osmosis node type requirement -First, determine how far in the past the desired block height is from the current time. If the desired block height is within the last seven days, you can make the state export with a default snapshot node. Anything further in the past more than likely needs to be done by setting up a node with an archive snapshot. +### Determine Osmosis node type requirement +First, determine how far in the past the desired block height is from the current time. If the desired block height is within the last seven days, you can make the state export with a default snapshot node. Anything further in the past more than likely needs to be done by setting up a node with an archive snapshot as the data for the block in question may not be present due to pruning. In our example, block height 2138101 is many months in the past, so we must use an archive snapshot. -### Run an osmosis node -To set up either a default or archive node, either use the osmosis bash installer [located here](https://get.osmosis.zone/)OR follow the instructions step by step [starting here.](../../osmosis-core/osmosisd)Ensure you follow the instructions for mainnet and set up using either the archive or default snapshot as determined above. Do not use state sync for this situation. +### Run an Osmosis node +To set up either a default or archive node, either use the Osmosis bash installer [located here](https://get.osmosis.zone/) OR follow the instructions step by step [starting here](../../osmosis-core/osmosisd). Ensure you follow the instructions for mainnet and set up using either the archive or default snapshot as determined above. Do not use state sync for this situation. @@ -66,14 +71,12 @@ osmosisd export 2138101 > state_export.json This process may take 30 minutes or more. -::: warning NOTE -Some cosmos sdk versions write to STDERR instead of STDOUT. If the above command does not work for you, try to replace the > with 2> +NOTE: Some cosmos sdk versions write to STDERR instead of STDOUT. If the above command does not work for you, try to replace the > with 2> As of this writing, v5 and later will require 2> while anything before v5 will just use > -::: ### Export accounts in JSON format -Now that you have a state export file with the name `state_export.json`, the last step needed is to export the accounts and respective balances from the state export. To get all existing osmosis accounts on the height the state export was taken and write it to a file called `balances.json`: +Now that you have a state export file with the name `state_export.json`, the last step needed is to export the accounts and respective balances from the state export. To get all existing Osmosis accounts on the height the state export was taken and write it to a file called `balances.json`: ```sh osmosisd export-derive-balances state_export.json balances.json diff --git a/docs/overview/integrate/frontend.md b/docs/overview/integrate/frontend.md index ac2a7977a..8ebd1635e 100644 --- a/docs/overview/integrate/frontend.md +++ b/docs/overview/integrate/frontend.md @@ -1,403 +1,21 @@ -# Osmosis Zone Front End +--- +sidebar_position: 8 +--- -## How to Add Assets onto the Osmosis Assets Page +# Ensure Visibility -Add assets to the [Osmosis frontend repo](https://github.com/osmosis-labs/osmosis-frontend) to have the Asset appear on the [Assets page of app.osmosis.zone](https://app.osmosis.zone/assets) or the [Osmosis Frontier](https://frontier.osmosis.zone/assets). +## List onto the Osmosis Frontend -Note that Osmosis will temporarily utilize an alternate front end interface for listing new and unverified assets: [frontier.osmosis.zone](https://frontier.osmosis.zone); once a pool containing the asset has been onboarded into receiving Osmosis Liquidity Mining incentives, the Asset will then be added to the main [app.osmosis.zone](https://app.osmosis.zone/) site; although, there are some exceptions of unincentivized assets being listed directly on the main site if the assets are well-established and part of an ecosystem with a large market capitalization. +As long as the asset has been properly registered according to the [registration documentation](https://docs.osmosis.zone/overview/integrate/registration) and there is a pool with USD $1000 of [initial liquidity](https://docs.osmosis.zone/overview/integrate/liquidity) then the pool will be visible on this frontend. -![image](https://i.ibb.co/1bhLSx3/Screen-Shot-2022-03-16-at-8-59-21-AM.png) +## Verify Assets -To be able to list assets, Osmosis also requires data about the blockchain from which the assets originate. This data is also used for Keplr's [Suggest Chain API](https://docs.keplr.app/api/suggest-chain.html) to add the chain to the user's wallet upon attempting to deposit or withdraw assets from Osmosis( wherever an external bridge is not used). If the assets being added are the first from the chain to be added to Osmosis, first add the chain data, and then add the asset data within the chain data. If chain data is already added, skip ahead to adding asset data. +An asset will initially show as an Unverified asset. This will require users to toggle on the Unverified Assets setting in the Cog Menu in the top right of their screen to see the asset. -Trade Page +Approval requires meeting the requirements in the assetlist repo that can be seen here: https://github.com/osmosis-labs/assetlists/blob/main/LISTING.md -Although any asset in a liquidity pool can be traded when a user specifies the pool, an Asset will only be listed on the Trade page if it is in a pool containing at least 1000 OSMO, 1000 ATOM, or 10 ION. +![](../../assets/asset_list.png) -### Prerequisites +## Swap Page -Chain Data - -- Chain registered onto the Cosmos Chain Registry - - See: [How to register onto the Cosmos Chain Registry](https://docs.osmosis.zone/integrate/registration.html#how-to-register-onto-the-cosmos-chain-registry) -- Chain registered onto SLIP173 - - See: [How to Register onto SLIP173](https://docs.osmosis.zone/integrate/registration.html#how-to-register-a-bech32-prefix-onto-slip173) -- Relayer(s) set up to relay packets between chains - - To set up a relayer, see the [Relaying Guide](https://docs.osmosis.zone/developing/relaying/relay.html) - - Don't want to set up a Relayer? See: [Shop for a Relayer as a Service (RAAS) Provider](https://docs.osmosis.zone/developing/relaying/relayers.html) -- IBC token transfer has been validated - - Or else a functioning Bridge between Chains (only if regular IBC transfers are not possible) -- Chain has a block explorer, either: - - Mintscan (preferred), or - - Any other Block explorer, e.g., Big Dipper, Ping, or a chain-dedicated explorer - -Asset Data - -- Asset registered onto the Cosmos Chain Registry - - See: [How to register onto the Cosmos Chain Registry](https://docs.osmosis.zone/integrate/registration.html#how-to-register-onto-the-cosmos-chain-registry) -- Asset price oracle added to Osmosis Zone (co-requisite) - - See: [How to Specify Asset Price Oracle on Osmosis Zone (CoinGecko)](https://docs.osmosis.zone/integrate/frontend.html#how-to-specify-asset-price-oracle-on-osmosis-zone-coingecko) - - See: [How to Specify Asset Price Oracle on Osmosis Zone (Liquidity Pool)](https://docs.osmosis.zone/integrate/frontend.html#how-to-specify-asset-price-oracle-on-osmosis-zone-liquidity-pool) -- Asset registered onto the Osmosis Assetlists Registry (post-requisite) - - See: [How to register an Asset onto the Osmosis Assetlists Registry](https://docs.osmosis.zone/integrate/registration.html#how-to-register-an-asset-onto-the-osmosis-assetlists-registry) - -### Requirements - -- Chain data: - - RPC and REST endpoints - - Chain name, Chain id - - BIP44 Coin type (slip44) - - e.g., `coinType: 118,` - - bech32 prefix (slip173) - - At least one staking currency must be specified - - At least one fee currency must be specified - - Cosmos SDK version - - Used to determine which 'features' must be specified - - Gas prices - - The low, average, and high gas prices (per gas unit) so users can choose to either save on fees or expedite transactions using Keplr wallet - - URL to a transation on a Block Explorer - -- Asset data: - - Denominations - - Coin denomination (the denomination for a 'whole' token (e.g., 'ATOM')) - - Coin minimal denomination (base denom on originating chain (e.g., 'uatom') - - For CW20 tokens: - - The minimal denomination looks like `cw20:` - - Will also need the CW20`<>`ICS20 contract address - - For assets originally foreign to the integrating chain (multihop IBC tokens): - - The minimal denomination is the 'ibc/...' denom on the registering chain - - Will also need the entire IBC Transfer Path with the original denomination - - Coin decimal places (e.g., 'ATOM' can be split into micro-ATOM, hence it has 6 decimal places--1 ATOM == 1,000,000 uatom) - - Asset Price data (if available), either: - - CoinGecko ID (optional, but should be included if and when one exists), or - - Refer to the latest [CoinGecko Coins List](https://api.coingecko.com/api/v3/coins/list) - - `pool:` (default alternative, if no CoinGecko ID exists yet), or - - The alternatives should only be used if there is an acceptable pool with the new asset - - See: [How to Specify Asset Price Oracle on Osmosis Zone (Liquidity Pool)](https://docs.osmosis.zone/integrate/frontend.html#how-to-specify-asset-price-oracle-on-osmosis-zone-liquidity-pool) - - none - - Token Logo Image files (both .png and .svg is recommended) - - Note: Currently, a .png is required to be able to render on info.osmosis.zone - - Note: image files shall be titled exactly with the token Symbol in lowercase. E.g., for 'ATOM', title the files `atom.png` and `atom.svg` - - Whether the asset is a staking currency - - Whether the asset is a fee currency - - Designate IBC Connection details: - - Source channel (Osmosis' channel to the registering chain) - - Destination channel (Registering chain's channel to Osmosis) - - Bridge URL (only if regular IBC transfers are not possible) - - Best to include URL parameters to pre-select the networks and assets on the bridge interface -- Enough OSMO for the pool creation fee (100 OSMO) and initial liquidity for an OSMO pool (at least 2000 OSMO-worth per pool) -- Basic understanding of GitHub, knowing how to fork, create a branch, commit changes, and submit a Pull Request - -### Steps - -1. Review the [Osmosis Frontend Repo](https://github.com/osmosis-labs/osmosis-frontend) docs: - 1. [README.md](https://github.com/osmosis-labs/osmosis-frontend/blob/master/README.md) -2. Submit a pull request branch with necessary changes to the following: - - `osmosis-frontend/packages/web/public/tokens/`: - - Add token logo images - - `osmosis-frontend/packages/web/config/chain-infos.ts`: - - Add chain data to the `chainInfos` onject - - Include the optimal RPC and REST endpoints - - Be sure to include coin type - - Be sure to include bech32 prefix - - List all currencies, including stake and fee currencies - - For each currency, be sure to include the Asset Price Oracle as `CoinGeckoID:` - - opt for a real CoinGecko ID, if one exists - - alternatively, use `pool:` if a pool exists - - or else none - - Include features - - 'stargate' -- must be specified if using Cosmos SDK v0.40+ - - 'ibc-transfer' -- must be specified if IBC transfers following the ICS20 standard have been enabled on the chain - - 'no-legacy-stdTx' -- must be specified if using Cosmos SDK v0.43+, but still recommended to specify, regardless of Cosmos SDK version - - 'ibc-go' -- must be specified if using Cosmos SDK v0.43+, and import the ibc-go repository - - E.g., `features: ['stargate', 'ibc-transfer', 'no-legacy-stdTx', 'ibc-go'],` - - Include gas price step - - Include chain explorer path - - Opt for Mintscan, if available - - Note: watch out for and remove any dollar sign ($) in the URL, which may be included in the Explorer URL in the Cosmos Chain Registry - - See examples below - - `osmosis-frontend/packages/web/config/ibc-assets.ts` - - Add assets to `IBCAssetInfos` - - Be sure to include the external bridge URLs if an external site is required to bridge to assets to and from Osmosis - - See examples below -3. Validate the deposit and withdrawal of the asset(s) via the generated staging link - -### Examples - -Example of chain-infos.ts::chainInfos: - - Juno chain, with native asset JUNO listed as a stake, fee, and currency token. - - Note: CW20 assets have a the asset symbol appended to the contract address as the coinMinimalDenom. -``` -{ - rpc: 'https://rpc-juno.keplr.app', - rest: 'https://lcd-juno.keplr.app', - chainId: 'juno-1', - chainName: 'Juno', - bip44: { - coinType: 118, - }, - bech32Config: Bech32Address.defaultBech32Config('juno'), - currencies: [ - { - coinDenom: 'JUNO', - coinMinimalDenom: 'ujuno', - coinDecimals: 6, - coinGeckoId: 'juno-network', - coinImageUrl: window.location.origin + '/public/assets/tokens/juno.svg', - isStakeCurrency: true, - isFeeCurrency: true, - }, - { - type: 'cw20', - contractAddress: 'juno168ctmpyppk90d34p3jjy658zf5a5l3w8wk35wht6ccqj4mr0yv8s4j5awr', - coinDenom: 'NETA', - coinMinimalDenom: 'cw20:juno168ctmpyppk90d34p3jjy658zf5a5l3w8wk35wht6ccqj4mr0yv8s4j5awr:NETA', - coinDecimals: 6, - coinGeckoId: 'neta', - coinImageUrl: window.location.origin + '/public/assets/tokens/neta.svg', - }, - { - type: 'cw20', - contractAddress: 'juno1g2g7ucurum66d42g8k5twk34yegdq8c82858gz0tq2fc75zy7khssgnhjl', - coinDenom: 'MARBLE', - coinMinimalDenom: 'cw20:juno1g2g7ucurum66d42g8k5twk34yegdq8c82858gz0tq2fc75zy7khssgnhjl:MARBLE', - coinDecimals: 3, - coinGeckoId: 'pool:marble', - coinImageUrl: window.location.origin + '/public/assets/tokens/marble.svg', - }, - ], - gasPriceStep: { - low: 0, - average: 0, - high: 0.035, - }, - features: ['stargate', 'ibc-transfer'], - explorerUrlToTx: 'https://www.mintscan.io/juno/txs/{txHash}', -}, -``` - -Examples of ibc-assets.ts::IBCAssetInfos: -- ATOM, a native token from Cosmos Hub: -``` - { - counterpartyChainId: 'cosmoshub-4', - sourceChannelId: 'channel-0', - destChannelId: 'channel-141', - coinMinimalDenom: 'uatom', - }, -``` -- NETA, a CW20 token from Juno: - - Note: *channel-42* is Osmosis' channel to Juno for native Juno assets, but channel-169 is Osmosis' channel to this CW20`<>`ICS20 contract on Juno, which currently accomodates NETA, MARBLE, BLOCK, HOPE, RACOON, and potentially other CW20 tokens in the future -``` - { - counterpartyChainId: 'juno-1', - sourceChannelId: 'channel-169', - destChannelId: 'channel-47', - coinMinimalDenom: 'cw20:juno168ctmpyppk90d34p3jjy658zf5a5l3w8wk35wht6ccqj4mr0yv8s4j5awr', - ics20ContractAddress: 'juno1v4887y83d6g28puzvt8cl0f3cdhd3y6y9mpysnsp3k8krdm7l6jqgm0rkn', - }, -``` -- PSTAKE, an ICS20 token originating from Gravity Bridge chain, transfered through Persistence chain, and finally coming to Osmosis (i.e., not directly to Osmosis from Gravity Bridge): - - Note: *channel-38* is Persistence chain's channel to Gravity bridge - - Note: *gravity0xfB5...006* is Gravity Chain's denomination of PSTAKE (originally from Ethereum) -``` - { - counterpartyChainId: 'core-1', - sourceChannelId: 'channel-4', - destChannelId: 'channel-6', - coinMinimalDenom: 'ibc/A6E3AF63B3C906416A9AF7A556C59EA4BD50E617EFFE6299B99700CCB780E444', - ibcTransferPathDenom: 'transfer/channel-38/gravity0xfB5c6815cA3AC72Ce9F5006869AE67f18bF77006', - }, -``` -- INJ, the staking and fee token for Injective chain. Injective uses an external site to bridge tokens between Injective Chain and Osmosis, thus we specifiy a custom deposit and withdraw URL override: -``` -{ - counterpartyChainId: 'injective-1', - sourceChannelId: 'channel-122', - destChannelId: 'channel-8', - coinMinimalDenom: 'inj', - depositUrlOverride: 'https://hub.injective.network/bridge/?destination=osmosis&origin=injective&token=inj', - withdrawUrlOverride: 'https://hub.injective.network/bridge/?destination=injective&origin=osmosis&token=inj', -}, -``` - -## How to Specify Asset Price Oracle on Osmosis Zone (Liquidity Pool) - -### Purpose - -This procedure will set up the default asset pricing mechanism for an asset to show its price throughout Osmosis Zone. If a CoinGecko Price feed exists, opt to use that instead. This pricing mechanism works by fetching the current spot price of the asset from a pool with an Asset of a known price. For exampe, we might not know the price of Foo coin directly, but we can assume it's price of, say, $2.00 by seeing that it's trading at 1 FOO per 2 UST in the FOO/UST pool. - -### Pre-requisites - -- Asset is in a Pool - - See: [How to create a Liquidity Pool](https://docs.osmosis.zone/developing/modules/spec-gamm.html#create-pool) -- Pool containing Asset is acceptable - - The criteria for 'acceptable' pools are *roughly* as follows: - - Contains only 2 tokens - - Contains a common Base Asset (i.e., OSMO, ATOM, or UST) - - 50/50 weighting - - 0% exit fee - - No future governor (set to blank ("")) - - 0.2-0.3% swap fee - - Sufficient liquidity (at least USD $1000-worth) - -### Requirements - -- Pool details - - Number (Pool ID) - - Assets - - coin minimal denomination - - source channel(s) (if Asset is foreign) -- Basic understanding of GitHub, knowing how to fork, create a branch, commit changes, and submit a Pull Request - -### Steps - -1. Review the [Osmosis Frontend Repo](https://github.com/osmosis-labs/osmosis-frontend/tree/frontier) docs: - 1. [README.md](https://github.com/osmosis-labs/osmosis-frontend/blob/master/README.md) -2. Submit a pull request branch with necessary changes to the following: - - `src/stores/root.ts` - - Specify pool under `RootStore::constructor::priceStore::queriesStore` - - `alternativeCoinId: 'pool:'` - - `poolID: '',` - - `spotPriceSourceDenom: ` - - `spotPriceDestDenom: ` - - `destCoinId: 'osmosis'` - - See examples below - - `src/config.ts` - - Add the alternative coin Id under each specification of the Asset within `EmbedChainInfos: ChainInfoWithExplorer` - - E.g., `coinGeckoId: 'pool:ugraviton'` - - Note that many assets are listed as a staking currency, a fee payment currency, and as a trading currency for a chain; the coin Id should be added to each listing of the asset - - See example below - -### Examples - -- Pool 1: -``` -{ - alternativeCoinId: 'pool:uosmo', - poolId: '1', - spotPriceSourceDenom: 'uosmo', - spotPriceDestDenom: DenomHelper.ibcDenom([{ portId: 'transfer', channelId: 'channel-0' }], 'uatom'), - destCoinId: 'cosmos', -}, -``` -- Pool 631: - - This pool contains a foreign CW20 token. Note how `cw20:` prefixes the contract address. -``` -{ - alternativeCoinId: 'pool:neta', - poolId: '631', - spotPriceSourceDenom: DenomHelper.ibcDenom( - [{ portId: 'transfer', channelId: 'channel-169' }], - 'cw20:juno168ctmpyppk90d34p3jjy658zf5a5l3w8wk35wht6ccqj4mr0yv8s4j5awr' - ), - spotPriceDestDenom: 'uosmo', - destCoinId: 'osmosis', -}, -``` -- Pool 648: - - This pool contains an IBC-multihop token. Note how all transfer paths are included. -``` -{ - alternativeCoinId: 'pool:pstake', - poolId: '648', - spotPriceSourceDenom: DenomHelper.ibcDenom( - [ - { portId: 'transfer', channelId: 'channel-4' }, - { portId: 'transfer', channelId: 'channel-38' }, - ], - 'gravity0xfB5c6815cA3AC72Ce9F5006869AE67f18bF77006' - ), - spotPriceDestDenom: 'uosmo', - destCoinId: 'osmosis', -}, -``` - -Example of osmosis-frontend/packages/web/config/chain-infos.ts::chainInfos: -- Umee chain info: - - Note that `coinGeckoId: 'pool:uumee',` is specified three times, once under each listing of the currency - - Note: once UMEE gets a listing and live price feed on CoinGecko, the values here should then be replaced with the CoinGeckoID, e.g., `coingGeckoId: 'umee'` -``` -{ - rpc: 'https://rpc.aphrodite.main.network.umee.cc', - rest: 'https://api.aphrodite.main.network.umee.cc', - chainId: 'umee-1', - chainName: 'Umee', - bip44: { - coinType: 118, - }, - bech32Config: Bech32Address.defaultBech32Config('umee'), - currencies: [ - { - coinDenom: 'UMEE', - coinMinimalDenom: 'uumee', - coinDecimals: 6, - coinGeckoId: 'pool:uumee', - coinImageUrl: window.location.origin + '/public/assets/tokens/umee.png', - isStakeCurrency: true, - isFeeCurrency: true, - }, - ], - features: ['stargate', 'ibc-transfer', 'no-legacy-stdTx'], - explorerUrlToTx: 'https://www.mintscan.io/umee/txs/{txHash}', -}, -``` - -## How to Add External Incentive Gauges onto the Osmosis Pools Page - -### Purpose - -Projects can permissionlessly add external incentive gauges for bonded LP positions. To learn more about external Liquidity Mining Incentives, see [Liquidity Mining Incentives: External Incentives](https://docs.osmosis.zone/integrate/incentives.html#external-incentives). - -This procedure instructs how to display those incentive gauges on a pool's page as extra rewards. Shown below is an example of external incentives added to the CHEQ / OSMO pool. - -![image](https://user-images.githubusercontent.com/95667791/157994437-a2a90c29-1f88-475f-afff-7c64b9060e54.png) - -### Pre-requisites - -- Asset has been added to the Osmosis Zone Assets page - - See: [How to Add an Asset onto the Osmosis Assets page](https://docs.osmosis.zone/integrate/frontend.html#how-to-add-an-asset-onto-the-osmosis-assets-page) -- Pool has been created - - See: [How to Create a Liquidity Pool](https://docs.osmosis.zone/developing/modules/spec-gamm.html#create-pool) -- External Incentive Gauge(s) have been created - - See: [How to Add an External Incentive Gauge to a Liquidity Pool](https://docs.osmosis.zone/developing/modules/spec-incentives.html#overview) - -### Requirements - -- External Incentive Gauge(s) details: - - Gauge ID - - Destributed Token Denomination (e.g., 'ibc/...') - - Pool Number -- Basic understanding of GitHub, knowing how to fork, create a branch, commit changes, and submit a Pull Request - -### Steps - -1. Review the [Osmosis Frontend Repo](https://github.com/osmosis-labs/osmosis-frontend/) docs: - 1. [README.md](https://github.com/osmosis-labs/osmosis-frontend/blob/master/README.md) -2. Submit a pull request branch with necessary changes to the following: - - `osmosis-frontend/packages/web/config/feature-flag.ts` - - Add a container for the pool under `ExternalIncentiveGaugeAllowList` - - E.g., `'602': []` - - Within the pool container, add the External Incentive Gauges - - For each External Incentive Gaugue, include: - - Gauge ID, and - - Distributed Token Denomination - - (must be the 'ibc/...' denomination) - - E.g., `{ gaugeId: '2127', denom: 'ibc/7A08C6F11EF0F59EB841B9F788A87EC9F2361C7D9703157EC13D940DC53031FA', },` - - See example below - -### Examples - -Example of Cheq External Incentives for pool #602, under feature-flag.ts::ExternalIncentiveGaugeAllowList: -``` - '602': [ - { - gaugeId: '2127', - denom: 'ibc/7A08C6F11EF0F59EB841B9F788A87EC9F2361C7D9703157EC13D940DC53031FA', - }, - { - gaugeId: '2128', - denom: 'ibc/7A08C6F11EF0F59EB841B9F788A87EC9F2361C7D9703157EC13D940DC53031FA', - }, - ], -``` +Although any asset in a liquidity pool can be traded when a user specifies the pool, an asset will only be listed on the Swap page if it is has a pool cointaining liquidity of USD $10,000. \ No newline at end of file diff --git a/docs/overview/integrate/incentives.md b/docs/overview/integrate/incentives.md index d6907198f..a578d9898 100644 --- a/docs/overview/integrate/incentives.md +++ b/docs/overview/integrate/incentives.md @@ -1,102 +1,73 @@ -# Liquidity Mining Incentives +--- +sidebar_position: 7 +--- +# Liquidity Incentives -There are many ways pools on Osmosis can reward liquidity mining incentives. One way is through (internal) Osmosis Liquidity Mining; Osmosis allocates 45% of its inflation to incentivize users to bond their liquidity on Osmosis. In addition, Osmosis allows for the permissionless creation of (external) liquidity mining gauges, allowing projects to add thier own rewards to further incentivize users to provide liquidity into a pool. -To learn more about the Liquidity Mining modules, see: Osmosis Docs: Develop > Osmosis-core > Modules > [Incentives](http://localhost:3000/osmosis-core/modules/spec-incentives) +Liquidity Providers on Osmosis receive swap fees by default, but can choose to bond to pools and receive additional liquidity incentives from many sources. -## Current incentives -There is a spreadsheet that shows the current incentives from the Osmosis chain: https://docs.google.com/spreadsheets/d/1oEn8JtrIU1mze_3Fw4DbbxWBq6yPUM-yAoaOPxG6Y1k/edit#gid=9186761 +* [External Incentives](https://docs.osmosis.zone/overview/getting-started/#external-incentives) -## External Incentives - -External Incentives are an effective way to incentivize users to provide liquidity, as well as a great way to have the pool be considered for onboarding into the set of pools receiving (internal) Osmosis Liquidity Mining incentives. Creating an incentive gauge is permissionless, so anyone can deposit tokens into a gauge to be distributed as bonding incentives. This feature allows outside parties to augment Osmosis’ own liquidity incentive program. To learn more, see: [External Incentives](../../overview/getting-started.md#external-incentives). - -It is possible to add incentives to any combination of 1-day, 7-day, and 14-day gauges. Incentives allocated to the 1-day gauge will be split among all three gauges. Incentives allocated to the 7-day gauge will be split among only the 7-day and 14-day gauges, but not to the 1-day gauge. Incentives allocated to the 14-day gauge will only be distributed to the 14-day gauge. - -Currently, the only way to create an external incentive gauge is to run the [create-gauge command](../../osmosis-core/modules/incentives/#create-gauge) using CLI. - -Once external incentives have been added, note the gauge Id numbers and follow the procedure to [Add External Incentive Gauges onto the Osmosis Zone Pools page](../integrate/frontend.md#how-to-add-external-incentive-gauges-onto-the-osmosis-pools-page) to request to show the gauges on the [Osmosis Zone Pools page](https://app.osmosis.zone/pools). + Osmosis allows for the permissionless creation of (external) liquidity mining gauges, allowing projects to add thier own rewards to further incentivize users to provide liquidity into a pool. -### External Incentive Matching Program +* [Internal Incentives](https://docs.osmosis.zone/overview/getting-started/#internal-incentives) -To incentivize projects to add external incentives, Osmosis governance voted to add the External Incentive Matching program. If on-chain governance approves to match external incentives for a pool, the incentives adjustment process measures the total dollar value of external incentives that have been added to the pool, matches the value in OSMO tokens, and releases that OSMO as extra liquidity mining rewards to all bonding gauges of the pool. -- See [Osmosis Proposal #47: Add Incentive Matching to Prop 13 Model](https://www.mintscan.io/osmosis/proposals/47) on Mintscan. + Osmosis allocates up to 20% of inflation to incentivize users to bond their liquidity on Osmosis. If a pool is included then it will be allocated a share of incentives based on several factors such as type of asset, swap fees generated in the pool, age of listing and sustained volumes. + Osmosis currently only incentivises pools composed of a very limited set of tokens as of [Proposal 638](https://www.mintscan.io/osmosis/proposals/638). -This has the potential to effectively double the incentive of a project's external incentives, although there are some restrictions to this: -- There is an OSMO bias that can down-scale the value of the OSMO matching. If the pool is an OSMO pool, (e.g., FOO/OSMO,) then the value of the matching is 100%. But, if the pool is a non-OSMO pool, (e.g., FOO/ATOM,) then the value of the matching is scaled down to 50% of the value of the external incentives (subject to change if the OSMO bias changes). - - See: [Osmosis Proposal #264: External Incentive Matching reduction within non-OSMO categories](https://www.mintscan.io/osmosis/proposals/264) -- There is also a cap on the value of the matching, which is no more than double the value of the standard OSMO incentives that the pool would receive from internal Osmosis Liquidity Mining. - - See: [Osmosis Proposal #133: Incentive Matching Fee Based and 1:1 Caps](https://www.mintscan.io/osmosis/proposals/133) +* [Superfluid Staking](https://docs.osmosis.zone/overview/getting-started/#superfluid-staking) -See [Osmosis Proposal #178: Match External Incentives for SWTH/OSMO](https://www.mintscan.io/osmosis/proposals/178) for an example of a successful proposal to match external incentives to a new pool. As always, don't forget to precede on-chain proposals with a forum post to give an opportunity for the community to provide feedback. See [Commonwealth post: Signalling proposal to match OSMO rewards to upcoming SWTH/OSMO pool](https://commonwealth.im/osmosis/discussion/4025-signalling-proposal-to-match-osmo-rewards-to-upcoming-swthosmo-pool). + If enabled on a pool, a portion of the OSMO within can also be staked. Providing additional security to Osmosis as well as giving the liquidity providers additional staking rewards and the ability to participate in governance. + Superfluid staking is only available on Classic pools or full range Supercharged Pools. -## Osmosis Liquidity Mining - -Bonded Liquidity Gauges are mechanisms for distributing liquidity incentives to LP tokens that have been bonded for a minimum amount of time. 45% of the daily issuance of OSMO goes towards these liquidity incentives. When a new pool is onboarded to receive (internal) Osmosis Liquidity Mining incentives, it will be granted allocation points and recieve a portion of the 45% of daily OSMO issuance. See [Bonded Liquidity Gauges](../../overview/getting-started.md#bonded-liquidity-gauges). - -### Distribution Calculations +To learn more about the Incentives module, see + [Osmosis Docs: Develop > Osmosis-core > Modules > Incentives](https://docs.osmosis.zone/osmosis-core/modules/incentives) +## External Incentives -#### Category Model +External Incentives are an effective way to incentivize users to provide liquidity, as well as a great way to have the pool be considered for onboarding into the set of pools receiving internal Osmosis Liquidity Mining incentives. Creating an incentive gauge is permissionless, so anyone can deposit tokens into a gauge to be distributed as bonding incentives. This feature allows outside parties to augment Osmosis’ own liquidity incentive program without having to obtain governance approval. -This model groups pools into a number of categories with fixed incentive shares, so that we can prioritize certain classes of liquidity directly. -The model is maintained in the [OsmoIncentives](https://github.com/OsmosisIncentivesCommittee/OsmoIncentives) repo and produces a new proposal to adjust incentive allocations weekly. These are also viewable as csv outputs which are auto imported into [Current Proposal](https://docs.google.com/spreadsheets/d/1ydQfgEDot0AC9xuT2txc39VBfuum_I1gU_1-GrmrWx4/edit?usp=sharing) and [Prospective Proposal](https://docs.google.com/spreadsheets/d/1oEn8JtrIU1mze_3Fw4DbbxWBq6yPUM-yAoaOPxG6Y1k/edit?usp=sharing) spreadsheets. +In Classic and Stableswap pools, it is possible to add incentives to any combination of 1-day, 7-day, and 14-day gauges. Incentives allocated to the 1-day gauge will be split among all three gauges. Incentives allocated to the 7-day gauge will be split among only the 7-day and 14-day gauges, but not to the 1-day gauge. Incentives allocated to the 14-day gauge will only be distributed to the 14-day gauge. -#### Target Share -The share of incentives allocated to each category is then split according to the proportion of swap fees collected by each pool within the category. These values are limited by the `swap fee cap` (currently 3), such that pools will not benefit by having more than 3x the average fee APR of the category. +In Supercharged pools, incentives are distributed block by block according to the ratio of liquidity provision to the active tick. -We then recalculate shares using (capped) fees + external incentives collected by the pool. To limit the incentive increase caused by a match relative to the base incentives, we take the minimum of this `adjusted reveneue` share, and `(1 + matched_multiple_cap) * capped_fee_share`. We set `matched_multiple_cap` at 1, so that matches can be no more than the base incentives of a pool. +Currently, the only way to create an external incentive gauge is to run the [create-gauge command](../../osmosis-core/modules/incentives/#create-gauge) using [CLI](https://docs.osmosis.zone/osmosis-core/osmosisd). -#### Minimum Share -Pools can also have a minimum share set by governance, to incentivize liquidity ahead of observed trading volume. Minimum shares have currently been set for the OSMO/ATOM, OSMO/WETH, OSMO/WBTC, OSMO/CRO and OSMO/USDC pools. These parameters are set and changed by governance and should be used to prioritizes the growth of strategic liquidity. +This command costs 50 OSMO to run, transferred from the running wallet's balance to the Osmosis Community Pool, but can be used to load any token as external incentives to any pool. -#### Maximum Share -Pools can also have a maximum share set by governance, to prevent too many incentives being allocated to any one pool and ensuring a diverse range of liquidity for trading. Currently the OSMO/ATOM pool is the only pool with a maximum set. +## Internal incentives +Internal incentives are provided from Osmosis inflation at each Epoch. Each pool on Osmosis has gauges that may be assigned a weighting to receive a share of these emissions. This weighting can be viewed on chain by [querying the poolincentives module](https://docs.osmosis.zone/osmosis-core/modules/pool-incentives#queries). -#### Major -Qualification for `Major` status is determined by governance based on a combination of factors, namely: -- Is the token market cap large relative to `Osmo` -- Does the majority of the trade volume happen outside of Osmosis -- Do we have a strategic interest in attracting more liquidity of this token +To see how these weightings translate into incentive rates and expected changes at the next adjustment there is a dashboard available from [Chaos Labs](https://community-staging.chaoslabs.xyz/osmosis/incentives-optimization). -Currently this means that there are 4 Major tokens: `Atom`, `WETH`, `WBTC` and `Cro` +Adjustments happen monthly and are required to be voted through Osmosis Governance in order to directly approve changes to the on chain parameters. An example of this is [Proposal 647](https://www.mintscan.io/osmosis/proposals/647). -#### Categories -These determine the ratio of incentives that are allocated to each category -- Osmo/Major - 45% -- Osmo/Stable - 30% -- Osmo/Minor - 14% -- Stable/Major - 0% -- Stable/Stable - 0% -- Others - 2% - Liquidity for Minor tokens paired with non-Osmo +Calculations to determine incentive weighting for each pool were set in [Proposal 578](https://www.mintscan.io/osmosis/proposals/578). -#### Scale Limited Adjustments -To prevent excessive volatility in the incentives APRs, these incentive targets are adjusted towards over multiple weeks, with each adjustment being limited to no more than +25% or -25%. This is somewhat disrupted as a result of normalization though, so when there are large changes in other pools, some pools might see changes in the range of +/- 30%. +These use the incentives research carried out [documented in this paper](https://hathornodes.com/osmosis_incentives_research.html) and the [revision to this](https://hathornodes.com/incentives_research_update.html) based on community feedback. -#### Maturity -This adjustment scale limiting, is also partially negated during the 4 week onboarding period, where pools are expected to grow quite quickly, and so incentives need to be able to adjust quickly as well to keep up. During this period, the setting for the pool is chosen to be a weighted average between the target level and the adjustment limited by the 25% scale, with the weighting between these shifting linearly from entirely target, to entirely scale limited adjustment over the onboarding period. (ie 100% target, 75% target/25% adjustment, 50/50, 25/75, 100% adjustment) +In summary, liquidity targets are set based on: +* Aiming to have slippage of 0.25% for most retail swaps, with 2.5% allowed for whale swaps. +* Minimum liquidity targets to defend against Oracle manipulation -#### Bond Duration -The above calculation determines what share of incentives go to each pool, but these shares are then further split into 3 gauges for each pool. Under current parameters, the 1day gauge receives 50%, 7day 30%, and 14day 20%. This means in effect that 100% of the incentives are available to 14 day bonders, 80% available to 7 day bonders, and only 50% available for 1 day bonders. The actual difference in APRs between bonding lengths is not this simple though, as it is heavily dependent on what percentage of the liquidity in the pool is bonded to each duration, and therefore how much competition there is within each gauge. +Incentives are then adjusted by up to 10% per month until that liquidity target is reached. -### Pool Onboarding -Although pools must be voted in to be onboarded to recieve Osmosis Liquidity Mining Incentives, there are ways to increase the chances of a pool being accepted. -- Propose an OSMO pool. OSMO pools have the highest chances of being onboarded. The community regularly expresses concern over incentivizing non-OSMO pools, so proposing only an OSMO pool has a better chance of being accepted. It is still somewhat common to onboard an ATOM or USDC pool, as those are common base assets on Osmosis, but pools with uncommon base assets (e.g., JUNO) probably have a low chance of being onboarded. -- Add External incentives. Pools that already have a significant amount of external incentives means that incentives will stack, and also shows that the project is serious about the pool. -- Propose well designed pools. Pools with high swap fees, high exit fees, or with extremely asymmetrical weighting can discourage trading or providing liquidity. It is probably best to stick to a standard pool design (i.e., 50/50 weighting, 0% exit fee, and <= 0.3% swap fee) -- Create a commonwealth post about the proposal before creating an on-chain proposal to give the community an opportunity to provide feedback and seek clarity. +## Superfluid Staking +Osmosis Superfluid Staking can further incentivize users to provide liquidity to a pool, as they are able to stake their LP tokens for additional rewards as well as participating in Osmosis governance. The rewards from superfluid staking come from a portion of the OSMO in the pool being staked, so only OSMO pools can qualify for superfluid staking. -As an example, we can see how MARBLE was onboarded into the set of pools to receive internal Osmosis Liquidity Mining rewards: -- See: [Commonwealth post: Signaling Proposal: Add MARBLE Incentivized Pool (#649 OSMO)](https://commonwealth.im/osmosis/discussion/3982-signaling-proposal-add-marble-incentivized-pool-649-osmo) -- See: [Osmosis Proposal #180: Signalling proposal for MARBLE/OSMO(#649) incentivized pool.](https://www.mintscan.io/osmosis/proposals/180) +The reason Osmosis hasn't simply allowed all OSMO pools to enable Superfluid staking is because any sudden extreme loss of value in an asset paired with OSMO would cause the OSMO side of the pool to shrink significantly, and this poses a risk to the security of the chain. The superfluid staked OSMO is meant to be safely staked and untouchable for at least 14-days (the duration on the unbonding period), like all staked OSMO, but if the amount of OSMO in a pool suddenly shrinks, then it essentially has the effect of releasing staked OSMO before the 14-days. This is why governance must assess whether a pool seems stable before enabling superfluid staking for it. -## Superfluid Staking +Currently, there is no strict criteria on which pools may have Superfluid staking enabled, however typical standards from historical discussions include: +* Chain/Token should be established for at least three months. +* Token supply should be reasonably decentralised. +* Liquidity should be suitably high (>$300k) to prevent high volatility in the quantity of Superfluid Staked OSMO. +* Pool liquidity should have stabilised. -Osmosis Superfluid Staking can further incentivize users to provide liquidity to a pool, as they'll be able to stake their LP tokens for additional rewards. The rewards from superfluid staking come from the OSMO in the pool being staked, so only OSMO pools can qualify for superfluid staking. +Superfluid staking is only available on full range positions in Supercharged pools and so this is most frequently used in Classic pools. -Currently, there is no strict criteria on which pools may have Superfluid staking enabled. The feature is enabled for certain pools via on-chain governance. The reason Osmosis hasn't simply allowed all OSMO pools to enable Superfluid staking is because any sudden extreme loss of value in an asset paired with OSMO would cause the OSMO side of the pool to shrink significantly, and this poses a risk to the security of the chain. The superfluid staked OSMO is meant to be safely staked and untouchable for at least 14-days (the duration on the unbonding period), like all staked OSMO, but if the amount of OSMO in a pool suddenly shrinks, then it essentially has the effect of releasing staked OSMO before the 14-days. This is why governance must assess whether a pool seems stable before enabling superfluid staking for it. Before being enabled for Superfluid staking, the token and project should seem legitimate to the community, have a significant amount of liquidity on Osmosis, and have been around for a decent amount of time. +The feature is enabled by via on-chain governance by a `Set Superfluid Asset` Proposal. These proposals must also be posted to the [Osmosis Governance Forum](https://gov.osmosis.zone/) for 3 days before moving to chain. -There has so far been no proven way to hasten the enabling of superfluid staking for a pool, although one could always try to gather suppport from the community and then propose on-chain to enable the feature for the pool. +For an example of a forum post see [Commonwealth Post: Enable Superfluid Staking on OSMO/USDT](https://commonwealth.im/osmosis/discussion/10497-enable-superfluid-staking-on-osmousdt) -## Interfluid Staking +For an example of a Superfluid proposal see [Proposal #471: Enable Superfluid Staking on OSMO/USDT](https://www.mintscan.io/osmosis/proposals/471) -Similar to how superfluid staking stakes a portion of the OSMO in a pool, Interfluid staking stakes a portion of the pair asset (e.g., FOO) on the corresponding foreign chain (e.g., on Foochain), but this feature is not yet live on Osmosis. +For instructions on how to carry out a `Set Superfluid Asset` Proposal via [CLI](https://docs.osmosis.zone/osmosis-core/osmosisd) see [Gov Module Documentation](https://docs.osmosis.zone/osmosis-core/modules/gov#submit-proposal-set-superfluid-asset) \ No newline at end of file diff --git a/docs/overview/integrate/index.mdx b/docs/overview/integrate/index.mdx index ea3ab70f7..0339084c6 100644 --- a/docs/overview/integrate/index.mdx +++ b/docs/overview/integrate/index.mdx @@ -1,6 +1,6 @@ --- title: Introduction -sidebar_position: 3 +sidebar_position: 1 --- import DocCardList from '@theme/DocCardList'; diff --git a/docs/overview/integrate/lbp.md b/docs/overview/integrate/lbp.md deleted file mode 100644 index 4ec0a16b2..000000000 --- a/docs/overview/integrate/lbp.md +++ /dev/null @@ -1,57 +0,0 @@ -# Creating a LBP - -The below is an example of the pool.json file for a [liquidity bootstrapping pool](../getting-started.md#liquidity-bootstrapping-pools). - -A liquidity bootstrapping pool's weight begins at the weight set in the `weights` parameter and linearly shifts the weights until `target-pool-weights` is reached over a time period set by the `duration` parameter upon pool creation. - -Typically, weights begin at an unbalanced ratio with more weight given to the token that is to be sold and shifts to a 1:1 weight (or a weight favoring the counter-party token that the pool is aiming to accrue). The changing of the weight affects the exchange price of the tokens even when the tokens within the pools remain the same. Note that linear change in weight does **not** mean linear change in price (it is highly recommend to play around with the various parameters on this [basic LBP simulator](https://docs.google.com/spreadsheets/d/1t6VsMJF8lh4xuH_rfPNdT5DM3nY4orF9KFOj2HdMmuY/edit#gid=1392289526) to make sure you understand how the pool will act with different parameters and market demand). - -The pool creator can designate when the weight change begins by setting the `start-time`. While the pool will be live and available for trade at the initial `weights`, pool weight shift will not begin until `start-time` is reached. - - -## Example Pool Files - -The following is an example of a liquidity bootstrapping pool. -The weights linearly change between the initial weights provided, and the target weights over 72 hrs (3 days) -If no start time is provided, it defaults to time the tx was successfully executed on chain. - -The `pool.json` file: - -```json -{ - "weights": "10akt,1atom", - "initial-deposit": "1000akt,100atom", - "swap-fee": "0.001", - "exit-fee": "0.001", - "lbp-params": { - "duration": "72h", - "target-pool-weights": "1akt,1atom" - } -} -``` - -Instead with start time included: - -```json -{ - "weights": "10akt,1atom", - "initial-deposit": "1000akt,100atom", - "swap-fee": "0.001", - "exit-fee": "0.001", - "lbp-params": { - "duration": "72h", - "target-pool-weights": "1akt,1atom", - "start-time": "2006-01-02T15:04:05Z" - } -} -``` - -## Example CLI TX - -``` -osmosisd tx gamm create-pool --pool-file="path/to/lbp-pool.json" --from myKey -``` - -::: warning Note -The command to create a liquidity bootstrapping pool is the same as creating a normal pool. However, if the pool has valid `lbp-params` in the pool file (json), it will be created as a liquidity bootstrapping pool. -::: \ No newline at end of file diff --git a/docs/overview/integrate/liquidity.md b/docs/overview/integrate/liquidity.md index df5e6140f..af04dec73 100644 --- a/docs/overview/integrate/liquidity.md +++ b/docs/overview/integrate/liquidity.md @@ -1,108 +1,50 @@ -# Liquidity +--- +sidebar_position: 6 +--- -## Options for Intial Liquidity +# Source Initial Liquidity -When integrating a new asset, Osmosis Zone recommends at least USD $1000-worth of liquidity in a pool before it is listed onto [frontier.osmosis.zone](https://frontier.osmosis.zone); there are a few ways to go about setting up the minimum liquidity requirement. +When integrating a new asset, Osmosis Zone recommends at least USD $1000-worth of liquidity in a pool before it is listed onto [osmosis.zone](https://app.osmosis.zone). There are a few ways to go about setting up the minimum liquidity requirement. *Note that the Osmosis Foundation will **not** consider any OTC token transfers or loans* -- Add your own liquidity - - Simply buy at least USD $500-worth of OSMO (recommended), ATOM, and/or UST to pair with USD $500-worth of the new asset to create a 50/50 pool - - Recommended criteria for a new pool: - - Contains only 2 tokens - - 50/50 weighting - - Contains a common Base Asset (i.e., OSMO, ATOM, or UST) - - 0.2 for OSMO pools, 0.3% swap fee for ATOM or UST pools - - 0% exit fee - - No future governor (set to blank ("")) - - Sufficient liquidity (at least USD $1000-worth) - - Alternatively, find some partners who would be willing to provide the base asset (e.g., OSMO, ATOM, UST, etc.) portion of the liquidity (this is assuming you can provide the pair asset portion (i.e., the new asset)) - - Alternatively, it is possible to create an asymmetrically-weighted liquidity pool to reduce the requirement for the base asset (e.g., 80% FOO::20% OSMO). However, Osmosis Foundation recommends only creating 50/50 pools - - See: [GAMM Module: Create pool](../../osmosis-core/modules/gamm/#create-pool) for the CLI command to create a pool - - If the asset has already been [added onto the Osmosis Zone Frontier Assets page](../integrate/frontend.md#how-to-add-an-asset-onto-the-osmosis-assets-page), then a new pool can be created using the [Osmosis Zone Frontier Pools page](https://frontier.osmosis.zone/pools) - - See: [Create a new pool](../../overview/getting-started.md#create-a-new-pool) -- Initiate a Liquidity Bootstrapping Pool (LBP) - - A Liquidity Bootstrapping Pool (LBP) is a Liquidity Pool that is initiated with a phase of linear weight change. - - Choose any starting weights (e.g., 90:10), ending weights (e.g., 50:50), and weight change duration (e.g., 3 days) - - The primary purpose of an LBP is to be able to initiate a liquidity pool with relatively low amounts of the base asset (e.g., 10% OSMO), and high amounts on the new pair asset (e.g., 90% FOO). Throughout the weight change, as the new pair assets gets cheaper, the market is incentivized to bootstrap the pool with more of the base asset over time. - - Because you'll be providing a low amount of the base asset (e.g., OSMO), it is expected to be able to provide a large amount of the pair asset (e.g., FOO) - - The benefit of being able to bootstrap a liquidity pool with more of the base asset from the market comes at the cost of the GAMM/LP token losing value throughout the weight change - - Some (unverified) examples, where the pool is intially created with a fiar price, and where the prices of the assets do not change throughout the LBP: - - 80 FOO/20 OSMO -> 50 FOO/50 OSMO, means a 2x of the OSMO-side, but a 20% decrease in value of GAMM/LP token - - 90 FOO/10 OSMO -> 50 FOO/50 OSMO, means a 3x of the OSMO-side, but a 40% decrease in value of GAMM/LP token - - 95 FOO/ 5 OSMO -> 50 FOO/50 OSMO, means a ~4.36x of the OSMO-side, but a ~56.4% decrease in value of GAMM/LP token - - Note that if the price of the pair asset (FOO) increases or decreases throughout the LBP, that can mitigate or exacerbate the loss of value of the GAMM/LP token - - The secondary purpose of an LBP is natural price discovery for the new asset. - - Although it can be a strategic way to establish a price for the token, an LBP is still possible to conduct with an already established price, even while arbitrage opportunities would exist. However, the GAMM/LP tokens will lose value of the duration of the weight change, and is therefore generally not recommended - - To learn more about LBPs, see: [Learn More: Liquidity Bootstrapping Pools](../../overview/getting-started.md#liquidity-bootstrapping-pools). - - To create an LBP, see: [Creating an LBP](../integrate/liquidity.md#creating-a-liquidity-bootstrapping-pool) - - When creating an LBP, be sure to request the appropriate changes on the Osmosis Zone Frontier Front End to ensure the LBP page is displayed - - Note: It is highly recommended to postpone any aridrops until after the LBP has fully completed. The potential for users dumping an airdropped token during such a sensitive phase of price discovery can significantly negatively impact the final price of the asset--much moreso than an airdrop that is released afterward. - - Note: LBP 2.0 is still being developed, and will likely be at least a few more months before the front end interface is implemented for it -- Request a loan from the Osmosis Community Pool (OCP) - - Osmosis has now seen a successful case of a new project propsing a loan of OSMO from the OCP, which would later be repaid in the form of the new pair token - - The loaned OSMO was sent to a multisig wallet, added to an LBP, and then the pair asset (STARS) was repaid to the OCP by the same multisig wallet after the completion of the LBP - - Example: - - Stargaze Network (loaned 135,000 OSMO, repaid equivalent value of STARS) - - On-chain Proposal: [Mintscan Osmosis Proposal 99](https://www.mintscan.io/osmosis/proposals/99) - - Commonwealth Posts: [1](https://commonwealth.im/osmosis/discussion/2882-details-and-parameters-of-stargaze-lbp-on-osmosis), [2](https://commonwealth.im/osmosis/discussion/2494-signaling-proposal-for-osmo-for-stars-token-swap) - -## Additional Liquidity - -As more liquidity becomes available to users, either through mining, airdrops, or giveaways, it could be strategic to incentivize more liquidity to be added to Osmosis liquidity pools to ensure there is a healthy, consistent market for the new asset. See the [Liquidity Mining Incentives Docs page](../integrate/incentives.md) to learn more about Osmosis Liquidity Mining Rewards, External Gauge Incentives, and Superfluid Staking. - -## Creating a Liquidity Bootstrapping Pool - -The below is an example of the pool.json file for a [liquidity bootstrapping pool](../../overview/getting-started.md#liquidity-bootstrapping-pools). - -A liquidity bootstrapping pool's weight begins at the weight set in the `weights` parameter and linearly shifts the weights until `target-pool-weights` is reached over a time period set by the `duration` parameter upon pool creation. - -Typically, weights begin at an unbalanced ratio with more weight given to the token that is to be sold and shifts to a 1:1 weight (or a weight favoring the counter-party token that the pool is aiming to accrue). The changing of the weight affects the exchange price of the tokens even when the tokens within the pools remain the same. Note that linear change in weight does **not** mean linear change in price (it is highly recommend to play around with the various parameters on this [basic LBP simulator](https://docs.google.com/spreadsheets/d/1t6VsMJF8lh4xuH_rfPNdT5DM3nY4orF9KFOj2HdMmuY/edit#gid=1392289526) to make sure you understand how the pool will act with different parameters and market demand). - -The pool creator can designate when the weight change begins by setting the `start-time`. While the pool will be live and available for trade at the initial `weights`, pool weight shift will not begin until `start-time` is reached. - - -### Example Pool Files - -The following is an example of a liquidity bootstrapping pool. -The weights linearly change between the initial weights provided, and the target weights over 72 hrs (3 days) -If no start time is provided, it defaults to time the tx was successfully executed on chain. - -The `pool.json` file: - -```json -{ - "weights": "10akt,1atom", - "initial-deposit": "1000akt,100atom", - "swap-fee": "0.001", - "exit-fee": "0.001", - "lbp-params": { - "duration": "72h", - "target-pool-weights": "1akt,1atom" - } -} -``` - -Instead with start time included: - -```json -{ - "weights": "10akt,1atom", - "initial-deposit": "1000akt,100atom", - "swap-fee": "0.001", - "exit-fee": "0.001", - "lbp-params": { - "duration": "72h", - "target-pool-weights": "1akt,1atom", - "start-time": "2006-01-02T15:04:05Z" - } -} -``` - -### Example CLI TX - -``` -osmosisd tx gamm create-pool --pool-file="path/to/lbp-pool.json" --from myKey -``` - -Note: The command to create a liquidity bootstrapping pool is the same as creating a normal pool. However, if the pool has valid `lbp-params` in the pool file (json), it will be created as a liquidity bootstrapping pool. +## Add your own liquidity +Buy at least USD $500-worth of your chosen Quote Asset (USDC, USDT, DAI, WBTC, ETH, ATOM or OSMO) to pair with USD $500-worth of the new asset to create a 50/50 pool. + +Alternatively, find partners who would be willing to provide the base asset portion of the liquidity to the equivalent value of the new asset you are creating a pool for. + +Alternatively, it is possible to create an asymmetrically-weighted liquidity pool to reduce the requirement for the base asset (e.g. 80% FOO::20% OSMO). However, 50/50 pools are recommended. + +## Utilise StreamSwap to obtain initial liquidity +[StreamSwap](https://streamswap.io/) is a protocol built on Osmosis that allows a token to be loaded into a stream and users to subscribe by depositing a second asset in order to receive a share of the token according to the proportion of the total deposit they contributed. + +The stream ends with participating users having smoothly exchanged their deposit for the streamed token and the initiating user obtaining the alternative asset that can then be used for any purpose, including as a base asset to establish a pool. + +The stream also helps to define an appropriate ratio of the two assets that should be added in order for the pool to have an equal value of each on each side of a 50:50 pool. + +## Request a Loan Swap from the Osmosis Community Pool (OCP) +Osmosis has seen multiple cases of a new project proposing a loan of OSMO from the OCP, which would later be repaid in the form of the new pair token. +The process for this is still under refinement, but current standards are that OSMO would be spent into a multisig controlled by the requesting team for use as initial liquidity. After 30 days, the equivalent value of the paired token would be returned to the Osmosis Community Pool based on a Time Weighted Average Price (TWAP) of both tokens. + +Stargaze Network was loaned 135,000 OSMO, repaid equivalent value of STARS +* On-chain Proposal: [Mintscan Osmosis Proposal 99](https://www.mintscan.io/osmosis/proposals/99) +* Commonwealth Posts: [Details and Parameters of Stargaze LBP on Osmosis](https://commonwealth.im/osmosis/discussion/2882-details-and-parameters-of-stargaze-lbp-on-osmosis), [Signalling proposal for OSMO for STARS Token Swap](https://commonwealth.im/osmosis/discussion/2494-signaling-proposal-for-osmo-for-stars-token-swap) + +Axelar Network was loaned 741,000 OSMO, repaid equivalent value of AXL +* On-chain Proposal: [Mintscan Osmosis Proposal 332](https://www.mintscan.io/osmosis/proposals/332) +* Commonwealth Post: [Proposal for Loan Swap of OSMO to Axelar](https://commonwealth.im/osmosis/discussion/6875-proposal-for-loan-swap-of-osmo-to-axelar) + +## Request a Token Swap from the Osmosis Community Pool +If your token has comparable inflation rates to that of OSMO then a direct swap could be used for both parties to establish Protocol Owned Liquidity to establish liquidity whilst maintaining value. + +WYND Protocol swapped 26,000 OSMO for the equivalent value of WYND shortly after launch to establish functional liquidity on both DEXs. +* On-chain Proposal: [Mintscan Osmosis Proposal 420](https://www.mintscan.io/osmosis/proposals/420) +* Commonwealth Post: [OSMO WYND Token Swap for Protocol Liquidity](https://commonwealth.im/osmosis/discussion/9620-osmowynd-token-swap-for-protocol-liquidity) + +Regen Network worked with the Osmosis Community to swap ~133,000 OSMO for ~53,000 NCT and establish the Carbon market on Osmosis +* On-chain Proposal: [Establish Carbon Market on Osmosis](https://www.mintscan.io/osmosis/proposals/182) +* Commonwealth Post: [Osmosis Carbon Market with Regen Network](https://commonwealth.im/osmosis/discussion/3936-proposal-osmosis-carbon-market-with-regen-network) + +# Additional Liquidity + +As more liquidity becomes available to users, either through mining, airdrops, or giveaways, it could be strategic to incentivize more liquidity to be added to Osmosis liquidity pools to ensure there is a healthy, consistent market for the new asset. See the [Liquidity Incentives Docs page](../integrate/incentives.md) to learn more about how you can . \ No newline at end of file diff --git a/docs/overview/integrate/pool-setup.md b/docs/overview/integrate/pool-setup.md index 16ca4f4ec..31e183353 100644 --- a/docs/overview/integrate/pool-setup.md +++ b/docs/overview/integrate/pool-setup.md @@ -1,3 +1,7 @@ +--- +sidebar_position: 5 +--- + # Pool Setup Guide ## Overview diff --git a/docs/overview/integrate/registration.md b/docs/overview/integrate/registration.md index a5d2011f8..e6fbb34bc 100644 --- a/docs/overview/integrate/registration.md +++ b/docs/overview/integrate/registration.md @@ -1,20 +1,21 @@ -# Registration +--- +sidebar_position: 4 +--- +# Register your Asset +Assets need to be registered in several locations in order to be displayed correctly on interfaces. Without registration, assets will show as a long list of characters. -## How to Register onto the Cosmos Chain Registry +# Prerequisites -### Purpose +- Registered to [SLIP173](https://github.com/satoshilabs/slips/blob/master/slip-0173.md) + - See: [How to register a bech32 prefix onto SLIP173](../integrate/transfer.md#how-to-register-a-bech32-prefix-onto-slip173) +- If coin type is not like ATOM, registered to [SLIP44](https://github.com/satoshilabs/slips/blob/master/slip-0044.md) + - Note: Coin Type 118 represents the Cosmos Hub's ATOM token, registered listed in [SLIP44](https://github.com/satoshilabs/slips/blob/master/slip-0044.md); many projects also default to using this coin type, while some have registered their own. -The Cosmos Chain Registry is used as a single source of truth and is used to look up chain and asset data +## Step 1: Register onto the Cosmos Chain Registry -### Prerequisites +### Purpose -- Registered to [SLIP173](https://github.com/satoshilabs/slips/blob/master/slip-0173.md) - - See: [How to register a bech32 prefix onto SLIP173](../integrate/registration.md#how-to-register-a-bech32-prefix-onto-slip173) -- Registered to [SLIP44](https://github.com/satoshilabs/slips/blob/master/slip-0044.md) (if coin type is not like ATOM) - - Note: Coin Type 118 represents the Cosmos Hub's ATOM token, registered listed in [SLIP44](https://github.com/satoshilabs/slips/blob/master/slip-0044.md); many projects also default to using this coin type, while some have registered their own. -- Chain added to Mintscan (optional) -- Assets listed on CoinGecko (optional) - - See: [How to enlist assets onto CoinGecko](../integrate/registration.md#how-to-enlist-an-asset-onto-coingecko) +The Cosmos Chain Registry is used as a single source of truth and is used to look up chain and asset data ### Requirements @@ -27,26 +28,24 @@ The Cosmos Chain Registry is used as a single source of truth and is used to loo ### Steps 1. Review the [Cosmos Chain Registry](https://github.com/cosmos/chain-registry) docs: - 1. [README.md](https://github.com/cosmos/chain-registry/blob/master/README.md) - 2. [chain.schema.json](https://github.com/cosmos/chain-registry/blob/master/chain.schema.json) - 3. [assetlist.schema.json](https://github.com/cosmos/chain-registry/blob/master/assetlist.schema.json) - Note: It is recommended to refer to another registration to serve as an example, such as [Osmosis' registration](https://github.com/cosmos/chain-registry/blob/master/osmosis/chain.json) -2. Submit a pull request with necessary changes to the following: - - `chain.json`: - - Be sure to include `bech32_prefix` - - e.g., `"bech32_prefix": "cosmos",` - - Be sure to include `slip44` (coin type) - - e.g., `"slip44": 118,` - - Be sure to include at least one RPC and one REST under `apis` - - For explorers, opt for Mintscan, if available - - `assetlists.json`: - - The `name` of an asset refers to how the asset should be called in persoanl communication, while `symbol` is like a stock ticker, typically in ALL CAPS, and these values may differ. - - e.g., `"name": graviton, "display": "graviton", "symbol": "GRAV"` - - Be sure to include the CoinGecko ID for each asset where one exists - - e.g., `"coingecko_id": "cosmos"` - - -## How to Register an Asset onto the Osmosis Assetlists Registry +2. If registering a new Chain, submit a pull request with necessary changes to the `chain.json` file. + - Follow the [chain.schema.json](https://github.com/cosmos/chain-registry/blob/master/chain.schema.json) format. + - Be sure to include `bech32_prefix` + - e.g., `"bech32_prefix": "cosmos",` + - Be sure to include `slip44` (coin type) + - e.g., `"slip44": 118,` + - Be sure to include at least one RPC and one REST under `apis` + - For explorers, opt for Mintscan, if available +3. If registering a new Asset, submit a pull request with necessary changes to the `assetlists.json` file. + - Follow the [assetlist.schema.json](https://github.com/cosmos/chain-registry/blob/master/assetlist.schema.json) format. + - The `name` of an asset refers to how the asset should be called in persoanl communication, while `symbol` is like a stock ticker, typically in ALL CAPS, and these values may differ. + - e.g., `"name": graviton, "display": "graviton", "symbol": "GRAV"` + - Be sure to include the CoinGecko ID for each asset where one exists + - e.g., `"coingecko_id": "cosmos"` + + +## Step 2: Register an Asset onto the Osmosis Assetlists Registry ### Purpose @@ -59,8 +58,8 @@ The Osmosis Assetlists Registry is used as a local source of truth for assets di - Opened IBC connection between the source chain and Osmosis - Selected a sole desigate IBC connection between the registering chain and Osmosis for this asset - All native assets from a chain should go through a single connection, but CW20 tokens can be sent through another connection -- There is a liquidity pool on Osmosis with sufficient liquidity. - - See: [Liquidity](../integrate/liquidity.md) + - See: [Enabling IBC transfers](../integrate/registration.md#enabling-ibc-transfers) and [Setting up and operating relayer to Osmosis](../integrate/registration.md#setting-up-and-operating-relayer-to-osmosis) +- There is a liquidity pool on Osmosis. - See: [GAMM Module: Create pool](../../osmosis-core/modules/gamm/#create-pool) for the CLI command to create a pool - Assets listed on CoinGecko (optional) - See: [How to enlist assets onto CoinGecko](../integrate/registration.md#how-to-enlist-an-asset-onto-coingecko) @@ -85,42 +84,221 @@ The Osmosis Assetlists Registry is used as a local source of truth for assets di 1. Review the [Osmosis Assetlists Registry](https://github.com/osmosis-labs/assetlists) docs: 1. [README.md](https://github.com/osmosis-labs/assetlists/blob/main/README.md) 2. [assetlist.schema.json](https://github.com/osmosis-labs/assetlists/blob/main/assetlist.schema.json) -2. Submit a pull request with necessary changes to the following: - - `osmosis-1/osmosis-frontier.assetlist.json`: - - Be sure to include the CoinGecko ID if one exists - - `images/` - - Add token logo images +2. Submit a pull request with necessary changes to the `osmosis-1/osmosis.zone_assets.json` file. + - Be sure to include the CoinGecko ID if one exists -## How to Register a bech32 Prefix onto SLIP173 - -### Purpose - -CosmosSDK Chain addresses can be represented with a chain-specific string preceding a hash, which helps identify to which chain an address belongs. They are registered on [SLIP173](https://github.com/satoshilabs/slips/blob/master/slip-0173.md) +## Step 3: Register an Asset on the Osmosis Frontend Repository ### Prerequisites -- Chain configured to use bech32 prefixes in wallet addresses - - Note: A bech32 prefix may still be registered, even before the chain is configured to use the prefixes, but only if the configuration will happen soon. +Chain Data + +- Chain registered onto the Cosmos Chain Registry + - See: [How to register onto the Cosmos Chain Registry](https://docs.osmosis.zone/integrate/registration.html#how-to-register-onto-the-cosmos-chain-registry) +- Chain registered onto SLIP173 + - See: [How to Register onto SLIP173](https://docs.osmosis.zone/integrate/registration.html#how-to-register-a-bech32-prefix-onto-slip173) +- Relayer(s) set up to relay packets between chains + - To set up a relayer, see the [Relaying Guide](https://docs.osmosis.zone/developing/relaying/relay.html) + - Don't want to set up a Relayer? See: [Shop for a Relayer as a Service (RAAS) Provider](https://docs.osmosis.zone/developing/relaying/relayers.html) +- IBC token transfer has been validated + - Or else a functioning Bridge between Chains (only if regular IBC transfers are not possible) +- Chain has a block explorer, either: + - Mintscan (preferred), or + - Any other Block explorer, e.g., Big Dipper, Ping, or a chain-dedicated explorer + +Asset Data + +- Asset registered onto the Cosmos Chain Registry + - See: [How to register onto the Cosmos Chain Registry](https://docs.osmosis.zone/integrate/registration.html#how-to-register-onto-the-cosmos-chain-registry) +- Asset price oracle added to Osmosis Zone (co-requisite) + - See: [How to Specify Asset Price Oracle on Osmosis Zone (CoinGecko)](https://docs.osmosis.zone/integrate/frontend.html#how-to-specify-asset-price-oracle-on-osmosis-zone-coingecko) + - See: [How to Specify Asset Price Oracle on Osmosis Zone (Liquidity Pool)](https://docs.osmosis.zone/integrate/frontend.html#how-to-specify-asset-price-oracle-on-osmosis-zone-liquidity-pool) +- Asset registered onto the Osmosis Assetlists Registry (post-requisite) + - See: [How to register an Asset onto the Osmosis Assetlists Registry](https://docs.osmosis.zone/integrate/registration.html#how-to-register-an-asset-onto-the-osmosis-assetlists-registry) ### Requirements - Chain data: - - Chain name - - Chain website - - bech32 prefix(es) - - Mainnet - - Testnet (optional) - - Regtest (optional) - - Note: The bech32 prefix must be unique among all registered prefixes. E.g., a new mainnet prefix cannot match a prefix already registered as a testnet prefix. + - RPC and REST endpoints + - Chain name, Chain id + - BIP44 Coin type (slip44) + - e.g., `coinType: 118,` + - bech32 prefix (slip173) + - At least one staking currency must be specified + - At least one fee currency must be specified + - Cosmos SDK version + - Used to determine which 'features' must be specified + - Gas prices + - The low, average, and high gas prices (per gas unit) so users can choose to either save on fees or expedite transactions using Keplr wallet + - URL to a transation on a Block Explorer + +- Asset data: + - Denominations + - Coin denomination (the denomination for a 'whole' token (e.g., 'ATOM')) + - Coin minimal denomination (base denom on originating chain (e.g., 'uatom') + - For CW20 tokens: + - The minimal denomination looks like `cw20:` + - Will also need the CW20`<>`ICS20 contract address + - For assets originally foreign to the integrating chain (multihop IBC tokens): + - The minimal denomination is the 'ibc/...' denom on the registering chain + - Will also need the entire IBC Transfer Path with the original denomination + - Coin decimal places (e.g., 'ATOM' can be split into micro-ATOM, hence it has 6 decimal places--1 ATOM == 1,000,000 uatom) + - Asset Price data (if available), either: + - CoinGecko ID (optional, but should be included if and when one exists), or + - Refer to the latest [CoinGecko Coins List](https://api.coingecko.com/api/v3/coins/list) + - `pool:` (default alternative, if no CoinGecko ID exists yet), or + - The alternatives should only be used if there is an acceptable pool with the new asset + - See: [How to Specify Asset Price Oracle on Osmosis Zone (Liquidity Pool)](https://docs.osmosis.zone/integrate/frontend.html#how-to-specify-asset-price-oracle-on-osmosis-zone-liquidity-pool) + - none + - Token Logo Image files (both .png and .svg is recommended) + - Note: Currently, a .png is required to be able to render on info.osmosis.zone + - Note: image files shall be titled exactly with the token Symbol in lowercase. E.g., for 'ATOM', title the files `atom.png` and `atom.svg` + - Whether the asset is a staking currency + - Whether the asset is a fee currency + - Designate IBC Connection details: + - Source channel (Osmosis' channel to the registering chain) + - Destination channel (Registering chain's channel to Osmosis) + - Bridge URL (only if regular IBC transfers are not possible) + - Best to include URL parameters to pre-select the networks and assets on the bridge interface +- Enough OSMO for the pool creation fee (100 OSMO) and initial liquidity for an OSMO pool (at least 2000 OSMO-worth per pool) - Basic understanding of GitHub, knowing how to fork, create a branch, commit changes, and submit a Pull Request ### Steps -1. Review the [SLIP173 Registry](https://github.com/satoshilabs/slips/blob/master/slip-0173.md): -2. Submit a pull request with necessary changes to the following: - - `slip-0173.md`: - - Add the chain name (as a link to the website) and prefix(es) into the *Registered human-readable parts* table +1. Review the [Osmosis Frontend Repo](https://github.com/osmosis-labs/osmosis-frontend) docs: + 1. [README.md](https://github.com/osmosis-labs/osmosis-frontend/blob/master/README.md) +2. Submit a pull request branch with necessary changes to the following: + - `osmosis-frontend/packages/web/public/tokens/`: + - Add token logo images + - `osmosis-frontend/packages/web/config/chain-infos.ts`: + - Add chain data to the `chainInfos` onject + - Include the optimal RPC and REST endpoints + - Be sure to include coin type + - Be sure to include bech32 prefix + - List all currencies, including stake and fee currencies + - For each currency, be sure to include the Asset Price Oracle as `CoinGeckoID:` + - opt for a real CoinGecko ID, if one exists + - alternatively, use `pool:` if a pool exists + - or else none + - Include features + - 'stargate' -- must be specified if using Cosmos SDK v0.40+ + - 'ibc-transfer' -- must be specified if IBC transfers following the ICS20 standard have been enabled on the chain + - 'no-legacy-stdTx' -- must be specified if using Cosmos SDK v0.43+, but still recommended to specify, regardless of Cosmos SDK version + - 'ibc-go' -- must be specified if using Cosmos SDK v0.43+, and import the ibc-go repository + - E.g., `features: ['stargate', 'ibc-transfer', 'no-legacy-stdTx', 'ibc-go'],` + - Include gas price step + - Include chain explorer path + - Opt for Mintscan, if available + - Note: watch out for and remove any dollar sign ($) in the URL, which may be included in the Explorer URL in the Cosmos Chain Registry + - See examples below + - `osmosis-frontend/packages/web/config/ibc-assets.ts` + - Add assets to `IBCAssetInfos` + - Be sure to include the external bridge URLs if an external site is required to bridge to assets to and from Osmosis + - See examples below +3. Validate the deposit and withdrawal of the asset(s) via the generated staging link + +### Examples + +Example of chain-infos.ts::chainInfos: + - Juno chain, with native asset JUNO listed as a stake, fee, and currency token. + - Note: CW20 assets have a the asset symbol appended to the contract address as the coinMinimalDenom. +``` +{ + rpc: 'https://rpc-juno.keplr.app', + rest: 'https://lcd-juno.keplr.app', + chainId: 'juno-1', + chainName: 'Juno', + bip44: { + coinType: 118, + }, + bech32Config: Bech32Address.defaultBech32Config('juno'), + currencies: [ + { + coinDenom: 'JUNO', + coinMinimalDenom: 'ujuno', + coinDecimals: 6, + coinGeckoId: 'juno-network', + coinImageUrl: window.location.origin + '/public/assets/tokens/juno.svg', + isStakeCurrency: true, + isFeeCurrency: true, + }, + { + type: 'cw20', + contractAddress: 'juno168ctmpyppk90d34p3jjy658zf5a5l3w8wk35wht6ccqj4mr0yv8s4j5awr', + coinDenom: 'NETA', + coinMinimalDenom: 'cw20:juno168ctmpyppk90d34p3jjy658zf5a5l3w8wk35wht6ccqj4mr0yv8s4j5awr:NETA', + coinDecimals: 6, + coinGeckoId: 'neta', + coinImageUrl: window.location.origin + '/public/assets/tokens/neta.svg', + }, + { + type: 'cw20', + contractAddress: 'juno1g2g7ucurum66d42g8k5twk34yegdq8c82858gz0tq2fc75zy7khssgnhjl', + coinDenom: 'MARBLE', + coinMinimalDenom: 'cw20:juno1g2g7ucurum66d42g8k5twk34yegdq8c82858gz0tq2fc75zy7khssgnhjl:MARBLE', + coinDecimals: 3, + coinGeckoId: 'pool:marble', + coinImageUrl: window.location.origin + '/public/assets/tokens/marble.svg', + }, + ], + gasPriceStep: { + low: 0, + average: 0, + high: 0.035, + }, + features: ['stargate', 'ibc-transfer'], + explorerUrlToTx: 'https://www.mintscan.io/juno/txs/{txHash}', +}, +``` + +Examples of ibc-assets.ts::IBCAssetInfos: +- ATOM, a native token from Cosmos Hub: +``` + { + counterpartyChainId: 'cosmoshub-4', + sourceChannelId: 'channel-0', + destChannelId: 'channel-141', + coinMinimalDenom: 'uatom', + }, +``` +- NETA, a CW20 token from Juno: + - Note: *channel-42* is Osmosis' channel to Juno for native Juno assets, but channel-169 is Osmosis' channel to this CW20`<>`ICS20 contract on Juno, which currently accomodates NETA, MARBLE, BLOCK, HOPE, RACOON, and potentially other CW20 tokens in the future +``` + { + counterpartyChainId: 'juno-1', + sourceChannelId: 'channel-169', + destChannelId: 'channel-47', + coinMinimalDenom: 'cw20:juno168ctmpyppk90d34p3jjy658zf5a5l3w8wk35wht6ccqj4mr0yv8s4j5awr', + ics20ContractAddress: 'juno1v4887y83d6g28puzvt8cl0f3cdhd3y6y9mpysnsp3k8krdm7l6jqgm0rkn', + }, +``` +- PSTAKE, an ICS20 token originating from Gravity Bridge chain, transfered through Persistence chain, and finally coming to Osmosis (i.e., not directly to Osmosis from Gravity Bridge): + - Note: *channel-38* is Persistence chain's channel to Gravity bridge + - Note: *gravity0xfB5...006* is Gravity Chain's denomination of PSTAKE (originally from Ethereum) +``` + { + counterpartyChainId: 'core-1', + sourceChannelId: 'channel-4', + destChannelId: 'channel-6', + coinMinimalDenom: 'ibc/A6E3AF63B3C906416A9AF7A556C59EA4BD50E617EFFE6299B99700CCB780E444', + ibcTransferPathDenom: 'transfer/channel-38/gravity0xfB5c6815cA3AC72Ce9F5006869AE67f18bF77006', + }, +``` +- INJ, the staking and fee token for Injective chain. Injective uses an external site to bridge tokens between Injective Chain and Osmosis, thus we specifiy a custom deposit and withdraw URL override: +``` +{ + counterpartyChainId: 'injective-1', + sourceChannelId: 'channel-122', + destChannelId: 'channel-8', + coinMinimalDenom: 'inj', + depositUrlOverride: 'https://hub.injective.network/bridge/?destination=osmosis&origin=injective&token=inj', + withdrawUrlOverride: 'https://hub.injective.network/bridge/?destination=injective&origin=osmosis&token=inj', +}, +``` + + + ## How to Enlist an Asset onto CoinGecko @@ -129,7 +307,7 @@ CosmosSDK Chain addresses can be represented with a chain-specific string preced CoinGecko ([CoinGecko.com](https://coingecko.com)) is cryptocurrency price aggregator which can provide asset price data directly to Osmosis Zone via API. Check out their [FAQ](https://www.coingecko.com/en/faq) to learn more. -Osmosis embraces CoinGecko price feeds and prioritizes CoinGecko prices over Osmosis pool spot prices on Osmosis Zone. If as asset is not yet registered on CoinGecko, it should aim to do so. This procedure will guide project administrators to register their Asset onto CoinGecko. +Osmosis embraces CoinGecko price feeds and uses these as a backup for pool spot prices on Osmosis Zone. If as asset is not yet registered on CoinGecko, it should aim to do so. This procedure will guide project administrators to register their Asset onto CoinGecko. ### Prerequisites @@ -163,3 +341,125 @@ From [coingecko.com/en/methodology](https://www.coingecko.com/en/methodology): - 'Listing Process Flow' 2. Fill in and submit a 'CoinGecko Request Form' (a current link can be found on their 'Methodology' page) + +### How to Specify Asset Price Oracle on Osmosis Zone (Liquidity Pool) + +#### Purpose + +This procedure will set up the default asset pricing mechanism for an asset to show its price throughout Osmosis Zone. If a CoinGecko Price feed exists, opt to use that instead. This pricing mechanism works by fetching the current spot price of the asset from a pool with an Asset of a known price. For exampe, we might not know the price of Foo coin directly, but we can assume it's price of, say, $2.00 by seeing that it's trading at 1 FOO per 2 UST in the FOO/UST pool. + +#### Pre-requisites + +- Asset is in a Pool + - See: [How to create a Liquidity Pool](https://docs.osmosis.zone/developing/modules/spec-gamm.html#create-pool) +- Pool containing Asset is acceptable + - The criteria for 'acceptable' pools are *roughly* as follows: + - Contains only 2 tokens + - Contains a common Base Asset (i.e., OSMO, ATOM, or UST) + - 50/50 weighting + - 0% exit fee + - No future governor (set to blank ("")) + - 0.2-0.3% swap fee + - Sufficient liquidity (at least USD $1000-worth) + +#### Requirements + +- Pool details + - Number (Pool ID) + - Assets + - coin minimal denomination + - source channel(s) (if Asset is foreign) +- Basic understanding of GitHub, knowing how to fork, create a branch, commit changes, and submit a Pull Request + +#### Steps + +1. Review the [Osmosis Frontend Repo](https://github.com/osmosis-labs/osmosis-frontend/tree/frontier) docs: + 1. [README.md](https://github.com/osmosis-labs/osmosis-frontend/blob/master/README.md) +2. Submit a pull request branch with necessary changes to the following: + - `src/stores/root.ts` + - Specify pool under `RootStore::constructor::priceStore::queriesStore` + - `alternativeCoinId: 'pool:'` + - `poolID: '',` + - `spotPriceSourceDenom: ` + - `spotPriceDestDenom: ` + - `destCoinId: 'osmosis'` + - See examples below + - `src/config.ts` + - Add the alternative coin Id under each specification of the Asset within `EmbedChainInfos: ChainInfoWithExplorer` + - E.g., `coinGeckoId: 'pool:ugraviton'` + - Note that many assets are listed as a staking currency, a fee payment currency, and as a trading currency for a chain; the coin Id should be added to each listing of the asset + - See example below + +#### Examples + +- Pool 1: +``` +{ + alternativeCoinId: 'pool:uosmo', + poolId: '1', + spotPriceSourceDenom: 'uosmo', + spotPriceDestDenom: DenomHelper.ibcDenom([{ portId: 'transfer', channelId: 'channel-0' }], 'uatom'), + destCoinId: 'cosmos', +}, +``` +- Pool 631: + - This pool contains a foreign CW20 token. Note how `cw20:` prefixes the contract address. +``` +{ + alternativeCoinId: 'pool:neta', + poolId: '631', + spotPriceSourceDenom: DenomHelper.ibcDenom( + [{ portId: 'transfer', channelId: 'channel-169' }], + 'cw20:juno168ctmpyppk90d34p3jjy658zf5a5l3w8wk35wht6ccqj4mr0yv8s4j5awr' + ), + spotPriceDestDenom: 'uosmo', + destCoinId: 'osmosis', +}, +``` +- Pool 648: + - This pool contains an IBC-multihop token. Note how all transfer paths are included. +``` +{ + alternativeCoinId: 'pool:pstake', + poolId: '648', + spotPriceSourceDenom: DenomHelper.ibcDenom( + [ + { portId: 'transfer', channelId: 'channel-4' }, + { portId: 'transfer', channelId: 'channel-38' }, + ], + 'gravity0xfB5c6815cA3AC72Ce9F5006869AE67f18bF77006' + ), + spotPriceDestDenom: 'uosmo', + destCoinId: 'osmosis', +}, +``` + +Example of osmosis-frontend/packages/web/config/chain-infos.ts::chainInfos: +- Umee chain info: + - Note that `coinGeckoId: 'pool:uumee',` is specified three times, once under each listing of the currency + - Note: once UMEE gets a listing and live price feed on CoinGecko, the values here should then be replaced with the CoinGeckoID, e.g., `coingGeckoId: 'umee'` +``` +{ + rpc: 'https://rpc.aphrodite.main.network.umee.cc', + rest: 'https://api.aphrodite.main.network.umee.cc', + chainId: 'umee-1', + chainName: 'Umee', + bip44: { + coinType: 118, + }, + bech32Config: Bech32Address.defaultBech32Config('umee'), + currencies: [ + { + coinDenom: 'UMEE', + coinMinimalDenom: 'uumee', + coinDecimals: 6, + coinGeckoId: 'pool:uumee', + coinImageUrl: window.location.origin + '/public/assets/tokens/umee.png', + isStakeCurrency: true, + isFeeCurrency: true, + }, + ], + features: ['stargate', 'ibc-transfer', 'no-legacy-stdTx'], + explorerUrlToTx: 'https://www.mintscan.io/umee/txs/{txHash}', +}, +``` \ No newline at end of file diff --git a/docs/overview/integrate/token-listings.md b/docs/overview/integrate/transfer.md similarity index 57% rename from docs/overview/integrate/token-listings.md rename to docs/overview/integrate/transfer.md index 050e8e698..fae84d031 100644 --- a/docs/overview/integrate/token-listings.md +++ b/docs/overview/integrate/transfer.md @@ -1,26 +1,27 @@ -# Token Listings +--- +sidebar_position: 3 +--- -## How to create a new pool with IBC assets +# Connect with Osmosis Osmosis is a automated market maker blockchain. This means any IBC-enabled zone can add its token as an asset to be traded on Osmosis AMM completely permissionlessly. Because Osmosis is fundamentally designed as an IBC-native AMM that trades IBC tokens, rather than tokens issued on the Osmosis zone, there are additional nuances to understand and steps to be taken in order to ensure your asset is supported by Osmosis. This document lays out the prerequisites and the process that is needed to ensure that your token meets the interchain UX standards set by Osmosis. -### Prerequisites +## Prerequisites 1. Zone must have IBC token transferred enabled (ICS20 standard). 2. Assets to be traded should be a fungible `sdk.Coins` asset. 3. Highly reliable, highly available altruistic (as in relay tx fees paid on behalf of user) relayer service. 4. Highly reliable, highly available, and scalable RPC/REST endpoint infrastructure. - -### 0. Enabling IBC transfers +## Enabling IBC transfers Because only IBC assets that have been transferred to Osmosis can be traded on Osmosis, the native chain of the asset must have IBC transfers enabled. Cosmos defines the fungible IBC token transfer standard in [ICS20](https://github.com/cosmos/ibc/tree/master/spec/app/ics-020-fungible-token-transfer) specification. At this time, only chains using Cosmos-SDK v0.40+ (aka Stargate) can support IBC transfers. -Note that IBC transfers can be enabled via: +IBC transfers can be enabled: 1. as part of a software upgrade, or -2. a `ParameterChange` governance proposal +2. via a `ParameterChange` governance proposal To ensure a smooth user experience, Osmosis assumes all tokens will be transferred through a single designated IBC channel between Osmosis and the counterparty zone. @@ -28,14 +29,14 @@ Recommended readings: * [IBC Overview](https://docs.cosmos.network/master/ibc/overview.html) - To understand IBC clients, connections, * [How to Upgrade IBC Chains and their Clients](https://docs.cosmos.network/master/ibc/upgrades/quick-guide.html) -### 1. Add your chain to cosmos/chain-registry and SLIP73 +### Not on a Cosmos-SDK chain? +Several intermediary chains are in use or being developed that link the IBC enabled Cosmos with other ecosystems. -#### Cosmos Chain Registry -Make a PR to add your chain's entry to the [Cosmos Chain Registry](https://github.com/cosmos/chain-registry). This allows Osmosis frontend to suggest your chain for asset deposit/withdrawals(IBC transfers). +For EVM chains, Osmosis [voted](https://www.mintscan.io/osmosis/proposals/206) to use [Axelar](https://axelar.network/) as its canonical bridge. This connects Osmosis to networks such as Ethereum, Avalanche, Arbitrum, Binance Smart Chain, Celo, Fantom, Polkadot and Polygon. -Make sure to include at least one reliable RPC, gRPC, REST endpoint behind https. Refer to the [Osmosis entry](https://github.com/cosmos/chain-registry/blob/master/osmosis/chain.json) as an example. +Any token added to the Axelar bridge is enabled for transfer to Osmosis and gains access to permissionless listing. -### 2. Setting up and operating relayer to Osmosis +## Setting up and operating a relayer to Osmosis Relayers are responsible of transferring IBC packets between Osmosis chain and the native chain of an asset. All Osmosis 'deposits' and 'withdrawals' are IBC transfers which dedicated relayers process. To ensure fungibility amongst IBC assets, the frontend will assume social consensus have been achieved and designate one specific channel between Osmosis and the native chain as the primary channel for all IBC token transfers. Multiple relayers can be active on the same channel, and for the sake of redundancy and increased resilience we recommend having multiple relayers actively relaying packets. It is recommended to initialize the channel as an unordered IBC channel, rather than an ordered IBC channel. @@ -53,34 +54,30 @@ At this time, Osmosis requires that all relayers to pay for the transaction fees If you prefer not to run your own chain's relayer to Osmosis, there may be various entities ([Cephalopod Equipment Corp.](https://cephalopod.equipment/), [Vitwit](https://www.vitwit.com/), etc) that provide relayers-as-a-service, or you may reach out to various validators in your ecosystem that may be able to operate a relayer. The Osmosis team does **not** provide relayer services for IBC assets. -#### SLIP73 bech32 prefix -Add your chain's bech32 prefix to the [SLIP73 repo](https://github.com/satoshilabs/slips/blob/master/slip-0173.md). The bech32 prefix should be a unix prefix, and only mainnet prefixes should be included. - - -### 3. Making a PR to Osmosis/assetlists -Due to the permissionless nature of IBC protocol, the same base asset transferred over two different IBC channels will result in two different token denominations. +## Register a bech32 Prefix onto SLIP173 -Example: -* `footoken` transferred to `barchain` through `channel-1`: `ibc/1b3d5f...` -* `footoken` transferred to `barchain` through `channel-2`: `ibc/a2c4e6...` +CosmosSDK Chain addresses can be represented with a chain-specific string preceding a hash, which helps identify to which chain an address belongs. They are registered on [SLIP173](https://github.com/satoshilabs/slips/blob/master/slip-0173.md) -In order to reduce user confusion and prevent token non-fungibility, Osmosis frontends are recommended to designate one specific channel as the primary channel for the chain's assets. The Osmosis will only show the IBC token denomination of the designated channel as with the original denomination (i.e. ATOM, AKT, etc). - -Therefore, Osmosis uses [Assetlists](https://github.com/osmosis-labs/assetlists) as a way to designate and manage token denominations of IBC tokens. - -Please create a pull request with the necessary information to allow your token to be shown in its original denomination, rather than as an IBC token denomination. - -If you need to verify the base denom of an IBC asset, you can use `{REST Endpoint Address} -/ibc/applications/transfer/v1beta1/denom_traces` for all IBC denoms or `{REST Endpoint Address} -/ibc/applications/transfer/v1beta1/denom_traces/{hash}` for one specific IBC denom. (If you need an RPC/REST endpoint for Osmosis, [Figment DataHub](https://datahub.figment.io) provides a free service for up to 100k requests/day.) +### Prerequisites -### 4. Creating a pool on Osmosis -Please refer to the [`create-pool` transaction example on the Osmosis repository](https://github.com/osmosis-labs/osmosis/tree/main/x/gamm#create-pool) on how to create a pool using your IBC tokens. +- Chain configured to use bech32 prefixes in wallet addresses + - Note: A bech32 prefix may still be registered, even before the chain is configured to use the prefixes, but only if the configuration will happen soon. -Recommended are: -* 50:50 OSMO-Token pool with 0.2% swap fee and 0% exit fee -* 50:50 ATOM-Token pool with 0.3% swap fee and 0% exit fee +### Requirements +- Chain data: + - Chain name + - Chain website + - bech32 prefix(es) + - Mainnet + - Testnet (optional) + - Regtest (optional) + - Note: The bech32 prefix must be unique among all registered prefixes. E.g., a new mainnet prefix cannot match a prefix already registered as a testnet prefix. +- Basic understanding of GitHub, knowing how to fork, create a branch, commit changes, and submit a Pull Request +### Steps -Guide created by dogemos. +1. Review the [SLIP173 Registry](https://github.com/satoshilabs/slips/blob/master/slip-0173.md): +2. Submit a pull request with necessary changes to the following: + - `slip-0173.md`: + - Add the chain name (as a link to the website) and prefix(es) into the *Registered human-readable parts* table \ No newline at end of file diff --git a/docs/overview/osmo.md b/docs/overview/osmo.md deleted file mode 100644 index 67e738260..000000000 --- a/docs/overview/osmo.md +++ /dev/null @@ -1,21 +0,0 @@ -# OSMO - -## Purpose - -The OSMO token is a governance token that allows staked token holders to decide the future of the protocol, including every implementation detail. OSMO will initially be used for the following (although governance is free to add or remove these functions): - -- Voting on protocol upgrades -- Allocating liquidity mining rewards for bonded liquidity gauges -- Setting the base network swap fee - -Governance is the critical component of how Osmosis evolves. Active stakeholders of the network will be responsible for proposing, vetting, and passing protocol upgrades. - -The pools eligible for liquidity rewards will be selected by OSMO governance participants, allowing the stakeholders to formulate an incentivization strategy that best aligns with the long-term interests of the protocol. - -## Superfluid Staking - -The OSMO token is also minted and burned in the context of Superfluid Staking. As a Osmosis-specific feature, Superfluid Staking provides the consensus layer more security with a sort of "Proof of Useful Stake". Each person gets an amount of Osmo representative of the value of their share of liquidity pool tokens staked and delegated to validators, resulting in the security guarantee of the consensus layer to also be based on GAMM LP shares. - -Further details can be seen in the [Superfluid module specifications](/osmosis-core/modules/superfluid/) - - diff --git a/docusaurus.config.js b/docusaurus.config.js index ae7629d69..b9527e528 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -137,7 +137,7 @@ const config = { items: [ { label: 'Overview', - to: '/overview', + to: 'overview/educate', position: 'left', }, { diff --git a/src/pages/index.jsx b/src/pages/index.jsx index 93ac39af2..c1c5695f0 100644 --- a/src/pages/index.jsx +++ b/src/pages/index.jsx @@ -29,7 +29,7 @@ export default function Homepage() { return (
@@ -37,7 +37,7 @@ export default function Homepage() {

Osmosis Docs

- The Osmosis blockchain is a decentralized network, ran by 100+ validators and full nodes, with many front-ends and development teams on it. Explore our docs and examples to quickly learn, develop & integrate with the Osmosis blockchain. + The Osmosis blockchain is a decentralized network, run by 150+ validators and full nodes, with many front-ends and development teams on it. Explore our docs and examples to quickly learn, develop & integrate with the Osmosis blockchain.

router.push('/osmosis-core/')}> Get Started → @@ -70,18 +70,29 @@ to="https://cli.osmosis.zone/"
} /> + +