# Entropy Keyring Design

The purpose of the keyring is to:
1. set you up with keys you need to operate with Entropy
2. support you to persist keys
3. support you to recover keys from mnemonic
4. provide helper functions which Entropy SDK consumes for internal functions

## Setup paths

Where it comes to instantiating a Keyring there are 3 major pathways we are designing to support

- Path A - first time user
- Path B - returning user
- Path C - recovering

Here's a visualization of all the paths (see them broken down in sub-sections below):

graph LR

A[Path A]--" generateMnemonic() "-->mnemonic
mnemonic--" mnemonicToKeyData()"-->keyData
mnemonic--" *write down* "-->paper[paper?]
keyData--" new Keyring() "-->keyRing
keyRing--" .json()"-->keyData
keyData-. *writeKeyData* .->storage[storage?]

B[Path B]-. *readKeyData* .->keyData

C[Path C]--" *manual entry* "-->mnemonic

classDef entry-point fill:hotpink,stroke:none;
class A,B,C entry-point;

classDef exit-point fill:white,stroke-dasharray:5 5;
class storage,paper exit-point;

### Path A - first time user

This user is brand new to Entropy, they want to get set up and running.
Their flow looks like this:

graph LR

A[Path A]--" generateMnemonic() "-->mnemonic
mnemonic--" mnemonicToKeyData()"-->keyData
mnemonic--" *write down* "-->paper[paper?]
keyData--" new Keyring() "-->keyRing
keyRing--" .json()"-->keyData
keyData-. *writeKeyData* .->storage[storage?]


classDef entry-point fill:hotpink,stroke:none;
class A,B,C entry-point;

classDef exit-point fill:white,stroke-dasharray:5 5;
class storage,paper exit-point;

In code:

import { Keyring, generateMnemomnic, mnemonicToKeyData } from `@entropyxyz/keyring`

// 1. create (and write down) mnemonic
const mnemomnic = generateMnemomnic()

// 2. use mnemonic to generate keyData
const keyData = mnemonicToKeyData(mnemonic)
/*
    {
      programMod: { type, secret, public, address },
      developer: { type, secret, public, address },
      device: { type, secret, public, address }
    } 

    where:
    - type = the type of keypair, e.g. blake256
    - secret = the secretKey of the keypair, stored in ...format?
    - public = the publicKey of the keypair, stored in ...format?
    - addresss = the formatted address of the keypair
*/

// 3. instantiate keyring
const keyring = new Keyring(keyData)

// 4. export keyData + persist
const keyData = keyring.json()
/*
    {
      programMod: { type, secret, ... },
      developer: { type, secret, ... },
      device: { type, secret, ... }
    } 
*/
await writeKeyData(keyData) // some function

**Notes**:
1. the generation of `keyData` here is deterministic (mostly)
- `mnemonicToKeyData` takes care of `mnemonic` => `seed` => `keyData` (programMod, developer, etc)
- `keyData.device` is NOT derived from the `seed`
- this key is deliberately design to NOT be recovered from the `mnemonic`
- we want all devices to be distiguishable to be able to mitigate for device theft
2. we do not persist `seed`
- this is a security feature, because the `seed` is used with `paths` to derive each key in `keyData`
- this allows users to e.g. share a `dev` key without revealing a `programMod` key

**Questions**:
1. is there a password on the mnemonic?
- mix: could do, but this just feels like putting a password over a password, so meh?
- frankie: "password" can mean many things, we should talk about "derivation path"
2. safe persisting of `keyData`... how, where?
- i) system keyring is an option
- ii) encrypted file (seperate from config?)
3. how do we handle changes in `mnemonicToKeyData`?
- e.g. add a new default key, or change the default `type` for a particular key(s)
- do we need a "version" D:
- frankie: no breaking changes expected, we can version the keyring appropriated, and migrations can be handled elsewhere.
4. do we make `mnemonicToKeyData` add `keyData.device`?
- this makes it non-deterministic
- but I am scared if people persist the results at this point they will not have their `keyData.device` :fire:
- frankie: agree
5. `keyData` formats
- `type`
- a) list the valid types we support initially?
- b) which types might we need to support in future, and do these have additional data requirements?
- `secret`
- c) what's the encoding? ("0x hex"? base58?)
- `public`
- d) what's the encoding?
- `address`
- e) what's the encoding?
6. can we rename `programMod`?
- :warning: bikeshed
- frankie: i'd prefer not to call it it the programMod since it's not that till we register it
- mix: how about `account` - we "register" an account, accounts have addresses (derived from this secret?), and account key being the one which can modify the account seems right?
- frankie: oh yeah... each account can have multiple registrations... I think we need naming which helps us tell clear stories... what is an "account"?

