# Mask Wallet Technical Design

## Structures
### KeyStore Json Format

{
  "version": 1, // Version of Mask Wallet KeyStore Format
  "type": "hd" // Type of KeyStore, "hd" | "privatekey" | ...
  "keyHash": "efbe00a55ddd4c5350e295a9533d28f93cac001bfdad8cf4275140461ea03e9e",
  "crypto": {
  // Payload is the raw data of crypto object
    "payload": { // User a scrypt  
        "cipher": "aes-128-ctr",
        "cipherparams": {
          "iv": "6006bd4e828f2f93dca31e36590ca4c9"
        },
"ciphertext":"b06b82b8cda0bc72761177b312dfd46318248ad8473b6c97d46c44aedf6a283f44f0267dd03f210dcddf4ea1a34f85b0b02533dd9c37ce2276cb087af3e43f2a76b968e17c816ca8ea5c",
        "kdf": "scrypt",
        "kdfparams": {
          "c": 10240,
          "prf": "hmac-sha256",
          "dklen": 32,
          "salt": "5d85aaf812a613f810cc1cda18d35f46c013f5e537629e25372969f5f87402cd"
        },
        "mac": "56af7c5faf0a791cbb4911c4c20070156e4ad0a03f8253b2a2fb005a68d7a026"
    }
    // The name of CryptoSuite to handle the payload
    "cryptoSuite":"scrypt"      
  },
  "keypairs": [
    {
      "address": "qzld7dav7d2sfjdl6x9snkvf6raj8lfxjcj5fa8y2r",
      "derivationPath": "m/44'/145'/0'/0/0",
      "curve": "SECP256k1",
      "chainType": "BITCOINCASH",
      "network": "MAINNET",
      "segWit": "NONE",
      "extPubKey": "031064f6a580000000251d72997d4cf931a7e6819f7da37725166100fc7dae9ca6afc3f8fd8a3d3a7f0303f2f84851514bf2f40a46b5bb9dbf4e5913fbacde1a96968cda08f9fd882caa"
    }
  ],
  "meta": {
    "name": "test-wallet",
    "passwordHint": "hint",
    "timestamp": 1575605134,
    "source": "MNEMONIC" // different from keyStore's type, source is used to indicator where this KeyStore is created from. A pk type KeyStore may not be created from a "PrivateKey" source
  }
}

## Usage
### Initialization
Before using any Mask Wallet features, users should registry a `KeyStoreStorage` by calling `setStorageRegistry` as below:

import { setStorageRegistry } from "@dimensiondev/mask-wallet"

let keyStoreStorage = {
    setKeyStore(store: KeyStore): Promise<void> = () => {
    
    },
    getKeyStore(hash: KeyStore["keyHash"]): Promise<KeyStore> = (keyStore) => {
    
    },
    deleteKeyStore(hash: KeyStore["keyHash"]): Promise<void> = () => {
    
    }
}
setStorageRegistry(keyStoreStorage)

**Note**: the initialization code will be omitted in all following code snippets

---

### KeyStoreManager
`KeyStoreManager` provides all the `KeyStore` manupulation methods including creating, importing, exporting, searching and deleting a KeyStore.

#### Get the KeyStoreManager

import { getKeyStoreManager } from "@dimensiondev/mask-wallet"

const keyStoreManager = await getKeyStoreManager()

### Wallet
`Wallet` provides all the methods for users to operate the `KeyPair`s.

#### Get the Wallet Instance

import { getWalletInstance } from "@dimensiondev/mask-wallet"

const wallet = await getWalletInstance()

---

### Create a new KeyStore
#### Create a HD KeyStore

import { getKeyStoreManager } from "@dimensiondev/mask-wallet"

const keyStoreManager = await getKeyStoreManager()

let createHdKeyStoreParam = {
    password: "A Password",
    passwordHint: "A simple Password",
    name: "Wallet1",
    keyType: "Mnemonic"
} 
let result = await keyStoreManager.createKeyStore(createHdKeyStoreParam)

result

KeyHash:"4fc213ddcb6fa44a2e2f4c83d67502f88464e6ee"
name:"Wallet1"
source:"Mnemonic"
KeyPairs:[]
createdAt:1576654549

#### Create a private key KeyStore

import { getKeyStoreManager } from "@dimensiondev/mask-wallet"

const keyStoreManager = await getKeyStoreManager()

let createPrivateKeyKeyStoreParam = {
    password: "A Password",
    passwordHint: "A simple Password",
    name: "Wallet1",
    keyType: "PrivateKey"
} 
let result = await keyStoreManager.createKeyStore(createPrivateKeyKeyStoreParam)

result

KeyHash:"4fc213ddcb6fa44a2e2f4c83d67502f88464e6ee"
name:"Wallet1"
source:"PrivateKey"
KeyPairs:[]
createdAt:1576654549

### Import a KeyStore
#### Get the support KeyStore Import Methods

import { getWalletInstance } from "@dimensiondev/mask-wallet"

const wallet = await getWalletInstance()
let importMethods = wallet.getSupportImportMethod("4fc213ddcb6fa44a2e2f4c83d67502f88464e6ee")

importMethods
[
    "PrivateKey",
    "Mnemonic",
    "KeyStoreJson"
]

#### Import a KeyStore by Mnemonic

import { getKeyStoreManager } from "@dimensiondev/mask-wallet"

const keyStoreManager = await getKeyStoreManager()

let importHdKeyStoreParam = {
    mnemonic: "inject kidney empty canal shadow pact comfort wife crush horse wife sketch"
    password: "A Password",
    passwordHint: "A simple Password",
    name: "Wallet1",
    overwrite: false
} 
let result = await keyStoreManager.importKeyStore(importHdKeyStoreParam)

