Documentation | United Network

Restore Card by Seed Phrase ​

This document provides a technical overview of the "Restore Card by Seed Phrase" feature.

Overview ​

The "Restore Card by Seed Phrase" feature allows users to restore their wallet on a new or existing card using a 12-word seed phrase. This process involves authorizing the card, entering the seed phrase, setting a new PIN, and writing the new wallet information to the card.

Workflow ​

The restoration process consists of the following steps:

  1. Card Authorization: The user initiates the process and is prompted to tap their card against their device. The application reads the card's public key via NFC to ensure the card is valid and not broken.

  2. Seed Phrase Entry: The user is presented with a form to enter their 12-word seed phrase. Each word is entered into a separate input field.

  3. Seed Phrase Validation: Once all 12 words are entered, the user clicks "Process". The application performs the following actions:

    • It concatenates the 12 words into a single string.
    • It uses the deriveSeedFromMnemonic function to validate the seed phrase and derive a master seed from it.
    • If the seed phrase is invalid (e.g., contains incorrect words), an error message is displayed.

  4. PIN Setup: After a valid seed phrase is entered, the user is prompted to set a new PIN for the card. They must enter the PIN twice to confirm it.

  5. Writing to Card: With a valid seed phrase and a new PIN, the application prepares to write the new wallet to the card.

    • It constructs a command containing the derived seed and the new PIN.
    • The user is prompted to tap their card again.
    • The application sends the command to the card via NFC to initialize it with the new wallet.

  6. Completion: Upon successful completion, the card is restored with the wallet corresponding to the entered seed phrase. The user is then redirected to the main dashboard.

Code Implementation ​

The user interface and logic for this feature are primarily handled by the RestoreSeedPhrase.vue component.

Key Components and Functions: ​

  • RestoreSeedPhrase.vue: The main Vue component for the feature.
    • authorizeCard(): Handles the initial card authorization via NFC using CmdGetInfo.
    • enterPinCode(): Triggers the seed phrase validation and transitions to the PIN entry step.
    • createSeed(): Validates the seed phrase using deriveSeedFromMnemonic.
    • writeSeed(): Writes the new seed and PIN to the card via NFC using CmdInit.
    • PinCode.vue: A reusable component for PIN entry and confirmation.
    • NFCHandlerWindow.vue: A component that manages the NFC interaction prompts.

Example: Seed Phrase Validation ​

javascript
// In RestoreSeedPhrase.vue

import { deriveSeedFromMnemonic } from '@/api/mnemonic';

// ...

const createSeed = () => {
  // ...
  const seedPhrasesStringLowercase = seedPhrasesArray.value.map(word => word?.trim().toLowerCase());
  seedPhrasesString.value = seedPhrasesStringLowercase.join(' ');
  
  try {
    // deriveSeedFromMnemonic will throw an error if the mnemonic is invalid
    seedPhrasesDerive.value = deriveSeedFromMnemonic(seedPhrasesString.value);
  } catch(err) {
    // Display an error to the user
    error.value = true;
    errorSubtitle.value = 'Phrases has wrong words.';
    return;
  }
}

Example: Writing to the Card ​

javascript
// In RestoreSeedPhrase.vue

import { CmdInit } from '@/api/card-io';
import { setUniSettings } from '@/api/global-settings';

// ...

const writeSeed = async () => {
  // ...
  setUniSettings({ ioMethod: 'nfc' });

  try {
    const signRequestPrepare = await CmdInit.buildRequest({
      "seed": seedPhrasesDerive.value,
      "keys": store.state.user.publicKeyCard,
      "pin": pinCodePre.value,
    });

    const result = await nfcHandlerWindow.value?.nfcProgressHandler(signRequestPrepare, CmdInit, false);
    
    if (result) {
      // Process success
    }
  } catch(err) {
    // Handle error
  }
}

Error Handling ​

The process includes robust error handling to inform the user of any issues that may occur, such as:

  • Invalid card
  • Incorrect seed phrase
  • NFC communication errors
  • Failures during the writing process

Error messages are displayed to the user to guide them on how to proceed.