Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update XCM SDK docs for ethersSigner to evmSigner changes #747

Merged
merged 7 commits into from
Sep 21, 2023
Merged

Update XCM SDK docs for ethersSigner to evmSigner changes #747

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
90c123b
change ethersSigner for evmSigner
mmaurello Sep 8, 2023
2ecd248
update xcm-sdk tutorial with viem wallet client
mmaurello Sep 12, 2023
e6c1645
capitalize ethers
mmaurello Sep 12, 2023
1d5f89e
Merge pull request #746 from mmaurello/allow-viem-client
eshaben Sep 14, 2023
daf2761
use viem locally and apply minor fixes
eshaben Sep 15, 2023
9db05df
add disclaimer
eshaben Sep 15, 2023
ea157dd
fix typo
eshaben Sep 19, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions builders/interoperability/xcm/xcm-sdk/v1/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,9 +126,9 @@ The SDK provides the following core methods:
- `Sdk()` - exposes the methods of the XCM SDK. **Must be called first to access other SDK methods**

??? code "Parameters"
| Name | Type | Description |
|:----------:|:------------:|:-----------------------------------------------------------:|
| `options?` | *SdkOptions* | Allows you to specify an `ethersSigner` or `polkadotSigner` |
| Name | Type | Description |
|:----------:|:------------:|:--------------------------------------------------------:|
| `options?` | *SdkOptions* | Allows you to specify an `evmSigner` or `polkadotSigner` |

??? code "Returns"
| Name | Type | Description |
Expand All @@ -139,15 +139,15 @@ The SDK provides the following core methods:
- `getTransferData()` - builds the data necessary to transfer an asset between a source chain and a destination chain

??? code "Parameters"
| Name | Type | Description |
|:-----------------------:|:--------------------------------:|:--------------------------------------------------------------------------------------:|
| `destinationAddress` | *string* | The address of the receiving account on the destination chain |
| `destinationKeyorChain` | *string \| AnyChain* | The key or `Chain` data for the destination chain |
| `ethersSigner?` | *EthersSigner* | The Ethers signer for Ethereum-compatible chains that use H160 Ethereum-style accounts |
| `keyOrAsset` | *string \| Asset* | The key or `Asset` data for the asset being transferred |
| `polkadotSigner?` | *PolkadotSigner \| IKeyringPair* | The Polkadot signer or Keyring pair |
| `sourceAddress` | *string* | The address of the sending account on the source chain |
| `sourceKeyOrChain` | *string \| AnyChain* | The key or `Chain` data for the source chain |
| Name | Type | Description |
|:-----------------------:|:--------------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------:|
| `destinationAddress` | *string* | The address of the receiving account on the destination chain |
| `destinationKeyorChain` | *string \| AnyChain* | The key or `Chain` data for the destination chain |
| `evmSigner?` | *EthersSigner \| WalletClient* | The signer for Ethereum-compatible chains that use H160 Ethereum-style accounts. Can be either an Ethers signer or a viem Wallet Client |
| `keyOrAsset` | *string \| Asset* | The key or `Asset` data for the asset being transferred |
| `polkadotSigner?` | *PolkadotSigner \| IKeyringPair* | The Polkadot signer or Keyring pair |
| `sourceAddress` | *string* | The address of the sending account on the source chain |
| `sourceKeyOrChain` | *string \| AnyChain* | The key or `Chain` data for the source chain |

