moved markdown files from root directory

(since everyone has a browser, text is obsolete)
modified:   docs/libraries.md
deleted:    docs/libraries/pandoc_templates/style.css
modified:   docs/merkle_patricia_dag.md
modified:   docs/mkdocs.sh
renamed:    LICENSE.md -> docs/rootDocs/LICENSE.md
renamed:    NOTICE.md -> docs/rootDocs/NOTICE.md
renamed:    README.md -> docs/rootDocs/README.md
renamed:    RELEASE_NOTES.md -> docs/rootDocs/RELEASE_NOTES.md
new file:   docs/scalable_reputation_management.md
modified:   docs/scale_clients_trust.md
modified:   docs/set_up_build_environments.md
modified:   docs/writing_and_editing_documentation.md
deleted:    pandoc_templates/style.css

LICENSE.html

@@ -14,7 +14,47 @@
     ul.task-list{list-style: none;}
     .display.math{display: block; text-align: center; margin: 0.5rem auto;}
   </style>
-  <link rel="stylesheet" href="docs/pandoc_templates/style.css" />
+  <style type="text/css">body {
+max-width: 30em;
+margin-left: 1em;
+}
+table {
+border-collapse: collapse;
+}
+td, th {
+border: 1px solid #999;
+padding: 0.5rem;
+text-align: left;
+}
+code{white-space: pre-wrap;
+}
+span.smallcaps{font-variant: small-caps;
+}
+span.underline{text-decoration: underline;
+}
+div.column{display: inline-block; vertical-align: top; width: 50%;
+}
+div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;
+}
+ul.task-list{list-style: none;
+}
+.display.math{display: block; text-align: center; margin: 0.5rem auto;
+}
+h1.title{text-align: center; font-size: xxx-large;
+}
+div.center {text-align:center;
+}
+div.centre {text-align:center;
+}
+table {
+border-collapse: collapse;
+}
+td, th {
+border: 1px solid #999;
+padding: 0.5rem;
+text-align: left;
+}
+</style>
   <!--[if lt IE 9]>
     <script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
   <![endif]-->

NOTICE.html

@@ -14,7 +14,47 @@
     ul.task-list{list-style: none;}
     .display.math{display: block; text-align: center; margin: 0.5rem auto;}
   </style>
-  <link rel="stylesheet" href="docs/pandoc_templates/style.css" />
+  <style type="text/css">body {
+max-width: 30em;
+margin-left: 1em;
+}
+table {
+border-collapse: collapse;
+}
+td, th {
+border: 1px solid #999;
+padding: 0.5rem;
+text-align: left;
+}
+code{white-space: pre-wrap;
+}
+span.smallcaps{font-variant: small-caps;
+}
+span.underline{text-decoration: underline;
+}
+div.column{display: inline-block; vertical-align: top; width: 50%;
+}
+div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;
+}
+ul.task-list{list-style: none;
+}
+.display.math{display: block; text-align: center; margin: 0.5rem auto;
+}
+h1.title{text-align: center; font-size: xxx-large;
+}
+div.center {text-align:center;
+}
+div.centre {text-align:center;
+}
+table {
+border-collapse: collapse;
+}
+td, th {
+border: 1px solid #999;
+padding: 0.5rem;
+text-align: left;
+}
+</style>
   <!--[if lt IE 9]>
     <script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
   <![endif]-->

README.html

@@ -77,7 +77,47 @@
     code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
     .display.math{display: block; text-align: center; margin: 0.5rem auto;}
   </style>
