Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Restore documentation that had been moved to zcash.readthedocs.io #5953

Merged
merged 7 commits into from
Sep 1, 2022
Merged

Restore documentation that had been moved to zcash.readthedocs.io #5953

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
ef07ba4
Revert "redirect and update source documentation"
nuttycom May 12, 2022
e9234ed
Fix documentation line wrapping
nuttycom May 12, 2022
ad72a60
Backport changes from zcash.readthedocs.io
nuttycom May 12, 2022
07d52d0
Backport tor.md changes from readthedocs
sellout Aug 25, 2022
fbdfbae
Move restored documentation into the zcashd book
nuttycom May 12, 2022
a6c05f1
Apply suggestions from code review
daira Aug 30, 2022
2621efd
Update doc/book/src/user/security-warnings.md
daira Aug 30, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
37 changes: 23 additions & 14 deletions doc/files.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,23 @@
* zcash.conf: contains configuration settings for zcashd
* zcashd.pid: stores the process id of zcashd while running
* blocks/blk000??.dat: block data (custom, 128 MiB per file)
* blocks/rev000??.dat; block undo data (custom)
* blocks/index/*; block index (LevelDB)
* chainstate/*; block chain state database (LevelDB)
* database/*: BDB database environment
* db.log: wallet database log file
* debug.log: contains debug information and general logging generated by zcashd
* fee_estimates.dat: stores statistics used to estimate minimum transaction fees and priorities required for confirmation
* peers.dat: peer IP address database (custom format)
* wallet.dat: personal wallet (BDB) with keys and transactions
* .cookie: session RPC authentication cookie (written at start when cookie authentication is used, deleted on shutdown): since 0.12.0
* onion_private_key: cached Tor hidden service private key for `-listenonion`: since 0.12.0
Data Directory Files
====================

Files within the zcashd data directory (``~/.zcash/``) on Linux unless otherwise specified) include:
daira marked this conversation as resolved.
Show resolved Hide resolved

| File | Description
|-----------------------|--------------
|``zcash.conf`` | contains configuration settings for zcashd
|``zcashd.pid`` | stores the process id of zcashd while running
|``blocks/blk000*.dat`` | block data (custom, 128 MiB per file)
|``blocks/rev000*.dat`` | block undo data (custom)
|``blocks/index/*`` | block index (LevelDB)
|``chainstate/*`` | block chain state database (LevelDB)
|``database/*`` | BDB database environment
|``db.log`` | wallet database log file
|``debug.log`` | contains debug information and general logging generated by zcashd
|``fee_estimates.dat`` | stores statistics used to estimate minimum transaction fees and priorities required for confirmation
|``peers.dat`` | peer IP address database (custom format)
|``wallet.dat`` | personal wallet (BDB) with keys and transactions (keep private, back this up!)
|``.cookie`` | session RPC authentication cookie (written at start when cookie authentication is used, deleted on shutdown)
|``.lock`` | data directory lock file (empty)
|``testnet3/*`` | contains testnet versions of these files, except ``zcash.conf``, if running ``-testnet``
|``onion_private_key`` | cached Tor hidden service private key for ``-listenonion``
21 changes: 9 additions & 12 deletions doc/security-warnings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
Security Warnings
====================
=================

Security Audit
--------------
Expand All @@ -9,12 +9,12 @@ announcements, audit results and other general security information, see
https://z.cash/support/security.html

x86-64 Linux Only
-----------------------
-----------------

There are [known bugs](https://github.com/scipr-lab/libsnark/issues/26) which
make proving keys generated on 64-bit systems unusable on 32-bit and big-endian
systems. It's unclear if a warning will be issued in this case, or if the
proving system will be silently compromised.
There are [known bugs](https://github.com/scipr-lab/libsnark/issues/26/)
which make proving keys generated on 64-bit systems unusable on 32-bit and
big-endian systems. It's unclear if a warning will be issued in this case, or
if the proving system will be silently compromised.

Wallet Encryption
-----------------
Expand Down Expand Up @@ -50,8 +50,8 @@ Side-Channel Attacks

This implementation of Zcash is not resistant to side-channel attacks. You
should assume (even unprivileged) users who are running on the hardware, or who
are physically near the hardware, that your `zcashd` process is running on will
be able to:
are physically near the hardware, that your `zcashd` process is running on
will be able to:

- Determine the values of your secret spending keys, as well as which notes you
are spending, by observing cache side-channels as you perform a JoinSplit
Expand All @@ -75,9 +75,6 @@ The REST interface is a feature inherited from upstream Bitcoin. By default,
it is disabled. We do not recommend you enable it until it has undergone a
security review.

RPC Interface
---------------

Users should choose a strong RPC password. If no RPC username and password are
set, zcashd will not start and will print an error message with a suggestion
for a strong random password. If the client knows the RPC password, they have
Expand All @@ -96,7 +93,7 @@ users should be controlled to prevent confused-deputy attacks which could spend
from any keys held by that zcashd.

Block Chain Reorganization: Major Differences
-------------------------------------------------
---------------------------------------------

Users should be aware of new behavior in Zcash that differs significantly from
Bitcoin: in the case of a block chain reorganization, Bitcoin's coinbase
Expand Down
116 changes: 84 additions & 32 deletions doc/wallet-backup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,90 +2,142 @@

## Overview

Backing up your Zcash private keys is the best way to be proactive about preventing loss of access to your ZEC.
Backing up your Zcash private keys is the best way to be proactive about
preventing loss of access to your ZEC.

Problems resulting from bugs in the code, user error, device failure, etc. may lead to losing access to your wallet (and as a result, the private keys of addresses which are required to spend from them).
Problems resulting from bugs in the code, user error, device failure, etc. may
lead to losing access to your wallet (and as a result, the private keys of
addresses which are required to spend from them).

No matter what the cause of a corrupted or lost wallet could be, we highly recommend all users backup on a regular basis. Anytime a new address in the wallet is generated, we recommending making a new backup so all private keys for addresses in your wallet are safe.
No matter what the cause of a corrupted or lost wallet could be, we highly
recommend all users backup on a regular basis. Anytime a new address in the
wallet is generated, we recommending making a new backup so all private keys
for addresses in your wallet are safe.

Note that a backup is a duplicate of data needed to spend ZEC so where you keep your backup(s) is another important consideration. You should not store backups where they would be equally or increasingly susceptible to loss or theft.
Note that a backup is a duplicate of data needed to spend ZEC so where you keep
your backup(s) is another important consideration. You should not store backups
where they would be equally or increasingly susceptible to loss or theft.

## Instructions for backing up your wallet and/or private keys

These instructions are specific for the officially supported Zcash Linux client. For backing up with third-party wallets, please consult with user guides or support channels provided for those services.
These instructions are specific for the officially supported Zcash Linux
client. For backing up with third-party wallets, please consult with user
guides or support channels provided for those services.

There are multiple ways to make sure you have at least one other copy of the private keys needed to spend your ZEC and view your shielded ZEC.
There are multiple ways to make sure you have at least one other copy of the
private keys needed to spend your ZEC and view your shielded ZEC.

For all methods, you will need to include an export directory setting in your config file (`zcash.conf` located in the data directory which is `~/.zcash/` unless it's been overridden with `datadir=` setting):
For all methods, you will need to include an export directory setting in your
config file (`zcash.conf` located in the data directory which is `~/.zcash/`
unless it's been overridden with `datadir=` setting):

`exportdir=path/to/chosen/export/directory`

You may chose any directory within the home directory as the location for export & backup files. If the directory doesn't exist, it will be created.
You may chose any directory within the home directory as the location for
export & backup files. If the directory doesn't exist, it will be created.

Note that zcashd will need to be stopped and restarted for edits in the config file to take effect.
Note that zcashd will need to be stopped and restarted for edits in the config
file to take effect.

### Using `backupwallet`

To create a backup of your wallet, use:

`zcash-cli backupwallet <nameofbackup>`.
```bash
$ zcash-cli backupwallet <nameofbackup>
```

The backup will be an exact copy of the current state of your wallet.dat file stored in the export directory you specified in the config file. The file path will also be returned.
The backup will be an exact copy of the current state of your wallet.dat file
stored in the export directory you specified in the config file. The file path
will also be returned.

If you generate a new Zcash address, it will not be reflected in the backup file.
If you generate a new Zcash address, it will not be reflected in the backup
file.

If your original `wallet.dat` file becomes inaccessible for whatever reason, you can use your backup by copying it into your data directory and renaming the copy to `wallet.dat`.
If your original `wallet.dat` file becomes inaccessible for whatever reason,
you can use your backup by copying it into your data directory and renaming the
copy to `wallet.dat`.

### Using `z_exportwallet` & `z_importwallet`

If you prefer to have an export of your private keys in human readable format, you can use:
If you prefer to have an export of your private keys in human readable format,
you can use:

`zcash-cli z_exportwallet <nameofbackup>`
```bash
$ zcash-cli z_exportwallet <nameofbackup>`
```

This will generate a file in the export directory listing all transparent and shielded private keys with their associated public addresses. The file path will be returned in the command line.
This will generate a file in the export directory listing all transparent and
shielded private keys with their associated public addresses. The file path
will be returned in the command line.

To import keys into a wallet which were previously exported to a file, use:

`zcash-cli z_importwallet <path/to/exportdir/nameofbackup>`
```bash
$ zcash-cli z_importwallet <path/to/exportdir/nameofbackup>
```

Copy link
Contributor

@daira daira Aug 30, 2022 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This needs work. HD-generated keys won't be included in the export file and therefore won't be imported; this includes all Sapling and Orchard keys generated since and including zcashd 4.7.0.

### Using `z_exportkey`, `z_importkey`, `dumpprivkey` & `importprivkey`

If you prefer to export a single private key for a shielded address, you can use:
If you prefer to export a single private key for a shielded address, you can
use:

`zcash-cli z_exportkey <z-address>`
```bash
$ zcash-cli z_exportkey <z-address>
```

This will return the private key and will not create a new file.

For exporting a single private key for a transparent address, you can use the command inherited from Bitcoin:
For exporting a single private key for a transparent address, you can use the
command inherited from Bitcoin:

`zcash-cli dumpprivkey <t-address>`
```bash
$ zcash-cli dumpprivkey <t-address>
```

This will return the private key and will not create a new file.

To import a private key for a shielded address, use:

`zcash-cli z_importkey <z-priv-key>`
```bash
$ zcash-cli z_importkey <z-priv-key>
```

This will add the key to your wallet and rescan the wallet for associated transactions if it is not already part of the wallet.
This will add the key to your wallet and rescan the wallet for associated
transactions if it is not already part of the wallet.

The rescanning process can take a few minutes for a new private key. To skip it, instead use:
The rescanning process can take a few minutes for a new private key. To skip
it, instead use:

`zcash-cli z_importkey <z-private-key> no`
```bash
$ zcash-cli z_importkey <z-private-key> no
```

For other instructions on fine-tuning the wallet rescan, see the command's help documentation:
For other instructions on fine-tuning the wallet rescan, see the command's help
documentation:

`zcash-cli help z_importkey`
```bash
$ zcash-cli help z_importkey
```

To import a private key for a transparent address, use:

`zcash-cli importprivkey <t-priv-key>`
```bash
$ zcash-cli importprivkey <t-priv-key>
```

This has the same functionality as `z_importkey` but works with transparent addresses.
This has the same functionality as `z_importkey` but works with transparent
addresses.

See the command's help documentation for instructions on fine-tuning the wallet rescan:
See the command's help documentation for instructions on fine-tuning the wallet
rescan:

`zcash-cli help importprivkey`
```bash
$ zcash-cli help importprivkey
```

### Using `dumpwallet`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is currently disabled by default.


This command inherited from Bitcoin is deprecated. It will export private keys in a similar fashion as `z_exportwallet` but only for transparent addresses.
This command inherited from Bitcoin is deprecated and should not be used. It
will export private keys in a similar fashion as `z_exportwallet` but only for
transparent addresses.