Polar path documentation (#319)

* Draft Signed-off-by: Chris Chinchilla <[email protected]> * Draft Signed-off-by: Chris Chinchilla <[email protected]> * Draft Signed-off-by: Chris Chinchilla <[email protected]> * Draft Signed-off-by: Chris Chinchilla <[email protected]> * Update docs/develop/09_polarpath/01_overview.md * Review Signed-off-by: Chris Chinchilla <[email protected]> * Add versions Signed-off-by: Chris Chinchilla <[email protected]> * Fix malformed tag Signed-off-by: Chris Chinchilla <[email protected]> * Draft Signed-off-by: Chris Chinchilla <[email protected]> * Remove the variable Signed-off-by: Chris Chinchilla <[email protected]> * Rewrite paths to not be broken Signed-off-by: Chris Chinchilla <[email protected]> * Update paths for release Signed-off-by: Chris Chinchilla <[email protected]> * Draft Signed-off-by: Chris Chinchilla <[email protected]> * Changes from review Signed-off-by: Chris Chinchilla <[email protected]> * Draft Signed-off-by: Chris Chinchilla <[email protected]> * Remove broken links Signed-off-by: Chris Chinchilla <[email protected]> * Change config Signed-off-by: Chris Chinchilla <[email protected]> * Fix links Signed-off-by: Chris Chinchilla <[email protected]> * Add disclaimer Signed-off-by: Chris Chinchilla <[email protected]> * Update imported file Signed-off-by: Chris Chinchilla <[email protected]> * Clarify Signed-off-by: Chris Chinchilla <[email protected]> * Fix broken pallet paths Signed-off-by: Chris Chinchilla <[email protected]> --------- Signed-off-by: Chris Chinchilla <[email protected]>
KILTprotocol · Oct 15, 2024 · e622d71 · e622d71
1 parent a0bcaae
commit e622d71
Show file tree

Hide file tree

Showing 9 changed files with 283 additions and 5 deletions.
diff --git a/docs/concepts/05_credentials/02_ctypes.md b/docs/concepts/05_credentials/02_ctypes.md
@@ -16,7 +16,7 @@ The schema defines which properties exist and what their type should be, e.g., a
 
 ## CType model JSON schema
 
-The following are all required properties of the JSON schema for [CType models](https://github.com/KILTprotocol/sdk-js/blob/master/packages/core/src/ctype/CType.schemas.ts):
+The following are all required properties of the JSON schema for CType models:
 
 -   `$id`: An **identifier**: in the format `kilt:ctype:0x{cTypeHash}`.
 -   `$schema`: A **reference to CType metaschema**: Describes what a valid CType must looks like. You can find the latest metaschema on IPFS at the following address [ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq/](ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq/).

diff --git a/docs/concepts/07_dip/04_user_account_kilt.md b/docs/concepts/07_dip/04_user_account_kilt.md
@@ -50,7 +50,7 @@ The command requires the following variables:
 -   `relayApi` The [`ApiPromise`](https://polkadot.js.org/docs/api/examples/promise/) instance for the parent relay chain.
 -   `signer` The signing callback to sign the cross-chain transaction.
 -   `submitterAddress` The address of the transaction submitter on the consumer chain.
--   `keyRelationship` The [`VerificationKeyRelationship`](https://kiltprotocol.github.io/sdk-js/types/types_src.VerificationKeyRelationship.html) required for the DIP operation authorized on the relay chain.
+-   `keyRelationship` The `VerificationKeyRelationship` required for the DIP operation authorized on the relay chain.
 
 And the following optional environment variables:
 

diff --git a/docs/develop/02_chain/04_fullnode.md b/docs/develop/02_chain/04_fullnode.md
@@ -41,7 +41,7 @@ This can either be `peregrine` or `spiritnet`.
 
 Hence, to start a full node for the Spiritnet network, the parameter would be `--chain=spiritnet`.
 Unfortunately, there is no hardcoded chain spec for the Peregrine network, so the full path of the chainspec file must be provided `--chain=/node/dev-specs/kilt-parachain/peregrine-kilt.json`.
-Please refer to the [KILT node repository](https://github.com/KILTprotocol/kilt-node/blob/master/dev-specs/kilt-parachain/peregrine-kilt.json) or the [Docker image](https://hub.docker.com/r/kiltprotocol/kilt-node/tags) for more information.
+Please refer to the [KILT node repository](https://github.com/KILTprotocol/kilt-node/blob/master/chainspecs/peregrine/peregrine-paseo.json) or the [Docker image](https://hub.docker.com/r/kiltprotocol/kilt-node/tags) for more information.
 
 ### Specify the Blockchain Storage Path
 

diff --git a/docs/develop/09_polarpath/01_overview.md b/docs/develop/09_polarpath/01_overview.md
@@ -0,0 +1,79 @@
+---
+id: what-is-polarpath
+title: Overview
+---
+
+:::version-label[polarPath]
+
+:::
+
+Polar path consists of an `asset-swap` pallet for parachain runtimes and extrinisics that let parachain developers make their native token accessible on the Ethereum network using [the Snowbridge bridge](https://docs.snowbridge.network) between Polkadot and Ethereum.
+
+Polar path provides parachains with a solution for creating an ERC-20 wrapper around their native tokens, enabling a trustless, one to one conversion of any existing native parachain token (TOKEN) into a wrapped parachain token (eTOKEN) on Ethereum while maintaining the trustlessness guarantees Snowbridge provides. The switch also sends a corresponding amount of the native token to the parachain's sovereign account on the Asset Hub (wTOKEN).
+
+## Setup
+
+:::tip Asset Hub
+The Polkadot Relay Chain doesn't natively support assets apart from DOT. Instead, parachains support this functionality, and for Polkadot, this parachain is the [Asset Hub](https://wiki.polkadot.network/docs/build-integrate-assets).
+:::
+
+Making a Parachain token usable on Ethereum requires the following steps:
+
+1. The involved AssetHub account need enough balance of wTOKEN to cover the switch. This includes the amount of the switch, fees, and an existential deposit. The balance can be in DOT, KSM, ETH, or USDC.
+
+    :::danger
+    If you don't have enough balance when you perform the switch, you will lock your funds, requiring a public KILT governance referendum to unlock them.
+    :::
+
+2. Deploy an ERC-20 contract token to Ethereum with a fixed supply based on the parachain needs.
+
+    :::tip Asset Hub
+    Usually, the total supply should match the parachain max supply.
+    :::
+
+3. [Disable the token issuer rights](https://ethereum.org/en/guides/how-to-revoke-token-access/) on the ERC-20 contract.
+4. [Register the ERC-20 token on Asset Hub](https://docs.snowbridge.network/applications/token-transfers#token-registration).
+5. The parachain must have a representative asset on the state of the reserve XCM fees asset.
+
+    For example, in the case of Asset Hub, the parachain should implement, `pallet-assets` to manage DOT on their chain.
+
+6. The entity holding ERC-20 funds performs a one-time transfer of all tokens from their Ethereum account, minus the amount of tokens previously locked with the parachain, to the parachain's sovereign account on Asset Hub.
+7. Parachain governance recognizes the wrapper around the ERC-20 token by pairing the ERC-20 token to the parachain token in the swap pallet and enable the token issuer rights.
+
+Holders of the token on the parachain can can now switch tokens between it and Ethereum.
+
+## Use cases
+
+After setup, the following flows are possible:
+
+:::tip XCM
+Polar path uses Polkadot's [Cross-Consensus Message Format (XCM)](https://wiki.polkadot.network/docs/learn-xcm), a messaging format and language used to communicate between consensus systems.
+:::
+
+### Sending tokens from the parachain to Ethereum
+
+1. Transmit custom parachain tokens, "TOKEN", from the parachain to tokens "eTOKEN" on Asset Hub via XCM
+2. Send eTOKENs from Asset Hub to the ERC-20 contract on Ethereum via Snowbridge
+
+### Sending tokens from Ethereum to the parachain
+
+1. Send eTOKENs from the ERC-20 contract on Ethereum to Asset Hub via Snowbridge
+2. Send wTOKENs on Asset Hub to TOKENs on the parachain via XCM
+
+## Extrinsics
+
+Before performing a switch, the `origin` account first needs to create a switch pair between the parachain token and the ERC-20 token using the `setSwitchPair` extrinisc. Then you can use any of the other extriniscs with the switch pair, including pausing, resuming, and performing the switch itself using the `switch` extrinisc.
+
+Read [the `switch` pallet's documentation](./02_switch_pallet.md) for more information on the extriniscs.
+
+:::tip KILT example
+The KILT parachain uses the `Root` origin account, so creating a switch pair requires a referendum to dispatch the extrinsic.
+:::
+
+:::info Local and remote assets
+A **local asset** is the identifier of the asset considered to be the parachain token.
+This is a [Junction](https://wiki.polkadot.network/docs/learn/xcm/fundamentals/multilocation-junctions) type, referring where in the current hierarchy to find the asset.
+
+A **remote asset** is the identifier of the asset considered to be the other side of the switch pair.
+For an ERC20 token, this is a [MultiLocation](https://wiki.polkadot.network/docs/learn/xcm/fundamentals/multilocation-summary) type (in XCM terms) pointing directly to an address on one of the many EVM-based deployments.
+:::