-  <link rel="stylesheet" href="docs/pandoc_templates/style.css" />
+  <style type="text/css">body {
+max-width: 30em;
+margin-left: 1em;
+}
+table {
+border-collapse: collapse;
+}
+td, th {
+border: 1px solid #999;
+padding: 0.5rem;
+text-align: left;
+}
+code{white-space: pre-wrap;
+}
+span.smallcaps{font-variant: small-caps;
+}
+span.underline{text-decoration: underline;
+}
+div.column{display: inline-block; vertical-align: top; width: 50%;
+}
+div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;
+}
+ul.task-list{list-style: none;
+}
+.display.math{display: block; text-align: center; margin: 0.5rem auto;
+}
+h1.title{text-align: center; font-size: xxx-large;
+}
+div.center {text-align:center;
+}
+div.centre {text-align:center;
+}
+table {
+border-collapse: collapse;
+}
+td, th {
+border: 1px solid #999;
+padding: 0.5rem;
+text-align: left;
+}
+</style>
   <!--[if lt IE 9]>
     <script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
   <![endif]-->

RELEASE_NOTES.html

@@ -14,7 +14,47 @@
     ul.task-list{list-style: none;}
     .display.math{display: block; text-align: center; margin: 0.5rem auto;}
   </style>
-  <link rel="stylesheet" href="docs/pandoc_templates/style.css" />
+  <style type="text/css">body {
+max-width: 30em;
+margin-left: 1em;
+}
+table {
+border-collapse: collapse;
+}
+td, th {
+border: 1px solid #999;
+padding: 0.5rem;
+text-align: left;
+}
+code{white-space: pre-wrap;
+}
+span.smallcaps{font-variant: small-caps;
+}
+span.underline{text-decoration: underline;
+}
+div.column{display: inline-block; vertical-align: top; width: 50%;
+}
+div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;
+}
+ul.task-list{list-style: none;
+}
+.display.math{display: block; text-align: center; margin: 0.5rem auto;
+}
+h1.title{text-align: center; font-size: xxx-large;
+}
+div.center {text-align:center;
+}
+div.centre {text-align:center;
+}
+table {
+border-collapse: collapse;
+}
+td, th {
+border: 1px solid #999;
+padding: 0.5rem;
+text-align: left;
+}
+</style>
   <!--[if lt IE 9]>
     <script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
   <![endif]-->
@@ -25,6 +65,8 @@
 </header>
 <p>To build and run <a href="./README.html">README</a></p>
 <p><a href="docs/index.htm">pre alpha documentation (mostly a wish list)</a></p>
-<p>This software is pre alpha and should not yet be released. It does not work well enough to even show what it would do if it was working</p>
+<p>This software is pre alpha and should not yet be released. It does
+not work well enough to even show what it would do if it was
+working</p>
 </body>
 </html>

docs/libraries.md

