Merge pull request #201 from galacticcouncil/add-integration-docs

Add integration docs

docs/05_daos/01_omnipool_listing.md

@@ -0,0 +1,67 @@
+---
+id: omnipool_listing
+title: Omnipool Listing
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+On this page you will find the **requirements and process** for listing a project's token in the Hydration Omnipool. These requirements have been defined by the Hydration DAO.  
+
+All listings in the Omnipool must be approved individually by the governance of the Hydration DAO in a public referendum open to all HDX holders. Depending on the outcome of the referendum, the Hydration DAO may decline a listing even if all criteria have been met.
+
+## 00 Prerequisites
+
+With all tokens pooled into a single pool, we must take extra precautions to avoid exposing the Omnipool to large swings in token values due to market manipulation. Therefore the requirements for listing a token in the Omnipool are listed below. There may be exceptions, or additional criteria preventing a token from being listed in the Omnipool since it is difficult to define absolute rules that apply in all situations. The actual decision lies with HDX token holders who may still reject a token that meets all criteria and may accept a token that does not.
+
+1. The token must have already gone through price discovery for at least eight months. Must be listed on a DEX with at least \$100k liquidity and/or listed on a CEX with active market maker support maintaining a 2% depth of at least \$2k. Ideally the token is listed on at least two exchanges.
+2. Sudo control of the chain/token must have been removed or revoked. This could involve the removal of the `sudo` pallet entirely, removing a registered sudo key, or in the case of AssetHub tokens the provable burning of any administrative control over the token.
+3. The project must have active token holder governance. Ideally through the use of OpenGov. We recommend setting up automated governance notifications (such as web3alerts) to mitigate governance attacks.
+4. The project must have transparent market data available, including the ability to inspect transactions via a block explorer.
+5. The token must be sufficiently distributed to avoid individuals causing large price swings. At least 40% of the token supply must be distributed and in circulation.
+6. The token must have a market cap of at least $1M.
+7. Initial liquidity
+  - For tokens with an FDV up to \$50M, the minimum team/treasury deposit into the Omnipool is \$300k worth of tokens.
+  - For tokens with an FDV above \$50M, the minimum team/treasury deposit into the Omnipool is \$500k worth of tokens.
+
+For new projects, a typical token launch sequence would be to perform a fair token launch using a [Liquidity Boostrapping Pool (LBP)](https://docs.hydration.net/daos/lbp) followed by the LBP liquidity being deposited into an Isolated Pair. Isolated Pairs can be permissionlessly created and swaps on the Hydration platform are automatically routed through both the Omnipool and Isolated Pairs, so new projects can still create their first DEX liquidity on Hydration even before their token qualifies for listing in the Omnipool. After eight months of continued price discovery, the team can apply for the token to be listed in the Omnipool if it meets the criteria above.
+
+
+## 01 Listing Process
+
+Initial listing of a token in the Omnipool is controlled by Hydration governance.
+
+1. Open XCM channel (bidirectional HRMP channels).
+2. List the token in the Hydration asset registry.
+3. Hydration community vote on whether to allow listing the token in the Omnipool. The governance vote will not directly list the token but instead will include a remark to authorize listing in the Omnipool. Hydra community will also decide what the cap will be for the token as a percentage of overall Omnipool TVL. Currently each parachain token is capped at 5% of the Omnipool but will be lowered as the Omnipool asset list diversifies.
+3. Initial token liquidity is transferred from team or treasury into either the chain's sibling acct on the Hydration chain or into the Omnipool account (`7L53bUTBbfuj14UpdCNPwmgzzHSsrsTWBHX5pys32mVWM3C1`).
+4. Hydration DAO passes a motion (including initial asset price) to add the initial liquidity to the Omnipool and enable trading. The resulting ownership NFT will be placed in the chain's sibling acct (or designated project/team acct for non-parachain tokens).
+
+Each community should consider depositing additional tokens later to bring the deposit up to $1M or up to 2.5% of FDV, in line with other community deposits. Hydra's DCA feature allows swaps to be spread out, enabling larger trades over time, but loan liquidations need to happen within a single block and therefore deeper token liquidity enables larger money markets for the token.
+
+## 02 Managing Treasury Deposits in the Omnipool
+
+Once initial Omnipool listing has been performed, a parachain/token's governance body can control their deposit remotely over XCM. Note that as a security precaution no account can add or remove more than 5% of the liquidity of a token within a single block and therefore large deposits and withdrawals must be performed incrementally unless assisted by Hydra governance.
+
+### Depositing Additional Liquidity
+
+The general process to make a large deposit remotely is:
+1. Manually try to deposit tokens as liquidity in the Hydration UI to see what the current maximum deposit limit is.
+2. Use `xtokens.transfer` or similar to transfer the new tokens to the chain's sibling acct on Hydration (plus like 20 tokens to use to pay XCM fees)
+3. Schedule once every 1 block repeating x times to deposit a chunk of tokens into the Omnipool. LP NFTs will automatically be placed in the account that the deposit is happening from. If your chain does not have the ability to schedule XCM transactions (using the `scheduler` pallet) then you likely should seek Hydra governance assistance in performing the deposit.
+
+**Example from Centrifuge:**
+Transfer 750k CFG, then deposit 37500 tokens 20 times   (costs 0.442 CFG in XCM fees)
+encoded call data: `0x3e02083e0300016d6f646c70792f747273727900000000000000000000000000000000000000007c00000000904cbb5f69aad29e00000000000003010200c91f01007369626cef070000000000000000000000000000000000000000000000000000003f040100000001010000001400000000790003010100c91f0314000400010200bd1f060200010000000000000000000000000000000000000000000000000000000000000013000064a7b3b6e00d1300010200bd1f060200010000000000000000000000000000000000000000000000000000000000000013000064a7b3b6e00d0006010700f2052a0102000400583b020d0000000000701c7cf40ae1f007000000000000140d0100000101007369626cef070000000000000000000000000000000000000000000000000000`
+
+**Example from Phala:**
+Transfer 4.08M PHA, then deposit 48000 PHA 85 times   (costs 6.9 PHA in XCM fees)
+encoded call data: `0x030208030300016d6f646c70792f747273727900000000000000000000000000000000000000005200000000001300407db892249f38010200c91f01007369626cf30700000000000000000000000000000000000000000000000000000007040100000001010000005500000001210003010100c91f0314000400010100cd1f00070010a5d4e81300010100cd1f00070010a5d4e80006010700f2052a0102000400583b0208000000000038e5be87aa000000000000000000140d0100000101007369626cf3070000000000000000000000000000000000000000000000000000`
+
+### Removing Liquidity
+
+Omnipool liquidity must be removed using the number of each specific LP NFT. It is again limited to 5% of the liquidity for that individual token.
+
+1. Use `assetRegistry->assetIds()` to find the index for your token in the Hydration asset registry.
+2. Use `uniques->acount(acct, 1337)` to find the IDs of the LP NFTs.
+3. Use `omnipool->positions(ID)` to get the details about each LP NFT. Specifically, the `amount` of tokens it represents. If the amount is greater than 5% of the token's liquidity in the Omnipool you can't remove all of liquidity of that LP in a single block and need to split it up.
+4. Create a series of XCM messages to call `omnipool.removeLiquidity(positionID, amount)` for each of the LP NFTs.

docs/06_devs/03_remote_swaps.md

@@ -0,0 +1,25 @@
+---
+id: remote_swaps
+title: Remote swaps
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+Building cross-chain swaps.
+
+## Introduction {#intro}
+With _xcm::execute_ call being gradually whitelisted on various chains, it is now possible to use Hydration as a universal atomic swapping engine. In practice, that means withdrawing funds on one chain, sending it to Hydration, swapping the asset for another and sending it back or another chain in one transaction. This enables cross-chain swaps and opening doors for use cases such as acquiring fee payment asset for a chain before a transaction happens and allowing for much better UX.
+
+## Example {#example}
+For demonstration purposes, let's consider the following scenario:
+User has 100 DOT on the Polkadot core chain and wants to swap it for USDT and have it available on Asset Hub. User facing application can offer one signature solution with a good UX and do the heavy lifting in the background. It just needs to construct an XCM message with a correct set of instructions which will differ depending on the nativeness of the asset, or in other words, where the reserve of the swapped asset reside.
+
+The extrinsic would be in this example constructed as a _polkadotXcm.send_ call containing the following [instructions](https://github.com/paritytech/xcm-format):
+
+<div style={{textAlign: 'center'}}>
+  <img src={useBaseUrl('/img/devs/remote_swaps/xcm_execute.png')} />
+</div>
+
+## Learn more
+To know more about remote swaps, you can head over to our github repository where you can find [integration tests](https://github.com/galacticcouncil/HydraDX-node/blob/769c33d63d24356791c2f0e276350ebdc2914005/integration-tests/src/exchange_asset.rs#L341) covering more advanced scenarios.
+

docs/06_devs/04_xchain.md

@@ -0,0 +1,138 @@
+---
+id: xchain
+title: Cross-Chain Integration
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+Pursuing its mission to **enable permissionless liquidity within and beyond the Polkadot ecosystem**, Hydration generally **welcomes integrations** with other projects which would like to leverage some of the functionalities that Hydration has to offer.
+
+This page provides a **step-by-step guide** that explains how to **integrate your chain and its assets** with Hydration.
+
+## Establishing cross-chain (XC) communication {#establishing-xc}
+The Polkadot ecosystem was designed with multichain interoperability support in mind from day 1. The protocol that allows two chains to exchange Cross-Consensus messages (XCM) with each other is called **Cross-Chain Message Passing (XCMP)**. While full XCMP is still under development, a stop-gap protocol called **Horizontally Relay-routed Message Passing (HRMP)** is used by parachains to establish communication channels. An HRMP channel has the same capabilities as an XCMP channel but is more demanding on resources as messages are not routed directly between parachains, but need to first pass via the relay chain.
+
+## Onboarding projects to Hydration {#onboarding-assets}
+As Hydration is a permissionless and decentralized protocol, anyone can propose a cross-chain integration. A common case for this would be to list tokens on Hydration, bootstrapping liquidity, enable DCAing, but other use cases may also come to mind.
+
+The procedure for proposing to open a channel to Hydration consists of the following steps:
+
+### Step 0: Spark a discussion with the community {#discussion}
+Before deciding to open a new cross-chain channel, you should initiate a discussion with the broader Hydration community. This step is important because it allows users to express interest in tokens that they would like to see trading on our platform and to red-flag potentially toxic assets.
+
+To initiate the discussion, please [open a discussion thread on Subsquare](https://hydration.subsquare.io/posts/create) which touches upon the following points:
+- introduction of your project
+- how it plans to leverage the functionality offered by Hydration
+- tokenomics
+- any other important info
+
+After creating the thread, please post a link in **#gov-discussion** on the [Hydration Discord](https://discord.gg/hydration-net).
+
+### Step 1: Gather asset registry info {#asset-registry-info}
+A chain's asset registry requires metadata about its tokens to function properly. For example, our native token HDX would be registered as follows: 
+
+|Field|Example|
+|-------------|:-----------:|
+|name|Hydration|
+|symbol|HDX|
+|decimals |12|
+|existential deposit |1 HDX|
+|location| (X2, (Parachain(2034), GeneralIndex(0))|
+
+Prepare this table for all the currencies you want to register.
+
+### Step 2: Integrate on Polkadot network {#live}
+
+:::important
+Both parachain [sovereign accounts](https://substrate.stackexchange.com/questions/1200/how-to-calculate-sovereignaccount-for-parachain/1210) must have enough funds (approx. 10.1 DOT) on the relay chain to reserve a deposit for HRMP channels and to process the XCM messages.
+:::
+
+:::warning
+Always test the encoded hash of the call is valid on the appropriate chain, sending transaction data to an incorrect relay chain may lead to a loss of funds. 
+:::
+
+##### 1) Your parachain
+To initiate a request for opening a channel to Hydration on the relay chain, please follow these steps:
+
+- prepare encoded transact call that will be executed on the relay chain:
+<div style={{textAlign: 'center'}}>
+  <img src={useBaseUrl('/img/devs/xchain/hrmp_init.png')} />
+</div>
+
+ _Encoded: 0x3c00f2070000e803000000900100_
+
+:::note
+The following actions can be performed only from root origin via governance or the sudo module of the respective chain.
+:::
+
+- send an XCM message from the parachain to the relay chain using the _polkadotXcm.send_ call containing the following [instructions](https://github.com/paritytech/xcm-format):
+
+  - WithdrawAsset
+  - BuyExecution
+  - Transact (input previously prepared call here)
+  - RefundSurplus
+  - DepositAsset
+
+##### 2) Hydration
+On the Hydration side, the following actions need to be performed:
+- accept the Parachain &#8594; Hydration channel request;
+- initiate a request for opening Hydration &#8594; Parachain channel;
+- register Parachain's native asset(s) in the Hydration asset registry.
+
+You can find an example of this call [here](https://hydration.subsquare.io/democracy/referenda/158).
+
+Prepare a batch call that contains all the necessary actions and before submitting, test its successful execution in [Chopsticks](https://github.com/AcalaNetwork/chopsticks).
+
+Once tested, note the preimage via _preimage.notePreimage_ extrinsic, choose the **Root** governance track and submit the referendum proposal using e.g. PolkadotJS Apps.
+<div style={{textAlign: 'center'}}>
+  <img src={useBaseUrl('/img/devs/xchain/submit_referendum.png')} />
+</div>
+
+In order to queue the referendum for voting, a decision deposit needs to be placed.
+<div style={{textAlign: 'center'}}>
+  <img src={useBaseUrl('/img/devs/xchain/decision_deposit.png')} />
+</div>
+
+##### 3) Your parachain
+If the referendum in previous step passed and was executed successfully, hrmp channel needs to be accepted also on the other parachain. 
+ - accept Hydration &#8594; Parachain channel request on the relay chain with the following Transact call, analogically to step 1:
+<div style={{textAlign: 'center'}}>
+  <img src={useBaseUrl('/img/devs/xchain/hrmp_accept.png')} />
+</div>
+
+ _Encoded: 0x17012a080000_
+
+- send an XCM message from the parachain to the relay chain using the _polkadotXcm.send_ call containing the following [instructions](https://github.com/paritytech/xcm-format):
+
+  - WithdrawAsset
+  - BuyExecution
+  - Transact (input previously prepared call here)
+  - RefundSurplus
+  - DepositAsset
+
+ - optionally register HDX in your parachain's asset registry.
+
+##### 4) Polkadot
+Wait for one session after each acceptance for the channels to be opened.
+
+##### 5) Add icons to the Hydration app
+Open a new issue in [Hydration UI repository](https://github.com/galacticcouncil/HydraDX-ui) with title "Add icons for _projectname_" and attach icons for the chain and all assets. Icon should have maximum size of 10kB and SVG/PNG format.
+
+##### 6) Add tokens to cross-chain UI
+To add your tokens to our [Cross-chain](https://app.hydration.net/cross-chain) page, it is necessary to open a pull request to the [sdk repository](https://github.com/galacticcouncil/sdk).
+
+1. **Fork the sdk repository**.
+2. **Extend xcm-cfg package**.
+    1. If necessary, add a [new chain](https://github.com/galacticcouncil/sdk/blob/master/packages/xcm-cfg/src/chains/)
+    2. Add new [assets](https://github.com/galacticcouncil/sdk/blob/master/packages/xcm-cfg/src/assets.ts)
+    3. Add new AssetRoute to both chain config files, [Hydration](https://github.com/galacticcouncil/sdk/blob/master/packages/xcm-cfg/src/configs/polkadot/hydration/index.ts) and [your chain's](https://github.com/galacticcouncil/sdk/tree/master/packages/xcm-cfg/src/configs/polkadot)
+3. (Optional / Recommended) **Test your changes locally in developer console**.
+    1. Build the project by following [README.md](https://github.com/galacticcouncil/sdk/blob/master/README.md)
+    2. Change current directory to `/examples/xcm-transfer/`
+    3. Adjust chains, asset, adresses and balance definitions in the [index file](https://github.com/galacticcouncil/sdk/blob/master/examples/xcm-transfer/src/index.ts)
+    4. Test your changes by running `npm run dev` and check the developer console output in your browser, typically at `localhost:3000` 
+3. **Open a PR from your fork to the main repository** and wait until the workflow is approved. UI preview with your changes will be deployed and appear in the PR description.
+4. **Try sending each of the registered tokens back and forth** from one chain to the other, and verify the deposits were successful and balances configuration is correct.
+5. **Add a comment that configuration is ready to be merged.**
+
+__Congratulations for registering your tokens on Hydration, and a warm welcome from Hydration!__

docs/06_devs/05_collators/_category_.json

@@ -0,0 +1,14 @@
+{
+  "label": "Collators",
+  "collapsible": true,
+  "collapsed": true,
+  "className": "red",
+  "link": {
+    "slug": "/collators",
+    "type": "generated-index",
+    "title": "Collators"
+  },
+  "customProps": {
+    "description": ""
+  }
+}