The Locker

The Locker is a Web3 application that allows you to protect and backup any of your mnemonic phrases (or any other text secret) directly on the blockchain and recover it whenever you need. The mnemonic phrase is stored securely on the Secret Network, a privacy-preserving blockchain that encrypts input, output, and state of smart contracts in a way that it hides data even from the nodes on the network.

The Locker gives you a secure way to backup your mnemonic phrase by using a single-use Keplr wallet, your email address and several friends to hold a new type of crypto assets that we call a Passphrase Lock Shares. When you need top recover your original passphrase, you can create yet another single-use Keplr wallet and ask your friends to transfer the Passphrase Lock Shares back to you before recovering your password with your email.

This NPM package to interact with the Locker Smart Contract on the Secret Network blockchain.

Alpha Version Notice

This library is still in Apha and deployed on the Secret Network testnet. This is meant for for testing only as the API might break. Please do use the application to backup any of your passphrase that actually holds crypto assets.

Table of Contents

1. The Locker Contract
2. Setup
3. Backup
4. Transfer Request
5. Transfer Approval
6. Recovery
7. Queries
8. Mailer Client

The Locker Contract

Here is the latest version of the Locker Contract deployed on the testnet chain:

Client version: 4.1.3 ChainId: pulsar-2 Contract address: secret1sh76mq5hecuthwjhuyuxudjgvrrgtyhkv8vwru Contract hash: 3016c10db6b14a76da3d1c02512ab310949987b7de2cc5f357c59d667124f673

const chainId = "pulsar-2";
const url = "TODO get the API endpoint from https://github.com/scrtlabs/api-registry";

const contract = {
    hash: "3016c10db6b14a76da3d1c02512ab310949987b7de2cc5f357c59d667124f673",
    address: "secret1sh76mq5hecuthwjhuyuxudjgvrrgtyhkv8vwru",
};

Setup

When Alice want to backup her mnemonic passphrase, she needs to create a new Backup Client. This client can be requires to create a SecretJS wallet that can be instantiated in the browser using the Keplr wallet or in NodeJs directly.

Here is the Keplr integration:

import { BackupClient } from "@prifilabs/backup.js";

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

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

const backupClient = new BackupClient(
  secretjs,
  keplrOfflineSigner,
  contract.address,
  contract.hash,
  chainId,
  window.crypto
);

And here is the NodeJS integration:

import { SecretNetworkClient, Wallet } from "secretjs";
import { webcrypto } from "crypto";
import { BackupClient } from "@prifilabs/backup.js";

const wallet = new Wallet(
  "TODO enter your Secret Network wallet mnemonic phrase"
);
const address = wallet.address;
const secretjs = new SecretNetworkClient({
  url,
  chainId,
  wallet,
  address,
});

const backupClient = new BackupClient(
  secretjs,
  wallet,
  contract.address,
  contract.hash,
  chainId,
  webcrypto,
  false
);

Backup

const backup = async (
  backupClient: BackupClient,
  email: string,
  passphrase: string,
  threshold: number,
  addressList: string[]
) => {
  // user starts the backup process by registering their email
  const { tid, key } = await backupClient.registerBackup(email);

  // ask the mailer backend to send the code by email
  const res = await axios.post(
    "https://trustless-backup.prifilabs.com/api/backup",
    { tid }
  );

  // decrypt the code to reveal the nonce
  const nonce = await backupClient.checkCodeBackup(key, code);

  // user sends their encrypted passphrase and share information along with the tid and nonce
  const { uuid, hash }: { uuid: string; hash: string } =
    await backupClient.confirmBackup(
      tid,
      key,
      nonce,
      passphrase,
      threshold,
      addressList
    );

  return uuid;
};

Transfer Request

const registerTransfer = async (uuid: string, backupClient: BackupClient) => {
  // Bob (share owner) starts transfer process by passing the uuid
  const { tid, key, hash } = await backupClient.registerTransfer(uuid);
};

const confirmTransfer = async (
  tid: string,
  key: string,
  to: string
) => {
  // Bob (share owner) starts transfer process by passing the uuid
  const { hash } = await backupClient.confirmTransfer(tid, key, to);

  // ask the mailer backend to send the code by email
  const res = await axios.post(
    "https://trustless-backup.prifilabs.com/api/transfer",
    { tid }
  );
};

Transfer Approval

const approve = async (
  key: string,
  to: string
) => {
  // Alice (client) receives code in email and code is decrypted to form the tid and nonce
  const { tid, nonce } = await backupClient.checkCodeTransfer(code);

  /* Input the tid and nonce to get the uuid and address being transferred to */
  const transfer_info: { uuid: string; addr: string } =
    await backupClient.getTransferInfo(tid, nonce);

  // Alice (client) finalizes transfer by passing the tid and nonce
  await backupClient.approveTransfer(tid, nonce, to);
};

Recovery

const recovery = async (uuid: string, backupClient: BackupClient) => {
  // user begins recovery process by passing the uuid
  const { tid, key } = await backupClient.registerRecovery(uuid);

  // ask the mailer backend to send the code by email
  const res = await axios.post(
    "https://trustless-backup.prifilabs.com/api/recovery",
    { tid }
  );

  // code is decrypted and returns the nonce
  const nonce = await backupClient.checkCodeBackup(key, code);

  // user confirms recovery by passing in the tid and nonce and the passphrase is returned
  const passphrase = await backupClient.confirmRecovery(tid, nonce, key);

  return passphrase;
};

Queries

GetShareCount

type ShareInfo = {
  uuid: string;
  email: string;
  count: number;
  threshold: number;
};

/* Returns a list of all shares owned by the user grouped by uuid */
const shares: ShareInfo[] = await backupClient.getShareCount();

GetTransferInfo

type TransferInfo = { uuid: string; addr: string };

/* Given the tid and nonce returns the uuid attempting transfer to addr */
const transfer_info: TransferInfo = await backupClient.getTransferInfo(
  tid,
  nonce
);

Mailer Client

import { MailerClient } from "@prifilabs/backup.js";
import { Wallet, SecretNetworkClient } from "secretjs";

const mailerWallet = new Wallet(
  "TODO enter the Mailer Backend wallet mnemonic phrase"
);

const secretjs = new SecretNetworkClient({
  url,
  chainId,
});

const client = new MailerClient(
  contract.address,
  contract.hash,
  mailerWallet,
  secretjs,
  chainId
);

Backup

// code contains encrypted nonce, send as-is to email
const { email, code } = await MailerClient.getBackup(tid);

Transfer

// code contains tid and nonce, send as-is to email
const { email, code } = await MailerClient.getTransfer(tid);

Recovery

// code contains encrypted nonce, send as-is to email
const { email, code } = await MailerClient.getRecovery(tid);