monero-project/monero-docs
monero-project/monero-docs
2
1
Fork 0
mirror of https://github.com/monero-project/monero-docs.git synced 2024-12-22 19:49:22 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge branch 'master' into master

Browse source
This commit is contained in:
Piotr Włodarek 2020-05-12 18:32:09 +00:00 committed by GitHub
commit e49858c1f0
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
22 changed files with 677 additions and 124 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/interacting/monero-blockchain-export-reference.md
View file

@ -3,7 +3,7 @@ title: monero-blockchain-export - Reference | Monero Documentation
---
# `monero-blockchain-export` - Reference
!!! warning
!!! note
Nowadays, there is little usage for raw blockchain export / import. In the past the p2p blockchain download was much slower. Back than blockchain.raw file was used to speed up the process of bootstrapping a node.
## Overview

4
docs/interacting/monero-blockchain-import-reference.md
View file

@ -3,8 +3,8 @@ title: monero-blockchain-import - Reference | Monero Documentation
---
# `monero-blockchain-import` - Reference
!!! warning
Nowadays, there is little usage for raw blockchain export/import. In the past the p2p blockchain download was much slower. Back than blockchain.raw file was used to speed up download process of bootstrapping a node.
!!! note
Nowadays, there is little usage for raw blockchain export / import. In the past the p2p blockchain download was much slower. Back than blockchain.raw file was used to speed up download process of bootstrapping a node.
## Overview

42
docs/interacting/monero-config-file.md
View file

