wallet-integrations.md

description
Learn how to integrate various web3 wallets with SecretJS.

Wallet Integrations

Secret Network Client Setup

import { SecretNetworkClient, Wallet } from "secretjs";

const wallet = new Wallet("Your mnemonic words go here");

const secretjs = new SecretNetworkClient({
  chainId: "pulsar-3",
  url: "https://pulsar.lcd.secretnodes.com",
  wallet: wallet,
  walletAddress: wallet.address,
});

Metamask

import { SecretNetworkClient, MetaMaskWallet } from "secretjs";

//@ts-ignore
const [ethAddress] = await window.ethereum.request({
  method: "eth_requestAccounts",
});

const wallet = await MetaMaskWallet.create(window.ethereum, ethAddress);

const secretjs = new SecretNetworkClient({
  url: "TODO get from https://github.com/scrtlabs/api-registry",
  chainId: "secret-4",
  wallet: wallet,
  walletAddress: wallet.address,
});

Notes:

1. MetaMask supports mobile!
2. MetaMask supports Ledger.
3. Secretjs MetaMaskWallet will automatically prompt the user to sign a personal_sign message, which is used to recover the users public key and derive the user's Secret Network address.
4. You might want to pass encryptionSeed to SecretNetworkClient.create() to use the same encryption key for the user across sessions. This value should be a true random 32 byte number that is stored securly in your app, such that only the user can decrypt it. This can also be a sha256(user_password) but might impair UX.
5. See Keplr's getOfflineSignerOnlyAmino() for list of unsupported transactions.

Keplr Wallet

The recommended way of integrating Keplr is by using window.keplr.getOfflineSigner():

import { SecretNetworkClient } from "secretjs";

const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

while (
  !window.keplr ||
  !window.getEnigmaUtils ||
  !window.getOfflineSigner
) {
  await sleep(50);
}

const CHAIN_ID = "secret-4";

await window.keplr.enable(CHAIN_ID);

const keplrOfflineSigner = window.keplr.getOfflineSigner(CHAIN_ID);
const [{ address: myAddress }] = await keplrOfflineSigner.getAccounts();

const url = "TODO get from https://github.com/scrtlabs/api-registry";

const secretjs = new SecretNetworkClient({
  url,
  chainId: CHAIN_ID,
  wallet: keplrOfflineSigner,
  walletAddress: myAddress,
  encryptionUtils: window.keplr.getEnigmaUtils(CHAIN_ID),
});

// Note: Using `window.getEnigmaUtils` is optional, it will allow
// Keplr to use the same encryption seed across sessions for the account.
// The benefit of this is that `secretjs.query.getTx()` will be able to decrypt
// the response across sessions.

Notes:

1. No mobile support yet.
2. Keplr supports Ledger.
3. By using encryptionUtils you let Keplr handle user encryption keys for you, which allows you to easily decrypt transactions across sessions.

Links:

• Official Keplr Website »
• Keplr API Docs »

Signer vs SignerAuto vs SignerOnlyAmino

TLDR:

• getOfflineSigner(): The recommended way. Efficient, supports all transaction types except Ledger.
• getOfflineSignerAuto(): Automatically selects the best signer based on the account type (Ledger or not).
• getOfflineSignerOnlyAmino(): The legacy way. Recommended only for Ledger users.

window.keplr.getOfflineSignerOnlyAmino()

The legacy and non-recommended way of signing transactions on cosmos-sdk. Suitable only for Ledger users due to its limited transaction support and better UI.

• 🟩 Looks good on Keplr
• 🟩 Supports users signing with Ledger
• 🟥 Doesn't support signing these transactions:
  • Every tx type under ibc_client, ibc_connection and ibc_channel (meaning IBC relaying, for example with ts-relayer)
  • gov/MsgSubmitProposal/ClientUpdateProposal
  • gov/MsgSubmitProposal/UpgradeProposal

Note that ibc_transfer/MsgTransfer for sending funds across IBC is supported.

window.keplr.getOfflineSigner()

The recommended way of signing transactions on cosmos-sdk. Efficient and supports all transaction types except those requiring a Ledger.

• 🟥 Looks bad on Keplr
• 🟥 Doesn't support users signing with Ledger
• 🟩 Supports signing transactions with all types of Msgs

window.keplr.getOfflineSignerAuto()

Automatically chooses the best signing method based on the user's Keplr account:

