Merge pull request #51 from gorazdko/update_docs

updating docs

Author: ChristopherA

README.md

@@ -16,19 +16,17 @@ The following files contain everything you need to set up your *LetheKit* hardwa
 * The [Lethekit Installation Instructions](doc/installation.md) show how to install LetheKit in your Arduino development environment.
 * The [Seedtool Installation Instructions](seedtool/doc/build.md) show to install Seedtool on your *LetheKit* using the Arduino IDE.
 * The [Seedtool Application Instuctions](seedtool/README.md) describe how to generate and recover
-[BIP-32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) HD wallet master seeds in [BIP-39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) and [SLIP-39](https://github.com/satoshilabs/slips/blob/master/slip-0039.md) formats.
+[BIP-32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) HD wallet master seeds in [BIP-39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) and [SSKR](https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2020-011-sskr.md) formats.
 
 ## Status - Late Alpha
 
 *LetheKit* is currently under active development and in the late alpha testing phase. It should not be used for production tasks until it has had further testing and auditing.
 
-### Known Issues
-
-#### ⚠️ Warning: Lack of Round-trip Compatibility between BIP-39 and SLIP-39
+### ⚠️ Warning: Lack of Round-trip Compatibility between BIP-39 and SLIP-39
 
 At first glance, BIP-39 and SLIP-39 both appear to be means of converting a binary seed to a set of backup words and back. You might assume you could simply convert a BIP-39 backup to a binary seed, from that binary seed to SLIP-39, and then use the SLIP-39 backup to recover the same wallet as the original BIP-39 backup, but this is **NOT** the case. This is because the SLIP-39 algorithm that SatoshiLabs uses in their Trezor wallet does not derive the master secret in the same way as their BIP-39 algorithm does.
 
-Currently Blockchain Commons is investigating an alternative to SLIP-39 that allows round-trips with BIP-39. We want to ensure that the same seed will result in the same derived keys using either BIP-39 or our alternative approach.
+Currently Blockchain Commons and LetheKit implement an alternative to SLIP-39, called [Shamir Secret Key Recovery](https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2020-011-sskr.md) (**SSKR**), that allows round-trips with BIP-39. We want to ensure that the same seed will result in the same derived keys using either BIP-39 or our alternative approach.
 
 As SLIP-39 is not round-trip compatible with BIP-39, and SLIP-39 is under the control of SatoshiLabs and does not appear to be a fully community-controlled standard, Blockchain Commons is no longer endorsing SLIP-39.
 
@@ -48,7 +46,8 @@ This table below also establishes provenance (repository of origin, permalink, a
 | bip39 | [https://github.com/ksedgwic/bip39](https://github.com/ksedgwic/bip39) | 9b8fa3c7d145c39558c2534f6cf40879477d93a1 | 2018 Chris Howe | [MIT License](https://github.com/ksedgwic/bip39/blob/master/LICENSE) |
 | TRNG-for-ATSAMD51J19A-Adafruit-Metro-M4- | [https://github.com/SapientHetero/TRNG-for-ATSAMD51J19A-Adafruit-Metro-M4-](https://github.com/SapientHetero/TRNG-for-ATSAMD51J19A-Adafruit-Metro-M4-) | 17d5e36cd922ce7df8047d9c89633dca9b5ae122 | 2019 Ron Sutton | [MIT License](https://github.com/SapientHetero/TRNG-for-ATSAMD51J19A-Adafruit-Metro-M4-/blob/master/LICENSE.txt) |
 | libwally-core | [https://github.com/ElementsProject/libwally-core](https://github.com/ElementsProject/libwally-core) | e0d0634aea716d813744326ea6c7590eb9fc381c | Jon Griffiths (Blockstream) 2016 | [BSD/MIT license](https://github.com/ElementsProject/libwally-core/blob/master/LICENSE) |
-| Library-arduino-cbor | [https://github.com/jjtara/Library-Arduino-Cbor](https://github.com/jjtara/Library-Arduino-Cbor) | 996bf4a853513ee1fb94286691209a067c915bfb | jjtara 20014 | [Apache license](https://github.com/jjtara/Library-Arduino-Cbor/blob/master/LICENSE) |
+| Library-arduino-cbor | [https://github.com/jjtara/Library-Arduino-Cbor](https://github.com/jjtara/Library-Arduino-Cbor) | 996bf4a853513ee1fb94286691209a067c915bfb | jjtara 2014 | [Apache license](https://github.com/jjtara/Library-Arduino-Cbor/blob/master/LICENSE) |
+| ArduinoSTL | [https://github.com/mike-matera/ArduinoSTL](https://github.com/mike-matera/ArduinoSTL) | 7411816e2d8f49d96559dbaa47e327816dde860c | Mike Matera 1999 | [GNU LGPL](https://github.com/mike-matera/ArduinoSTL/blob/master/LICENSE) |
 
 ### Dependencies
 
@@ -60,7 +59,8 @@ The following internal Blockchain Commons projects are leveraged by *LetheKit*:
 
 - [BlockchainCommons/bc-crypto-base](https://github.com/blockchaincommons/bc-crypto-base) — Well-Reviewed and Audited Cryptographic Functions for Use in Blockchain Commons Software Projects
 - [BlockchainCommons/bc-shamir](https://github.com/BlockchainCommons/bc-shamir) - C Implementation of Shamir Secret Sharing for use in Blockchain Commons Software Projects
-- [BlockchainCommons/bc-slip39](https://github.com/BlockchainCommons/bc-slip39) - C Implementation of SLIP-39 Shamir Secret Sharing standard.
+- [BlockchainCommons/bc-bytewords](https://github.com/BlockchainCommons/bc-bytewords) - C library for encoding and decoding Bytewords.
+- [BlockchainCommons/bc-sskr](https://github.com/BlockchainCommons/bc-sskr) - Implementation of Shamir Secret Key Recovery (SSKR)
 
 ### Derived from ...
 
@@ -107,6 +107,7 @@ The following people directly contributed to this repository. You can add your n
 | ----------------- | ------------------- | ------------------------------------------------- | ------------------------------------- | -------------------------------------------------- |
 | Christopher Allen | Principal Architect | [@ChristopherA](https://github.com/ChristopherA) | \<[email protected]\> | FDFE 14A5 4ECB 30FC 5D22  74EF F8D3 6C91 3574 05ED |
 | Ken Sedgwick      | Project Lead        | [@ksedgwic](https://github.com/ksedgwic)          | \<[email protected]\>                  | 4695 E5B8 F781 BF85 4326 9639 BBFC E515 8602 5550  |
+| Gorazd Kovacic     | Project Maintainer  | [@gorazdko](https://github.com/gorazdko)  | \<[email protected]\>  | 41F0 EA16 99A7 4C1E 2FA4 1B53 8CF9 6BC3 FF9D BBCE  |
 
 ## Responsible Disclosure
 

seedtool/README.md

@@ -1,59 +1,12 @@
-# Warning!  There is a problem with LetheKit/seedtool BIP39/SLIP39 interoperability.
-
-### The following is being tracked as [Issue #38](https://github.com/BlockchainCommons/bc-lethekit/issues/38):
-
-#### What is the problem?
-
-The LetheKit seedtool application generates new wallets using dice
-entropy to create BIP39 and SLIP39 recovery mnemonics. The BIP39 and
-SLIP39 mnemonics represent valid wallets, but they are not the same
-wallet.
-
-This is a serious problem.  If both BIP39 and SLIP39 backups are
-created at the same time and funds are placed in the BIP39 wallet the
-SLIP39 backup will fail to recover the same wallet and the funds would
-be lost.
-
-#### Why is this the case?
-
-Andrew Kozlik explains it well in this [GitHub comment]
-(https://github.com/iancoleman/slip39/issues/1#issuecomment-563213494)
-
-#### How can matching BIP39 and SLIP39 backups be made?
-
-Andrew Kozlik explains (above) that in principle, SLIP39 shares which
-are 59 words long could match a BIP39 mnemonic.  In practice SLIP39
-shares of this length are non-standard and unlikely to be supported by
-any devices or applications.  The extreme length is also significantly
-painful to record and enter.
-
-#### Impact on LetheKit/seedtool:
-
-The desired feature of (standard) matching BIP39 and SLIP39 backups is
-not possible.
-
-The conversion of a BIP39 backup into a SLIP39 backup is not possible.
-
-The conversion of a SLIP39 backup into a BIP39 backup is not possible.
-
-LetheKit/seedtool can generate valid BIP39 and SLIP39 wallets but
-should not allow generation of both at the same time or suggest it
-can convert between the two.
-
-LetheKit can restore SLIP39 backups, but a mechanism to export the
-master secret (likely via QR code) would need to be added.
-
-## The original (invalid) directions follow:
-
 # Seedtool Application Instructions
 
 The *seedtool* utility allows you to generate and recover
 [BIP-32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki)
 HD wallet master seeds using
 [BIP-39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki)
 and
-[SLIP-39](https://github.com/satoshilabs/slips/blob/master/slip-0039.md)
-formats.
+[SSKR](https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2020-011-sskr.md)
+formats. In addition, it supports viewing XPUB keys and addresses in different formats.
 
 ## Compile and Upload Instruction
 
@@ -67,31 +20,32 @@ There are three ways to insert a key into the *seedtool*:
 
 ### Key Generation with Dice
 
-By rolling dice and typing the values, you can gather enough auditable entropy to generate a secure master seed.  Rolling 50 dice gathers
+By rolling dice and typing the values, you can gather enough auditable entropy to generate a secure master seed. Rolling 50 dice gathers
 roughly 128 bits of entropy.
 
 ![Generate Seed](doc/images/generate-seed.png)
 
 ### BIP-39 Key Recovery
 
 You can insert a key into the *seedtool* by entering its BIP-39
-recovery mnemonic passphrase.  From there you can generate SLIP-39
+recovery mnemonic passphrase.  From there you can generate SSKR
 shares.
 
 ![BIP-39 Restore](doc/images/bip39-restore.png)
 
-### SLIP-39 Key Recovery
+### SSKR Recovery
 
-If you possess enough shares of a SLIP-39 set, you can recover the
+If you possess enough shares of a SSKR set, you can recover the
 master seed with *seedtool*.  From there you can generate the BIP-39
 mnemonic passphrase which will allow you to use it with most wallets.
 
-![SLIP-39 Recovery Menu](doc/images/slip39-restore-menu.png) ![SLIP-39 Share Entry](doc/images/slip39-share-restore.png)
+![SSKR Recovery Menu](doc/images/sskr-restore-menu.png) ![SSKR Share Entry](doc/images/sskr-share-restore.png)
 
 ## Functions with a Seed
 
 Once you have a seed through any of the prior flows, you can create
-BIP-39 and SLIP-39 mnemonic passphrases.
+BIP-39 and SSKR mnemonic passphrases. In addition you can view extended public
+keys, wallet addresses etc. 
 
 ![Seed Present Menu](doc/images/seed-present.png)
 
@@ -102,12 +56,48 @@ offline fashion (e.g., hammering into metal).
 
 ![BIP-39 View](doc/images/bip39-view.png)
 
-### SLIP-39 Generation
+### SSKR Generation
 
-SLIP-39 requires some configuration choices to determine total number of shares
+SSKR requires some configuration choices to determine total number of shares
 and the required number of shares present to recover.
 
-![SLIP-39 Generation Config](doc/images/config-slip39.png) ![SLIP-39 Share View](doc/images/slip39-share-view.png)
+![SSKR Generation Config](doc/images/config-sskr.png) ![SSKR Share View](doc/images/sskr-share-view.png)
+
+You can choose among different formats:  
+![SSKR Share Format](doc/images/sskr-share-format.png)
+![SSKR Share View UR](doc/images/sskr-share-view-ur.png) ![SSKR Share View QRUR](doc/images/sskr-share-view-qrur.png)
+
+### Displaying XPUBs
+
+Extended public keys (XPUBs) can be shown in different formats (base58, UR, QR) with different
+options (slip132, with derivation path). Derivation path can be manually set.
+
+![XPUB BASE58](doc/images/xpub_base58.png)
+![XPUB OPTIONS](doc/images/xpub_options.png)
+![XPUB UR](doc/images/xpub_ur.png)
+
+![XPUB OPTIONS](doc/images/xpub_qr_text.png)
+![XPUB OPTIONS](doc/images/xpub_qrur.png)
+![XPUB DERIVATION](doc/images/xpub_derivation.png)
+
+### Displaying Seed
+
+You can choose to export seed in UR or QR-UR format.
+
+![seed ur](doc/images/seed_ur.png)
+![seed qrur](doc/images/seed_qrur.png)
+
+
+### Displaying Addresses
+
+![ADDR TEXT](doc/images/address_bech32.png) ![ADDR ur](doc/images/address_ur.png)
+![ADDR qr](doc/images/address_qr.png) ![ADDR qrur](doc/images/address_qrur.png)
+![ADDR format](doc/images/address_format.png)
+
+A wallet can be exported in the 4 different formats (text, QR, UR and QR-UR):
+
+![wallet export](doc/images/wallet_export.png) ![wallet export text](doc/images/wallet_export_text.png)
+![wallet export text](doc/images/wallet_export_qr.png) ![wallet export text](doc/images/wallet_export_qrur.png)
 
 ## Common Workflows
 
@@ -124,20 +114,20 @@ To execute this flow with *seedtool*:
 1. Generate a new master seed using 50+ die rolls.
 2. Record your master BIP-39 backup in a secure manner (hammer into metal).
    This BIP-39 backup may be restored into most other wallets for common use.
-3. Optionally create a SLIP-39 sharded backup set which can serve as
+3. Optionally create a SSKR sharded backup set which can serve as
    long-term cold storage.
 
-### Generate a SLIP-39 Backup Set for an Existing Wallet
+### Generate a SSKR Backup Set for an Existing Wallet
 
 If you've already got a wallet in use, and have the BIP-39 backup for
-it, you can generate a SLIP-39 backup set as well:
+it, you can generate a SSKR backup set as well:
 1. Restore your seed in *seedtool* using your BIP-39 backup.
-2. Create a SLIP-39 sharded backup.
+2. Create a SSKR sharded backup.
 
-### Recover a Master Seed from SLIP-39 Backup Shards
+### Recover a Master Seed from SSKR Backup Shards
 
 If you need to recover your master seed and have enough shards from a
-SLIP-39 backup set:
-1. Recover the master seed from the SLIP-39 shards.
+SSKR backup set:
+1. Recover the master seed from the SSKR shards.
 2. Create a BIP-39 mnemonic which may then be directly restored into
    most wallets for use.

seedtool/VALIDATE.md

@@ -21,43 +21,45 @@
     12 owner
 
 
-#### Restore SLIP39 (2 out of 3)
+#### Restore SSK (2 out of 3)
+
+Note: Each generation of SSKR shares (using the same binary seed) leads to different combination of words.
+However, the restoration of these words should always lead back to the same binary seed.
 
     Share #1
-     1 hour       6 source    11 overall   16 brother
-     2 aluminum   7 mobil     12 welcome   17 helpful
-     3 academic   8 early     13 custody   18 adult
-     4 acid       9 tenant    14 tadpole   19 huge
-     5 cargo     10 vampire   15 idea      20 home
+     1 tuna   6 gyro   11 zone   16 runs   21 waxy   26 buzz
+     2 acid   7 able   12 jazz   17 dark   22 zone   27 horn
+     3 epic   8 acid   13 draw   18 menu   23 body   28 luau
+     4 gyro   9 able   14 pool   19 luau   24 veto   29 tiny
+     5 cost   10 news  15 jump   20 hard   25 meow
      
-    hour aluminum academic acid cargo
-    source mobil early tenant vampire
-    overall welcome custody tadpole idea
-    brother helpful adult huge home
+    Share #2
+     1 tuna   6 gyro   11 whiz   16 scar   21 gala   26 zone
+     2 acid   7 able   12 very   17 also   22 huts   27 cost
+     3 epic   8 acid   13 stub   18 jowl   23 what   28 into
+     4 gyro   9 acid   14 join   19 idea   24 knob   29 ugly
+     5 cost   10 help  15 inky   20 yawn   25 song
 
+    Share #3
+     1 tuna   6 gyro   11 visa   16 fuel   21 rock   26 cook
+     2 acid   7 able   12 join   17 iris   22 ugly   27 slot
+     3 epic   8 acid   13 yurt   18 judo   23 soap   28 next
+     4 gyro   9 also   14 echo   19 fizz   24 safe   29 guru
+     5 cost   10 axis  15 heat   20 cost   25 dice
 
-    Share #2
-     1 hour       6 scramble  11 flea      16 genre
-     2 aluminum   7 sheriff   12 jury      17 spider
-     3 academic   8 taught    13 artwork   18 organize
-     4 agency     9 teammate  14 album     19 jury
-     5 beyond    10 reward    15 else      20 move
 
-    hour aluminum academic agency beyond
-    scramble sheriff taught teammate reward
-    flea jury artwork album else
-    genre spider organize jury move
+## Validation with seedtool
 
+```bash
+$ seedtool --version
+0.9.0
 
-    Share #3
-     1 hour       6 wisdom    11 boundary  16 wavy
-     2 aluminum   7 chest     12 envelope  17 observe
-     3 academic   8 cause     13 crisis    18 behavior
-     4 always     9 chubby    14 intend    19 punish
-     5 alien     10 hand      15 bumpy     20 isolate
-     
-    hour aluminum academic always alien
-    wisdom chest cause chubby hand
-    boundary envelope crisis intend bumpy
-    wavy observe behavior punish isolate
+$ seedtool --in sskr "tuna acid epic gyro cost gyro able acid also axis visa join yurt echo heat fuel iris judo fizz cost rock ugly soap safe dice cook slot next guru" "tuna acid epic gyro cost gyro able acid acid help whiz very stub join inky scar also jowl idea yawn gala huts what knob song zone cost into ugly"
+8d969eef6ecad3c29a3a629280e686cf
+
+$ seedtool --in dice 123456
+8d969eef6ecad3c29a3a629280e686cf
 
+$ seedtool --in dice 123456 | seedtool --in hex --out bip39
+mirror reject rookie talk pudding throw happy era myth already payment owner
+```