# 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()
```