@@ -191,6 +191,41 @@ executed than in the past.
 ./configure && make && make install
 ```
 
+## The standard Linux installer
+
+`*.deb`
+
+`debhelper` and `dh-make` provide a somewhat user friendly tool for
+making deb files.
+
+`*.deb` files are commonly built from `*.dsc` files, which are also
+available in the repository.
+
+Which gives you the option, under debian, of building your entire
+toolchain, something not possible in windows.  It is half way to the
+goal of building your own linux from scratch, without the elaborate
+process where you type in a hundred commands, and if you
+mistype a single one of them, everything goes to hell and you do
+not know where in the process you went off the rails.  But if you
+want people to build from source, you probably want them to
+develop, in which case git is better than `*.dsc` files
+
+The standard deb file builder integrated into debian is `git-buildpackage`.
+
+But other systems like a `*.rpm` package, which is built by `git-buildpackage-rpm`
+
+But desktop integration is kind of random.
+
+Under Mate and KDE Plasma, run-on-login is done by placing your
+`*.desktop` file in  `~/.config/autostart`
+
+To be in the menus for all users, should be in
+`/usr/share/applications` with its `Categories=` entry set to whatever Wasabi sets its `Categories=` entry to.  But what about the
+menu for just one user?
+
+The documentation says `~/.local/share/applications`.  Which I
+do not entirely trust.
+
 ## The standard windows installer
 
 Wix creating an `*.msi` file.
@@ -211,24 +246,16 @@ There is an automatic wix setup:  Visual Studio-> Tools-> Extensions&updates ->s
 
 Which is the Microsoft utility for building wix files.  It creates a quite adequate wix setup by gui, in the spirit of the skeleton windows gui app.
 
-## [NSIS](https://nsis.sourceforge.io/Download) Nullsoft Scriptable Install System.
+[NSIS]:https://nsis.sourceforge.io/Download
+{target="blank"}
 
-People who know what they are doing seem to use this install system, and they
+## [NSIS] Nullsoft Scriptable Install System
- write nice installs with it.
 
-To build setup program:
+People who know what they are doing seem to use this open
+source install system, and they  write nice installs with it.
 
-1. Build both x64 and Win32 Release configs
+But NSIS has not had any releases since 2019, and it looks that
-1. When you construct wallet.nsi in nullsoft, add it to your project.
+updating has been minimal for several years before that.
-1. When building a deliverable, Right click on the WalletSetup.nsi file in Visual Studio project and select properties.
-1. Set Excluded from Build to No
-1. OK Properties
-1. Right click .nsi file again and choose Compile.
-1. Set the .nsi file properties back to Excluded from Build.
-
-This manual building of the setup is due to the fact that we need both x64
-and Win32 exes for the setup program and Visual Studio doesn’t  provide a
-way to do this easily.
 
 # Package managers
 
@@ -276,43 +303,57 @@ for modular multiplicative inverse, which it, of course, supports,
 `mpz_gcdext`, greatest common divisor extended, but which is deeply
 hidden in the [documentation](http://www.mpir.org/mpir-3.0.0.pdf).
 
-# [wxWidgets](./libraries/building_and_using_libraries.html#instructions-for-wxwidgets)
+# [wxWidgets](./libraries/building_and_using_libraries.html#instructions-for-wxwidgets){target="_blank"}
 
 # Secure compilation
 
 I am currently using Visual Studio, the most powerful, convenient,
-and useful code development system around.  But increasingly owned
+and useful code development system around.  But increasingly owned by
-by enemies of increasing wickedness and diminishing competence.
+enemies of increasing wickedness and diminishing competence.  Also,
-Also, completely different, and not altogether compatible with, what
+completely different, and not altogether compatible with, what is needed
-is needed to build code on linux.
+to build code on linux.
 
-I attempted to build wxWidgets using MingGW which is open source,
+I attempted to build wxWidgets using MingGW which is open source, and failed.
-and failed.
 
-Git is open source, and operated by good people, but its hash function
+Git is open source, and operated by good people, but its hash function is
-is insecure, and its signing system relies on Gpg, which is designed
+insecure, and its signing system relies on Gpg, which is designed to be
-to be part of the Web of Trust, which no longer exists and never was
+part of the Web of Trust, which no longer exists and never was entirely
-entirely working, and never designed for the use to which Git uses it.
+working, and never designed for the use to which Git uses it.
 
-After we get a signing and security system, which will not be for a
+After we get a signing and security system, which will not be for a while,
-while, we should create a fork of Git that actually is secure.
+we should create a fork of Git that actually is secure.
 
-[Build environment for Git for Windows](https://github.com/git-for-windows/build-extra){target="_blank"} is a complete package
+[Build environment for Git for Windows]:https://github.com/git-for-windows/build-extra{target="_blank"}
-that can compile Git on Windows *and* compile itself.
 
-I suspect it can *only* compile Git for Windows and itself, but it does
+[Build environment for Git for Windows] is a package that builds a package
-so by building a pile of more generally useful tools.  If I can get my
+manager that installs packages that can build Git on windows.  But it is a
-software building in that toolset, I have complete open source software
+package manager, not a pile of compilers and build tools, a package
-on windows to build my software, complete source code, including the
+manager that merely installs precompiled files from who knows where,
-source code for the repository of the source code.
+compiled by who knows who?
 
-This recursive capability would shield my software from a broad range
+What we actually need is a full development environment that can build a
-of enemy attacks, particularly if we eventually make Git secure.
+full development environment, and you can have multiple versions of the
+tools on the same machine, and can select one or more all of the newly
+modified tools for your build environment, or build a full install package
+from source, including compilers, make utilities, ide, and git.  When a
+source file for the ide or one of its components changes, the default full
+build action being to build the new component, and switch to it, but the
+release components are not overwritten, and you can switch back until you
+explicitly overwrite the release version by running a newly built install
+package or manually copy a newly built component over the release
+component.
 
-Building Git is a linux compatibility stress test.  If you have
+There should be a unit test, of course, and should unit test fail, the default
-software that compiles in an environment designed to pass a linux
+action should be to switch back to the release version, and open up the
-compatibility stress test, then you have maximum compatibility
+source code hinted by the unit test failure.
-between windows and linux.
+
+It should be a development environment that provides special case
+handling for development of the development environment.
+
+All this is very far indeed from what [Build environment for Git for Windows]
+provides, and creating it would be an enormous project, but the
+only way to prevent toolchain attacks is to make toolchain development
+readily available to everyone.
 
 # Networking
 
@@ -561,12 +602,24 @@ delay between a transaction affecting a the payer factor state, and the
 transaction affecting the payee factor state.  A transaction has no immediate
 affect.  The payer mutable substate changes in a way reflecting the
 transaction block at the next block boundary.  And that change then has
-effect on product mutable state at a subsequent product state block boundary, changing the stake possessed by the substate.
+effect on product mutable state at a subsequent product state block
+boundary, changing the stake possessed by the substate.
 
 Which then has effect on the payee mutable  substate at its next
 block boundary when the payee substate links back to the previous
 product state.
 
+# wxSqlite3
+
+wxSqlite integrates a third free open source encryption library that appears
+to use libSodium encryption algorithms into Sqlite to provide encrypted
+databases, and integrates sqlite3 databases into one of the wxWidgets
+tools, but not, however, the one that I actually want, wGrid.
+
+More layers lead to more attack surface, so it would be better to use
+wxSqlite as a model for the integration, rather than using it directly, and
+then use a fork of the third party library, rather than using it directly.
+
 # Safe maths
 
 [Safeint]:https://github.com/dcleblanc/SafeInt

docs/libraries/pandoc_templates/style.css

@@ -1 +0,0 @@
-../pandoc_templates/style.css

docs/merkle_patricia_dag.md

@@ -257,8 +257,8 @@ information from the peer that has the node with more children.
 <svg
 	xmlns="http://www.w3.org/2000/svg"
 	xmlns:xlink="http://www.w3.org/1999/xlink"
-	width="29em" height="18em"
+	width="30em" height="19.6em"
-	viewBox="0 170 220 140"
+	viewBox="0 170 214 140"
 	style="background-color:ivory"
 	stroke-width="1"
 	stroke-linecap="round" >
@@ -400,22 +400,30 @@ particular part of the blockchain is valid.  This has three
 advantages over the chain structure.
 
 1. A huge problem with proof of stake is "nothing at stake".
-  There is nothing stopping the peers from pulling a whole
+   There is nothing stopping the peers from pulling a whole
-  new history out of their pocket.\
+   new history out of their pocket.\
-  With this data structure, there is something stopping them. They
+   With this data structure, there is something stopping them. They
    cannot pull a brand new history out of their pocket, because the
    clients have a collection of very old roots of very large balanced
    binary merkle trees of blocks.  They keep the hash paths to all their
    old transactions around, and if the peers invent a brand new history,
    the clients find that the context of all their old transactions has
    changed.
-1. It protects clients against malicious peers, since any claim the peer
-    makes about the total state of the blockchain can be proven with
-	$\bigcirc(\log_2n)$ hashes.
 1. If a block gets lost or corrupted that peer can identify that one
-    specific block that is a problem.  At present peers have to download,
+   specific block that is a problem.  At present peers have to download,
    or at least re-index, the entire blockchain far too often, and a full
-    re-index takes days or weeks.
+   re-index takes days or weeks.
+1. It protects clients against malicious peers, since any claim the peer
+   makes about the total state of the blockchain can be proven with
+   $\bigcirc(\log_2n)$ hashes.
+1. We don't want the transaction metadata to be handled
+   outside the secure wallet system, so we need client wallets
+   interacting directly with other client wallets, so we need any
+   client to be able to verify that the other client is on a
+   consensus about the state of the blockchain that is a
+   successor, predecessor, or the same as its consensus, that
+   each client can itself verify that the consensus claimed by its
+   peer is generally accepted.
 
 This is not a Merkle-patricia tree.  This is a generalization of a Merkle
 patricia dag to support immutability.
@@ -427,13 +435,13 @@ one of which corresponds to appending a $0$ bit to the bitstring that
 identifies the vertex and the path to the vertex, and one of which
 corresponds to adding a $1$ bit to the bitstring.
 
-In an immutable append only Merkle patricia dag vertices identified by bit
+In an immutable append only Merkle patricia dag vertices identified
-strings ending in a $0$ bit have a third hash link, that links to a vertex whose
+by bit strings ending in a $0$ bit have a third hash link, that links to a
-bit string is truncated back by zeroing the prior the $1$ bit and removing any
+vertex whose bit string is truncated back by removing the trailing $0$
-$0$ bits following it. Thus, whereas in blockchain (Merkle chain) you need $n$
+bits back to rightmost $1$ bit and zeroing that $1$ bit.  Thus, whereas in
-hashes to reach and prove data $n$ blocks back, in a immutable append
+blockchain (Merkle chain) you need $n$ hashes to reach and prove
-only Merkle patricia dag, you only need $\bigcirc(\log_2n)$ hashes to reach a
+a vertext $n$ blocks back, in a immutable append only Merkle patricia
-vertex of the blockdag $n$ blocks back.
+dag, you only need $\bigcirc(\log_2n)$ hashes to reach a vertex $n$ blocks back.
 
 The vertex $0010$ has an extra link back to the vertex $000$, the
 vertices $0100$ and $010$ have extra links back to the vertex $00$, the
@@ -461,7 +469,8 @@ This reduces the amount of trust that clients have to place in peers.
 When the blockchain gets very large there will be rather few peers
 and a great many clients, thus there will be a risk that the peers will
 plot together to bugger the clients.  This structure enables a client
-to verify that any part of the blockchain is what his peer say it is, and thus avoids the risk that peer may tell different clients different
+to verify that any part of the blockchain is what his peer say it is,
+and thus avoids the risk that peer may tell different clients different
 accounts of the consensus.  Two clients can quickly verify that they
 are on the same total order and total set of transactions, and that
 any item that matters to them is part of this same total order and

docs/mkdocs.sh

@@ -64,16 +64,17 @@ do
  #  echo "       $base.html up to date"
  fi
 done
-cd ../..
+cd ../rootDocs
-templates=docs/pandoc_templates
+templates="../pandoc_templates"
 for f in *.md
 do
  len=${#f}
  base=${f:0:($len-3)}
- if [ $f -nt $base.html ];
+ if [ $f -nt ../../$base.html ];
  then
-   pandoc $osoptions --wrap=preserve --from markdown --to html --metadata=lang:en --standalone --css=$templates/style.css -o $base.html $base.md
+   pandoc $osoptions --wrap=preserve --from markdown --to html --metadata=lang:en --css=$templates/style.css --self-contained   -o ../../$base.html $base.md
-   echo "$base.html from $f"
+   #--include-in-header=style.css
+   echo "../..$base.html from $f"
  #else
  #  echo "       $base.html up to date"
  fi

docs/rootDocs/RELEASE_NOTES.md

@@ -5,4 +5,6 @@ To build and run [README](./README.html)
 
 [pre alpha documentation (mostly a wish list)](docs/index.htm)
 
-This software is pre alpha and should not yet be released. It does not work well enough to even show what it would do if it was working
+This software is pre alpha and should not yet be released. It does
+not work well enough to even show what it would do if it was
+working

docs/scalable_reputation_management.md

@@ -0,0 +1,44 @@
+---
+lang: en
+title: Scalable Reputation Management
+---
+
+# Scalable Reputation Management
+
+The hardest part of the cypherpunk plan is scalable reputation management.
+
+We plan to have a global store of named rhocoins, thereby squaring Zooko’s
+triangle. Associated with each name will be a nameserver, which tells you how
+to contact that individual, his websites, etc, which have public keys signed by
+the rhocoin private key. You start out assuming that he and all his associated
+data are on that nameserver, and it gives you a permanent or temporary redirect,
+signed by a public key authorized by his rhocoin private key to give such
+redirects, which key contains a limit for that key and all the redirects.
+
+He has a collection of positive reviews, that chain to spent coins in the blockchain, via his offer or payment request, and also to a recent global hash. But what about negative reviews?.
+
+For that, we need reputation managers, two or three, that hold a replicated collection of negative reviews.
+
+The payment request chains to a name being monitored by the reputation monitors, but the person making the payment is generally anonymous. So he could manufacture positive reviews in unlimited number by sending payments to himself. So the reputation monitoring entities need to monitor spam, much as google has a problem with link farms. If the same entity gives reviews to entities that do not spam, or is unreasonably prone to giving frivolous negative reviews. One way around this is to give reviewers reputation points on the basis of the money they have paid to entities with good reputation. Paying one ro to a hundred entities gives you more reputation than paying money one hundred ro to one hundred entities..
+
+We really want to subdivide reviews into good, grey, and possible spam. which, suggests a logistic curve over the sum of a bunch of logistic curves.
+
+ln {B+∑ ln(P~i~+1)}
+
+This means it is not enough to connect the review to the rocoins. Needs to be connected to a cheap but permanent identity. So, the transaction chains to the payers through a Merkle-patricia tree, which links to each payment request, which links to the durable named identity of the wallet receiving it, and the durable but possibly nameless wallet paying it. This part of the chain is not on global canonical blockchain, but in the private blockchains of the receiving and paying wallet, which can be visible, if the payer or the payee make parts of it public. Any conversations about the payment before the transaction are directly rendered immutable by the global blockchain, so we know the that Ann, the party that controls the wallet posting a review made the payment, but, without Bob’s cooperation, cannot know that parts of the conversation that Ann claims were seen by Bob after the transaction actually were seen by Bob. We can, however, if either Ann or Bob makes the payment request public, know that Bob requested payment for such and such, and Ann paid. If someone is telling fibs about what happened after the transaction, we can know from the global shared blockchain that Ann is not fibbing about what Ann paid and Bob promised to deliver.
+
+The transaction is on the global shared canonical blockchain, and links through a Merkle dac, which is not on the global shared canonical blockchain, to immutable information about who made the payment, who received the payment, and why. Subsequent conversations about the transaction are mutable, unless, of course, they result in another payment. If there is a continuing relationship, and continuing transactions between Ann and Bob, then the entire conversation up to the most recent payment is immutable.
+
+The problem is sybil attack. A transaction creates reputation for buyer and seller, creating an incentive to create a network of dummy transaction, to generate positive reputation for scammers, and to attack the reputation of good actors.
+
+But, we assume that there are a small number of big centralized reputation brokers, with big machines and custom algorithms that they continually tweek.
+
+One solution is to have sixty four different reputation colors, each represented by eight byte number. Known entities, that we have external information indicating that supply real goods and services, get a mix of colors reflecting the source and content of that external information. Unknown actors randomly and automatically get a color from a different palette. A transaction causes the parties get more of the same color as the entity that they transact with.
+
+Known link farms get colors from the bad palette.
+
+So, the main network of legitimate actors will tend to get all the same color mix, because every legitimate customer buys from lots of legitimate sellers, and every legitimate seller sells to lots of legitimate buyers.
+
+Networks of fakes will get their own distinct color, because the reputation circulates inside that network. The big giveaway will not so much be bad colors versus good colors, but the failure of colors to homogenize. All the good actors will tend to develop rather similar colors, each link farm will have its own distinct color. Every transaction inside your own little group will tend to result in more of your group color, and less of the general mix.
+
+With forty colors, we have a trillion different composite colors, so we randomly assign each seller entity that collects reviews an initial pool of distinct color, and they get additional color from feedback on each transaction of the entity transacted with. If feedback from a wallet never seen before, it has no color, so they get more of their own color, and it gets a pool of the color of the entity they gave feedback to proportional to the amount paid. Every completely unknown seller entity gets one hundred units of various randomly chosen colors. External reputational indications result in additions of color reflecting that external information.which will get mixed in with throughout the network of real actors and real feedback.

docs/scale_clients_trust.md

@@ -4,18 +4,58 @@ title: Scaling, trust and clients
 
 # Scaling
 
-The Bitcoin blockchain has become inconveniently large, and evaluating it from beginning to end to
+The Bitcoin blockchain has become inconveniently large, and evaluating it
-determine the current mutable state is apt to fail half way through.  Your computer takes a very long
+from beginning to end to determine the current mutable state is apt to fail
-time and is apt to fail to make it all the way.
+half way through.  Your computer takes a very long time and is apt to fail
+to make it all the way.
 
-And, to take over the world, needs to become one hundred times larger.  Instead of five hundred
+And, to take over the world, needs to become one hundred times larger.
-gigabytes of blockchain, fifty terabytes.  And if you have eight eight terabyte drives attached to your
+Instead of five hundred gigabytes of blockchain, fifty terabytes.  And if you
-computer, it is big expensive computer, and drives keep failing from time to time.  And they are not
+have eight eight terabyte drives attached to your computer, it is big
-the only thing that fails from time to time.
+expensive computer, and drives keep failing from time to time.  And they
+are not the only thing that fails from time to time.
 
-It is doable, but the only people that would be full peers on the blockchain would be a bunch of
+It is doable, but the only people that would be full peers on the blockchain
-corporations and quite wealthy individuals.  You would have a small data centre, rather than a computer
+would be a bunch of corporations and quite wealthy individuals.  You
-Which is likely to have bad consequences.
+would have a small data centre, rather than a computer Which is likely to
+have bad consequences.
+
+## Kademlia
+
+[Kademlia]:https://codethechange.stanford.edu/guides/guide_kademlia.html
+"Distributed Hash Tables with Kademlia"
+{target="_blank"}
+
+[Kademlia] is a patricia tree of hashes, except that instead of direct links to
+data, we have groups of peers that are known to be up, running, and
+handling that vertex of the patricia tree.
+
+Trouble is, if we need to look up an enormous number of links, we don't
+want to walk through that tree an enormous number of times, since each
+step in the walk is relatively slow.
+
+So, an algorithm to distribute the blockchain over a very large number of
+peers is a little bit tricky.  We cannot have the tree split into too many tiny
+fragments.  If we are looking for tiny bit of data, a transaction, each input
+for a transaction, and each output for a transaction, we want to get a whole
+pile of such little bits in one go over a single connection.
+
+And, if we are using massively replicated transaction checking, rather than
+recursive zk-snarks, we need to make sure that the community evaluating
+each transaction is big enough and random enough, and need reputation
+management and the capacity to kick out peers that invalidly evaluate
+state.  So we want a big pile of peers on each branch of the transaction tree.
+
+And each group of peers is providing services to and receiving services
+from many other groups of peers.  We have to incentivize this in a way that
+ensures that each peer is managing a decently large branch of the tree, and
+each branch of the tree is managed by a decently large number of peers.
+Which is a hard problem, which the bittorrent community has been failing
+to solve for a long time, though in the case of bittorrent, the primary way
+this problem manifests is that peers have a big pile of old data sitting
+around and are disinclined to make it available.  And if they did make it
+available, the same peer would appear in far too many different and
+unrelated branches of the tree, creating excessive [Kademlia] lookup costs.
 
 ## Merkle Patricia tree of signatures
 
@@ -36,7 +76,7 @@ Suppose this is hash the state sequence of Bob.  Then everyone sharing this prei
 We all know the company with good reputation, that gets into financial difficulties, sells its good name to new management, which cashes in the long accrued reputation for a quick buck, then the phones
 stop being answered, the website gradually ceases to work, and large amounts of spam mail arrives.
 
-## sharding, many blockchains.
+## sharding, many blockchains
 
 Coins in a shard are shares in [sovereign cipher corporations] whose
 primary asset is a coin on the primary blockchain that vests power over
@@ -68,6 +108,7 @@ wallets.
 
 [interests that do not necessarily coincide]:https://vitalik.ca/general/2021/05/23/scaling.html
 "Vitalik Buterin talks blockchain scaling"
+{target="_blank"}
 
 And a few hundred seems to be the minimum size required to stop peers
 with a lot of clients from doing nefarious things. At scale, we are going to

docs/set_up_build_environments.md

@@ -50,7 +50,7 @@ To install guest additions on Debian:
 ```bash
 su -l root
 apt-get -qy update && apt-get -qy install build-essential module-assistant git dialog rsync