@ -9,7 +9,7 @@ By default Monero looks for `bitmonero.conf` in Monero [data directory](/interac
To use a specific config file add `--config-file` option:
`./monerod --config-file=/etc/monero.conf`
`./monerod --config-file=/etc/monerod.conf`
The `--config-file` option is available for:
@ -22,12 +22,16 @@ The `--config-file` option is available for:
* `option-name=value`
* `valueless-option-name=1` for options that don't expect value
* `# I am a comment`
* `# comment`
* whitespace is ignored
## Reference
All command line options work as configuration file options. See [monerod reference](/interacting/monerod-reference).
All configuration options are the same as command line options for the binary.
* [monerod reference](/interacting/monerod-reference)
* [monero-wallet-cli reference](/interacting/monero-wallet-cli-reference)
* [monero-wallet-rpc reference](/interacting/monero-wallet-rpc-reference)
Skip the `--` from `--option-name`.
@ -38,17 +42,21 @@ Example:
translates to:
log-level=4
stagenet=1 # use value "1" for
stagenet=1 # use value "1" to enable the value-less options like --stagenet
## Example
## Examples
# /etc/monero.conf
### `monerod.conf`
This config is tailored for production server usage.
# /etc/monero/monerod.conf
# Data directory (blockchain db and indices)
data-dir=/home/monero/.monero
data-dir=/home/monero/.monero # Remember to create the monero user first
# Log file
log-file=/var/log/monero/monero.log
log-file=/var/log/monero/monerod.log
max-log-file-size=0 # Prevent monerod from managing the log files; we want logrotate to take care of that
# P2P full node
@ -74,3 +82,21 @@ translates to:
limit-rate-up=1048576 # 1048576 kB/s == 1GB/s; a raise from default 2048 kB/s; contribute more to p2p network
limit-rate-down=1048576 # 1048576 kB/s == 1GB/s; a raise from default 8192 kB/s; allow for faster initial sync
### `monero-wallet-cli.conf`
This config is tailored for desktop usage on [stagenet](/infrastructure/networks).
# $HOME/.bitmonero/stagenet/monero-wallet-cli.conf
# Pick network
stagenet=1
# Connect to a remote full node
daemon-address=monero-stagenet.exan.tech:38081
untrusted-daemon=1
# Log file
log-file=/tmp/monero-wallet-cli.log
# wallet-file=/home/YOUR-USER/.bitmonero/stagenet/wallets/MoneroExampleStagenetWallet

313
docs/interacting/monero-wallet-cli-reference.md Normal file
View file

@ -0,0 +1,313 @@
---
title: monero-wallet-cli - Reference | Monero Documentation
---
# `monero-wallet-cli` - Reference
!!! note
Get yourself comfortable with a friendly Monero CLI wallet.
It is the most reliable and most complete wallet for Monero.
Use [stagenet](/infrastructure/networks) for learning.
## Overview
### Command line wallet
The "official" command line wallet for Monero. Available for Linux, macOS and Windows.
Wallet uses your private keys to understand your total balance,
transactions history, and to facilitate creating transactions.
However, wallet does not store the blockchain and does not directly participate in the p2p network.
The CLI wallet is the most reliable and most feature complete wallet for Monero.
### Depends on the full node
Wallet connects to a [full node](/interacting/monerod-reference) to scan the blockchain for your transaction outputs and to send your transactions out to the network.
The full node can be either local (same computer) or remote.
Normally, you run the full node on the same computer as wallet (or within your home network).
Connection happens over HTTP and uses [this API](https://www.getmonero.org/resources/developer-guides/wallet-rpc.html).
Any transaction leaving the wallet is already blinded by all Monero privacy features.
This means plain text HTTP communication isn't an issue on its own even if you connect to a remote node.
However, connecting to a remote node has other nuanced trade-offs, which is a topic for a separate article.
## Syntax
`./monero-wallet-cli [options] [command]`
Example:
`./monero-wallet-cli --stagenet`
## Running
Go to directory where you unpacked Monero.
Run the full node and wait until it syncs up with the network (may take up to a few days):
`./monerod --stagenet`
In a separate terminal window, run the wallet:
`./monero-wallet-cli --stagenet --generate-new-wallet MoneroExampleStagenetWallet`
## Options
#### Help and version
| Option | Description
|---------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `--help` | Enlist available options.
| `--version` | Show `monero-wallet-cli` version to stdout. Example: <br />`Monero 'Boron Butterfly' (v0.14.0.0-release)`
#### Pick network
| Option | Description
|------------------|------------------------------------------------------------------------------------------------
| (missing) | By default wallet assumes [mainnet](/infrastructure/networks).
| `--stagenet` | Run on [stagenet](/infrastructure/networks). Remember to run your daemon with `--stagenet` as well.
| `--testnet` | Run on [testnet](/infrastructure/networks). Remember to run your daemon with `--testnet` as well.
#### Logging
| Option | Description
|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------
| `--log-file <arg>` | Full path to the log file.
| `--log-level <arg>` | `0-4` with `0` being minimal logging and `4` being full tracing. Defaults to `0`. These are general presets and do not directly map to severity levels. For example, even with minimal `0`, you may see some most important `INFO` entries.
| `--max-log-file-size <arg>` | Soft limit in bytes for the log file (=104850000 by default, which is just under 100MB). Once log file grows past that limit, monero creates the next log file with a UTC timestamp postfix `-YYYY-MM-DD-HH-MM-SS`.<br /><br />In production deployments, you would probably prefer to use established solutions like logrotate instead. In that case, set `--max-log-file-size 0` to prevent monero from managing the log files.
| `--max-log-files <arg>` | Limit on the number of log files (=50 by default). The oldest log files are removed. In production deployments, you would probably prefer to use established solutions like logrotate instead.
#### Full node connection
Wallet depends on a full node for all non-local operations. The following options define how to connect to [`monerod`](/interacting/monerod-reference):
| Option | Description
|--------------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `--daemon-address <arg>` | Use `monerod` instance at `<host>:<port>`. Example: <br />`./monero-wallet-cli --daemon-address monero-stagenet.exan.tech:38081 --stagenet`
| `--daemon-host <arg>` | Use `monerod` instance at host `<arg>` instead of localhost.
| `--daemon-port <arg>` | Use `monerod` instance at port `<arg>` instead of 18081.
| `--daemon-login <arg>` | Specify `username[:password]` for `monerod` RPC API. It is based on HTTP Basic Auth. Mind that connections are by default unencrypted. Authentication only makes sense if you establish a secure connection (maybe via Tor, or SSH tunneling, or reverse proxy w/ TLS).
| `--trusted-daemon` | Enable commands and behaviors which rely on `monerod` instance being trusted. Default for localhost connection. The trust in this context concerns preserving your privacy. Only use this flag if you do control `monerod`. Trusted daemon allows for commands like `rescan_spent`, `start_mining`, `import_key_images` and behaviors like **not** warning about potential attack on transient problems with transaction sending.
| `--untrusted-daemon` | Disable commands and behaviors which rely on `monerod` instance being trusted. Default for a non-localhost connections. See `--trusted-daemon` for more details.
| `--do-not-relay` | The newly created transaction will not be relayed to the Monero network. Instead it will be dumped to a file in a raw hexadecimal format. Useful if you want to push the transaction through a gateway like [https://xmrchain.net/rawtx](https://xmrchain.net/rawtx). This may be easier to use over Tor than Monero wallet.
| `--allow-mismatched-daemon-version` | Allow communicating with `monerod` that uses a different RPC version.
#### Create new wallet
| Option | Description
|--------------------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `--generate-new-wallet <arg>` | Create a new Monero wallet and save it to `<arg>` file. You will be asked for a password. The password is used to encrypt the wallet file but it is unrelated to your master spend key or mnemonic seed. Generate a very strong password with your password manager (~256 bits of entropy). Example:<br /><br />`./monero-wallet-cli --stagenet --generate-new-wallet $HOME/.bitmonero/stagenet/wallets/MoneroExampleStagenetWallet`
| `--kdf-rounds <arg>` | Concerns encrypting the wallet file. The wallet file is encrypted with ChaCha stream cipher. The encryption key is derived from the user supplied password by hashing the password with CryptoNight. This option defines how many times the CryptoNight hashing will be applied. The default is `1` round of hashing. <br /><br />Note this is **unrelated** to spend key generation. <br /><br />The more rounds the longer you will wait to open the wallet or send transaction. But also the attacker will have it harder to brute force your wallet password. <br /><br />**Note:** You will have to remember and provide the same `kdf-rounds` on every wallet access!<br /><br />**Recommendation:** Do not change the default value. Instead generate a very strong wallet password with your password manager (256 bits of entropy).
#### Open existing wallet
| Option | Description
|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `--wallet-file <arg>` | Open existing wallet. Example: <br/><br/>`./monero-wallet-cli --stagenet --wallet-file $HOME/.bitmonero/stagenet/wallets/MoneroExampleStagenetWallet` <br /><br/>This is only for wallet files generated with `monero-wallet-cli`, `monero-wallet-gui`, or `monero-wallet-rpc` tools. If you have other type of wallet then see importing options.
| `--password <arg>` | Provide wallet password as a parameter instead of interactively. Remember to escape/quote as needed. <br /><br />**Not recommended** because the password will remain in your command history and will also be visible in the process table. For automation prefer `--password-file`. <br /><br />The option also works in combination with `--generate-new-wallet`.
| `--password-file <arg>` | Provide password as a file in stead of interactively. Trailing `\n` are discarded when reading the password file. <br /><br />Prefer this over `--password` if you automate wallet access. Make sure the password file is meaningfully separated from the wallet file. Otherwise it provides no security benefit. <br /><br />The option also works in combination with `--generate-new-wallet`.
#### Restore wallet
| Option | Description
|----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `--generate-from-device <arg>` | Restore/generate a special wallet to work with a **hardware device** like [Ledger](https://www.ledger.com/) or [Trezor](https://trezor.io/) and save it to `<arg>` file. Example: <br /><br />`./monero-wallet-cli --stagenet --generate-from-device MoneroExampleDeviceWallet --subaddress-lookahead 5:20` <br /><br />This is a one-time action. Next time you simply [open the wallet](#open-existing-wallet).<br /><br />By default the command expects Ledger hardware connected. For Trezor hardware add `--hw-device Trezor` (expected ~May 2019).<br /><br />It will take **up to 25 minutes** with default settings. This is because hardware devices are slow to pre-generate subaddresses. To mitigate use low `--subaddress-lookahead 5:20`. <br /><br />The local wallet will not have private spend key and will not be able to spend on its own. It serves as a user interface and a bridge for low-power hardware devices. Transaction signing with a private spend key always happens on the hardware device. <br /><br />See the [complete guide to hardware wallet setup](https://www.reddit.com/r/Monero/comments/8op6cp/ledger_cli_guides_requires_cli_v01220/).
| `--generate-from-view-key <arg>` | Restore a view-only version of the wallet to track incoming transactions and save it to `<arg>` file. The wallet is created based on a **secret view key** and **standard address**. The secret view key is meant to be pasted as hexadecimal.
| `--generate-from-spend-key <arg>`| Restore a wallet from **secret spend key** and save it to `<arg>` file. The secret spend key is meant to be pasted as hexadecimal.
| `--restore-deterministic-wallet` | Restore a wallet from **secret mnemonic seed**. Use this to restore from your 25 words backup. <br /><br />You will be asked for a password to encrypt the wallet file (once restored). Note this is **not** a passphrase to mnemonic seed. Mnemonic seeds generated by Monero official wallets are naked.
| `--restore-height <arg>` | Only scan for transactions later than specific blockchain height. The default is `0`. Raising the value makes wallet restoration **radically faster**. The optimal value should match the day you originally created the wallet (but cannot be later). The mapping between the block height and date/time is available on block explorers like [https://xmrchain.net](https://xmrchain.net/). For instance, if you created the wallet in 2019+ use `1730000`.
#### Multisig wallet
| Option | Description
|---------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `--generate-from-multisig-keys <arg>` | Create a standard wallet from multisig keys. This is useful to combine all multisig secret keys back into the standard wallet (when you no longer need the multisig). The wallet will then have control of the funds. It only supports providing all secret keys even if the multisig scheme allowed for less (only `N/N` not `N/M`).
| `--restore-multisig-wallet` | Restore a multisig wallet from **secret seed** that was earlier exported with the `seed` interactive command. This only restores your part of the wallet. Other multisig participants will still be necessary to sign the transaction.
#### Config file
| Option | Description
|--------------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `--config-file <arg>` | Full path to the [configuration file](/interacting/monero-config-file). Note this should be a separate config than `monerod` uses because these tools accept different set of options.
#### Performance
| Option | Description
|--------------------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `--subaddress-lookahead <arg>` | Accepts `m:n`, by default `50:200`. The first value is the number of accounts and the second value is the number of subaddresses per account. <br /><br />The wallet will not check for payments to subaddresses further than `n` away from the last received payment. This can happen if you generated unique subaddresses for `n` clients in a row but none of them paid. <br /><br >On the other hand the more subaddresses you set to look ahead, the longer it takes to create your wallet, because they must be pre-computed. This is normally not a concern, except for hardware wallets. On the Ledger the default value of `50:200` can take over 20 minutes (one time on wallet creation)!
| `--max-concurrency <arg>` | Max number of threads to use for parallel jobs. The default value `0` uses the number of CPU threads.
#### Internationalization
| Option | Description
|--------------------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `--mnemonic-language <arg>` | Language for mnemonic seed words. One of `english`, `english_old`, `esperanto`, `french`, `german`, `italian`, `japanese`, `lojban`, `portuguese`, `russian`, `spanish`. <br /><br />It might be a good idea to stick to default English which is by far the most popular and well tested. It also avoids potential non-ASCII characters pitfalls or bugs.
| `--use-english-language-names` | If your display freezes, exit blind with ^C, then run again with `--use-english-language-names`. This can happen when Monero prompts for a language displaying language names in their natives alphabets.
#### Legacy
These options are either legacy or rarely useful.
| Option | Description
|------------------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `--non-deterministic` | Generate legacy non-deterministic wallet. The view key will **not** be derived from the spend key. You would also have to backup the *.keys. To restore non-deterministic wallet (standard address) use `--generate-from-keys`. To restore fully you will need the *.keys file.
| `--generate-from-keys <arg>` | Restore legacy non-deterministic wallet by providing both spend and view keys and the standard address.
| `--shared-ringdb-dir <arg>` | Set shared ring database path. [No longer worthwhile](https://www.reddit.com/r/Monero/comments/9rtnpx/are_there_any_updated_blackball_databases/).
| `--create-address-file` | Has no effect. The `*.address.txt` file is created regardless of this option.
| `--electrum-seed <arg>` | Provide mnemonic seed as a commandline option for `--restore-deterministic-wallet` instead of interactively. This is not recommended b/c the seed will be saved in your command history and also visible in the process list.
| `--generate-from-json <arg>` | You would run `monero-wallet-rpc` to use this option. It seems exposed in `monero-wallet-cli` by accident.
| `--tx-notify <arg>` | You would run `monero-wallet-rpc` to use this option. It seems exposed in `monero-wallet-cli` by accident.
## Defaults
Wallet files are created and seek in current directory. This is rarely what you want. Use `--wallet-file` and similar options to control this.
Log files are created in the same directory as `monero-wallet-cli` binary. Use `--log-file` to specify the location.
## Commands
Commands are used interactively in the `monero-wallet-cli` prompt.
You can also run a one-off command by providing it as a commandline parameter.
This is rarely useful though. For automation prefer `monero-wallet-rpc`.
The CLI wallet has **built-in help for individual commands** - we will not attempt to reproduce that.
Instead we focus on grouping commands so you can quickly find what you are looking for.
Use `help command_name` to learn more.
### Help and version
`help` - list all commands
`help command_name` - show help for individual command
`version` - show version of the monero-wallet-cli binary
### Balance
`account` - total balance; list accounts with respective balances
`balance detail` - within the current account, list addresses with respective balances
### Manage accounts
`account`
`account new`
`account switch`
`account label`
### Manage addresses
`address all`
`address new`
`address label`
### Network status
`status` - show if synced up to the blockchain height
`fee` - show current fee-per-byte and full node's mempool (the backlog of transactions depending on the priority)
`wallet_info` - show wallet file path, standard address, type and network
### Secret mnemonic seed
`seed` - show raw mnemonic seed
`encrypted_seed` - create mnemonic seed encrypted with the passphrase; you will need to remember or store the passphrase separately; restoring will not be possible without the passphrase
### Secret keys
`spendkey` - show secret spend key and public spend key
`viewkey` - show secret view key and public view key
### Proofs
`get_reserve_proof` -> `check_reserve_proof` - prove the balance
`get_spend_proof` -> `check_spend_proof` - prove you made the payment
`sign <file>` -> `verify <filename> <address> <signature>` - prove ownership of the address; allows to verify the file was signed by the owner of specific Monero address
`get_tx_proof` -> `check_tx_proof`
### Multisig
#### Setup
`prepare_multisig`
`make_multisig`
`finalize_multisig`
#### Update
`export_multisig_info`
`import_multisig_info`
#### Other
`submit_multisig`
`exchange_multisig_keys`
`export_raw_multisig_tx`
### Tx private key
These allow to learn and verify transaction's private key `r`.
This was useful to create a [proof of payment](https://www.getmonero.org/resources/user-guides/prove-payment.html)
but got superseded by `get_spend_proof`.
`get_tx_key <txid>`
`check_tx_key <txid> <txkey> <address>`
`set_tx_key <txid> <tx_key>`
### Advanced
`unspent_outputs` - show a list of, and a histogram of unspent outputs (indivisible pieces of your total balance)
`export_key_images <file>` -> `import_key_images <file>` - used to inform the view-only wallet about outgoing transactions so it can calculate the real balance; normally view-only wallets only learn about incoming transactions, not outgoing
`export_outputs <file>` - export a set of outputs owned by this wallet to a `<file>`
### Mining
`start_mining`
`stop_mining`
### Donate
`donate <amount>` - donate `<amount> to development team.
### Non essential or legacy
`address_book [(add ((<address> [pid <id>])|<integrated address>) [<description possibly with whitespaces>])|(delete <index>)]`
`set_description [free text note]` -> `get_description` - manage convenience description of the wallet (the information is local)
`save` - this now happens automatically
`save_bc` - this now happens automatically
`bc_height` - show blockchain height (superseded with `status`)
`sweep_unmixable` - only relevant for very old wallets (<= 2016); send all unmixable outputs to yourself with ring_size 10
TODO: document remaining commands

15
docs/interacting/monero-wallet-gui-reference.md
View file

@ -16,7 +16,7 @@ However, wallet does not store the blockchain and does not directly participate
### Depends on the full node
Wallet connects to [full node](/interacting/monerod-reference) to scan the blockchain for your transaction outputs and to send your transactions out to the network.
Wallet connects to a [full node](/interacting/monerod-reference) to scan the blockchain for your transaction outputs and to send your transactions out to the network.
The full node can be either local (same computer) or remote.
@ -27,7 +27,7 @@ Connection happens over HTTP and uses [this API](https://www.getmonero.org/resou
Any transaction leaving the wallet is already blinded by all Monero privacy features.
This means plain text HTTP communication isn't an issue on its own even if you connect to a remote node.
However, connecting to a remote node has other nuanced trade-offs, which is a topic for a separate article. TODO: write an article or link the best available source.
However, connecting to a remote node has other nuanced trade-offs, which is a topic for a separate article.
### User guide PDF
@ -58,7 +58,18 @@ In a separate terminal window, run the wallet:
## Options
There are very few options because everything is set up via a GUI.
| Option | Description
|---------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `--help` | Enlists available options.
| `--log-file` | Full path to the log file. Example (mind file permissions): <br/>`./monerod --log-file=/var/log/monero/mainnet/monerod.log`
## Defaults
The wallet is created in `$HOME/Monero/wallets/`.
You may want to change it to `$HOME/.bitmonero/wallets/` to have all Monero related files in one place.
This is possible on wallet creation wizard in the GUI.
The log file is created directly in the home directory `$HOME/monero-wallet-gui.log`.
You may want to change with `--log-file=$HOME/.bitmonero/monero-wallet-gui.log` option.

31
docs/interacting/monerod-reference.md
View file

@ -63,16 +63,16 @@ The following groups are only to make reference easier to follow. The daemon its
| Option | Description
|---------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `--help` | Enlist available options.
| `--version` | Show `monerod` version to stdout. Example: <br />`Monero 'Lithium Luna' (v0.12.3.0-release)`
| `--version` | Show `monerod` version to stdout. Example: <br />`Monero 'Boron Butterfly' (v0.14.0.0-release)`
| `--os-version` | Show build timestamp and target operating system. Example output:<br />`OS: Linux #1 SMP PREEMPT Fri Aug 24 12:48:58 UTC 2018 4.18.5-arch1-1-ARCH`.
#### Pick network
| Option | Description
| Option | Description
|------------------|------------------------------------------------------------------------------------------------
| (missing) | By default monerod assumes [mainnet](/infrastructure/networks).
| `--stagenet` | Run on [stagenet](/infrastructure/networks). Remember to run your wallet with `--stagenet` as well.
| `--testnet` | Run on [testnet](/infrastructure/networks). Remember to run your wallet with `--testnet` as well.
| (missing) | By default monerod assumes [mainnet](/infrastructure/networks).
| `--stagenet` | Run on [stagenet](/infrastructure/networks). Remember to run your wallet with `--stagenet` as well.
| `--testnet` | Run on [testnet](/infrastructure/networks). Remember to run your wallet with `--testnet` as well.
#### Logging
@ -98,8 +98,8 @@ The following options will be helpful if you intend to have an always running no
| `--non-interactive` | Do not require tty in a foreground mode. Helpful when running in a container. By default `monerod` runs in a foreground and opens stdin for reading. This breaks containerization because no tty gets assigned and `monerod` process crashes. You can make it run in a background with `--detach` but this is inconvenient in a containerized environment because the canonical usage is that the container waits on the main process to exist (forking makes things more complicated).
| `--no-igd` | Disable UPnP port mapping on the router ("Internet Gateway Device"). Add this option to improve security if you are **not** behind a NAT (you can bind directly to public IP or you run through Tor).
| `--max-txpool-weight` | Set maximum transactions pool size in bytes. By default 648000000 (~618MB). These are transactions pending for confirmations (not included in any block).
| `--enforce-dns-checkpointing` | The emergency checkpoints set by [MoneroPulse](/infrastructure/monero-pulse.md) operators will be enforced. It is probably a good idea to set enforcing for unattended nodes. <br /><br />If encountered block hash does not match corresponding checkpoint, the local blockchain will be rolled back a few blocks, effectively blocking following what MoneroPulse operators consider invalid fork. The log entry will be produced: `ERROR` `Local blockchain failed to pass a checkpoint, rolling back!` Eventually, the alternative ("fixed") fork will get heavier and the node will follow it, leaving the "invalid" fork behind.<br /><br />By default checkpointing only notifies about discrepancy by producing the following log entry: `ERROR` `WARNING: local blockchain failed to pass a MoneroPulse checkpoint, and you could be on a fork. You should either sync up from scratch, OR download a fresh blockchain bootstrap, OR enable checkpoint enforcing with the --enforce-dns-checkpointing command-line option`.<br /><br />Reference: [source code](https://github.com/monero-project/monero/blob/22a6591a70151840381e327f1b41dc27cbdb2ee6/src/cryptonote_core/blockchain.cpp#L3614).
| `--disable-dns-checkpoints` | The [MoneroPulse](/infrastructure/monero-pulse.md) checkpoints set by core developers will be discarded. The checkpoints are apparently still fetched though.
| `--enforce-dns-checkpointing` | The emergency checkpoints set by [MoneroPulse](/infrastructure/monero-pulse) operators will be enforced. It is probably a good idea to set enforcing for unattended nodes. <br /><br />If encountered block hash does not match corresponding checkpoint, the local blockchain will be rolled back a few blocks, effectively blocking following what MoneroPulse operators consider invalid fork. The log entry will be produced: `ERROR` `Local blockchain failed to pass a checkpoint, rolling back!` Eventually, the alternative ("fixed") fork will get heavier and the node will follow it, leaving the "invalid" fork behind.<br /><br />By default checkpointing only notifies about discrepancy by producing the following log entry: `ERROR` `WARNING: local blockchain failed to pass a MoneroPulse checkpoint, and you could be on a fork. You should either sync up from scratch, OR download a fresh blockchain bootstrap, OR enable checkpoint enforcing with the --enforce-dns-checkpointing command-line option`.<br /><br />Reference: [source code](https://github.com/monero-project/monero/blob/22a6591a70151840381e327f1b41dc27cbdb2ee6/src/cryptonote_core/blockchain.cpp#L3614).
| `--disable-dns-checkpoints` | The [MoneroPulse](/infrastructure/monero-pulse) checkpoints set by core developers will be discarded. The checkpoints are apparently still fetched though.
#### P2P network
@ -150,9 +150,13 @@ The following options define how the API behaves.
#### Accepting Monero
| Option | Description
|------------------|------------------------------------------------------------------------------------------------
| `--block-notify` | Run a program for each new block. The argument must be a **full path**. If the argument contains `%s` it will be replaced by the block hash. Example: <br />`./monerod --block-notify="/usr/bin/echo %s"`<br /><br />Couple of notes:<br />1) Block notifications are good for immediate reaction. However, you should always assume you will miss some block notifications and you should independently poll the API to cover this up.<br />2) Mind blockchain reorganizations. Block notifications can revert to same and past heights. This actually happens pretty often.<br />3) See also `--tx-notify` option of `monero-wallet-rpc` daemon [here](https://github.com/monero-project/monero/pull/4333).
These are network notifications offered by `monerod`. There are also wallet notifications like `--tx-notify` offered by `monero-wallet-rpc` [here](https://github.com/monero-project/monero/pull/4333).
| Option | Description
|------------------------------|------------------------------------------------------------------------------------------------
| `--block-notify <arg>` | Run a program for each new block. The `<arg>` must be a **full path**. If the `<arg>` contains `%s` it will be replaced by the block hash. Example: <br />`./monerod --block-notify="/usr/bin/echo %s"`<br /><br />Block notifications are good for immediate reaction. However, you should always assume you will miss some block notifications and you should independently poll the API to cover this up. <br /><br />Mind blockchain reorganizations. Block notifications can revert to same and past heights. Small reorganizations are natural and happen every day.
| `--block-rate-notify <arg>` | Run a program when the number of blocks received in the recent past deviates significantly from the expectation. The `<arg>` must be a **full path**. The `<arg`> can contain any of `%t`, `%b`, `%e` symbols to interpolate: <br /><br >`%t`: the number of minutes in the observation window<br /><br >`%b`: the number of blocks observed in that window<br /><br >`%e`: the ideal number of blocks expected in that window<br /><br > The option will let you know if the network hash rate drops by a lot. This may be indicative of a large section of the network miners moving off to mine a private chain, to be later released to the network. Note that if this event triggers, it is not incontrovertible proof that this is happening. It might just be chance. The longer the window (the %t parameter), and the larger the distance between actual and expected number of blocks, the more indicative it is of a possible chain reorg double-spend attack being prepared.<br /><br />**Recommendation:** unless you run economically significant Monero exchange or operation, do **not** act on this data. It is hard to calibrate and easy to misinterpret. If this is a real attack, it will target high-liquidity entities and not small merchants.
| `--reorg-notify <arg>` | Run a program when reorganization happens (ie, at least one block is removed from the top of the blockchain). The `<arg>` must be a **full path**. The `<arg`> can contain any of `%s`, `%h`, `%n` symbols to interpolate: <br /><br >`%s`: the height at which the split occurs <br /><br />`%h`: the height of the new blockchain<br /><br />`%d`: the number of blocks discarded from the old chain <br /><br />`%n`: the number of blocks being added <br /><br /> The option will let you know when a block is removed from the chain to be replaced by other blocks. This happens when a 51% attack occurs, but small reorgs also happen in the normal course of things. The `%d` parameter will be set to the number of blocks discarded from the old chain (so if this is higher than the number of confirmations you wait to act upon an incoming payment, that payment might have been cancelled). The `%n` parameter wil be set to the number of blocks in the new chain (so if this is higher than the number of confirmations you wait to act upon an incoming payment, any incoming payment in the first block will be automatically acted upon by your platform). <br /><br />**Recommendation**: unless you run economically significant Monero exchange or operation, you do **not** need to bother with this option. Simply account for reorganizations by requiring at least 10 confirmations before shipping valuable goods.
#### Performance
@ -161,7 +165,7 @@ These are advanced options that allow you to optimize performance of your `moner
| Option | Description
|---------------------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `--db-sync-mode` | Specify sync option, using format:<br />`[safe|fast|fastest]:[sync|async]:[<nblocks_per_sync>[blocks]|<nbytes_per_sync>[bytes]]`<br /><br />The default is `fast:async:250000000bytes`.<br /><br />The `fast:async:*` can corrupt blockchain database in case of a system crash. It should not corrupt if just `monerod` crashes. If you are concerned with system crashes use `safe:sync`.
| `--max-concurrency` | Max number of threads to use for a parallel jobs. The default value `0` uses the number of CPU threads.
| `--max-concurrency` | Max number of threads to use for parallel jobs. The default value `0` uses the number of CPU threads.
| `--prep-blocks-threads` | Max number of threads to use when computing block hashes (PoW) in groups. Defaults to 4. Decrease this if you don't want `monerod` hog your computer when syncing.
| `--fast-block-sync` | Sync up most of the way by using embedded, "known" block hashes. Pass `1` to turn on and `0` to turn off. This is on (`1`) by default. Normally, for every block the full node must calculate the block hash to verify miner's proof of work. Because the CryptoNight PoW used in Monero is very expensive (even for verification), `monerod` offers skipping these calculations for old blocks. In other words, it's a mechanism to trust `monerod` binary regarding old blocks' PoW validity, to sync up faster.
| `--block-sync-size` | How many blocks are processed in a single batch during chain synchronization. By default this is 20 blocks for newer history and 100 blocks for older history ("pre v4"). Default behavior is represented by value `0`. Intuitively, the more resources you have, the bigger batch size you may want to try out. Example:<br />`./monerod --block-sync-size=500`
@ -180,7 +184,7 @@ Be advised though that real mining happens **in pools** and with high-end **GPU-
| Option | Description
|------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `--start-mining` | Specify wallet address to mining for. **This must be a [main address](/public-address/main-address)!** It can be neither a subaddres nor integrated address.
| `--start-mining` | Specify wallet address to mining for. **This must be a [standard address](/public-address/standard-address)!** It can be neither a subaddres nor integrated address.
| `--mining-threads` | Specify mining threads count. By default ony one thread will be used. For best results, set it to number of your physical cores.
| `--extra-messages-file` | Specify file for extra messages to include into coinbase transactions.
| `--bg-mining-enable` | Enable unobtrusive mining. In this mode mining will use a small percentage of your system resources to never noticeably slow down your computer. This is intended to encourage people to mine to improve decentralization. That being said chances of finding a block are diminishingly small with solo CPU mining, and even lesser with its unobtrusive version. You can tweak the unobtrusivness / power trade-offs with the further `--bg-*` options below.
@ -232,7 +236,7 @@ You can also type commands directly in the console of the running `monerod` (if
| Option | Description
|------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `help [<command>]` | Show help for `<command>`.
| `version` | Show version information. Example output:<br />`Monero 'Beryllium Bullet' (v0.13.0.2-release)`
| `version` | Show version information. Example output:<br />`Monero 'Boron Butterfly' (v0.14.0.0-release)`
| `status` | Show status. Example output:<br />`Height: 186754/186754 (100.0%) on stagenet, not mining, net hash 317 H/s, v9, up to date, 8(out)+0(in) connections, uptime 0d 3h 48m 47s`
#### P2P network
@ -288,7 +292,6 @@ You can also type commands directly in the console of the running `monerod` (if
| `print_status` | Show if daemon is running.
| `update (check|download)` | Check if update is available and optionally download it. The hash is SHA-256. On linux use `sha256sum` to verify. Example output:<br />`Update available: v0.13.0.4: https://downloads.getmonero.org/cli/monero-linux-x64-v0.13.0.4.tar.bz2, hash 693e1a0210201f65138ace679d1ab1928aca06bb6e679c20d8b4d2d8717e50d6`<br/>`Update downloaded to: /opt/monero-v0.13.0.2/monero-linux-x64-v0.13.0.4.tar.bz2`
#### Mining
| Option | Description

5
docs/interacting/overview.md
View file

@ -15,7 +15,7 @@ Monero project nicely decouples network node logic from wallet logic.
Wallet logic is offered through three independent user interfaces - the GUI, the CLI, and the HTTP API.
```
# cd monero-gui-v0.13.0.3
# cd monero-gui-v0.14.0.0
# ---- guide to Monero GUI ----
@ -87,8 +87,7 @@ This is where the blockchain, log files, and p2p network memory are stored.
By default data directory is at:
* `$HOME/.bitmonero/` on Linux
* `$HOME/Library/Application\ Support/` on macOS
* `$HOME/.bitmonero/` on Linux and macOS
* `C:\ProgramData\bitmonero\` on Windows
Please mind:

13
docs/interacting/verify-monero-binaries.md
View file

@ -7,7 +7,7 @@ Verification must be carried on **before extracting the archive and before using
Instructions were tested on Linux. They should also work on macOS with slight modifications.
## 0. Import core dev PGP key
## 1. Import core dev PGP key
This is a one time action. Skip this step for subsequent Monero releases.
@ -29,7 +29,7 @@ Trust Riccardo's public key (fingerprint must be exactly this):
If key with this fingerprint was not found then remove imported key immediately (gpg --delete-keys ...).
That would mean the key changed (likely was compromised).
## 1. Verify signature of hash list
## 2. Verify signature of hash list
The list of binaries and their hashes is published on [getmonero.org](https://www.getmonero.org/downloads/hashes.txt) and a few other places like release notes on [r/monero](https://reddit.com/r/monero).
Please note the publication channel does not matter as long as you properly verify the signature! u
@ -38,12 +38,11 @@ To verify these are real hashes (not tampered with) run:
`curl https://www.getmonero.org/downloads/hashes.txt | gpg --verify`
The expected output is:
The expected output should contain the line:
...
gpg: Good signature from "Riccardo Spagni <ric@spagni.net>" [full]
`gpg: Good signature from "Riccardo Spagni <ric@spagni.net>" [full]`
## 2. Verify the hash
## 3. Verify the hash
By this step we checked that published hashes were not tampered with.
@ -53,7 +52,7 @@ The last step is to compare published hash with downloaded archive SHA-256 hash.
Replace the example file name with actual one:
file_name=monero-linux-x64-v0.13.0.4.tar.bz2
file_name=monero-linux-x64-v0.14.0.0.tar.bz2
file_hash=`sha256sum $file_name | cut -c 1-64`

2
docs/multisignature.md
View file

@ -23,7 +23,7 @@ Let's consider the 2-of-3 scheme. We have 3 participants. Each participant is gr
Multi-signing is a wallet-level feature. There is no way to learn from the blockchain which transactions were created using multiple signatures.
It is also worth noting in Monero there is no multisig addresses as such. [Address structure](/public-address/main-address/) does not care how the underlying private spend key got created.
It is also worth noting in Monero there is no multisig addresses as such. [Address structure](/public-address/standard-address/) does not care how the underlying private spend key got created.
After multisig wallet setup every participant ends up knowing the public address and private view key. This is necessary for participants to recognize and decipher transactions they are supposed to co-sign.

7
docs/proof-of-work/cryptonight.md
View file

@ -131,13 +131,16 @@ This is how Monero community refers to original implementation of CryptoNight.
### CryptoNight v1
See the [source code diff](https://github.com/monero-project/monero/pull/3253/files) for CryptoNight v1 modifications.
See the [source code diff](https://github.com/monero-project/monero/pull/3253/files).
### CryptoNight v2
The v2 changes were more involved.
See the [rationale](https://github.com/SChernykh/xmr-stak-cpu/blob/master/README.md) and the [source code diff](https://github.com/monero-project/monero/commit/5fd83c13fbf8dc304909345e60a853c15b0de1e5#diff-7000dc02c792439471da62856f839d62).
### CryptoNight v3 aka CryptoNightR
See the [rationale](https://github.com/monero-project/monero/pull/5126) and the [source code diff](https://github.com/monero-project/monero/pull/5126/files).
## Critique
* CryptoNight hash is relatively expensive to verify. This poses a risk of DoS-ing nodes with incorrect proofs to process. See [strong asymmetry](/proof-of-work/what-is-pow/#strong-asymmetry) requirement.

6
docs/proof-of-work/random-x.md Normal file
View file

@ -0,0 +1,6 @@
---
title: RandomX | Monero Documentation
---
# RandomX
For general information about RandomX you can read this [article](https://www.monerooutreach.org/stories/RandomX.html).

60
docs/public-address/main-address.md
View file

@ -1,61 +1,3 @@
---
title: Main Address | Monero Documentation
redirect: /public-address/standard-address/
---
# Address
Monero public address is what you publish to get paid.
An address can be generated offline and for free. It boils down to generating a large random number representing your private spending key.
Publishing your Monero address does __not__ endanger your privacy. That's because in Monero transactions go to stealth addresses which are decoupled from your public address.
There are a few **types of public addresses** in Monero:
* Main address - basic type of an address, also refered to as raw address
* Subaddress - what you should be using by default
* Integrated address - relevant for exchanges, merchants, and other businesses accepting Monero in a fully automated way
## Main address
Historicaly, raw address was the only available option. For that reason it is the most widely adopted and supported address type.
Its strength is simplicity. However, these days users should prefer receiving to subaddresses instead.
Technically, raw address is also a basis for creating subaddresses and integrated addresses.
Raw address is **still useful for**:
* accepting block reward in a solo-mining scenario as other addresses are not supported
* accepting from senders who batch payouts (like mining pools); in this scenario the sender is paying multiple parties using a single transaction; such transaction has multiple outputs; subaddresses do not work in this scenario
* accepting from senders who use legacy wallets (can't send to subaddress)
Monero raw address is composed of two public keys:
* public spend key
* public view key
It also contains a checksum and a "network byte" which actually identifies both the network and the address type.
## Data structure
Index | Size in bytes | Description
------------|------------------|-------------------------------------------------------------
0 | 1 | identifies the network and address type; [18](https://github.com/monero-project/monero/blob/793bc973746a10883adb2f89827e223f562b9651/src/cryptonote_config.h#L149) - main chain; [53](https://github.com/monero-project/monero/blob/793bc973746a10883adb2f89827e223f562b9651/src/cryptonote_config.h#L161) - test chain
1 | 32 | public spend key
33 | 32 | public view key
65 | 4 | checksum ([Keccak-f[1600] hash](https://github.com/monero-project/monero/blob/8f1f43163a221153403a46902d026e3b72f1b3e3/src/common/base58.cpp#L261) of the previous 65 bytes, trimmed to first [4](https://github.com/monero-project/monero/blob/8f1f43163a221153403a46902d026e3b72f1b3e3/src/common/base58.cpp#L53) bytes)
It totals to 69 bytes. The bytes are then encoded ([src](https://github.com/monero-project/monero/blob/8f1f43163a221153403a46902d026e3b72f1b3e3/src/common/base58.cpp#L240)) in [Monero specific Base58](/cryptography/base58) format, resulting in a 95 chars long string. Example main address:
`4AdUndXHHZ6cfufTMvppY6JwXNouMBzSkbLYfpAV5Usx3skxNgYeYTRj5UzqtReoS44qo9mtmXCqY45DJ852K5Jv2684Rge`
See the [source code](https://github.com/monero-project/monero/blob/f7b9f44c1b0d53170fd7f53d37fc67648f3247a2/src/cryptonote_basic/cryptonote_basic_impl.cpp#L159).
## Generating
Main address is derived from the root private key.
## Reference
* [StackExchenge answer](https://monero.stackexchange.com/questions/980/what-are-the-public-viewkeys-and-spendkeys)
* [https://xmr.llcoins.net/addresstests.html](https://xmr.llcoins.net/addresstests.html)

61
docs/public-address/standard-address.md Normal file
View file

@ -0,0 +1,61 @@
---
title: Standard Address | Monero Documentation
---
# Address
Monero public address is what you publish to get paid.
An address can be generated offline and for free. It boils down to generating a large random number representing your private spending key.
Publishing your Monero address does __not__ endanger your privacy. That's because in Monero transactions go to stealth addresses which are decoupled from your public address.
There are a few **types of public addresses** in Monero:
* Standard address - basic type of an address, also referred to as raw address
* Subaddress - what you should be using by default
* Integrated address - relevant for exchanges, merchants, and other businesses accepting Monero in a fully automated way
## Standard address
Historically, raw address was the only available option. For that reason it is the most widely adopted and supported address type.
Its strength is simplicity. However, these days users should prefer receiving to subaddresses instead.
Technically, raw address is also a basis for creating subaddresses and integrated addresses.
Raw address is **still useful for**:
* accepting block reward in a solo-mining scenario as other addresses are not supported
* accepting from senders who batch payouts (like mining pools); in this scenario the sender is paying multiple parties using a single transaction; such transaction has multiple outputs; subaddresses do not work in this scenario
* accepting from senders who use legacy wallets (can't send to subaddress)
Monero raw address is composed of two public keys:
* public spend key
* public view key
It also contains a checksum and a "network byte" which actually identifies both the network and the address type.
## Data structure
Index | Size in bytes | Description
------------|------------------|-------------------------------------------------------------
0 | 1 | identifies the network and address type; [18](https://github.com/monero-project/monero/blob/793bc973746a10883adb2f89827e223f562b9651/src/cryptonote_config.h#L149) - main chain; [53](https://github.com/monero-project/monero/blob/793bc973746a10883adb2f89827e223f562b9651/src/cryptonote_config.h#L161) - test chain
1 | 32 | public spend key
33 | 32 | public view key
65 | 4 | checksum ([Keccak-f[1600] hash](https://github.com/monero-project/monero/blob/8f1f43163a221153403a46902d026e3b72f1b3e3/src/common/base58.cpp#L261) of the previous 65 bytes, trimmed to first [4](https://github.com/monero-project/monero/blob/8f1f43163a221153403a46902d026e3b72f1b3e3/src/common/base58.cpp#L53) bytes)
It totals to 69 bytes. The bytes are then encoded ([src](https://github.com/monero-project/monero/blob/8f1f43163a221153403a46902d026e3b72f1b3e3/src/common/base58.cpp#L240)) in [Monero specific Base58](/cryptography/base58) format, resulting in a 95 chars long string. Example standard address:
`4AdUndXHHZ6cfufTMvppY6JwXNouMBzSkbLYfpAV5Usx3skxNgYeYTRj5UzqtReoS44qo9mtmXCqY45DJ852K5Jv2684Rge`
See the [source code](https://github.com/monero-project/monero/blob/f7b9f44c1b0d53170fd7f53d37fc67648f3247a2/src/cryptonote_basic/cryptonote_basic_impl.cpp#L159).
## Generating
Standard address is derived from the root private key. TODO.
## Reference
* [StackExchenge answer](https://monero.stackexchange.com/questions/980/what-are-the-public-viewkeys-and-spendkeys)
* [https://xmr.llcoins.net/addresstests.html](https://xmr.llcoins.net/addresstests.html)

21
docs/public-address/subaddress.md
View file

@ -20,9 +20,6 @@ Note it won't help if you have an account with the service. Then your payouts ar
## Group funds into accounts
!!! Note
Feel free to skip this if your are new to Monero. Accounts are not essential and currently not supported by the GUI.
**Accounts** are a convenience wallet-level feature to group subaddresses under one label and balance.
You may want to organize your funds into accounts like "cash", "work", "trading", "mining", "donations", etc.
@ -31,8 +28,6 @@ As accounts are only groupings of subaddresses, they themselves do not have an a
Accounts are deterministically derived from the root private key along with subaddresses.
As of September 2018 accounts are only supported by the CLI wallet and missing from GUI wallet.
Accounts are similar to subaccounts in your classic bank account. There is a very important difference though. In Monero funds don't really sit on accounts or public addresses. Public addresses are conceptually a gateway or a routing mechanism. Funds sit on transactions' unspent outputs. Thus, a single transaction can - in principle - aggregate and spend outputs from multiple addresses (and by extension from multiple accounts). The CLI or GUI wallet may not directly support creating such transactions for simplicity.
In short, think of accounts as a **soft** grouping of your funds.
@ -56,7 +51,7 @@ Index | Size in bytes | Description
------------|------------------|-------------------------------------------------------------
0 | 1 | identifies the network and address type; [42](https://github.com/monero-project/monero/blob/31bdf7bd113c2576fe579ef3a25a2d8fef419ffc/src/cryptonote_config.h#L171) - mainnet; [36](https://github.com/monero-project/monero/blob/31bdf7bd113c2576fe579ef3a25a2d8fef419ffc/src/cryptonote_config.h#L200) - stagenet; [63](https://github.com/monero-project/monero/blob/31bdf7bd113c2576fe579ef3a25a2d8fef419ffc/src/cryptonote_config.h#L185) - testnet
Otherwise the data structure is the same as for the [main address](/public-address/main-address/#data-structure).
Otherwise the data structure is the same as for the [standard address](/public-address/standard-address/#data-structure).
## Generating
@ -81,7 +76,7 @@ Where:
* `Hs` is a Keccak-256 hash function interpreted as integer and modulo `l` (maximum edwards25519 scalar)
* `||` is a byte array concatenation operator
* `SubAddr` is a 0-terminated fixed string (8 bytes total)
* `a` is a private view key of the main address (a 32 byte little endian unsigned integer)
* `a` is a private view key of the standard address (a 32 byte little endian unsigned integer)
* `account_index` is index of an account (a 32 bit little endian unsigned integer)
* `subaddress_index_within_account` is index of the subaddress within the account (a 32 bit little endian unsigned integer)
@ -95,7 +90,7 @@ The subaddress public spend key `D` is derived as follows:
Where:
* `B` is main address public spend key
* `B` is standard address public spend key
* `m` is subaddress private view key
* `G` is the "base point"; this is simply a constant specific to [edwards25519](/cryptography/asymmetric/edwards25519)
@ -107,21 +102,21 @@ The subaddress public view key `C` is derived as follows:
Where:
* `a` is a private view key of the main address
* `a` is a private view key of the standard address
* `D` is a public spend key of the subaddress
### Special case for (0, 0)
The subaddress #0 on the account #0 is the [main address](/public-address/main-address).
As main address has different generation rules, this is simply implemented via an `if` statement.
The subaddress #0 on the account #0 is the [standard address](/public-address/standard-address).
As standard address has different generation rules, this is simply implemented via an `if` statement.
### Building the address string
The procedure is the same as for the [main address](/public-address/main-address).
The procedure is the same as for the [standard address](/public-address/standard-address).
## Caveats
* It is not recommended to sweep all the balances of subaddress to main address in a single transaction. That links the subaddresses together on the blockchain. However, this only concerns privacy against specific sender and the situation will never get worse than not using subaddresses in the first place. If you need to join funds while preserving maximum privacy do it with individual transactions (one per subaddress).
* It is not recommended to sweep all the balances of subaddress to standard address in a single transaction. That links the subaddresses together on the blockchain. However, this only concerns privacy against specific sender and the situation will never get worse than not using subaddresses in the first place. If you need to join funds while preserving maximum privacy do it with individual transactions (one per subaddress).
* Convenience labels are not preserved when recreating from seed.
## Reference

14
docs/technical-specs.md
View file

@ -19,8 +19,10 @@ title: Monero Technical Specification | Monero Documentation
* v0 since block height 0
* v1 since block height 1546000 (forked on 2018-04-06)
* v2 since block height 1685555 (forked on 2018-10-18)
* v3 since block height 1788000 (scheduled to fork on 2018-03-09); "CryptonightR"
* Changes every ~6 months to discourage ASIC-s
* v3 since block height 1788000 (forked on 2019-03-09); "CryptonightR"
* would change every ~6 months to discourage ASIC-s development
* RandomX
* v0 since block height 1978433 (forked on 2019-11-30)
## Difficulty retarget
@ -35,20 +37,20 @@ title: Monero Technical Specification | Monero Documentation
## Block reward
* smoothly decreasing and subject to penalties for blocks greater then median size of the last 100 blocks (M100)
* ~3.8 XMR as of Sep 2018; for the current reward check the coinbase transaction of the [latest block](https://moneroblocks.info/)
* ~3.1 XMR as of Feb 2019; for the current reward check the coinbase transaction of the [latest block](https://xmrchain.net/)
## Block size
* dynamic
* maximum of two times the median size of the last 100 blocks (2 * M100)
* ~100KB as of Aug 2018; check [the latest block size](https://bitinfocharts.com/comparison/monero-size.html#3m)
* ~20KB as of Feb 2019; check [the latest block size](https://bitinfocharts.com/comparison/monero-size.html#3m)
## Emission curve
### Main emission
* first, the main emission is about to produce ~18.132 million coins by the end of May 2022
* as of Aug 2018 the emission is about 20 XMR per 10 minutes
* as of Feb 2019 the emission is about 15 XMR per 10 minutes
* see [charts and details](https://www.reddit.com/r/Monero/comments/512kwh/useful_for_learning_about_monero_coin_emission/)
### Tail emission
@ -85,5 +87,5 @@ title: Monero Technical Specification | Monero Documentation
## IP address privacy
* there is an ongoing effort to integrate I2P into Monero - the [Kovri](https://github.com/monero-project/kovri) project
* there is an ongoing effort to integrate Tor into Monero wallet for transaction sending
* assurance: none at the moment - please use TOR or I2P

60
docs/todo/bulletproofs.md Normal file
View file

@ -0,0 +1,60 @@
https://www.reddit.com/r/Bitcoin/comments/8dr4fw/benedikt_b%C3%BCnz_bulletproofs/dxpv4q6/
Pieter Wuille on Bulletproofs:
Bulletproofs is a general technology to implement zero-knowledge proofs.
Bitcoin does not use zero-knowledge proofs. There is no way you can just "plug in" Bulletproofs anywhere in Bitcoin.
Perhaps you are talking about confidential transactions (CT). This is a technique to permit a public ledger that makes the amounts hidden while still permitting everyone to verify the balances adds up. If that sounds like magic, that's because it is.
CT rely on zero-knowledge proofs. They could use Bulletproofs. They could also use other types of zero-knowledge proofs (there are several, zk-SNARKS is the well known, each with their own trade-offs). Certainly the invention of Bulletproofs made CT more accessible.
However... CT is still very different from how Bitcoin works right now. There is no obvious way to integrate them. My best hope would be using something like an extension block, where you can have coins on the "legacy" side or coins on the confidential side - with explicit operations to move them between the two.
However, that is far from simple, and AFAIK nobody is really working on it. Much as I love this technique and would be very excited to see it in Bitcoin, it's unrealistic to think that it will be usable anytime soon there.
Every system must lack at least one of unconditional soundness and unconditional blindness. It's perfectly possible to build a system that lacks both.
Bulletproofs are a general zero-knowledge proof technique. That means that they can be used to prove any statement over secret data without revealing that data.
You could prove you know 2 numbers that add up to 7.
You could prove that you know a string whose SHA256 hash is 16c28109a2719ebd4a123db11ff966f02d814354e3dc932449484f1c5a804af4, without revealing anything else about that string.
They could be used instead of zk-SNARKs in Zero-Knowledge Contingent Payments (swapping money for solutions to a problem). These can be done without any changes to Bitcoin.
You could (in theory, read on) use them to build a blockchain similar to ZCash (which heavily relies on zk-SNARKs for proving that their ledger makes sense), but without the trusted setup procedure or novel cryptography (Bulletproofs use very conservative security assumptions). Unfortunately, Bulletproof validation is much slower than zk-SNARK validation for complex problems, so it's not really comparable.
I expect that the most interesting applications are things we haven't considered yet. They suddenly bring zero-knowledge proofs into scope for a lot of problems and protocols where it wasn't really reasonable to go through the effort of using one of the existing proof systems.
++++
I'm pretty sure that Monero is not unconditionally sound. Even if it is, after switching to Bulletproofs they won't be (Bulletproofs cannot be made unconditionally sound).
Yes, with the old rangeproof construction there was an alternative that was unconditionally sound, but not unconditionally private.
This is not possible with Bulletproofs (and theoretically impossible with anything with similar compactness; unconditionally sound proofs cannot be small).
++++
Bulletproofs are a general zero-knowledge proof technique. That means that they can be used to prove any statement over secret data without revealing that data.
You could prove you know 2 numbers that add up to 7.
You could prove that you know a string whose SHA256 hash is 16c28109a2719ebd4a123db11ff966f02d814354e3dc932449484f1c5a804af4, without revealing anything else about that string.
They could be used instead of zk-SNARKs in Zero-Knowledge Contingent Payments (swapping money for solutions to a problem). These can be done without any changes to Bitcoin.
You could (in theory, read on) use them to build a blockchain similar to ZCash (which heavily relies on zk-SNARKs for proving that their ledger makes sense), but without the trusted setup procedure or novel cryptography (Bulletproofs use very conservative security assumptions). Unfortunately, Bulletproof validation is much slower than zk-SNARK validation for complex problems, so it's not really comparable.
I expect that the most interesting applications are things we haven't considered yet. They suddenly bring zero-knowledge proofs into scope for a lot of problems and protocols where it wasn't really reasonable to go through the effort of using one of the existing proof systems.
++++
Practical zero-knowledge proofs have existed for a few years now, and ZKCPs are indeed an application of them.
Bulletproofs are just a new type of zero-knowledge proof. Compared to zk-SNARKS, they're much more conservative in their security assumptions, and don't need a complicated setup procedure before proofs can be created. On the other hand, they're also larger and slower for complicated problsms. And they don't do anything that couldn't be done before - they're just more practical depending on your requirements.

32
docs/todo/confidential-transactions.md Normal file
View file

@ -0,0 +1,32 @@
https://www.reddit.com/r/Bitcoin/comments/8dr4fw/benedikt_b%C3%BCnz_bulletproofs/dxpv4q6/
Pieter Wuille on CT:
In a system that uses CT, if someone finds a break in the fundamental security of elliptic curve cryptography (ECC), he can print money. Worse, because the amounts are all private, he can do so undetectably. That's an existential threat for a currency which has controlled inflation as prime goal.
Such a break would be dangerous for Bitcoin (even without CT) regardless, as it relies on ECC for protecting against theft. However, Bitcoin can migrate to use a different signature scheme if necessary. It would be chaotic, but not necessarily pose an existential risk.
There are people who agree with this perspective. It's a mathematical fact that any privacy system that hides amounts and is built on top of ECC will at least have one of the properties below:
An ECC break will permit printing money undetectaby.
An ECC break will permit deanonymizing amounts in the historical chain.
In other words:
An ECC break means the currency can undetectably be inflated (going forward).
An ECC break means the ledger's history can retroactively be deanonymized (goin backward).
So we are faced with a choice between those two regardless if we want better privacy. Some people believe the second is worse than the first, and choosing the first actually allows for more efficient technology. This is a choice that Zcash, Monero, Grin, all make. CT with Bulletproofs would do the same.
However, regardless of your own opinion in this matter, Bitcoin's evolution is a large collaborative process, where such fundamental changes need buy-in from large parts of the ecosystem. My fear is that the question of giving up the ability to exactly audit the monetary supply is going to make it hard to make CT acceptable.
Furthermore, there are other challenges. CT makes transactions larger, slower to verify, and poses a very significant engineering challenge to incorporate into Bitcoin without breaking backward compatibility.
++++
> Also, is there any possible system that can have unconditional soundness and privacy at the same time (something other than ECC obviously)?
No, that's mathematically impossible.

18
docs/todo/confidential-transactions.txt Normal file
View file

@ -0,0 +1,18 @@
Pieter Wuille on CT:
In a system that uses CT, if someone finds a break in the fundamental security of elliptic curve cryptography (ECC), he can print money. Worse, because the amounts are all private, he can do so undetectably. That's an existential threat for a currency which has controlled inflation as prime goal.
Such a break would be dangerous for Bitcoin (even without CT) regardless, as it relies on ECC for protecting against theft. However, Bitcoin can migrate to use a different signature scheme if necessary. It would be chaotic, but not necessarily pose an existential risk.
There are people who agree with this perspective. It's a mathematical fact that any privacy system that hides amounts and is built on top of ECC will at least have one of the properties below:
An ECC break will permit printing money undetectaby.
An ECC break will permit deanonymizing amounts in the historical chain.
So we are faced with a choice between those two regardless if we want better privacy. Some people believe the second is worse than the first, and choosing the first actually allows for more efficient technology. This is a choice that Zcash, Monero, Grin, all make. CT with Bulletproofs would do the same.
However, regardless of your own opinion in this matter, Bitcoin's evolution is a large collaborative process, where such fundamental changes need buy-in from large parts of the ecosystem. My fear is that the question of giving up the ability to exactly audit the monetary supply is going to make it hard to make CT acceptable.
Furthermore, there are other challenges. CT makes transactions larger, slower to verify, and poses a very significant engineering challenge to incorporate into Bitcoin without breaking backward compatibility.

0
docs/cryptography/pedersen-commitment.md → docs/todo/pedersen-commitment.md
View file

6
docs/todo/risks-of-using-remote-node.md
View file

@ -1,6 +1,10 @@
# Risks of using remote node
https://monero.stackexchange.com/questions/1482/how-much-information-is-passed-from-the-daemon-to-simplewallet-when-scanning-for?rq=1%20https://monero.stackexchange.com/questions/1134/is-it-safe-to-share-a-daemon-with-a-roommate?noredirect=1&lq=1
https://monero.stackexchange.com/questions/38/what-privacy-or-security-trade-offs-are-associated-with-not-running-your-own-ful/
https://monero.stackexchange.com/questions/1482/how-much-information-is-passed-from-the-daemon-to-simplewallet-when-scanning-for?rq=1%20
https://monero.stackexchange.com/questions/1134/is-it-safe-to-share-a-daemon-with-a-roommate?noredirect=1&lq=1
## Reference

77
docs/todo/stealth-address.md Normal file
View file

@ -0,0 +1,77 @@
---
title: Stealth Address | Monero Documentation
---
# Stealth Address
## Hides recipient
Stealth address is a privacy technique to hide the recipient.
Even though blockchain is public, observer has no way to link the payment to the recipient.
Payments simply do **not** go to recipient address. Instead payments go to one-time "stealth" addresses.
## One-time, per payment
Stealth address is generated for each individual payment and must not be reused.
In Bitcoin, should stealth address be reused, the payments are linked.
Observer would learn these payments were to the same person.
This wouldn't be end of the world though, as most users would link the outputs anyway when spending from the wallet.
In Monero, stealth address reuse leads to lose of funds.
If sender re-uses stealth address, then recipient will only be able to claim one of the payments.
See [key image](/cryptography/asymmetric/key-image) to learn why this is the case.
Practically, to re-use stealth address, sender would have to manually craft a malicious transaction.
Recipient would simply not acknowledge receiving the payment, as if sender never paid.
## Wallet level feature
Stealth addresses are not part of the consensus layer. For transaction to be valid,
it does not matter how the key pairs were generated.
Stealth address is non-interactive protocol between sender and recipient.
## Elliptic curves magic properties
Before going further understand the following properties of elliptic curves.
Once you internalize these critical properties,
you will be able to easily come up with a stealth address scheme yourself.
### It is possible to establish a shared secret without sharing a secret
Two parties can come up with the same secret number w/o sending anything except their public keys.
Specifically, having 2 unrelated key pairs, you can exchange public keys, and then each party can independently calculate the same secret number, simply by multiplying own private key with other party's public key:
`s = aB = bA`, where:
* s - the secret (256-bit number)
* a - Alice private key
* A - Alice public key
* b - Bob private key
* B - Bob public key
### A new key pair can be derived by multiplying both keys
Having a key pair, you can derive a new key pair, simply by multiplying both keys by an integer.
Surprisingly, the new key pair will be valid, i.e. the private key will match the public key.
## Stealth address protocol
1. Sender Alice generates a new key pair. Note this is entirely local to the sender.
* a - private key
* A - public key
2. Sender Alice gets receiver's (Bob) public key from his address, `B`.
3. Sender calculates the secret:
`s = rB`
## Reference
http://www.scitepress.org/DigitalLibrary/Link.aspx?doi=10.5220/0006270005590566

12
mkdocs.yml
View file

@ -9,18 +9,17 @@ nav:
- Interacting:
- Download: 'interacting/download-monero-binaries.md'
- Verify: 'interacting/verify-monero-binaries.md'
- Overview: 'interacting/overview.md'
- Config: 'interacting/monero-config-file.md'
- What is what overview: 'interacting/overview.md'
- monerod: 'interacting/monerod-reference.md'
- monero-wallet-cli: 'interacting/monero-wallet-cli-reference.md'
- monero-wallet-gui: 'interacting/monero-wallet-gui-reference.md'
- monero-blockchain-export: 'interacting/monero-blockchain-export-reference.md'
- monero-blockchain-import: 'interacting/monero-blockchain-import-reference.md'
- monero-wallet-rpc: 'interacting/monero-wallet-rpc-reference.md'
- Config file: 'interacting/monero-config-file.md'
- Technical specs: 'technical-specs.md'
- Cryptography:
- Introduction: 'cryptography/introduction.md'
- PRNG: 'cryptography/prng.md'
- 'Keccak-256': 'cryptography/keccak-256.md'
- Asymmetric:
- Introduction: 'cryptography/asymmetric/introduction.md'
- Private keys: 'cryptography/asymmetric/private-key.md'
@ -28,14 +27,17 @@ nav:
- Edwards25519 curve: 'cryptography/asymmetric/edwards25519.md'
- Key image: 'cryptography/asymmetric/key-image.md'
- Base58: 'cryptography/base58.md'
- PRNG: 'cryptography/prng.md'
- 'Keccak-256': 'cryptography/keccak-256.md'
- Address:
- Main: 'public-address/main-address.md'
- Standard: 'public-address/standard-address.md'
- Subaddress: 'public-address/subaddress.md'
- Integrated: 'public-address/integrated-address.md'
- Proof of Work:
- What is PoW?: 'proof-of-work/what-is-pow.md'
- PoW in Cryptocurrencies: 'proof-of-work/pow-in-cryptocurrencies.md'
- CryptoNight: 'proof-of-work/cryptonight.md'
- RandomX: 'proof-of-work/random-x.md'
- Multisignature: 'multisignature.md'
- Infrastructure:
- Mainnet, stagenet, testnet: 'infrastructure/networks.md'