Skip to content

Commit

Permalink
fix: Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@dudo50
dudo50 authored Jan 30, 2024
1 parent 44971f8 commit 4a4be79
Showing 1 changed file with 140 additions and 115 deletions.
255 changes: 140 additions & 115 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,59 +1,50 @@
# @paraspell/sdk

![Full name (3)](https://user-images.githubusercontent.com/55763425/197985791-fc7afa52-061d-413a-bbe9-bf1123f16a50.png)

[![npm version][npm-version-src]][npm-version-href]

[![npm downloads][npm-downloads-src]][npm-downloads-href]

[![Known Vulnerabilities](https://snyk.io/test/github/paraspell/sdk/badge.svg)](https://snyk.io/test/github/paraspell/sdk)

SDK For XCM & XCMP handling made with ❤️ by ParaSpell✨. It is no longer necessary to construct calls manually. @paraspell/sdk handles this for you. Feel free to become a magician and try your paraSPELLS 🧙✨.

##### Currently supporting 50 Polkadot & Kusama nodes list [here](https://github.com/paraspell/sdk/blob/main/docs/supportedNodes.md).

### Check out our brand new Wiki documentation! [Wiki docs](https://paraspell.github.io/docs/)

## Usage

**Install package:**

#### Since version 1.0.0

Our SDK introduced all Polkadot libraries as peer dependencies. The reason for this is, that most of the projects use these libraries in some way already and it fixes issues with unmet dependency warnings. Make sure your project has them. You can install them by following the command:

##### Install DEPS via npm||yarn||pnpm
<br /><br />

<div align="center">
<h1 align="center">@paraspell/sdk</h1>
<h4 align="center"> SDK for handling XCM asset transfers across Polkadot and Kusama ecosystems. </h4>
<p align="center">
<a href="https://npmjs.com/package/@paraspell/sdk">
<img alt="version" src="https://img.shields.io/npm/v/@paraspell/sdk?style=flat-square" />
</a>
<a href="https://npmjs.com/package/@paraspell/sdk">
<img alt="downloads" src="https://img.shields.io/npm/dm/@paraspell/sdk?style=flat-square" />
</a>
<a href="https://github.com/paraspell/xcm-sdk/actions">
<img alt="build" src="https://github.com/paraspell/xcm-sdk/actions/workflows/release.yml/badge.svg" />
</a>
<a href="https://snyk.io/test/github/paraspell/sdk">
<img alt="snyk" src="https://snyk.io/test/github/paraspell/sdk/badge.svg" />
</a>
</p>
<p>Currently supporting 50 Polkadot & Kusama nodes list <a href = "https://github.com/paraspell/sdk/blob/main/docs/supportedNodes.md"\>[here]</p>
<p>SDK documentation <a href = "https://paraspell.github.io/docs/" \>[here]</p>
</div>

<br /><br />
<br /><br />
## Installation

#### Install dependencies

```
//npm
npm install @polkadot/api @polkadot/types @polkadot/api-base @polkadot/apps-config @polkadot/util
//yarn
yarn add @polkadot/api @polkadot/types @polkadot/api-base @polkadot/apps-config @polkadot/util
//pnpm
pnpm install @polkadot/api @polkadot/types @polkadot/api-base @polkadot/apps-config @polkadot/util
pnpm||yarn||npm install @polkadot/api @polkadot/types @polkadot/api-base @polkadot/apps-config @polkadot/util
```

##### Install SDK via npm||yarn||pnpm
#### Install SDK

```
//npm
npm install @paraspell/sdk
//yarn
yarn add @paraspell/sdk
//pnpm
pnpm install @paraspell/sdk
pnpm||yarn||npm install @paraspell/sdk
```

##### Importing package to your project:

If you wish to use XCM, HRMP and XYK Pallets only you can import Builder like this:
#### Importing package to your project:

Builder pattern:
```js
import { Builder } from '@paraspell/sdk'
```

Old function like import (With assets):

Other patterns:
```js
// ESM
import * as paraspell from '@paraspell/sdk'
Expand All @@ -62,69 +53,115 @@ import * as paraspell from '@paraspell/sdk'
const paraspell = require('@paraspell/sdk')
```

## Currently implemented pallets
## Implementation

XCM pallet (Combined xTokens, polkadotXCM, ormlXTokens, XcmPallet & relayerXCM):

Builder pattern XCM & HRMP construction
```
NOTES:
- If you wish to transfer from Parachain that uses long IDs for example Moonbeam you have to add the character 'n' the end of currencyID. Eg: .currency(42259045809535163221576417993425387648n) will mean you transfer xcDOT.
- You can now use custom ParachainIDs if you wish to test in TestNet. Just add parachainID as an additional parameter eg: .to('Basilisk', 2948)
- You can now add optional parameter useKeepAlive which will ensure, that you send more than existential deposit.
```

#### Builder pattern:
```ts
//NOTE If you wish to transfer from Parachain that uses long IDs for example Moonbeam you have to add the character 'n' the end of currencyID. Eg: .currency(42259045809535163221576417993425387648n) will mean you transfer xcDOT.
//NOTE2 You can now use custom ParachainIDs if you wish to test in TestNet. Just add parachainID as an additional parameter eg: .to('Basilisk', 2948)
//NOTE3 XCM Transfer Builders now require await
//NOTE4 You can now add optional parameter useKeepAlive which will ensure, that you send more than existential deposit.
//NOTE5 API parameter in XCM messages is now optional!

//Transfer tokens from Parachain to Parachain
await Builder(/*node api - optional*/).from(NODE).to(NODE/*,customParaId - optional*/).currency(CurrencyString||CurrencyID).amount(amount).address(address).build()

//Transfer tokens from the Relay chain to Parachain
await Builder(/*node api - optional*/).to(NODE/*,customParaId - optional*/).amount(amount).address(address).build()

//Transfer tokens from Parachain to Relay chain
await Builder(/*node api - optional*/).from(NODE).amount(amount).address(address).build()

//Use keepAlive example
await Builder(/*node api - optional*/).from(NODE).amount(amount).address(address).useKeepAlive(destinationParaAPI).build()
//Transfer assets from Parachain to Parachain
await Builder(/*node api - optional*/)
.from(NODE)
.to(NODE/*,customParaId - optional*/)
.currency(CurrencyString||CurrencyID)
.amount(amount)
.address(address)
.build()
/*
EXAMPLE:
await Builder()
.from('Basilisk')
.to('Robonomics')
.currency('XRT')
.amount(1000000000000)
.address('4FCUYBMe2sbq5KosN22emsPUydS8XUwZhJ6VUZesmouGu6qd')
.build()
*/

//Transfer assets from the Relay chain to Parachain
await Builder(/*node api - optional*/)
.to(NODE/*,customParaId - optional*/)
.amount(amount)
.address(address)
.build()
/*
EXAMPLE:
await Builder()
.to('AssetHubPolkadot')
.amount(1000000000000)
.address('141NGS2jjZca5Ss2Nysth2stJ6rimcnufCNHnh5ExSsftn7U')
.build()
*/

//Transfer assets from Parachain to Relay chain
await Builder(/*node api - optional*/)
.from(NODE)
.amount(amount)
.address(address)
.build()
/*
EXAMPLE:
await Builder()
.from('AssetHubPolkadot')
.amount(1000000000000)
.address('141NGS2jjZca5Ss2Nysth2stJ6rimcnufCNHnh5ExSsftn7U')
.build()
*/

//Use keepAlive option
await Builder(/*node api - optional*/)
.from(NODE)
.amount(amount)
.address(address)
.useKeepAlive(destinationParaAPI)
.build()

//Close HRMP channels
Builder(api).from(NODE).closeChannel().inbound(inbound).outbound(outbound).build()
Builder(api)
.from(NODE)
.closeChannel()
.inbound(inbound)
.outbound(outbound)
.build()

//Open HRMP channels
Builder(api).from(NODE).to(NODE).openChannel().maxSize(maxSize).maxMessageSize(maxMsgSize).build()'
Builder(api)
.from(NODE)
.to(NODE)
.openChannel()
.maxSize(maxSize)
.maxMessageSize(maxMsgSize)
.build()'
```

Function pattern XCM & HRMP construction
#### Function pattern:

```ts
//NOTE If you wish to transfer from Parachain that uses long IDs for example Moonbeam you have to add character 'n' the end of currencyID. Eg: currency = 42259045809535163221576417993425387648n will mean you transfer xcDOT.
//NOTE2 You can now use custom ParachainIDs if you wish to test in TestNet. Just add parachainID as an additional parameter eg: .to('Basilisk', 2948)
//NOTE3 XCM Transfer Builders now require await
//NOTE4 You can now add optional parameter useKeepAlive which will ensure, that you send more than existential deposit.
//NOTE5 API parameter in XCM messages is now optional!
//Transfer tokens from Parachain to Parachain
//Transfer assets from Parachain to Parachain
await paraspell.xcmPallet.send(api?: ApiPromise, origin: origin Parachain name string, currency: CurrencyString||CurrencyID, amount: any, to: destination address string, destination: destination Parachain ID, paraIdTo?: number,)
//Transfer tokens from Parachain to Relay chain
//Transfer assets from Parachain to Relay chain
await paraspell.xcmPallet.send(api?: ApiPromise, origin: origin Parachain name string, amount: any, to: destination address string, paraIdTo?: number,)
//Transfer tokens from Relay chain to Parachain
//Transfer assets from Relay chain to Parachain
await paraspell.xcmPallet.transferRelayToPara(api?: ApiPromise, destination: destination Parachain ID, amount: any, to: destination address string,paraIdTo?: number,)
//Use keepAlive example
//Use keepAlive option
await paraspell.xcmPallet.send(api?: ApiPromise, destination: TNode, amount: string | number | bigint, to: string, paraIdTo?: number, destApiForKeepAlive?: ApiPromise)
//hrmp pallet:
//Close HRMP channels
paraspell.closeChannels.closeChannel(api: ApiPromise, origin: origin Parachain ID, inbound: number, outbound: number)
//parasSudoWrapper pallet:
//Open HRMP channels
paraspell.openChannels.openChannel(api: ApiPromise, origin: origin Parachain ID, destination: destination Parachain ID, maxSize: number, maxMessageSize: number)
```

Asset pallet construction:
#### Asset queries:

```ts
//Returns assets object from assets.json for particular node including information about native and foreign assets
Expand Down Expand Up @@ -161,7 +198,7 @@ paraspell.assets.getTNode(nodeID: number)
paraspell.NODE_NAMES
```

Node pallet operations
#### Parachain XCM Pallet queries

```js
import { getDefaultPallet, getSupportedPallets, SUPPORTED_PALLETS } from '@paraspell/sdk'
Expand All @@ -176,60 +213,48 @@ getSupportedPallets(node: TNode)
console.log(SUPPORTED_PALLETS)
```

Existential deposit query
#### Existential deposit queries
```ts
import { getExistentialDeposit } from "@paraspell/sdk";
const ed = getExistentialDeposit('Acala')
```

##### Example of usage can be found in the UI repository [here](https://github.com/paraspell/ui) or in the Astarot repository [here](https://github.com/paraspell/astarot)

##### A list of currently compatible nodes can be found [here](https://github.com/paraspell/sdk/blob/beta-pre-release/docs/supportedNodes.md)

## 💻 Development

- Clone this repository

- Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable` (use `npm i -g corepack` for Node.js < 16.10)

- Install dependencies using `pnpm install`

## 💻 Tests
- Run compilation test using `pnpm compile`

- Run linting test using `pnpm lint`

- Run updateAssets script using `pnpm updateAssets`

- Run updatePallets script using `pnpm updatePallets`

- Run tests using `pnpm test`

- Run all checks using `pnpm runAll`
- Run end to end tests using `pnpm test:e2e`

## Founded by
- Update Parachain registered assets in the map using script - `pnpm updateAssets`

[<img width="245" alt="web3 foundation_grants_badge_black" src="https://user-images.githubusercontent.com/55763425/211145923-f7ee2a57-3e63-4b7d-9674-2da9db46b2ee.png">](https://github.com/w3f/Grants-Program/pull/1245)
- Update XCM pallets in the map using script - `pnpm updatePallets`

[<img width="245" alt="web3 foundation_grants_badge_white (1)" src="https://user-images.githubusercontent.com/55763425/211069914-bbec9e28-7a0d-417b-8149-087b7f04e57e.png">](https://github.com/w3f/Grants-Program/pull/1245)
- Update existential deposits in the map using script - `pnpm updateEds`

[<img width="245" alt="kusamacommunity" src="https://user-images.githubusercontent.com/55763425/227636288-e0aa6f2a-9eb6-4af2-bc6b-d572f145a2f0.png">](https://kusama.subsquare.io/referenda/referendum/123)

[![logo-v1](https://user-images.githubusercontent.com/55763425/204865221-90d2b3cd-f2ac-48a2-a367-08722aa8e923.svg)](https://bsx.fi/)
- Run all core tests using `pnpm runAll`

## License

Made with 💛 by [ParaSpell✨](https://github.com/paraspell)

Published under [MIT License](https://github.com/paraspell/sdk/blob/main/LICENSE).

<!-- Badges -->

[npm-version-src]: https://img.shields.io/npm/v/@paraspell/sdk?style=flat-square
[npm-version-href]: https://npmjs.com/package/@paraspell/sdk
[npm-downloads-src]: https://img.shields.io/npm/dm/@paraspell/sdk?style=flat-square
[npm-downloads-href]: https://npmjs.com/package/@paraspell/sdk
[github-actions-src]: https://img.shields.io/github/workflow/status/unjs/@paraspell/sdk/ci/main?style=flat-square
[github-actions-href]: https://github.com/unjs/@paraspell/sdk/actions?query=workflow%3Aci
[codecov-src]: https://img.shields.io/codecov/c/gh/unjs/@paraspell/sdk/main?style=flat-square
[codecov-href]: https://codecov.io/gh/unjs/@paraspell/sdk
## Support

<div align="center">
<p align="center">
<a href="href="https://github.com/w3f/Grants-Program/pull/1245">
<img width="200" alt="version" src="https://user-images.githubusercontent.com/55763425/211145923-f7ee2a57-3e63-4b7d-9674-2da9db46b2ee.png" />
</a>
<a href="href="https://kusama.subsquare.io/referenda/277">
<img width="200" alt="version" src="https://github.com/paraspell/xcm-sdk/assets/55763425/9ed74ebe-9b29-4efd-8e3e-7467ac4caed6" />
</a>
<a href="href="https://bsx.fi/">
<img width="200" alt="version" src="https://user-images.githubusercontent.com/55763425/204865221-90d2b3cd-f2ac-48a2-a367-08722aa8e923.svg" />
</a>
</p>
</div>

0 comments on commit 4a4be79

Please sign in to comment.