Signing Providers for dApps

This page will guide you through the process of integrating the erdjs signing providers in a dApp which isn't based on dapp-core.

important

Note that for most purposes, we recommend using dapp-core instead of integrating the signing providers on your own.

important

The code samples depicted on this page can also be found on the erdjs examples repository.

The following signing providers are available:

  • Web Wallet Provider
  • Extension Provider (Maiar DeFi Wallet)
  • Wallet Connect provider
  • Hardware Wallet (Ledger) Provider

The Web Wallet Provider

note

Make sure you have a look over the webhooks, in advance.

@elrondnetwork/erdjs-web-wallet-provider allows the users of a dApp to login and sign transactions using the Web Wallet.

In order to create an instance of the provider, do as follows:

import { WalletProvider, WALLET_PROVIDER_DEVNET } from "@elrondnetwork/erdjs-web-wallet-provider";

const provider = new WalletProvider(WALLET_PROVIDER_DEVNET);

The following provider URLs are defined by the package: WALLET_PROVIDER_TESTNET, WALLET_PROVIDER_DEVNET, WALLET_PROVIDER_MAINNET.

Login and logout

Then, ask the user to log in:

const callbackUrl = encodeURIComponent("http://my-dapp");
await provider.login({ callbackUrl });

Once the user opens her wallet, the web wallet issues a redirected back to callbackUrl, along with the address of the user. You can get the address as follows:

import qs from "qs";

const queryString = window.location.search.slice(1);
const params = qs.parse(queryString);
console.log(params.address);

In order to log out, do as follows:

const callbackUrl = window.location.href.split("?")[0];
await provider.logout({ callbackUrl: callbackUrl });

Sometimes, a dApp (and its backend) might want to reliably assign an off-chain user identity to an Elrond address. In this context, the web wallet provider supports an extra parameter to the login() method: a custom authentication token, completely opaque to the web wallet, to be signed with the user's wallet, at login-time:

// An identity token, provided by an identity provider (server-side)
// (e.g. Google ID, a custom identity token)
const authToken = "aaaabbbbaaaabbbb";

// A server-side handler used to acknowledge, validate and honour
// the relationship between "authToken" and the Elrond address of the user
const callbackUrl = encodeURIComponent("https://my-dapp/on-wallet-login");
await provider.login({ callbackUrl, token: authToken });

Signing transactions

Transactions can be signed as follows:

import { Transaction } from "@elrondnetwork/erdjs";

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

await provider.signTransactions(
    [firstTransaction, secondTransaction], 
    { callbackUrl: callbackUrl }
);

Upon signing the transactions using the web wallet, the user is redirected back to callbackUrl, while the query string contains information about the transactions, including their signatures. The information can be used to reconstruct Transaction objects using getTransactionsFromWalletUrl():

const plainSignedTransactions = provider.getTransactionsFromWalletUrl();
important

The following workaround is subject to change.

As of July 2022, the Web Wallet provider returns the data field as a plain string. However, erdjs' Transaction.fromPlainObject() expects it to be base64-encoded. Therefore, we need to apply a workaround (an additional conversion) on the results of getTransactionsFromWalletUrl().

for (const plainTransaction of plainSignedTransactions) {
    const plainTransactionClone = structuredClone(plainTransaction);
    plainTransactionClone.data = Buffer.from(plainTransactionClone.data).toString("base64");
    const transaction = Transaction.fromPlainObject(plainTransactionClone);

    // "transaction" can now be broadcasted.
}

Signing messages

important

Documentation in this section is preliminary and subject to change.

As of July 2022, the web wallet provider does not allow one to sign arbitrary messages (only transaction signing is supported).

The Extension Provider (Maiar DeFi Wallet)

note

Make sure you have a look over this page, in advance.

@elrondnetwork/erdjs-extension-provider allows the users of a dApp to login and sign transactions using the Maiar DeFi Wallet.

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

import { ExtensionProvider } from "@elrondnetwork/erdjs-extension-provider";

const provider = ExtensionProvider.getInstance();

Before performing any operation, make sure to initialize the provider:

await provider.init();

Login and logout

Then, ask the user to login:

const address = await provider.login();

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

In order to log out, do as follows:

await provider.logout();

The login() method supports the token parameter (similar to the web wallet provider):

// A custom identity token (opaque to the signing provider)
const authToken = "aaaabbbbaaaabbbb";

await provider.login({ token: authToken });

console.log("Address:", provider.account.address);
console.log("Token signature:", provider.account.signature);

Signing transactions

Transactions can be signed as follows:

import { Transaction } from "@elrondnetwork/erdjs";

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

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

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

Signing messages

Arbitrary messages can be signed as follows:

import { SignableMessage } from "@elrondnetwork/erdjs";

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

await provider.signMessage(message);

console.log(message.toJSON());

The Wallet Connect provider

@elrondnetwork/erdjs-wallet-connect-provider allows the users of a dApp to login and sign transactions using Maiar (the mobile application).

