Minor updates / rewording.

README.md

@@ -18,8 +18,7 @@ Join the conversation on the <a href="https://t.me/mybonk_build" target="_blank"
 
 ---
 # Table of Contents 
-Tip: Click the 'TOC' button (![Github TOC button](docs/img/github-toc-icon.svg)) in the
-top right corner to display the table of content in a separate pane.
+Tip: Click the 'TOC' button (![Github TOC button](docs/img/github-toc-icon.svg)) in one of the top corners to display the table of content in a separate pane.
 - [0. Before you start](#before-you-start)
   - [Overview](#overview)
   - [Terminology](#terminology)
@@ -57,57 +56,56 @@ top right corner to display the table of content in a separate pane.
 
 Read this document from the beginning to the end before getting your hands on the keyboard. Also watch this presentation by Valentin Gagarin about [Flattening the Learning Curve for Nix/NixOS](https://www.youtube.com/watch?v=WFRQvkfPoDI&list=WL&index=87) as Nix/NixOS is the cornerstone of MY₿ONK.
 
-You might have a feeling of "déjà vu" as it is essentially a scrambled from various sources including [nixOS](https://nixos.org) and [nixOS manual](https://nixos.org/manual/nixos/stable/index.html), [nixOS Wiki](https://nixos.wiki/wiki/Main_Page), [nix-bitcoin](https://nixbitcoin.org/), [Virtual Box](https://www.virtualbox.org/), [Raspibolt](https://raspibolt.org/) and [Raspiblitz](https://github.com/rootzoll/raspiblitz#readme) (although the approach of MY₿ONK is radically different). 
+You might have a feeling of "déjà vu" as it is essentially a scrambled from various sources from [nixOS manual](https://nixos.org/manual/nixos/stable/index.html), [nixOS Wiki](https://nixos.wiki/wiki/Main_Page), [nix-bitcoin](https://nixbitcoin.org/), [Virtual Box](https://www.virtualbox.org/), [Raspibolt](https://raspibolt.org/), [Raspiblitz](https://github.com/rootzoll/raspiblitz#readme) (although the approach of MY₿ONK is radically different). 
 
-If you have any experience with the command line or already run any other full node you have a significant advantage, you could complete this setup in 2 hours maybe, otherwise allocate 1 day.
+If you have any experience with the command line or already run any other full node you have a significant advantage, you could complete this setup in 2 hours maybe, otherwise allocate 1 day (excluding the time required for blockchain download and indexations which is what takes most time, possibly days unless you have a recent local copy of these e.g. on the local network or USB drive).
 
-We [collaboratively] take great pride and care maintaining this document so it remains up to date and concise, often it refers to external links. Explore these external links when instructed to, this will make the journey smoother.
-  
-It is assumed that you know a little bit of everything but not enough so we show you the way step by step based on the typical MY₿ONK setup.
+It is assumed that you know a little bit of everything but not enough so we show you the way step by step based on the MY₿ONK setup (one MY₿ONK orchestrator and one MY₿ONK console).
+
+We [collaboratively] take great pride and care maintaining this document so it remains up to date and concise, often it refers to external links. Explore these external links, it will make your journey smoother.
 
 You too can contribute to improving this document on GitHub.
 
 Enjoy the ride, no stress, check out our  [baby rabbit holes](/baby-rabbit-holes.md)  :hole: :rabbit2: and the [FAQ](/faq.md) 👷 
 
-
-### Overview
-This example small ecosystem consists of only two elements that we are going to build together:
-
-
-- **One MY₿ONK orchestrator:**
-  This machine is used to orchestrate your fleet of MY₿ONK consoles, it is essentially a Linux with a few additional software installed including the Nix package manager.
-- **One MY₿ONK console:**
-  This machine runs the [MY₿ONK core](https://github.com/mybonk/mybonk-core) stack on NixOS. It is setup once and its configuration can be updated remotely using MY₿ONK orchestrator.
-
 ### Terminology
 - '``#``' stands for '````$ sudo````' (or '```$ doas```' which is a similar tool).
-- **MY₿ONK core**: Or simply 'MY₿ONK' is a tailor-made full-node [software stack](https://github.com/mybonk/mybonk-core) for MY₿ONK console (although it can run on pretty much any hardware if you are ready to tune and hack a little bit). MY₿ONK core is based on nix-bitcoin itself based on nixOS.
-- **MY₿ONK console**: A full-node bitcoin-only hardware platform designed with anonymity, security, low price, performance, durability, low-energy, supply chain resilience and generic parts in mind.
-- **MY₿ONK orchestrator**:
-  Used to orchestrate your [fleet of] MY₿ONK console[s], it is currently a separate Linux machine with a few additional software installed on including the Nix package manager. The MY₿ONK orchestrator will soon be integrated within the MY₿ONK console but for now it is a separate machine ([ref #30](https://github.com/mybonk/mybonk-core/issues/30#issue-1609334323)).
+- **MY₿ONK console:**
+  Full-node, bitcoin-only hardware platform designed with anonymity, security, low price, performance, durability, low-energy, supply chain resilience and generic parts in mind. This machine runs the [MY₿ONK core](https://github.com/mybonk/mybonk-core) stack over NixOS. It is setup once and its configuration can be updated remotely, on the fly, using MY₿ONK orchestrator.
+- **MY₿ONK orchestrator:**
+  Machine is used to orchestrate your [fleet of] MY₿ONK console(s), it is essentially a Linux with a few additional software installed including the Nix package manager.
+- **MY₿ONK core**: Or simply 'MY₿ONK' is a tailor-made full-node [software stack](https://github.com/mybonk/mybonk-core) for MY₿ONK console (although it can run on pretty much any hardware if you are ready to hack some). MY₿ONK core is based on a nix-bitcoin overlay running on nixOS.
 - **MY₿ONK user**: The end user, you, the family man, the boucher, the baker, the hair dresser, the mechanics... Just want the thing to work, "plug and forget". Uses very simple user interface and never uses the command line. On MAINNET.
-- **MY₿ONK operator**: A "MY₿ONK user" that got really serious about it and decided to learn more, move to the next level. Has some "skin in the game" on MAINNET and is happy to experiment on SIGNET. Many operators take part in nodes Federations or create their own Federation.
+- **MY₿ONK operator**: A "MY₿ONK user" that got really serious about it and decided to move to the next level. Has some "skin in the game" on MAINNET and is happy to experiment on SIGNET. Many operators take part in nodes Federations or create their own Federation.
 - **MY₿ONK hacker**: A "MY₿ONK operator" so deep in the rabbit hole, bitcoin, privacy and sovereignty that he became a MY₿ONK hacker. That's an advanced user, student, Maker, researcher, security expert .etc... Just want to tear things apart. Love to use command line. On SIGNET.
 
+### Overview
+This small ecosystem example consists of only two elements that we are going to build together:
+- One MY₿ONK console
+- One MY₿ONK orchestrator
+
+
+
 ### Advice
 
 - **Nix vs. NixOS**: It is *very* important to understand the concept that nix and nixOS are different things: 
-  - [Nix](https://nixos.org/manual/nix/stable/) is a purely functional package management and build system. Nix is also the expression language designed specifically for the Nix, it is a pure, lazy, functional language. 
+  - [Nix](https://nixos.org/manual/nix/stable/) is a functional *package management and build system*. 
+  - Nix is also the *expression language* designed specifically for the Nix. It is a pure, lazy and functional language. 
     - Purity means that operations in the language don't have side-effects (for instance, there is no variable assignment).
     - Laziness means that arguments to functions are evaluated only when they are needed.
     - Functional means that functions are “normal” values that can be passed around and manipulated in interesting ways. The language is *not* a full-featured, general purpose language. Its main job is to describe packages, compositions of packages, and the variability within packages.
-
-  - NixOS is a Linux distribution based on Nix. In NixOS, the entire operating system — the kernel, applications, system packages, configuration files, and so on — is all built by the Nix package manager. [Here is an overview of the NixOS Linux distribution on NixOS Wiki](https://nixos.wiki/wiki/Overview_of_the_NixOS_Linux_distribution). Furthermore:
-
-    - See how Nix and NixOS work and relate: [https://nixos.org/guides/how-nix-works.html](https://nixos.org/guides/how-nix-works.html)
+  - And there is also NixOS, which is a *Linux distribution based on Nix*. 
+    - In NixOS, the entire operating system — the kernel, applications, system packages, configuration files, and so on — is all built by the Nix package manager. 
+    - [Here](https://nixos.wiki/wiki/Overview_of_the_NixOS_Linux_distribution)  is an overview of the NixOS Linux distribution.
+    - See how Nix and NixOS relate: [https://nixos.org/guides/how-nix-works.html](https://nixos.org/guides/how-nix-works.html)
     - A general introduction to the Nix and NixOS ecosystem: [https://nix.dev](https://nix.dev/)
     - Search functions within the nix ecosystem based on type, name, description, example, category .etc..: [https://noogle.dev](https://noogle.dev/)
 
 - **Read and explore**: The pros write and read documentation, they are not so much on YouTube. For 1 hour of reading you should spend about 4 hours experimenting with what you learned and so on.
 
 - **Be patient**: Learning takes time, getting a node up and running "by hand" takes time (system build, blocks download, various indexing). Also bear in mind that some services on the stack depend on others and won't operate properly before the service(s) they depend on are fully synchronized (e.g. Lightning Network vs. Bitcoin, Sparrow wallet vs Fulcrum).
 
-- **Don't trust, verify**: Anything you download on the internet is at risk of being malicious software. Know your sources. Always run the GPG (signature) or SHA-256 (hash) verification (typically next to the download link of an image or package there is a string of hexadecimal characters).
+- **Don't trust, verify**: Anything you download on the internet is at risk of being malicious software. Know your sources. Always run the GPG (signature) / SHA-256 (hash) verification (typically next to the download link of an image or package there is a string of hexadecimal characters).
 
 ### ssh auto login and tmux
 

baby-rabbit-holes.md

@@ -127,8 +127,9 @@ A *CLI* (command-line interface) is what deal with when you interact with the sh
         - .etc... .
 - Shell commands you must know *really well*:
   - ```pwd```, ```ls```, ```cd```, ```type```, ```mkdir```, ```mv```, ```rm```, ```ln```, ```which```, ```whereis```, ```cat```, ```head```, ```tail```, ```more```, ```tee``` …
+  - ```tree```: Outputs a depth-indented listing of files making it easy to visualize the organization of files and directories within a given path. With no arguments the tree lists the files in the current directory. When directory arguments are given, the tree lists all the files or directories found in the given directories each in turn. 
   - ```uname -a```, ```hostname```, ```whoami```, ```passwd```, ```chown```, ```chgrp```, ```chmod```, …
-  - ```ip a```
+  - ```ip a``` / ```hostname -I```: Tells you the IP address of your system.
   - ```su```/```sudo```, ```doas```: Used to assume the identity of another user on the system (they are both similar tools, ```doas``` has been ported from the OpenBSD project and could be assumed "safer" than ```sudo``` as it is less error-prone e.g. when setting up somewhat complicated patterns in ```/etc/sudoers```).
   - ```history``` 
     - ```echo "$HISTFILE"```
@@ -174,6 +175,7 @@ A *CLI* (command-line interface) is what deal with when you interact with the sh
     - ```find /dir/to/search -name "pattern" -print```
     - ```find /dir/to/search -name "file-to-search" -print```
     - ```find /dir/to/search -name "file-to-search" -print [-action]```
+
 ## Text processing
 
 - ```vi``` (cheat-sheet [HERE](https://www.thegeekdiary.com/basic-vi-commands-cheat-sheet/))
@@ -374,6 +376,13 @@ Tmux shortcuts
 - update
 ## http vs. https
 ## OS-layer firewall
+The following commands are replaces by configuration parameters in the NixOS configuration.
+- ```sudo netstat -lptu```: See what port is open and what process is listening.
+- ```sudo ufw allow 9999```: Open port 9999.
+- ```sudo ufw enable```: In case ```ufw``` is not running (check with sudo ```ufw``` status).
+
+
+
 ## partitions filesystem
 - ```findmnt```: 
 - /
@@ -479,7 +488,7 @@ Tmux shortcuts
   - Using flakes: 
     - [https://determinate.systems/posts/nix-run]()
 
-- ```nix --version```: Get running nix version (important as the MY₿ONK console might be running a different version from the one on MY₿ONK orchestrator).
+- ```nix --version```: Get running nix version.
 - ```nix-shell```: Start an interactive shell based on a Nix expression. This is distinct from ```nix shell```.
 - ```nix-build```: Build a Nix expression. This is distinct from ```nix build```.
 - ```nix-channel```
@@ -594,7 +603,10 @@ Tmux shortcuts
   ```
 
 ## Podcasts
-- nixbitcoin-dev with Stefan Livera: A security focused bitcoin node https://stephanlivera.com/episode/195/
+- [Citadel Dispatch #37, Sep 2021](https://fountain.fm/episode/4VMvLwI6VXY5uG4xJhfu): Building software from source code, reproducible builds, reducing trust, coin selection, coin control, coinjoin
+- [Citadel Dispatch #42, Nov 2021](https://fountain.fm/episode/sPtROvlhO5v6niLY8fvy): Security focused bitcoin nodes with @nixbitcoinorg, @n1ckler, and @seardsalmon
+- [nixbitcoin-dev with Stefan Livera](https://stephanlivera.com/episode/195/): A security focused bitcoin node.
+
 
 ## Connext projects / references
 - [Seed-signer](https://github.com/SeedSigner/seedsigner/blob/dev/README.md): Bitcoin only, open source, offline, airgapped Bitcoin signing device. Can also DIY.
@@ -625,6 +637,8 @@ Tmux shortcuts
 
 ## For developers
   - Great Nix language tour: https://nixcloud.io/tour
+  - [Poetry2nix](https://www.tweag.io/blog/2020-08-12-poetry2nix/): Developping Python with Poetry & Poetry2Nix: Reproducible, flexible, Python environments.
+  - [The difference between RPC and REST](https://nordicapis.com/whats-the-difference-between-rpc-and-rest/)
   - [Polar](https://lightningpolar.com/): One-click Bitcoin Lightning Networks for local app development & testing.
   - [Rust](https://www.rust-lang.org/): Multi-paradigm, general-purpose programming language that emphasizes performance, type safety, and concurrency. It enforces memory safety—ensuring that all references point to valid memory—without requiring the use of a garbage collector or reference counting present in other memory-safe languages.
   - [Cargo](https://doc.rust-lang.org/cargo/): Package manager for Rust.

docs/LicheePi4A-hw-tests-instructions.md

@@ -1,8 +1,10 @@
 # How to burn the latest factory image on Sipeed LicheePi4A 
 
-- Source (in progress and in Chinese, pass it through Google translate for now): https://wiki.sipeed.com/hardware/en/lichee/th1520/lpi4a/4_burn_image.html
+- Source: https://wiki.sipeed.com/hardware/en/lichee/th1520/lpi4a/4_burn_image.html
 
-- Board boot process is ```brom -> uboot spl -> uboot -> opensbi -> kernel```
+- I use a Mac to build and burn, these steps are very similar if you use another system.
+
+- Board boot process is ```brom -> U-Boot SPL -> U-Boot -> openSBI -> kernel```
 
 - We will use the tool ```fastboot``` which is part of the "android tools" to burn the image (the official documentation refers to some ```burn_tool.zip``` not too sure what it is specifically but ```fastboot``` does the job):
     - Install android tools:
@@ -44,44 +46,28 @@
         - light-lpi4a-ddr2G.dtb #history dtb
     - The **root** filesystem ```rootfs.ext4```, in this case a Debian system.
 
-**in the following commands make sure you change the paths to whatever latest version available**:
+**in the following commands make sure you change the paths to whatever latest version available (in this example it is 20230721)**:
 
     ``` 
-    $ wget --no-parent -r https://mirror.iscas.ac.cn/revyos/extra/images/lpi4a/20230511/
+    $ wget --no-parent -r https://mirror.iscas.ac.cn/revyos/extra/images/lpi4a/20230721/
     ```
 
 - Navigate to the location:
     ````
-    $ cd mirror.iscas.ac.cn/revyos/extra/images/lpi4a/20230511/
+    $ cd mirror.iscas.ac.cn/revyos/extra/images/lpi4a/20230721/
     ````
 
-- Check the hash of the downloaded files (**make sure you change the filename to whatever you downloaded**), the calculated hash must match the one in ```md5sum.txt```
-    ```
-    $ md5sum ./boot.ext4
-    e30a5ee03bf4cf0d87794908eca41767  boot.ext4
-
-    $ md5sum ./rootfs.ext4
-    776a960a4926f667adb2abfa2049872a  rootfs.ext4
-
-    $ cat ./md5sum.txt
-    e30a5ee03bf4cf0d87794908eca41767  boot.ext4
-    776a960a4926f667adb2abfa2049872a  rootfs.ext4
-    ```
-
 - Burn the board:
-    - Press and hold the "BOOT" button on the board while plugging the USB-C to power it. 
-    - Using a tool like ```lsusb``` (on MacOS you can use [this one](https://github.com/jlhonora/lsusb#readme)) the board show up something like this ```Bus 020 Device 005: ID 2345:7654 2345 USB download gadget```.
+    - Press and hold the "BOOT" button on the board while plugging the USB-C to power it from your laptop.
+    - If needed you can use a tool like ```lsusb``` to show what is going on the USB ports (on MacOS you can use [this one](https://github.com/jlhonora/lsusb#readme)), The board is represented by a line similar to this: 
+
+        ```Bus 020 Device 005: ID 2345:7654 2345 USB download gadget```.
 
-    - Check and create the partitions on the flash (**burning the system will be very slow if you don't**):
+    - Create the partition on the flash (**the burning process will be very slow if you don't do this**):
         ````
         $ sudo fastboot flash ram ./u-boot-with-spl.bin
         $ sudo fastboot reboot
-        $ sleep 10
         ````
-        NOTE1: SPL (Secondary Program Loader) is a platform specific stage of U-Boot and should be the first in the boot chain. It can also be built from source.
-
-        NOTE2: If ```u-boot-with-spl.bin``` is not present in the repository copy it from a previous version (parent directory).
-
         Which will return something like this:
         ````
         Sending 'ram' (935 KB)                             OKAY [  0.247s]