### Path B - returning user

This path assume a user already has a working `keyData` they have read from persistence.

Flow looks like this:

graph LR

keyData--" new Keyring() "-->keyRing
keyRing--" .json()"-->keyData

B[Path B]-. *readKeyData* .->keyData

classDef entry-point fill:hotpink,stroke:none;
class A,B,C entry-point;

classDef exit-point fill:white,stroke-dasharray:5 5;
class storage,paper exit-point;

import { Keyring } from 'entropxyz/keyring'

const keyData = await readKeyData() // some function
// {
//   programMod: { type, secret, ... },
//   developer: { type, secret, ... },
//   device: { type, secret, ... }
// } 

const keyring = new Keyring(keyData)

**Notes**:
1. all keys are optional
- there should be at least one key tho
2. this `keyData` is not necessarily the same as the data generated from mnemonic, it could be: user-created, e.g. I make some new data for a new device:
- completely manually user generated, or spliced together e.g.

   const newKeyData = mnemonicToKeyData(generateMnemonic())
   const keyData = {
     ..., // new keys
     programMod,    // "admin" keys from an earlier install
   }

- :warning: in this case, this data connot be recovered froma `mnemonic` alone, as the determinism is broken

**Questions**:
1. are all keys required? what are the implications?
- mix: I really dislike code that's like "check if we have a key", then if we do, use it.
- frankie: we can just check and throw

### Path C - recovering

This path covers the case that a user has lost their setup, but has a record of their `mnemonic`.
This flow looks like:

graph LR

mnemonic--" mnemonicToKeyData()"-->keyData
keyData--" new Keyring() "-->keyRing
keyRing--" .json()"-->keyData
keyData-. *writeKeyData* .->storage[storage?]

C[Path C]--" *manual entry* "-->mnemonic

classDef entry-point fill:hotpink,stroke:none;
class A,B,C entry-point;

classDef exit-point fill:white,stroke-dasharray:5 5;
class storage,paper exit-point;

In code:

import { Keyring, mnemonicToKeyData } from `@entropyxyz/keyring`

// 1. User recreates keyData
const keyData = mnemonicToKeyData(mnemonic)

// 2. instantiate keyring
const keyring = new Keyring(keyData)

// 3. persistence of keyData
const keyData = keyring.json()
await writeKeyData(keyData) // some function

**Notes**:
1. :warning: `keyData.device` is unique to every device, so:
- the user MUST persist the new `keyData`
2. :warning: if the original `keyData` was custom in some way, this recovery path does not work (see Path B, Note 2)

---

## API

### `new Keyring(keyData: Keydata) => keyRing`

### `keyring.json() => keyData`

returns `keyData` for persistence

### TODO: "get key"

Should be able to access:
- `signer` needed for creating extrinsics
- ... what else

Should NOT be able to access:
- is there any internal state we want to explicitly not expose?

e.g.

keyring[keyname].signer
keyring.get(keyname).signer

### TODO: "get ephemeral key"

creates a disposable key intended for singal use encryption while signing:

e.g.

keyring.createEphemeralSigner()
keyring.create(type).signer

### Helper functions

#### `generateMnemonic() => string`

bip39, no password?

#### `mnemonicToKeyData(mnemonic: string, opts) => keyData`

- bip39, no password?
- needs a clear spec of `KeyData`
- might need versioning, migrations?

`opts` (rename) is added to specify the keys + paths to derive, e.g

{
  programMod: '/path/to/programMod',
  developer: '/path/to/programMod',
  device: Math.random(),
}

#### `isValidKeyData(keyData) => boolean`

mix: we should write this early because it makes the number of checks we need to do
everywhere else soooo much lighter if we can tightly check data before ingesting

## Other Concerns

### Admin / Registration / Sponsorhips

are curent way of thinking is to have an admin key and registration key
the key that pays for registartion and the key that gets set as the programMod

they can be one in the same (infact they are right now)
however they can also be different. In my personal case i would want them to be different

i think also for "sponsorship" reason we should allow them to be different

init
should take all "3" seeds but only requires programMod i'm still stuck on this name

### hot swap keyring?

should you be able to set a different keyring to an already initialized entropy?

entropy.setKeyring(keyring)