??? code "Returns"
| Name | Type | Description |
Expand Down
145 changes: 128 additions & 17 deletions builders/interoperability/xcm/xcm-sdk/v1/xcm-sdk.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,26 +23,40 @@ To get started with the Moonbeam XCM SDK, you'll need to first install the SDK:
npm install @moonbeam-network/xcm-sdk
```

You'll also need to install a few additional dependencies that you'll use to interact with the SDK in this guide:
You'll also need to install a few additional dependencies that you'll use to interact with the SDK in this guide. You'll need the Polkadot.js API to create a Polkadot signer:

```bash
npm install ethers@^5.7.2 @polkadot/api @polkadot/util-crypto
npm install @polkadot/api @polkadot/util-crypto
```

You'll also need an Ethereum signer if you're interacting with an Ethereum-compatible chain like Moonbeam. This guide will cover using Ethers.js and viem. You'll need to install whichever library you want to use:

=== "Ethers.js"

```bash
npm install ethers@^5.7.2
```

=== "viem"

```bash
npm install
```

## Create Signers {: #create-signers }

When transferring assets between chains, you'll need signers in place to sign the transactions. If you're interacting with an Ethereum-compatible chain that uses standard Ethereum-style H160 addresses, such as Moonbeam, you'll need to have an Ethereum signer, more specifically an [Ethers.js](https://docs.ethers.org/v5/){target=_blank} signer. To interact with the relay chain or other parachains, you'll need a [Polkadot](https://polkadot.js.org/docs/api/){target=_blank} signer.
When transferring assets between chains, you'll need signers in place to sign the transactions. If you're interacting with an Ethereum-compatible chain that uses standard Ethereum-style H160 addresses, such as Moonbeam, you'll need to have an Ethereum signer, which can be an [Ethers.js](https://docs.ethers.org/v5/){target=_blank} signer or a [viem Wallet Client](https://viem.sh/docs/clients/wallet.html){target=_blank}. To interact with the relay chain or other parachains, you'll need a [Polkadot](https://polkadot.js.org/docs/api/){target=_blank} signer.
eshaben marked this conversation as resolved.
Show resolved Hide resolved

You can pass, for example, a [MetaMask signer into Ethers](https://docs.ethers.org/v5/getting-started/#getting-started--connecting){target=_blank} or another compatible wallet. Similarly, with Polkadot, you can [pass a compatible wallet to the signer using the `@polkadot/extension-dapp` library](https://polkadot.js.org/docs/extension/){target=_blank}.
You can pass, for example, a [browser extension wallet as a signer into Ethers](https://docs.ethers.org/v5/getting-started/#getting-started--connecting){target=_blank} or [viem](https://viem.sh/docs/clients/wallet.html#json-rpc-accounts){target=_blank}, such as MetaMask. Similarly, with Polkadot, you can [pass a compatible wallet to the signer using the `@polkadot/extension-dapp` library](https://polkadot.js.org/docs/extension/){target=_blank}.

To create a signer for Ethers.js and Polkadot.js, you can refer to the following sections.
To create an EVM signer and a Polkadot signer, you can refer to the following sections.

!!! remember
**Never store your private key or mnemonic in a JavaScript or TypeScript file.**

### Create a Ethers Signer {: #create-a-ethers-signer }
### Create a EVM Signer {: #create-a-evm-signer }

To create a Ethers signer, you can use the following code snippet:
To create an Ethers signer, you can use the following code snippet:

```js
import { ethers } from 'ethers';
Expand All @@ -52,7 +66,7 @@ const provider = new ethers.providers.WebSocketProvider('INSERT_WS_ENDPOINT', {
chainId: 'INSERT_CHAIN_ID',
name: 'INSERT_CHAIN_NAME',
});
const ethersSigner = new ethers.Wallet(privateKey, provider);
const evmSigner = new ethers.Wallet(privateKey, provider);
```

For Moonbeam specifically, you can use the following configurations:
Expand All @@ -70,7 +84,7 @@ For Moonbeam specifically, you can use the following configurations:
name: 'moonbeam',
}
);
const ethersSigner = new ethers.Wallet(privateKey, provider);
const evmSigner = new ethers.Wallet(privateKey, provider);
```

=== "Moonriver"
Expand All @@ -86,7 +100,7 @@ For Moonbeam specifically, you can use the following configurations:
name: 'moonriver',
}
);
const ethersSigner = new ethers.Wallet(privateKey, provider);
const evmSigner = new ethers.Wallet(privateKey, provider);
```

=== "Moonbase Alpha"
Expand All @@ -102,7 +116,98 @@ For Moonbeam specifically, you can use the following configurations:
name: 'moonbase',
}
);
const ethersSigner = new ethers.Wallet(privateKey, provider);
const evmSigner = new ethers.Wallet(privateKey, provider);
```

