Skip to content

Commit

Permalink
Merge pull request #957 from multiversx/new-providers-docs
Browse files Browse the repository at this point in the history 
add metamask proxy and cross window provider docs
  • Loading branch information
@dragos-rebegea
dragos-rebegea committed Aug 8, 2024
2 parents c9f5287 + 4e7037b commit 56ad626
Show file tree
Hide file tree
Showing 2 changed files with 186 additions and 6 deletions.
172 changes: 172 additions & 0 deletions docs/sdk-and-tools/sdk-js/sdk-js-signing-providers.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -522,6 +522,178 @@ console.log(message.toJSON());

[comment]: # (mx-context-auto)

## The Web Wallet Cross Window Provider

[`@multiversx/sdk-web-wallet-cross-window-provider`](https://github.com/multiversx/mx-sdk-js-web-wallet-cross-window-provider) allows the users of a dApp to log in and sign transactions using the MultiversX Web Wallet.

In order to aquire the instance (singleton) of the provider, do as follows:

```js
import { CrossWindowProvider } from "@multiversx/sdk-web-wallet-cross-window-provider";

const provider = CrossWindowProvider.getInstance();
```

Before performing any operation, make sure to initialize the provider and web wallet address:

```js
await provider.init();
provider.setWalletUrl("https://wallet.multiversx.com");
```

[comment]: # (mx-context-auto)

### Login and logout {#cross-window-login-and-logout}

Then, ask the user to log in:

```js
const address = await provider.login();

console.log(address);
console.log(provider.account);
```

In order to log out, do as follows:

```js
await provider.logout();
```

The `login()` method supports the `token` parameter, for **the native authentication flow** (always recommended, see above):

```js
const nativeAuthInitialPart = await nativeAuthClient.initialize();
await provider.login({ token: nativeAuthInitialPart });

const address = provider.account.address;
const signature = provider.account.signature;
const nativeAuthToken = nativeAuthClient.getToken(address, nativeAuthInitialPart, signature);
```

[comment]: # (mx-context-auto)

### Signing transactions {#cross-window-signing-transactions}

Transactions can be signed as follows:

```js
import { Transaction } from "@multiversx/sdk-core";

const firstTransaction = new Transaction({ ... });
const secondTransaction = new Transaction({ ... });

await provider.signTransactions([firstTransaction, secondTransaction]);

// "firstTransaction" and "secondTransaction" can now be broadcasted.
```

[comment]: # (mx-context-auto)

### Signing messages {#cross-window-signing-messages}

Arbitrary messages can be signed as follows:

```js
import { SignableMessage } from "@multiversx/sdk-core";

const message = new SignableMessage({
message: Buffer.from("hello")
});

await provider.signMessage(message);

console.log(message.toJSON());
```

[comment]: # (mx-context-auto)

## The Metamask Proxy Provider

[`@multiversx/sdk-metamask-proxy-provider`](https://github.com/multiversx/mx-sdk-js-metamask-proxy-provider) allows the users of a dApp to log in and sign transactions using the Metamask wallet by using MultiversX Web Wallet as a proxy widget in iframe.

In order to aquire the instance (singleton) of the provider, do as follows:

```js
import { MetamaskProxyProvider } from "@multiversx/sdk-metamask-proxy-provider";

const provider = MetamaskProxyProvider.getInstance();
```

Before performing any operation, make sure to initialize the provider and metamask snap web wallet address:

```js
await provider.init();
provider.setWalletUrl("https://snap-wallet.multiversx.com");
```

[comment]: # (mx-context-auto)

### Login and logout {#metamask-proxy-login-and-logout}

Then, ask the user to log in:

```js
const address = await provider.login();

console.log(address);
console.log(provider.account);
```

In order to log out, do as follows:

```js
await provider.logout();
```

The `login()` method supports the `token` parameter, for **the native authentication flow** (always recommended, see above):

```js
const nativeAuthInitialPart = await nativeAuthClient.initialize();
await provider.login({ token: nativeAuthInitialPart });

const address = provider.account.address;
const signature = provider.account.signature;
const nativeAuthToken = nativeAuthClient.getToken(address, nativeAuthInitialPart, signature);
```

[comment]: # (mx-context-auto)

### Signing transactions {#metamask-proxy-signing-transactions}

Transactions can be signed as follows:

```js
import { Transaction } from "@multiversx/sdk-core";

const firstTransaction = new Transaction({ ... });
const secondTransaction = new Transaction({ ... });

await provider.signTransactions([firstTransaction, secondTransaction]);

// "firstTransaction" and "secondTransaction" can now be broadcasted.
```

[comment]: # (mx-context-auto)

### Signing messages {#metamask-proxy-signing-messages}

Arbitrary messages can be signed as follows:

```js
import { SignableMessage } from "@multiversx/sdk-core";

const message = new SignableMessage({
message: Buffer.from("hello")
});

await provider.signMessage(message);

console.log(message.toJSON());
```

[comment]: # (mx-context-auto)

## Verifying the signature of a login token

:::note
Expand Down
20 changes: 14 additions & 6 deletions docs/sdk-and-tools/sdk-js/sdk-js.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,21 +24,29 @@ Base libraries:

Signing providers for dApps:

| Package | Docs | Source code | Description |
|--------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------|
| [sdk-hw-provider](https://www.npmjs.com/package/@multiversx/sdk-hw-provider) | [documentation](/sdk-and-tools/sdk-js/sdk-js-signing-providers#the-hardware-wallet-provider) | [Github](https://github.com/multiversx/mx-sdk-js-hw-provider) | Sign using the hardware wallet (Ledger). |
| [sdk-wallet-connect-provider](https://www.npmjs.com/package/@multiversx/sdk-wallet-connect-provider) | [documentation](/sdk-and-tools/sdk-js/sdk-js-signing-providers#the-walletconnect-provider) | [Github](https://github.com/multiversx/mx-sdk-js-wallet-connect-provider) | Sign using WalletConnect. |
| [sdk-extension-provider](https://www.npmjs.com/package/@multiversx/sdk-extension-provider) | [documentation](/sdk-and-tools/sdk-js/sdk-js-signing-providers#the-browser-extension-provider) \| [interactive documentation](https://interactive-tutorials.multiversx.com/dashboard/extension-provider) | [Github](https://github.com/multiversx/mx-sdk-js-extension-provider) | Sign using the MultiversX DeFi Wallet (browser extension). |
| [sdk-web-wallet-provider](https://www.npmjs.com/package/@multiversx/sdk-web-wallet-provider) | [documentation](/sdk-and-tools/sdk-js/sdk-js-signing-providers#the-web-wallet-provider) | [Github](https://github.com/multiversx/mx-sdk-js-web-wallet-provider) | Sign using the MultiversX web wallet, using webhooks **(DEPRECATED)**. |
| [mx-sdk-js-web-wallet-cross-window-provider](https://www.npmjs.com/package/@multiversx/sdk-web-wallet-cross-window-provider) | [documentation](/sdk-and-tools/sdk-js/sdk-js-signing-providers#the-web-wallet-cross-window-provider) \| [interactive documentation](https://interactive-tutorials.multiversx.com/dashboard/cross-window-provider) | [Github](https://github.com/multiversx/mx-sdk-js-web-wallet-cross-window-provider) | Sign using the MultiversX web wallet, by opening the wallet in a new tab. |
| [mx-sdk-js-metamask-proxy-provider](https://www.npmjs.com/package/@multiversx/sdk-metamask-proxy-provider) | [documentation](/sdk-and-tools/sdk-js/sdk-js-signing-providers#the-metamask-proxy-provider) \| [interactive documentation](https://interactive-tutorials.multiversx.com/dashboard/iframe-provider) | [Github](https://github.com/multiversx/mx-sdk-js-metamask-proxy-provider) | Sign using the Metamask wallet, by using web wallet as a proxy widget in iframe. |

For more details about integrating a signing provider into your dApp, please follow [this guide](/sdk-and-tools/sdk-js/sdk-js-signing-providers) or the [mx-sdk-js-examples repository](https://github.com/multiversx/mx-sdk-js-examples).

Signing SDKs:

| Package | Source code | Description |
|--------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------|
| [sdk-dapp](https://www.npmjs.com/package/@multiversx/sdk-dapp) | [Github](https://github.com/multiversx/mx-sdk-dapp) | A library that holds the core functional & signing logic of a dapp on the MultiversX Network. |
| [sdk-hw-provider](https://www.npmjs.com/package/@multiversx/sdk-hw-provider) | [Github](https://github.com/multiversx/mx-sdk-js-hw-provider) | Sign using the hardware wallet (Ledger). |
| [sdk-web-wallet-provider](https://www.npmjs.com/package/@multiversx/sdk-web-wallet-provider) | [Github](https://github.com/multiversx/mx-sdk-js-web-wallet-provider) | Sign using the MultiversX web wallet. |
| [sdk-wallet-connect-provider](https://www.npmjs.com/package/@multiversx/sdk-wallet-connect-provider) | [Github](https://github.com/multiversx/mx-sdk-js-wallet-connect-provider) | Sign using WalletConnect. |
| [sdk-extension-provider](https://www.npmjs.com/package/@multiversx/sdk-extension-provider) | [Github](https://github.com/multiversx/mx-sdk-js-extension-provider) | Sign using the MultiversX DeFi Wallet (browser extension). |
| [sdk-guardians-provider](https://www.npmjs.com/package/@multiversx/sdk-guardians-provider) | [Github](https://github.com/multiversx/mx-sdk-js-guardians-provider) | Helper library for integrating a co-signing provider (Guardian) into dApps. |


:::important
For all purposes, **we recommend using [sdk-dapp](/sdk-and-tools/sdk-dapp)** instead of integrating the signing providers on your own.
:::

For more details about integrating a signing provider into your dApp, please follow [this guide](/sdk-and-tools/sdk-js/sdk-js-signing-providers) or the [mx-sdk-js-examples repository](https://github.com/multiversx/mx-sdk-js-examples).

Native Authenticator libraries:

| Package | Source code | Description |
Expand Down

0 comments on commit 56ad626

Please sign in to comment.