Merge pull request #731 from PROWLERx15/update-docs

[Documentation] Improved Docs

Author: newtonick

.github/pull_request_template.md

@@ -14,7 +14,7 @@ This pull request is categorized as a:
 
 ## Checklist
 
-- [ ] I’ve run `pytest` and made sure all unit tests pass before sumbitting the PR
+- [ ] I’ve run `pytest` and made sure all unit tests pass before submitting the PR
 
 If you modified or added functionality/workflow, did you add new unit tests?
 

README.md

@@ -1,21 +1,17 @@
 # Code Structure
 
-SeedSigner roughly follows a Model-View-Controller approach. Like in a typical web app (e.g. Flask) the `View`s can be called as needed like individual web urls. After completing display and interaction with the user, the `View` then decides where to route the user next, analogous to a web app returning a `response.redirect(url)`.
-
-The `Controller` then ends up being quite stripped down. For example, there's no need for a web app's `urls.py` since there are no mappings from url to `View` to maintain since we're not actually using a url/http routing approach.
-
-`View`s have to handle user interaction so there are `while True` loops that cycle between waiting for user input, gathering data, and then updating the UI components accordingly. You wouldn't find this kind of cycle in a web app because this sort of interactive user input is handled in the browser at the html/css/js level.
+SeedSigner roughly follows a Model-View-Controller approach. Like in a typical web app (e.g. Flask), the `View`s can be called as needed like individual web URLs. After completing display and interaction with the user, the `View` then decides where to route the user next, analogous to a web app returning a `response.redirect(URL)`.
 
+The `Controller` then ends up being quite stripped down. For example, there's no need for a web app's `urls.py` since there are no mappings from URL to `View` to maintain since we're not actually using a URL/HTTP routing approach.
 
+`View`s have to handle user interaction, so there are `while True` loops that cycle between waiting for user input, gathering data, and then updating the UI components accordingly. You wouldn't find this kind of cycle in a web app because this sort of interactive user input is handled in the browser at the HTML/CSS/JS level.
 
 * `Model`s: Store the persistent settings, the in-memory seeds, current wallet information, etc.
 * `Controller`: Manages the state of the world and controls access to global resources.
 * `View`s: Implementation of each screen. Prepares relevant data for display. Must also instantiate the display objects that will actually render the UI.
-* `gui.screens`: Re-usable formatted UI renderers.
+* `gui.screens`: Reusable formatted UI renderers.
 * `gui.components`: Basic individual UI elements that are used by the `templates` such as the top nav, buttons, button lists, text displays.
 
-In an typical webserver context the `View` would send data to an html template (e.g. Jinja) which would then dynamically populate the page with html elements like `<input>`, `<button>`, `<img>`, etc. This is analgous to our `gui.screens` constructing a UI renderer by piecing together various `gui.components` as needed.
-
-
+In a typical web server context, the `View` would send data to an HTML template (e.g. Jinja) which would then dynamically populate the page with HTML elements like `<input>`, `<button>`, `<img>`, etc. This is analogous to our `gui.screens` constructing a UI renderer by piecing together various `gui.components` as needed.
 
 `Controller` is a global singleton that any `View` can access and update as needed.

docs/code_structure.md

@@ -1,37 +1,45 @@
-## Debugging a Crash for advanced (technical) users
+## Debugging a Crash for Advanced (Technical) Users
 
 These instructions are intended to help users of SeedSigner provide crash exception and traceback logs to developers to aid in troubleshooting and resolving bugs.
 
 ### Testnet vs Mainnet
 
-Whenever possible recreate a crash in testnet. This will help avoid accidently revealing private information about yourself, your bitcoin transactions, or lose any funds.
+Whenever possible, recreate a crash in testnet. This will help avoid accidentally revealing private information about yourself, your Bitcoin transactions, or losing any funds.
 
-### Network connected SeedSigner
+### Network-Connected SeedSigner
 
