This change makes many improvements to the documentation aimed at higher clarity and robustness. Aside from rewording and reordering various parts, it makes sure the documentation is up to date with the reality and best (security and cleanness) practices.
The list of changes:
* Changes the title of "Installation" section to make it clear it's manual and from source
* Points at more convenient options right on top
* Adds "Build dependencies" subtitle
* Makes "Build" a subtitle as it belongs under "Manual installation from source" section
* Recommends using Debain native packaging, which is more secure than `rustup`
* Suggests installation and use of `cfg_me`
* Moves Docker-based installation higher to be better visible
* Informs that native, stable packages are not available yet.
* Adds information about the experimental repository. While it can't be recommended for production use yet, the hope is to attract more contributors and deliver stable, secure and user-friendly experience sooner.
* Makes it clear that the documented configuration is manual, so that users using automated systems won't attempt to configure it manually
* Makes "Bitcoind configuration", "Usage" and "Configuration files" into subtitles
* Mentions the no-prune requirement upfront
* Makes it clear that `txindex` is not necessary, but also allowed.
* Recommends using cookie file
* Instead of telling people to wait for IBD before running `electrs` it accurately describes the behavior.
* Moves the section about `electrs` configuration before usage to be more visible. It's also the ordering of steps a user should take.
* Changes title of "configuration files and environment variables" to "Electrs configuration" to be consistent with "Bitcoind configuration"
* Recommends configuration files - they are clearer and saved across executions
* Clarifies the behavior of overriding files/arguments
* Documents `--conf` and `--conf-dir` arguments
* Explains the difference between `cookie` and `cookie_file`
* Renames "Usage" to "Electrs usage" to be more obvious
* Points out extra configuration suggestions, so they won't get lost after "Electrum client" section
* Notifies users of Debian repository to skip messing with Electrum configuration.
* Makes it clear that the script is provided in the repository (was not immediately obvious to me, LOL; providing `.desktop` file would be nicer, though)
* Added missing title "Extra configuration suggestions"
* Suggests to use more clear path in Tor configuration
* Hints at `tor-hs-config-patch`
* Warns users using the experimental Debian repository to not mess with systemd files
This commits contains fixes to merklization function arguments
and return types. New hash type system from bitcoin crate does
not cover all cases for merkle values; and the same function
may be applied to different hash types. Thus, I have used generic
types to abstract the logic.
`Txid` merklization operates with TxMerkleNode type;
`BlockHash` merklization does not introduce a new type: the same
design decision was made in the original work on new bitcoin
crate type system since it is used in a single case, and there is
no point in introducing a special designated hash type.
Script hashes (used in RPC queries) are left of Sha256dHash type
since there is no corresponding type defined in bitcoin crate;
this type is specific to Electrum X protocol. Corresponding
new type can be implemented in the project later with `hash_newtype!`
macro in the same way it was done in bitcoin crate.
This changes `split_off`, which does one allocation and copies `n` items
in the best case, `2 * n` items in the worst case to `retain`, which does
zero allocations and copies zero items in the best case and `3 * (n - 1)`
items in worst case (because swap is 3 copies and `retain` has to swap
due to possibility of panic).
I believe this should be net-benefit due to usually small `n`.
This change implements non-blocking cleanup of threads. It achieves it
by cleaning up periodically based on thread ID, that gets sent from dead
thread over a channel. Aside from internal locks in the channel, there
are no other locks. The cleanup also happens only after a new connection
is accepted, but hopefully won't be an issue, unless there are many
connections that die and then nothing connects for a long time. A final
cleanup happens when the thread is finishing.
After a recent switch to configure_me in ec049b9a, the 'mainnet'
arg value became 'bitcoin'. 2c50791d then updated db dir location
but the doc for the --network arg remained stale.
An alternative is to accept both 'mainnet' and 'bitcoin' but
it would be confusing IMHO.
This change allows the user to specify a custom cookie file, which is then
used instead of `~/.bitcoin/.cookie`. This resolves situations when the
user wants to have the cookie file in non-standard path.
Aside from that, the code now pre-computes the default path, improving
the performance by avoiding allocation (and copying). Unfortunately, due
to limitations of Rust, the code doesn't print out cookie configuration
anymore. This however might be safer, since the cookie isn't printed,
and thus doesn't end up in some readable logs by accident.
Closes#176Closes#189
