Skip to content

Commit 9402575

Browse files
dzmitry-lahodadzmitry-lahoda
committed
fin tech
1 parent 5ad9eb8 commit 9402575

19 files changed

+1053
-253
lines changed

‎.vscode/settings.json

+8-2
Original file line numberDiff line numberDiff line change
@@ -15,10 +15,16 @@
1515
"git.postCommitCommand": "sync",
1616
"files.defaultLanguage": "markdown",
1717
"files.exclude": {
18-
"**/node_modules": true
18+
"**/node_modules": true,
19+
"**/target/**": true,
20+
"**/bin/**": true,
21+
"**/obj/**": true,
1922
},
2023
"files.watcherExclude": {
21-
"**/node_modules": true
24+
"**/node_modules": true,
25+
"**/bin/**": true,
26+
"**/target/**": true,
27+
"**/obj/**": true,
2228
},
2329
"vscodeMarkdownNotes.noteCompletionConvention": "noExtension",
2430
"vscodeMarkdownNotes.slugifyMethod": "github-slugger",

‎How IBC-ICS20 and XCM can be encoded during transfers.md

+205
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
# Overview
2+
3+
Purpose of this document to show simple IBC-ICS20 and XCM transfers flows.
4+
5+
Describes assets identifiers on each chain and asset allowance scenarios(governance).
6+
7+
> This is not RFC and not initiative.
8+
> It devoted to help shared understanding on how things work according protocols.
9+
## How assets are transferred?
10+
11+
Underlying mechanics ensure correctness of transfers, see references for details. Not discussed here.
12+
13+
All transfers map `on the wire` (remote, foreign) asset identifiers to and from `local`.
14+
15+
`NOTE: This text uses remote to number mapping as explainer. Hashes for transfers would work too`
16+
`
17+
Will start from specific examples and go to more real multihop generalized examples.
18+
19+
Assets transfers require allowance to be transferred and stored on accounts.
20+
So we touch governance for basic "fees".
21+
22+
### Specific examples of transfer
23+
24+
**Each bold** section outlines separate consensus transformation.
25+
26+
#### DOT from Polkadot to Picasso
27+
28+
Let transfer forward.
29+
30+
**Polkadot**
31+
32+
We send *Native*, zero(0) asset configured as *DOT = XcmLocation(parents = 0, junctions = Here)*.
33+
34+
`NOTE: We use *DOT* symbol in this text, on chain it is never used for transfers, it is just for us to describe flow`
35+
36+
**Composable**
37+
38+
Upon receive we have *Sender = XcmLocation(parents = 1, junctions = Here)* and asset to be *X = XcmLocation(parents = 0, junctions = Here)*.
39+
40+
`NOTE: We use *X*, as *X* is not yet known to be *DOT* `
41+
42+
*pallet-xcm* prefixes asset with sender, and we get *X = XcmLocation(parents = 1, junctions = Here)*.
43+
44+
`NOTE: *pallet-xcm* is really [several pallets and configs](./xcmp/xcmp.runtime.dot)
45+
After that *assets configuration* maps *X* to *DOT = 2*.
46+
`NOTE: *2*is just number for simplicity`.
47+
`NOTE: *assets configuration* can be implemented several ways, possible examples shown later`
48+
49+
*pallet-ibc* calls *assets configuration* to map *2* number to *2* string.
50+
51+
`NOTE: so *DOT* asset has XCM remote location in *assets configuration*, but for *pallet-ibc* transfer happens if asset is local`
52+
53+
**Picasso**
54+
55+
Upon receive of ICS20 transfer of *2*, *pallet-ibc* maps it to *transfer/channel-0/2* asset, and then *pallet-ibc* asks *assets configuration* to map prefixed denomination to local *DOT = 1002*.
56+
57+
`NOTE: well known *transfer* is *IBC Source Port on Composable*, and *channel-0* is *IBC Source Channel on Composable*(with counter)`
58+
59+
`NOTE: We have to open channels and setup mapping before send`
60+
61+
`NOTE: We could map to same number for convenience, so *DOT* could be *2* on both chains`
62+
63+
**Done**.
64+
65+
### DOT from Picasso to Polkadot
66+
67+
Let transfer back.
68+
69+
**Picasso**
70+
71+
We call *pallet-ibc* *transfer* with asset *DOT = 1002*.
72+
73+
*DOT* local asset is mapped to became *transfer/channel-0/2* and sent via IBC.
74+
75+
`NOTE: so you see we mapping of local asset to IBC asset here`
76+
77+
**Composable**
78+
79+
Asset prefix removed by *pallet-ibc* to form *2* string. And mapped to *DOT = 2* by *assets configuration*.
80+
81+
*2* is mapped to *XcmLocation(parents = 1, junctions = Here)* remote location by *assets*.
82+
83+
XCM sent.
84+
85+
**Polkadot**
86+
87+
`pallet-xcm` maps ` XcmLocation(parents = 1, junctions = Here)` to ` XcmLocation(parents = 0, junctions = Here)` to Native, zero(0) asset.
88+
89+
**Done**.
90+
91+
### Generalization
92+
93+
We have chains *A*, *B*, *C*, *D*.
94+
95+
#### Topology *A - XCM - B - IBC - C - XCM - D*
96+
97+
Real world would be Polkadot -> Composable -> Picasso -> Moonbeam.
98+
99+
**Forward**
100+
101+
A. *XcmLocation(< as it is here>)*
102+
103+
B. *XcmLocation(< as it sent by A>) -> XcmLocation(< rewrite ancestry to point to A>) -> LocalIdOnB -> LocalIdOnBAsString -> IBC-ICS20 prefixed denomination(LocalIdOnBAsString)*
104+
105+
C. *IBC-ICS20 prefixed denomination(LocalIdOnBAsString) -> IBC-ICS20 prefixed denomination(sourcePortOnB/sourceChannelOnB/LocalIdOnBAsString) -> LocalIdOnC -> XcmLocation( < LocalIdOnC as here> )*
106+
107+
`NOTE: See how asset above also it is foreign because from B, but on bridge switch it became local and mapped to XCM remote`
108+
109+
`NOTE: Invariant is that foreign asset has can have one and only one remote location, but configured as "local" when sent to other channels.`
110+
111+
D. *XcmLocation( < LocalIdOnC as here> ) -> XcmLocation( < LocalIdOnC prefixed with route from Origin > ) -> LocalIdOnD*
112+
113+
> Local asset has no true remote location (None), foreign asset has one and only one remote location.
114+
#### Try other transfer flows
115+
116+
Just list we can expand as reasonable to run in future:
117+
118+
1. *A - IBC - B - XCM - C - IBC - D*
119+
120+
2. *A - IBC - B - IBC - C - IBC - D*
121+
122+
Multihop IBC and XCM are supported.
123+
124+
### Some possible user experiences
125+
126+
In case of PBLO. On Picasso is *100*. So it is Local asset. When sent via IBC to other chain, it will get IBC prefix mapping, app can show *ibcPBLO* because of that.
127+
128+
In case of USDT, USDT from Statemine can be show as xcmUSDT(because it is common good parachain prefix). USDT from Cosmos can be ibcUSDT.
129+
Later, when there would be IBC/XCM to ETH, new *assets* module to be created which classifies not only bridge, but prefix(channel) used.
130+
131+
`NOTE: XCVM/CW to be defined in some other document later, likely that would be own bridge type`
132+
133+
## How `assets routes` are created
134+
135+
Currently ICS20 allows to send only 1 asset which are allowed to pay fee for storage(ED) on destination.
136+
137+
Governance should allow such assets explicitly.
138+
139+
140+
### For DOT from Polkadot to Picasso
141+
142+
**Composable**
143+
144+
Governance defines prefix of *XcmLocation(parents = 1, junctions = Here)* in *pallet-xcm* (and open relevant channel).
145+
146+
Governance opens channel to *IBC Picasso* and gets well known *transfer/channel-0/* prefix.
147+
148+
Above are "handshakes".
149+
150+
151+
Governance defines bimap of *XcmLocation(parents = 1, junctions = Here)* to *2*.
152+
153+
Governance makes *2* asset as payable(defines conversion ratio to Native).
154+
155+
Governance makes *2* bimap to metadata (may be "DOT" symbol, not used for fees or transfers). But used in user experience.
156+
157+
**Picasso**
158+
159+
Governance defines bimap *portOnComposable/channelOnComposable/2* to *1002*.
160+
161+
Governance makes *DOT* bimap to metadata (not used for fees or transfers). But used in user experience.
162+
163+
`NOTE: DOT symbol may or may be not different value. It can be prefixed *ibc() depending if there is *remote* IBC mapping for it`
164+
165+
`NOTE: multihop infrastructure for user can be built on top later`
166+
167+
### On local and remote difference regarding expected configuration
168+
169+
#### Foreign asset
170+
Has well known remote prefix (like XCM origin or IBC port), suffix part is fully controlled by counterparty and may vary.
171+
When received is usually minted, and when send back to origin is usually burnt.
172+
`NOTE: If send downward or to sibling bridge, start acting as local asset for that end, but still yet on this chain identifies as foreign`
173+
`NOTE: In future when IBC will support transfer of multiple assets and we will support non sufficient assets,
174+
may consider define prefix and wildcard to avoid storing big one to on map and become more permissonless`
175+
176+
#### Local asset
177+
Does not have remote IBC or XCM location which indicates that it was bridged.
178+
May have some convetion how to form prefix and well known suffix when sent sibling or downward by bridges.
179+
The convetion usually idenfifies local consesus protocol/pallet/contract which *governs* asset.
180+
Is escrowed on sent, does not allows transer back more than escrowed.
181+
182+
#### Teleport assets
183+
Considers some foreign and local assets to be equivalent. Likely should be separate asset configuration.
184+
185+
186+
## References
187+
188+
[ICS20: Fungible Token Transfer](https://github.com/cosmos/ibc/tree/main/spec/app/ics-020-fungible-token-transfer)
189+
190+
[CW20 Spec: Fungible Tokens](https://github.com/CosmWasm/cw-plus/blob/main/packages/cw20/README.md)
191+
192+
[RFC013](https://github.com/ComposableFi/composable/pull/2954)
193+
194+
https://github.com/CosmWasm/cw-plus/blob/main/packages/cw20/src/denom.rs
195+
196+
https://github.com/paritytech/xcm-format
197+
198+
https://github.com/cosmos/ibc/tree/main/spec/app/ics-029-fee-payment
199+
200+
https://github.com/cosmos/cosmos-sdk/blob/main/types/coin.go
201+
202+
https://ibc.cosmos.network/main/architecture/adr-001-coin-source-tracing.html
203+
204+
205+
https://media.githubusercontent.com/media/cosmos/ibc/old/papers/2020-05/build/paper.pdf

‎How to open Dotsama XCMP HRMP channel.md

+157
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
---
2+
title: How to open Dotsama XCMP HRPM channel
3+
---
4+
5+
# Overview
6+
7+
This document describes all technical steps required to open a channel to any arbitrary chain.
8+
9+
Please adapt this to the variation of governance, business value and discussion forums according to the target chains.
10+
11+
This guide contains examples and links with guiding explanations on how to modify this for the next channel.
12+
13+
## Assumptions
14+
15+
This guide assumes the following conditions:
16+
- You can get a minimum of 30 KSM and up to 70 KSM equivalent to handle end to end process
17+
18+
- You are aware of how to use Polkadotjs and open relevant chains
19+
20+
- You have a basic understanding of Dotsama encodings and the basics of XCM
21+
22+
- You are aware of how Root transactions can be executed on the target chain
23+
24+
- Transaction execution starts from Root unless stated otherwise
25+
26+
## Identity and communication mediums
27+
28+
29+
- Create on chain and off chain identity on [polkassembly]
30+
31+
- Login to https://matrix.to/#/#kusama:matrix.parity.io to observe discussions
32+
33+
- Each chain may have its own chat to find
34+
35+
36+
## Minimum amount of native tokens for relay tip
37+
38+
39+
Check that the chains involved have enough relay native tokens.
40+
41+
As of now this is in `Storage -> configuration -> activeConfig` related to channels.
42+
43+
The minimal amount of relay native token required is `hrmpSenderDeposit` + `hrmpRecipientDeposit`. It's recommended to have 2x the minimal amount.
44+
45+
Chain accounts can be obtained by mapping a parachain id to an account via [substrate-js-utilities]
46+
47+
48+
## Send Request to open channel to counterparty parachain
49+
50+
Example, [0x290001010002100004000000000b0060defb740513000000000b0060defb74050006000700f2052a01383c00e8030000e8030000009001000d0100040001009d20](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fpicasso-rpc.composable.finance#/extrinsics/decode/0x290001010002100004000000000b0060defb740513000000000b0060defb74050006000700f2052a01383c00e8030000e8030000009001000d0100040001009d20).
51+
52+
It will request to open `hrmp` to other parachain
53+
54+
It will execute a request to open a channel (half of future duplex).
55+
56+
**Details**
57+
58+
A message will be sent to the relay and pay all fees in the relay native(example, KSM) tokens.
59+
60+
Ensure the transaction is executed from `Native` (Parachain itself) `originType`
61+
62+
Ensure the function `DepositAsset` will deposit to the relevant Parachain identifier (spending chain).
63+
Specifically `0, X1(Parachain(2087))`.
64+
65+
Ensure `requireWeightAtMost` is safely larger (e.g. 2-3x) than the weight of the transact.
66+
67+
`Developer -> [Runtime Calls](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Frpc.ibp.network%2Fkusama#/runtime) -> TransactionPaymentCallApi -> queryCallInfo -> weight`
68+
but strictly (and if possible safely) less than `requireWeightAtMost`.
69+
70+
`requireWeightAtMost` should be equivalent or less than in `BuyExecution` (you can compare it to the `queryCallInfo.partialFee` of the call and make `BuyExecution` 10x+ larger than this). In case of failure to do so, XCM will fail with `TooExpensive`
71+
72+
Do not set `requireWeightAtMost` too big as you will get `dmpQueue.OverweightEnqueued`. `requireWeightAtMost` has some similar semantics to `requireWeightMinimum`. It is not clear if the message will be retried automatically. For a sanity check navigate to `configuration -> activeConfig -> umpMaxIndividualWeight` and see if it is way higher than the weight of our transact.
73+
74+
`NOTE: above details apply to other requests too`.
75+
76+
For additional safety consider scheduling the transact messages instead of executing immediately.
77+
78+
[0x3c00e8030000e803000000900100](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fkusama-rpc.polkadot.io#/extrinsics/decode/0x3c00e8030000e803000000900100).
79+
80+
Check that:
81+
82+
- The `Transact` message contains a proper existing parachain recipient.
83+
84+
- `proposedMaxCapacity` is less or equal to `Storage -> configuration -> activeConfig` `hrmpChannelMaxCapacity`
85+
86+
- `proposedMaxMessageSize` is less or equal to `hrmpChannelMaxMessageSize` here.
87+
88+
- `hrmpMaxParachain*Channels` is not exceeded by any participant chains.
89+
## Counterparty chain to accept our request and request back
90+
91+
Encode the preimage above via `Democracy -> Submit preimage`.
92+
93+
Then `Submit proposal`.
94+
95+
https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fkarura-rpc-3.aca-api.network%2Fws#/extrinsics/decode/0x33000101000210000400000000070010a5d4e81300000000070010a5d4e800060003009435775c1802083c01270800003c0027080000e8030000009001000d010004000100411f
96+
97+
**Details**
98+
99+
Find the latest `proposal` or successful `referenda` to open channels and compare differences with our message. Things change so the further examples are likely to be out of date.
100+
101+
Please do all relevant checks from the previous step.
102+
103+
## Accept on our chain request
104+
105+
This should be executed
106+
107+
[Accept Open Channel on Kusama from 2001 example](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fkusama.api.onfinality.io%2Fpublic-ws#/extrinsics/decode/0x3c01d1070000)
108+
109+
as message from our chain
110+
111+
[Send XCM to accept from Picasso to Kusama for chain 2001](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fpicasso-rpc.composable.finance#/extrinsics/decode/0x2900010100020c000400000000070010a5d4e81300000000070010a5d4e80006010700e8764817183c01d0070000)
112+
113+
it must be send from [sudo](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fpicasso-rpc.composable.finance#/extrinsics/decode/0x020029000101000214000400000000070010a5d4e81300000000070010a5d4e80006000300943577183c01d1070000140d0100040001009d20)
114+
115+
116+
**Details**
117+
118+
All relevant check steps similar to before do apply.
119+
120+
Additionally check that there is `hrmp` open channel request to us.
121+
122+
## Tokens and transfers
123+
124+
Follow relevant guides.
125+
126+
You may find some [examples](./xcm-examples.md)
127+
128+
[polkassembly]:https://parachains.polkassembly.io/
129+
130+
[karura-gov]: https://karura.subsquare.io/democracy/
131+
132+
[substrate-js-utilities]: https://www.shawntabrizi.com/substrate-js-utilities
133+
134+
[moonbeam]: (https://docs.moonbeam.network/builders/xcm/xc-integration/)
135+
136+
137+
## References
138+
139+
https://docs.acalaswap.app/developer-guides/create-a-new-token
140+
141+
https://wiki.acala.network/build/development-guide/composable-chains/open-hrmp-channel
142+
143+
https://acala.notion.site/Acala-Karura-Token-Listing-Playbook-c6b97e022ac6402cb15ce3cb419c48e5
144+
145+
https://wiki.acala.network/integrate/integration-1/token-transfer
146+
147+
https://acala.discourse.group/t/open-hrmp-channel-between-composable-picasso-and-karura/918
148+
149+
https://karura.subsquare.io/democracy/proposal/
150+
151+
https://kusama.polkassembly.io/referendum/163
152+
153+
https://kusama.polkassembly.io/referendum/164
154+
155+
https://acala.discourse.group/t/open-hrmp-channel-between-karura-and-statemine/451
156+
157+
https://acala.discourse.group/t/open-hrmp-cross-chain-communication-between-bifrost-and-karura-parachain/316/7

‎fin.hs

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
#!/usr/bin/env nix-shell
2+
#!nix-shell --pure -i runghc -p "haskellPackages.ghcWithPackages (pkgs: [ pkgs.turtle ])"
3+
4+
-- Buy
5+
data Bid a = Bid { maximum_amount :: a } deriving (Show)
6+
-- Sell/Ask
7+
data Offer a = Offer { man_amount :: a } deriving (Show)
8+
9+
main = do
10+
putStrLn "Hello world from a distributable Haskell script!"

0 commit comments

Comments
 (0)