-apt-get -qy upgrade
+apt-get -qy full-upgrade
 m-a -qi prepare
 mount -t iso9660 /dev/sr0 /media/cdrom
 cd /media/cdrom0 && sh ./VBoxLinuxAdditions.run
@@ -3102,8 +3102,10 @@ wandering around somewhat lost figuring out how desktops should work.
 Under Mate and KDE Plasma, bitcoin implements run-on-login by generating a
 `bitcoin.desktop` file and writing it into `~/.config/autostart`
 
-It does not, however, place the `bitcoin.desktop` file in any of the expected
+It does not, however, place the `bitcoin.desktop` file in any of the
-other places.
+expected other places.  Should be in `/usr/share/applications`
+with its `Categories=` entry set to whatever Wasabi sets its
+`Categories=` entry to.
 
 Under Mate and KDE Plasma, bitcoin stores its configuration data in
 `~/.config/Bitcoin/Bitcoin-Qt.conf`, rather than in `~/.bitcoin`
@@ -3123,11 +3125,11 @@ integrate itself into the linux desktop, used to ensure your program appears
 in the main application menu, the linux equivalent of the windows startup
 menu.
 
-Getting your desktop file into the startup menu is slightly different in KDE
+Getting your desktop file into the menus is slightly different in KDE
 to the way it is in Gnome, but there are substantial similarities.
-FreeDesktop tries to maintain and promote uniformity.  Gnome rather
+FreeDesktop tries to maintain and promote uniformity. Gnome3
-casually changed the mechanism in a minor release, breaking all previous
+rather casually changed the mechanism in a minor release, breaking
-desktop applications.
+all previous desktop applications.
 
 ## Flatpack
 

docs/writing_and_editing_documentation.md

@@ -468,9 +468,10 @@ repetitious items in diagrams beautifully, because you can define an item
 by reference to another item, thus very large hierarchical structure can be
 defined by very small source code.
 
+<div style="width: 100%; height: 22em; overflow: auto;">
 <svg
 	xmlns="http://www.w3.org/2000/svg"
-	width="29em"  height="12em"
+	width="58em"  height="24em"
 	viewBox="40 60 60 50"
 	style="background-color:ivory">
 	<g  id="startblocks"
@@ -514,6 +515,7 @@ defined by very small source code.
 		</text>
 	</g>
 </svg>
+</div>
 
 <script>
 	document.getElementById("startblocks").addEventListener

pandoc_templates/style.css

@@ -1 +0,0 @@
-../docs/pandoc_templates/style.css