Alternatively, you can create a viem Wallet Client to pass as EVM signer:

=== "Moonbeam"

```js
import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts'
import { moonbeam } from 'viem/chains';

const privateKey = 'INSERT_PRIVATE_KEY';
const account = privateKeyToAccount(privateKey);

const evmSigner = createWalletClient({
account,
chain: moonbeam,
transport: http(),
});
```

=== "Moonriver"

```js
import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts'
import { moonriver } from 'viem/chains';

const privateKey = 'INSERT_PRIVATE_KEY';
const account = privateKeyToAccount(privateKey);

const evmSigner = createWalletClient({
account,
chain: moonriver,
transport: http(),
});
```

=== "Moonbase Alpha"

```js
import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts'
import { moonbaseAlpha } from 'viem/chains';

const privateKey = 'INSERT_PRIVATE_KEY';
const account = privateKeyToAccount(privateKey);

const evmSigner = createWalletClient({
account,
chain: moonbaseAlpha,
transport: http(),
});
```

If you want to pass in a browser extension wallet to viem, you can use the following code:

=== "Moonbeam"

```js
import { createWalletClient, custom } from 'viem';
import { moonbeam } from 'viem/chains';

const evmSigner = createWalletClient({
chain: moonbeam,
transport: custom(window.ethereum),
});
```

=== "Moonriver"

```js
import { createWalletClient, custom } from 'viem';
import { moonriver } from 'viem/chains';

const evmSigner = createWalletClient({
chain: moonriver,
transport: custom(window.ethereum),
});
```

=== "Moonbase Alpha"

```js
import { createWalletClient, custom } from 'viem';
import { moonbaseAlpha } from 'viem/chains';

const evmSigner = createWalletClient({
chain: moonbaseAlpha,
transport: custom(window.ethereum),
});
```

!!! note
eshaben marked this conversation as resolved.
Show resolved Hide resolved
Expand Down Expand Up @@ -136,7 +241,7 @@ import { Sdk } from '@moonbeam-network/xcm-sdk';
const { assets, getTransferData } = Sdk();
```

You can choose either method, as both will return the data necessary to initiate an asset transfer between the source chain and the destination chain. Using `assets` will provide additional data along the way, including the list of supported assets and, once an asset is selected, the supported source and estination chains that are able to send and receive the asset.
You can choose either method, as both will return the data necessary to initiate an asset transfer between the source chain and the destination chain. Using `assets` will provide additional data along the way, including the list of supported assets and, once an asset is selected, the supported source and destination chains that are able to send and receive the asset.

The process for using `assets` to build the transfer data is as follows:

Expand Down Expand Up @@ -204,9 +309,13 @@ const fromPolkadot = async() => {
.asset('dot')
.source('polkadot')
.destination('moonbeam')
.accounts(pair.address, ethersSigner.address {
pair,
});
.accounts(
pair.address,
evmSigner.address, // If using viem, use evmSigner.account.address
{
pair,
}
);
}

fromPolkadot();
Expand All @@ -222,7 +331,7 @@ import { Sdk } from '@moonbeam-network/xcm-sdk';

const fromPolkadot = async() => {
const data = await Sdk().getTransferData({
destinationAddress: ethersSigner.address,
destinationAddress: evmSigner.address, // If using viem, use evmSigner.account.address
destinationKeyOrChain: 'moonbeam',
keyOrAsset: 'dot',
polkadotSigner: pair,
Expand Down Expand Up @@ -695,4 +804,6 @@ The `fee` property returns the amount of fees to be paid along with information
```

!!! note
For more information on assets and asset amounts, including fees, please refer to the [XCM SDK Reference](/builders/interoperability/xcm/xcm-sdk/v1/reference#assets){target=_blank}.
For more information on assets and asset amounts, including fees, please refer to the [XCM SDK Reference](/builders/interoperability/xcm/xcm-sdk/v1/reference#assets){target=_blank}.

--8<-- 'text/disclaimers/third-party-content.md'
eshaben marked this conversation as resolved.
Show resolved Hide resolved