-If you are using SeedSigner for development and testing, then I recommend network access via ssh to view crash logs. Follow [these](https://github.com/SeedSigner/seedsigner/blob/main/docs/usb_relay.md) instructions to setup a USB relay for internet access. You can also connect your SeedSigner to Wifi if you have a rasp pi zero w/ wifi.
+If you are using SeedSigner for development and testing, then we recommend network access via SSH to view crash logs. Follow [these](https://github.com/SeedSigner/seedsigner/blob/main/docs/usb_relay.md) instructions to set up a USB relay for internet access. You can also connect your SeedSigner to WiFi if you have a Raspberry Pi Zero W with WiFi.
 
-### Airgapped debugging setup
+### Airgapped Debugging Setup
 
-If you are using SeedSigner for mainnet transactions, then do not connect your device to a network or the internet. Instead connect your SeedSigner to a HDMI display (without internet) and a USB keyboard. This will require an HDMI adapter and micro USB to USB A adapter. Plug in the HDMI display and keyboard before powering on SeedSigner. The password for the SeedSigner pi user is `raspberry`.
+If you are using SeedSigner for mainnet transactions, then do not connect your device to a network or the internet. Instead, connect your SeedSigner to an HDMI display (without internet) and a USB keyboard. This will require an HDMI adapter and a micro USB to USB A adapter. Plug in the HDMI display and keyboard before powering on SeedSigner. The password for the SeedSigner pi user is `raspberry`.
 
-### Debugging steps
+### Debugging Steps
 
-At this point you should be signed into the pi user either on a HDMI display (via command line) or a ssh connection.
+At this point, you should be signed into the pi user either on an HDMI display (via command line) or an SSH connection.
 
-Follow these steps to setup a debug session.
+Follow these steps to set up a debug session:
 
-`cd seedsigner/src`
+1. Navigate to the source directory:
+   ```bash
+   cd seedsigner/src
+   ```
 
-`nano settings.ini`
+2. Edit the settings file:
+   ```bash
+   nano settings.ini
+   ```
 
-in nano editor change `debug = False` to `debug = True` (case sensitive). Save and exit settings.ini.
+3. In the nano editor, change `debug = False` to `debug = True` (case sensitive). Save and exit settings.ini.
 
-stop the seedsigner systemd process by running
+4. Stop the SeedSigner systemd process:
+   ```bash
+   sudo systemctl stop seedsigner.service
+   ```
 
-`sudo systemctl stop seedsigner.service`
-
-now start the python app manually by running
-
-`python3 main.py`
+5. Start the Python app manually:
+   ```bash
+   python3 main.py
+   ```
 
 SeedSigner should now be up and running. Keep it connected to the display and keyboard. Recreate the steps to cause the crash. The traceback log and exception will be displayed on the HDMI display.

docs/debug_crash.md

@@ -3,12 +3,16 @@
 ### Quickly generate a new seed to test with
 Generate a new 12- or 24-word seed via [https://iancoleman.io/bip39/](https://iancoleman.io/bip39/).
 
-Access a `python3` environment that has the `embit` library installed (e.g. your own local machine, ssh into the SeedSigner, etc)
+Access a `python3` environment that has the `embit` library installed (e.g., your own local machine, SSH into the SeedSigner, etc.).
 
-Start a python REPL session by just typing: `python3`
-
-Paste in the following but insert your newly generated mnemonic:
+Start a `python3` REPL session by typing:
+```bash
+python3
 ```
+
+Paste in the following code (replace the seed phrase with your newly generated mnemonic):
+
+```python
 from embit import bip39
 seed_phrase = "smoke chimney announce candy glory tongue refuse fatigue cricket once consider beef treat urge wing deny gym robot tobacco adult problem priority wheat diagram"
 data = ""
@@ -19,7 +23,7 @@ for word in seed_phrase.split(" "):
 print(data)
 ```
 
-For the seed in the snippet, you should see:
+For the example seed phrase above, you should see:
 ```
 163803200074026607961827144306700411123603780160185419152013046908321497181700301371136719990487
 ```
@@ -28,35 +32,36 @@ Take the output and paste it into a [QR code generator](https://www.the-qrcode-g
 
 Start up SeedSigner's UI to import a seed from a QR code. Scan the new QR code and you're good to go!
 
-
 # Advanced developer notes
 
 ## Backup an SD card
 
-You can back up and restore any size SD card but the process is a little inefficient so the bigger the source SD card, the bigger the backup will be and the longer it'll take to create (and even longer to image back to a new SD card), even if most of the card is blank.
+You can back up and restore any size SD card, but the process is a little inefficient. The bigger the source SD card, the bigger the backup will be and the longer it'll take to create (and even longer to image back to a new SD card), even if most of the card is blank.
 
-You can restore a backup image to an SD card of the same or larger size. So it's strongly recommended to do repetitive development work on a smaller card that's easier to backup and restore. Once the image is stabilized, then write it to a bigger card, if necessary (that being said, there's really no reason to use a large SD card for SeedSigner. An 8GB SD card is more than big enough).
+You can restore a backup image to an SD card of the same or larger size. It's strongly recommended to do repetitive development work on a smaller card that's easier to backup and restore. Once the image is stabilized, then write it to a bigger card, if necessary (that being said, there's really no reason to use a large SD card for SeedSigner. An 8GB SD card is more than big enough).
 
-Insert the SD card into a Mac/Linux machine and create a compressed img file.
+### Steps to create a backup:
 
-First verify the name of your SD card:
+1. Insert the SD card into a Mac/Linux machine
+2. Verify the name of your SD card:
 
-```
+```bash
 # Mac:
 diskutil list
 
 # Linux:
 sudo fdisk -l
 ```
 
-It will most likely be `/dev/disk1` on most systems.
+The device will most likely be `/dev/disk1` on most systems.
 
-Now we use `dd` to clone and `gzip` to compress it. Note that we reference the SD card by adding an `r` in front of the disk name. This speeds up the cloning considerably.
+3. Create a compressed backup using `dd` and `gzip`. Note that we reference the SD card by adding an `r` in front of the disk name to speed up the cloning process:
 
-```
+```bash
 sudo dd if=/dev/rdisk1 conv=sparse bs=4m | gzip -9 > seedsigner.img.gz
 ```
 
 The process should take about 15 minutes and will typically generate a roughly 1.1GB image.
 
-To restore from your backup image, just use the Raspberry Pi Imager. Remember that you can only write it to an SD card of equal or greater size than the original SD card.
+### Restoring from backup
+To restore from your backup image, use the Raspberry Pi Imager. Remember that you can only write it to an SD card of equal or greater size than the original SD card.

docs/developer_tips.md

@@ -7,20 +7,19 @@ As usual: Don't Trust, Verify!<br>
 <br><br>
 **Note:**<br>
 **Do NOT use this with any seed you want to use later with real funds. This exercise is only for checking that the independent codebases get to the same end result!**<br>
-**However, if you do want to check your real seedphrases you should download the Iancoleman and/or Bitcoiner.Guide tools onto an airgapped, ephemeral computer (e.g. using tails-OS) and perform these tests on there. Destroy/abandon the TailsOS afterwards.**<br>
+**However, if you do want to check your real seed phrases you should download the Ian Coleman and/or Bitcoiner.Guide tools onto an airgapped, ephemeral computer (e.g. using Tails-OS) and perform these tests on there. Destroy/abandon the Tails-OS afterwards.**<br>
 **Never input seed phrases that you intend to use to store real funds onto an internet-connected computer!!!**
 <br><br><br>
 
 ## 99 Dice Rolls / 24 Seed Words Example
 
-The following 99 dice roll results are used in the verification steps as an example for a 24 words seed:<br>
+The following 99 dice roll results are used in the verification steps as an example for a 24-word seed:<br>
 > 655152231316521321611331544441236164664431121534415633526456254462245546236542364246312613322234612
 
 The corresponding 24 seed words are:<br>
 > eyebrow obvious such suggest poet seven breeze blame virtual frown dynamic donor harsh pigeon express broccoli easy apology scatter force recipe shadow claim radio
 
 (Scroll down near the end to see result values for a 50 dice rolls / 12 seed words example)
-<br><br><br>
 
 ## Creating seed via Dice rolls in SeedSigner (here v0.6.0)
 
@@ -56,7 +55,7 @@ Keep the SeedSigner open and the newly created seed still loaded as we will need
 ## Create new wallet from seed in Sparrow Wallet to see xpub/zpub and addresses
 
 Go to https://www.sparrowwallet.com/download/ and download the release version supported by your operating system.<br><br>
-Open Sparrow Wallet, go to 'File' menu and select 'New Wallet'. Enter a name (e.g. test), and click 'Create Wallet'.<br><br>
+Open Sparrow Wallet, go to the 'File' menu and select 'New Wallet'. Enter a name (e.g. test), and click 'Create Wallet'.<br><br>
 Click 'Airgapped Hardware Wallet' (1) and click on the 'Scan' button in the SeedSigner entry (2) which will open the camera scan screen:<br>
 <kbd><img src="img/dicedoc/sparrow_wallet_1.png"></kbd>
 
@@ -84,7 +83,7 @@ Go to https://iancoleman.io/bip39 and check 'Show entropy details' (1):<br>
 <br>
 Make sure to check (1) 'Hex' and (2) '24 Words' as 'Mnemonic Length'.<br>
 (Do not use 'dice' format because dice 6 will be replaced by 0).<br>
-Then enter the 99 dices numbers in (3). The corresponding seed words are shown in (4):<br>
+Then enter the 99 dice numbers in (3). The corresponding seed words are shown in (4):<br>
 <kbd><img src="img/dicedoc/coleman_verify.png"></kbd>
 <br><br>
 The 24 seed words are the same in SeedSigner and the Ian Coleman tool.
@@ -144,7 +143,7 @@ Compare to zpub in Sparrow:<br>
 <kbd><img src="img/dicedoc/sparrow_zpub.png"></kbd>
 <br>
 
-Zpub is the same as shown in SeedSigner, Sparrow and Ian Colemand tool.
+Zpub is the same as shown in SeedSigner, Sparrow and Ian Coleman tool.
 <br><br>
 **Addresses:**<br>
 Scroll down a little bit where the receive addresses are shown and compare to the ones generated in Sparrow ('Addresses' tab of the wallet):<br>
@@ -163,10 +162,10 @@ Check that the change addresses all match.
 
 ## 50 Dice Rolls / 12 Seed Words Example
 
-SeedSigner supports the creation of mnenomic seeds both with 12 or 24 seed words corresponding to 50 or 99 dice rolls. Below are some example result values for using 50 dice rolls only.<br><br>
-All the steps shown can be executed the same way, just select the '12 words (50 rolls)' option in SeedSigner and change the 'Mnenomic Length' dropdown boxes in both web tools to '12 Words'.<br><br>
+SeedSigner supports the creation of mnemonic seeds both with 12 or 24 seed words corresponding to 50 or 99 dice rolls. Below are some example result values for using 50 dice rolls only.<br><br>
+All the steps shown can be executed the same way, just select the '12 words (50 rolls)' option in SeedSigner and change the 'Mnemonic Length' dropdown boxes in both web tools to '12 Words'.<br><br>
 
-50 dice roll results as an example for a 12 words seed:<br>
+50 dice roll results as an example for a 12-word seed:<br>
 > 65515223131652132161133154444123616466443112153441
 
 The corresponding 12 seed words are:<br>
@@ -246,7 +245,7 @@ python3 mnemonic.py -h
         python3 mnemonic.py coins 1111100111...
 
         # 256 coin flips / 24-word mnemonic
-        python mnemonic.py coins 0010111010...
+        python3 mnemonic.py coins 0010111010...
 
         # GENERATE 50 random dice rolls / 12-word mnemonic
         python3 mnemonic.py dice rand12

docs/dice_verification.md

@@ -1,8 +1,8 @@
-# SeedSigner Electrum seed phrase support
+# SeedSigner Electrum Seed Phrase Support
 
-SeedSigner supports loading of [Electrum's Segwit seed phrases](https://electrum.readthedocs.io/en/latest/seedphrase.html#electrum-seed-version-system).  This is considered an Advanced feature that is disabled by default.  
+SeedSigner supports loading of [Electrum's SegWit seed phrases](https://electrum.readthedocs.io/en/latest/seedphrase.html#electrum-seed-version-system). This is considered an Advanced feature that is disabled by default.
 
-To load an Electrum Segwit seed phrase, first enable Electrum seed support in Settings -> Advanced -> Electrum seed support.  After this option is enabled, the user will now be able to enter an Electrum seed phrase by selecting "Enter Electrum seed" in the Load Seed screen.
+To load an Electrum SegWit seed phrase, first enable Electrum seed support in Settings -> Advanced -> Electrum seed support. After this option is enabled, the user will now be able to enter an Electrum seed phrase by selecting "Enter Electrum seed" in the Load Seed screen.
 
 Some SeedSigner functionality is deliberately disabled when using an Electrum mnemonic:
 
@@ -11,5 +11,5 @@ Some SeedSigner functionality is deliberately disabled when using an Electrum mn
 - SeedQR backups
 	- Since Electrum seeds are not supported by other SeedQR implementations, it would be dangerous to use SeedQR as a backup tool for Electrum seeds and is thus disabled
 - Custom derivations
-	- Hard coded derivation path and script types in SeedSigner to match Electrum wallet software. These are m/0h for single sig and m/1h for multisig
+	- Hard-coded derivation path and script types in SeedSigner to match Electrum wallet software. These are m/0h for single sig and m/1h for multisig
 	- User-chosen custom derivations are thus not supported for Electrum seeds