• For Ledger users, uses window.keplr.getOfflineSignerOnlyAmino().
• For non-Ledger users, uses window.keplr.getOfflineSigner().
• 🟩 Smart and adaptable
• 🟩 Provides flexibility for both Ledger and non-Ledger accounts

If the connected Keplr account uses Ledger, returns window.keplr.getOfflineSignerOnlyAmino().
Otherwise returns window.keplr.getOfflineSigner().

Fina Wallet

Fina implements the Keplr API, so the above Keplr docs applies. If you support Keplr, your app will also work on the Fina Wallet mobile app. This works because the Fina Wallet mobile app has webview to which it injects its objects under window.keplr.

Fina supports deep linking into its in-app browser.

Example1: fina://wllet/dapps?network=secret-4&url=https%3A%2F%2Fdash.scrt.network

Example2:

If a user accessed your app using a regular mobile browser, you can open your app in the Fina in-app browser using this code:

const urlSearchParams = new URLSearchParams();
urlSearchParams.append("network", "secret-4");
urlSearchParams.append("url", window.location.href);

window.open(`fina://wllet/dapps?${urlSearchParams.toString()}`, "_blank");

Links:

• Official Fina Website »

Leap Cosmos Wallet

The recommended way of integrating Leap is by using window.leap.getOfflineSigner():

import { SecretNetworkClient } from "secretjs";

const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

while (
  !window.leap ||
  !window.leap.getEnigmaUtils ||
  !window.leap.getOfflineSignerOnlyAmino
) {
  await sleep(50);
}

const CHAIN_ID = "secret-4";

await window.leap.enable(CHAIN_ID);

const leapOfflineSigner = window.leap.getOfflineSigner(CHAIN_ID);
const [{ address: myAddress }] = await leapOfflineSigner.getAccounts();

const url = "TODO get from https://github.com/scrtlabs/api-registry";

const secretjs = new SecretNetworkClient({
  url,
  chainId: CHAIN_ID,
  wallet: leapOfflineSigner,
  walletAddress: myAddress,
  encryptionUtils: window.leap.getEnigmaUtils(CHAIN_ID),
});

// Note: Using `window.leap.getEnigmaUtils()` is optional, it will allow
// Leap to use the same encryption seed across sessions for the account.
// The benefit of this is that `secretjs.query.getTx()` will be able to decrypt
// the response across sessions.

Links:

• Official Leap Website »
• Leap API Docs »

Starshell Wallet

StarShell implements the Keplr API, so the above Keplr docs applies. If you support Keplr, your app will also work on StarShell wallet. This works because StarShell wallet asks the user to turn off Keplr and then overrides window.keplr with its objects.

Links:

• Official StarShell Website »

Ledger Wallet

@cosmjs/ledger-amino can be used to sign transactions with a Ledger wallet running the Cosmos app.

import { SecretNetworkClient } from 'secretjs';
import { makeCosmoshubPath } from "@cosmjs/amino";
import { LedgerSigner } from "@cosmjs/ledger-amino";

// NodeJS only
import TransportNodeHid from "@ledgerhq/hw-transport-node-hid";

// Browser only
//import TransportNodeHid from "@ledgerhq/hw-transport-webusb";

const interactiveTimeout = 120_000;
const accountIndex = 0;
const cosmosPath = makeCosmoshubPath(accountIndex);

const ledgerTransport = await TransportNodeHid.create(interactiveTimeout, interactiveTimeout);
const ledgerSigner = new LedgerSigner(
  ledgerTransport,
  {
    testModeAllowed: true,
    hdPaths: [cosmosPath],
    prefix: 'secret'
  }
);
const [{ address }] = await signer.getAccounts();

const client = new SecretNetworkClient({
  url: "TODO get from https://github.com/scrtlabs/api-registry",
  chainId: "secret-4",
  wallet: ledgerSigner,
  walletAddress: address,
});

Notes:

1. Use the appropriate hw-transport package for your environment (Node or Browser)
2. The Ledger Cosmos app only supports coin type 118
3. You might want to pass encryptionSeed to SecretNetworkClient.create() to use the same encryption key for the user across sessions. This value should be a true random 32 byte number that is stored securly in your app, such that only the user can decrypt it. This can also be a sha256(user_password) but might impair UX.
4. See Keplr's getOfflineSignerOnlyAmino() for list of unsupported transactions.

Links:

• @cosmjs/ledger-amino Documentation