result

KeyHash:"4fc213ddcb6fa44a2e2f4c83d67502f88464e6ee"
name:"Wallet1"
source:"Mnemonic"
KeyPairs:[]
createdAt:1576654549

#### Import a KeyStore by private key

import { getKeyStoreManager } from "@dimensiondev/mask-wallet"

const keyStoreManager = await getKeyStoreManager()

let importPrivateKeyKeyStoreParam = {
    privateKey: "f15716d3b003b304b8055d9cc62e6b9c869d56cc930c3858d4d7c31f5f53f14a",
    password: "A Password",
    passwordHint: "A simple Password",
    name: "Wallet1",
    overwrite: false
} 
let result = await keyStoreManager.importKeyStore(importPrivateKeyKeyStoreParam)

result

KeyHash:"4fc213ddcb6fa44a2e2f4c83d67502f88464e6ee"
name:"Wallet1"
source:"PrivateKey"
KeyPairs:[]
createdAt:1576654549

#### Import a KeyStore by V3 KeyStore JSON

import { getKeyStoreManager } from "@dimensiondev/mask-wallet"

const keyStoreManager = await getKeyStoreManager()

let importJsonKeyStoreParam = {
    json: "{
            "cipher": "aes-128-ctr",
            "cipherparams": {
              "iv": "437ef8c8553df9910ad117ecec5b8c05"
            },
            "ciphertext": "acabec2bd6fab27d867ebabe0ded9c64c85aebd294d29ecf537e563474ebb931522dbb977e0644830516550255edde02c507863cb083b55f2f0f759c2f8a885a81a6518237e7b65b7cf3e912fb36e42a13a7b2df3d401e5ff778a412a6d4c5516645770c4b12f2e30551542c699eef",
            "kdf": "pbkdf2",
            "kdfparams": {
              "c": 65535,
              "dklen": 32,
              "prf": "hmac-sha256",
              "salt": "33c8f2d27fe994a1e7d51108c7811cdaa2b821cc6760ed760954b4b67a1bcd8c"
            },
            "mac": "6b86a18f4ba9f3f428e256e72a3d832dcf0cd1cb820ec61e413a64d83b012059"
          }",
    password: "A Password",
    passwordHint: "A simple Password",
    name: "Wallet1",
    overwrite: false
} 
let result = await keyStoreManager.importKeyStore(importJsonKeyStoreParam)

result

KeyHash:"4fc213ddcb6fa44a2e2f4c83d67502f88464e6ee"
name:"Wallet1"
source:"EncryptedJson"
KeyPairs:[]
createdAt:1576654549

### Export a KeyStore
####

### Retrive KeyStore
#### Retrive all allKeyStores

import { getKeyStoreManager } from "@dimensiondev/mask-wallet"

const keyStoreManager = await getKeyStoreManager()
let allKeyStores = await keyStoreManager.getAllKeyStore()

allKeyStores
[
    {
        KeyHash: "4fc213ddcb6fa44a2e2f4c83d67502f88464e6ee",
        meta: {
            name: "Wallet1",
            type: "Mnemonic",
            passwordHint: "A simple password",
            createdAt:1576654549
        }
    },
    {
        KeyHash: "3278gf8723gf732ry7932hf329gf8239hf329fg8",
        meta: {
            name: "Wallet2",
            type: "PrivateKey",
            passwordHint: null,
            createdAt:1576654183
        }
    }
]

#### Retrieve a KeyStore
##### Retrieve a KeyStore using KeyHash

import { getKeyStoreManager } from "@dimensiondev/mask-wallet"

const keyStoreManager = await getKeyStoreManager()
let keyStore = await keyStoreManager.getKeyStore("4fc213ddcb6fa44a2e2f4c83d67502f88464e6ee")

keyStore
{
    KeyHash: "4fc213ddcb6fa44a2e2f4c83d67502f88464e6ee",
    meta: {
        name: "Wallet1",
        type: "Mnemonic",
        passwordHint: "A simple password",
        createdAt:1576654549
    }
}

##### Search for a KeyPair and the contained KeyStore using address

import { getKeyStoreManager } from "@dimensiondev/mask-wallet"

const keyStoreManager = await getKeyStoreManager()
let (keyStore, KeyPair) = await keyStoreManager.getKeyStoreByAdress("JHBkzZJnLZ3S3HLvxjpFAjd6ywP7WAk5miL7MwVCn9a7jHS")

keyStore
{
    KeyHash: "4fc213ddcb6fa44a2e2f4c83d67502f88464e6ee",
    meta: {
        name: "Wallet1",
        type: "Mnemonic",
        passwordHint: "A simple password",
        createdAt:1576654549
    }
}

KeyPair
{
    address: "JHBkzZJnLZ3S3HLvxjpFAjd6ywP7WAk5miL7MwVCn9a7jHS",
    curve: "SECP256k1",
    chainType: "ethereum",
    network: "mainnet",
    derivationPath: "m/44'/60'/0'/0/0"
}

#### Delete KeyStore
##### Delete a keyStore using KeyHash

import { getKeyStoreManager } from "@dimensiondev/mask-wallet"

const keyStoreManager = await getKeyStoreManager()
let result = await keyStoreManager.deleteKeyStore("4fc213ddcb6fa44a2e2f4c83d67502f88464e6ee")

##### Delete all KeyStore

import { getKeyStoreManager } from "@dimensiondev/mask-wallet"

const keyStoreManager = await getKeyStoreManager()
let result = await keyStoreManager.deleteAllKeyStore()