From 01a739afaa3bb811c685741b52af12735681bfa8 Mon Sep 17 00:00:00 2001 From: PROWLERx15 Date: Sun, 13 Apr 2025 18:24:20 +0530 Subject: [PATCH] update docs --- README.md | 50 ++++++++--------- docs/code_structure.md | 14 ++--- docs/debug_crash.md | 44 ++++++++------- docs/developer_tips.md | 35 ++++++------ docs/dice_verification.md | 37 ++++++------- docs/electrum.md | 8 +-- docs/feature_roadmap.md | 24 ++++----- docs/legacy_hardware.md | 10 ++-- docs/qr_formats.md | 16 +++--- docs/raspberry_pi_os_build_instructions.md | 53 +++++++++--------- docs/seed_qr/README.md | 12 ++--- docs/usb_relay.md | 62 +++++++++++----------- 12 files changed, 185 insertions(+), 180 deletions(-) diff --git a/README.md b/README.md index e483bc41..5c0329ed 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ If you have specific questions about the project, our [Telegram Group](https://t * Stateless, air-gapped operation: * Temporarily stores seeds in memory while the device is powered; all memory is wiped when power is removed. * SD card removable after boot to ensure no secret data can be written to it. - * No wifi or Bluetooth hardware onboard. + * No WiFi or Bluetooth hardware onboard. * Can only receive data via reading QR codes with its camera. * Can only send data by displaying QR codes on its screen. @@ -51,7 +51,7 @@ If you have specific questions about the project, our [Telegram Group](https://t * Import any existing seed phrase via an optimized seed word entry interface. * Partial support for Electrum Segwit seed phrases [(info)](docs/electrum.md). -* Wallet setup and transaction signing +* Wallet setup and transaction signing: * Script types: Taproot, native segwit, nested segwit, legacy (p2pkh). * Single sig and multisig xpub export. * Support for user-defined custom derivation paths. @@ -59,7 +59,7 @@ If you have specific questions about the project, our [Telegram Group](https://t * Verify the PSBT's single sig or multisig change outputs or self-transfer outputs. * Mainnet, testnet, and regtest. -* Additional utilities +* Additional utilities: * [SettingsQR](https://github.com/SeedSigner/seedsigner-settings-generator) to instantly reconfigure a SeedSigner for beginners, advanced users, or tailored to your preferences. * Scan a software wallet's receive or change address to verify that it's correct. * Address Explorer for single sig and multisig wallets. @@ -93,7 +93,7 @@ To build a SeedSigner, you will need: Notes: * You may need to solder the 40 GPIO pins (20 pins per row) to the Raspberry Pi Zero board. If you don't want to solder, most stores offer the board "with headers" already soldered on. -* The Pi Zero "W" or "2W" is often easier to find but has wifi/Bluetooth hardware. You can still use these boards and can optionally [disable the wifi/Bluetooth hardware](https://github.com/DesobedienteTecnologico/rpi_disable_wifi_and_bt_by_hardware). +* The Pi Zero "W" or "2W" is often easier to find but has WiFi/Bluetooth hardware. You can still use these boards and can optionally [disable the WiFi/Bluetooth hardware](https://github.com/DesobedienteTecnologico/rpi_disable_wifi_and_bt_by_hardware). * Other cameras with the above sensor module should work, but may not fit in the Orange Pill enclosure. * Choose the Waveshare screen carefully; they make a number of different boards that look very similar but ARE NOT COMPATIBLE! Make sure you purchase the model that has a resolution of 240x240 pixels. * Raspberry Pi 1 is also compatible, but will require a [hardware modification to the Waveshare LCD Hat](./docs/legacy_hardware.md). @@ -111,8 +111,8 @@ Instructions to build a SeedSigner OS image (using precisely the same process th ## Downloading the Software - -Download the current Version (0.8.5) software image that is compatible with your Raspberry Pi Hardware. The Pi Zero 1.3 is the most common and recommended board. +Download the current Version (0.8.5) software image that is compatible with your Raspberry Pi Hardware. The Pi Zero 1.3 is the most common and recommended board. + | Board | Download Image Link/Name | | --------------------- | --------------------------------- | |**[Raspberry Pi Zero 1.3](https://www.raspberrypi.com/products/raspberry-pi-zero/)** |[`seedsigner_os.0.8.5.pi0.img`](https://github.com/SeedSigner/seedsigner/releases/download/0.8.5/seedsigner_os.0.8.5.pi0.img) | @@ -124,9 +124,9 @@ Download the current Version (0.8.5) software image that is compatible with your |[Raspberry Pi 4 Model B](https://www.raspberrypi.com/products/raspberry-pi-4-model-b/) |[`seedsigner_os.0.8.5.pi4.img`](https://github.com/SeedSigner/seedsigner/releases/download/0.8.5/seedsigner_os.0.8.5.pi4.img) | |[Raspberry Pi 400](https://www.raspberrypi.com/products/raspberry-pi-400-unit/) |[`seedsigner_os.0.8.5.pi4.img`](https://github.com/SeedSigner/seedsigner/releases/download/0.8.5/seedsigner_os.0.8.5.pi4.img) | -Note: If you have physically removed the WiFi component from your board, you will still use the image file of the original(un-modified) hardware. (Our files are compiled/based on the *processor* architecture). Although it is better to spend a few minutes upfront to determine which specific Pi hardware/model you have, if you are still unsure which hardware you have, you can try using the pi0.img file. Making an incorrect choice here will not ruin your board, because this is software, not firmware. +Note: If you have physically removed the WiFi component from your board, you will still use the image file of the original (un-modified) hardware. (Our files are compiled/based on the *processor* architecture). Although it is better to spend a few minutes upfront to determine which specific Pi hardware/model you have, if you are still unsure which hardware you have, you can try using the pi0.img file. Making an incorrect choice here will not ruin your board, because this is software, not firmware. -**also download** these 2 signature verification files to the same folder +**Also download** these 2 signature verification files to the same folder: [The Plaintext manifest file](https://github.com/SeedSigner/seedsigner/releases/download/0.8.5/seedsigner.0.8.5.sha256.txt) [The Signature of the manifest file](https://github.com/SeedSigner/seedsigner/releases/download/0.8.5/seedsigner.0.8.5.sha256.txt.sig) @@ -147,7 +147,7 @@ We assume you are running the commands from a computer where both [GPG](https:// ### Step 1. Verify that the signature (.sig) file is genuine: -Run GPG's *fetch-keys* command to import the SeedSigner projects public key from the popular online keyserver called *Keybase.io*, into your computers *keychain*. +Run GPG's *fetch-keys* command to import the SeedSigner project's public key from the popular online keyserver called *Keybase.io*, into your computer's *keychain*. ``` @@ -169,7 +169,7 @@ The result must display "**Good signature**". Ignore any email addresses - *onl
On the *last* output line, look at your *rightmost* 16 characters (the 4 blocks of 4). -**Crucially, we must now check WHO that Primary key fingerprint /ID belongs to.** We will start by looking at Keybase.io to see if it is the *SeedSigner project* 's public key or not. +**Crucially, we must now check WHO that Primary key fingerprint /ID belongs to.** We will start by looking at Keybase.io to see if it is the *SeedSigner project*'s public key or not.
About the warning message:

Since you are about to match the outputted fingerprint/ID against the proofs at Keybase.io/SeedSigner, and thereby confirm who the pubkey really belongs to-, you can safely ignore this warning message: @@ -184,16 +184,16 @@ On the *last* output line, look at your *rightmost* 16 characters (the 4 blocks

More about how the verify command works:

-The verify command will attempt to decrypt the signature file (sha256.sig) by trying each public key already imported into your computer. If the public key we just imported (via fetch-keys), manages to: (a) successfully decrypt the .sig file , and (b), that result matches exactly to the clear-text equivalent (.sha256) of the .sig file, then its "a good signature"! +The verify command will attempt to decrypt the signature file (sha256.sig) by trying each public key already imported into your computer. If the public key we just imported (via fetch-keys), manages to: (a) successfully decrypt the .sig file , and (b), that result matches exactly to the clear-text equivalent (.sha256) of the .sig file, then it's "a good signature"! -Crucially, we must still manually check who *exactly* owns the Key ID which gave us that "Good signature". Thats what the warning message means- Who does the matching key really belong to? We will start by looking at keybase.io to see if it is "The SeedSigner project"'s public Key or not. +Crucially, we must still manually check who *exactly* owns the Key ID which gave us that "Good signature". That's what the warning message means- Who does the matching key really belong to? We will start by looking at keybase.io to see if it is "The SeedSigner project"'s public Key or not. Note that it is the file hashes of .sig and .sha256 that *verify* compares, not their raw contents.


-Now to determine ***who*** the Public key ID belongs to: Goto [Keybase.io/SeedSigner](https://keybase.io/seedsigner) +Now to determine ***who*** the Public key ID belongs to: Go to [Keybase.io/SeedSigner](https://keybase.io/seedsigner)
![SS - Keybase Website PubKey visual matching1_Cropped-80pct](https://user-images.githubusercontent.com/91296549/215326193-97c84e35-5570-4e52-bf3f-e86d367c8908.jpg) @@ -207,13 +207,13 @@ Now to determine ***who*** the Public key ID belongs to: Goto [Keybase.io/SeedSi
Learn more about how keybase.io helps you check that someone (online) is who they say they are:

Keybase.io allows you to independently verify that the public key saved on Keybase.io, is both authentic and that it belongs to the organization it claims to represent. - Keybase has already checked the three pubkey file locations cryptographically when they were saved there. You can further verify the key publications if you would like: + Keybase has already checked the three pubkey file locations cryptographically when they were saved there. You can further verify the key publications if you would like: - *via Keybase*: By clicking on any of the three blue badges to see that the "proof" was published at that location. (The blue badge marked as tweet, is in the most human-readable form and it is also a bi-directional link on Twitter) or, - *without keybase (out-of-band)*: By using these 3 links directly: [Twitter](https://twitter.com/SeedSigner/status/1530555252373704707), [Github](https://gist.github.com/SeedSigner/5936fa1219b07e28a3672385b605b5d2) and [SeedSigner.com](https://seedsigner.com/keybase.txt). This method can be used if you would like to make an even deeper, independent inspection without relying on Keybase at all, or if the Keybase.io site is no longer valid or it is removed entirely. -Once you have used one of these methods, you will know if the Public Key stored on Keybase, is genuinely from the SeedSinger Project or not. +Once you have used one of these methods, you will know if the Public Key stored on Keybase, is genuinely from the SeedSigner Project or not.


@@ -224,8 +224,8 @@ If the two ID's do *not* match, then you must stop here immediately. Do not cont ### Step 2. Verifying that the *software images/binaries* are genuine -Now that you have confirmed that you do have the real SeedSigner Project's Public Key (ie the 16 characters match) - you can return to your terminal window. Running the *shasum* command, is the final verification step and will confirm (via file hashing) that the software code/image files, were also not altered since publication, or even during your download process. -(Prior to version 0.6.0 , your verify command will check the .zip file which contains the binary files.) +Now that you have confirmed that you do have the real SeedSigner Project's Public Key (ie the 16 characters match) - you can return to your terminal window. Running the *shasum* command, is the final verification step and will confirm (via file hashing) that the software code/image files, were also not altered since publication, or even during your download process. +(Prior to version 0.6.0, your verify command will check the .zip file which contains the binary files.) **On Linux or OSX:** Run this command ``` @@ -246,7 +246,7 @@ seedsigner_os.0.8.5.[Your_Pi_Model_For_Example:pi02w].img: OK **If you receive the "OK" message** for your **seedsigner_os.0.8.5.[Your_Pi_Model_For_Example:pi02w].img file**, as shown above, then your verification is fully complete! **All of your downloaded files have now been confirmed as both authentic and unaltered!** You can proceed to create/write your MicroSD card😄😄 !! -If your file result shows "FAILED", then you must stop here immediately. Do not continue. Contact us for assistance at the Telegram group address above. +If your file result shows "FAILED", then you must stop here immediately. Do not continue. Contact us for assistance at the Telegram group address above.
@@ -265,19 +265,19 @@ To write the SeedSigner software onto your MicroSD card, there are a few options | DD Command Line Utility | Built-in to Linux and MacOS, the DD (Data Duplicator) is a tool for advanced users. If not used carefully it can accidentally format the incorrect disk! | Built-in to Linux and MacOS | Be sure to download the software from the genuine publisher. -Either of the Etcher or Pi Imager software is recommended. Some SeedSigner users have reported a better experience with one or the other. So, if the one application doesn’t work well for your particular machine, then please try the other one. +Either of the Etcher or Pi Imager software is recommended. Some SeedSigner users have reported a better experience with one or the other. So, if the one application doesn't work well for your particular machine, then please try the other one.
### **General Considerations:** The writing and verify steps are very quick from version 0.6.0 upwards, so please pay close attention to your screen. Make sure to set any write-protection physical slider on the MicroSD Card Adapter to UN-locked. -You also don’t need to pre-format the MicroSD beforehand. You *dont* need to unzip any .zip file beforehand. -Current Etcher and Pi Imager software will perform a verify action (by default) to make sure the card was written successfully! Watching for that verify step to complete successfully, can save you a lot of headaches if you later need to troubleshoot issues where your SeedSigner device doesn’t boot up at power on. -Writing the MicroSd card is also known as flashing. +You also don't need to pre-format the MicroSD beforehand. You *don't* need to unzip any .zip file beforehand. +Current Etcher and Pi Imager software will perform a verify action (by default) to make sure the card was written successfully! Watching for that verify step to complete successfully, can save you a lot of headaches if you later need to troubleshoot issues where your SeedSigner device doesn't boot up at power on. +Writing the MicroSD card is also known as flashing. It will overwrite everything on the MicroSD card. If the one application fails for you, then please try again using our other recommended application. -Advanced users may want to try the Linux/MacOS *DD* command instead of using Etcher or Pi Imager, however, a reminder is given that DD can overwrite the wrong disk if you are not careful ! +Advanced users may want to try the Linux/MacOS *DD* command instead of using Etcher or Pi Imager, however, a reminder is given that DD can overwrite the wrong disk if you are not careful! #### **Specific considerations for Windows users:** -Use the Pi imager software as your first choice on Windows. Windows can sometimes flag the writing of a MicroSD as risky behaviour and hence it may prevent this activity. If this happens, your writing/flashing will fail, hang or wont even begin, in which case you should to try to run the Etcher/Pi-Imager app "As administrator", (right-click and choose that option). It can also be blocked by windows security in some cases, so If you have the (non-default) *Controlled Folder Access* option set to active, try turning that *off* temporarily. +Use the Pi imager software as your first choice on Windows. Windows can sometimes flag the writing of a MicroSD as risky behaviour and hence it may prevent this activity. If this happens, your writing/flashing will fail, hang or won't even begin, in which case you should try to run the Etcher/Pi-Imager app "As administrator", (right-click and choose that option). It can also be blocked by windows security in some cases, so If you have the (non-default) *Controlled Folder Access* option set to active, try turning that *off* temporarily. @@ -288,7 +288,7 @@ Use the Pi imager software as your first choice on Windows. Windows can sometime ### Open Pill -The Open Pill enclosure design is all about quick, simple and inexpensive depoloyment of a SeedSigner device. The design does not require any additional hardware and can be printed using a standard FDM 3D printer in about 2 hours, no supports necessary. A video demonstrating the assembly process can be found [here](https://youtu.be/gXPFJygZobEa). To access the design file and printable model, click [here](https://github.com/SeedSigner/seedsigner/tree/main/enclosures/open_pill). +The Open Pill enclosure design is all about quick, simple and inexpensive deployment of a SeedSigner device. The design does not require any additional hardware and can be printed using a standard FDM 3D printer in about 2 hours, no supports necessary. A video demonstrating the assembly process can be found [here](https://youtu.be/gXPFJygZobEa). To access the design file and printable model, click [here](https://github.com/SeedSigner/seedsigner/tree/main/enclosures/open_pill). ### Orange Pill diff --git a/docs/code_structure.md b/docs/code_structure.md index 50b7d315..5a0f0276 100644 --- a/docs/code_structure.md +++ b/docs/code_structure.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 ``, `