First, let's see a (simple) way to build a QR dialog using qrcode (and bootstrap):

import QRCode from "qrcode";

async function openModal(connectorUri) {
    const svg = await QRCode.toString(connectorUri, { type: "svg" });

    // The referenced elements must be added to your page, in advance
    $("#MyWalletConnectQRContainer").html(svg);
    $("#MyWalletConnectModal").modal("show");
}

function closeModal() {
    $("#MyWalletConnectModal").modal("hide");
}

In order to create an instance of the provider, do as follows:

import { WalletConnectProvider } from "@elrondnetwork/erdjs-wallet-connect-provider";

var provider;

const bridgeUrl = "https://bridge.walletconnect.org";

const callbacks = {
    onClientLogin: async function () {
        // closeModal() is defined above
        closeModal();
        const address = await provider.getAddress();
        console.log("Address:", address);
    },
    onClientLogout: async function () {
        console.log("onClientLogout()");
    }
};

const provider = new WalletConnectProvider(bridgeUrl, callbacks);

Before performing any operation, make sure to initialize the provider:

await provider.init();

Login and logout

Then, ask the user to login using Maiar on her phone:

const connectorUri = await provider.login();

// openModal() is defined above
openModal(connectorUri);

Once the user confirms the login, the onClientLogin() callback (declared above) is executed.

In order to log out, do as follows:

await provider.logout();

Signing transactions

Transactions can be signed as follows:

import { Transaction } from "@elrondnetwork/erdjs";

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

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

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

Alternatively, one can sign a single transaction using the method signTransaction().

Signing messages

important

Documentation in this section is preliminary and subject to change.

As of July 2022, erdjs' Wallet Connect provider does not allow one to sign arbitrary messages (only transaction signing is supported).

The Hardware Wallet (Ledger) Provider

note

Make sure you have a look over this page, in advance.

@elrondnetwork/erdjs-hw-provider allows the users of a dApp to login and sign transactions using a Ledger device.

In order to create an instance of the provider, do as follows:

import { HWProvider } from "@elrondnetwork/erdjs-hw-provider";

const provider = new HWProvider();

Before performing any operation, make sure to initialize the provider (also, the Elrond application has to be open on the device):

await provider.init();

Login

Before asking the user to log in using the Ledger, you may want to get all the available addresses on the device, display them, and let the user choose one of them:

const addresses = await provider.getAccounts();
console.log(addresses);

The login looks like this:

const chosenAddressIndex = 3;
await provider.login({ addressIndex: chosenAddressIndex });
alert(`Logged in. Address: ${await provider.getAddress()}`);

Alternatively, in order to select a specific address on the device after login, call setAddressIndex():

const addressIndex = 3;
await provider.setAddressIndex(addressIndex);
console.log(`Address has been set: ${await provider.getAddress()}.`);

The Ledger provider does not support a logout operation per se (not applicable in this context).

The login flow supports the token parameter (similar to other providers), using the method tokenLogin():

// A custom identity token (opaque to the signing provider)
const authToken = "aaaabbbbaaaabbbb";

// Note the additional suffix (required as of July 2022):
const payloadToSign = Buffer.from(`${authToken}{}`);
const { address, signature } = await provider.tokenLogin({ addressIndex: 0, token: payloadToSign });

console.log("Address:", address);
console.log("Signature:", signature.hex());

Signing transactions

Transactions can be signed as follows:

import { Transaction } from "@elrondnetwork/erdjs";

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

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

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

Alternatively, one can sign a single transaction using the method signTransaction().

Signing messages

Arbitrary messages can be signed as follows:

import { SignableMessage } from "@elrondnetwork/erdjs";

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

await provider.signMessage(message);

console.log(message.toJSON());

Verifying the signature of a login token

As previously mentioned, a dApp (and its backend) might want to reliably assign an off-chain user identity to an Elrond address. On this purpose, the signing providers allow a login token to be used within the login flow - this token is signed using the wallet of the user. Afterwards, a backend application would normally verify the signature of the token, as follows:

export function verifyAuthTokenSignature(address, authToken, signature) {
    console.log("verifyAuthTokenSignature()");
    console.log("address:", address);
    console.log("authToken:", authToken);
    console.log("signature:", signature);

    // Note that the verification API will be improved in a future version of erdjs-walletcore.
    // As of @elrondnetwork/[email protected], this API is a bit tedious:
    const verifier = UserVerifier.fromAddress(new Address(address));
    
    const message = new SignableMessage({
        signature: { hex: () => signature },
        message: Buffer.from(`${address}${authToken}{}`)
    });

    const ok = verifier.verify(message);
    if (ok) {
        return `The bearer of the token [${authToken}] is also the owner of the address [${address}].`;
    }

    return "Verification failed.";
}
note

The workaround applied in the code snippet above is subject for improvement.

← Migration guideserdgo →